@hienlh/ppm 0.8.76 → 0.8.78

package/docs/project-changelog.md

@@ -2,7 +2,42 @@
 
 All notable changes to PPM are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-**Current Version:** v0.8.60
+**Current Version:** v0.8.76
+
+---
+
+## [0.8.77] — 2026-04-01 (Planned)
+
+### Added
+- **Deterministic Tab URLs + Backend Workspace Sync**
+  - Tab IDs now deterministic ({type}:{identifier}) instead of random (tab-xxxx)
+  - URL format changed: `/project/{name}/{tabType}/{identifier}` (e.g., `/project/ppm/editor/src/index.ts`)
+  - New `workspace_state` database table (schema v10) persists tab layout per project
+  - GET/PUT `/api/project/:name/workspace` endpoints for server-side persistence
+  - Frontend syncs workspace layout to server with 1.5s debounce
+  - Deep linking from URL auto-creates tabs if missing
+  - Latest-wins conflict resolution: server timestamp > client localStorage
+  - Tab ID patterns standardized: `editor:path`, `chat:provider/sessionId`, `terminal:index`, etc.
+  - Migration from random IDs to deterministic IDs on first load
+
+### Technical Details
+- **Files Created:**
+  - `src/server/routes/workspace.ts` — Workspace GET/PUT endpoints
+  - `src/web/hooks/use-workspace-sync.ts` — Server sync orchestration with debounce
+- **Files Modified:**
+  - `src/services/db.service.ts` — Added workspace_state table (schema v10), helper functions
+  - `src/web/stores/panel-utils.ts` — Deterministic tab ID derivation logic
+  - `src/web/hooks/use-url-sync.ts` — URL parsing/building with new format
+  - `src/web/stores/panel-store.ts` — Load workspace from server on project switch
+  - `src/web/stores/tab-store.ts` — Tab interface updated with metadata
+- **Breaking Changes:** URLs changed; old `/project/{name}/tab/{id}` URLs redirected or ignored (fallback to project root)
+- **Migration:** Client-side: old random tab IDs migrated to deterministic format on first load
+
+### Benefits
+- **Shareable deep links** — URLs point to specific files/chats (e.g., `/project/ppm/editor/src/index.ts`)
+- **Cross-device persistence** — Workspace layout saved on server, restored on any device
+- **URL-driven navigation** — Paste URL to recreate workspace state
+- **Conflict-free sync** — Latest timestamp wins; no manual merge dialogs
 
 ---
 

package/docs/system-architecture.md

