pi-studio 0.9.41 → 0.9.43

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.43] — 2026-08-11
+
+### Fixed
+- Preserve each Studio tab’s unsaved editor text and selected views when cmux reconstructs a hidden browser surface after switching workspaces, while keeping tab recovery state isolated and bounded in the running Studio server.
+
+## [0.9.42] — 2026-08-11
+
+### Changed
+- Open Studio as a focused cmux browser surface in the caller’s workspace when launched from cmux, with a bounded system-browser fallback when cmux is unavailable or declines the request.
+
 ## [0.9.41] — 2026-08-11
 
 ### Fixed

package/README.md

@@ -38,7 +38,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 - Includes an optional tmux-backed **REPL** view for Shell, Python, IPython, Julia, R, GHCi, and Clojure sessions, with Raw/Literate send modes, `Cmd/Ctrl+Shift+Enter` **Send to REPL**, session start/stop/interrupt controls, a compact refresh-persistent **Studio REPL Record** of user and Pi-sent code, a secondary raw tmux mirror, agent-facing `studio_repl_status` / `studio_repl_send` tools, and Markdown/PDF/HTML export
 - Includes a local persistent scratchpad for quick notes you want to keep out of the main editor until you're ready to copy or insert them, with a **Recent…** picker for recovering scratchpads saved under earlier file/draft identities
 - Includes a docked **Outline** rail for navigating document structure in the current editor text, with clickable entries that jump in the raw editor and reveal matching preview locations when available
-- Restores the current browser-tab editor workspace after refresh and provides an explicit **Reset editor** action when you want to discard the restored draft and return the tab to a fresh blank draft without changing responses or saved files
+- Restores each browser tab’s editor workspace after refresh or cmux hidden-surface reconstruction, and provides an explicit **Reset editor** action when you want to discard the restored draft and return the tab to a fresh blank draft without changing responses or saved files
 - Turns local preview links, including links inside sandboxed HTML previews, into Studio actions: PDFs open in the embedded viewer, images open in a zoomable focus viewer, PDF/image links can open in a new Studio preview tab, text/code/CSV/TSV document links can open in a new editor tab, DOCX/ODT links can be converted to editable Markdown, and right-click menus provide **Open here**, **Reveal in file manager**, and **Copy path** for local resources
 - Includes local comments anchored to selections/lines, shown in a docked **Comments** rail, with transient **Comment** / **Jump** actions from raw-editor selections plus editor-preview selections for Markdown, LaTeX, code/text/diff previews, and an opt-in comment mode for editor HTML previews; source-anchored comments can be toggled into inline `[an: ...]` annotations when you want comments reflected in the document text
 - Browses response history (`Prev/Next/Last`) and loads either:
@@ -63,7 +63,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 
 | Command | Description |
 |---|---|
-| `/studio` | Open with last assistant response (fallback: blank) |
+| `/studio` | Open in cmux when available, otherwise the system browser, with the last assistant response (fallback: blank) |
 | `/studio <path>` | Open with file preloaded |
 | `/studio --last` | Force last response |
 | `/studio --blank` | Force blank editor |
