pi-studio 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -4,10 +4,25 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.8.3] — 2026-05-13
+
+### Changed
+- Updated package, README, and UI wording to describe the feature as interactive HTML preview.
+
+### Fixed
+- **Open new editor** now opens a blank companion editor when the current editor is empty.
+- PDF export now preserves Pandoc YAML front matter while applying Studio Markdown transforms and lets Markdown documents with `header-includes` control their own LaTeX preamble, fixing exports that use YAML-defined commands such as `\firstpageletterhead`.
+- Reduced scroll snap-back after using browser Find by preserving Studio pane scroll positions during pane activation.
+
+## [0.8.2] — 2026-05-13
+
+### Changed
+- Improved dark-theme contrast for Studio dropdown arrows and the interactive HTML preview zoom percentage by using the stronger Studio info text colour token.
+
 ## [0.8.1] — 2026-05-13
 
 ### Added
-- Added first-cut HTML artifact preview for straight, unfenced HTML in Studio preview panes, rendered in a sandboxed iframe with inline scripts enabled, network requests blocked by CSP, fit/capped sizing, and toolbar zoom controls; HTML export preserves authored HTML artifacts instead of converting them through Markdown.
+- Added first-cut interactive HTML preview for straight, unfenced HTML in Studio preview panes, rendered in a sandboxed iframe with inline scripts enabled, network requests blocked by CSP, fit/capped sizing, and toolbar zoom controls; HTML export preserves authored HTML previews instead of converting them through Markdown.
 
 ## [0.8.0] — 2026-05-12
 

package/README.md

@@ -1,6 +1,6 @@
 # pi-studio
 
