Upload 15 files

app.py

@@ -1,181 +1,33 @@
-import os
-import json
-import shutil
-from pathlib import Path
+"""
+HugPanel — Multi-zone workspace for HuggingFace Spaces.
+
+Open/Closed Principle: routers are auto-discovered from the routers/ package.
+Adding a new feature = adding a new file in routers/ — no changes here.
+"""
+
 from contextlib import asynccontextmanager
 
 import uvicorn
-from fastapi import FastAPI, Request, WebSocket, UploadFile, File, Form, HTTPException, Query
+from fastapi import FastAPI
 from fastapi.staticfiles import StaticFiles
-from fastapi.responses import HTMLResponse, FileResponse, JSONResponse
+from fastapi.responses import FileResponse
 
-import zones
-import proxy
-from terminal import terminal_ws, kill_terminal, active_terminals
+from routers import discover_routers
+from routers.terminal import active_terminals, kill_terminal
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     yield
-    # Cleanup terminals khi shutdown
     for zone_name in list(active_terminals.keys()):
         kill_terminal(zone_name)
 
 
 app = FastAPI(title="HugPanel", lifespan=lifespan)
 
-
-# ── Zone API ──────────────────────────────────────────────
-
-@app.get("/api/zones")
-def api_list_zones():
-    return zones.list_zones()
-
-
-@app.post("/api/zones")
-def api_create_zone(name: str = Form(...), description: str = Form("")):
-    try:
-        result = zones.create_zone(name, description)
-        return result
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.delete("/api/zones/{zone_name}")
-def api_delete_zone(zone_name: str):
-    try:
-        kill_terminal(zone_name)
-        zones.delete_zone(zone_name)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-# ── File Manager API ─────────────────────────────────────
-
-@app.get("/api/zones/{zone_name}/files")
-def api_list_files(zone_name: str, path: str = Query("")):
-    try:
-        return zones.list_files(zone_name, path)
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.get("/api/zones/{zone_name}/files/read")
-def api_read_file(zone_name: str, path: str = Query(...)):
-    try:
-        content = zones.read_file(zone_name, path)
-        return {"content": content, "path": path}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.get("/api/zones/{zone_name}/files/download")
-def api_download_file(zone_name: str, path: str = Query(...)):
-    try:
-        zone_path = zones.get_zone_path(zone_name)
-        target = zones._safe_path(zone_path, path)
-        if not target.is_file():
-            raise HTTPException(404, "File không tồn tại")
-        return FileResponse(target, filename=target.name)
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.post("/api/zones/{zone_name}/files/write")
-def api_write_file(zone_name: str, path: str = Form(...), content: str = Form(...)):
-    try:
-        zones.write_file(zone_name, path, content)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.post("/api/zones/{zone_name}/files/mkdir")
-def api_create_folder(zone_name: str, path: str = Form(...)):
-    try:
-        zones.create_folder(zone_name, path)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.post("/api/zones/{zone_name}/files/upload")
-async def api_upload_file(zone_name: str, path: str = Form(""), file: UploadFile = File(...)):
-    try:
-        zone_path = zones.get_zone_path(zone_name)
-        dest = zones._safe_path(zone_path, os.path.join(path, file.filename))
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        content = await file.read()
-        dest.write_bytes(content)
-        return {"ok": True, "path": str(dest.relative_to(zone_path))}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.delete("/api/zones/{zone_name}/files")
-def api_delete_file(zone_name: str, path: str = Query(...)):
-    try:
-        zones.delete_file(zone_name, path)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.post("/api/zones/{zone_name}/files/rename")
-def api_rename_file(zone_name: str, old_path: str = Form(...), new_name: str = Form(...)):
-    try:
-        zones.rename_item(zone_name, old_path, new_name)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-# ── Port Management API ───────────────────────────────────
-
-@app.get("/api/zones/{zone_name}/ports")
-def api_list_ports(zone_name: str):
-    try:
-        return proxy.list_ports(zone_name)
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.post("/api/zones/{zone_name}/ports")
-def api_add_port(zone_name: str, port: int = Form(...), label: str = Form("")):
-    try:
-        return proxy.add_port(zone_name, port, label)
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-@app.delete("/api/zones/{zone_name}/ports/{port}")
-def api_remove_port(zone_name: str, port: int):
-    try:
-        proxy.remove_port(zone_name, port)
-        return {"ok": True}
-    except ValueError as e:
-        raise HTTPException(400, str(e))
-
-
-# ── Reverse Proxy ────────────────────────────────────────
-
-@app.api_route("/port/{zone_name}/{port}/{subpath:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"])
-async def proxy_route(request: Request, zone_name: str, port: int, subpath: str = ""):
-    return await proxy.proxy_http(request, zone_name, port, subpath)
-
-
-@app.websocket("/port/{zone_name}/{port}/ws/{subpath:path}")
-async def proxy_ws_route(websocket: WebSocket, zone_name: str, port: int, subpath: str = ""):
-    await proxy.proxy_ws(websocket, zone_name, port, f"ws/{subpath}")
-
-
-# ── Terminal WebSocket ────────────────────────────────────
-
-@app.websocket("/ws/terminal/{zone_name}")
-async def ws_terminal(websocket: WebSocket, zone_name: str):
-    await terminal_ws(websocket, zone_name)
-
+# Auto-register all routers (Open/Closed — new router files are picked up automatically)
+for router in discover_routers():
+    app.include_router(router)
 
 # ── Static Files & SPA ──────────────────────────────────
 

config.py

@@ -0,0 +1,26 @@
+"""
+Centralized configuration for HugPanel.
+
+Single Responsibility: all constants and paths live here.
+Dependency Inversion: other modules depend on this abstraction, not on each other.
+"""
+
+import os
+import re
+from pathlib import Path
+
+# ── Paths ──────────────────────────────────────
+DATA_DIR = Path(os.environ.get("DATA_DIR", "/data/zones"))
+ZONES_META = DATA_DIR.parent / "zones_meta.json"
+
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+# ── Validation ─────────────────────────────────
+ZONE_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]{1,50}$")
+
+# ── Port Limits ────────────────────────────────
+MIN_PORT = 1024
+MAX_PORT = 65535
+
+# ── Terminal ───────────────────────────────────
+SCROLLBACK_SIZE = 128 * 1024  # 128 KB

