pi-studio 0.9.63 → 0.10.1

package/shared/studio-editor-mode.js

@@ -0,0 +1,48 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// Oliver, 13 Oct: dual editor mode (Prompt and Document) is the default; single editor
+// mode is the earlier one-editor Studio. The choice is kept per Pi profile. The older
+// development flags, when any is set, still decide everything, as before.
+export const STUDIO_EDITOR_MODE_ENV = ["PI_STUDIO_BUFFER_RECOVERY", "PI_STUDIO_BUFFER_SWITCHING", "PI_STUDIO_DOCUMENT_HOSTING"];
+
+export function resolveStudioEditorFlags(env, savedMode) {
+	const forced = STUDIO_EDITOR_MODE_ENV.some(key => typeof env[key] === "string" && env[key] !== "");
+	const recovery = forced ? env.PI_STUDIO_BUFFER_RECOVERY === "1" : savedMode !== "single";
+	const switching = recovery && (!forced || env.PI_STUDIO_BUFFER_SWITCHING === "1");
+	const hosting = switching && (!forced || env.PI_STUDIO_DOCUMENT_HOSTING === "1");
+	return { forced, recovery, switching, hosting, mode: hosting ? "dual" : "single" };
+}
+
+export function readStudioEditorMode(path) {
+	try {
+		const mode = JSON.parse(readFileSync(path, "utf8"))?.mode;
+		return mode === "single" || mode === "dual" ? mode : null;
+	} catch { return null; }
+}
+
+export function writeStudioEditorMode(path, mode) {
+	if (mode !== "single" && mode !== "dual") throw new Error("Unknown editor mode.");
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = path + "." + process.pid + ".tmp";
+	writeFileSync(temporary, JSON.stringify({ mode }) + "\n", "utf8");
+	renameSync(temporary, path);
+}
+
+// Starting, stopping and switching Studio take turns (Sol, candidate69). run() queues at
+// once, so a caller that checked pending() and then queued can't be overtaken.
+export function createStudioTurns() {
+	/** @type {Promise<unknown>} */
+	let tail = Promise.resolve();
+	let pending = 0;
+	return Object.freeze({
+		/** @template T @param {() => Promise<T>} operation @returns {Promise<T>} */
+		run(operation) {
+			pending += 1;
+			const turn = tail.then(operation).finally(() => { pending -= 1; });
+			tail = turn.catch(() => undefined);
+			return turn;
+		},
+		pending: () => pending,
+	});
+}

package/shared/studio-linked-reader-ui.js

