pi-studio 0.9.45 → 0.9.47

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.47] — 2026-08-20
+
+### Fixed
+- Fall back to Pandoc’s compatible self-contained resource mode when its capability probe times out, and evict failed probes so one transient delay cannot disable previews for the rest of the Studio process.
+
+## [0.9.46] — 2026-08-20
+
+### Fixed
+- Re-resolve local Markdown images and refresh active previews when their file or working-directory context changes, preventing stale relative image URLs from rendering as broken links in Muxy and other browser hosts.
+
 ## [0.9.45] — 2026-08-20
 
 ### Changed

package/client/studio-client.js

@@ -222,6 +222,14 @@
       ) {
         throw new Error("Studio navigation helpers failed to load.");
       }
+      const previewResourceHelpers = globalThis.PiStudioPreviewResourceHelpers;
+      if (
+        !previewResourceHelpers
+        || typeof previewResourceHelpers.areStudioPreviewResourceContextsEqual !== "function"
+        || typeof previewResourceHelpers.hydrateStudioPreviewLocalImages !== "function"
+      ) {
+        throw new Error("Studio preview resource helpers failed to load.");
+      }
       const showMeHelpers = globalThis.PiStudioShowMeHelpers;
       if (!showMeHelpers || typeof showMeHelpers.chooseStudioShowMeFocus !== "function") {
         throw new Error("Studio Show me helpers failed to load.");
@@ -403,6 +411,7 @@
       const HTML_EXPORT_FETCH_TIMEOUT_MS = 180_000;
       const HTML_ARTIFACT_MATH_RENDER_FETCH_TIMEOUT_MS = 30_000;
       const HTML_ARTIFACT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
+      const RENDERED_PREVIEW_IMAGE_FETCH_TIMEOUT_MS = 8_000;
       const EDITOR_TAB_TEXT = "  ";
       const QUIZ_DEFAULT_COUNT = 5;
       const COMPLETION_CONTEXT_STORAGE_KEY = "piStudio.completionContextMode";
@@ -6035,19 +6044,33 @@
         }).filter(Boolean);
       }
 