routers/__init__.py

@@ -0,0 +1,21 @@
+"""
+Auto-discovery of API routers.
+
+Open/Closed Principle: adding a new feature = adding a new file in this package.
+No need to modify app.py — routers are discovered automatically.
+"""
+
+import importlib
+import pkgutil
+
+from fastapi import APIRouter
+
+
+def discover_routers() -> list[APIRouter]:
+    """Scan this package for modules exposing a `router` attribute."""
+    routers = []
+    for _, modname, _ in pkgutil.iter_modules(__path__):
+        mod = importlib.import_module(f".{modname}", __package__)
+        if hasattr(mod, "router"):
+            routers.append(mod.router)
+    return routers

routers/files.py

@@ -0,0 +1,130 @@
+"""
+File management API.
+
+Single Responsibility: only handles file CRUD operations within zones.
+Separated from zone management (zones.py) — each has its own reason to change.
+"""
+
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+from fastapi import APIRouter, Form, File, UploadFile, Query, HTTPException
+from fastapi.responses import FileResponse
+
+from storage import get_zone_path, safe_path
+
+router = APIRouter(prefix="/api/zones/{zone_name}/files", tags=["files"])
+
+
+@router.get("")
+def list_files(zone_name: str, path: str = Query("")):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        if not target.is_dir():
+            raise ValueError("Không phải thư mục")
+        return [
+            {
+                "name": item.name,
+                "is_dir": item.is_dir(),
+                "size": item.stat().st_size if item.is_file() else 0,
+                "modified": datetime.fromtimestamp(item.stat().st_mtime).isoformat(),
+            }
+            for item in sorted(target.iterdir())
+        ]
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.get("/read")
+def read_file(zone_name: str, path: str = Query(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        if not target.is_file():
+            raise ValueError("File không tồn tại")
+        return {"content": target.read_text(encoding="utf-8", errors="replace"), "path": path}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.get("/download")
+def download_file(zone_name: str, path: str = Query(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        if not target.is_file():
+            raise HTTPException(404, "File không tồn tại")
+        return FileResponse(target, filename=target.name)
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("/write")
+def write_file(zone_name: str, path: str = Form(...), content: str = Form(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("/mkdir")
+def create_folder(zone_name: str, path: str = Form(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        target.mkdir(parents=True, exist_ok=True)
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("/upload")
+async def upload_file(zone_name: str, path: str = Form(""), file: UploadFile = File(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        dest = safe_path(zone_path, os.path.join(path, file.filename))
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        content = await file.read()
+        dest.write_bytes(content)
+        return {"ok": True, "path": str(dest.relative_to(zone_path))}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.delete("")
+def delete_file(zone_name: str, path: str = Query(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        target = safe_path(zone_path, path)
+        if target == zone_path.resolve():
+            raise ValueError("Không thể xoá thư mục gốc zone")
+        if target.is_dir():
+            shutil.rmtree(target)
+        elif target.is_file():
+            target.unlink()
+        else:
+            raise ValueError("File/thư mục không tồn tại")
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("/rename")
+def rename_file(zone_name: str, old_path: str = Form(...), new_name: str = Form(...)):
+    try:
+        zone_path = get_zone_path(zone_name)
+        source = safe_path(zone_path, old_path)
+        if not source.exists():
+            raise ValueError("File/thư mục nguồn không tồn tại")
+        dest = safe_path(zone_path, str(Path(old_path).parent / new_name))
+        source.rename(dest)
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))

routers/ports.py

@@ -0,0 +1,70 @@
+"""
+Port management API.
+
+Single Responsibility: only handles port CRUD for zones.
+Reverse proxy logic is in proxy.py — separate reason to change.
+"""
+
+from fastapi import APIRouter, Form, HTTPException
+
+from config import MIN_PORT, MAX_PORT
+from storage import load_meta, save_meta
+
+router = APIRouter(prefix="/api/zones/{zone_name}/ports", tags=["ports"])
+
+
+def _validate_port(port: int):
+    if not (MIN_PORT <= port <= MAX_PORT):
+        raise ValueError(f"Port must be between {MIN_PORT} and {MAX_PORT}")
+
+
+def _validate_zone(meta: dict, zone_name: str):
+    if zone_name not in meta:
+        raise ValueError(f"Zone '{zone_name}' does not exist")
+
+
+@router.get("")
+def list_ports(zone_name: str):
+    try:
+        meta = load_meta()
+        _validate_zone(meta, zone_name)
+        return meta[zone_name].get("ports", [])
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.post("")
+def add_port(zone_name: str, port: int = Form(...), label: str = Form("")):
+    try:
+        _validate_port(port)
+        meta = load_meta()
+        _validate_zone(meta, zone_name)
+
+        ports = meta[zone_name].setdefault("ports", [])
+        for p in ports:
+            if p["port"] == port:
+                raise ValueError(f"Port {port} already mapped in zone '{zone_name}'")
+
+        entry = {"port": port, "label": label or f"Port {port}"}
+        ports.append(entry)
+        save_meta(meta)
+        return entry
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.delete("/{port}")
+def remove_port(zone_name: str, port: int):
+    try:
+        meta = load_meta()
+        _validate_zone(meta, zone_name)
+
+        ports = meta[zone_name].get("ports", [])
+        before = len(ports)
+        meta[zone_name]["ports"] = [p for p in ports if p["port"] != port]
+        if len(meta[zone_name]["ports"]) == before:
+            raise ValueError(f"Port {port} not found in zone '{zone_name}'")
+        save_meta(meta)
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))

routers/proxy.py

@@ -0,0 +1,150 @@
+"""
+Reverse proxy for virtual ports.
+
+Single Responsibility: only handles HTTP/WebSocket proxying.
+Port CRUD is in ports.py — separate concern.
+"""
+
+import asyncio
+import json
+
+import httpx
+from fastapi import APIRouter, Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import Response
+
+from config import MIN_PORT, MAX_PORT
+from storage import load_meta
+
+router = APIRouter(tags=["proxy"])
+
+# ── Shared HTTP client ────────────────────────
+
+_HOP_HEADERS = frozenset({
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailers", "transfer-encoding", "upgrade",
+})
+
+_client: httpx.AsyncClient | None = None
+
+
+def _get_client() -> httpx.AsyncClient:
+    global _client
+    if _client is None:
+        _client = httpx.AsyncClient(
+            timeout=httpx.Timeout(30.0, connect=5.0),
+            follow_redirects=False,
+            limits=httpx.Limits(max_connections=50),
+        )
+    return _client
+
+
+def _validate_proxy_access(zone_name: str, port: int):
+    """Validate port range and check it's registered for the zone."""
+    if not (MIN_PORT <= port <= MAX_PORT):
+        raise ValueError(f"Port must be between {MIN_PORT} and {MAX_PORT}")
+    meta = load_meta()
+    if zone_name not in meta:
+        raise ValueError(f"Zone '{zone_name}' does not exist")
+    ports = meta[zone_name].get("ports", [])
+    if not any(p["port"] == port for p in ports):
+        raise ValueError("Port not mapped")
+
+
+# ── HTTP Reverse Proxy ────────────────────────
+
+@router.api_route(
+    "/port/{zone_name}/{port}/{subpath:path}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],
+)
+async def proxy_http(request: Request, zone_name: str, port: int, subpath: str = ""):
+    try:
+        _validate_proxy_access(zone_name, port)
+    except ValueError:
+        return Response(content="Port not mapped", status_code=404)
+
+    target_url = f"http://127.0.0.1:{port}/{subpath}"
+    if request.url.query:
+        target_url += f"?{request.url.query}"
+
+    headers = {}
+    for key, value in request.headers.items():
+        if key.lower() not in _HOP_HEADERS and key.lower() != "host":
+            headers[key] = value
+    headers["host"] = f"127.0.0.1:{port}"
+    headers["x-forwarded-for"] = request.client.host if request.client else "127.0.0.1"
+    headers["x-forwarded-proto"] = request.url.scheme
+    headers["x-forwarded-prefix"] = f"/port/{zone_name}/{port}"
+
+    body = await request.body()
+    client = _get_client()
+
+    try:
+        resp = await client.request(method=request.method, url=target_url, headers=headers, content=body)
+    except httpx.ConnectError:
+        return Response(
+            content=f"Cannot connect to port {port}. Make sure your server is running.",
+            status_code=502,
+            media_type="text/plain",
+        )
+    except httpx.TimeoutException:
+        return Response(content=f"Timeout connecting to port {port}", status_code=504, media_type="text/plain")
+
+    resp_headers = {}
+    for key, value in resp.headers.items():
+        if key.lower() not in _HOP_HEADERS and key.lower() != "content-encoding":
+            resp_headers[key] = value
+
+    return Response(content=resp.content, status_code=resp.status_code, headers=resp_headers)
+
+
+# ── WebSocket Reverse Proxy ──────────────────
+
+@router.websocket("/port/{zone_name}/{port}/ws/{subpath:path}")
+async def proxy_ws(websocket: WebSocket, zone_name: str, port: int, subpath: str = ""):
+    try:
+        _validate_proxy_access(zone_name, port)
+    except ValueError:
+        await websocket.close(code=4004, reason="Port not mapped")
+        return
+
+    await websocket.accept()
+    target_url = f"ws://127.0.0.1:{port}/ws/{subpath}"
+
+    import websockets as ws_lib
+
+    try:
+        async with ws_lib.connect(target_url) as backend_ws:
+            async def client_to_backend():
+                try:
+                    while True:
+                        msg = await websocket.receive()
+                        if msg.get("type") == "websocket.disconnect":
+                            break
+                        if "text" in msg:
+                            await backend_ws.send(msg["text"])
+                        elif "bytes" in msg:
+                            await backend_ws.send(msg["bytes"])
+                except (WebSocketDisconnect, Exception):
+                    pass
+
+            async def backend_to_client():
+                try:
+                    async for message in backend_ws:
+                        if isinstance(message, str):
+                            await websocket.send_text(message)
+                        else:
+                            await websocket.send_bytes(message)
+                except (WebSocketDisconnect, Exception):
+                    pass
+
+            await asyncio.gather(client_to_backend(), backend_to_client())
+    except Exception:
+        try:
+            await websocket.send_text(json.dumps({"error": f"Cannot connect WebSocket to port {port}"}))
+        except Exception:
+            pass
+    finally:
+        try:
+            await websocket.close()
+        except Exception:
+            pass

routers/terminal.py

@@ -0,0 +1,187 @@
+"""
+Terminal WebSocket with persistent PTY sessions.
+
+Single Responsibility: only handles PTY lifecycle and WebSocket communication.
+Depends on storage.get_zone_path for path resolution (Dependency Inversion).
+"""
+
+import asyncio
+import collections
+import fcntl
+import json
+import os
+import pty
+import select
+import struct
+import termios
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from config import SCROLLBACK_SIZE
+from storage import get_zone_path
+
+router = APIRouter(tags=["terminal"])
+
+# Active terminals: {zone_name: {fd, pid, buffer, buffer_size, bg_task, ws}}
+active_terminals: dict[str, dict] = {}
+
+
+# ── PTY Management ────────────────────────────
+
+def _spawn_shell(zone_name: str) -> dict:
+    """Spawn a new PTY shell for a zone."""
+    zone_path = get_zone_path(zone_name)
+    master_fd, slave_fd = pty.openpty()
+
+    child_pid = os.fork()
+    if child_pid == 0:
+        os.setsid()
+        os.dup2(slave_fd, 0)
+        os.dup2(slave_fd, 1)
+        os.dup2(slave_fd, 2)
+        os.close(master_fd)
+        os.close(slave_fd)
+        os.chdir(str(zone_path))
+        env = os.environ.copy()
+        env["TERM"] = "xterm-256color"
+        env["HOME"] = str(zone_path)
+        env["PS1"] = f"[{zone_name}] \\w $ "
+        os.execvpe("/bin/bash", ["/bin/bash", "--norc"], env)
+    else:
+        os.close(slave_fd)
+        flag = fcntl.fcntl(master_fd, fcntl.F_GETFL)
+        fcntl.fcntl(master_fd, fcntl.F_SETFL, flag | os.O_NONBLOCK)
+        return {"fd": master_fd, "pid": child_pid, "buffer": collections.deque(), "buffer_size": 0}
+
+
+def _resize_terminal(zone_name: str, rows: int, cols: int):
+    if zone_name in active_terminals:
+        fd = active_terminals[zone_name]["fd"]
+        winsize = struct.pack("HHHH", rows, cols, 0, 0)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, winsize)
+
+
+def _append_buffer(info: dict, data: bytes):
+    info["buffer"].append(data)
+    info["buffer_size"] += len(data)
+    while info["buffer_size"] > SCROLLBACK_SIZE:
+        old = info["buffer"].popleft()
+        info["buffer_size"] -= len(old)
+
+
+def _get_buffer(info: dict) -> bytes:
+    return b"".join(info["buffer"])
+
+
+def _is_alive(zone_name: str) -> bool:
+    if zone_name not in active_terminals:
+        return False
+    try:
+        pid = active_terminals[zone_name]["pid"]
+        return os.waitpid(pid, os.WNOHANG) == (0, 0)
+    except ChildProcessError:
+        active_terminals.pop(zone_name, None)
+        return False
+
+
+async def _bg_reader(zone_name: str):
+    """Background: continuously read PTY output into the ring buffer."""
+    info = active_terminals.get(zone_name)
+    if not info:
+        return
+    fd = info["fd"]
+    while _is_alive(zone_name):
+        await asyncio.sleep(0.02)
+        try:
+            r, _, _ = select.select([fd], [], [], 0)
+            if r:
+                data = os.read(fd, 4096)
+                if data:
+                    _append_buffer(info, data)
+                    ws = info.get("ws")
+                    if ws:
+                        try:
+                            await ws.send_bytes(data)
+                        except Exception:
+                            info["ws"] = None
+        except (OSError, BlockingIOError):
+            pass
+        except Exception:
+            break
+
+
+def kill_terminal(zone_name: str):
+    """Kill terminal process for a zone."""
+    if zone_name in active_terminals:
+        info = active_terminals.pop(zone_name)
+        bg = info.get("bg_task")
+        if bg:
+            bg.cancel()
+        try:
+            os.kill(info["pid"], 9)
+            os.waitpid(info["pid"], os.WNOHANG)
+        except (ProcessLookupError, ChildProcessError):
+            pass
+        try:
+            os.close(info["fd"])
+        except OSError:
+            pass
+
+
+# ── WebSocket Handler ─────────────────────────
+
+@router.websocket("/ws/terminal/{zone_name}")
+async def terminal_ws(websocket: WebSocket, zone_name: str):
+    await websocket.accept()
+
+    try:
+        get_zone_path(zone_name)
+    except ValueError as e:
+        await websocket.send_json({"error": str(e)})
+        await websocket.close()
+        return
+
+    # Spawn or reuse terminal
+    if not _is_alive(zone_name):
+        kill_terminal(zone_name)
+        try:
+            info = _spawn_shell(zone_name)
+            info["ws"] = None
+            active_terminals[zone_name] = info
+            info["bg_task"] = asyncio.create_task(_bg_reader(zone_name))
+        except Exception as e:
+            await websocket.send_json({"error": f"Cannot create terminal: {e}"})
+            await websocket.close()
+            return
+
+    info = active_terminals[zone_name]
+    fd = info["fd"]
+
+    # Replay buffered scrollback
+    buf = _get_buffer(info)
+    if buf:
+        await websocket.send_bytes(buf)
+
+    # Register this WebSocket as the active receiver
+    info["ws"] = websocket
+
+    try:
+        while True:
+            msg = await websocket.receive()
+            if msg.get("type") == "websocket.disconnect":
+                break
+            if "text" in msg:
+                data = json.loads(msg["text"])
+                if data.get("type") == "resize":
+                    _resize_terminal(zone_name, data.get("rows", 24), data.get("cols", 80))
+                elif data.get("type") == "input":
+                    os.write(fd, data["data"].encode("utf-8"))
+            elif "bytes" in msg:
+                os.write(fd, msg["bytes"])
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass
+    finally:
+        if zone_name in active_terminals and active_terminals[zone_name].get("ws") is websocket:
+            active_terminals[zone_name]["ws"] = None

routers/zones.py

@@ -0,0 +1,71 @@
+"""
+Zone CRUD API.
+
+Single Responsibility: only handles zone create/list/delete.
+File management is in files.py, port management in ports.py.
+"""
+
+import shutil
+from datetime import datetime
+
+from fastapi import APIRouter, Form, HTTPException
+
+from config import DATA_DIR
+from storage import load_meta, save_meta, validate_zone_name
+from routers.terminal import kill_terminal
+
+router = APIRouter(prefix="/api/zones", tags=["zones"])
+
+
+@router.get("")
+def list_zones():
+    meta = load_meta()
+    return [
+        {
+            "name": name,
+            "created": info.get("created", ""),
+            "description": info.get("description", ""),
+            "exists": (DATA_DIR / name).is_dir(),
+        }
+        for name, info in meta.items()
+    ]
+
+
+@router.post("")
+def create_zone(name: str = Form(...), description: str = Form("")):
+    try:
+        validate_zone_name(name)
+        zone_path = DATA_DIR / name
+        if zone_path.exists():
+            raise ValueError(f"Zone '{name}' đã tồn tại")
+
+        zone_path.mkdir(parents=True)
+        (zone_path / "README.md").write_text(
+            f"# {name}\n\nZone được tạo lúc {datetime.now().isoformat()}\n"
+        )
+
+        meta = load_meta()
+        meta[name] = {"created": datetime.now().isoformat(), "description": description}
+        save_meta(meta)
+        return {"name": name, "path": str(zone_path)}
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+
+@router.delete("/{zone_name}")
+def delete_zone(zone_name: str):
+    try:
+        validate_zone_name(zone_name)
+        zone_path = DATA_DIR / zone_name
+        if not zone_path.exists():
+            raise ValueError(f"Zone '{zone_name}' không tồn tại")
+
+        kill_terminal(zone_name)
+        shutil.rmtree(zone_path)
+
+        meta = load_meta()
+        meta.pop(zone_name, None)
+        save_meta(meta)
+        return {"ok": True}
+    except ValueError as e:
+        raise HTTPException(400, str(e))

static/app.js

@@ -14,6 +14,8 @@ let termDataDisposable = null;
 let termResizeDisposable = null;
 let termCurrentZone = null; // tracks which zone the terminal is connected to
 let promptResolve = null;
+let isMobile = window.matchMedia("(max-width: 768px)").matches;
+let currentMobileTab = "files";
 
 // ── Init ──────────────────────────────────────
 document.addEventListener("DOMContentLoaded", () => {
@@ -21,6 +23,27 @@ document.addEventListener("DOMContentLoaded", () => {
     loadZones();
     initResizers();
     bindEvents();
+
+    // Track mobile state on resize
+    const mq = window.matchMedia("(max-width: 768px)");
+    mq.addEventListener("change", (e) => {
+        isMobile = e.matches;
+        if (!isMobile) {
+            // Exiting mobile: reset panel visibility
+            toggleSidebar(false);
+            document.getElementById("panel-files").classList.remove("m-active");
+            document.getElementById("pane-editor").classList.remove("m-active");
+            document.getElementById("pane-terminal").classList.remove("m-active");
+            document.getElementById("panel-right").classList.remove("m-active");
+        } else if (currentZone) {
+            switchMobileTab(currentMobileTab);
+        }
+    });
+
+    // Apply initial mobile tab if on mobile
+    if (isMobile && currentZone) {
+        switchMobileTab("files");
+    }
 });
 
 // ── API ───────────────────────────────────────
@@ -77,7 +100,7 @@ async function openZone(name) {
 
     // Reset editor
     const editorContainer = document.getElementById("editor-container");
-    editorContainer.innerHTML = `<div class="editor-empty"><i data-lucide="mouse-pointer-click"></i><p>Double-click a file to open</p></div>`;
+    editorContainer.innerHTML = `<div class="editor-empty"><i data-lucide="mouse-pointer-click"></i><p>${isMobile ? 'Tap a file to open' : 'Double-click a file to open'}</p></div>`;
     document.getElementById("editor-tabs").innerHTML = `<span class="tab-placeholder"><i data-lucide="code-2"></i> No file open</span>`;
     lucide.createIcons({ nodes: [editorContainer, document.getElementById("editor-tabs")] });
     cmEditor = null;
@@ -90,6 +113,12 @@ async function openZone(name) {
     await loadFiles();
     loadPorts();
 
+    // Mobile: close sidebar, show files tab
+    if (isMobile) {
+        toggleSidebar(false);
+        switchMobileTab("files");
+    }
+
     // Auto-connect terminal
     setTimeout(() => connectTerminal(), 200);
 }
@@ -139,7 +168,6 @@ async function loadFiles() {
 }
 
 function renderBreadcrumb() {
-    const bc = document.getElementById("breadcrumb");
     const parts = currentPath ? currentPath.split("/").filter(Boolean) : [];
     let html = `<span onclick="navigateTo('')">~</span>`;
     let path = "";
@@ -148,7 +176,10 @@ function renderBreadcrumb() {
         html += `<span class="sep">/</span>`;
         html += `<span onclick="navigateTo('${escapeAttr(path)}')">${escapeHtml(part)}</span>`;
     }
-    bc.innerHTML = html;
+    // Update both desktop and mobile breadcrumbs
+    document.getElementById("breadcrumb").innerHTML = html;
+    const mbc = document.getElementById("breadcrumb-mobile");
+    if (mbc) mbc.innerHTML = html;
 }
 
 function renderFiles(files) {
@@ -160,7 +191,7 @@ function renderFiles(files) {
     }
     let html = "";
     if (currentPath) {
-        html += `<div class="file-item" ondblclick="navigateUp()">
+        html += `<div class="file-item" ondblclick="navigateUp()" onclick="if(isMobile)navigateUp()">
             <span class="fi-icon fi-icon-back"><i data-lucide="corner-left-up"></i></span>
             <span class="fi-name">..</span>
         </div>`;
@@ -174,8 +205,10 @@ function renderFiles(files) {
         const iconClass = f.is_dir ? "fi-icon-folder" : fileIconClass(f.name);
         const iconName = f.is_dir ? "folder" : "file-text";
         const size = f.is_dir ? "" : formatSize(f.size);
+        const dblAction = f.is_dir ? `navigateTo('${escapeAttr(relPath)}')` : `editFile('${escapeAttr(relPath)}')`;
+        const tapAction = f.is_dir ? `navigateTo('${escapeAttr(relPath)}')` : `editFile('${escapeAttr(relPath)}')`;
 
-        html += `<div class="file-item" ondblclick="${f.is_dir ? `navigateTo('${escapeAttr(relPath)}')` : `editFile('${escapeAttr(relPath)}')`}">
+        html += `<div class="file-item" ondblclick="${dblAction}" onclick="if(isMobile){${tapAction}}">
             <span class="fi-icon ${iconClass}"><i data-lucide="${iconName}"></i></span>
             <span class="fi-name">${escapeHtml(f.name)}</span>
             <span class="fi-size">${size}</span>
@@ -246,7 +279,7 @@ async function editFile(relPath) {
             mode: getMode(filename),
             theme: "material-darker",
             lineNumbers: true,
-            lineWrapping: false,
+            lineWrapping: isMobile,
             indentWithTabs: false,
             indentUnit: 4,
             tabSize: 4,
@@ -267,8 +300,13 @@ async function editFile(relPath) {
         cmEditor.on("change", () => {
             const dot = document.getElementById("editor-modified");
             if (dot) dot.style.display = "block";
+            const mTab = document.querySelector('#mobile-tabs [data-tab="editor"]');
+            if (mTab) mTab.classList.add('has-dot');
         });
 
+        // Auto-switch to editor tab on mobile
+        if (isMobile) switchMobileTab('editor');
+
         // Focus editor
         setTimeout(() => cmEditor.refresh(), 50);
     } catch (e) {
@@ -286,6 +324,8 @@ async function saveFile() {
         await api(`/api/zones/${currentZone}/files/write`, { method: "POST", body: form });
         const dot = document.getElementById("editor-modified");
         if (dot) dot.style.display = "none";
+        const mTab = document.querySelector('#mobile-tabs [data-tab="editor"]');
+        if (mTab) mTab.classList.remove('has-dot');
         toast("File saved", "success");
     } catch (e) {
         toast("Save failed: " + e.message, "error");
@@ -382,7 +422,7 @@ function connectTerminal() {
     if (!term) {
         term = new window.Terminal({
             cursorBlink: true,
-            fontSize: 13,
+            fontSize: isMobile ? 11 : 13,
             fontFamily: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace",
             theme: {
                 background: "#09090b",
@@ -680,6 +720,57 @@ function fileIconClass(name) {
     return classes[ext] || "fi-icon-file";
 }
 
+// ── Mobile: Sidebar ─────────────────────────
+function toggleSidebar(open) {
+    const sidebar = document.getElementById("sidebar");
+    const backdrop = document.getElementById("sidebar-backdrop");
+    if (open) {
+        sidebar.classList.add("open");
+        backdrop.classList.add("open");
+    } else {
+        sidebar.classList.remove("open");
+        backdrop.classList.remove("open");
+    }
+}
+
+// ── Mobile: Tab Switching ───────────────────
+function switchMobileTab(tab) {
+    currentMobileTab = tab;
+
+    // Update tab bar highlighting
+    document.querySelectorAll(".mobile-tab").forEach(btn => {
+        btn.classList.toggle("active", btn.dataset.tab === tab);
+    });
+
+    const panelFiles = document.getElementById("panel-files");
+    const panelRight = document.getElementById("panel-right");
+    const paneEditor = document.getElementById("pane-editor");
+    const paneTerminal = document.getElementById("pane-terminal");
+
+    // Remove all active
+    panelFiles.classList.remove("m-active");
+    panelRight.classList.remove("m-active");
+    paneEditor.classList.remove("m-active");
+    paneTerminal.classList.remove("m-active");
+
+    if (tab === "files") {
+        panelFiles.classList.add("m-active");
+    } else if (tab === "editor") {
+        panelRight.classList.add("m-active");
+        paneEditor.classList.add("m-active");
+        setTimeout(() => { if (cmEditor) cmEditor.refresh(); }, 50);
+    } else if (tab === "terminal") {
+        panelRight.classList.add("m-active");
+        paneTerminal.classList.add("m-active");
+        setTimeout(() => {
+            if (fitAddon) fitAddon.fit();
+            if (!termSocket || termSocket.readyState !== WebSocket.OPEN) {
+                connectTerminal();
+            }
+        }, 50);
+    }
+}
+
 // ── Event Binding ────────────────────────────
 function bindEvents() {
     document.getElementById("btn-add-zone").addEventListener("click", () => showModal("modal-overlay"));

static/index.html

@@ -2,8 +2,12 @@
 <html lang="vi">
 <head>
     <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
     <title>HugPanel</title>
+    <meta name="mobile-web-app-capable" content="yes">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+    <meta name="theme-color" content="#09090b">
     <link rel="stylesheet" href="/static/style.css">
     <!-- Lucide Icons -->
     <script src="https://cdn.jsdelivr.net/npm/lucide@0.344.0/dist/umd/lucide.min.js"></script>
@@ -34,11 +38,15 @@
 </head>
 <body>
     <div id="app">
+        <!-- Sidebar Backdrop (mobile) -->
+        <div id="sidebar-backdrop" class="sidebar-backdrop" onclick="toggleSidebar(false)"></div>
+
         <!-- Sidebar -->
         <aside id="sidebar">
             <div class="sidebar-brand">
                 <div class="brand-icon"><i data-lucide="layout-dashboard"></i></div>
                 <span class="brand-text">HugPanel</span>
+                <button id="btn-close-sidebar" class="icon-btn-sm sidebar-close-btn" onclick="toggleSidebar(false)"><i data-lucide="x"></i></button>
             </div>
 
             <nav class="sidebar-nav">
@@ -81,12 +89,15 @@
             <div id="workspace" class="view">
                 <div class="topbar">
                     <div class="topbar-left">
+                        <button id="btn-hamburger" class="icon-btn-sm hamburger-btn" onclick="toggleSidebar(true)" title="Menu">
+                            <i data-lucide="menu"></i>
+                        </button>
                         <span class="zone-indicator" id="zone-badge">
                             <i data-lucide="box"></i>
                             <span id="zone-title"></span>
                         </span>
-                        <span class="topbar-sep"></span>
-                        <div class="breadcrumb" id="breadcrumb"></div>
+                        <span class="topbar-sep desktop-only"></span>
+                        <div class="breadcrumb desktop-only" id="breadcrumb"></div>
                     </div>
                     <div class="topbar-right">
                         <div class="port-controls" id="port-controls">
@@ -113,6 +124,7 @@
                                 <button class="icon-btn-sm" id="btn-upload" title="Upload"><i data-lucide="upload"></i></button>
                             </div>
                         </div>
+                        <div class="breadcrumb mobile-breadcrumb mobile-only" id="breadcrumb-mobile"></div>
                         <div id="file-list" class="file-tree"></div>
                         <input type="file" id="file-upload-input" style="display:none" multiple>
                     </div>
@@ -151,6 +163,22 @@
                         </div>
                     </div>
                 </div>
+
+                <!-- Mobile Bottom Tab Bar -->
+                <nav id="mobile-tabs" class="mobile-tabs">
+                    <button class="mobile-tab active" data-tab="files" onclick="switchMobileTab('files')">
+                        <i data-lucide="folder"></i>
+                        <span>Files</span>
+                    </button>
+                    <button class="mobile-tab" data-tab="editor" onclick="switchMobileTab('editor')">
+                        <i data-lucide="code-2"></i>
+                        <span>Editor</span>
+                    </button>
+                    <button class="mobile-tab" data-tab="terminal" onclick="switchMobileTab('terminal')">
+                        <i data-lucide="terminal-square"></i>
+                        <span>Terminal</span>
+                    </button>
+                </nav>
             </div>
         </main>
     </div>

static/style.css

@@ -834,5 +834,418 @@ body {
     font-size: 12px;
 }
 
+/* ── Mobile Infrastructure ─── */
+.sidebar-backdrop {
+    display: none;
+    position: fixed;
+    inset: 0;
+    background: rgba(0,0,0,0.5);
+    z-index: 49;
+    -webkit-tap-highlight-color: transparent;
+}
+
+.sidebar-close-btn { display: none; }
+.hamburger-btn { display: none; }
+.mobile-only { display: none !important; }
+.mobile-tabs { display: none; }
+
+/* ── Mobile Breakpoint ─────── */
+@media (max-width: 768px) {
+    :root {
+        --sidebar-w: 280px;
+        --topbar-h: 48px;
+        --panel-header-h: 44px;
+        --mobile-tab-h: 56px;
+    }
+
+    .desktop-only { display: none !important; }
+    .mobile-only { display: flex !important; }
+
+    /* Sidebar → slide-out drawer */
+    #sidebar {
+        position: fixed;
+        left: 0; top: 0; bottom: 0;
+        width: var(--sidebar-w);
+        transform: translateX(-100%);
+        transition: transform 250ms cubic-bezier(0.4, 0, 0.2, 1);
+        z-index: 50;
+        box-shadow: none;
+    }
+
+    #sidebar.open {
+        transform: translateX(0);
+        box-shadow: var(--shadow-lg);
+    }
+
+    .sidebar-backdrop.open {
+        display: block;
+    }
+
+    .sidebar-close-btn {
+        display: inline-flex;
+        margin-left: auto;
+    }
+
+    .hamburger-btn { display: inline-flex; }
+
+    /* Sidebar brand spacing */
+    .sidebar-brand { padding: 12px 14px 10px; }
+    .brand-text { font-size: 14px; }
+
+    /* Sidebar items bigger touch targets */
+    .zone-list li {
+        padding: 10px 12px;
+        font-size: 14px;
+        min-height: 44px;
+    }
+
+    .zone-list li .zone-icon { width: 20px; height: 20px; }
+
+    /* Main takes full width */
+    #main { width: 100%; }
+
+    /* Topbar mobile */
+    .topbar {
+        height: var(--topbar-h);
+        padding: 0 8px;
+        gap: 4px;
+    }
+
+    .topbar-left { gap: 6px; }
+
+    .zone-indicator {
+        font-size: 11px;
+        padding: 3px 8px;
+        max-width: 120px;
+        overflow: hidden;
+    }
+
+    .zone-indicator #zone-title {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    /* Port button compact */
+    .btn-toggle-ports span:not(.port-count) { display: none; }
+    #btn-toggle-ports { padding: 4px 8px; }
+
+    /* Mobile breadcrumb (inside files panel) */
+    .mobile-breadcrumb {
+        display: flex !important;
+        padding: 6px 12px;
+        border-bottom: 1px solid var(--border);
+        background: var(--bg-1);
+        overflow-x: auto;
+        -webkit-overflow-scrolling: touch;
+        flex-shrink: 0;
+    }
+
+    .mobile-breadcrumb span {
+        font-size: 13px;
+        padding: 4px 8px;
+        min-height: 32px;
+        display: flex;
+        align-items: center;
+    }
+
+    /* Workspace body → stacked full-screen */
+    .workspace-body {
+        flex-direction: column;
+        position: relative;
+    }
+
+    /* Hide resizers on mobile */
+    .resizer-v, .resizer-h { display: none; }
+
+    /* Each panel = absolute full screen, switch via class */
+    .panel-files {
+        width: 100% !important;
+        max-width: 100%;
+        min-width: 100%;
+        border-right: none;
+        position: absolute;
+        inset: 0;
+        z-index: 1;
+    }
+
+    .panel-right {
+        position: absolute;
+        inset: 0;
+        z-index: 1;
+    }
+
+    .pane-editor {
+        position: absolute;
+        inset: 0;
+        z-index: 1;
+    }
+
+    .pane-terminal {
+        position: absolute;
+        inset: 0;
+        height: 100% !important;
+        z-index: 1;
+    }
+
+    /* Only show active mobile panel */
+    .panel-files,
+    .pane-editor,
+    .pane-terminal {
+        display: none;
+    }
+
+    .panel-files.m-active { display: flex; }
+    .pane-editor.m-active { display: flex; }
+    .pane-terminal.m-active { display: flex; }
+
+    /* When editor or terminal is active, show panel-right as container */
+    .panel-right.m-active { display: flex; }
+
+    /* File items — bigger touch targets, always show actions */
+    .file-item {
+        min-height: 48px;
+        height: auto;
+        padding: 8px 12px;
+        gap: 10px;
+    }
+
+    .file-item .fi-icon { width: 20px; height: 20px; }
+    .file-item .fi-icon svg { width: 18px; height: 18px; }
+    .file-item .fi-name { font-size: 14px; }
+    .file-item .fi-size { font-size: 12px; }
+
+    /* Always show file actions on touch */
+    .file-item .fi-actions {
+        opacity: 1;
+    }
+
+    .fi-actions button {
+        width: 34px; height: 34px;
+    }
+
+    .fi-actions button svg { width: 16px; height: 16px; }
+
+    /* Panel headers bigger */
+    .panel-header, .pane-header {
+        height: var(--panel-header-h);
+        padding: 0 12px;
+    }
+
+    .panel-title { font-size: 12px; }
+    .panel-title svg { width: 15px; height: 15px; }
+
+    .icon-btn-sm {
+        width: 36px; height: 36px;
+    }
+
+    .icon-btn-sm svg { width: 18px; height: 18px; }
+
+    /* Editor mobile */
+    .editor-container .CodeMirror {
+        font-size: 12px;
+    }
+
+    .pane-tab {
+        padding: 6px 12px;
+        font-size: 13px;
+    }
+
+    /* Terminal mobile */
+    .terminal-container .xterm {
+        padding: 2px 0 2px 2px;
+    }
+
+    /* Bottom Tab Bar */
+    .mobile-tabs {
+        display: flex;
+        height: var(--mobile-tab-h);
+        background: var(--bg-1);
+        border-top: 1px solid var(--border);
+        flex-shrink: 0;
+        z-index: 10;
+    }
+
+    .mobile-tab {
+        flex: 1;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 2px;
+        background: none;
+        border: none;
+        color: var(--text-3);
+        cursor: pointer;
+        font-size: 10px;
+        font-weight: 500;
+        font-family: var(--font);
+        padding: 6px 0;
+        -webkit-tap-highlight-color: transparent;
+        transition: color var(--transition);
+        position: relative;
+    }
+
+    .mobile-tab svg { width: 20px; height: 20px; }
+
+    .mobile-tab.active {
+        color: var(--accent);
+    }
+
+    .mobile-tab.active::after {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: 25%; right: 25%;
+        height: 2px;
+        background: var(--accent);
+        border-radius: 0 0 2px 2px;
+    }
+
+    .mobile-tab.has-dot::before {
+        content: '';
+        position: absolute;
+        top: 6px;
+        right: calc(50% - 16px);
+        width: 6px; height: 6px;
+        background: var(--accent);
+        border-radius: 50%;
+    }
+
+    /* Modals full-width on mobile */
+    .modal {
+        width: 100%;
+        max-width: 100vw;
+        border-radius: var(--radius-lg) var(--radius-lg) 0 0;
+        margin: 0;
+        position: fixed;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        animation: slideUpModal 250ms ease;
+    }
+
+    .modal-sm { width: 100%; }
+
+    .modal form { padding: 16px; }
+
+    .form-group input[type="text"],
+    .form-group input[type="number"] {
+        padding: 12px 14px;
+        font-size: 16px; /* prevents iOS zoom */
+    }
+
+    .modal-overlay {
+        align-items: flex-end;
+    }
+
+    @keyframes slideUpModal {
+        from { transform: translateY(100%); }
+        to { transform: translateY(0); }
+    }
+
+    /* Port panel on mobile */
+    .port-panel {
+        position: fixed;
+        top: auto !important;
+        bottom: var(--mobile-tab-h);
+        left: 8px;
+        right: 8px;
+        width: auto;
+        border-radius: var(--radius-lg);
+    }
+
+    /* Toast at top on mobile (avoid keyboard) */
+    .toast-container {
+        top: 12px;
+        bottom: auto;
+        left: 12px;
+        right: 12px;
+    }
+
+    .toast { max-width: 100%; }
+
+    /* Welcome page mobile */
+    .welcome-hero { padding: 20px; }
+    .welcome-hero h1 { font-size: 22px; }
+    .welcome-hero p { font-size: 13px; max-width: 280px; }
+    .welcome-icon { width: 64px; height: 64px; }
+    .welcome-icon svg { width: 28px; height: 28px; }
+    .welcome-glow { width: 200px; height: 200px; }
+
+    /* Empty state mobile */
+    .empty-state { padding: 30px 16px; }
+    .editor-empty svg { width: 24px; height: 24px; }
+
+    /* Icon buttons bigger for touch */
+    .icon-btn {
+        width: 40px; height: 40px;
+    }
+
+    .icon-btn svg { width: 20px; height: 20px; }
+
+    /* Environment badges in sidebar */
+    .sidebar-bottom { padding: 10px 14px; }
+    .badge { font-size: 9px; padding: 3px 8px; }
+}
+
+/* ── Small phones (< 380px) ── */
+@media (max-width: 380px) {
+    :root {
+        --sidebar-w: 260px;
+    }
+
+    .zone-indicator { max-width: 90px; font-size: 10px; }
+    .mobile-tab span { font-size: 9px; }
+    .mobile-tab svg { width: 18px; height: 18px; }
+}
+
+/* ── Form input number (port) ── */
+.form-group input[type="number"] {
+    width: 100%;
+    padding: 8px 12px;
+    background: var(--bg-0);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text);
+    font-size: 13px;
+    outline: none;
+    transition: border-color var(--transition);
+    font-family: var(--font);
+}
+
+.form-group input[type="number"]:focus { border-color: var(--accent); box-shadow: 0 0 0 2px var(--accent-glow); }
+
+/* ── Touch optimizations ───── */
+@media (pointer: coarse) {
+    .file-item .fi-actions { opacity: 1; }
+
+    .file-item {
+        min-height: 48px;
+        -webkit-tap-highlight-color: transparent;
+    }
+
+    .zone-list li {
+        min-height: 44px;
+        -webkit-tap-highlight-color: transparent;
+    }
+
+    .icon-btn-sm {
+        min-width: 36px;
+        min-height: 36px;
+    }
+}
+
+/* Safe area for notch devices */
+@supports (padding: env(safe-area-inset-bottom)) {
+    .mobile-tabs {
+        padding-bottom: env(safe-area-inset-bottom);
+    }
+
+    .modal {
+        padding-bottom: env(safe-area-inset-bottom);
+    }
+}
+
 /* ── Utility ───────────────── */
 .hidden { display: none !important; }

storage.py

@@ -0,0 +1,48 @@
+"""
+Shared storage layer — zone metadata and path utilities.
+
+Single Responsibility: only handles metadata persistence and path resolution.
+Dependency Inversion: routers depend on these abstractions instead of importing each other.
+"""
+
+import json
+import os
+from pathlib import Path
+
+from config import DATA_DIR, ZONES_META, ZONE_NAME_PATTERN
+
+
+def load_meta() -> dict:
+    """Load zones metadata from JSON file."""
+    if ZONES_META.exists():
+        return json.loads(ZONES_META.read_text(encoding="utf-8"))
+    return {}
+
+
+def save_meta(meta: dict):
+    """Save zones metadata to JSON file."""
+    ZONES_META.write_text(json.dumps(meta, indent=2, default=str), encoding="utf-8")
+
+
+def validate_zone_name(name: str):
+    """Validate zone name format. Raises ValueError if invalid."""
+    if not ZONE_NAME_PATTERN.match(name):
+        raise ValueError("Tên zone chỉ chứa a-z, A-Z, 0-9, _, - (tối đa 50 ký tự)")
+
+
+def get_zone_path(name: str) -> Path:
+    """Get the filesystem path for a zone, validating it exists."""
+    validate_zone_name(name)
+    zone_path = DATA_DIR / name
+    if not zone_path.is_dir():
+        raise ValueError(f"Zone '{name}' không tồn tại")
+    return zone_path
+
+
+def safe_path(zone_path: Path, rel_path: str) -> Path:
+    """Resolve a relative path within a zone, preventing path traversal."""
+    target = (zone_path / rel_path).resolve()
+    zone_resolved = zone_path.resolve()
+    if target != zone_resolved and not str(target).startswith(str(zone_resolved) + os.sep):
+        raise ValueError("Truy cập ngoài zone không được phép")
+    return target