pi-studio 0.5.20 → 0.5.21

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.5.21] — 2026-03-19
+
+### Fixed
+- PDF export now uses a two-step prepare/download flow and opens the generated PDF in the system’s default viewer first, so browser surfaces like cmux do not need to navigate away from the current Studio page.
+- LaTeX preview and PDF export now use the document `.aux` file when available to substitute basic `\eqref{...}`, `\ref{...}`, and `\autoref{...}` values more reliably, and preview decorates block equations with their resolved equation numbers.
+- Upload + working-directory LaTeX workflows now derive the effective source path more reliably, helping Studio find the correct `.aux` file for reference resolution.
+
 ## [0.5.20] — 2026-03-19
 
 ### Fixed

package/client/studio-client.js

@@ -1351,6 +1351,8 @@
 
         let response;
         try {
+          const effectivePath = getEffectiveSavePath();
+          const sourcePath = effectivePath || sourceState.path || "";
           response = await fetch("/render-preview?token=" + encodeURIComponent(token), {
             method: "POST",
             headers: {
@@ -1358,8 +1360,8 @@
             },
             body: JSON.stringify({
               markdown: String(markdown || ""),
-              sourcePath: sourceState.path || "",
-              resourceDir: (!sourceState.path && resourceDirInput) ? resourceDirInput.value.trim() : "",
+              sourcePath: sourcePath,
+              resourceDir: (!sourcePath && resourceDirInput) ? resourceDirInput.value.trim() : "",
             }),
             signal: controller ? controller.signal : undefined,
           });
@@ -1444,16 +1446,17 @@
           return;
         }
 
-        const sourcePath = sourceState.path || "";
-        const resourceDir = (!sourceState.path && resourceDirInput) ? resourceDirInput.value.trim() : "";
+        const effectivePath = getEffectiveSavePath();
+        const sourcePath = effectivePath || sourceState.path || "";
+        const resourceDir = (!sourcePath && resourceDirInput) ? resourceDirInput.value.trim() : "";
         const isEditorPreview = rightView === "editor-preview";
         const editorPdfLanguage = isEditorPreview ? normalizeFenceLanguage(editorLanguage || "") : "";
         const isLatex = isEditorPreview
           ? editorPdfLanguage === "latex"
           : /\\documentclass\b|\\begin\{document\}/.test(markdown);
         let filenameHint = isEditorPreview ? "studio-editor-preview.pdf" : "studio-response-preview.pdf";
-        if (sourceState.path) {
-          const baseName = sourceState.path.split(/[\\/]/).pop() || "studio";
+        if (sourcePath) {
+          const baseName = sourcePath.split(/[\\/]/).pop() || "studio";
           const stem = baseName.replace(/\.[^.]+$/, "") || "studio";
           filenameHint = stem + "-preview.pdf";
         }
@@ -1478,8 +1481,8 @@
             }),
           });
 