-Extension for [pi](https://pi.dev) that opens a local two-pane browser workspace for working with prompts, responses, live working details, Markdown and LaTeX documents, code files, and other common text-based files side by side. Annotate responses and files, add local comments, write, edit, and run prompts, browse prompt and response history, request critiques, and use live preview for code, Markdown, and LaTeX.
+Extension for [pi](https://pi.dev) that opens a local two-pane browser workspace for working with prompts, responses, live working details, Markdown and LaTeX documents, interactive HTML previews, code files, and other common text-based files side by side. Annotate responses and files, add local comments, write, edit, and run prompts, browse prompt and response history, request critiques, and use live preview for code, Markdown, LaTeX, and interactive HTML.
 
 ## Quick demo
 
@@ -35,10 +35,10 @@ Extension for [pi](https://pi.dev) that opens a local two-pane browser workspace
   - strips markers before send (optional)
   - saves `.annotated.md`
 - Renders Markdown/LaTeX/code previews (math + Mermaid), theme-synced with pi
-- Renders straight, unfenced HTML artifacts in preview via a sandboxed browser iframe with zoom controls, while fenced `html` blocks remain source code
+- Renders straight, unfenced interactive HTML in preview via a sandboxed browser iframe with zoom controls, while fenced `html` blocks remain source code
 - Embeds local PDFs in Studio Markdown previews via explicit `studio-pdf` fenced blocks
 - Ships optional `pi-studio-dark` and `pi-studio-light` themes tuned for Studio's browser workspace
-- Exports right-pane preview as PDF (pandoc + LaTeX) or standalone HTML, preserving authored HTML artifacts as HTML
+- Exports right-pane preview as PDF (pandoc + LaTeX) or standalone HTML, preserving authored HTML previews as HTML
 - Exports local files headlessly via `/studio-pdf <path>` to `<name>.studio.pdf` or `/studio-html <path>` to `<name>.studio.html`; without a path, those commands export the last model response to a timestamped file
 - Shows model/session/context usage in the footer, plus a compact-context action
 

package/client/studio-client.js

@@ -1954,6 +1954,51 @@
         updatePaneFocusButtons();
       }
 
+      function snapshotStudioScrollablePositions() {
+        return [sourceTextEl, sourcePreviewEl, critiqueViewEl]
+          .filter((el) => el && typeof el.scrollTop === "number" && typeof el.scrollLeft === "number")
+          .map((el) => ({ el, top: el.scrollTop, left: el.scrollLeft }));
+      }
+
+      function restoreStudioScrollablePositions(snapshot) {
+        if (!Array.isArray(snapshot)) return;
+        snapshot.forEach((entry) => {
+          const el = entry && entry.el;
+          if (!el || !el.isConnected) return;
+          if (typeof entry.top === "number") el.scrollTop = entry.top;
+          if (typeof entry.left === "number") el.scrollLeft = entry.left;
+        });
+        syncEditorHighlightScroll();
+      }
+
+      function scheduleStudioScrollablePositionRestore(snapshot) {
+        if (!Array.isArray(snapshot) || snapshot.length === 0) return;
+        const schedule = typeof window.requestAnimationFrame === "function"
+          ? window.requestAnimationFrame.bind(window)
+          : (cb) => window.setTimeout(cb, 16);
+        window.setTimeout(() => restoreStudioScrollablePositions(snapshot), 0);
+        schedule(() => {
+          restoreStudioScrollablePositions(snapshot);
+          schedule(() => restoreStudioScrollablePositions(snapshot));
+        });
+      }
+
+      function shouldPreserveScrollForPaneActivationEvent(event) {
+        const target = event && event.target;
+        if (!(target instanceof Element)) return true;
+        if (target.closest("button, select, input, a, [role='button'], .studio-copy-block-btn, .preview-comment-add, .preview-comment-jump")) {
+          return false;
+        }
+        return true;
+      }
+
+      function activatePaneFromInteraction(nextPane, event) {
+        const shouldPreserveScroll = shouldPreserveScrollForPaneActivationEvent(event);
+        const snapshot = shouldPreserveScroll ? snapshotStudioScrollablePositions() : [];
+        setActivePane(nextPane);
+        if (shouldPreserveScroll) scheduleStudioScrollablePositionRestore(snapshot);
+      }
+
       function setActivePane(nextPane) {
         activePane = nextPane === "right" ? "right" : "left";
 
@@ -2711,7 +2756,7 @@
           record.shell.classList.toggle("is-height-capped", capped);
         }
         if (record.detail) {
-          record.detail.textContent = "HTML artifact";
+          record.detail.textContent = "HTML preview";
         }
       }
 
@@ -2719,7 +2764,7 @@
 
       function renderHtmlArtifactPreview(targetEl, html, pane, options) {
         if (!targetEl) return;
-        const title = options && options.title ? String(options.title) : "HTML artifact preview";
+        const title = options && options.title ? String(options.title) : "HTML preview";
         const previewId = "html_artifact_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 10);
         pruneDisconnectedHtmlArtifactFrames();
         clearPreviewJumpHighlight(targetEl);
@@ -2736,7 +2781,7 @@
         label.textContent = title;
         const detail = document.createElement("span");
         detail.className = "studio-html-artifact-detail";
-        detail.textContent = "HTML artifact";
+        detail.textContent = "HTML preview";
 
         const tools = document.createElement("span");
         tools.className = "studio-html-artifact-tools";
@@ -2783,10 +2828,10 @@
           });
           return button;
         };
-        const zoomOutBtn = makeZoomButton("−", "Zoom out HTML artifact", () => setArtifactZoom(artifactZoom - HTML_ARTIFACT_ZOOM_STEP));
-        const zoomResetBtn = makeZoomButton("100%", "Reset HTML artifact zoom", () => setArtifactZoom(1));
+        const zoomOutBtn = makeZoomButton("−", "Zoom out HTML preview", () => setArtifactZoom(artifactZoom - HTML_ARTIFACT_ZOOM_STEP));
+        const zoomResetBtn = makeZoomButton("100%", "Reset HTML preview zoom", () => setArtifactZoom(1));
         zoomResetBtn.classList.add("studio-html-artifact-zoom-reset");