@@ -150,6 +150,7 @@ Studio only passes icon-pack arguments when a diagram actually references `lucid
 ## Notes
 
 - Local-only server (`127.0.0.1`) with tokenized Studio URLs.
+- When Pi runs inside cmux, Studio opens as a focused cmux browser surface in the caller’s workspace. If cmux is unavailable or declines the request, Studio falls back to the system browser.
 - For remote SSH sessions, keep Studio bound to localhost and use SSH local port forwarding; `/studio` and `/studio --status` print the full tokenized localhost URL. The SSH hint repeats the full URL so it is visible even if your terminal only shows the latest notification. Open that URL through the tunnel, preserving the `?token=...` parameter. If SSH is not auto-detected, use `/studio --no-browser`; for stable forwarding, use `/studio --port <port>` or combine them, e.g. `/studio --no-browser --port 3417`.
 - Full Studio is a singleton per Pi session: use `/studio` to open it, `/studio-replace` to explicitly replace it, and `/studio-editor-only` for extra editing/preview tabs that do not take over the full Studio session view.
 - Studio is designed as a complement to terminal pi, not a replacement.

package/client/studio-client.js

@@ -1,4 +1,4 @@
-    (() => {
+    (async () => {
       const statusLineEl = document.getElementById("statusLine");
       const statusEl = document.getElementById("status");
       const statusSpinnerEl = document.getElementById("statusSpinner");
@@ -209,9 +209,17 @@
       };
 
       const navigationHelpers = globalThis.PiStudioNavigationHelpers;
-      if (!navigationHelpers || typeof navigationHelpers.readPaneFocusTarget !== "function") {
+      if (
+        !navigationHelpers
+        || typeof navigationHelpers.readPaneFocusTarget !== "function"
+        || typeof navigationHelpers.ensureStudioTabStateId !== "function"
+        || typeof navigationHelpers.readStudioWorkspaceState !== "function"
+        || typeof navigationHelpers.persistStudioWorkspaceState !== "function"
+        || typeof navigationHelpers.clearStudioWorkspaceState !== "function"
+      ) {
         throw new Error("Studio navigation helpers failed to load.");
       }
+      const studioTabStateId = navigationHelpers.ensureStudioTabStateId(window);
       const initialQueryParams = new URLSearchParams(window.location.search || "");
       const initialPaneFocusTarget = navigationHelpers.readPaneFocusTarget(window.location);
       const skipInitialWorkspaceRestore = initialQueryParams.get("skipWorkspaceRestore") === "1";
@@ -2059,8 +2067,9 @@
       const PANE_SPLIT_MIN_PERCENT = 20;
       const PANE_SPLIT_MAX_PERCENT = 80;
       const PANE_SPLIT_SNAP_TO_CENTER_PERCENT = 1;
-      const STUDIO_WORKSPACE_STORAGE_KEY = "piStudio.workspaceState.v1";
       const STUDIO_WORKSPACE_MAX_TEXT_CHARS = 900_000;
+      const STUDIO_WORKSPACE_PERSIST_INTERVAL_MS = 300;
+      const STUDIO_WORKSPACE_RECOVERY_FETCH_TIMEOUT_MS = 1_500;
       const EDITOR_HIGHLIGHT_MAX_CHARS = 100_000;
       const EDITOR_HIGHLIGHT_STORAGE_KEY = "piStudio.editorHighlightEnabled";
       const EDITOR_LANGUAGE_STORAGE_KEY = "piStudio.editorLanguage";
@@ -2217,6 +2226,8 @@
       let workspacePersistenceReady = false;
       let workspacePersistTimer = null;
       let workspaceRestoredFromBrowser = false;
+      let workspaceServerPersistenceBlocked = false;
+      let lastWorkspacePersistenceSavedAt = 0;
       let suppressedEditorSelectionStart = null;
       let suppressedEditorSelectionEnd = null;
       const previewJumpHighlightState = new WeakMap();
@@ -3605,11 +3616,13 @@
       });
 
       document.addEventListener("visibilitychange", () => {
-        if (!document.hidden) {
-          windowHasFocus = typeof document.hasFocus === "function" ? document.hasFocus() : windowHasFocus;
-          if (windowHasFocus) {
-            clearTitleAttention();
-          }
+        if (document.hidden) {
+          flushWorkspacePersistence({ beacon: false });
+          return;
+        }
+        windowHasFocus = typeof document.hasFocus === "function" ? document.hasFocus() : windowHasFocus;
+        if (windowHasFocus) {
+          clearTitleAttention();
         }
       });
 
@@ -11377,34 +11390,46 @@
         return "source:" + normalized.source + ":" + normalized.label;
       }
 
-      function getWorkspacePersistenceStorage() {
+      function readPersistedWorkspaceState() {
         try {
-          return window.sessionStorage || null;
+          return navigationHelpers.readStudioWorkspaceState(window, studioTabStateId);
         } catch {
           return null;
         }
       }
 
-      function clearLegacyWorkspacePersistenceStorage() {
-        try {
-          if (window.localStorage) window.localStorage.removeItem(STUDIO_WORKSPACE_STORAGE_KEY);
-        } catch {}
-      }
-
-      function readPersistedWorkspaceState() {
+      async function readServerWorkspaceRecoveryState() {
+        if (skipInitialWorkspaceRestore) return { status: "skipped", state: null };
+        const controller = typeof AbortController === "function" ? new AbortController() : null;
+        const timer = controller
+          ? window.setTimeout(() => controller.abort(), STUDIO_WORKSPACE_RECOVERY_FETCH_TIMEOUT_MS)
+          : null;
         try {
-          const storage = getWorkspacePersistenceStorage();
-          const raw = storage ? storage.getItem(STUDIO_WORKSPACE_STORAGE_KEY) : null;
-          if (!raw) return null;
-          const parsed = JSON.parse(raw);
-          if (!parsed || typeof parsed !== "object" || parsed.version !== 1) return null;
-          if (typeof parsed.text !== "string") return null;
-          return parsed;
+          const payload = await fetchStudioJson("/tab-workspace-state", {
+            query: { tabStateId: studioTabStateId },
+            signal: controller ? controller.signal : undefined,
+          });
+          const state = payload && payload.state && typeof payload.state === "object" ? payload.state : null;
+          return { status: state ? "found" : "empty", state };
         } catch {
-          return null;
+          return { status: "unavailable", state: null };
+        } finally {
+          if (timer !== null) window.clearTimeout(timer);
         }
       }
 
+      function getWorkspaceStateSavedAt(state) {
+        return state && typeof state.savedAt === "number" && Number.isFinite(state.savedAt)
+          ? state.savedAt
+          : 0;
+      }
+
+      function chooseNewestRestorableWorkspaceState(states) {
+        return states
+          .filter((state) => shouldRestorePersistedWorkspaceState(state))
+          .sort((a, b) => getWorkspaceStateSavedAt(b) - getWorkspaceStateSavedAt(a))[0] || null;
+      }
+
       function shouldRestorePersistedWorkspaceState(state) {
         if (skipInitialWorkspaceRestore) return false;
         if (!state || typeof state.text !== "string") return false;
@@ -11417,9 +11442,10 @@
       }
 
       function buildWorkspacePersistencePayload() {
+        lastWorkspacePersistenceSavedAt = Math.max(Date.now(), lastWorkspacePersistenceSavedAt + 1);
         return {
           version: 1,
-          savedAt: Date.now(),
+          savedAt: lastWorkspacePersistenceSavedAt,
           sourceState: normalizeWorkspaceSourceState(sourceState),
           resourceDir: getCurrentResourceDirValue(),
           editorView,
@@ -11434,38 +11460,63 @@
         };
       }
 
-      function persistWorkspaceStateNow() {
+      function sendServerWorkspaceRecoveryState(payload, options) {
+        if ((options && options.skipServer) || (workspaceServerPersistenceBlocked && !(options && options.forceServer))) return;
+        const body = { tabStateId: studioTabStateId, state: payload };
+        if (ws && ws.readyState === WebSocket.OPEN) {
+          try {
+            ws.send(JSON.stringify({ type: "workspace_state_update", ...body }));
+            return;
+          } catch {
+            // Fall through to the authenticated HTTP path.
+          }
+        }
+        if (options && options.beacon && trySendStudioJsonBeacon("/tab-workspace-state", body)) return;
+        void fetchStudioJson("/tab-workspace-state", {
+          method: "POST",
+          body: JSON.stringify(body),
+          keepalive: Boolean(options && options.beacon),
+        }).catch(() => {
+          // Session storage remains the in-page fallback if server recovery fails.
+        });
+      }
+
+      function persistWorkspaceStateNow(options) {
         if (!workspacePersistenceReady) return;
         try {
-          const storage = getWorkspacePersistenceStorage();
-          if (!storage) return;
-          clearLegacyWorkspacePersistenceStorage();
           const payload = buildWorkspacePersistencePayload();
           if (payload.text.length > STUDIO_WORKSPACE_MAX_TEXT_CHARS) {
-            storage.removeItem(STUDIO_WORKSPACE_STORAGE_KEY);
+            navigationHelpers.clearStudioWorkspaceState(window, studioTabStateId);
+            sendServerWorkspaceRecoveryState({
+              ...payload,
+              sourceState: { source: "recovery-omitted", label: "oversized editor", path: null, draftId: null },
+              resourceDir: "",
+              rightView: "editor-preview",
+              text: "",
+            }, { ...(options || {}), forceServer: true });
             return;
           }
-          storage.setItem(STUDIO_WORKSPACE_STORAGE_KEY, JSON.stringify(payload));
+          navigationHelpers.persistStudioWorkspaceState(window, studioTabStateId, payload);
+          sendServerWorkspaceRecoveryState(payload, options);
         } catch {
-          // Ignore browser storage failures and quota limits.
+          // Ignore browser storage, serialization, and recovery-request failures.
         }
       }
 
       function scheduleWorkspacePersistence() {
-        if (!workspacePersistenceReady) return;
-        if (workspacePersistTimer !== null) window.clearTimeout(workspacePersistTimer);
+        if (!workspacePersistenceReady || workspacePersistTimer !== null) return;
         workspacePersistTimer = window.setTimeout(() => {
           workspacePersistTimer = null;
           persistWorkspaceStateNow();
-        }, 160);
+        }, STUDIO_WORKSPACE_PERSIST_INTERVAL_MS);
       }
 
-      function flushWorkspacePersistence() {
+      function flushWorkspacePersistence(options) {
         if (workspacePersistTimer !== null) {
           window.clearTimeout(workspacePersistTimer);
           workspacePersistTimer = null;
         }
-        persistWorkspaceStateNow();
+        persistWorkspaceStateNow(options || { beacon: true });
       }
 
       function clearPersistedWorkspaceState() {
@@ -11474,10 +11525,16 @@
           workspacePersistTimer = null;
         }
         try {
-          const storage = getWorkspacePersistenceStorage();
-          if (storage) storage.removeItem(STUDIO_WORKSPACE_STORAGE_KEY);
+          navigationHelpers.clearStudioWorkspaceState(window, studioTabStateId);
+          const marker = buildWorkspacePersistencePayload();
+          sendServerWorkspaceRecoveryState({
+            ...marker,
+            sourceState: { source: "recovery-cleared", label: "cleared editor", path: null, draftId: null },
+            resourceDir: "",
+            rightView: "editor-preview",
+            text: "",
+          }, { beacon: true, forceServer: true });
         } catch {}
-        clearLegacyWorkspacePersistenceStorage();
       }
 
       function applyPersistedWorkspaceState(state) {
@@ -12555,6 +12612,8 @@
           headers,
           body: init.body,
           cache: "no-store",
+          signal: init.signal,
+          keepalive: init.keepalive === true,
         });
         let payload = null;
         try {
@@ -21892,13 +21951,26 @@
       setAnnotationsEnabled(initialAnnotationsEnabled, { silent: true });
       setReplSendMode(replSendMode);
 
-      const persistedWorkspaceState = readPersistedWorkspaceState();
+      const sessionWorkspaceState = readPersistedWorkspaceState();
+      const serverWorkspaceRecovery = await readServerWorkspaceRecoveryState();
+      workspaceServerPersistenceBlocked = serverWorkspaceRecovery.status === "unavailable";
+      const serverWorkspaceState = serverWorkspaceRecovery.state;
+      lastWorkspacePersistenceSavedAt = Math.max(
+        lastWorkspacePersistenceSavedAt,
+        getWorkspaceStateSavedAt(sessionWorkspaceState),
+        getWorkspaceStateSavedAt(serverWorkspaceState),
+      );
+      const persistedWorkspaceState = chooseNewestRestorableWorkspaceState([
+        sessionWorkspaceState,
+        serverWorkspaceState,
+      ]);
       applyPersistedWorkspaceState(persistedWorkspaceState);
 
       setEditorView(editorView);
       setRightView(rightView);
       renderSourcePreview();
       workspacePersistenceReady = true;
+      persistWorkspaceStateNow({ skipServer: serverWorkspaceRecovery.status === "unavailable" });
       if (workspaceRestoredFromBrowser) {
         setStatus("Restored editor workspace from this browser tab. Use Reset editor to discard it.", "success");
       }

package/client/studio-navigation-helpers.js

@@ -2,6 +2,10 @@
   const PANE_FOCUS_PARAM = "paneFocus";
   const PANE_FOCUS_OFF = "off";
   const PANE_FOCUS_TARGETS = Object.freeze(["left", "right"]);
+  const STUDIO_TAB_STATE_PARAM = "studioTabState";
+  const STUDIO_TAB_STATE_ID_PATTERN = /^[a-zA-Z0-9_-]{20,128}$/;
+  const STUDIO_WORKSPACE_STORAGE_PREFIX = "piStudio.workspaceState.v2:";
+  const STUDIO_WORKSPACE_LEGACY_STORAGE_KEY = "piStudio.workspaceState.v1";
   const STUDIO_LAUNCH_PROTOCOL_VERSION = 1;
   const STUDIO_LAUNCH_CHANNEL_PREFIX = "pi-studio-launch-v1:";
   const STUDIO_PENDING_KINDS = Object.freeze(["document", "preview", "export"]);
@@ -48,6 +52,98 @@
     return true;
   }
 
+  function isValidStudioTabStateId(value) {
+    return typeof value === "string" && STUDIO_TAB_STATE_ID_PATTERN.test(value);
+  }
+
+  function makeStudioTabStateId(cryptoLike) {
+    try {
+      const launchId = makeStudioLaunchId(cryptoLike);
+      const candidate = "tab_" + launchId;
+      if (isValidStudioTabStateId(candidate)) return candidate;
+    } catch {
+      // This ID isolates local browser state; it is not an authentication secret.
+    }
+    const candidate = "tab_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2).padEnd(16, "0");
+    if (isValidStudioTabStateId(candidate)) return candidate;
+    throw new Error("Could not create a Studio tab-state ID.");
+  }
+
+  function ensureStudioTabStateId(windowLike) {
+    if (!windowLike || !windowLike.location) throw new Error("Studio tab-state URL is unavailable.");
+    const currentHref = String(windowLike.location.href || "");
+    const url = new URL(currentHref);
+    const existing = url.searchParams.getAll(STUDIO_TAB_STATE_PARAM);
+    if (existing.length === 1 && isValidStudioTabStateId(existing[0])) return existing[0];
+
+    const tabStateId = makeStudioTabStateId(windowLike.crypto);
+    url.searchParams.delete(STUDIO_TAB_STATE_PARAM);
+    url.searchParams.set(STUDIO_TAB_STATE_PARAM, tabStateId);
+    if (windowLike.history && typeof windowLike.history.replaceState === "function") {
+      windowLike.history.replaceState(windowLike.history.state, "", url.toString());
+    }
+    return tabStateId;
+  }
+
+  function getStudioWorkspaceStorageKey(tabStateId) {
+    if (!isValidStudioTabStateId(tabStateId)) throw new Error("Invalid Studio tab-state ID.");
+    return STUDIO_WORKSPACE_STORAGE_PREFIX + tabStateId;
+  }
+
+  function getStudioSessionStorage(windowLike) {
+    try {
+      return windowLike && windowLike.sessionStorage ? windowLike.sessionStorage : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function parseStudioWorkspaceState(raw) {
+    try {
+      const parsed = JSON.parse(String(raw || ""));
+      if (!parsed || typeof parsed !== "object" || parsed.version !== 1 || typeof parsed.text !== "string") return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  function readStudioWorkspaceState(windowLike, tabStateId) {
+    const key = getStudioWorkspaceStorageKey(tabStateId);
+    const sessionStorage = getStudioSessionStorage(windowLike);
+    if (!sessionStorage || typeof sessionStorage.getItem !== "function") return null;
+    try {
+      const current = parseStudioWorkspaceState(sessionStorage.getItem(key));
+      if (current) return current;
+      return parseStudioWorkspaceState(sessionStorage.getItem(STUDIO_WORKSPACE_LEGACY_STORAGE_KEY));
+    } catch {
+      return null;
+    }
+  }
+
+  function persistStudioWorkspaceState(windowLike, tabStateId, state) {
+    const key = getStudioWorkspaceStorageKey(tabStateId);
+    const sessionStorage = getStudioSessionStorage(windowLike);
+    if (!sessionStorage || typeof sessionStorage.setItem !== "function") return false;
+    try {
+      sessionStorage.setItem(key, JSON.stringify(state));
+      sessionStorage.removeItem(STUDIO_WORKSPACE_LEGACY_STORAGE_KEY);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function clearStudioWorkspaceState(windowLike, tabStateId) {
+    const key = getStudioWorkspaceStorageKey(tabStateId);
+    const sessionStorage = getStudioSessionStorage(windowLike);
+    if (!sessionStorage || typeof sessionStorage.removeItem !== "function") return;
+    try {
+      sessionStorage.removeItem(key);
+      sessionStorage.removeItem(STUDIO_WORKSPACE_LEGACY_STORAGE_KEY);
+    } catch {}
+  }
+
   function normalizeStudioPendingKind(value) {
     return STUDIO_PENDING_KINDS.includes(value) ? value : null;
   }
@@ -490,6 +586,9 @@
     PANE_FOCUS_OFF,
     PANE_FOCUS_PARAM,
     PANE_FOCUS_TARGETS,
+    STUDIO_TAB_STATE_PARAM,
+    STUDIO_WORKSPACE_LEGACY_STORAGE_KEY,
+    STUDIO_WORKSPACE_STORAGE_PREFIX,
     STUDIO_LAUNCH_CHANNEL_PREFIX,
     STUDIO_LAUNCH_DELIVERY_TIMEOUT_MS,
     STUDIO_LAUNCH_MESSAGE_MAX_CHARS,
@@ -501,14 +600,21 @@
     buildPendingStudioUrl,
     canOpenPendingStudioLaunch,
     createPendingStudioLaunch,
+    clearStudioWorkspaceState,
+    ensureStudioTabStateId,
+    getStudioWorkspaceStorageKey,
     isValidStudioLaunchId,
+    isValidStudioTabStateId,
     makeStudioLaunchId,
+    makeStudioTabStateId,
     normalizePaneFocusTarget,
     normalizeStudioLaunchMessage,
     normalizeStudioPendingKind,
     normalizeStudioRelativeTarget,
     openStudioTabDirect,
+    persistStudioWorkspaceState,
     readPaneFocusTarget,
+    readStudioWorkspaceState,
     replacePaneFocusUrlState,
     startStudioPendingPage,
     studioLaunchChannelName,

package/index.ts

@@ -29,6 +29,7 @@ import {
 } from "./shared/studio-markdown-latex-literals.js";
 import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
+import { isStudioCmuxSession, openStudioUrlInBrowser } from "./shared/studio-browser-launcher.js";
 import { buildStudioReplTmuxStartArgs } from "./shared/studio-repl-tmux.js";
 import { buildStudioForwardingHint, buildStudioSshTunnelHint, isStudioSshSession as isSshSession } from "./shared/studio-ssh-hint.js";
 import {
@@ -37,6 +38,11 @@ import {
 	isValidStudioLaunchId,
 	normalizeStudioPendingKind,
 } from "./shared/studio-tab-launcher.js";
+import {
+	createStudioWorkspaceStateStore,
+	isValidStudioTabStateId,
+	normalizeStudioWorkspaceRecoveryState,
+} from "./shared/studio-workspace-state.js";
 import { renderStudioAnnotationInlineHtml } from "./shared/studio-annotation-render.js";
 import {
 	buildStudioMermaidCliIconArgs,
@@ -566,6 +572,12 @@ interface CancelRequestMessage {
 	requestId: string;
 }
 
+interface WorkspaceStateUpdateMessage {
+	type: "workspace_state_update";
+	tabStateId: string;
+	state: ReturnType<typeof normalizeStudioWorkspaceRecoveryState>;
+}
+
 type IncomingStudioMessage =
 	| HelloMessage
 	| PingMessage
@@ -599,7 +611,8 @@ type IncomingStudioMessage =
 	| QuartoPreviewStopRequestMessage
 	| GitChangesRequestMessage
 	| OpenEditorOnlyRequestMessage
-	| CancelRequestMessage;
+	| CancelRequestMessage
+	| WorkspaceStateUpdateMessage;
 
 const REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
 const PREVIEW_RENDER_MAX_CHARS = 400_000;
@@ -618,6 +631,7 @@ const STUDIO_QUIZ_CONTEXT_MAX_FILES = 18;
 const STUDIO_QUIZ_SNIPPET_MAX_CHARS = 8_000;
 const STUDIO_QUIZ_DISCUSSION_MAX_CHARS = 6_000;
 const REQUEST_BODY_MAX_BYTES = 1_000_000;
+const STUDIO_WORKSPACE_STATE_REQUEST_MAX_BYTES = 4_000_000;
 const RESPONSE_HISTORY_LIMIT = 30;
 const CMUX_NOTIFY_TIMEOUT_MS = 1200;
 const PREPARED_PDF_EXPORT_TTL_MS = 5 * 60 * 1000;
@@ -7544,27 +7558,6 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 	}
 }
 
-function openUrlInDefaultBrowser(url: string): Promise<void> {
-	const openCommand =
-		process.platform === "darwin"
-			? { command: "open", args: [url] }
-			: process.platform === "win32"
-				? { command: "cmd", args: ["/c", "start", "", url] }
-				: { command: "xdg-open", args: [url] };
-
-	return new Promise<void>((resolve, reject) => {
-		const child = spawn(openCommand.command, openCommand.args, {
-			stdio: "ignore",
-			detached: true,
-		});
-		child.once("error", reject);
-		child.once("spawn", () => {
-			child.unref();
-			resolve();
-		});
-	});
-}
-
 function openPathInDefaultViewer(path: string): Promise<void> {
 	const openCommand =
 		process.platform === "darwin"
@@ -8518,6 +8511,10 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 
 	if (msg.type === "hello") return { type: "hello" };
 	if (msg.type === "ping") return { type: "ping" };
+	if (msg.type === "workspace_state_update" && typeof msg.tabStateId === "string" && isValidStudioTabStateId(msg.tabStateId)) {
+		const state = normalizeStudioWorkspaceRecoveryState(msg.state);
+		if (state) return { type: "workspace_state_update", tabStateId: msg.tabStateId, state };
+	}
 	if (msg.type === "get_latest_response") return { type: "get_latest_response" };
 	if (msg.type === "get_trace_snapshot" && typeof msg.responseHistoryId === "string") {
 		return {
@@ -10958,6 +10955,7 @@ ${cssVarsBlock}
 
 export default function (pi: ExtensionAPI) {
 	let serverState: StudioServerState | null = null;
+	const studioWorkspaceStateStore = createStudioWorkspaceStateStore();
 	let activeRequest: ActiveStudioRequest | null = null;
 	let studioDirectRunChain: StudioDirectRunChain | null = null;
 	let queuedStudioDirectRequests: QueuedStudioDirectRequest[] = [];
@@ -11328,14 +11326,7 @@ export default function (pi: ExtensionAPI) {
 		return null;
 	};
 
-	const isProbablyCmuxSession = (): boolean => {
-		const workspaceId = String(process.env.CMUX_WORKSPACE_ID ?? "").trim();
-		if (workspaceId) return true;
-		const termProgram = String(process.env.TERM_PROGRAM ?? "").trim().toLowerCase();
-		if (termProgram === "cmux") return true;
-		const term = String(process.env.TERM ?? "").trim().toLowerCase();
-		return term.includes("cmux");
-	};
+	const isProbablyCmuxSession = (): boolean => isStudioCmuxSession(process.env);
 
 	const sanitizeTerminalNotificationText = (value: string, maxLength = 240): string => {
 		const sanitized = String(value)
@@ -12618,6 +12609,10 @@ export default function (pi: ExtensionAPI) {
 			sendToClient(client, { type: "pong", timestamp: Date.now() });
 			return;
 		}
+		if (msg.type === "workspace_state_update") {
+			studioWorkspaceStateStore.set(msg.tabStateId, msg.state);
+			return;
+		}
 
 		emitDebugEvent("studio_message", {
 			type: msg.type,
@@ -14580,6 +14575,66 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/tab-workspace-state") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void (async () => {
+				const method = (req.method ?? "GET").toUpperCase();
+				if (method === "GET") {
+					const tabStateId = requestUrl.searchParams.get("tabStateId") ?? "";
+					if (!isValidStudioTabStateId(tabStateId)) {
+						respondJson(res, 400, { ok: false, error: "Invalid Studio tab-state ID." });
+						return;
+					}
+					respondJson(res, 200, { ok: true, state: studioWorkspaceStateStore.get(tabStateId) });
+					return;
+				}
+
+				if (method !== "POST") {
+					res.setHeader("Allow", "GET, POST");
+					respondJson(res, 405, { ok: false, error: "Method not allowed. Use GET or POST." });
+					return;
+				}
+
+				let rawBody = "";
+				try {
+					rawBody = await readRequestBody(req, STUDIO_WORKSPACE_STATE_REQUEST_MAX_BYTES);
+				} catch (error) {
+					respondJson(res, 413, { ok: false, error: error instanceof Error ? error.message : String(error) });
+					return;
+				}
+				let payload: Record<string, unknown> = {};
+				try {
+					payload = rawBody ? JSON.parse(rawBody) as Record<string, unknown> : {};
+				} catch {
+					respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+					return;
+				}
+				const tabStateId = typeof payload.tabStateId === "string" ? payload.tabStateId : "";
+				if (!isValidStudioTabStateId(tabStateId)) {
+					respondJson(res, 400, { ok: false, error: "Invalid Studio tab-state ID." });
+					return;
+				}
+				const state = normalizeStudioWorkspaceRecoveryState(payload.state);
+				if (!state) {
+					respondJson(res, 400, { ok: false, error: "Invalid or oversized Studio workspace state." });
+					return;
+				}
+				const stored = studioWorkspaceStateStore.set(tabStateId, state);
+				respondJson(res, 200, { ok: true, stored });
+			})().catch((error) => {
+				respondJson(res, 500, {
+					ok: false,
+					error: `Studio workspace recovery failed: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/scratchpad-state") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -15056,6 +15111,7 @@ export default function (pi: ExtensionAPI) {
 		await new Promise<void>((resolve) => {
 			state.server.close(() => resolve());
 		});