+          const contentType = String(response.headers.get("content-type") || "").toLowerCase();
           if (!response.ok) {
-            const contentType = String(response.headers.get("content-type") || "").toLowerCase();
             let message = "PDF export failed with HTTP " + response.status + ".";
             if (contentType.includes("application/json")) {
               const payload = await response.json().catch(() => null);
@@ -1495,6 +1498,53 @@
             throw new Error(message);
           }
 
+          if (contentType.includes("application/json")) {
+            const payload = await response.json().catch(() => null);
+            if (!payload || typeof payload.downloadUrl !== "string") {
+              throw new Error("PDF export prepared successfully, but Studio did not receive a download URL.");
+            }
+
+            const exportWarning = typeof payload.warning === "string" ? payload.warning.trim() : "";
+            const openError = typeof payload.openError === "string" ? payload.openError.trim() : "";
+            const openedExternal = payload.openedExternal === true;
+            let downloadName = typeof payload.filename === "string" && payload.filename.trim()
+              ? payload.filename.trim()
+              : (filenameHint || "studio-preview.pdf");
+            if (!/\.pdf$/i.test(downloadName)) {
+              downloadName += ".pdf";
+            }
+
+            if (openedExternal) {
+              if (exportWarning) {
+                setStatus("Opened PDF in default viewer with warning: " + exportWarning, "warning");
+              } else {
+                setStatus("Opened PDF in default viewer: " + downloadName, "success");
+              }
+              return;
+            }
+
+            const link = document.createElement("a");
+            link.href = payload.downloadUrl;
+            link.download = downloadName;
+            link.rel = "noopener";
+            document.body.appendChild(link);
+            link.click();
+            link.remove();
+
+            if (openError) {
+              if (exportWarning) {
+                setStatus("Opened browser fallback because external viewer failed (" + openError + "). Warning: " + exportWarning, "warning");
+              } else {
+                setStatus("Opened browser fallback because external viewer failed (" + openError + ").", "warning");
+              }
+            } else if (exportWarning) {
+              setStatus("Exported PDF with warning: " + exportWarning, "warning");
+            } else {
+              setStatus("Exported PDF: " + downloadName, "success");
+            }
+            return;
+          }
+
           const exportWarning = String(response.headers.get("x-pi-studio-export-warning") || "").trim();
           const blob = await response.blob();
           const headerFilename = parseContentDispositionFilename(response.headers.get("content-disposition"));
@@ -4030,7 +4080,7 @@
           const text = typeof reader.result === "string" ? reader.result : "";
           setEditorText(text, { preserveScroll: false, preserveSelection: false });
           setSourceState({
-            source: "blank",
+            source: "upload",
             label: "upload: " + file.name,
             path: null,
           });

package/client/studio.css

@@ -762,6 +762,33 @@
       font-family: "STIX Two Math", "Cambria Math", "Latin Modern Math", "STIXGeneral", serif;
     }
 