-        const zoomInBtn = makeZoomButton("+", "Zoom in HTML artifact", () => setArtifactZoom(artifactZoom + HTML_ARTIFACT_ZOOM_STEP));
+        const zoomInBtn = makeZoomButton("+", "Zoom in HTML preview", () => setArtifactZoom(artifactZoom + HTML_ARTIFACT_ZOOM_STEP));
         zoomControls.appendChild(zoomOutBtn);
         zoomControls.appendChild(zoomResetBtn);
         zoomControls.appendChild(zoomInBtn);
@@ -3882,7 +3927,7 @@
 
         const htmlArtifactSource = getRightPaneHtmlArtifactSource();
         if (htmlArtifactSource) {
-          setStatus("PDF export does not support HTML artifacts yet. Export as HTML or use the browser print dialog inside the artifact.", "warning");
+          setStatus("PDF export does not support interactive HTML previews yet. Export as HTML or use the browser print dialog inside the preview.", "warning");
           return;
         }
 
@@ -4400,7 +4445,7 @@
         if (editorView !== "preview") return;
         const text = prepareEditorTextForPreview(sourceTextEl.value || "");
         if (isHtmlArtifactPreviewText(text, editorLanguage)) {
-          renderHtmlArtifactPreview(sourcePreviewEl, text, "source", { title: "Editor HTML artifact preview" });
+          renderHtmlArtifactPreview(sourcePreviewEl, text, "source", { title: "Editor HTML preview" });
           return;
         }
         if (supportsCodePreviewCommentsForCurrentEditor()) {
@@ -4672,7 +4717,7 @@
             return;
           }
           if (isHtmlArtifactPreviewText(editorText, editorLanguage)) {
-            renderHtmlArtifactPreview(critiqueViewEl, editorText, "response", { title: "Editor HTML artifact preview" });
+            renderHtmlArtifactPreview(critiqueViewEl, editorText, "response", { title: "Editor HTML preview" });
             return;
           }
           if (supportsCodePreviewCommentsForCurrentEditor()) {
@@ -4696,7 +4741,7 @@
 
         if (rightView === "preview") {
           if (isHtmlArtifactPreviewText(markdown, "")) {
-            renderHtmlArtifactPreview(critiqueViewEl, markdown, "response", { title: "Response HTML artifact preview" });
+            renderHtmlArtifactPreview(critiqueViewEl, markdown, "response", { title: "Response HTML preview" });
             return;
           }
           const nonce = ++responsePreviewRenderNonce;
@@ -4777,7 +4822,7 @@
           } else if (!canExportPreview) {
             exportPdfBtn.title = "Nothing to export yet.";
           } else if (isHtmlArtifactPreview) {
-            exportPdfBtn.title = "This is an HTML artifact preview. Export as HTML; PDF export is not available yet.";
+            exportPdfBtn.title = "This is an interactive HTML preview. Export as HTML; PDF export is not available yet.";
           } else {
             exportPdfBtn.title = "Choose PDF or HTML and export the current right-pane preview.";
           }
@@ -4785,18 +4830,18 @@
         if (exportPreviewPdfBtn) {
           exportPreviewPdfBtn.disabled = uiBusy || previewExportInProgress || !canExportPreview || isHtmlArtifactPreview;
           exportPreviewPdfBtn.title = isHtmlArtifactPreview
-            ? "HTML artifact PDF export is not available yet."
+            ? "Interactive HTML preview PDF export is not available yet."
             : "Export the current right-pane preview as PDF.";
         }
         if (exportPreviewHtmlBtn) {
           exportPreviewHtmlBtn.disabled = uiBusy || previewExportInProgress || !canExportPreview;
           exportPreviewHtmlBtn.title = isHtmlArtifactPreview
-            ? "Export the authored HTML artifact."
+            ? "Export the authored HTML preview."
             : "Export the current right-pane preview as standalone HTML.";
         }
         if (exportPreviewControlsEl) {
           exportPreviewControlsEl.title = canExportPreview
-            ? (isHtmlArtifactPreview ? "Export this HTML artifact." : "Choose a format and export the current right-pane preview.")
+            ? (isHtmlArtifactPreview ? "Export this HTML preview." : "Choose a format and export the current right-pane preview.")
             : "Switch right pane to a non-empty preview before exporting.";
         }
         if (!canExportPreview || previewExportInProgress) {
@@ -11114,9 +11159,12 @@
           setWsState("Ready");
           const targetUrl = resolveCompanionEditorTargetUrl(message);
           const opened = navigatePendingCompanionWindow(responseRequestId, targetUrl);
+          const readyMessage = typeof message.message === "string" && message.message.trim()
+            ? message.message.trim()
+            : "Opened companion editor with a detached copy of the current editor text.";
           setStatus(
             opened
-              ? "Opened companion editor with a detached copy of the current editor text."
+              ? readyMessage
               : (targetUrl ? "Companion editor ready: " + targetUrl : "Companion editor is ready, but Studio did not receive a URL."),
             opened ? "success" : "warning",
           );
@@ -11578,13 +11626,13 @@
       }
 
       if (leftPaneEl) {
-        leftPaneEl.addEventListener("mousedown", () => setActivePane("left"));
-        leftPaneEl.addEventListener("focusin", () => setActivePane("left"));
+        leftPaneEl.addEventListener("mousedown", (event) => activatePaneFromInteraction("left", event));
+        leftPaneEl.addEventListener("focusin", (event) => activatePaneFromInteraction("left", event));
       }
 
       if (rightPaneEl) {
-        rightPaneEl.addEventListener("mousedown", () => setActivePane("right"));
-        rightPaneEl.addEventListener("focusin", () => setActivePane("right"));
+        rightPaneEl.addEventListener("mousedown", (event) => activatePaneFromInteraction("right", event));
+        rightPaneEl.addEventListener("focusin", (event) => activatePaneFromInteraction("right", event));
       }
 
       if (leftFocusBtn) {
@@ -12074,10 +12122,6 @@
       if (openCompanionBtn) {
         openCompanionBtn.addEventListener("click", () => {
           const content = sourceTextEl.value;
-          if (!content.trim()) {
-            setStatus("Editor is empty. Nothing to copy into a companion view.", "warning");
-            return;
-          }
 
           const requestId = beginUiAction("open_editor_only");
           if (!requestId) return;

package/client/studio.css

@@ -77,7 +77,7 @@
 
     .export-preview-trigger::after {
       content: "⌄";
-      color: var(--muted);
+      color: var(--studio-info-text, var(--text));
       font-size: 14px;
       line-height: 1;
       transform: translateY(-1px);
@@ -1598,7 +1598,7 @@
 
     .rendered-markdown .studio-html-artifact-zoom-reset {
       min-width: 42px;
-      color: var(--muted);
+      color: var(--studio-info-text, var(--text));
     }
 
     .rendered-markdown .studio-html-artifact-frame {
@@ -3121,7 +3121,7 @@
 
     body.studio-ui-refresh .studio-refresh-chip::after {
       content: "⌄";
-      color: var(--muted);
+      color: var(--studio-info-text, var(--text));
       font-size: 14px;
       line-height: 1;
       transform: translateY(-1px);

package/index.ts

@@ -3457,6 +3457,49 @@ function normalizeStudioMarkdownFencedBlocks(markdown: string): string {
 	return out.join("\n");
 }
 
+interface StudioYamlFrontMatterSplit {
+	frontMatter: string;
+	body: string;
+}
+
+function splitStudioYamlFrontMatter(markdown: string): StudioYamlFrontMatterSplit | null {
+	const source = String(markdown ?? "");
+	const match = source.match(/^(\uFEFF?---[ \t]*(?:\r?\n)[\s\S]*?(?:\r?\n)---[ \t]*(?:\r?\n|$))([\s\S]*)$/);
+	if (!match) return null;
+	return {
+		frontMatter: match[1] ?? "",
+		body: match[2] ?? "",
+	};
+}
+
+function mapStudioMarkdownBodyPreservingYamlFrontMatter(markdown: string, transformBody: (body: string) => string): string {
+	const source = String(markdown ?? "");
+	const split = splitStudioYamlFrontMatter(source);
+	if (!split) return transformBody(source);
+	return `${split.frontMatter}${transformBody(split.body)}`;
+}
+
+function stripStudioMarkdownHtmlCommentsPreservingYamlFrontMatter(markdown: string): string {
+	return mapStudioMarkdownBodyPreservingYamlFrontMatter(markdown, (body) => stripStudioMarkdownHtmlComments(body));
+}
+
+function hasStudioYamlHeaderIncludes(markdown: string): boolean {
+	const split = splitStudioYamlFrontMatter(markdown);
+	if (!split) return false;
+	return /^\s*header-includes\s*:/im.test(split.frontMatter);
+}
+
+function prepareStudioMarkdownForPandoc(markdown: string, options?: { preserveLiteralLatexCommands?: boolean }): string {
+	const shouldPreserveLiteralLatexCommands = options?.preserveLiteralLatexCommands !== false;
+	return mapStudioMarkdownBodyPreservingYamlFrontMatter(markdown, (body) => {
+		const normalizedMath = normalizeMathDelimiters(body);
+		const latexReady = shouldPreserveLiteralLatexCommands
+			? preserveLiteralLatexCommandsInMarkdown(normalizedMath)
+			: normalizedMath;
+		return normalizeObsidianImages(latexReady);
+	});
+}
+
 function hasStudioMarkdownDiffFence(markdown: string): boolean {
 	const lines = String(markdown ?? "").replace(/\r\n/g, "\n").split("\n");
 
@@ -4300,8 +4343,10 @@ function prepareStudioPdfMarkdown(markdown: string, isLatex?: boolean, editorLan
 	const annotationReadySource = !effectiveEditorLanguage || effectiveEditorLanguage === "markdown" || effectiveEditorLanguage === "latex"
 		? replaceStudioAnnotationMarkersForPdf(source)
 		: source;
-	const commentStrippedSource = stripStudioMarkdownHtmlComments(annotationReadySource);
-	return normalizeObsidianImages(preserveLiteralLatexCommandsInMarkdown(normalizeMathDelimiters(commentStrippedSource)));
+	const commentStrippedSource = stripStudioMarkdownHtmlCommentsPreservingYamlFrontMatter(annotationReadySource);
+	return prepareStudioMarkdownForPandoc(commentStrippedSource, {
+		preserveLiteralLatexCommands: !hasStudioYamlHeaderIncludes(annotationReadySource),
+	});
 }
 
 function stripMathMlAnnotationTags(html: string): string {
@@ -4559,7 +4604,7 @@ function decorateStudioPandocSyntaxHtml(html: string): string {
 
 async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string, sourcePath?: string): Promise<string> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
-	const markdownWithoutHtmlComments = isLatex ? markdown : stripStudioMarkdownHtmlComments(markdown);
+	const markdownWithoutHtmlComments = isLatex ? markdown : stripStudioMarkdownHtmlCommentsPreservingYamlFrontMatter(markdown);
 	const markdownWithPreviewPageBreaks = isLatex ? markdownWithoutHtmlComments : replaceStudioPreviewPageBreakCommands(markdownWithoutHtmlComments);
 	const latexSubfigurePreviewTransform = isLatex
 		? preprocessStudioLatexSubfiguresForPreview(markdownWithPreviewPageBreaks)
@@ -4580,7 +4625,7 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 	}
 	const normalizedMarkdown = isLatex
 		? sourceWithResolvedRefs
-		: normalizeStudioMarkdownFencedBlocks(normalizeObsidianImages(preserveLiteralLatexCommandsInMarkdown(normalizeMathDelimiters(sourceWithResolvedRefs))));
+		: normalizeStudioMarkdownFencedBlocks(prepareStudioMarkdownForPandoc(sourceWithResolvedRefs));
 	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath);
 
 	let renderedHtml = await new Promise<string>((resolve, reject) => {
@@ -5501,6 +5546,8 @@ async function renderStudioPdfWithPandoc(
 		await mkdir(tempDir, { recursive: true });
 		await writeFile(preamblePath, buildStudioPdfPreamble(pdfOptions), "utf-8");
 
+		const hasYamlHeaderIncludesForPdf = inputFormat !== "latex" && hasStudioYamlHeaderIncludes(markdownForPdf);
+		const headerIncludeArgs = hasYamlHeaderIncludesForPdf ? [] : ["--include-in-header", preamblePath];
 		const args = [
 			"-f", inputFormat,
 			"-o", outputPath,
@@ -5508,7 +5555,7 @@ async function renderStudioPdfWithPandoc(
 			...buildStudioPdfPandocVariableArgs(pdfOptions, inputFormat !== "latex"),
 			"-V", "urlcolor=blue",
 			"-V", "linkcolor=blue",
-			"--include-in-header", preamblePath,
+			...headerIncludeArgs,
 			...bibliographyArgs,
 		];
 		if (resourcePath) args.push(`--resource-path=${resourcePath}`);
@@ -5652,6 +5699,8 @@ async function renderStudioPdfWithPandoc(
 		return { pdf: rendered.pdf, warning: mermaidPrepared.warning ?? rendered.warning };
 	}
 
+	const hasYamlHeaderIncludesForPdf = !isLatex && hasStudioYamlHeaderIncludes(markdownForPdf);
+	const headerIncludeArgs = hasYamlHeaderIncludesForPdf ? [] : ["--include-in-header", preamblePath];
 	const args = [
 		"-f", inputFormat,
 		"-o", outputPath,
@@ -5659,7 +5708,7 @@ async function renderStudioPdfWithPandoc(
 		...buildStudioPdfPandocVariableArgs(pdfOptions, !isLatex),
 		"-V", "urlcolor=blue",
 		"-V", "linkcolor=blue",
-		"--include-in-header", preamblePath,
+		...headerIncludeArgs,
 		...bibliographyArgs,
 	];
 	if (resourcePath) args.push(`--resource-path=${resourcePath}`);
@@ -8599,9 +8648,10 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			const resourceDir = resolveStudioCompanionResourceDir(msg.path, msg.resourceDir, studioCwd);
+			const hasContent = msg.content.trim().length > 0;
 			const document: InitialStudioDocument = {
 				text: msg.content,
-				label: buildStudioCompanionLabel(msg.label),
+				label: hasContent ? buildStudioCompanionLabel(msg.label) : "blank companion editor",
 				source: "blank",
 				draftId: createStudioDraftId(),
 				resourceDir,
@@ -8614,7 +8664,9 @@ export default function (pi: ExtensionAPI) {
 				requestId: msg.requestId,
 				url,
 				relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
-				message: "Companion editor is ready with a detached copy of the current editor text.",
+				message: hasContent
+					? "Companion editor is ready with a detached copy of the current editor text."
+					: "Blank companion editor is ready.",
 			});
 			return;
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-studio",
-  "version": "0.8.1",
-  "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, prompt/response history, and live Markdown/LaTeX/code preview",
+  "version": "0.8.3",
+  "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, prompt/response history, and live Markdown/LaTeX/code/interactive HTML preview",
   "type": "module",
   "license": "MIT",
   "repository": {