pi-studio 0.9.47 → 0.9.49

package/index.ts

@@ -28,8 +28,10 @@ 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";
 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";
@@ -275,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 {
@@ -648,6 +665,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_IMPORT_FILE_MAX_BYTES = 10_000_000;
 const STUDIO_WORKSPACE_STATE_REQUEST_MAX_BYTES = 4_000_000;
 const RESPONSE_HISTORY_LIMIT = 30;
 const CMUX_NOTIFY_TIMEOUT_MS = 1200;
@@ -2947,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();
@@ -3020,7 +3009,7 @@ function resolveStudioLocalPreviewResourcePath(
 		label: rel && rel !== "" ? rel : basename(candidateReal),
 		extension,
 		kind: getStudioLocalPreviewResourceKind(extension, candidateReal),
-		page: parseStudioLocalPreviewResourcePage(rawPath),
+		page: parseStudioLocalPreviewPage(rawPath),
 		resourceDir: boundaryReal,
 	};
 }
@@ -6127,6 +6116,31 @@ function decorateStudioPandocSyntaxHtml(html: string): string {
 	);
 }
 
+function buildStudioLatexPandocCompatibilityWarning(omittedPackages: Array<{ name: string }>): string | undefined {
+	const packageNames = Array.from(new Set(
+		omittedPackages
+			.map((entry) => String(entry?.name ?? "").trim())
+			.filter(Boolean),
+	));
+	if (packageNames.length === 0) return undefined;
+	const packageLabel = packageNames
+		.map((name) => name.toLowerCase().endsWith(".sty") ? name : `${name}.sty`)
+		.join(", ");
+	const noun = packageNames.length === 1 ? "package" : "packages";
+	const subject = packageNames.length === 1 ? "it redefines" : "they redefine";
+	return `Studio omitted local LaTeX ${noun} ${packageLabel} from this Pandoc rendering because ${subject} document startup. Package-specific layout may be absent; compile the source directly with LaTeX for authoritative output.`;
+}
+
+function combineStudioWarnings(...warnings: Array<string | undefined>): string | undefined {
+	const messages = Array.from(new Set(warnings.map((warning) => String(warning ?? "").trim()).filter(Boolean)));
+	return messages.length > 0 ? messages.join(" ") : undefined;
+}
+
+function renderStudioLatexPandocCompatibilityWarningHtml(warning: string | undefined): string {
+	if (!warning) return "";
+	return `<div class="preview-warning studio-latex-compatibility-warning" role="note">${escapeStudioHtmlText(warning)}</div>`;
+}
+
 const resolveStudioPandocHtmlResourceFlag = createStudioPandocHtmlResourceFlagResolver(async (pandocCommand: string) => {
 	const result = await runStudioSubprocess(pandocCommand, ["--help"], {
 		timeoutMs: 5_000,
@@ -6150,8 +6164,15 @@ function preprocessStudioLatexFootnotemarksForPreview(latex: string): string {
 
 async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string, sourcePath?: string): Promise<string> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
-	const latexPreviewSource = isLatex ? preprocessStudioLatexFootnotemarksForPreview(markdown) : markdown;
-	const markdownWithNormalizedFences = isLatex ? latexPreviewSource : normalizeStudioMarkdownSmartFences(markdown);
+	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath)
+		?? resolveStudioPandocWorkingDir(sourcePath ? dirname(sourcePath) : undefined);
+	const latexPandocCompatibility = isLatex
+		? prepareStudioLatexForPandoc(markdown, pandocWorkingDir)
+		: { source: markdown, omittedPackages: [] as Array<{ name: string; path: string }> };
+	const latexPandocCompatibilityWarning = buildStudioLatexPandocCompatibilityWarning(latexPandocCompatibility.omittedPackages);
+	const pandocInputSource = latexPandocCompatibility.source;
+	const latexPreviewSource = isLatex ? preprocessStudioLatexFootnotemarksForPreview(pandocInputSource) : pandocInputSource;
+	const markdownWithNormalizedFences = isLatex ? latexPreviewSource : normalizeStudioMarkdownSmartFences(pandocInputSource);
 	const markdownWithoutHtmlComments = isLatex ? markdownWithNormalizedFences : stripStudioMarkdownHtmlCommentsPreservingYamlFrontMatter(markdownWithNormalizedFences);
 	const markdownWithPreviewPageBreaks = isLatex ? markdownWithoutHtmlComments : replaceStudioPreviewPageBreakCommands(markdownWithoutHtmlComments);
 	const latexSubfigurePreviewTransform = isLatex
@@ -6164,7 +6185,7 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 		? preprocessStudioLatexReferences(latexAlgorithmPreviewTransform.markdown, sourcePath, resourcePath)
 		: markdownWithPreviewPageBreaks;
 	const inputFormat = isLatex ? "latex" : "markdown+lists_without_preceding_blankline-blank_before_blockquote-blank_before_header+tex_math_dollars+tex_math_single_backslash+tex_math_double_backslash+autolink_bare_uris-raw_html";
-	const bibliographyArgs = buildStudioPandocBibliographyArgs(markdown, isLatex, resourcePath);
+	const bibliographyArgs = buildStudioPandocBibliographyArgs(pandocInputSource, isLatex, resourcePath);
 	const args = ["-f", inputFormat, "-t", "html5", "--mathml", "--wrap=none", ...bibliographyArgs];
 	let htmlTemplateDir: string | null = null;
 	const useStudioHtmlTemplate = Boolean(resourcePath || isLatex);
@@ -6185,7 +6206,6 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 	const normalizedMarkdown = isLatex
 		? sourceWithResolvedRefs
 		: normalizeStudioMarkdownFencedBlocks(prepareStudioMarkdownForPandoc(sourceWithResolvedRefs));
-	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath);
 
 	let pandocResult: StudioSubprocessResult;
 	try {
@@ -6230,6 +6250,7 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 		renderedHtml = decorateStudioPreviewPageBreakHtml(renderedHtml);
 	}
 	renderedHtml = decorateStudioPandocSyntaxHtml(renderedHtml);
+	renderedHtml = renderStudioLatexPandocCompatibilityWarningHtml(latexPandocCompatibilityWarning) + renderedHtml;
 	return stripMathMlAnnotationTags(renderedHtml);
 }
 
@@ -6616,8 +6637,15 @@ async function renderStudioStandaloneHtmlWithPandoc(
 	sourcePath?: string,
 	options?: StudioHtmlRenderOptions,
 ): Promise<{ html: Buffer; warning?: string }> {
-	const delimitedMarkdown = isLatex ? null : formatStudioDelimitedTextAsMarkdown(markdown, editorLanguage);
-	const input = delimitedMarkdown ?? markdown;
+	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath)
+		?? resolveStudioPandocWorkingDir(sourcePath ? dirname(sourcePath) : undefined);
+	const latexPandocCompatibility = isLatex
+		? prepareStudioLatexForPandoc(markdown, pandocWorkingDir)
+		: { source: markdown, omittedPackages: [] as Array<{ name: string; path: string }> };
+	const latexPandocCompatibilityWarning = buildStudioLatexPandocCompatibilityWarning(latexPandocCompatibility.omittedPackages);
+	const pandocCompatibleMarkdown = latexPandocCompatibility.source;
+	const delimitedMarkdown = isLatex ? null : formatStudioDelimitedTextAsMarkdown(pandocCompatibleMarkdown, editorLanguage);
+	const input = delimitedMarkdown ?? pandocCompatibleMarkdown;
 	const effectiveEditorLanguage = delimitedMarkdown ? "markdown" : inferStudioPdfLanguage(input, editorLanguage);
 	if (!isLatex && isLikelyStandaloneStudioHtml(input, effectiveEditorLanguage)) {
 		return { html: Buffer.from(String(input ?? ""), "utf-8") };
@@ -6634,8 +6662,12 @@ async function renderStudioStandaloneHtmlWithPandoc(
 	let renderedHtml = await renderStudioMarkdownWithPandoc(pdfPrepared.markdown, isLatex, resourcePath, sourcePath);
 	renderedHtml = renderStudioPdfBlocksInHtml(renderedHtml, pdfPrepared.blocks, sourcePath, resourcePath);
 	renderedHtml = applyStudioAnnotationPlaceholdersToHtml(renderedHtml, annotationPrepared.placeholders);
+	renderedHtml = renderStudioLatexPandocCompatibilityWarningHtml(latexPandocCompatibilityWarning) + renderedHtml;
 	const standaloneHtml = buildStudioStandaloneHtmlDocument(renderedHtml, resourcePath, options);
-	return { html: Buffer.from(standaloneHtml, "utf-8") };
+	return {
+		html: Buffer.from(standaloneHtml, "utf-8"),
+		warning: latexPandocCompatibilityWarning,
+	};
 }
 
 async function renderStudioLiteralTextPdf(text: string, title = "Studio export", options?: StudioPdfRenderOptions): Promise<Buffer> {
@@ -7024,19 +7056,26 @@ async function renderStudioPdfWithPandoc(
 ): Promise<{ pdf: Buffer; warning?: string }> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
 	const pdfEngine = process.env.PANDOC_PDF_ENGINE?.trim() || "xelatex";
+	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath)
+		?? resolveStudioPandocWorkingDir(sourcePath ? dirname(sourcePath) : undefined);
+	const latexPandocCompatibility = isLatex
+		? prepareStudioLatexForPandoc(markdown, pandocWorkingDir)
+		: { source: markdown, omittedPackages: [] as Array<{ name: string; path: string }> };
+	const latexPandocCompatibilityWarning = buildStudioLatexPandocCompatibilityWarning(latexPandocCompatibility.omittedPackages);
+	const pandocInputSource = latexPandocCompatibility.source;
 	const latexSubfigurePdfTransform = isLatex
-		? preprocessStudioLatexSubfiguresForPdf(markdown)
-		: { markdown, groups: [] };
+		? preprocessStudioLatexSubfiguresForPdf(pandocInputSource)
+		: { markdown: pandocInputSource, groups: [] };
 	const latexPdfSource = isLatex
 		? preprocessStudioLatexAlgorithmsForPdf(
 			latexSubfigurePdfTransform.markdown,
 			sourcePath,
 			resourcePath,
 		)
-		: markdown;
+		: pandocInputSource;
 	const sourceWithResolvedRefs = isLatex
 		? injectStudioLatexEquationTags(preprocessStudioLatexReferences(latexPdfSource, sourcePath, resourcePath), sourcePath, resourcePath)
-		: markdown;
+		: pandocInputSource;
 	const effectiveEditorLanguage = inferStudioPdfLanguage(sourceWithResolvedRefs, editorPdfLanguage);
 	const pdfCalloutTransform = !isLatex && (!effectiveEditorLanguage || effectiveEditorLanguage === "markdown")
 		? preprocessStudioMarkdownCalloutsForPdf(sourceWithResolvedRefs)
@@ -7044,8 +7083,7 @@ async function renderStudioPdfWithPandoc(
 	const pdfAlignedImageTransform = !isLatex && (!effectiveEditorLanguage || effectiveEditorLanguage === "markdown")
 		? preprocessStudioMarkdownImageAlignmentForPdf(pdfCalloutTransform.markdown)
 		: { markdown: pdfCalloutTransform.markdown, blocks: [] as StudioPdfAlignedImageBlock[] };
-	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath);
-	const bibliographyArgs = buildStudioPandocBibliographyArgs(markdown, isLatex, resourcePath);
+	const bibliographyArgs = buildStudioPandocBibliographyArgs(pandocInputSource, isLatex, resourcePath);
 
 	const runPandocPdfExport = async (
 		inputFormat: string,
@@ -7098,7 +7136,7 @@ async function renderStudioPdfWithPandoc(
 	};
 
 	if (isLatex && (latexSubfigurePdfTransform.groups.length > 0 || collectStudioInlineAnnotationMarkers(sourceWithResolvedRefs).length > 0)) {
-		return await renderStudioPdfFromGeneratedLatex(
+		const rendered = await renderStudioPdfFromGeneratedLatex(
 			sourceWithResolvedRefs,
 			pandocCommand,
 			pdfEngine,
@@ -7114,6 +7152,10 @@ async function renderStudioPdfWithPandoc(
 			"",
 			themeStyle,
 		);
+		return {
+			pdf: rendered.pdf,
+			warning: combineStudioWarnings(latexPandocCompatibilityWarning, rendered.warning),
+		};
 	}
 
 	if (!isLatex && effectiveEditorLanguage === "diff") {
@@ -7187,7 +7229,10 @@ async function renderStudioPdfWithPandoc(
 			themeStyle,
 		);
 		await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
-		return { pdf: rendered.pdf, warning: mermaidPrepared.warning ?? rendered.warning };
+		return {
+			pdf: rendered.pdf,
+			warning: combineStudioWarnings(latexPandocCompatibilityWarning, mermaidPrepared.warning, rendered.warning),
+		};
 	}
 
 	const hasYamlHeaderIncludesForPdf = !isLatex && hasStudioYamlHeaderIncludes(markdownForPdf);
@@ -7222,7 +7267,10 @@ async function renderStudioPdfWithPandoc(
 			throw new Error(`pandoc PDF export failed with exit code ${pandocResult.code}${stderr ? `: ${stderr}` : ""}${hint}`);
 		}
 
-		return { pdf: await readFile(outputPath), warning: mermaidPrepared.warning };
+		return {
+			pdf: await readFile(outputPath),
+			warning: combineStudioWarnings(latexPandocCompatibilityWarning, mermaidPrepared.warning),
+		};
 	} finally {
 		await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
 	}
@@ -7308,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 {
@@ -7345,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);
@@ -7354,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") {
@@ -7532,6 +7597,64 @@ function revealStudioLocalFile(filePath: string): { ok: true; message: string }
 	return { ok: true, message: process.platform === "linux" ? "Opened containing folder." : "Revealed resource in file manager." };
 }
 
+async function handleImportStudioFileCopyRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "POST") {
+		res.setHeader("Allow", "POST");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+		return;
+	}
+
+	const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+	let payload: Record<string, unknown> = {};
+	try {
+		payload = rawBody ? JSON.parse(rawBody) : {};
+	} catch {
+		respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+		return;
+	}
+
+	const requestedPath = typeof payload.path === "string" ? payload.path : "";
+	const resolved = resolveStudioPath(requestedPath, studioCwd);
+	if (resolved.ok === false) {
+		respondJson(res, 400, { ok: false, error: resolved.message });
+		return;
+	}
+
+	try {
+		const stats = statSync(resolved.resolved);
+		if (!stats.isFile()) {
+			respondJson(res, 400, { ok: false, error: `Path is not a file: ${resolved.label}` });
+			return;
+		}
+		if (stats.size > STUDIO_IMPORT_FILE_MAX_BYTES) {
+			respondJson(res, 413, {
+				ok: false,
+				error: `File is too large to import into Studio (${stats.size} bytes; limit ${STUDIO_IMPORT_FILE_MAX_BYTES} bytes).`,
+			});
+			return;
+		}
+	} catch (error) {
+		respondJson(res, 404, {
+			ok: false,
+			error: `Could not access file: ${resolved.label} (${error instanceof Error ? error.message : String(error)})`,
+		});
+		return;
+	}
+
+	const file = readStudioFile(resolved.resolved, studioCwd);
+	if (file.ok === false) {
+		respondJson(res, 400, { ok: false, error: file.message });
+		return;
+	}
+	respondJson(res, 200, {
+		ok: true,
+		text: file.text,
+		filename: basename(file.resolvedPath),
+		resolvedPath: file.resolvedPath,
+	});
+}
+
 async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
@@ -7567,6 +7690,50 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 	}
 }
 