+    .rendered-markdown .studio-display-equation {
+      position: relative;
+      margin: 1em 0;
+    }
+
+    .rendered-markdown .studio-display-equation-body {
+      padding-right: 4.5em;
+      overflow-x: auto;
+      overflow-y: hidden;
+    }
+
+    .rendered-markdown .studio-display-equation-body math[display="block"] {
+      margin: 0;
+    }
+
+    .rendered-markdown .studio-display-equation-number {
+      position: absolute;
+      top: 50%;
+      right: 0;
+      transform: translateY(-50%);
+      color: var(--muted);
+      font-size: 0.95em;
+      line-height: 1;
+      white-space: nowrap;
+      font-variant-numeric: tabular-nums;
+    }
+
     .rendered-markdown math[display="block"] {
       display: block;
       margin: 1em 0;

package/index.ts

@@ -56,6 +56,15 @@ interface StudioContextUsageSnapshot {
 	percent: number | null;
 }
 
+interface PreparedStudioPdfExport {
+	pdf: Buffer;
+	filename: string;
+	warning?: string;
+	createdAt: number;
+	filePath?: string;
+	tempDirPath?: string;
+}
+
 interface InitialStudioDocument {
 	text: string;
 	label: string;
@@ -158,6 +167,8 @@ const REQUEST_BODY_MAX_BYTES = 1_000_000;
 const RESPONSE_HISTORY_LIMIT = 30;
 const UPDATE_CHECK_TIMEOUT_MS = 1800;
 const CMUX_NOTIFY_TIMEOUT_MS = 1200;
+const PREPARED_PDF_EXPORT_TTL_MS = 5 * 60 * 1000;
+const MAX_PREPARED_PDF_EXPORTS = 8;
 const STUDIO_TERMINAL_NOTIFY_TITLE = "pi Studio";
 const CMUX_STUDIO_STATUS_KEY = "pi_studio";
 const CMUX_STUDIO_STATUS_COLOR_DARK = "#5ea1ff";
@@ -1099,6 +1110,160 @@ function buildStudioPandocBibliographyArgs(markdown: string, isLatex: boolean |
 	];
 }
 
+function parseStudioAuxTopLevelGroups(input: string): string[] {
+	const groups: string[] = [];
+	let i = 0;
+	while (i < input.length) {
+		while (i < input.length && /\s/.test(input[i]!)) i++;
+		if (i >= input.length) break;
+		if (input[i] !== "{") break;
+		i++;
+		let depth = 1;
+		let current = "";
+		while (i < input.length && depth > 0) {
+			const ch = input[i]!;
+			i++;
+			if (ch === "{") {
+				depth++;
+				current += ch;
+				continue;
+			}
+			if (ch === "}") {
+				depth--;
+				if (depth > 0) current += ch;
+				continue;
+			}
+			current += ch;
+		}
+		groups.push(current);
+	}
+	return groups;
+}
+
+function resolveStudioLatexAuxPath(sourcePath: string | undefined, baseDir: string | undefined): string | undefined {
+	const source = typeof sourcePath === "string" ? sourcePath.trim() : "";
+	const workingDir = resolveStudioPandocWorkingDir(baseDir);
+	if (!source) return undefined;
+	const expanded = expandHome(source);
+	const resolvedSource = isAbsolute(expanded)
+		? expanded
+		: resolve(workingDir || process.cwd(), expanded);
+
+	if (!/\.(tex|latex)$/i.test(resolvedSource)) return undefined;
+	const auxPath = resolvedSource.replace(/\.[^.]+$/i, ".aux");
+	try {
+		return statSync(auxPath).isFile() ? auxPath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function readStudioLatexAuxLabels(sourcePath: string | undefined, baseDir: string | undefined): Map<string, { number: string; kind: string }> {
+	const auxPath = resolveStudioLatexAuxPath(sourcePath, baseDir);
+	const labels = new Map<string, { number: string; kind: string }>();
+	if (!auxPath) return labels;
+
+	let text = "";
+	try {
+		text = readFileSync(auxPath, "utf-8");
+	} catch {
+		return labels;
+	}
+
+	for (const line of text.split(/\r?\n/)) {
+		const match = line.match(/^\\newlabel\{([^}]+)\}\{(.*)\}$/);
+		if (!match) continue;
+		const label = match[1] ?? "";
+		if (!label || label.endsWith("@cref")) continue;
+		const groups = parseStudioAuxTopLevelGroups(match[2] ?? "");
+		if (groups.length === 0) continue;
+		const number = String(groups[0] ?? "").trim();
+		if (!number) continue;
+		const rawKind = String(groups[3] ?? "").trim();
+		const kind = rawKind.split(".")[0] || (label.startsWith("eq:") ? "equation" : label.startsWith("fig:") ? "figure" : "ref");
+		labels.set(label, { number, kind });
+	}
+
+	return labels;
+}
+
+function formatStudioLatexReference(label: string, referenceType: "eqref" | "ref" | "autoref", labels: Map<string, { number: string; kind: string }>): string | null {
+	const entry = labels.get(label);
+	if (!entry) return null;
+	if (referenceType === "eqref") return `(${entry.number})`;
+	if (referenceType === "autoref") {
+		if (entry.kind === "equation") return `Equation ${entry.number}`;
+		if (entry.kind === "figure") return `Figure ${entry.number}`;
+		if (entry.kind === "section" || entry.kind === "subsection" || entry.kind === "subsubsection") return `Section ${entry.number}`;
+		if (entry.kind === "algorithm") return `Algorithm ${entry.number}`;
+	}
+	return entry.number;
+}
+
+function preprocessStudioLatexReferences(markdown: string, sourcePath: string | undefined, baseDir: string | undefined): string {
+	const labels = readStudioLatexAuxLabels(sourcePath, baseDir);
+	if (labels.size === 0) return markdown;
+	let transformed = String(markdown ?? "");
+	transformed = transformed.replace(/\\eqref\s*\{([^}]+)\}/g, (match, label) => formatStudioLatexReference(String(label || "").trim(), "eqref", labels) ?? match);
+	transformed = transformed.replace(/\\autoref\s*\{([^}]+)\}/g, (match, label) => formatStudioLatexReference(String(label || "").trim(), "autoref", labels) ?? match);
+	transformed = transformed.replace(/\\ref\s*\{([^}]+)\}/g, (match, label) => formatStudioLatexReference(String(label || "").trim(), "ref", labels) ?? match);
+	return transformed;
+}
+
+function escapeStudioHtmlText(text: string): string {
+	return String(text ?? "")
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}
+
+function decorateStudioLatexRenderedHtml(html: string, sourcePath: string | undefined, baseDir: string | undefined): string {
+	const labels = readStudioLatexAuxLabels(sourcePath, baseDir);
+	if (labels.size === 0) return html;
+	let transformed = String(html ?? "");
+
+	transformed = transformed.replace(/<a\b([^>]*)>([\s\S]*?)<\/a>/g, (match, attrs) => {
+		const typeMatch = String(attrs ?? "").match(/\bdata-reference-type="([^"]+)"/);
+		const labelMatch = String(attrs ?? "").match(/\bdata-reference="([^"]+)"/);
+		if (!typeMatch || !labelMatch) return match;
+		const referenceTypeRaw = String(typeMatch[1] ?? "").trim();
+		const label = String(labelMatch[1] ?? "").trim();
+		const referenceType =
+			referenceTypeRaw === "eqref" || referenceTypeRaw === "autoref" || referenceTypeRaw === "ref"
+				? referenceTypeRaw
+				: null;
+		if (!referenceType || !label) return match;
+		const formatted = formatStudioLatexReference(label, referenceType, labels);
+		if (!formatted) return match;
+		return `<a${attrs}>${escapeStudioHtmlText(formatted)}</a>`;
+	});
+
+	transformed = transformed.replace(/<math\b[^>]*display="block"[^>]*>[\s\S]*?<\/math>/g, (block) => {
+		if (/studio-display-equation/.test(block)) return block;
+		const labelMatch = block.match(/\\label\s*\{([^}]+)\}/);
+		if (!labelMatch) return block;
+		const label = String(labelMatch[1] ?? "").trim();
+		if (!label) return block;
+		const formatted = formatStudioLatexReference(label, "eqref", labels);
+		if (!formatted) return block;
+		return `<div class="studio-display-equation"><div class="studio-display-equation-body">${block}</div><div class="studio-display-equation-number">${escapeStudioHtmlText(formatted)}</div></div>`;
+	});
+
+	return transformed;
+}
+
+function injectStudioLatexEquationTags(markdown: string, sourcePath: string | undefined, baseDir: string | undefined): string {
+	const labels = readStudioLatexAuxLabels(sourcePath, baseDir);
+	if (labels.size === 0) return markdown;
+	return String(markdown ?? "").replace(/\\label\s*\{([^}]+)\}/g, (match, label) => {
+		const entry = labels.get(String(label || "").trim());
+		if (!entry || entry.kind !== "equation") return match;
+		return `\\tag{${entry.number}}\\label{${String(label || "").trim()}}`;
+	});
+}
+
 function readStudioGitDiff(baseDir: string):
 	| { ok: true; text: string; label: string }
 	| { ok: false; level: "info" | "warning" | "error"; message: string } {
@@ -1681,17 +1846,18 @@ async function preprocessStudioMermaidForPdf(markdown: string, workDir: string):
 	};
 }
 
