pi-studio 0.9.44 → 0.9.46

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [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
+- Open Studio in Muxy’s built-in browser when launched from a Muxy pane, using Muxy’s pane-local environment and CLI without global shell hooks, while retaining the bounded cmux and system-browser fallbacks.
+
 ## [0.9.44] — 2026-08-14
 
 ### Added

package/README.md

@@ -63,7 +63,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 
 | Command | Description |
 |---|---|
-| `/studio` | Open in cmux when available, otherwise the system browser, with the last assistant response (fallback: blank) |
+| `/studio` | Open in Muxy or cmux when available, otherwise the system browser, with the last assistant response (fallback: blank) |
 | `/studio <path>` | Open with file preloaded |
 | `/studio --last` | Force last response |
 | `/studio --blank` | Force blank editor |
@@ -150,7 +150,7 @@ Studio only passes icon-pack arguments when a diagram actually references `lucid
 ## Notes
 
 - Local-only server (`127.0.0.1`) with tokenized Studio URLs.
-- When Pi runs inside cmux, Studio opens as a focused cmux browser surface in the caller’s workspace. If cmux is unavailable or declines the request, Studio falls back to the system browser.
+- When Pi runs inside Muxy or cmux, Studio opens in that terminal app’s built-in browser. Muxy is detected from its pane/socket environment without installing global hooks; cmux targets and focuses the caller’s workspace. If the detected terminal browser is unavailable, disabled, or declines the request, Studio falls back once to the system browser.
 - For remote SSH sessions, keep Studio bound to localhost and use SSH local port forwarding; `/studio` and `/studio --status` print the full tokenized localhost URL. The SSH hint repeats the full URL so it is visible even if your terminal only shows the latest notification. Open that URL through the tunnel, preserving the `?token=...` parameter. If SSH is not auto-detected, use `/studio --no-browser`; for stable forwarding, use `/studio --port <port>` or combine them, e.g. `/studio --no-browser --port 3417`.
 - Full Studio is a singleton per Pi session: use `/studio` to open it, `/studio-replace` to explicitly replace it, and `/studio-editor-only` for extra editing/preview tabs that do not take over the full Studio session view.
 - Studio is designed as a complement to terminal pi, not a replacement.

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

@@ -108,6 +108,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);
 
@@ -10563,6 +10564,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 +10988,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 +14604,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 +14627,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.44",
+  "version": "0.9.46",
   "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-browser-launcher.js

@@ -1,6 +1,40 @@
 import { spawn } from "node:child_process";
 
-export const STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS = 5_000;
+export const STUDIO_TERMINAL_BROWSER_OPEN_TIMEOUT_MS = 5_000;
+export const STUDIO_MUXY_CLI_TIMEOUT_SECONDS = 4;
+// Retain the original exported name for callers that imported the cmux-only helper.
+export const STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS = STUDIO_TERMINAL_BROWSER_OPEN_TIMEOUT_MS;
+
+/** @param {NodeJS.ProcessEnv | Record<string, string | undefined>} env */
+function isStudioNestedZedTerminal(env) {
+	const zedTerm = String(env.ZED_TERM ?? "").trim().toLowerCase();
+	return zedTerm === "1" || zedTerm === "true";
+}
+
+/**
+ * Detect whether the current process is running inside Muxy itself rather than
+ * a nested application terminal that inherited Muxy's environment.
+ *
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function isStudioMuxySession(env = process.env) {
+	const paneId = String(env.MUXY_PANE_ID ?? "").trim();
+	const socketPath = String(env.MUXY_SOCKET_PATH ?? "").trim();
+	return Boolean(paneId && socketPath && !isStudioNestedZedTerminal(env));
+}
+
+/**
+ * Build the Muxy CLI invocation for opening Studio in its built-in browser.
+ *
+ * @param {string} target
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {{ command: string, args: string[] } | undefined}
+ */
+export function getStudioMuxyBrowserOpenCommand(target, env = process.env) {
+	if (!isStudioMuxySession(env)) return undefined;
+	return { command: "muxy", args: ["browser", "open", target] };
+}
 
 /**
  * Detect whether the current process is running inside cmux.
@@ -9,6 +43,7 @@ export const STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS = 5_000;
  * @returns {boolean}
  */
 export function isStudioCmuxSession(env = process.env) {
+	if (isStudioNestedZedTerminal(env)) return false;
 	const workspaceId = String(env.CMUX_WORKSPACE_ID ?? "").trim();
 	const termProgram = String(env.TERM_PROGRAM ?? "").trim().toLowerCase();
 	const term = String(env.TERM ?? "").trim().toLowerCase();
@@ -73,24 +108,23 @@ function spawnDetachedBrowser(openCommand, spawnProcess) {
 }
 
 /**
- * Try to open Studio in a focused cmux browser surface.
+ * Try a terminal application's bounded browser-open command.
  *
- * @param {string} target
+ * @param {{ command: string, args: string[] } | undefined} openCommand
  * @param {{
- *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
  *   spawnProcess?: typeof spawn,
  *   timeoutMs?: number,
+ *   spawnEnv?: NodeJS.ProcessEnv | Record<string, string | undefined>,
  * }} [options]
  * @returns {Promise<boolean>}
  */
-export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
-	const openCommand = getStudioCmuxBrowserOpenCommand(target, options.env ?? process.env);
+async function tryOpenStudioUrlWithTerminalBrowser(openCommand, options = {}) {
 	if (!openCommand) return false;
 
 	const spawnProcess = options.spawnProcess ?? spawn;
 	const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs >= 0
 		? options.timeoutMs
-		: STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS;
+		: STUDIO_TERMINAL_BROWSER_OPEN_TIMEOUT_MS;
 
 	return await new Promise((resolve) => {
 		let settled = false;
@@ -108,7 +142,10 @@ export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
 		timeout.unref?.();
 
 		try {
-			child = spawnProcess(openCommand.command, openCommand.args, { stdio: "ignore" });
+			const spawnOptions = options.spawnEnv
+				? { stdio: "ignore", env: options.spawnEnv }
+				: { stdio: "ignore" };
+			child = spawnProcess(openCommand.command, openCommand.args, spawnOptions);
 		} catch {
 			finish(false);
 			return;
@@ -119,7 +156,47 @@ export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
 }
 
 /**
- * Open Studio in cmux when available, falling back to the system browser.
+ * Try to open Studio in Muxy's built-in browser.
+ *
+ * @param {string} target
+ * @param {{
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   spawnProcess?: typeof spawn,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function tryOpenStudioUrlInMuxyBrowser(target, options = {}) {
+	const env = options.env ?? process.env;
+	const openCommand = getStudioMuxyBrowserOpenCommand(target, env);
+	return await tryOpenStudioUrlWithTerminalBrowser(openCommand, {
+		...options,
+		spawnEnv: {
+			...env,
+			MUXY_CLI_TIMEOUT: String(STUDIO_MUXY_CLI_TIMEOUT_SECONDS),
+		},
+	});
+}
+
+/**
+ * Try to open Studio in a focused cmux browser surface.
+ *
+ * @param {string} target
+ * @param {{
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   spawnProcess?: typeof spawn,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
+	const openCommand = getStudioCmuxBrowserOpenCommand(target, options.env ?? process.env);
+	return await tryOpenStudioUrlWithTerminalBrowser(openCommand, options);
+}
+
+/**
+ * Open Studio in the caller's supported terminal browser when available,
+ * falling back once to the system browser.
  *
  * @param {string} target
  * @param {{
@@ -128,10 +205,15 @@ export async function tryOpenStudioUrlInCmuxBrowser(target, options = {}) {
  *   spawnProcess?: typeof spawn,
  *   timeoutMs?: number,
  * }} [options]
- * @returns {Promise<"cmux" | "system">}
+ * @returns {Promise<"muxy" | "cmux" | "system">}
  */
 export async function openStudioUrlInBrowser(target, options = {}) {
-	if (await tryOpenStudioUrlInCmuxBrowser(target, options)) return "cmux";
+	const env = options.env ?? process.env;
+	if (isStudioMuxySession(env)) {
+		if (await tryOpenStudioUrlInMuxyBrowser(target, options)) return "muxy";
+	} else if (isStudioCmuxSession(env)) {
+		if (await tryOpenStudioUrlInCmuxBrowser(target, options)) return "cmux";
+	}
 
 	const openCommand = getStudioDefaultBrowserOpenCommand(target, options.platform ?? process.platform);
 	await spawnDetachedBrowser(openCommand, options.spawnProcess ?? spawn);