pi-studio 0.9.48 → 0.9.50

package/index.ts

@@ -28,6 +28,7 @@ import {
 	preserveLiteralLatexCommandsInMarkdown,
 } from "./shared/studio-markdown-latex-literals.js";
 import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
+import { parseStudioLocalPreviewPage, parseStudioPdfLaunchTarget } from "./shared/studio-local-preview-path.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
 import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pandoc-resource-flag.js";
 import { prepareStudioLatexForPandoc } from "./shared/studio-latex-pandoc-compat.js";
@@ -276,6 +277,21 @@ interface InitialStudioDocument {
 	resourceDir?: string;
 }
 
+interface StudioLaunchSelection {
+	document: InitialStudioDocument;
+	kind: "document" | "pdf-preview";
+	mode?: StudioUiMode;
+	transient?: boolean;
+	skipWorkspaceRestore?: boolean;
+	paneFocus?: "left" | "right";
+	resourcePath?: string;
+}
+
+interface StudioUrlOptions {
+	skipWorkspaceRestore?: boolean;
+	paneFocus?: "left" | "right";
+}
+
 type PersistedStudioReviewNoteAnchorKind = "source" | "html-selection" | "html-element" | "html-page";
 
 interface PersistedStudioReviewNote {
@@ -2949,35 +2965,6 @@ function decodeStudioHtmlPreviewResourcePath(resourcePath: string): string {
 	}
 }
 
-function parseStudioLocalPreviewResourcePage(resourcePath: string): number | null {
-	const raw = String(resourcePath || "");
-	const parts: string[] = [];
-	const queryIndex = raw.indexOf("?");
-	if (queryIndex >= 0) {
-		const queryEnd = raw.indexOf("#", queryIndex);
-		parts.push(raw.slice(queryIndex + 1, queryEnd >= 0 ? queryEnd : raw.length));
-	}
-	const hashIndex = raw.indexOf("#");
-	if (hashIndex >= 0) parts.push(raw.slice(hashIndex + 1));
-	for (const part of parts) {
-		try {
-			const params = new URLSearchParams(part);
-			const rawPage = params.get("page") || params.get("p");
-			if (rawPage) {
-				const page = Number.parseInt(rawPage, 10);
-				if (Number.isFinite(page) && page > 0) return page;
-			}
-		} catch {
-			const match = part.match(/(?:^|[&;])page=(\d+)/i) || part.match(/^page=(\d+)$/i);
-			if (match && match[1]) {
-				const page = Number.parseInt(match[1], 10);
-				if (Number.isFinite(page) && page > 0) return page;
-			}
-		}
-	}
-	return null;
-}
-
 function getStudioLocalPreviewResourceKind(extension: string, filePathOrName?: string): StudioLocalPreviewResourceKind {
 	const ext = extension.toLowerCase();
 	const name = basename(String(filePathOrName || "")).toLowerCase();
@@ -3022,7 +3009,7 @@ function resolveStudioLocalPreviewResourcePath(
 		label: rel && rel !== "" ? rel : basename(candidateReal),
 		extension,
 		kind: getStudioLocalPreviewResourceKind(extension, candidateReal),
-		page: parseStudioLocalPreviewResourcePage(rawPath),
+		page: parseStudioLocalPreviewPage(rawPath),
 		resourceDir: boundaryReal,
 	};
 }
@@ -7369,16 +7356,31 @@ function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: str
 		return;
 	}
 
