pi-studio 0.9.39 → 0.9.41

package/index.ts

@@ -29,7 +29,14 @@ 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 { buildStudioReplTmuxStartArgs } from "./shared/studio-repl-tmux.js";
 import { buildStudioForwardingHint, buildStudioSshTunnelHint, isStudioSshSession as isSshSession } from "./shared/studio-ssh-hint.js";
+import {
+	buildStudioPendingPage,
+	buildStudioPendingSecurityHeaders,
+	isValidStudioLaunchId,
+	normalizeStudioPendingKind,
+} from "./shared/studio-tab-launcher.js";
 import { renderStudioAnnotationInlineHtml } from "./shared/studio-annotation-render.js";
 import {
 	buildStudioMermaidCliIconArgs,
@@ -89,6 +96,7 @@ interface StudioQuartoPreviewState {
 const STUDIO_CSS_URL = new URL("./client/studio.css", import.meta.url);
 const STUDIO_ANNOTATION_HELPERS_URL = new URL("./client/studio-annotation-helpers.js", import.meta.url);
 const STUDIO_MERMAID_HELPERS_URL = new URL("./client/studio-mermaid-helpers.js", import.meta.url);
+const STUDIO_NAVIGATION_HELPERS_URL = new URL("./client/studio-navigation-helpers.js", import.meta.url);
 const STUDIO_CLIENT_URL = new URL("./client/studio-client.js", import.meta.url);
 
 interface StudioServerState {
@@ -7258,6 +7266,17 @@ function respondText(res: ServerResponse, status: number, text: string): void {
 	res.end(text);
 }
 
+function respondStudioPendingError(res: ServerResponse, status: number, text: string, allow?: string): void {
+	const nonce = randomUUID().replace(/-/g, "");
+	const headers = {
+		...buildStudioPendingSecurityHeaders(nonce),
+		"Content-Type": "text/plain; charset=utf-8",
+		...(allow ? { Allow: allow } : {}),
+	};
+	res.writeHead(status, headers);
+	res.end(text);
+}
+
 function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: string): void {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") {
@@ -7393,12 +7412,9 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 		}
 		const document = buildStudioLocalResourcePreviewDocument(resource);
 		const docId = storeTransientStudioDocument(document);
-		const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true });
-		const parsedUrl = new URL(url);
 		respondJson(res, 200, {
 			...basePayload,
-			url,
-			relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+			relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 		});
 		return;
 	}
@@ -7458,13 +7474,10 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 	}
 
 	const docId = storeTransientStudioDocument(document);
-	const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true });
-	const parsedUrl = new URL(url);
 	respondJson(res, 200, {
 		...basePayload,
 		converted,
-		url,
-		relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+		relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 	});
 }
 
@@ -9626,7 +9639,7 @@ function startStudioReplSession(runtime: StudioReplRuntime, cwd: string, options
 		};
 	}
 	const command = getStudioReplRuntimeCommand(runtime, commandOverride);