+async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "POST") {
+		res.setHeader("Allow", "POST");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+		return;
+	}
+	if (isSshSession()) {
+		respondJson(res, 409, { ok: false, error: "Cannot open a system PDF viewer from an SSH/headless Studio session. Copy the path instead." });
+		return;
+	}
+
+	const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+	let payload: Record<string, unknown> = {};
+	try {
+		payload = rawBody ? JSON.parse(rawBody) : {};
+	} catch {
+		respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+		return;
+	}
+
+	try {
+		const resource = resolveStudioLocalPreviewResourcePath(
+			typeof payload.path === "string" ? payload.path : "",
+			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
+			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
+			studioCwd,
+		);
+		if (resource.kind !== "pdf") {
+			respondJson(res, 400, { ok: false, error: "Only local PDF previews can be opened in the system PDF viewer." });
+			return;
+		}
+		await openPathInDefaultViewer(resource.filePath);
+		respondJson(res, 200, {
+			ok: true,
+			message: "Opened PDF in the system viewer.",
+			path: resource.filePath,
+			label: resource.label,
+		});
+	} catch (error) {
+		respondJson(res, 404, { ok: false, error: `Local PDF unavailable: ${error instanceof Error ? error.message : String(error)}` });
+	}
+}
+
 function openPathInDefaultViewer(path: string): Promise<void> {
 	const openCommand =
 		process.platform === "darwin"
@@ -10120,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);
@@ -10131,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()}`;
 }
 
@@ -10140,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)}`;
 }