-	const pdf = readFileSync(filePath);
-	res.writeHead(200, {
+	const stats = statSync(filePath);
+	const etag = `W/"${[
+		stats.size,
+		Math.trunc(stats.mtimeMs),
+		Math.trunc(stats.ctimeMs),
+		stats.ino,
+	].map((value) => Number(value).toString(16)).join("-")}"`;
+	const commonHeaders = {
 		"Content-Type": "application/pdf",
-		"Content-Length": String(pdf.length),
 		"Content-Disposition": `inline; filename="${basename(filePath).replace(/["\\]/g, "") || "document.pdf"}"`,
 		"Cache-Control": "no-store",
 		"X-Content-Type-Options": "nosniff",
 		"Cross-Origin-Resource-Policy": "same-origin",
-	});
-	res.end(method === "HEAD" ? undefined : pdf);
+		"ETag": etag,
+		"Last-Modified": stats.mtime.toUTCString(),
+	};
+	if (method === "HEAD") {
+		res.writeHead(200, { ...commonHeaders, "Content-Length": String(stats.size) });
+		res.end();
+		return;
+	}
+
+	const pdf = readFileSync(filePath);
+	res.writeHead(200, { ...commonHeaders, "Content-Length": String(pdf.length) });
+	res.end(pdf);
 }
 
 function respondHtmlPreviewResourceJson(req: IncomingMessage, res: ServerResponse, filePath: string, mimeType: string): void {
@@ -7406,7 +7408,7 @@ function sanitizeStudioPreviewBlockLine(value: string): string {
 	return String(value || "").replace(/[\r\n]+/g, " ").trim();
 }
 
-function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource): InitialStudioDocument {
+function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource, options?: { watchPdf?: boolean }): InitialStudioDocument {
 	const label = basename(resource.filePath) || resource.label || "local preview";
 	const resourcePath = resource.label || basename(resource.filePath) || resource.filePath;
 	const title = sanitizeStudioPreviewBlockLine(label);
@@ -7415,6 +7417,8 @@ function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewRes
 		text = "```studio-pdf\n"
 			+ `path: ${sanitizeStudioPreviewBlockLine(resourcePath)}\n`
 			+ `title: ${title || "PDF preview"}\n`
+			+ (resource.page ? `page: ${resource.page}\n` : "")
+			+ (options?.watchPdf ? "watch: true\n" : "")
 			+ "height: 820\n"
 			+ "```\n";
 	} else if (resource.kind === "image") {
@@ -10283,7 +10287,7 @@ function buildStudioRelativeUrl(
 	mode: StudioUiMode = "full",
 	doc?: InitialStudioDocument | null,
 	docId?: string,
-	options?: { skipWorkspaceRestore?: boolean },
+	options?: StudioUrlOptions,
 ): string {
 	const params = new URLSearchParams({ token });
 	if (mode !== "full") params.set("mode", mode);
@@ -10294,6 +10298,7 @@ function buildStudioRelativeUrl(
 	if (doc?.draftId) params.set("draftId", doc.draftId);
 	if (doc?.resourceDir) params.set("resourceDir", doc.resourceDir);
 	if (options?.skipWorkspaceRestore) params.set("skipWorkspaceRestore", "1");
+	if (options?.paneFocus) params.set("paneFocus", options.paneFocus);
 	return `/?${params.toString()}`;
 }
 
@@ -10303,7 +10308,7 @@ function buildStudioUrl(
 	mode: StudioUiMode = "full",
 	doc?: InitialStudioDocument | null,
 	docId?: string,
-	options?: { skipWorkspaceRestore?: boolean },
+	options?: StudioUrlOptions,
 ): string {
 	return `http://127.0.0.1:${port}${buildStudioRelativeUrl(token, mode, doc, docId, options)}`;
 }
@@ -10312,16 +10317,18 @@ interface StudioLaunchFlags {
 	args: string;
 	openRemoteBrowser: boolean;
 	noBrowser: boolean;
+	watchPdf: boolean;
 	port?: number;
 	error?: string;
 }
 
 function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 	const parsed = tokenizeStudioCommandArgs(rawArgs);
-	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, error: parsed.error };
+	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, watchPdf: false, error: parsed.error };
 	const remaining: string[] = [];
 	let openRemoteBrowser = false;
 	let noBrowser = false;
+	let watchPdf = false;
 	let port: number | undefined;
 	for (let i = 0; i < parsed.tokens.length; i += 1) {
 		const token = parsed.tokens[i]!;
@@ -10333,14 +10340,18 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 			noBrowser = true;
 			continue;
 		}
+		if (token === "--watch" || token === "--auto-refresh") {
+			watchPdf = true;
+			continue;
+		}
 		if (token === "--port" || token.startsWith("--port=")) {
 			const rawPort = token.startsWith("--port=") ? token.slice("--port=".length) : parsed.tokens[++i];
 			if (!rawPort) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, error: "Missing value for --port." };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: "Missing value for --port." };
 			}
 			const requestedPort = Number(rawPort);
 			if (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
 			}
 			port = requestedPort;
 			continue;
@@ -10348,9 +10359,9 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 		remaining.push(token);
 	}
 	if (openRemoteBrowser && noBrowser) {
-		return { args: rawArgs, openRemoteBrowser, noBrowser, port, error: "Use either --no-browser or --open-browser, not both." };
+		return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, port, error: "Use either --no-browser or --open-browser, not both." };
 	}