@@ -140,10 +140,24 @@ POST   /api/db/connections/:id/query              → Execute query (readonly ch
 PATCH  /api/db/connections/:id/cell               → Update cell value (single)
 GET    /api/upgrade/status                        → Get current + available versions, install method
 POST   /api/upgrade/apply                         → Install new version, trigger supervisor self-replace
+GET    /api/project/:name/workspace               → Get saved workspace layout + metadata
+PUT    /api/project/:name/workspace               → Save workspace layout (layout JSON)
 WS     /ws/project/:name/chat/:sessionId          → Chat streaming
 WS     /ws/project/:name/terminal/:id             → Terminal I/O
 ```
 
+**URL Format (Deterministic Tabs, v0.8.77+):**
+```
+/project/{name}                          → Project root (project switcher)
+/project/{name}/editor/{filePath}        → Open editor tab (e.g., src/index.ts)
+/project/{name}/chat/{provider}/{sessionId} → Open chat tab
+/project/{name}/terminal/{index}         → Open terminal tab
+/project/{name}/database/{connId}/{table} → Open database browser
+/project/{name}/git-graph                → Git history graph (singleton)
+/project/{name}/settings                 → Settings panel (singleton)
+```
+Tab IDs are deterministic: `{type}:{identifier}` (e.g., `editor:src/index.ts`, `chat:claude/abc123`). Deep links auto-create missing tabs.
+
 ---
 
 ### Service Layer (Business Logic)
@@ -161,7 +175,7 @@ WS     /ws/project/:name/terminal/:id             → Terminal I/O
 |---------|---------|-------------|
 | **ChatService** | Session management, message streaming | createSession, streamMessage, getHistory |
 | **ConfigService** | Config loading (YAML→SQLite migration) | load, save, getToken |
-| **DbService** | SQLite persistence (9 tables, WAL, connections/accounts CRUD) | getDb, openTestDb, getConnections, insertConnection, deleteConnection, getTableCache |
+| **DbService** | SQLite persistence (10 tables, WAL, connections/accounts/workspace CRUD) | getDb, openTestDb, getWorkspace, setWorkspace, getConnections, insertConnection, deleteConnection, getTableCache |
 | **TableCacheService** | Cache table metadata, search tables | syncTables, searchTables, invalidateCache |
 | **GitService** | Git command execution | status, diff, commit, stage, branch |
 | **FileService** | File operations with validation | read, write, tree, delete, mkdir |
@@ -260,11 +274,11 @@ PPM supports multiple AI providers through a generic `AIProvider` interface and
 - Enforce security (no parent directory access)
 
 **Key Patterns:**
-- SQLite: WAL mode, foreign keys, lazy init, schema v1 with 6 tables
+- SQLite: WAL mode, foreign keys, lazy init, schema v10 (10 tables: config, connections, accounts, usage_history, session_logs, push_subscriptions, session_map, table_metadata, session_logs, workspace_state)
 - Path validation: `projectPath/relativePath` only, reject `..`
 - Caching: Directory trees cached with TTL
 - Error handling: Descriptive messages (file not found, permission denied)
-- Migration: Automatic YAML→SQLite migration on first run with new db.service
+- Migration: Automatic YAML→SQLite migration on first run with new db.service; schema auto-upgrade on version bump
 
 ---
 
@@ -284,6 +298,24 @@ PPM supports multiple AI providers through a generic `AIProvider` interface and
 const messages = chatStore((s) => s.messages); // Subscribe to messages only
 ```
 
+#### Workspace Sync (v0.8.77+)
+
+**Deterministic Tab IDs & URL Routing:**
+- Tab IDs derived from type + metadata: `deriveTabId(type, metadata) → {type}:{identifier}`
+- Examples: `editor:src/index.ts`, `chat:claude/abc123`, `terminal:1`, `git-graph`
+- URLs rebuilt from active tab: `/project/{name}/{type}/{identifier}`
+- Deep linking: URL → `parseUrlState()` → auto-create tabs if missing
+
+**Workspace Persistence:**
+1. **Client**: PanelStore layout (grid, panels, tabs) cached in localStorage per project
+2. **Server**: Workspace JSON persisted in `workspace_state` SQLite table
+3. **Sync Flow:**
+   - User loads project → fetch workspace from server (GET `/api/project/:name/workspace`)
+   - Latest-wins: server `updated_at` vs client localStorage timestamp
+   - Panel layout changes debounced (1.5s) → POST to server
+   - On reconnect: server layout restored, client edits queued
+4. **Cross-Device:** Any device can load workspace, browser restores exact grid + active tabs
+
 ---
 
 ## Communication Protocols

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.76",
+  "version": "0.8.78",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/server/index.ts

@@ -360,12 +360,16 @@ if (process.argv.includes("__serve__")) {
 
   // Sync externally-started tunnel URL + PID into tunnelService
   // so GET /api/tunnel reflects the correct state and Share button doesn't start a duplicate.
+  // Also write server version to status.json so supervisor heartbeat reports the actual running version.
   try {
     const { resolve: r } = await import("node:path");
     const { homedir: h } = await import("node:os");
-    const { readFileSync: rf } = await import("node:fs");
+    const { readFileSync: rf, writeFileSync: wf } = await import("node:fs");
     const statusFile = r(h(), ".ppm", "status.json");
     const status = JSON.parse(rf(statusFile, "utf-8"));
+    // Write running server version — source of truth for heartbeat
+    status.serverVersion = VERSION;
+    wf(statusFile, JSON.stringify(status));
     if (status.shareUrl) {
       const { tunnelService } = await import("../services/tunnel.service.ts");
       tunnelService.setExternalUrl(status.shareUrl);

package/src/server/routes/project-scoped.ts

@@ -4,6 +4,7 @@ import { chatRoutes } from "./chat.ts";
 import { gitRoutes } from "./git.ts";
 import { fileRoutes } from "./files.ts";
 import { sqliteRoutes } from "./sqlite.ts";
+import { workspaceRoutes } from "./workspace.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
 
@@ -27,3 +28,4 @@ projectScopedRouter.route("/chat", chatRoutes);
 projectScopedRouter.route("/git", gitRoutes);
 projectScopedRouter.route("/files", fileRoutes);
 projectScopedRouter.route("/sqlite", sqliteRoutes);
+projectScopedRouter.route("/workspace", workspaceRoutes);

package/src/server/routes/workspace.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import { getWorkspace, setWorkspace } from "../../services/db.service.ts";
+import { ok, err } from "../../types/api.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const workspaceRoutes = new Hono<Env>();
+
+/** GET /workspace — load saved workspace layout */
+workspaceRoutes.get("/", (c) => {
+  try {
+    const projectName = c.get("projectName");
+    const row = getWorkspace(projectName);
+    if (!row) return c.json(ok(null));
+    return c.json(ok({
+      layout: JSON.parse(row.layout_json),
+      updatedAt: row.updated_at,
+    }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** PUT /workspace — save workspace layout */
+workspaceRoutes.put("/", async (c) => {
+  try {
+    const projectName = c.get("projectName");
+    const body = await c.req.json<{ layout: unknown }>();
+    if (!body.layout) return c.json(err("Missing layout"), 400);
+    const updatedAt = setWorkspace(projectName, JSON.stringify(body.layout));
+    return c.json(ok({ updatedAt }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/services/db.service.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { mkdirSync, existsSync } from "node:fs";
 
 const PPM_DIR = process.env.PPM_HOME || resolve(homedir(), ".ppm");
-const CURRENT_SCHEMA_VERSION = 9;
+const CURRENT_SCHEMA_VERSION = 10;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -251,6 +251,42 @@ function runMigrations(database: Database): void {
       PRAGMA user_version = 9;
     `);
   }
+
+  if (current < 10) {
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS workspace_state (
+        project_name TEXT PRIMARY KEY,
+        layout_json  TEXT NOT NULL,
+        updated_at   TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      PRAGMA user_version = 10;
+    `);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Workspace helpers
+// ---------------------------------------------------------------------------
+
+export interface WorkspaceRow {
+  project_name: string;
+  layout_json: string;
+  updated_at: string;
+}
+
+export function getWorkspace(projectName: string): WorkspaceRow | null {
+  return getDb().query(
+    "SELECT project_name, layout_json, updated_at FROM workspace_state WHERE project_name = ?",
+  ).get(projectName) as WorkspaceRow | null;
+}
+
+export function setWorkspace(projectName: string, layoutJson: string): string {
+  const now = new Date().toISOString();
+  getDb().query(
+    "INSERT INTO workspace_state (project_name, layout_json, updated_at) VALUES (?, ?, ?) ON CONFLICT(project_name) DO UPDATE SET layout_json = excluded.layout_json, updated_at = excluded.updated_at",
+  ).run(projectName, layoutJson, now);
+  return now;
 }
 
 // ---------------------------------------------------------------------------

package/src/services/supervisor.ts

@@ -451,16 +451,20 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
       cloudUrl: device.cloud_url,
       deviceId: device.device_id,
       secretKey: device.secret_key,
-      heartbeatFn: () => ({
-        type: "heartbeat" as const,
-        tunnelUrl,
-        state: supervisorState,
-        appVersion: VERSION,
-        availableVersion: (readStatus().availableVersion as string) || null,
-        serverPid: serverChild?.pid ?? null,
-        uptime: Math.floor((Date.now() - startTime) / 1000),
-        timestamp: new Date().toISOString(),
-      }),
+      heartbeatFn: () => {
+        const status = readStatus();
+        return {
+          type: "heartbeat" as const,
+          tunnelUrl,
+          state: supervisorState,
+          // Use server-reported version (source of truth) with supervisor fallback
+          appVersion: (status.serverVersion as string) || VERSION,
+          availableVersion: (status.availableVersion as string) || null,
+          serverPid: serverChild?.pid ?? null,
+          uptime: Math.floor((Date.now() - startTime) / 1000),
+          timestamp: new Date().toISOString(),
+        };
+      },
     });
 
     // Handle commands from Cloud

package/src/web/app.tsx

@@ -10,12 +10,18 @@ import { ProjectBottomSheet } from "@/components/layout/project-bottom-sheet";
 import { LoginScreen } from "@/components/auth/login-screen";
 import { useProjectStore, resolveOrder } from "@/stores/project-store";
 import { useTabStore } from "@/stores/tab-store";
+import { usePanelStore } from "@/stores/panel-store";
+import {
+  fetchWorkspaceFromServer,
+  resolveWorkspaceConflict,
+  savePanelLayout,
+} from "@/stores/panel-utils";
 import {
   useSettingsStore,
   applyThemeClass,
 } from "@/stores/settings-store";
 import { getAuthToken } from "@/lib/api-client";
-import { useUrlSync, parseUrlState } from "@/hooks/use-url-sync";
+import { useUrlSync, parseUrlState, autoOpenFromUrl } from "@/hooks/use-url-sync";
 import { useGlobalKeybindings } from "@/hooks/use-global-keybindings";
 import { useNotificationBadge } from "@/hooks/use-notification-badge";
 import { useServerReload } from "@/hooks/use-server-reload";
@@ -127,56 +133,52 @@ export function App() {
     });
   }, [authState]);
 
-  // Fetch projects after auth, then restore from URL if applicable
+  // Fetch projects after auth, then restore workspace + URL
   useEffect(() => {
     if (authState !== "authenticated") return;
 
-    fetchProjects().then(() => {
-      const { projectName: urlProject, tabId: urlTab, openChat } = initialUrlRef.current;
+    fetchProjects().then(async () => {
+      const urlState = initialUrlRef.current;
       const { projects, customOrder } = useProjectStore.getState();
       if (projects.length === 0) return;
 
       // URL project takes priority, then fall back to first sorted project
-      let target = urlProject ? projects.find((p) => p.name === urlProject) : undefined;
+      let target = urlState.projectName
+        ? projects.find((p) => p.name === urlState.projectName)
+        : undefined;
       if (!target) {
         target = resolveOrder(projects, customOrder)[0];
       }
-      if (target) {
-        useProjectStore.getState().setActiveProject(target);
-        if (urlProject && urlTab) {
-          queueMicrotask(() => {
-            const { tabs } = useTabStore.getState();
-            if (tabs.some((t) => t.id === urlTab)) {
-              useTabStore.getState().setActiveTab(urlTab);
-            }
-          });
+      if (!target) return;
+
+      useProjectStore.getState().setActiveProject(target);
+
+      // Fetch server workspace + compare with localStorage (latest-wins)
+      const serverLayout = await fetchWorkspaceFromServer(target.name);
+      if (serverLayout) {
+        const localRaw = localStorage.getItem(`ppm-panels-${target.name}`);
+        const localLayout = localRaw ? JSON.parse(localRaw) : null;
+        const resolved = resolveWorkspaceConflict(localLayout, serverLayout);
+        if (resolved && resolved === serverLayout) {
+          // Server wins — overwrite localStorage and reload panels
+          savePanelLayout(target.name, resolved);
+          usePanelStore.getState().reloadProject(target.name);
         }
       }
 
-      // Deep link: ?openChat=sessionId — open/focus the chat tab
-      if (openChat) {
-        queueMicrotask(() => {
-          const { tabs, setActiveTab, openTab } = useTabStore.getState();
-          const existing = tabs.find(
-            (t) => t.type === "chat" && t.metadata?.sessionId === openChat,
-          );
-          if (existing) {
-            setActiveTab(existing.id);
-          } else {
-            openTab({
-              type: "chat",
-              title: "Chat",
-              projectId: target?.name ?? null,
-              closable: true,
-              metadata: { sessionId: openChat },
-            });
-          }
-          // Clean up query param
+      // Auto-open target tab from URL (type-based)
+      queueMicrotask(() => {
+        if (urlState.tabType) {
+          autoOpenFromUrl(urlState.tabType, urlState.tabIdentifier, target!.name);
+        }
+        // Legacy: ?openChat= query param
+        if (urlState.openChat) {
+          autoOpenFromUrl("chat", urlState.openChat, target!.name);
           const url = new URL(window.location.href);
           url.searchParams.delete("openChat");
           window.history.replaceState(null, "", url.pathname);
-        });
-      }
+        }
+      });
     });
   }, [authState, fetchProjects]);
 

package/src/web/hooks/use-url-sync.ts

@@ -1,37 +1,181 @@
 import { useEffect, useRef } from "react";
-import { useTabStore } from "@/stores/tab-store";
+import { useTabStore, type TabType } from "@/stores/tab-store";
+
+// ---------------------------------------------------------------------------
+// URL state types
+// ---------------------------------------------------------------------------
+
+export interface UrlState {
+  projectName: string | null;
+  tabType: TabType | null;
+  tabIdentifier: string | null;
+  openChat: string | null;
+}
+
+const VALID_TAB_TYPES: TabType[] = [
+  "terminal", "chat", "editor", "database", "sqlite",
+  "postgres", "git-graph", "git-diff", "settings", "browser",
+];
+
+// ---------------------------------------------------------------------------
+// Parse URL → state
+// ---------------------------------------------------------------------------
 
 /**
- * Parse the current URL to extract project name and tab ID.
- * Expected format: /project/:projectName/tab/:tabId
+ * Parse the current URL to extract project name and tab info.
+ * Format: /project/{name}/{tabType}/{...identifier}
  */
-export function parseUrlState(): { projectName: string | null; tabId: string | null; openChat: string | null } {
+export function parseUrlState(): UrlState {
   const path = window.location.pathname;
-  const match = path.match(/^\/project\/([^/]+)(?:\/tab\/([^/]+))?/);
   const params = new URLSearchParams(window.location.search);
   const openChat = params.get("openChat");
-  if (!match) return { projectName: null, tabId: null, openChat };
-  return {
-    projectName: match[1] ? decodeURIComponent(match[1]) : null,
-    tabId: match[2] ? decodeURIComponent(match[2]) : null,
-    openChat,
-  };
+
+  const match = path.match(/^\/project\/([^/]+)(?:\/([^/]+)(\/.*)?)?/);
+  if (!match) return { projectName: null, tabType: null, tabIdentifier: null, openChat };
+
+  const projectName = decodeURIComponent(match[1]!);
+  const rawType = match[2] ?? null;
+  const rawIdentifier = match[3] ? match[3].slice(1) : null; // strip leading /
+
+  // Legacy fallback: /project/{name}/tab/{tabId}
+  if (rawType === "tab") {
+    return { projectName, tabType: null, tabIdentifier: null, openChat };
+  }
+
+  const tabType = VALID_TAB_TYPES.includes(rawType as TabType) ? (rawType as TabType) : null;
+
+  return { projectName, tabType, tabIdentifier: rawIdentifier, openChat };
 }
 
+// ---------------------------------------------------------------------------
+// Build URL from state
+// ---------------------------------------------------------------------------
+
 /**
- * Build URL path from project name and tab ID.
+ * Build URL path from project name and deterministic tab ID.
  */
-function buildUrl(projectName: string | null, tabId: string | null): string {
+export function buildUrl(projectName: string | null, tabId: string | null): string {
   if (!projectName || projectName === "__global__") return "/";
+
   let url = `/project/${encodeURIComponent(projectName)}`;
-  if (tabId) url += `/tab/${encodeURIComponent(tabId)}`;
+  if (!tabId) return url;
+
+  // Strip panel suffix (@panel-xxx) — not meaningful in URLs
+  const atIdx = tabId.indexOf("@");
+  const cleanId = atIdx !== -1 ? tabId.slice(0, atIdx) : tabId;
+
+  // tabId format: "type:identifier" or "type" (singletons)
+  const colonIdx = cleanId.indexOf(":");
+  if (colonIdx === -1) {
+    // Singleton: git-graph, settings
+    url += `/${cleanId}`;
+  } else {
+    const type = cleanId.slice(0, colonIdx);
+    const identifier = cleanId.slice(colonIdx + 1);
+    // Real slashes — no encoding for paths. Only encode special URL chars.
+    url += `/${type}/${identifier.replace(/[?#]/g, encodeURIComponent)}`;
+  }
   return url;
 }
 
+// ---------------------------------------------------------------------------
+// Tab ID reconstruction from URL
+// ---------------------------------------------------------------------------
+
+/** Reconstruct deterministic tab ID from parsed URL */
+export function tabIdFromUrl(tabType: TabType, tabIdentifier: string | null): string {
+  if (!tabIdentifier) return tabType; // singleton
+  return `${tabType}:${tabIdentifier}`;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-open tab from URL
+// ---------------------------------------------------------------------------
+
+function buildMetadataFromUrl(
+  type: TabType, identifier: string | null, projectName: string,
+): Record<string, unknown> | null {
+  switch (type) {
+    case "editor": return identifier ? { filePath: identifier, projectName } : null;
+    case "chat": {
+      if (!identifier) return null;
+      const slashIdx = identifier.indexOf("/");
+      if (slashIdx === -1) return { sessionId: identifier, projectName };
+      const providerId = identifier.slice(0, slashIdx);
+      const sessionId = identifier.slice(slashIdx + 1);
+      return sessionId ? { sessionId, providerId, projectName } : null;
+    }
+    case "terminal": return { terminalIndex: parseInt(identifier ?? "1", 10), projectName };
+    case "git-graph": return { projectName };
+    case "git-diff": return identifier ? { filePath: identifier, projectName } : null;
+    case "settings": return {};
+    case "database": {
+      const [connId, tableName] = (identifier ?? "").split(":");
+      return connId ? { connectionId: connId, tableName: tableName ?? "" } : null;
+    }
+    case "sqlite": return identifier ? { filePath: identifier, projectName } : null;
+    case "postgres": {
+      const [connId, tableName] = (identifier ?? "").split(":");
+      return connId ? { connectionId: connId, tableName: tableName ?? "" } : null;
+    }
+    case "browser": return identifier ? { url: identifier } : null;
+    default: return null;
+  }
+}
+
+function buildTitleFromUrl(type: TabType, identifier: string | null): string {
+  switch (type) {
+    case "editor": return identifier?.split("/").pop() ?? "File";
+    case "chat": return "Chat";
+    case "terminal": return `Terminal ${identifier ?? "1"}`;
+    case "git-graph": return "Git Graph";
+    case "git-diff": return identifier?.split("/").pop() ?? "Diff";
+    case "settings": return "Settings";
+    case "database": return identifier ?? "Database";
+    case "sqlite": return identifier?.split("/").pop() ?? "SQLite";
+    case "postgres": return identifier ?? "PostgreSQL";
+    case "browser": return "Browser";
+    default: return type;
+  }
+}
+
+/** Auto-open or focus a tab based on URL state */
+export function autoOpenFromUrl(
+  tabType: TabType,
+  tabIdentifier: string | null,
+  projectName: string,
+): void {
+  const { tabs, setActiveTab, openTab } = useTabStore.getState();
+  const expectedId = tabIdFromUrl(tabType, tabIdentifier);
+
+  // Check if tab already exists
+  const existing = tabs.find((t) => t.id === expectedId);
+  if (existing) {
+    setActiveTab(existing.id);
+    return;
+  }
+
+  // Auto-create tab from URL
+  const metadata = buildMetadataFromUrl(tabType, tabIdentifier, projectName);
+  if (!metadata) return;
+
+  openTab({
+    type: tabType,
+    title: buildTitleFromUrl(tabType, tabIdentifier),
+    projectId: projectName,
+    closable: true,
+    metadata,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Hook: sync URL ↔ tab state
+// ---------------------------------------------------------------------------
+
 /**
  * Sync tab/project state with browser URL.
- * - On tab/project change → pushState (enables back/forward navigation)
- * - On popstate (back/forward) → restore tab from URL
+ * - On tab/project change → pushState with type-based URL
+ * - On popstate (back/forward) → restore/create tab from URL
  */
 export function useUrlSync() {
   const activeTabId = useTabStore((s) => s.activeTabId);
@@ -40,7 +184,6 @@ export function useUrlSync() {
 
   // Push URL when active tab or project changes
   useEffect(() => {
-    // Skip push if this change was triggered by popstate (back/forward)
     if (isPopState.current) {
       isPopState.current = false;
       return;
@@ -55,11 +198,20 @@ export function useUrlSync() {
   // Listen for back/forward navigation
   useEffect(() => {
     function handlePopState() {
-      const { tabId } = parseUrlState();
+      const { tabType, tabIdentifier } = parseUrlState();
+      if (!tabType) return;
+
+      isPopState.current = true;
       const { tabs, setActiveTab } = useTabStore.getState();
-      if (tabId && tabs.some((t) => t.id === tabId)) {
-        isPopState.current = true;
-        setActiveTab(tabId);
+      const expectedId = tabIdFromUrl(tabType, tabIdentifier);
+      const existing = tabs.find((t) => t.id === expectedId);
+
+      if (existing) {
+        setActiveTab(existing.id);
+      } else {
+        // Auto-open tab on back/forward if it was closed
+        const project = useTabStore.getState().currentProject;
+        if (project) autoOpenFromUrl(tabType, tabIdentifier, project);
       }
     }