-async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string): Promise<string> {
+async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string, sourcePath?: string): Promise<string> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
+	const sourceWithResolvedRefs = isLatex ? preprocessStudioLatexReferences(markdown, sourcePath, resourcePath) : markdown;
 	const inputFormat = isLatex ? "latex" : "markdown+lists_without_preceding_blankline+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(sourceWithResolvedRefs, isLatex, resourcePath);
 	const args = ["-f", inputFormat, "-t", "html5", "--mathml", "--wrap=none", ...bibliographyArgs];
 	if (resourcePath) {
 		args.push(`--resource-path=${resourcePath}`);
 		// Embed images as data URIs so they render in the browser preview
 		args.push("--embed-resources", "--standalone");
 	}
-	const normalizedMarkdown = isLatex ? markdown : normalizeObsidianImages(normalizeMathDelimiters(markdown));
+	const normalizedMarkdown = isLatex ? sourceWithResolvedRefs : normalizeObsidianImages(normalizeMathDelimiters(sourceWithResolvedRefs));
 	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath);
 
 	return await new Promise<string>((resolve, reject) => {
@@ -1737,6 +1903,9 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 					const bodyMatch = renderedHtml.match(/<body[^>]*>([\s\S]*)<\/body>/i);
 					if (bodyMatch) renderedHtml = bodyMatch[1];
 				}
+				if (isLatex) {
+					renderedHtml = decorateStudioLatexRenderedHtml(renderedHtml, sourcePath, resourcePath);
+				}
 				succeed(stripMathMlAnnotationTags(renderedHtml));
 				return;
 			}
@@ -1832,12 +2001,16 @@ async function renderStudioPdfWithPandoc(
 	isLatex?: boolean,
 	resourcePath?: string,
 	editorPdfLanguage?: string,
+	sourcePath?: string,
 ): Promise<{ pdf: Buffer; warning?: string }> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
 	const pdfEngine = process.env.PANDOC_PDF_ENGINE?.trim() || "xelatex";