-	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, port };
+	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, watchPdf, port };
 }
 
 function shouldAutoOpenStudioBrowser(options?: { openRemoteBrowser?: boolean; noBrowser?: boolean }): boolean {
@@ -10745,7 +10756,7 @@ ${cssVarsBlock}
   <link rel="stylesheet" href="${stylesheetHref}" />
 </head>
 <body data-initial-source="${initialSource}" data-initial-label="${initialLabel}" data-initial-path="${initialPath}" data-initial-draft-id="${initialDraftId}" data-initial-resource-dir="${initialResourceDir}" data-model-label="${initialModel}" data-terminal-label="${initialTerminal}" data-terminal-detail="${initialTerminalDetailAttr}" data-theme-name="${initialTheme}" data-context-tokens="${initialContextTokens}" data-context-window="${initialContextWindow}" data-context-percent="${initialContextPercent}" data-studio-mode="${studioMode}" data-ssh-session="${initialSshSession}">
-  <header>
+  <header id="studioHeader">
     <h1><span class="app-logo" aria-hidden="true">π</span> Studio <span class="app-subtitle">${appSubtitle}</span></h1>
     <div class="controls">
       <button id="saveAsBtn" type="button" title="Save editor content to a new file path. Cmd/Ctrl+S falls back here when no direct save path is available.">Save editor as…</button>
@@ -10755,9 +10766,13 @@ ${cssVarsBlock}
       <button id="importFileBtn" type="button" title="Import a file as an editable copy.">Import file copy…</button>
       <input id="fileInput" class="file-input-hidden" type="file" tabindex="-1" aria-hidden="true" accept=".md,.markdown,.mdx,.qmd,.js,.mjs,.cjs,.jsx,.ts,.mts,.cts,.tsx,.py,.pyw,.sh,.bash,.zsh,.json,.jsonc,.json5,.rs,.c,.h,.cpp,.cxx,.cc,.hpp,.hxx,.jl,.f90,.f95,.f03,.f,.for,.r,.R,.m,.tex,.latex,.diff,.patch,.java,.go,.rb,.swift,.html,.htm,.css,.xml,.yaml,.yml,.toml,.lua,.txt,.rst,.adoc" />
       <button id="getEditorBtn" type="button" title="Load the current terminal editor draft into Studio.">Load from pi editor</button>
-      <button id="zenModeBtn" class="zen-mode-btn" type="button" title="Hide secondary Studio controls. Shortcut: F9.">Zen</button>
+      <button id="hideStudioHeaderBtn" class="header-visibility-btn" type="button" aria-controls="studioHeader" title="Hide the global Studio header. Restore it from the top-right edge.">Hide header</button>
+      <button id="zenModeBtn" class="zen-mode-btn" type="button" title="Hide the Studio header and secondary controls. Shortcut: F9.">Zen</button>
     </div>
   </header>
+  <div id="studioHeaderReveal" class="studio-header-reveal" hidden>
+    <button id="studioHeaderRevealBtn" type="button" aria-controls="studioHeader" title="Show the Studio header.">Show header</button>
+  </div>
 
   <main>
     <section id="leftPane">
@@ -11070,7 +11085,7 @@ ${cssVarsBlock}
             <div><dt>Cmd/Ctrl+Alt+W</dt><dd>Switch the right pane directly to Working</dd></div>
             <div><dt>F8</dt><dd>Focus editor text</dd></div>
             <div><dt>Shift+F8</dt><dd>Focus right-pane content</dd></div>
-            <div><dt>F9</dt><dd>Toggle Zen mode</dd></div>
+            <div><dt>F9</dt><dd>Toggle Zen mode and hide or restore the Studio header</dd></div>
             <div><dt>F10</dt><dd>Focus or unfocus the active pane</dd></div>
             <div><dt>Esc</dt><dd>Close overlays, exit pane focus, or stop an active request</dd></div>
             <div><dt>?</dt><dd>Show keyboard shortcuts when not editing text</dd></div>
@@ -11082,6 +11097,7 @@ ${cssVarsBlock}
             <div><dt>Alt/Option+=</dt><dd>Increase the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+-</dt><dd>Decrease the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+0</dt><dd>Reset the active pane's text size when not editing text</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+R</dt><dd>Refresh the focused or visible PDF preview from disk</dd></div>
           </dl>
         </section>
         <section class="shortcuts-group">
@@ -15744,10 +15760,11 @@ export default function (pi: ExtensionAPI) {
 	const resolveStudioLaunchDocument = (
 		trimmed: string,
 		ctx: ExtensionCommandContext,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string },
-	): InitialStudioDocument | null => {
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; allowPdfPreview?: boolean; watchPdf?: boolean },
+	): StudioLaunchSelection | null => {
 		const defaultSource = options?.defaultSource === "blank" ? "blank" : "last-response";
 		const commandLabel = options?.commandLabel ?? "/studio";
+		const selectDocument = (document: InitialStudioDocument): StudioLaunchSelection => ({ document, kind: "document" });
 		const latestAssistant =
 			extractLatestAssistantFromEntries(ctx.sessionManager.getBranch())
 				?? extractLatestAssistantFromEntries(ctx.sessionManager.getEntries())
@@ -15756,51 +15773,51 @@ export default function (pi: ExtensionAPI) {
 
 		if (!trimmed) {
 			if (defaultSource === "last-response" && latestAssistant) {
-				return {
+				return selectDocument({
 					text: latestAssistant,
 					label: "last model response",
 					source: "last-response",
 					draftId: createStudioDraftId(),
 					resourceDir: ctx.cwd,
-				};
+				});
 			}
-			return {
+			return selectDocument({
 				text: "",
 				label: "blank",
 				source: "blank",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed === "--blank" || trimmed === "blank") {
-			return {
+			return selectDocument({
 				text: "",
 				label: "blank",
 				source: "blank",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed === "--last" || trimmed === "last") {
 			if (!latestAssistant) {
 				ctx.ui.notify("No assistant response found; opening blank studio.", "warning");
-				return {
+				return selectDocument({
 					text: "",
 					label: "blank",
 					source: "blank",
 					draftId: createStudioDraftId(),
 					resourceDir: ctx.cwd,
-				};
+				});
 			}
-			return {
+			return selectDocument({
 				text: latestAssistant,
 				label: "last model response",
 				source: "last-response",
 				draftId: createStudioDraftId(),
 				resourceDir: ctx.cwd,
-			};
+			});
 		}
 
 		if (trimmed.startsWith("-")) {
@@ -15814,6 +15831,36 @@ export default function (pi: ExtensionAPI) {
 			return null;
 		}
 
+		const pdfTarget = options?.allowPdfPreview ? parseStudioPdfLaunchTarget(normalizePathInput(pathArg)) : null;
+		if (pdfTarget) {
+			const resolved = resolveStudioPath(pdfTarget.path, ctx.cwd);
+			if (resolved.ok === false) {
+				ctx.ui.notify(resolved.message, "error");
+				return null;
+			}
+			try {
+				const resource = resolveStudioLocalPreviewResourcePath(
+					pdfTarget.page ? `${resolved.resolved}#page=${pdfTarget.page}` : resolved.resolved,
+					resolved.resolved,
+					dirname(resolved.resolved),
+					ctx.cwd,
+				);
+				if (resource.kind !== "pdf") throw new Error("Only local .pdf files can open in the Studio PDF viewer.");
+				return {
+					document: buildStudioLocalResourcePreviewDocument(resource, { watchPdf: options?.watchPdf }),
+					kind: "pdf-preview",
+					mode: "editor-only",
+					transient: true,
+					skipWorkspaceRestore: true,
+					paneFocus: "right",
+					resourcePath: resource.filePath,
+				};
+			} catch (error) {
+				ctx.ui.notify(`Could not open PDF preview: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return null;
+			}
+		}
+
 		const file = readStudioFile(pathArg, ctx.cwd);
 		if (file.ok === false) {
 			ctx.ui.notify(file.message, "error");
@@ -15827,13 +15874,13 @@ export default function (pi: ExtensionAPI) {
 			);
 		}
 
-		return {
+		return selectDocument({
 			text: file.text,
 			label: file.label,
 			source: "file",
 			path: file.resolvedPath,
 			resourceDir: ctx.cwd,
-		};
+		});
 	};
 
 	const resolveLastModelResponseForExport = (ctx: ExtensionContext): { markdown: string } | null => {
@@ -16090,7 +16137,7 @@ export default function (pi: ExtensionAPI) {
 		trimmed: string,
 		ctx: ExtensionCommandContext,
 		mode: StudioUiMode,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean },
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean; allowPdfPreview?: boolean; watchPdf?: boolean },
 	) => {
 		const launchOpenFlags = parseStudioLaunchOpenFlags(trimmed);
 		if (launchOpenFlags.error) {
@@ -16101,7 +16148,17 @@ export default function (pi: ExtensionAPI) {
 		if (serverState && launchOpenFlags.port && serverState.port !== launchOpenFlags.port) {
 			ctx.ui.notify(`Studio server is already running on port ${serverState.port}; requested port ${launchOpenFlags.port}. Use /studio --stop, then restart Studio with --port ${launchOpenFlags.port} to change it.`, "warning");
 		}
-		if (mode === "full" && hasConnectedFullStudioView()) {
+
+		const parsedLaunchPath = options?.allowPdfPreview ? parsePathArgument(launchArgs) : null;
+		const launchesPdfPreview = parsedLaunchPath
+			? Boolean(parseStudioPdfLaunchTarget(normalizePathInput(parsedLaunchPath)))
+			: false;
+		if (launchOpenFlags.watchPdf && !launchesPdfPreview) {
+			ctx.ui.notify("--watch requires a local PDF path, for example: /studio --watch main.pdf", "error");
+			return;
+		}
+		const requestedLaunchMode: StudioUiMode = launchesPdfPreview ? "editor-only" : mode;
+		if (requestedLaunchMode === "full" && hasConnectedFullStudioView()) {
 			if (options?.replaceExistingFull) {
 				closeStudioClientsByMode("full", 4001, "Full Studio replaced");
 			} else {
@@ -16132,9 +16189,14 @@ export default function (pi: ExtensionAPI) {
 			// ignore theme read errors
 		}
 
-		const selected = resolveStudioLaunchDocument(launchArgs, ctx, options);
-		if (!selected) return;
-		initialStudioDocument = selected;
+		const selection = resolveStudioLaunchDocument(launchArgs, ctx, {
+			...options,
+			watchPdf: launchOpenFlags.watchPdf,
+		});
+		if (!selection) return;
+		const selected = selection.document;
+		const launchMode = selection.mode ?? requestedLaunchMode;
+		if (!selection.transient) initialStudioDocument = selected;
 
 		let state: StudioServerState;
 		try {
@@ -16145,10 +16207,16 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`Failed to start Studio server${portText}: ${message}`, "error");
 			return;
 		}
-		const url = buildStudioUrl(state.port, state.token, mode, selected);
+		const docId = selection.transient ? storeTransientStudioDocument(selected) : undefined;
+		const url = buildStudioUrl(state.port, state.token, launchMode, selected, docId, {
+			skipWorkspaceRestore: selection.skipWorkspaceRestore,
+			paneFocus: selection.paneFocus,
+		});
 		const tunnelHint = buildStudioSshTunnelHint(state.port, url)
 			?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(state.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
-		const openedLabel = mode === "editor-only" ? "pi Studio editor-only view" : "pi Studio";
+		const openedLabel = selection.kind === "pdf-preview"
+			? "pi Studio PDF preview"
+			: (launchMode === "editor-only" ? "pi Studio editor-only view" : "pi Studio");
 
 		const shouldOpenBrowser = shouldAutoOpenStudioBrowser({
 			openRemoteBrowser: launchOpenFlags.openRemoteBrowser,
@@ -16160,7 +16228,10 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify(`${openedLabel} is ready. Browser auto-open was skipped because ${skipReason}.`, "info");
 			} else {
 				await openStudioUrlInBrowser(url);
-				if (selected.source === "file") {
+				if (selection.kind === "pdf-preview") {
+					const watchLabel = launchOpenFlags.watchPdf ? " (auto-refresh on)" : "";
+					ctx.ui.notify(`Opened ${openedLabel}${watchLabel}: ${selection.resourcePath ?? selected.label}`, "info");
+				} else if (selected.source === "file") {
 					ctx.ui.notify(`Opened ${openedLabel} with file loaded: ${selected.label}`, "info");
 				} else if (selected.source === "last-response") {
 					ctx.ui.notify(`Opened ${openedLabel} with last model response (${selected.text.length} chars).`, "info");
@@ -16182,7 +16253,7 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	pi.registerCommand("studio", {
-		description: "Open pi Studio browser UI (/studio, /studio <file>, /studio --blank, /studio --last, /studio --no-browser, /studio --port <port>)",
+		description: "Open pi Studio browser UI or a PDF preview (/studio, /studio <file>, /studio --watch <pdf>, /studio --blank, /studio --last, /studio --no-browser)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 
@@ -16212,7 +16283,8 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify(
 					"Usage: /studio [path|--blank|--last]\n"
 						+ "  /studio           Open studio with last model response (fallback: blank)\n"
-						+ "  /studio <path>    Open studio with file preloaded\n"
+						+ "  /studio <path>    Open a text file in Studio, or a PDF in a read-only companion preview\n"
+						+ "  /studio --watch <pdf>  Open a PDF with auto-refresh enabled\n"
 						+ "  /studio --blank   Open with blank editor\n"
 						+ "  /studio --last    Open with last model response\n"
 						+ "  /studio --no-browser  Print the Studio URL without opening a browser\n"
@@ -16220,7 +16292,7 @@ export default function (pi: ExtensionAPI) {
 						+ "  /studio --open-remote  Over SSH, open the remote browser anyway\n"
 						+ "  /studio --status  Show studio status\n"
 						+ "  /studio --stop    Stop studio server\n"
-						+ "  Note: only one full /studio view is allowed per Pi session.\n"
+						+ "  Note: only one full /studio view is allowed per Pi session; PDF previews open as companions.\n"
 						+ "  /studio-replace [path]  Replace the current full Studio view with a new one\n"
 						+ "  /studio-editor-only [path]  Open another Studio tab in editor-only mode\n"
 						+ "  /studio-current <path>  Load a file into currently open Studio tab(s)\n"
@@ -16231,7 +16303,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			await openStudioView(trimmed, ctx, "full", { defaultSource: "last-response", commandLabel: "/studio" });
+			await openStudioView(trimmed, ctx, "full", { defaultSource: "last-response", commandLabel: "/studio", allowPdfPreview: true });
 		},
 	});
 
@@ -16263,14 +16335,15 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("studio-editor-only", {
-		description: "Open pi Studio in editor-only mode (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --no-browser)",
+		description: "Open pi Studio in editor-only mode or preview a PDF (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --watch <pdf>)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 			if (trimmed === "help" || trimmed === "--help" || trimmed === "-h") {
 				ctx.ui.notify(
 					"Usage: /studio-editor-only [path|--blank|--last]\n"
 						+ "  /studio-editor-only         Open an editor-only Studio view (default: blank editor)\n"
-						+ "  /studio-editor-only <path>  Open an editor-only Studio view with file preloaded\n"
+						+ "  /studio-editor-only <path>  Open a text file for editing, or a PDF in a read-only preview\n"
+						+ "  /studio-editor-only --watch <pdf>  Open a PDF with auto-refresh enabled\n"
 						+ "  /studio-editor-only --blank Open with blank editor\n"
 						+ "  /studio-editor-only --last  Open with last model response loaded into the editor\n"
 						+ "  /studio-editor-only --no-browser  Print URL without opening a browser\n"
@@ -16281,7 +16354,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			await openStudioView(trimmed, ctx, "editor-only", { defaultSource: "blank", commandLabel: "/studio-editor-only" });
+			await openStudioView(trimmed, ctx, "editor-only", { defaultSource: "blank", commandLabel: "/studio-editor-only", allowPdfPreview: true });
 		},
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.48",
+  "version": "0.9.50",
   "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-local-preview-path.js

@@ -0,0 +1,46 @@
+function parseStudioLocalPreviewPage(resourcePath) {
+	const raw = String(resourcePath || "");
+	const parts = [];
+	const queryIndex = raw.indexOf("?");
+	if (queryIndex >= 0) {
+		const queryEnd = raw.indexOf("#", queryIndex);
+		parts.push(raw.slice(queryIndex + 1, queryEnd >= 0 ? queryEnd : raw.length));
+	}
+	const hashIndex = raw.indexOf("#");
+	if (hashIndex >= 0) parts.push(raw.slice(hashIndex + 1));
+	for (const part of parts) {
+		try {
+			const params = new URLSearchParams(part);
+			const rawPage = params.get("page") || params.get("p");
+			if (rawPage) {
+				const page = Number.parseInt(rawPage, 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		} catch {
+			const match = part.match(/(?:^|[&;])page=(\d+)/i) || part.match(/^page=(\d+)$/i);
+			if (match && match[1]) {
+				const page = Number.parseInt(match[1], 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		}
+	}
+	return null;
+}
+
+function parseStudioPdfLaunchTarget(pathInput) {
+	const raw = String(pathInput || "").trim();
+	if (!raw || /\0/.test(raw) || /^\/\//.test(raw)) return null;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(raw) && !/^[a-z]:[\\/]/i.test(raw)) return null;
+
+	const match = raw.match(/^(.*?\.pdf)(?:(?:\?[^#]*)?(?:#.*)?)?$/i);
+	if (!match || !match[1]) return null;
+	return {
+		path: match[1],
+		page: parseStudioLocalPreviewPage(raw),
+	};
+}
+
+export {
+	parseStudioLocalPreviewPage,
+	parseStudioPdfLaunchTarget,
+};