pi-studio 0.9.41 → 0.9.42

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.42] — 2026-08-11
+
+### Changed
+- Open Studio as a focused cmux browser surface in the caller’s workspace when launched from cmux, with a bounded system-browser fallback when cmux is unavailable or declines the request.
+
 ## [0.9.41] — 2026-08-11
 
 ### Fixed

package/README.md

@@ -63,7 +63,7 @@ _The video shows an earlier version of the Studio interface. The basic workflow
 
 | Command | Description |
 |---|---|
-| `/studio` | Open with last assistant response (fallback: blank) |
+| `/studio` | Open in 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,6 +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.
 - 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/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 { 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";
 import {
@@ -7544,27 +7545,6 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 	}
 }
 
-function openUrlInDefaultBrowser(url: string): Promise<void> {
-	const openCommand =
-		process.platform === "darwin"
-			? { command: "open", args: [url] }
-			: process.platform === "win32"
-				? { command: "cmd", args: ["/c", "start", "", url] }
-				: { command: "xdg-open", args: [url] };
-
-	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 openPathInDefaultViewer(path: string): Promise<void> {
 	const openCommand =
 		process.platform === "darwin"
@@ -11328,14 +11308,7 @@ export default function (pi: ExtensionAPI) {
 		return null;
 	};
 
-	const isProbablyCmuxSession = (): boolean => {
-		const workspaceId = String(process.env.CMUX_WORKSPACE_ID ?? "").trim();
-		if (workspaceId) return true;
-		const termProgram = String(process.env.TERM_PROGRAM ?? "").trim().toLowerCase();
-		if (termProgram === "cmux") return true;
-		const term = String(process.env.TERM ?? "").trim().toLowerCase();
-		return term.includes("cmux");
-	};
+	const isProbablyCmuxSession = (): boolean => isStudioCmuxSession(process.env);
 
 	const sanitizeTerminalNotificationText = (value: string, maxLength = 240): string => {
 		const sanitized = String(value)
@@ -15836,7 +15809,7 @@ export default function (pi: ExtensionAPI) {
 				const skipReason = launchOpenFlags.noBrowser ? "--no-browser was used" : "SSH was detected";
 				ctx.ui.notify(`${openedLabel} is ready. Browser auto-open was skipped because ${skipReason}.`, "info");
 			} else {
-				await openUrlInDefaultBrowser(url);
+				await openStudioUrlInBrowser(url);
 				if (selected.source === "file") {
 					ctx.ui.notify(`Opened ${openedLabel} with file loaded: ${selected.label}`, "info");
 				} else if (selected.source === "last-response") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.41",
+  "version": "0.9.42",
   "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

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+
+export const STUDIO_CMUX_BROWSER_OPEN_TIMEOUT_MS = 5_000;
+
+/**
+ * Detect whether the current process is running inside cmux.
+ *
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function isStudioCmuxSession(env = process.env) {
+	const workspaceId = String(env.CMUX_WORKSPACE_ID ?? "").trim();
+	const termProgram = String(env.TERM_PROGRAM ?? "").trim().toLowerCase();
+	const term = String(env.TERM ?? "").trim().toLowerCase();
+	const bundleId = String(env.CMUX_BUNDLE_ID ?? "").trim().toLowerCase();
+	return Boolean(workspaceId || termProgram === "cmux" || term.includes("cmux") || bundleId.includes("cmux"));
+}
+
+/**
+ * Build the cmux CLI invocation for opening Studio in the caller's workspace.
+ *
+ * @param {string} target
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {{ command: string, args: string[] } | undefined}
+ */
+export function getStudioCmuxBrowserOpenCommand(target, env = process.env) {
+	if (!isStudioCmuxSession(env)) return undefined;
+
+	const workspaceId = String(env.CMUX_WORKSPACE_ID ?? "").trim();
+	const command = String(env.CMUX_BUNDLED_CLI_PATH ?? "").trim() || "cmux";
+	const args = ["browser", "open", target];
+	if (workspaceId) args.push("--workspace", workspaceId);
+	args.push("--focus", "true");
+	return { command, args };
+}
+
+/**
+ * Build the platform-native system-browser invocation.
+ *
+ * @param {string} target
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function getStudioDefaultBrowserOpenCommand(target, platform = process.platform) {
+	if (platform === "darwin") return { command: "open", args: [target] };
+	if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", target] };
+	return { command: "xdg-open", args: [target] };
+}
+
+/**
+ * @param {{ command: string, args: string[] }} openCommand
+ * @param {typeof spawn} spawnProcess
+ * @returns {Promise<void>}
+ */
+function spawnDetachedBrowser(openCommand, spawnProcess) {
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = spawnProcess(openCommand.command, openCommand.args, {
+				stdio: "ignore",
+				detached: true,
+			});
+		} catch (error) {
+			reject(error);
+			return;
+		}
+		child.once("error", reject);
+		child.once("spawn", () => {
+			child.unref();
+			resolve();
+		});
+	});
+}
+
+/**
+ * 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);
+	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;
+
+	return await new Promise((resolve) => {
+		let settled = false;
+		let child;
+		const finish = (opened) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			resolve(opened);
+		};
+		const timeout = setTimeout(() => {
+			child?.kill();
+			finish(false);
+		}, timeoutMs);
+		timeout.unref?.();
+
+		try {
+			child = spawnProcess(openCommand.command, openCommand.args, { stdio: "ignore" });
+		} catch {
+			finish(false);
+			return;
+		}
+		child.once("error", () => finish(false));
+		child.once("close", (code) => finish(code === 0));
+	});
+}
+
+/**
+ * Open Studio in cmux when available, falling back to the system browser.
+ *
+ * @param {string} target
+ * @param {{
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   platform?: NodeJS.Platform,
+ *   spawnProcess?: typeof spawn,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {Promise<"cmux" | "system">}
+ */
+export async function openStudioUrlInBrowser(target, options = {}) {
+	if (await tryOpenStudioUrlInCmuxBrowser(target, options)) return "cmux";
+
+	const openCommand = getStudioDefaultBrowserOpenCommand(target, options.platform ?? process.platform);
+	await spawnDetachedBrowser(openCommand, options.spawnProcess ?? spawn);
+	return "system";
+}