+		studioWorkspaceStateStore.clear();
 	};
 
 	const hydrateLatestAssistant = (entries: SessionEntry[]) => {
@@ -15836,7 +15892,7 @@ export default function (pi: ExtensionAPI) {
 				const skipReason = launchOpenFlags.noBrowser ? "--no-browser was used" : "SSH was detected";
 				ctx.ui.notify(`${openedLabel} is ready. Browser auto-open was skipped because ${skipReason}.`, "info");
 			} else {
-				await openUrlInDefaultBrowser(url);
+				await openStudioUrlInBrowser(url);
 				if (selected.source === "file") {
 					ctx.ui.notify(`Opened ${openedLabel} with file loaded: ${selected.label}`, "info");
 				} else if (selected.source === "last-response") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.41",
+  "version": "0.9.43",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/studio-browser-launcher.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+
+export const STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS = 5_000;
+
+/**
+ * Detect whether the current process is running inside cmux.
+ *
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function isStudioCmuxSession(env = process.env) {
+	const workspaceId = String(env.CMUX_WORKSPACE_ID ?? "").trim();
+	const termProgram = String(env.TERM_PROGRAM ?? "").trim().toLowerCase();
+	const term = String(env.TERM ?? "").trim().toLowerCase();
+	const bundleId = String(env.CMUX_BUNDLE_ID ?? "").trim().toLowerCase();
+	return Boolean(workspaceId || termProgram === "cmux" || term.includes("cmux") || bundleId.includes("cmux"));
+}
+
+/**
+ * Build the cmux CLI invocation for opening Studio in the caller's workspace.
+ *
+ * @param {string} target
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {{ command: string, args: string[] } | undefined}
+ */
+export function getStudioCmuxBrowserOpenCommand(target, env = process.env) {
+	if (!isStudioCmuxSession(env)) return undefined;
+
+	const workspaceId = String(env.CMUX_WORKSPACE_ID ?? "").trim();
+	const command = String(env.CMUX_BUNDLED_CLI_PATH ?? "").trim() || "cmux";
+	const args = ["browser", "open", target];
+	if (workspaceId) args.push("--workspace", workspaceId);
+	args.push("--focus", "true");
+	return { command, args };
+}
+
+/**
+ * Build the platform-native system-browser invocation.
+ *
+ * @param {string} target
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function getStudioDefaultBrowserOpenCommand(target, platform = process.platform) {
+	if (platform === "darwin") return { command: "open", args: [target] };
+	if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", target] };
+	return { command: "xdg-open", args: [target] };
+}
+
+/**
+ * @param {{ command: string, args: string[] }} openCommand
+ * @param {typeof spawn} spawnProcess
+ * @returns {Promise<void>}
+ */
+function spawnDetachedBrowser(openCommand, spawnProcess) {
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = spawnProcess(openCommand.command, openCommand.args, {
+				stdio: "ignore",
+				detached: true,
+			});
+		} catch (error) {
+			reject(error);
+			return;
+		}
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.unref();
+			resolve();
+		});
+	});
+}
+
+/**
+ * Try to open Studio in a focused cmux browser surface.
+ *
+ * @param {string} target
+ * @param {{
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   spawnProcess?: typeof spawn,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
+	const openCommand = getStudioCmuxBrowserOpenCommand(target, options.env ?? process.env);
+	if (!openCommand) return false;
+
+	const spawnProcess = options.spawnProcess ?? spawn;
+	const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs >= 0
+		? options.timeoutMs
+		: STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS;
+
+	return await new Promise((resolve) => {
+		let settled = false;
+		let child;
+		const finish = (opened) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			resolve(opened);
+		};
+		const timeout = setTimeout(() => {
+			child?.kill();
+			finish(false);
+		}, timeoutMs);
+		timeout.unref?.();
+
+		try {
+			child = spawnProcess(openCommand.command, openCommand.args, { stdio: "ignore" });
+		} catch {
+			finish(false);
+			return;
+		}
+		child.once("error", () => finish(false));
+		child.once("close", (code) => finish(code === 0));
+	});
+}
+
+/**
+ * Open Studio in cmux when available, falling back to the system browser.
+ *
+ * @param {string} target
+ * @param {{
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   platform?: NodeJS.Platform,
+ *   spawnProcess?: typeof spawn,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<"cmux" | "system">}
+ */
+export async function openStudioUrlInBrowser(target, options = {}) {
+	if (await tryOpenStudioUrlInCmuxBrowser(target, options)) return "cmux";
+
+	const openCommand = getStudioDefaultBrowserOpenCommand(target, options.platform ?? process.platform);
+	await spawnDetachedBrowser(openCommand, options.spawnProcess ?? spawn);
+	return "system";
+}