@@ -10149,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]!;
@@ -10170,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;
@@ -10185,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 {
@@ -10589,7 +10763,8 @@ ${cssVarsBlock}
       <button id="saveOverBtn" type="button" title="Overwrite current file with editor content. Shortcut: Cmd/Ctrl+S.">Save editor</button>
       <button id="refreshFromDiskBtn" type="button" title="Reload the current file-backed document from disk.">Refresh from disk</button>
       <button id="clearWorkspaceBtn" type="button" title="Clear editor text and reset this tab to a fresh blank draft. Saved files and responses are not changed.">Reset editor</button>
-      <label class="file-label" title="Browser import: load a selected text file as a detached copy. Use Save editor as… to attach this copy to a file path and make it file-backed, or use the Files view to open a refreshable file-backed document directly.">Import file copy…<input id="fileInput" type="file" 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" /></label>
+      <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>
     </div>
@@ -10918,6 +11093,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">
@@ -14909,6 +15085,19 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/import-file-copy") {
+			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 handleImportStudioFileCopyRequest(req, res, studioCwd).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `File import failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/local-preview-link") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -14945,6 +15134,19 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/open-local-resource") {
+			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 handleOpenLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Open in system viewer failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/pdf-resource") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -15554,10 +15756,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())
@@ -15566,51 +15769,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("-")) {
@@ -15624,6 +15827,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");
@@ -15637,13 +15870,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 => {
@@ -15900,7 +16133,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) {
@@ -15911,7 +16144,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 {
@@ -15942,9 +16185,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 {
@@ -15955,10 +16203,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,
@@ -15970,7 +16224,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");
@@ -15992,7 +16249,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();
 
@@ -16022,7 +16279,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"
@@ -16030,7 +16288,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"
@@ -16041,7 +16299,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 });
 		},
 	});
 
@@ -16073,14 +16331,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"
@@ -16091,7 +16350,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 });
 		},
 	});