refactor: Rename sandbox to runtime and fix terminal hook (#130)

* fix(hooks): refactor useTerminal to avoid synchronous setState warning

* fix(hooks): remove unused onError variable

* chore(infra): rename sandbox directory to runtime

Author: Che-Zhu

.github/workflows/build-runtime.yml

@@ -6,15 +6,15 @@ on:
     branches: [main, master]
     types: [opened, synchronize, reopened]
     paths:
-      - "sandbox/**"
+      - "runtime/**"
       - ".github/workflows/build-runtime.yml"
-      - "!sandbox/*.md"
+      - "!runtime/*.md"
   push:
     branches: [main, master]
     paths:
-      - "sandbox/**"
+      - "runtime/**"
       - ".github/workflows/build-runtime.yml"
-      - "!sandbox/*.md"
+      - "!runtime/*.md"
 
 permissions:
   pull-requests: write
@@ -88,8 +88,8 @@ jobs:
         id: docker-build
         uses: docker/build-push-action@v6
         with:
-          context: ./sandbox
-          file: ./sandbox/Dockerfile
+          context: ./runtime
+          file: ./runtime/Dockerfile
           labels: ${{ steps.meta.outputs.labels }}
           platforms: linux/amd64
           tags: ${{ steps.meta.outputs.tags }}

hooks/use-terminal.ts

@@ -47,35 +47,22 @@ export function useTerminal(options: UseTerminalOptions): UseTerminalReturn {
     reconnectDelay = 3000,
     onConnected,
     onDisconnected,
-    onError,
   } = options
 
   const [status, setStatus] = useState<'disconnected' | 'connecting' | 'connected' | 'error'>(
-    'disconnected'
+    ttydUrl ? 'connecting' : 'disconnected'
   )
-  const [wsUrl, setWsUrl] = useState<string | null>(null)
+  const [wsUrl, setWsUrl] = useState<string | null>(ttydUrl ?? null)
+  const [prevTtydUrl, setPrevTtydUrl] = useState(ttydUrl)
+
+  if (ttydUrl !== prevTtydUrl) {
+    setPrevTtydUrl(ttydUrl)
+    setWsUrl(ttydUrl ?? null)
+    setStatus(ttydUrl ? 'connecting' : 'disconnected')
+  }
   const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null)
   const shouldReconnectRef = useRef(true)
 
-  // Parse ttyd URL and prepare WebSocket URL
-  useEffect(() => {
-    if (!ttydUrl) {
-      setWsUrl(null)
-      setStatus('disconnected')
-      return
-    }
-
-    try {
-      // ttydUrl already includes the token as query parameter
-      setWsUrl(ttydUrl)
-      setStatus('connecting')
-    } catch (error) {
-      console.error('[useTerminal] Invalid ttyd URL:', error)
-      setStatus('error')
-      onError?.(error as Error)
-    }
-  }, [ttydUrl, onError])
-
   // Handle connection status callbacks
   const handleConnected = useCallback(() => {
     setStatus('connected')

sandbox/.bashrc runtime/.bashrcsandbox/.bashrc renamed to runtime/.bashrc

@@ -149,7 +149,7 @@ Users can manually expose these ports if needed:
 The image is automatically built via GitHub Actions workflow when:
 - Pull requests are opened (validation only, no push)
 - Changes are pushed to `main` or `master` branch
-- Changes are detected in `sandbox/` directory
+- Changes are detected in `runtime/` directory
 - Manually triggered via workflow dispatch
 
 **Workflow File**: `.github/workflows/build-runtime.yml`
@@ -169,14 +169,14 @@ The image is automatically built via GitHub Actions workflow when:
 ### Local Build (Single Architecture)
 
 ```bash
-cd sandbox
+cd runtime
 docker build -t fullstack-web-runtime:local .
 ```
 
 ### Local Multi-Architecture Build
 
 ```bash
-cd sandbox
+cd runtime
 docker buildx build \
   --platform linux/amd64,linux/arm64 \
   -t fullstack-web-runtime:local \
@@ -210,7 +210,7 @@ Set these in repository settings (Settings → Secrets and variables → Actions
 ### Directory Structure
 
 ```
-sandbox/
+runtime/
 ├── Dockerfile           # Multi-stage Docker build
 ├── entrypoint.sh        # Container startup script
 ├── .bashrc              # Shell configuration with custom prompt
@@ -228,7 +228,7 @@ sandbox/
 
 ```bash
 # Build locally
-cd sandbox
+cd runtime
 docker build -t test-runtime .
 
 # Test web terminal
@@ -408,7 +408,7 @@ We welcome contributions! Please follow these steps:
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Make your changes to `sandbox/` directory
+3. Make your changes to `runtime/` directory
 4. Test locally with `docker build`
 5. Commit your changes (`git commit -m 'feat: Add new feature'`)
 6. Push to your fork (`git push origin feature/my-feature`)