-	const effectiveEditorLanguage = inferStudioPdfLanguage(markdown, editorPdfLanguage);
+	const sourceWithResolvedRefs = isLatex
+		? injectStudioLatexEquationTags(preprocessStudioLatexReferences(markdown, sourcePath, resourcePath), sourcePath, resourcePath)
+		: markdown;
+	const effectiveEditorLanguage = inferStudioPdfLanguage(sourceWithResolvedRefs, editorPdfLanguage);
 	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath);
-	const bibliographyArgs = buildStudioPandocBibliographyArgs(markdown, isLatex, resourcePath);
+	const bibliographyArgs = buildStudioPandocBibliographyArgs(sourceWithResolvedRefs, isLatex, resourcePath);
 
 	const runPandocPdfExport = async (
 		inputFormat: string,
@@ -1934,7 +2107,7 @@ async function renderStudioPdfWithPandoc(
 	const inputFormat = isLatex
 		? "latex"
 		: "markdown+lists_without_preceding_blankline+tex_math_dollars+tex_math_single_backslash+tex_math_double_backslash+autolink_bare_uris+superscript+subscript-raw_html";
-	const normalizedMarkdown = prepareStudioPdfMarkdown(markdown, isLatex, effectiveEditorLanguage);
+	const normalizedMarkdown = prepareStudioPdfMarkdown(sourceWithResolvedRefs, isLatex, effectiveEditorLanguage);
 
 	const tempDir = join(tmpdir(), `pi-studio-pdf-${Date.now()}-${randomUUID()}`);
 	const preamblePath = join(tempDir, "_pdf_preamble.tex");
@@ -2095,6 +2268,27 @@ function openUrlInDefaultBrowser(url: string): Promise<void> {
 	});
 }
 