@@ -0,0 +1,232 @@
+import { createStudioLinkedReader } from "./studio-linked-reader.js";
+
+// A reading surface, not an editor or a second owner of the underlying buffers.
+// Application callbacks keep resource grants and guarded editing in one place.
+export function createStudioLinkedReaderUi(options) {
+	const { document, window, host, root, footer, select, header, metadata } = options;
+	const history = createStudioLinkedReader();
+	let disposed = false, owner = null, ownerPage = null, renderSequence = 0;
+	const make = (tag, name, text) => {
+		const element = document.createElement(tag); element.className = name;
+		if (text) element.textContent = text;
+		return element;
+	};
+	const toolbar = make("div", "studio-reader-toolbar");
+	toolbar.hidden = true; toolbar.setAttribute("aria-label", "Linked file navigation");
+	const surface = make("div", "studio-reader-surface"); surface.hidden = true;
+	const content = make("div", "panel-scroll rendered-markdown studio-reader-content");
+	content.id = "studioLinkedReaderContent"; content.setAttribute("tabindex", "0");
+	surface.append(content); host.insertBefore(toolbar, metadata || root); host.append(surface);
+	const button = (label, fn, group = toolbar) => {
+		const element = make("button", "studio-reader-action", label); element.type = "button";
+		element.addEventListener("click", () => { void fn(); }); group.append(element); return element;
+	};
+	const backButton = button("Back", back), forwardButton = button("Forward", forward);
+	const snapshotLabel = make("span", "studio-reader-snapshot", ""); toolbar.append(snapshotLabel);
+	const refreshButton = button("Refresh", refresh);
+	refreshButton.title = "Read this file again.";
+	const actions = make("div", "studio-reader-actions"); toolbar.append(actions);
+	const editButton = button("Checking editor…", () => openForEdit(), actions);
+	// Matches the Files row (Oliver, 10 Oct): a file open nowhere yet can go to either buffer.
+	const promptButton = button("Open in Prompt", () => openForEdit("prompt"), actions);
+	const returnButton = button("Return", () => close({ restore: true }), actions);
+	const temporaryOption = make("option", "", "");
+	temporaryOption.value = ""; temporaryOption.disabled = true; temporaryOption.dataset.linkedReaderOption = "1";
+	const previousRootInert = Boolean(root.inert), previousFooterInert = Boolean(footer?.inert), previousMetadataInert = Boolean(metadata?.inert);
+	const warn = error => options.report?.(error?.message || String(error || "Could not read this file."));
+	const active = () => history.snapshot().active;
+	const current = page => !disposed && history.isCurrent(page);
+	const context = () => {
+		const page = history.snapshot().current;
+		return page ? { sourcePath: page.path, resourceDir: page.resourceDir, isCurrent: () => current(page) } : null;
+	};
+	function layout() {
+		if (disposed || !active()) return;
+		const pane = host.getBoundingClientRect(), heading = (header || root).getBoundingClientRect();
+		toolbar.style.top = Math.max(0, (header ? heading.bottom : heading.top) - pane.top - (host.clientTop || 0)) + "px";
+		const bar = toolbar.getBoundingClientRect();
+		surface.style.top = Math.max(0, bar.bottom - pane.top - (host.clientTop || 0)) + "px";
+	}
+	function displayLabel(page, state) {
+		const parts = path => String(path || "").replace(/\\/g, "/").split("/").filter(Boolean);
+		const pathParts = parts(page.path), name = pathParts.at(-1) || page.label;
+		const matches = state.entries.filter(entry => parts(entry.path).at(-1) === name);
+		const originMatches = parts(state.origin?.path).at(-1) === name;
+		if (matches.length < 2 && !originMatches) return name;
+		const others = [...new Set([...matches.map(entry => entry.path), ...(originMatches ? [state.origin.path] : [])])].filter(path => path !== page.path);
+		for (let count = 2; count <= pathParts.length; count++) {
+			const label = pathParts.slice(-count).join("/");
+			if (!others.some(path => parts(path).slice(-count).join("/") === label)) return label;
+		}
+		return page.path;
+	}
+	function sync() {
+		if (disposed) return;
+		const state = history.snapshot(), reading = state.active, page = state.current;
+		host.dataset.linkedReaderActive = reading ? "1" : "0";
+		toolbar.hidden = !state.entries.length;
+		surface.hidden = !reading;
+		root.inert = reading || previousRootInert;
+		if (footer) footer.inert = reading || previousFooterInert;
+		if (metadata) metadata.inert = reading || previousMetadataInert;
+		if (reading) {
+			root.setAttribute("aria-hidden", "true"); footer?.setAttribute("aria-hidden", "true"); metadata?.setAttribute("aria-hidden", "true");
+			if (temporaryOption.parentElement !== select) select.append(temporaryOption);
+			temporaryOption.textContent = displayLabel(page, state); select.value = "";
+			select.title = page.path + " · Read-only snapshot.";
+			const date = new Date(page.readAt);
+			snapshotLabel.textContent = "Read-only · saved file as of " + date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", hour12: false });
+			snapshotLabel.title = "Saved file read at " + date.toLocaleString() + ". Refresh to read it again.";
+		} else {
+			root.removeAttribute("aria-hidden"); footer?.removeAttribute("aria-hidden"); metadata?.removeAttribute("aria-hidden"); temporaryOption.remove();
+			toolbar.style.top = "";
+		}
+		const rootLabel = options.originLabel(state.origin) || "current view";
+		const rootTitle = options.originTitle?.(state.origin) || rootLabel;
+		backButton.textContent = "← " + (state.back ? displayLabel(state.back, state) : rootLabel);
+		backButton.title = state.back?.path || rootTitle;
+		backButton.hidden = !reading; backButton.disabled = !reading;
+		forwardButton.textContent = (state.forward ? displayLabel(state.forward, state) : "Forward") + " →";
+		forwardButton.title = state.forward?.path || "";
+		forwardButton.hidden = !state.forward; forwardButton.disabled = !state.forward;
+		refreshButton.hidden = !reading; refreshButton.disabled = !reading || Boolean(state.pending);
+		editButton.hidden = !reading;
+		editButton.textContent = ownerPage === page?.id && owner ? owner.label : "Checking editor…";
+		editButton.disabled = !reading || Boolean(state.pending) || ownerPage !== page?.id || !owner || owner.disabled === true || options.editingBusy?.() === true;
+		promptButton.hidden = !reading || ownerPage !== page?.id || owner?.kind !== "new" || options.canOpenInPrompt?.() !== true;
+		promptButton.disabled = editButton.disabled;
+		returnButton.textContent = reading ? "Return to " + rootLabel : "Close";
+		returnButton.title = reading ? "Leave this reading history for " + rootTitle + "." : "Forget this reading history.";
+		snapshotLabel.hidden = !reading; layout();
+	}
+	const changed = () => { sync(); options.changed?.(); };
+	function rememberPosition() {
+		if (active() && !content.inert) history.rememberPosition({ top: content.scrollTop, left: content.scrollLeft });
+	}
+	content.addEventListener("scroll", rememberPosition);
+	function signature(value) {
+		return value ? JSON.stringify([value.kind, value.label || "", value.workspaceId || "", value.bufferId || "", value.disabled === true]) : "";
+	}
+	async function checkOwner(page) {
+		try {
+			const result = await options.findOwner(page);
+			if (!current(page)) return;
+			owner = result; ownerPage = page.id; sync();
+		} catch (error) {
+			if (!current(page)) return;
+			owner = { kind: "unavailable", label: "Editor unavailable", disabled: true }; ownerPage = page.id;
+			sync(); warn(error);
+		}
+	}
+	async function renderPage() {
+		const page = history.snapshot().current;
+		if (!page || disposed) return;
+		const sequence = ++renderSequence;
+		owner = null; ownerPage = null;
+		content.inert = true; content.replaceChildren(); content.scrollTop = 0; content.scrollLeft = 0;
+		const loading = make("div", "preview-loading", "Reading " + page.label + "…"); content.append(loading);
+		changed();
+		const stillCurrent = () => sequence === renderSequence && current(page);
+		const ownerCheck = checkOwner(page);
+		try {
+			await options.render(content, page, stillCurrent);
+			if (!stillCurrent()) return;
+			content.inert = false;
+			const saved = history.snapshot().current.position;
+			content.scrollTop = saved.top; content.scrollLeft = saved.left;
+			if (page.fragment && saved.top === 0) {
+				let fragment = page.fragment; try { fragment = decodeURIComponent(fragment); } catch {}
+				const heading = Array.from(content.querySelectorAll?.("[id]") || []).find(el => el.id === fragment);
+				// Do not scroll the page/editor or move focus while reading.
+				if (heading) content.scrollTop = Math.max(0, heading.getBoundingClientRect().top - content.getBoundingClientRect().top + content.scrollTop);
+			}
+		} catch (error) { if (stillCurrent()) { content.inert = false; warn(error); } }
+		await ownerCheck;
+		if (stillCurrent()) sync();
+	}
+	async function read(href, suppliedContext, settings = {}) {
+		if (disposed || !options.contextIsCurrent(suppliedContext)) return false;
+		rememberPosition();
+		const origin = options.captureOrigin(suppliedContext);
+		const ticket = history.begin(origin, settings);
+		if (!ticket) return false;
+		const isCurrent = () => !disposed && history.snapshot().pending === ticket && options.contextIsCurrent(suppliedContext);
+		const requestContext = { ...(suppliedContext || {}), isCurrent };
+		changed();
+		try {
+			const payload = await options.read(href, requestContext);
+			if (!isCurrent()) { history.cancel(ticket); return false; }
+			const fragment = String(href || "").split("#").slice(1).join("#");
+			const result = history.commit(ticket, { ...payload, fragment });
+			if (!result.ok) { warn(result.message); return false; }
+			await renderPage(); return true;
+		} catch (error) {
+			const owned = history.snapshot().pending === ticket;
+			history.cancel(ticket);
+			if (owned && !error?.studioCancelled && options.contextIsCurrent(suppliedContext) && !disposed) warn(error);
+			return false;
+		} finally { changed(); }
+	}
+	async function refresh() {
+		const page = history.snapshot().current;
+		if (!page) return false;
+		// page.path is literal; read() takes a link, so keep "#", "?" and "%" in the name.
+		return read(String(page.path).replace(/[%#?]/g, ch => encodeURIComponent(ch)), context(), { refresh: true });
+	}
+	async function back() {
+		rememberPosition();
+		const result = history.back();
+		if (!result.ok) return false;
+		if (result.left) { renderSequence++; changed(); await options.returnToOrigin(result.origin); sync(); }
+		else await renderPage();
+		return true;
+	}
+	async function forward() {
+		rememberPosition();
+		if (!history.forward().ok) return false;
+		await renderPage(); return true;
+	}
+	async function close(settings = {}) {
+		rememberPosition();
+		const wasActive = active(), origin = history.close(); renderSequence++;
+		owner = null; ownerPage = null; content.replaceChildren(); changed();
+		if (wasActive) {
+			if (settings.restore && origin) await options.returnToOrigin(origin);
+			else if (settings.manual === true) options.manualLeave();
+		}
+		sync();
+	}
+	async function openForEdit(role = "document") {
+		const page = history.snapshot().current, displayed = owner;
+		if (!page || !displayed || displayed.disabled || history.snapshot().pending || options.editingBusy?.()) return false;
+		try {
+			const checked = await options.findOwner(page);
+			if (!current(page)) return false;
+			if (signature(checked) !== signature(displayed)) {
+				owner = checked; ownerPage = page.id; sync();
+				warn("The editing destination changed. Check the action and choose it again."); return false;
+			}
+			const opened = await options.openForEdit(page, checked, () => current(page), role);
+			if (opened && current(page)) await close({ restore: false, manual: true });
+			return Boolean(opened);
+		} catch (error) { if (current(page)) warn(error); return false; }
+	}
+	const observer = typeof window.ResizeObserver === "function" ? new window.ResizeObserver(layout) : null;
+	observer?.observe(host); observer?.observe(toolbar); if (header) observer?.observe(header);
+	window.addEventListener("resize", layout);
+	function revealFragment(fragment) {
+		if (!active() || content.inert) return false;
+		let id = fragment; try { id = decodeURIComponent(id); } catch {}
+		const target = Array.from(content.querySelectorAll?.("[id]") || []).find(el => el.id === id);
+		if (!target) return false;
+		content.scrollTop = Math.max(0, target.getBoundingClientRect().top - content.getBoundingClientRect().top + content.scrollTop);
+		rememberPosition(); return true;
+	}
+	function dispose() {
+		if (disposed) return;
+		void close({ restore: false }); disposed = true; observer?.disconnect();
+		window.removeEventListener("resize", layout); toolbar.remove(); surface.remove(); temporaryOption.remove();
+	}
+	return Object.freeze({ read, refresh, back, forward, close, openForEdit, sync, context, revealFragment, dispose,
+		snapshot: () => history.snapshot(), isCurrent: current, contentElement: content });
+}

package/shared/studio-linked-reader.js

@@ -0,0 +1,110 @@
+// Bounded, page-local reading history. These snapshots are never editable
+// buffers, filesystem grants, save receipts or recovered workspace authority.
+export function createStudioLinkedReader(options = {}) {
+	const limit = (value, fallback, maximum) => Number.isSafeInteger(value) && value > 0
+		? Math.min(value, maximum) : fallback;
+	const maxEntries = limit(options.maxEntries, 24, 100);
+	const maxCharacters = limit(options.maxCharacters, 2700000, 2700000);
+	const maxEntryCharacters = limit(options.maxEntryCharacters, 900000, 900000);
+	const now = typeof options.now === "function" ? options.now : Date.now;
+	let entries = [], index = -1, origin = null, pending = null, sequence = 0, nextId = 0;
+	const current = () => index >= 0 ? entries[index] : null;
+	const position = value => Object.freeze({
+		top: Number.isFinite(value?.top) ? Math.max(0, Math.min(100000000, value.top)) : 0,
+		left: Number.isFinite(value?.left) ? Math.max(0, Math.min(100000000, value.left)) : 0,
+	});
+	const validString = (value, maximum) => typeof value === "string" && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value);
+	const originCopy = value => value && ["editor", "response", "files", "view"].includes(value.kind)
+		? Object.freeze({ ...value }) : null;
+	const invalidate = () => { pending = null; sequence++; };
+	const owns = ticket => Boolean(ticket && ticket === pending && ticket.sequence === sequence);
+	const failure = message => ({ ok: false, message });
+
+	function begin(nextOrigin, settings = {}) {
+		const refresh = settings.refresh === true;
+		if (refresh && !current()) return null;
+		// A visit while reading always belongs to that reading session's root,
+		// irrespective of changes to the editor or hidden response beneath it.
+		const root = current() || refresh ? origin : originCopy(nextOrigin) || origin;
+		if (!root) return null;
+		invalidate();
+		pending = Object.freeze({ sequence, refresh, origin: root, targetId: current()?.id ?? null,
+			newRoot: !current() && root !== origin });
+		return pending;
+	}
+
+	function commit(ticket, value) {
+		if (!owns(ticket)) return failure("This reading request is no longer current.");
+		pending = null;
+		if (!value || !validString(value.path, 4096) || !value.path
+			|| !/^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value.path)
+			|| typeof value.text !== "string") return failure("The file snapshot could not be prepared.");
+		if (value.text.length > maxEntryCharacters) return failure("This file exceeds the reader's text limit.");
+		const selected = current();
+		if (ticket.refresh && (!selected || selected.id !== ticket.targetId || selected.path !== value.path)) {
+			return failure("The file identity changed while refreshing. Kept the current snapshot.");
+		}
+		const trail = ticket.newRoot ? [] : ticket.refresh ? entries.slice() : entries.slice(0, index + 1);
+		const nextCount = trail.length + (ticket.refresh ? 0 : 1);
+		const characters = trail.reduce((total, item) => total + item.text.length, 0)
+			- (ticket.refresh ? selected.text.length : 0) + value.text.length;
+		if (nextCount > maxEntries || characters > maxCharacters) {
+			return failure("Reader history is full. Kept the current snapshots; close the reader to start a new history.");
+		}
+		const name = value.path.replace(/\\/g, "/").split("/").pop() || "file";
+		const item = Object.freeze({
+			id: ticket.refresh ? selected.id : ++nextId,
+			revision: ticket.refresh ? selected.revision + 1 : 1,
+			path: value.path,
+			label: validString(value.label, 512) && value.label ? value.label : name,
+			text: value.text,
+			resourceDir: validString(value.resourceDir, 4096) ? value.resourceDir : "",
+			extension: validString(value.extension, 32) ? value.extension : "",
+			fragment: ticket.refresh ? selected.fragment : validString(value.fragment, 1024) ? value.fragment : "",
+			position: ticket.refresh ? selected.position : position(null),
+			readAt: now(),
+		});
+		if (ticket.refresh) trail[index] = item;
+		else { trail.push(item); index = trail.length - 1; }
+		entries = trail;
+		origin = ticket.origin;
+		return { ok: true, current: item };
+	}
+
+	function cancel(ticket) {
+		if (!owns(ticket)) return false;
+		invalidate(); return true;
+	}
+	function rememberPosition(value) {
+		const selected = current();
+		if (!selected) return false;
+		entries[index] = Object.freeze({ ...selected, position: position(value) });
+		return true;
+	}
+	function back() {
+		if (!current()) return failure("There is no earlier reading location.");
+		invalidate(); index--;
+		return { ok: true, left: index < 0, origin, current: current() };
+	}
+	function forward() {
+		if (index + 1 >= entries.length) return failure("There is no later reading location.");
+		invalidate(); index++;
+		return { ok: true, left: false, current: current() };
+	}
+	function close() {
+		const root = origin;
+		invalidate(); entries = []; index = -1; origin = null;
+		return root;
+	}
+	function snapshot() {
+		return Object.freeze({ active: index >= 0, origin, index, current: current(),
+			entries: Object.freeze(entries.slice()), pending,
+			back: index > 0 ? entries[index - 1] : null,
+			forward: entries[index + 1] || null });
+	}
+	function isCurrent(item) {
+		const selected = current();
+		return Boolean(selected && item && selected.id === item.id && selected.revision === item.revision);
+	}
+	return Object.freeze({ begin, commit, cancel, rememberPosition, back, forward, close, snapshot, isCurrent });
+}

package/shared/studio-metadata-write-order.js

@@ -0,0 +1,35 @@
+// In-flight fetch and sendBeacon requests can reach the server out of order.
+// Keep last-arrival behavior between different pages, but never let an older
+// write from the same Studio tab overwrite one of its newer persisted snapshots.
+export function createStudioMetadataWriteOrderTracker() {
+	const versions = new Map();
+
+	function prepare(kind, documentKey, ownership) {
+		if (!ownership) return Object.freeze({ commit() {} });
+		const writerId = String(ownership.writerId || "");
+		const writeVersion = Number(ownership.writeVersion);
+		if (!writerId || !Number.isSafeInteger(writeVersion) || writeVersion <= 0) return null;
+		const key = JSON.stringify([String(kind || ""), String(documentKey || ""), writerId]);
+		const previous = versions.get(key);
+		if (previous !== undefined && writeVersion < previous) return null;
+		let committed = false;
+		return Object.freeze({
+			commit() {
+				if (committed) return;
+				committed = true;
+				const current = versions.get(key);
+				if (current === undefined || writeVersion >= current) versions.set(key, writeVersion);
+			},
+		});
+	}
+
+	return Object.freeze({
+		prepare,
+		claim(kind, documentKey, ownership) {
+			const prepared = prepare(kind, documentKey, ownership);
+			if (!prepared) return false;
+			prepared.commit();
+			return true;
+		},
+	});
+}

package/shared/studio-read-only-media.js

@@ -0,0 +1,24 @@
+// Read-only transport/view chrome only. Neither helper grants resources,
+// registers a workspace nor attaches a file to an editable buffer.
+/** @param {{token: string, kind: string, path: string, resourceDir?: string, page?: number | null}} options */
+export function buildStudioReadOnlyMediaUrl({ token, kind, path, resourceDir = "", page = null }) {
+ if (!["pdf", "image"].includes(kind) || typeof token !== "string" || !token || token.length > 512
+  || typeof path !== "string" || !/^(\/|[a-zA-Z]:[\\/])/.test(path) || path.length > 16384 || path.includes("\0")) throw Error("A resolved local PDF/image and authenticated token are required.");
+ // The receiving media resolvers accept a URI reference AFTER query decoding.
+ // Preserve this already-resolved literal filename through that second layer:
+ // URLSearchParams must not expose literal #/? or percent escapes to its decoder.
+ const params = new URLSearchParams({ token, path: encodeURIComponent(path), resourceDir });
+ return (kind === "pdf" ? "/pdf-resource?" : "/image-viewer?") + params.toString()
+  + (kind === "pdf" && Number.isSafeInteger(page) && page > 0 ? "#page=" + page : "");
+}
+export function buildStudioReadOnlyImagePage({ label, dataUrl, nonce }) {
+ if (typeof nonce !== "string" || !/^[a-f0-9]{32,64}$/.test(nonce)) throw Error("A fresh image-page nonce is required.");
+ if (typeof dataUrl !== "string" || !/^data:image\/(?:png|jpeg|gif|webp|svg\+xml);base64,[A-Za-z0-9+/]*={0,2}$/.test(dataUrl)) throw Error("Only supported image data may be shown in the image viewer.");
+ const escape = value => String(value || "Image").replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+ const title = escape(label);
+ return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>
+<style nonce="${nonce}">html,body{margin:0;background:#171717;color:#e7e7e7;font:14px system-ui,sans-serif}header{position:sticky;top:0;display:flex;gap:12px;align-items:center;flex-wrap:wrap;padding:12px;background:#222;border-bottom:1px solid #444}h1{font-size:14px;font-weight:600;margin:0;overflow-wrap:anywhere}nav{display:flex;gap:6px}button{font:inherit;padding:5px 12px;background:transparent;color:inherit;border:1px solid #777;border-radius:5px;cursor:pointer}button[aria-pressed="true"]{background:#444}button:focus-visible{outline:2px solid #9bd;outline-offset:2px}.hint{color:#aaa;font-size:12px}main{padding:12px;overflow:auto}img{display:block;margin:auto}body[data-scale="fit"] img{max-width:100%;max-height:calc(100vh - 100px);width:auto;height:auto}body[data-scale="actual"] img{max-width:none;max-height:none}</style></head><body data-scale="fit">
+<header><h1>${title}</h1><nav aria-label="Image size"><button id="mediaFit" type="button" aria-pressed="true">Fit</button><button id="mediaActual" type="button" aria-pressed="false">Actual size</button></nav><span class="hint">Read-only image</span></header>
+<main><img src="${dataUrl}" alt="${title}"></main>
+<script nonce="${nonce}">const fit=document.getElementById("mediaFit"),actual=document.getElementById("mediaActual");function scale(value){document.body.dataset.scale=value;fit.setAttribute("aria-pressed",String(value==="fit"));actual.setAttribute("aria-pressed",String(value==="actual"));}fit.addEventListener("click",()=>scale("fit"));actual.addEventListener("click",()=>scale("actual"));scale("fit");</script></body></html>`;
+}

package/shared/studio-resource-grants.js

@@ -99,6 +99,9 @@ export function createStudioResourceGrantRegistry(options = {}) {
 
 	function grantFile(pathInput, details = {}) {
 		const resolved = canonicalExistingPath(pathInput, fallbackCwd(details), "file");
+		// Producers holding an already-canonical file identity may require exact
+		// equality before registration. A replaced symlink must add no new grant.
+		if (details.expectedCanonicalPath !== undefined && resolved.canonicalPath !== details.expectedCanonicalPath) throw new Error("The exact canonical file identity changed; no grant was added.");
 		return addGrant("file", resolved.canonicalPath, normalizeGrantSource(details.source, "explicit-file"));
 	}
 

package/shared/studio-run-lifecycle.js

@@ -0,0 +1,47 @@
+/**
+ * A Pi agent run outlives a response, request slot, agent_end, and automatic
+ * compaction/retry. Only agent_settled (or session teardown) retires this target.
+ * This ledger holds identity/facts, never prompt text or browser view state.
+ * @typedef {'direct'|'critique'|'show-me'|'annotation'} RunKind
+ * @typedef {{id:string, requestId:string|null, kind:RunKind|null, origin:'studio'|'outside'|'unknown', startedAt:number, stopping:boolean}} Run
+ */
+export function createStudioRunLifecycle({ makeId = () => crypto.randomUUID(), now = () => Date.now() } = {}) {
+  /** @type {Run|null} */
+  let run = null;
+  /** @type {{reason:string, willRetry:boolean}|null} */
+  let compaction = null;
+  /** @type {'outside'|'unknown'} */
+  let inputOrigin = "unknown";
+  /** @param {{id:string,kind:string,startedAt?:number}|null} request */
+  function start(request = null) {
+    if (run) return snapshot(); // an automatic continuation is the same run
+    const owned = request && ["direct", "critique", "show-me", "annotation"].includes(request.kind);
+    run = { id: makeId(), requestId: owned ? request.id : null, kind: owned ? /** @type {RunKind} */ (request.kind) : null,
+      origin: owned ? "studio" : inputOrigin, startedAt: request?.startedAt ?? now(), stopping: false };
+    inputOrigin = "unknown";
+    return snapshot();
+  }
+  function snapshot() {
+    return { run: run ? { ...run, phase: run.stopping ? "stopping" : compaction ? "compacting" : "running", cancellable: run.origin === "studio" && !run.stopping } : null,
+      compaction: compaction ? { ...compaction } : null };
+  }
+  return {
+    start, snapshot,
+    /** Only an SDK input source proves outside origin; missing request IDs do not. @param {string} source */
+    input(source) { inputOrigin = source === "interactive" || source === "rpc" ? "outside" : "unknown"; },
+    /** @param {{reason?:string,willRetry?:boolean}} event */
+    compactStart(event = {}) { compaction = { reason: event.reason || "unknown", willRetry: event.willRetry === true }; },
+    compactEnd() { compaction = null; },
+    settled() { run = null; compaction = null; inputOrigin = "unknown"; },
+    /** Delivery is not settlement. A stale run token cannot stop a later run. */
+    /** @param {string} requestId @param {string|undefined} runId @param {()=>void} deliver */
+    stop(requestId, runId, deliver) {
+      if (!run || run.origin !== "studio" || run.requestId !== requestId || (runId && run.id !== runId)) return { ok: false, message: "That Studio run is no longer the active cancellation target." };
+      if (run.stopping) return { ok: true, kind: run.kind }; // idempotent acknowledgement, not a second abort
+      const target = run;
+      try { deliver(); } catch (error) { return { ok: false, message: "Failed to stop request: " + (error instanceof Error ? error.message : String(error)) }; }
+      if (run === target) target.stopping = true;
+      return { ok: true, kind: target.kind };
+    },
+  };
+}

package/shared/studio-system-theme.js

@@ -0,0 +1,9 @@
+// Pi's "system" theme takes its colours from the terminal. When the terminal
+// reports none, Pi falls back to ANSI palette numbers that only the terminal
+// can draw, so Studio cannot know the real colours (trial48 finding 2).
+export function systemThemeLacksTrueColor(theme) {
+  if (!theme || theme.name !== "system") return false;
+  const read = fn => { try { return String(fn() ?? ""); } catch { return ""; } };
+  const sample = read(() => theme.getFgAnsi("text")) + read(() => theme.getBgAnsi("userMessageBg"));
+  return !/\x1b\[(?:38|48);2;/.test(sample);
+}