-      function buildHtmlArtifactResourceFetchUrl(record, resourceUrl) {
+      function buildLocalPreviewResourceFetchUrl(context, resourceUrl) {
         const token = getToken();
         if (!token) return "";
         const params = new URLSearchParams({ token, path: String(resourceUrl || "") });
-        if (record && record.sourcePath) {
-          params.set("sourcePath", record.sourcePath);
+        if (context && context.sourcePath) {
+          params.set("sourcePath", context.sourcePath);
         }
-        if (record && record.resourceDir) {
-          params.set("resourceDir", record.resourceDir);
+        if (context && context.resourceDir) {
+          params.set("resourceDir", context.resourceDir);
         }
         return "/html-preview-resource?" + params.toString();
       }
 
+      async function fetchLocalPreviewResourceDataUrl(context, resourceUrl, timeoutMs, timeoutLabel) {
+        const fetchUrl = buildLocalPreviewResourceFetchUrl(context, resourceUrl);
+        if (!fetchUrl) throw new Error("Missing Studio token in URL.");
+        const response = await fetchWithTimeout(fetchUrl, { method: "GET" }, timeoutMs, timeoutLabel);
+        const payload = await response.json().catch(() => null);
+        if (!response.ok || !payload || payload.ok !== true || typeof payload.dataUrl !== "string") {
+          const message = payload && typeof payload.error === "string"
+            ? payload.error
+            : (timeoutLabel || "Local preview resource load") + " failed with HTTP " + response.status + ".";
+          throw new Error(message);
+        }
+        return payload.dataUrl;
+      }
+
       function postHtmlArtifactResourceResults(record, results) {
         if (!record || !record.iframe || !record.iframe.isConnected || !record.iframe.contentWindow) return;
         try {
@@ -6064,15 +6087,13 @@
       async function fetchHtmlArtifactResource(record, item) {
         const resourceId = item && item.resourceId ? item.resourceId : "";
         try {
-          const fetchUrl = buildHtmlArtifactResourceFetchUrl(record, item.url);
-          if (!fetchUrl) throw new Error("Missing Studio token in URL.");
-          const response = await fetchWithTimeout(fetchUrl, { method: "GET" }, HTML_ARTIFACT_RESOURCE_FETCH_TIMEOUT_MS, "HTML preview resource load");
-          const payload = await response.json().catch(() => null);
-          if (!response.ok || !payload || payload.ok !== true || typeof payload.dataUrl !== "string") {
-            const message = payload && typeof payload.error === "string" ? payload.error : "HTML preview resource load failed with HTTP " + response.status + ".";
-            throw new Error(message);
-          }
-          return { resourceId, ok: true, dataUrl: payload.dataUrl };
+          const dataUrl = await fetchLocalPreviewResourceDataUrl(
+            record,
+            item.url,
+            HTML_ARTIFACT_RESOURCE_FETCH_TIMEOUT_MS,
+            "HTML preview resource load",
+          );
+          return { resourceId, ok: true, dataUrl };
         } catch (error) {
           return { resourceId, ok: false, error: error && error.message ? error.message : String(error || "HTML preview resource load failed.") };
         }
@@ -8513,15 +8534,23 @@
         const timeoutId = controller ? window.setTimeout(() => controller.abort(), 8000) : null;
 
         const previewOptions = options && typeof options === "object" ? options : {};
+        const requestedResourceContext = previewOptions.resourceContext && typeof previewOptions.resourceContext === "object"
+          ? previewOptions.resourceContext
+          : null;
 
         let response;
         try {
           const effectivePath = getEffectiveSavePath();
-          const sourcePath = effectivePath || sourceState.path || "";
+          const sourcePath = requestedResourceContext
+            ? String(requestedResourceContext.sourcePath || "")
+            : (effectivePath || sourceState.path || "");
+          const resourceDir = requestedResourceContext
+            ? String(requestedResourceContext.resourceDir || "")
+            : ((resourceDirInput && !sourcePath) ? getCurrentResourceDirValue() : "");
           const payload = {
             markdown: String(markdown || ""),
             sourcePath: sourcePath,
-            resourceDir: (!sourcePath && resourceDirInput) ? getCurrentResourceDirValue() : "",
+            resourceDir: sourcePath ? "" : resourceDir,
           };
           if (previewOptions.includeEditorLanguage) {
             payload.editorLanguage = String(editorLanguage || "");
@@ -9282,10 +9311,12 @@
           stripMarkdownHtmlComments: !previewingEditorText || editorLanguage !== "latex",
         };
         const pdfPrepared = prepareStudioPdfBlocksForPreview(previewPrepared.markdown);
+        const previewResourceContext = getHtmlPreviewResourceContextOptions();
 
         try {
           const renderedHtml = await renderMarkdownWithPandoc(pdfPrepared.markdown, {
             includeEditorLanguage: pane === "source" || rightView === "editor-preview",
+            resourceContext: previewResourceContext,
           });
 
           if (pane === "source") {
@@ -9297,6 +9328,14 @@
           clearPreviewJumpHighlight(targetEl);
           finishPreviewRender(targetEl);
           targetEl.innerHTML = sanitizeRenderedHtml(renderedHtml, markdown, previewFallbackOptions);
+          await previewResourceHelpers.hydrateStudioPreviewLocalImages(targetEl, (resourceUrl) => (
+            fetchLocalPreviewResourceDataUrl(
+              previewResourceContext,
+              resourceUrl,
+              RENDERED_PREVIEW_IMAGE_FETCH_TIMEOUT_MS,
+              "Preview image load",
+            )
+          ));
           renderStudioPdfBlocksInElement(targetEl, pdfPrepared.blocks, previewingEditorText);
           applyPreviewAnnotationPlaceholdersToElement(targetEl, previewPrepared.placeholders);
           await renderAnnotationMathInElement(targetEl);
@@ -9406,6 +9445,13 @@
         }
       }
 
+      function refreshPreviewsForResourceContextChange() {
+        renderSourcePreview();
+        if (rightView === "preview") {
+          renderActiveResult();
+        }
+      }
+
       function scheduleResponseEditorPreviewRender(delayMs) {
         if (responseEditorPreviewTimer) {
           window.clearTimeout(responseEditorPreviewTimer);
@@ -11414,6 +11460,7 @@
       function setSourceState(next, options) {
         const previousDescriptor = getCurrentStudioDocumentDescriptor();
         const previousQuartoPath = getCurrentStudioQuartoSourcePath();
+        const previousPreviewResourceContext = getHtmlPreviewResourceContextOptions();
         const nextPath = next && next.path ? next.path : null;
         sourceState = {
           source: next && next.source ? next.source : "blank",
@@ -11457,6 +11504,10 @@
         const refreshChangedQuartoView = rightView === "editor-quarto-preview" && quartoSourceChanged && isCurrentStudioQuartoDocument();
         if (refreshChangedQuartoView) requestStudioQuartoPreviewCheck(false);
         if (leavingUnavailableQuartoView || refreshChangedQuartoView) refreshResponseUi();
+        const nextPreviewResourceContext = getHtmlPreviewResourceContextOptions();
+        if (!previewResourceHelpers.areStudioPreviewResourceContextsEqual(previousPreviewResourceContext, nextPreviewResourceContext)) {
+          refreshPreviewsForResourceContextChange();
+        }
         scheduleWorkspacePersistence();
       }
 
@@ -21993,7 +22044,7 @@
         }
         updateSaveFileTooltip();
         syncActionButtons();
-        renderSourcePreview();
+        refreshPreviewsForResourceContextChange();
         scheduleWorkspacePersistence();
       }
       if (sourceBadgeEl) {
@@ -22036,7 +22087,7 @@
           showResourceDirState("button");
           updateSaveFileTooltip();
           syncActionButtons();
-          renderSourcePreview();
+          refreshPreviewsForResourceContextChange();
           scheduleWorkspacePersistence();
         });
       }

package/client/studio-preview-resource-helpers.js

@@ -0,0 +1,52 @@
+(() => {
+  const STUDIO_PREVIEW_LOCAL_IMAGE_LIMIT = 100;
+  const STUDIO_PREVIEW_IMAGE_DATA_URL_PATTERN = /^data:image\/(?:png|jpeg|gif|webp);base64,/i;
+
+  function isResolvableStudioPreviewImageSource(value) {
+    const source = String(value || "").trim();
+    if (!source || source.startsWith("#") || source.startsWith("//")) return false;
+    if (/^(?:data|blob|https?|about|javascript):/i.test(source)) return false;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(source) && !/^[a-z]:[\\/]/i.test(source)) return false;
+    return true;
+  }
+
+  function areStudioPreviewResourceContextsEqual(left, right) {
+    const a = left && typeof left === "object" ? left : {};
+    const b = right && typeof right === "object" ? right : {};
+    return String(a.sourcePath || "") === String(b.sourcePath || "")
+      && String(a.resourceDir || "") === String(b.resourceDir || "");
+  }
+
+  async function hydrateStudioPreviewLocalImages(target, resolveResource) {
+    if (!target || typeof target.querySelectorAll !== "function" || typeof resolveResource !== "function") {
+      return { attempted: 0, resolved: 0 };
+    }
+
+    const images = Array.from(target.querySelectorAll("img[src]"))
+      .filter((image) => image && typeof image.getAttribute === "function" && isResolvableStudioPreviewImageSource(image.getAttribute("src")))
+      .slice(0, STUDIO_PREVIEW_LOCAL_IMAGE_LIMIT);
+
+    let resolved = 0;
+    await Promise.all(images.map(async (image) => {
+      const originalSource = String(image.getAttribute("src") || "").trim();
+      try {
+        const dataUrl = await resolveResource(originalSource);
+        if (!STUDIO_PREVIEW_IMAGE_DATA_URL_PATTERN.test(String(dataUrl || ""))) return;
+        if (image.isConnected === false || String(image.getAttribute("src") || "").trim() !== originalSource) return;
+        image.setAttribute("src", dataUrl);
+        resolved += 1;
+      } catch {
+        // Leave unresolved images unchanged so authored browser URLs retain their normal behavior.
+      }
+    }));
+
+    return { attempted: images.length, resolved };
+  }
+
+  globalThis.PiStudioPreviewResourceHelpers = Object.freeze({
+    STUDIO_PREVIEW_LOCAL_IMAGE_LIMIT,
+    areStudioPreviewResourceContextsEqual,
+    hydrateStudioPreviewLocalImages,
+    isResolvableStudioPreviewImageSource,
+  });
+})();

package/index.ts

@@ -29,6 +29,7 @@ import {
 } from "./shared/studio-markdown-latex-literals.js";
 import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
+import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pandoc-resource-flag.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";
@@ -108,6 +109,7 @@ const STUDIO_CSS_URL = new URL("./client/studio.css", import.meta.url);
 const STUDIO_ANNOTATION_HELPERS_URL = new URL("./client/studio-annotation-helpers.js", import.meta.url);
 const STUDIO_MERMAID_HELPERS_URL = new URL("./client/studio-mermaid-helpers.js", import.meta.url);
 const STUDIO_NAVIGATION_HELPERS_URL = new URL("./client/studio-navigation-helpers.js", import.meta.url);
+const STUDIO_PREVIEW_RESOURCE_HELPERS_URL = new URL("./client/studio-preview-resource-helpers.js", import.meta.url);
 const STUDIO_SHOW_ME_HELPERS_URL = new URL("./client/studio-show-me-helpers.js", import.meta.url);
 const STUDIO_CLIENT_URL = new URL("./client/studio-client.js", import.meta.url);
 
@@ -6125,27 +6127,19 @@ function decorateStudioPandocSyntaxHtml(html: string): string {
 	);
 }
 
-const studioPandocHtmlResourceFlagCache = new Map<string, Promise<"--embed-resources" | "--self-contained">>();
-
-async function getStudioPandocHtmlResourceFlag(pandocCommand: string): Promise<"--embed-resources" | "--self-contained"> {
-	let cached = studioPandocHtmlResourceFlagCache.get(pandocCommand);
-	if (!cached) {
-		cached = runStudioSubprocess(pandocCommand, ["--help"], {
-			timeoutMs: 5_000,
-			stdoutMaxBytes: 250_000,
-			stderrMaxBytes: 20_000,
-			label: "pandoc capability probe",
-			notFoundMessage: "pandoc was not found. Install pandoc or set PANDOC_PATH to the pandoc binary.",
-		}).then((result) => {
-			if (result.code !== 0) {
-				throw new Error(`pandoc capability probe failed with exit code ${result.code}${result.stderr ? `: ${result.stderr}` : ""}`);
-			}
-			return result.stdout.includes("--embed-resources") ? "--embed-resources" : "--self-contained";
-		});
-		studioPandocHtmlResourceFlagCache.set(pandocCommand, cached);
+const resolveStudioPandocHtmlResourceFlag = createStudioPandocHtmlResourceFlagResolver(async (pandocCommand: string) => {
+	const result = await runStudioSubprocess(pandocCommand, ["--help"], {
+		timeoutMs: 5_000,
+		stdoutMaxBytes: 250_000,
+		stderrMaxBytes: 20_000,
+		label: "pandoc capability probe",
+		notFoundMessage: "pandoc was not found. Install pandoc or set PANDOC_PATH to the pandoc binary.",
+	});
+	if (result.code !== 0) {
+		throw new Error(`pandoc capability probe failed with exit code ${result.code}${result.stderr ? `: ${result.stderr}` : ""}`);
 	}
-	return cached;
-}
+	return result.stdout;
+});
 
 function preprocessStudioLatexFootnotemarksForPreview(latex: string): string {
 	return String(latex ?? "").replace(/\\footnotemark\s*\[\s*([^\]\r\n]+?)\s*\]/g, (_match, marker: string) => {
@@ -6185,7 +6179,7 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 		await mkdir(htmlTemplateDir, { recursive: true });
 		const htmlTemplatePath = join(htmlTemplateDir, "template.html");
 		await writeFile(htmlTemplatePath, STUDIO_PANDOC_HTML_FRAGMENT_TEMPLATE, "utf-8");
-		if (resourcePath) args.push(await getStudioPandocHtmlResourceFlag(pandocCommand));
+		if (resourcePath) args.push(await resolveStudioPandocHtmlResourceFlag(pandocCommand));
 		args.push("--standalone", `--template=${htmlTemplatePath}`);
 	}
 	const normalizedMarkdown = isLatex
@@ -10563,6 +10557,7 @@ function buildStudioHtml(
 	const annotationHelpersScriptHref = `/studio-annotation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const mermaidHelpersScriptHref = `/studio-mermaid-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const navigationHelpersScriptHref = `/studio-navigation-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
+	const previewResourceHelpersScriptHref = `/studio-preview-resource-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const showMeHelpersScriptHref = `/studio-show-me-helpers.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const clientScriptHref = `/studio-client.js?token=${encodeURIComponent(studioToken ?? "")}`;
 	const faviconHref = buildStudioFaviconDataUri(style);
@@ -10986,6 +10981,7 @@ ${cssVarsBlock}
   <script src="${annotationHelpersScriptHref}"></script>
   <script src="${mermaidHelpersScriptHref}"></script>
   <script src="${navigationHelpersScriptHref}"></script>
+  <script src="${previewResourceHelpersScriptHref}"></script>
   <script src="${showMeHelpersScriptHref}"></script>
   <script src="${clientScriptHref}"></script>
 </body>
@@ -14601,6 +14597,7 @@ export default function (pi: ExtensionAPI) {
 			requestUrl.pathname === "/studio-annotation-helpers.js"
 			|| requestUrl.pathname === "/studio-mermaid-helpers.js"
 			|| requestUrl.pathname === "/studio-navigation-helpers.js"
+			|| requestUrl.pathname === "/studio-preview-resource-helpers.js"
 			|| requestUrl.pathname === "/studio-show-me-helpers.js"
 			|| requestUrl.pathname === "/studio-client.js"
 		) {
@@ -14623,18 +14620,22 @@ export default function (pi: ExtensionAPI) {
 					? STUDIO_MERMAID_HELPERS_URL
 					: requestUrl.pathname === "/studio-navigation-helpers.js"
 						? STUDIO_NAVIGATION_HELPERS_URL
-						: requestUrl.pathname === "/studio-show-me-helpers.js"
-							? STUDIO_SHOW_ME_HELPERS_URL
-							: STUDIO_CLIENT_URL;
+						: requestUrl.pathname === "/studio-preview-resource-helpers.js"
+							? STUDIO_PREVIEW_RESOURCE_HELPERS_URL
+							: requestUrl.pathname === "/studio-show-me-helpers.js"
+								? STUDIO_SHOW_ME_HELPERS_URL
+								: STUDIO_CLIENT_URL;
 			const targetLabel = requestUrl.pathname === "/studio-annotation-helpers.js"
 				? "studio annotation helper script"
 				: requestUrl.pathname === "/studio-mermaid-helpers.js"
 					? "studio Mermaid helper script"
 					: requestUrl.pathname === "/studio-navigation-helpers.js"
 						? "studio navigation helper script"
-						: requestUrl.pathname === "/studio-show-me-helpers.js"
-							? "studio Show me helper script"
-							: "studio client script";
+						: requestUrl.pathname === "/studio-preview-resource-helpers.js"
+							? "studio preview resource helper script"
+							: requestUrl.pathname === "/studio-show-me-helpers.js"
+								? "studio Show me helper script"
+								: "studio client script";
 
 			try {
 				const clientScript = readFileSync(targetUrl, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.45",
+  "version": "0.9.47",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/studio-pandoc-resource-flag.js

@@ -0,0 +1,34 @@
+export function createStudioPandocHtmlResourceFlagResolver(probeHelp) {
+  if (typeof probeHelp !== "function") {
+    throw new TypeError("A Pandoc capability probe function is required.");
+  }
+
+  const cache = new Map();
+
+  async function getResourceFlag(pandocCommand) {
+    const command = String(pandocCommand || "pandoc");
+    let cached = cache.get(command);
+    if (!cached) {
+      cached = Promise.resolve()
+        .then(() => probeHelp(command))
+        .then((helpText) => String(helpText || "").includes("--embed-resources")
+          ? "--embed-resources"
+          : "--self-contained");
+      cache.set(command, cached);
+      void cached.catch(() => {
+        if (cache.get(command) === cached) cache.delete(command);
+      });
+    }
+    return cached;
+  }
+
+  return async function resolveStudioPandocHtmlResourceFlag(pandocCommand) {
+    try {
+      return await getResourceFlag(pandocCommand);
+    } catch {
+      // Old and current Pandoc versions accept --self-contained. The actual
+      // render can now succeed or report the executable's useful error.
+      return "--self-contained";
+    }
+  };
+}