+function openPathInDefaultViewer(path: string): Promise<void> {
+	const openCommand =
+		process.platform === "darwin"
+			? { command: "open", args: [path] }
+			: process.platform === "win32"
+				? { command: "cmd", args: ["/c", "start", "", path] }
+				: { command: "xdg-open", args: [path] };
+
+	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 detectLensFromText(text: string): Lens {
 	const lines = text.split("\n");
 	const fencedCodeBlocks = (text.match(/```[\w-]*\n[\s\S]*?```/g) ?? []).length;
@@ -3044,6 +3238,7 @@ export default function (pi: ExtensionAPI) {
 	let serverState: StudioServerState | null = null;
 	let activeRequest: ActiveStudioRequest | null = null;
 	let lastStudioResponse: LastStudioResponse | null = null;
+	let preparedPdfExports = new Map<string, PreparedStudioPdfExport>();
 	let initialStudioDocument: InitialStudioDocument | null = null;
 	let studioCwd = process.cwd();
 	let lastCommandCtx: ExtensionCommandContext | null = null;
@@ -4105,6 +4300,100 @@ export default function (pi: ExtensionAPI) {
 		}
 	};
 
+	const disposePreparedPdfExport = (entry: PreparedStudioPdfExport | null | undefined) => {
+		if (!entry?.tempDirPath) return;
+		void rm(entry.tempDirPath, { recursive: true, force: true }).catch(() => undefined);
+	};
+
+	const clearPreparedPdfExports = () => {
+		for (const entry of preparedPdfExports.values()) {
+			disposePreparedPdfExport(entry);
+		}
+		preparedPdfExports.clear();
+	};
+
+	const prunePreparedPdfExports = () => {
+		const now = Date.now();
+		for (const [id, entry] of preparedPdfExports) {
+			if (entry.createdAt + PREPARED_PDF_EXPORT_TTL_MS <= now) {
+				preparedPdfExports.delete(id);
+				disposePreparedPdfExport(entry);
+			}
+		}
+		while (preparedPdfExports.size > MAX_PREPARED_PDF_EXPORTS) {
+			const oldestKey = preparedPdfExports.keys().next().value;
+			if (!oldestKey) break;
+			const oldestEntry = preparedPdfExports.get(oldestKey);
+			preparedPdfExports.delete(oldestKey);
+			disposePreparedPdfExport(oldestEntry);
+		}
+	};
+
+	const storePreparedPdfExport = (pdf: Buffer, filename: string, warning?: string): string => {
+		prunePreparedPdfExports();
+		const exportId = randomUUID();
+		preparedPdfExports.set(exportId, {
+			pdf,
+			filename,
+			warning,
+			createdAt: Date.now(),
+		});
+		return exportId;
+	};
+
+	const ensurePreparedPdfExportFile = async (exportId: string): Promise<PreparedStudioPdfExport | null> => {
+		prunePreparedPdfExports();
+		const entry = preparedPdfExports.get(exportId);
+		if (!entry) return null;
+		if (entry.filePath && entry.tempDirPath) return entry;
+
+		const tempDirPath = join(tmpdir(), `pi-studio-prepared-pdf-${Date.now()}-${randomUUID()}`);
+		const filePath = join(tempDirPath, sanitizePdfFilename(entry.filename));
+		await mkdir(tempDirPath, { recursive: true });
+		await writeFile(filePath, entry.pdf);
+		entry.tempDirPath = tempDirPath;
+		entry.filePath = filePath;
+		preparedPdfExports.set(exportId, entry);
+		return entry;
+	};
+
+	const getPreparedPdfExport = (exportId: string): PreparedStudioPdfExport | null => {
+		prunePreparedPdfExports();
+		return preparedPdfExports.get(exportId) ?? null;
+	};
+
+	const handlePreparedPdfDownloadRequest = (requestUrl: URL, res: ServerResponse) => {
+		const exportId = requestUrl.searchParams.get("id") ?? "";
+		if (!exportId) {
+			respondText(res, 400, "Missing PDF export id.");
+			return;
+		}
+
+		const prepared = getPreparedPdfExport(exportId);
+		if (!prepared) {
+			respondText(res, 404, "PDF export is no longer available. Re-export the document.");
+			return;
+		}
+
+		const safeAsciiName = prepared.filename
+			.replace(/[\x00-\x1f\x7f]/g, "")
+			.replace(/[;"\\]/g, "_")
+			.replace(/\s+/g, " ")
+			.trim() || "studio-preview.pdf";
+
+		const headers: Record<string, string> = {
+			"Content-Type": "application/pdf",
+			"Cache-Control": "no-store",
+			"X-Content-Type-Options": "nosniff",
+			"Content-Disposition": `inline; filename="${safeAsciiName}"; filename*=UTF-8''${encodeURIComponent(prepared.filename)}`,
+			"Content-Length": String(prepared.pdf.length),
+		};
+		if (prepared.warning) headers["X-Pi-Studio-Export-Warning"] = prepared.warning;
+
+		res.writeHead(200, headers);
+		res.end(prepared.pdf);
+	};
+
 	const handleRenderPreviewRequest = async (req: IncomingMessage, res: ServerResponse) => {
 		let rawBody = "";
 		try {
@@ -4153,7 +4442,7 @@ export default function (pi: ExtensionAPI) {
 					: "";
 			const resourcePath = resolveStudioBaseDir(sourcePath || undefined, userResourceDir || undefined, studioCwd);
 			const isLatex = /\\documentclass\b|\\begin\{document\}/.test(markdown);
-			const html = await renderStudioMarkdownWithPandoc(markdown, isLatex, resourcePath);
+			const html = await renderStudioMarkdownWithPandoc(markdown, isLatex, resourcePath, sourcePath || undefined);
 			respondJson(res, 200, { ok: true, html, renderer: "pandoc" });
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -4227,24 +4516,29 @@ export default function (pi: ExtensionAPI) {
 		const filename = sanitizePdfFilename(requestedFilename || (isLatex ? "studio-latex-preview.pdf" : "studio-preview.pdf"));
 
 		try {
-			const { pdf, warning } = await renderStudioPdfWithPandoc(markdown, isLatex, resourcePath, editorPdfLanguage);
-			const safeAsciiName = filename
-				.replace(/[\x00-\x1f\x7f]/g, "")
-				.replace(/[;"\\]/g, "_")
-				.replace(/\s+/g, " ")
-				.trim() || "studio-preview.pdf";
-
-			const headers: Record<string, string> = {
-				"Content-Type": "application/pdf",
-				"Cache-Control": "no-store",
-				"X-Content-Type-Options": "nosniff",
-				"Content-Disposition": `attachment; filename="${safeAsciiName}"; filename*=UTF-8''${encodeURIComponent(filename)}`,
-				"Content-Length": String(pdf.length),
-			};
-			if (warning) headers["X-Pi-Studio-Export-Warning"] = warning;
-
-			res.writeHead(200, headers);
-			res.end(pdf);
+			const { pdf, warning } = await renderStudioPdfWithPandoc(markdown, isLatex, resourcePath, editorPdfLanguage, sourcePath || undefined);
+			const exportId = storePreparedPdfExport(pdf, filename, warning);
+			const token = serverState?.token ?? "";
+			let openedExternal = false;
+			let openError: string | null = null;
+			try {
+				const prepared = await ensurePreparedPdfExportFile(exportId);
+				if (!prepared?.filePath) {
+					throw new Error("Prepared PDF file was not available for external open.");
+				}
+				await openPathInDefaultViewer(prepared.filePath);
+				openedExternal = true;
+			} catch (viewerError) {
+				openError = viewerError instanceof Error ? viewerError.message : String(viewerError);
+			}
+			respondJson(res, 200, {
+				ok: true,
+				filename,
+				warning: warning ?? null,
+				openedExternal,
+				openError,
+				downloadUrl: `/export-pdf?token=${encodeURIComponent(token)}&id=${encodeURIComponent(exportId)}`,
+			});
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			respondJson(res, 500, { ok: false, error: `PDF export failed: ${message}` });
@@ -4361,14 +4655,23 @@ export default function (pi: ExtensionAPI) {
 		if (requestUrl.pathname === "/export-pdf") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
-				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				const method = (req.method ?? "GET").toUpperCase();
+				if (method === "GET") {
+					respondText(res, 403, "Invalid or expired studio token. Re-run /studio.");
+				} else {
+					respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				}
 				return;
 			}
 
 			const method = (req.method ?? "GET").toUpperCase();
+			if (method === "GET") {
+				handlePreparedPdfDownloadRequest(requestUrl, res);
+				return;
+			}
 			if (method !== "POST") {
-				res.setHeader("Allow", "POST");
-				respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+				res.setHeader("Allow", "GET, POST");
+				respondJson(res, 405, { ok: false, error: "Method not allowed. Use GET or POST." });
 				return;
 			}
 
@@ -4534,6 +4837,7 @@ export default function (pi: ExtensionAPI) {
 		if (!serverState) return;
 		clearActiveRequest();
 		clearPendingStudioCompletion();
+		clearPreparedPdfExports();
 		clearCompactionState();
 		closeAllClients(1001, "Server shutting down");
 
@@ -4552,6 +4856,7 @@ export default function (pi: ExtensionAPI) {
 	const rotateToken = () => {
 		if (!serverState) return;
 		serverState.token = createSessionToken();
+		clearPreparedPdfExports();
 		closeAllClients(4001, "Session invalidated");
 		broadcastState();
 	};
@@ -4566,6 +4871,7 @@ export default function (pi: ExtensionAPI) {
 		clearCompactionState();
 		agentBusy = false;
 		clearPendingStudioCompletion();
+		clearPreparedPdfExports();
 		refreshRuntimeMetadata({ cwd: ctx.cwd, model: ctx.model });
 		refreshContextUsage(ctx);
 		emitDebugEvent("session_start", {
@@ -4585,6 +4891,7 @@ export default function (pi: ExtensionAPI) {
 		hydrateLatestAssistant(ctx.sessionManager.getBranch());
 		agentBusy = false;
 		clearPendingStudioCompletion();
+		clearPreparedPdfExports();
 		refreshRuntimeMetadata({ cwd: ctx.cwd, model: ctx.model });
 		refreshContextUsage(ctx);
 		emitDebugEvent("session_switch", {
@@ -4805,6 +5112,7 @@ export default function (pi: ExtensionAPI) {
 		lastCommandCtx = null;
 		agentBusy = false;
 		clearPendingStudioCompletion();
+		clearPreparedPdfExports();
 		clearCompactionState();
 		setTerminalActivity("idle");
 		await stopServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "description": "Browser GUI for structured critique workflows in pi",
   "type": "module",
   "license": "MIT",