-	const result = runStudioTmux(["new-session", "-d", "-s", sessionName, "-c", cwd || process.cwd(), command], { timeout: 5_000 });
+	const result = runStudioTmux(buildStudioReplTmuxStartArgs(sessionName, cwd || process.cwd(), command), { timeout: 5_000 });
 	if (!result.ok) return { ok: false, message: result.message || `Failed to start ${STUDIO_REPL_RUNTIME_LABELS[runtime]} REPL.` };
 	return {
 		ok: true,
@@ -10077,8 +10090,7 @@ function readTransientStudioDocument(id: string): InitialStudioDocument | null {
 	return entry ? { ...entry.document } : null;
 }
 
-function buildStudioUrl(
-	port: number,
+function buildStudioRelativeUrl(
 	token: string,
 	mode: StudioUiMode = "full",
 	doc?: InitialStudioDocument | null,
@@ -10094,7 +10106,18 @@ function buildStudioUrl(
 	if (doc?.draftId) params.set("draftId", doc.draftId);
 	if (doc?.resourceDir) params.set("resourceDir", doc.resourceDir);
 	if (options?.skipWorkspaceRestore) params.set("skipWorkspaceRestore", "1");
-	return `http://127.0.0.1:${port}/?${params.toString()}`;
+	return `/?${params.toString()}`;
+}
+
+function buildStudioUrl(
+	port: number,
+	token: string,
+	mode: StudioUiMode = "full",
+	doc?: InitialStudioDocument | null,
+	docId?: string,
+	options?: { skipWorkspaceRestore?: boolean },
+): string {
+	return `http://127.0.0.1:${port}${buildStudioRelativeUrl(token, mode, doc, docId, options)}`;
 }
 
 interface StudioLaunchFlags {
@@ -10508,6 +10531,7 @@ function buildStudioHtml(
 	const stylesheetHref = `/studio.css?token=${encodeURIComponent(studioToken ?? "")}`;
 	const annotationHelpersScriptHref = `/studio-annotation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const mermaidHelpersScriptHref = `/studio-mermaid-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
+	const navigationHelpersScriptHref = `/studio-navigation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const clientScriptHref = `/studio-client.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const faviconHref = buildStudioFaviconDataUri(style);
 	const bootConfigJson = JSON.stringify({ mermaidConfig }).replace(/</g, "\\u003c");
@@ -10926,6 +10950,7 @@ ${cssVarsBlock}
   </script>
   <script src="${annotationHelpersScriptHref}"></script>
   <script src="${mermaidHelpersScriptHref}"></script>
+  <script src="${navigationHelpersScriptHref}"></script>
   <script src="${clientScriptHref}"></script>
 </body>
 </html>`;
@@ -12851,13 +12876,10 @@ export default function (pi: ExtensionAPI) {
 				resourceDir,
 			};
 			const docId = storeTransientStudioDocument(document);
-			const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true });
-			const parsedUrl = new URL(url);
 			sendToClient(client, {
 				type: "editor_only_ready",
 				requestId: msg.requestId,
-				url,
-				relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+				relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 				message: hasContent
 					? "Editor tab is ready with a detached copy of the current editor text."
 					: "Blank editor tab is ready.",
@@ -14237,8 +14259,6 @@ export default function (pi: ExtensionAPI) {
 					resourceDir: dirname(exportedPath),
 				};
 				const docId = storeTransientStudioDocument(document);
-				const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true });
-				const parsedUrl = new URL(url);
 				respondJson(res, 200, {
 					ok: true,
 					filename,
@@ -14246,8 +14266,7 @@ export default function (pi: ExtensionAPI) {
 					writeError: writeResult.error,
 					warning: warning ?? null,
 					openedStudio: true,
-					url,
-					relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+					relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 					downloadUrl: `/export-pdf?token=${encodeURIComponent(token)}&id=${encodeURIComponent(exportId)}`,
 				});
 				return;
@@ -14384,8 +14403,6 @@ export default function (pi: ExtensionAPI) {
 					draftId: exportedPath ? undefined : createStudioDraftId(),
 				};
 				const docId = storeTransientStudioDocument(document);
-				const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true });
-				const parsedUrl = new URL(url);
 				respondJson(res, 200, {
 					ok: true,
 					filename,
@@ -14393,8 +14410,7 @@ export default function (pi: ExtensionAPI) {
 					writeError: writeResult.error,
 					warning: warning ?? null,
 					openedStudio: true,
-					url,
-					relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+					relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 					downloadUrl: `/export-html?token=${encodeURIComponent(token)}&id=${encodeURIComponent(exportId)}`,
 				});
 				return;
@@ -14453,6 +14469,39 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/studio-open-pending") {
+			const tokens = requestUrl.searchParams.getAll("token");
+			if (tokens.length !== 1 || tokens[0] !== serverState.token) {
+				respondStudioPendingError(res, 403, "Invalid or expired studio token. Re-run /studio.");
+				return;
+			}
+
+			const method = (req.method ?? "GET").toUpperCase();
+			if (method !== "GET") {
+				respondStudioPendingError(res, 405, "Method not allowed. Use GET.", "GET");
+				return;
+			}
+
+			const allowedKeys = new Set(["token", "launchId", "kind"]);
+			if (Array.from(requestUrl.searchParams.keys()).some((key) => !allowedKeys.has(key))) {
+				respondStudioPendingError(res, 400, "Unsupported Studio pending-page parameter.");
+				return;
+			}
+			const launchIds = requestUrl.searchParams.getAll("launchId");
+			const kinds = requestUrl.searchParams.getAll("kind");
+			const launchId = launchIds.length === 1 ? launchIds[0] : "";
+			const kind = kinds.length === 1 ? normalizeStudioPendingKind(kinds[0]) : null;
+			if (!isValidStudioLaunchId(launchId) || !kind) {
+				respondStudioPendingError(res, 400, "Invalid Studio pending-page request.");
+				return;
+			}
+
+			const nonce = randomUUID().replace(/-/g, "");
+			res.writeHead(200, buildStudioPendingSecurityHeaders(nonce));
+			res.end(buildStudioPendingPage({ token: serverState.token, launchId, kind, nonce }));
+			return;
+		}
+
 		if (requestUrl.pathname === "/studio.css") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -14482,7 +14531,12 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		if (requestUrl.pathname === "/studio-annotation-helpers.js" || requestUrl.pathname === "/studio-mermaid-helpers.js" || requestUrl.pathname === "/studio-client.js") {
+		if (
+			requestUrl.pathname === "/studio-annotation-helpers.js"
+			|| requestUrl.pathname === "/studio-mermaid-helpers.js"
+			|| requestUrl.pathname === "/studio-navigation-helpers.js"
+			|| requestUrl.pathname === "/studio-client.js"
+		) {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
 				respondText(res, 403, "Invalid or expired studio token. Re-run /studio.");
@@ -14500,12 +14554,16 @@ export default function (pi: ExtensionAPI) {
 				? STUDIO_ANNOTATION_HELPERS_URL
 				: requestUrl.pathname === "/studio-mermaid-helpers.js"
 					? STUDIO_MERMAID_HELPERS_URL
-					: STUDIO_CLIENT_URL;
+					: requestUrl.pathname === "/studio-navigation-helpers.js"
+						? STUDIO_NAVIGATION_HELPERS_URL
+						: STUDIO_CLIENT_URL;
 			const targetLabel = requestUrl.pathname === "/studio-annotation-helpers.js"
 				? "studio annotation helper script"
 				: requestUrl.pathname === "/studio-mermaid-helpers.js"
 					? "studio Mermaid helper script"
-					: "studio client script";
+					: requestUrl.pathname === "/studio-navigation-helpers.js"
+						? "studio navigation helper script"
+						: "studio client script";
 
 			try {
 				const clientScript = readFileSync(targetUrl, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "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",
@@ -30,6 +30,7 @@
   ],
   "scripts": {
     "test": "node --test",
+    "test:browser": "node --test test/studio-tab-launcher-browser.test.js",
     "typecheck": "tsc --noEmit"
   },
   "pi": {

package/shared/studio-repl-tmux.js

@@ -0,0 +1,28 @@
+const STUDIO_REPL_PROMPT_COMMAND_ENVIRONMENT = "PROMPT_COMMAND=";
+
+/**
+ * Build the tmux arguments for a Studio-owned REPL session.
+ *
+ * PROMPT_COMMAND contains shell-local function names on some terminals (notably
+ * cmux/Ghostty with macOS Bash 3.2). The variable may be exported to Pi while
+ * the corresponding functions cannot be inherited by a child shell, so start
+ * each detached REPL with a clean prompt-command environment.
+ *
+ * @param {string} sessionName
+ * @param {string} cwd
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function buildStudioReplTmuxStartArgs(sessionName, cwd, command) {
+	return [
+		"new-session",
+		"-d",
+		"-s",
+		sessionName,
+		"-c",
+		cwd,
+		"-e",
+		STUDIO_REPL_PROMPT_COMMAND_ENVIRONMENT,
+		command,
+	];
+}

package/shared/studio-tab-launcher.js

@@ -0,0 +1,86 @@
+const STUDIO_PENDING_KINDS = Object.freeze(["document", "preview", "export"]);
+const STUDIO_LAUNCH_ID_PATTERN = /^[a-zA-Z0-9_-]{20,128}$/;
+const STUDIO_CSP_NONCE_PATTERN = /^[a-zA-Z0-9_-]{16,128}$/;
+
+function escapeHtmlAttribute(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function normalizeStudioPendingKind(value) {
+  return STUDIO_PENDING_KINDS.includes(value) ? value : null;
+}
+
+export function isValidStudioLaunchId(value) {
+  return typeof value === "string" && STUDIO_LAUNCH_ID_PATTERN.test(value);
+}
+
+export function buildStudioPendingSecurityHeaders(nonce) {
+  if (typeof nonce !== "string" || !STUDIO_CSP_NONCE_PATTERN.test(nonce)) {
+    throw new Error("Invalid Studio pending-page CSP nonce.");
+  }
+  return {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cross-Origin-Opener-Policy": "same-origin",
+    "Cross-Origin-Resource-Policy": "same-origin",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+    "Content-Security-Policy": [
+      "default-src 'none'",
+      `script-src 'nonce-${nonce}'`,
+      `style-src 'nonce-${nonce}'`,
+      "base-uri 'none'",
+      "form-action 'none'",
+      "object-src 'none'",
+      "frame-ancestors 'none'",
+    ].join("; "),
+  };
+}
+
+export function buildStudioPendingPage(options) {
+  const config = options && typeof options === "object" ? options : {};
+  const token = typeof config.token === "string" ? config.token : "";
+  const launchId = typeof config.launchId === "string" ? config.launchId : "";
+  const kind = normalizeStudioPendingKind(config.kind);
+  const nonce = typeof config.nonce === "string" ? config.nonce : "";
+  if (!token) throw new Error("Studio pending page requires a token.");
+  if (!isValidStudioLaunchId(launchId)) throw new Error("Invalid Studio launch ID.");
+  if (!kind) throw new Error("Invalid Studio pending-page kind.");
+  buildStudioPendingSecurityHeaders(nonce);
+
+  const kindLabel = kind === "document" ? "document" : (kind === "export" ? "export" : "preview");
+  const helperQuery = new URLSearchParams({ token }).toString();
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>Preparing Studio tab…</title>
+  <style nonce="${escapeHtmlAttribute(nonce)}">
+    :root { color-scheme: light dark; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { min-height: 100vh; margin: 0; display: grid; place-items: center; background: Canvas; color: CanvasText; }
+    main { width: min(34rem, calc(100vw - 3rem)); padding: 2rem; border: 1px solid color-mix(in srgb, CanvasText 18%, transparent); border-radius: 12px; }
+    h1 { margin: 0 0 0.65rem; font-size: 1.15rem; }
+    p { margin: 0; line-height: 1.5; opacity: 0.8; overflow-wrap: anywhere; }
+    button { margin-top: 1.25rem; padding: 0.45rem 0.8rem; font: inherit; }
+    [hidden] { display: none !important; }
+  </style>
+</head>
+<body data-studio-pending-launch="1" data-launch-id="${escapeHtmlAttribute(launchId)}" data-launch-kind="${escapeHtmlAttribute(kind)}" data-studio-token="${escapeHtmlAttribute(token)}">
+  <main aria-live="polite" aria-atomic="true">
+    <h1 id="pendingTitle">Preparing Studio ${kindLabel}…</h1>
+    <p id="pendingDetail">Waiting for the originating Studio page.</p>
+    <button id="pendingCloseBtn" type="button" hidden>Close tab</button>
+  </main>
+  <noscript>This Studio tab requires JavaScript. You can close it and return to the originating Studio page.</noscript>
+  <script nonce="${escapeHtmlAttribute(nonce)}" src="/studio-navigation-helpers.js?${escapeHtmlAttribute(helperQuery)}"></script>
+</body>
+</html>`;
+}
+
+export { STUDIO_PENDING_KINDS };