package/shared/studio-workspace-state.js

@@ -0,0 +1,118 @@
+export const STUDIO_TAB_STATE_ID_PATTERN = /^[a-zA-Z0-9_-]{20,128}$/;
+export const STUDIO_WORKSPACE_STATE_MAX_TEXT_CHARS = 900_000;
+export const STUDIO_WORKSPACE_STATE_MAX_ENTRIES = 16;
+export const STUDIO_WORKSPACE_STATE_MAX_TOTAL_TEXT_CHARS = 3_000_000;
+export const STUDIO_WORKSPACE_STATE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export function isValidStudioTabStateId(value) {
+	return typeof value === "string" && STUDIO_TAB_STATE_ID_PATTERN.test(value);
+}
+
+function boundedString(value, maxLength) {
+	return typeof value === "string" ? value.slice(0, maxLength) : "";
+}
+
+function finiteNumber(value, fallback = 0) {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function normalizeStudioWorkspaceRecoveryState(value) {
+	if (!value || typeof value !== "object" || value.version !== 1 || typeof value.text !== "string") return null;
+	if (value.text.length > STUDIO_WORKSPACE_STATE_MAX_TEXT_CHARS) return null;
+	const sourceState = value.sourceState && typeof value.sourceState === "object" ? value.sourceState : {};
+	return {
+		version: 1,
+		savedAt: Math.max(0, finiteNumber(value.savedAt)),
+		sourceState: {
+			source: boundedString(sourceState.source, 100),
+			label: boundedString(sourceState.label, 4_000),
+			path: boundedString(sourceState.path, 16_384) || null,
+			draftId: boundedString(sourceState.draftId, 256) || null,
+		},
+		resourceDir: boundedString(value.resourceDir, 16_384),
+		editorView: boundedString(value.editorView, 100),
+		rightView: boundedString(value.rightView, 100),
+		editorLanguage: boundedString(value.editorLanguage, 100),
+		followLatest: value.followLatest === true,
+		responseHistoryIndex: Math.floor(finiteNumber(value.responseHistoryIndex, -1)),
+		selectionStart: Math.max(0, Math.floor(finiteNumber(value.selectionStart))),
+		selectionEnd: Math.max(0, Math.floor(finiteNumber(value.selectionEnd))),
+		scrollTop: Math.max(0, finiteNumber(value.scrollTop)),
+		text: value.text,
+	};
+}
+
+export function createStudioWorkspaceStateStore(options = {}) {
+	const maxEntries = Math.max(1, Math.floor(Number(options.maxEntries) || STUDIO_WORKSPACE_STATE_MAX_ENTRIES));
+	const maxTotalTextChars = Math.max(1, Math.floor(Number(options.maxTotalTextChars) || STUDIO_WORKSPACE_STATE_MAX_TOTAL_TEXT_CHARS));
+	const ttlMs = Math.max(1, Math.floor(Number(options.ttlMs) || STUDIO_WORKSPACE_STATE_TTL_MS));
+	const now = typeof options.now === "function" ? options.now : Date.now;
+	const entries = new Map();
+	let totalTextChars = 0;
+
+	function remove(tabStateId) {
+		const existing = entries.get(tabStateId);
+		if (!existing) return false;
+		entries.delete(tabStateId);
+		totalTextChars = Math.max(0, totalTextChars - existing.state.text.length);
+		return true;
+	}
+
+	function cleanup() {
+		const currentTime = now();
+		for (const [tabStateId, entry] of entries) {
+			if (currentTime - entry.storedAt > ttlMs) remove(tabStateId);
+		}
+	}
+
+	function evictOldest(excludedTabStateId) {
+		let oldestId = null;
+		let oldestStoredAt = Number.POSITIVE_INFINITY;
+		for (const [tabStateId, entry] of entries) {
+			if (tabStateId === excludedTabStateId) continue;
+			if (entry.storedAt < oldestStoredAt) {
+				oldestId = tabStateId;
+				oldestStoredAt = entry.storedAt;
+			}
+		}
+		return oldestId ? remove(oldestId) : false;
+	}
+
+	return Object.freeze({
+		get(tabStateId) {
+			if (!isValidStudioTabStateId(tabStateId)) return null;
+			cleanup();
+			return entries.get(tabStateId)?.state ?? null;
+		},
+		set(tabStateId, rawState) {
+			if (!isValidStudioTabStateId(tabStateId)) return false;
+			const state = normalizeStudioWorkspaceRecoveryState(rawState);
+			if (!state || state.text.length > maxTotalTextChars) return false;
+			cleanup();
+			const existing = entries.get(tabStateId);
+			if (existing && existing.state.savedAt > state.savedAt) return false;
+			if (existing) remove(tabStateId);
+			while (entries.size >= maxEntries || totalTextChars + state.text.length > maxTotalTextChars) {
+				if (!evictOldest(tabStateId)) return false;
+			}
+			entries.set(tabStateId, { state, storedAt: now() });
+			totalTextChars += state.text.length;
+			return true;
+		},
+		delete(tabStateId) {
+			return isValidStudioTabStateId(tabStateId) ? remove(tabStateId) : false;
+		},
+		clear() {
+			entries.clear();
+			totalTextChars = 0;
+		},
+		get size() {
+			cleanup();
+			return entries.size;
+		},
+		get totalTextChars() {
+			cleanup();
+			return totalTextChars;
+		},
+	});
+}