pi-studio 0.9.63 → 0.10.1

package/shared/studio-buffer-store.js

@@ -0,0 +1,227 @@
+// Browser-safe model only. Paths/revisions are claims, never filesystem grants or save authority.
+export const STUDIO_BUFFER_LIMITS = Object.freeze({
+	buffers: 16,
+	textChars: 900_000,
+	totalTextChars: 3_000_000, // Includes baselines, not just visible editor text.
+	pendingOperations: 64,
+});
+const ID = /^[a-zA-Z0-9_-]{1,128}$/;
+const WORKSPACE_ID = /^[a-zA-Z0-9_-]{20,128}$/;
+const DISK_REVISION = /^sha256:[a-f0-9]{64}$/;
+const BUFFER_KEYS = ["id", "role", "revision", "text", "baselineText", "sourceState", "diskRevision", "resourceDir", "view", "metadata"];
+const PATCH_KEYS = BUFFER_KEYS.filter((key) => !["id", "role", "revision"].includes(key));
+
+export class StudioBufferStateError extends Error {
+	constructor(reason, message) { super(message); this.name = "StudioBufferStateError"; this.reason = reason; }
+}
+function requireState(condition, reason, message) {
+	if (!condition) throw new StudioBufferStateError(reason, message);
+}
+function object(value, keys, label) {
+	requireState(value && typeof value === "object" && !Array.isArray(value), "invalid-state", `${label} must be an object.`);
+	requireState(Object.keys(value).every((key) => keys.includes(key)), "unknown-field", `${label} has unsupported fields; preserve the original recovery data.`);
+}
+function string(value, max, label, nullable = false) {
+	if (nullable && value === null) return null;
+	requireState(typeof value === "string", "invalid-state", `${label} must be text.`);
+	requireState(value.length <= max, "limit-exceeded", `${label} exceeds its limit; nothing was changed.`);
+	return value;
+}
+function integer(value, label, min = 0) {
+	requireState(Number.isSafeInteger(value) && value >= min, "invalid-state", `${label} must be a safe integer.`);
+	return value;
+}
+function scroll(value) {
+	requireState(typeof value === "number" && Number.isFinite(value) && value >= 0, "invalid-state", "Invalid scroll position.");
+	return value;
+}
+function freeze(value) {
+	if (value && typeof value === "object") { Object.values(value).forEach(freeze); Object.freeze(value); }
+	return value;
+}
+function failure(error) {
+	return { ok: false, reason: error.reason || "invalid-state", message: error instanceof StudioBufferStateError ? error.message : "Invalid buffer state; nothing was changed." };
+}
+function provenance(value) {
+	object(value, ["version", "kind", "responseId", "responseNumber", "annotated"], "Source provenance");
+	requireState(value.version === 1 && value.kind === "response" && typeof value.annotated === "boolean", "invalid-state", "Unsupported source provenance; keep the original recovery data.");
+	const responseId = string(value.responseId, 256, "Response identity", true);
+	requireState(responseId === null || (responseId.length > 0 && !responseId.includes("\0")), "invalid-state", "Invalid response identity.");
+	const responseNumber = value.responseNumber === null ? null : integer(value.responseNumber, "Response position", 1);
+	requireState(responseNumber === null || responseNumber <= 1_000_000_000, "limit-exceeded", "Response position exceeds its limit.");
+	return { version: 1, kind: "response", responseId, responseNumber, annotated: value.annotated };
+}
+function source(value) {
+	object(value, ["source", "label", "path", "draftId", "provenance"], "Source identity");
+	const path = string(value.path, 16_384, "Source path", true);
+	requireState(path === null || (path.length > 0 && !path.includes("\0")), "invalid-state", "Invalid source path.");
+	const draftId = string(value.draftId, 256, "Source draft ID", true);
+	requireState(!path || draftId === null, "invalid-state", "A file source cannot also have a draft identity.");
+	return { source: string(value.source, 100, "Source kind"), label: string(value.label, 4_000, "Source label"), path, draftId,
+		...(Object.prototype.hasOwnProperty.call(value, "provenance") ? { provenance: provenance(value.provenance) } : {}) };
+}
+function buffer(value) {
+	object(value, BUFFER_KEYS, "Buffer");
+	requireState(typeof value.id === "string" && ID.test(value.id), "invalid-state", "Invalid buffer ID.");
+	requireState(["prompt", "document"].includes(value.role), "invalid-state", "Invalid buffer role.");
+	const text = string(value.text, STUDIO_BUFFER_LIMITS.textChars, "Buffer text");
+	const baselineText = string(value.baselineText, STUDIO_BUFFER_LIMITS.textChars, "Buffer baseline", true);
+	const sourceState = source(value.sourceState);
+	requireState(value.diskRevision === null || (typeof value.diskRevision === "string" && DISK_REVISION.test(value.diskRevision)), "invalid-state", "Invalid disk revision.");
+	requireState(sourceState.path !== null || value.diskRevision === null, "invalid-state", "Detached buffers cannot carry a disk revision.");
+	const v = value.view;
+	object(v, ["editorView", "rightView", "editorLanguage", "selectionStart", "selectionEnd", "selectionDirection", "scrollTop", "previewScrollTop", "rightScrollTop", "followLatest", "responseHistoryIndex"], "Buffer view");
+	const start = integer(v.selectionStart, "Selection start");
+	const end = integer(v.selectionEnd, "Selection end");
+	requireState(start <= end && end <= text.length, "invalid-state", "Selection lies outside the buffer.");
+	requireState(["none", "forward", "backward"].includes(v.selectionDirection) && typeof v.followLatest === "boolean", "invalid-state", "Invalid buffer view state.");
+	const m = value.metadata;
+	object(m, ["annotationsEnabled", "reviewNotesKey", "scratchpadKey"], "Buffer metadata");
+	requireState(m.annotationsEnabled === null || typeof m.annotationsEnabled === "boolean", "invalid-state", "Invalid annotation preference.");
+	return {
+		id: value.id, role: value.role, revision: integer(value.revision, "Buffer revision"), text, baselineText, sourceState,
+		diskRevision: value.diskRevision, resourceDir: string(value.resourceDir, 16_384, "Resource directory"),
+		view: {
+			editorView: string(v.editorView, 100, "Editor view"), rightView: string(v.rightView, 100, "Right view"),
+			editorLanguage: string(v.editorLanguage, 100, "Editor language"), selectionStart: start, selectionEnd: end,
+			selectionDirection: v.selectionDirection, scrollTop: scroll(v.scrollTop), previewScrollTop: scroll(v.previewScrollTop),
+			...(Object.prototype.hasOwnProperty.call(v, "rightScrollTop") ? { rightScrollTop: scroll(v.rightScrollTop) } : {}),
+			followLatest: v.followLatest, responseHistoryIndex: integer(v.responseHistoryIndex, "Response position", -1),
+		},
+		metadata: { annotationsEnabled: m.annotationsEnabled, reviewNotesKey: string(m.reviewNotesKey, 24_000, "Review association", true), scratchpadKey: string(m.scratchpadKey, 24_000, "Scratchpad association", true) },
+	};
+}
+
+export function createStudioBuffer(options) {
+	object(options, BUFFER_KEYS, "New buffer");
+	const path = options.sourceState?.path ?? null;
+	return freeze(buffer({
+		id: options.id, role: options.role, revision: 0, text: "", baselineText: path ? null : "", diskRevision: null, resourceDir: "",
+		...options,
+		sourceState: { source: "blank", label: options.role === "prompt" ? "Prompt" : "Untitled", path, draftId: path ? null : options.id, ...options.sourceState },
+		view: { editorView: "markdown", rightView: options.role === "prompt" ? "preview" : "editor-preview", editorLanguage: "markdown",
+			selectionStart: 0, selectionEnd: 0, selectionDirection: "none", scrollTop: 0, previewScrollTop: 0, followLatest: false, responseHistoryIndex: -1, ...options.view },
+		metadata: { annotationsEnabled: null, reviewNotesKey: null, scratchpadKey: null, ...options.metadata },
+	}));
+}
+
+// Strict codec boundary: no identity/text truncation, unknown-field dropping or partial recovery.
+export function validateStudioBufferWorkspace(value, expected = {}) {
+	try {
+		requireState(value && value.version === 2, "unsupported-version", "Unsupported workspace schema; preserve the original recovery data.");
+		object(value, ["version", "workspaceId", "mode", "revision", "savedAt", "selectedBufferId", "activePromptId", "order", "buffers"], "Workspace");
+		requireState(typeof value.workspaceId === "string" && WORKSPACE_ID.test(value.workspaceId), "invalid-state", "Invalid workspace ID.");
+		requireState(["full", "editor-only"].includes(value.mode), "invalid-state", "Watched/read-only views do not own editable buffer stores.");
+		requireState((expected.workspaceId === undefined || expected.workspaceId === value.workspaceId) && (expected.mode === undefined || expected.mode === value.mode), "wrong-workspace", "Recovery belongs to a different workspace or mode.");
+		requireState(Array.isArray(value.buffers) && value.buffers.length >= 1 && value.buffers.length <= STUDIO_BUFFER_LIMITS.buffers, "limit-exceeded", "Workspace buffer count is outside its limit.");
+		const buffers = value.buffers.map(buffer);
+		const ids = new Set(buffers.map((entry) => entry.id));
+		requireState(ids.size === buffers.length, "invalid-state", "Duplicate buffer identity.");
+		requireState(Array.isArray(value.order) && value.order.length === ids.size && new Set(value.order).size === ids.size && value.order.every((id) => ids.has(id)), "invalid-state", "Invalid buffer ordering.");
+		requireState(ids.has(value.selectedBufferId), "invalid-state", "Selected buffer is missing.");
+		const active = buffers.find((entry) => entry.id === value.activePromptId);
+		requireState(value.mode === "full" ? active?.role === "prompt" : value.activePromptId === null && buffers.every((entry) => entry.role === "document"), "invalid-state", "Invalid active Prompt or companion role.");
+		const total = buffers.reduce((sum, entry) => sum + entry.text.length + (entry.baselineText?.length || 0), 0);
+		requireState(total <= STUDIO_BUFFER_LIMITS.totalTextChars, "limit-exceeded", "Workspace text and baselines exceed the aggregate limit; no buffers were evicted.");
+		return { ok: true, state: freeze({ version: 2, workspaceId: value.workspaceId, mode: value.mode,
+			revision: integer(value.revision, "Workspace revision"), savedAt: integer(value.savedAt, "Recovery timestamp"),
+			selectedBufferId: value.selectedBufferId, activePromptId: value.activePromptId, order: [...value.order], buffers }) };
+	} catch (error) { return failure(error); }
+}
+
+export function isStudioBufferDirty(entry) {
+	return entry.baselineText === null || entry.text !== entry.baselineText;
+}
+
+export function createStudioBufferStore(initialState, options = {}) {
+	const initial = validateStudioBufferWorkspace(initialState);
+	if (!initial.ok) throw new StudioBufferStateError(initial.reason, initial.message);
+	let state = initial.state;
+	const now = typeof options.now === "function" ? options.now : Date.now;
+	const pending = new Map(); // Page-memory only: never recovered, persisted or copied with a document.
+	const get = (id) => state.buffers.find((entry) => entry.id === id) || null;
+	const fail = (reason, message) => ({ ok: false, reason, message });
+	function commit(next) {
+		const candidate = validateStudioBufferWorkspace({ ...next, revision: state.revision + 1, savedAt: Math.max(state.savedAt + 1, now()) });
+		if (!candidate.ok) return candidate;
+		state = candidate.state;
+		return { ok: true };
+	}
+	function update(id, expectedRevision, patch) {
+		const current = get(id);
+		if (!current || current.revision !== expectedRevision) return fail("stale-buffer", "The originating buffer changed or closed; retry explicitly.");
+		try { object(patch, PATCH_KEYS, "Buffer update"); } catch (error) { return failure(error); }
+		const next = { ...current, ...patch, revision: current.revision + 1 };
+		if (patch.sourceState && patch.sourceState.path !== current.sourceState.path) {
+			// Never carry a previous file's baseline/revision to a different path by accident.
+			if (!("baselineText" in patch)) next.baselineText = null;
+			if (!("diskRevision" in patch)) next.diskRevision = null;
+		}
+		if (typeof next.text === "string" && !("view" in patch)) {
+			next.view = { ...next.view, selectionStart: Math.min(next.view.selectionStart, next.text.length), selectionEnd: Math.min(next.view.selectionEnd, next.text.length) };
+		}
+		return commit({ ...state, buffers: state.buffers.map((entry) => entry.id === id ? next : entry) });
+	}
+	function targetMatches(target) {
+		return Boolean(target && pending.get(target.requestId) === target && get(target.bufferId)?.revision === target.revision
+			&& (!target.requireActivePrompt || state.activePromptId === target.bufferId));
+	}
+	return Object.freeze({
+		snapshot: () => state,
+		get,
+		update,
+		add(entry) {
+			if (get(entry?.id)) return fail("duplicate-buffer", "This buffer ID is already open.");
+			return commit({ ...state, buffers: [...state.buffers, entry], order: [...state.order, entry?.id] });
+		},
+		select(id) {
+			if (!get(id)) return fail("missing-buffer", "The selected buffer is not open.");
+			return id === state.selectedBufferId ? { ok: true } : commit({ ...state, selectedBufferId: id });
+		},
+		activatePrompt(id) {
+			if (state.mode !== "full" || get(id)?.role !== "prompt") return fail("not-a-prompt", "Only a full workspace Prompt can be activated.");
+			if (id === state.activePromptId) return { ok: true };
+			const result = commit({ ...state, activePromptId: id });
+			// Switching away and back must not revive a transfer aimed at an earlier active destination.
+			if (result.ok) for (const [requestId, target] of pending) if (target.requireActivePrompt) pending.delete(requestId);
+			return result;
+		},
+		close(target, { discard = false, replacementPromptId = null } = {}) {
+			if (!targetMatches(target)) {
+				if (target && pending.get(target.requestId) === target) pending.delete(target.requestId);
+				return fail("stale-operation", "The buffer changed, closed or reopened; confirm again.");
+			}
+			const id = target.bufferId;
+			const entry = get(id);
+			if (discard !== true && (isStudioBufferDirty(entry) || (entry.role === "prompt" && entry.text.length > 0))) return fail("confirmation-required", "Closing this buffer needs an explicit discard decision.");
+			const activePromptId = id === state.activePromptId ? replacementPromptId : state.activePromptId;
+			if (id === state.activePromptId && (!replacementPromptId || replacementPromptId === id || get(replacementPromptId)?.role !== "prompt")) return fail("replacement-prompt-required", "Choose the next active Prompt explicitly before closing this one.");
+			const order = state.order.filter((other) => other !== id);
+			const result = commit({ ...state, activePromptId, selectedBufferId: state.selectedBufferId === id ? activePromptId || order[0] : state.selectedBufferId,
+				order, buffers: state.buffers.filter((other) => other.id !== id) });
+			if (result.ok) for (const [requestId, target] of pending) if (target.bufferId === id) pending.delete(requestId);
+			return result;
+		},
+		beginOperation(bufferId, requestId, { requireActivePrompt = false } = {}) {
+			const entry = get(bufferId);
+			if (!entry || (requireActivePrompt && state.activePromptId !== bufferId)) return fail("missing-origin", "The requested originating buffer/Prompt is not available.");
+			if (typeof requestId !== "string" || !requestId.length || requestId.length > 256 || pending.has(requestId)) return fail("invalid-request", "Request IDs must be bounded and unique among pending operations.");
+			if (pending.size >= STUDIO_BUFFER_LIMITS.pendingOperations) return fail("limit-exceeded", "Too many pending buffer operations; nothing was evicted.");
+			const target = Object.freeze({ bufferId, revision: entry.revision, requestId, requireActivePrompt: Boolean(requireActivePrompt) });
+			pending.set(requestId, target);
+			return { ok: true, target };
+		},
+		isCurrent: targetMatches,
+		finishOperation(target, patch) {
+			const matches = targetMatches(target);
+			if (target && pending.get(target.requestId) === target) pending.delete(target.requestId);
+			if (!matches) return fail("stale-operation", "The originating operation changed, closed or completed; retry explicitly.");
+			return update(target.bufferId, target.revision, patch);
+		},
+		cancelOperation(target) {
+			return Boolean(target && pending.get(target.requestId) === target && pending.delete(target.requestId));
+		},
+		clearPendingOperations: () => pending.clear(),
+		get pendingOperationCount() { return pending.size; },
+	});
+}

package/shared/studio-buffer-switching.js

@@ -0,0 +1,53 @@
+import { createStudioBuffer, validateStudioBufferWorkspace } from "./studio-buffer-store.js";
+
+// Deliberately narrower than the store: no parked Prompts or general tab management.
+export function isStudioPromptDocumentBufferState(state) {
+	return state?.mode === "full" && state.buffers.length <= 2
+		&& state.buffers.filter(b => b.role === "prompt").length === 1
+		&& state.buffers.filter(b => b.role === "document").length <= 1
+		&& state.buffers.some(b => b.id === state.activePromptId && b.role === "prompt");
+}
+
+// This is only a reason to ASK about recovered v2, never permission to change its
+// submission target. v1/fresh editor launches have explicit visible-editor intent.
+export function needsStudioLegacyPromptChoice(state) {
+	if (!isStudioPromptDocumentBufferState(state) || state.selectedBufferId === state.activePromptId) return false;
+	const prompt = state.buffers.find(b => b.id === state.activePromptId);
+	return prompt.revision === 0 && prompt.text === "" && prompt.baselineText === ""
+		&& prompt.sourceState.source === "blank" && prompt.sourceState.label === "Prompt"
+		&& prompt.sourceState.path === null && prompt.sourceState.draftId === prompt.id
+		&& prompt.diskRevision === null && prompt.resourceDir === ""
+		&& prompt.metadata.annotationsEnabled === null && prompt.metadata.reviewNotesKey === null && prompt.metadata.scratchpadKey === null;
+}
+
+export function prepareStudioPromptDocumentWorkspace(value, { makeBufferId, roleChoice, now = Date.now } = {}) {
+	const checked = validateStudioBufferWorkspace(value);
+	if (!checked.ok) return checked;
+	const state = checked.state;
+	if (!isStudioPromptDocumentBufferState(state)) return { ok: false, reason: "unsupported-collection",
+		message: "Studio shows one Prompt and one Document. Other buffers were retained; export them or use a compatible build." };
+	let buffers = state.buffers, activePromptId = state.activePromptId;
+	if (roleChoice === "visible-prompt" && state.selectedBufferId !== activePromptId) {
+		if (!needsStudioLegacyPromptChoice(state)) return { ok: false, reason: "role-decision-required", message: "The existing Prompt cannot be replaced by a role migration. Both texts were kept." };
+		buffers = buffers.map(b => b.id === state.selectedBufferId
+			? createStudioBuffer({ ...b, role: "prompt", revision: b.revision + 1 })
+			: createStudioBuffer({ ...b, role: "document", revision: b.revision + 1,
+				sourceState: { ...b.sourceState, label: "Document" }, view: { ...b.view, rightView: "editor-preview" } }));
+		activePromptId = state.selectedBufferId;
+	} else if (roleChoice === "keep-roles" && needsStudioLegacyPromptChoice(state)) {
+		// Explicitly chosen Prompt provenance, not an inferred association/grant.
+		// Remember the choice without a new recovery schema or a disposable sidecar.
+		buffers = buffers.map(b => b.id === activePromptId ? createStudioBuffer({ ...b, revision: b.revision + 1,
+			sourceState: { ...b.sourceState, source: "prompt" } }) : b);
+	}
+	if (!buffers.some(b => b.role === "document")) {
+		let document;
+		try { document = createStudioBuffer({ id: makeBufferId(), role: "document", sourceState: { label: "Document" }, resourceDir: buffers[0].resourceDir }); }
+		catch (error) { return { ok: false, reason: error.reason || "invalid-state", message: "The document buffer could not be created; existing text was kept." }; }
+		buffers = [...buffers, document];
+	}
+	if (buffers === state.buffers) return checked;
+	return validateStudioBufferWorkspace({ ...state, buffers, activePromptId,
+		order: [activePromptId, ...buffers.filter(b => b.id !== activePromptId).map(b => b.id)],
+		revision: state.revision + 1, savedAt: Math.max(state.savedAt + 1, now()) });
+}

package/shared/studio-disk-revisions.js

@@ -295,6 +295,17 @@ function throwStudioDiskConflict(conflict) {
 	throw error;
 }
 
+// Trusted, synchronous host authorization supplements (never replaces) filesystem
+// and revision checks. Run before creating a temporary file and again immediately
+// before commit, with the disk helper's actual canonical destination.
+function authorizeStudioDiskCommit(options, path) {
+	if (typeof options?.authorizeCommit !== "function") return;
+	const result = options.authorizeCommit(path);
+	if (result?.ok !== true) throwStudioDiskConflict(result?.ok === false ? result : {
+		ok: false, reason: "authority-required", message: "Document ownership must be confirmed synchronously before saving.",
+	});
+}
+
 function createStudioNewFileMetadata() {
 	return { mode: 0o666 & ~process.umask() };
 }
@@ -375,6 +386,7 @@ export function saveStudioDiskFileIfRevision(options) {
 	const targetExisted = target.exists;
 	const metadata = targetExisted ? target : createStudioNewFileMetadata();
 	try {
+		authorizeStudioDiskCommit(options, stableTargetPath);
 		const written = writeStudioDiskFileAtomically(stableTargetPath, options?.content, metadata, {
 			replace: targetExisted,
 			beforeCommit: () => {
@@ -414,6 +426,7 @@ export function saveStudioDiskFileIfRevision(options) {
 						"A new file appeared at this path while Studio was preparing to recreate it.",
 					));
 				}
+				authorizeStudioDiskCommit(options, stableTargetPath);
 			},
 		});
 		return { ok: true, ...written };
@@ -497,6 +510,7 @@ export function saveStudioDiskFileAs(options) {
 	const targetExisted = target.exists;
 	const metadata = targetExisted ? target : createStudioNewFileMetadata();
 	try {
+		authorizeStudioDiskCommit(options, stableTargetPath);
 		const written = writeStudioDiskFileAtomically(stableTargetPath, options?.content, metadata, {
 			replace: targetExisted,
 			beforeCommit: () => {
@@ -535,6 +549,7 @@ export function saveStudioDiskFileAs(options) {
 						"A file appeared at this path while Studio was preparing the save.",
 					));
 				}
+				authorizeStudioDiskCommit(options, stableTargetPath);
 			},
 		});
 		return { ok: true, ...written };

package/shared/studio-document-entrypoints.js

@@ -0,0 +1,38 @@
+// Hosting pages consume an already registered workspace or a retained read-only
+// watched capability. Descriptive URL fields never authorize a file read.
+const unavailable = message => ({ ok: false, message });
+export function resolveStudioHostingPage({ enabled, requestUrl, mode, workspace, transient }) {
+	if (!enabled) return { ok: true, legacy: true };
+	const params = requestUrl.searchParams;
+	const hostedId = params.get("hostedWorkspace") || "", tabId = params.get("studioTabState") || "";
+	if (hostedId && tabId && hostedId !== tabId) return unavailable("This link looks damaged, perhaps by a line break when it was copied. Copy the full link from Pi again; nothing was changed.");
+	const id = hostedId || tabId;
+	const state = id ? workspace(id) : null;
+	if (state) {
+		const selected = state.buffers.find(buffer => buffer.id === state.selectedBufferId);
+		if (state.mode !== mode || !selected || params.get("watchFile") === "1" || params.get("watchedFile") === "1") {
+			return unavailable("This retained workspace cannot change its editing mode through a URL.");
+		}
+		return { ok: true, workspaceId: id, state,
+			document: { text: selected.text, label: selected.sourceState.label, source: "blank" } };
+	}
+	if (hostedId) return unavailable("This retained Document host is unavailable. Keep browser recovery copies; do not reload an independent disk copy.");
+	const docId = params.get("docId") || "", document = docId ? transient(docId) : null;
+	if (mode === "editor-only" && document?.watchFile === true && document.source === "file" && document.path) {
+		if (params.has("docPath") && params.get("docPath") !== document.path) return unavailable("The watched preview path does not match its retained authorization.");
+		return { ok: true, watched: true, document };
+	}
+	return unavailable("This editing URL is not registered in dual editor mode. Start with /studio, then use Open Document, New editor tab, Move or Copy in that workspace. Existing work was kept.");
+}
+export function studioHostingCommandError({ enabled, mode, replace = false, watchedText = false, current = false }) {
+	if (!enabled) return null;
+	if (current || replace) return "Terminal replacement is unavailable in dual editor mode. Use Open Document in the owning Studio workspace, or switch with /studio --single; current work was kept.";
+	if (mode === "editor-only" && !watchedText) return "This standalone command is unavailable in dual editor mode (/studio --single switches). Use New editor tab, Open file in a new editor, Move or Copy in Studio. Read-only watched text previews remain available.";
+	return null;
+}
+export function studioHostingLocalLinkError({ enabled, action, kind }) {
+	if (!enabled) return null;
+	if (kind === "office" && ["document", "editor-url"].includes(action)) return "Office conversion is unavailable in dual editor mode. Convert separately and explicitly import a Markdown copy; the original document was not changed.";
+	if (["editor-url", "preview-url"].includes(action)) return "This legacy standalone-tab route is unavailable in dual editor mode. Use the owning Studio workspace's opening controls or an inline preview.";
+	return null;
+}

package/shared/studio-document-escrow.js

@@ -0,0 +1,147 @@
+import { createStudioBuffer } from "./studio-buffer-store.js";
+const fail = (reason, message) => ({ ok: false, reason, message });
+const validMove = value => typeof value === "string" && /^[a-f0-9]{48}$/.test(value);
+
+// One non-editable handoff backup per host. It never participates in ordinary
+// workspace recovery or grants a file/metadata writer. No durable-storage claim.
+// A copy retries the same bounded identity, never a fresh intent after a lost
+// acknowledgement. Persist only identifiers/preconditions, not URLs or tokens.
+// One verified storage write retires a pending request AND retains its destination.
+// v1 pending records remain readable; v2 adds a bounded, token-free identity list.
+// No silent eviction: at capacity new creation is refused before dispatch.
+export function createStudioDocumentCreationIntent(storage, key, normalizeRequest, kinds) {
+	let loaded = false, raw = null, record = null, error = null, destinations = [];
+	const validId = value => typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+	const pending = request => Object.freeze({ version: 1, request: Object.freeze(normalizeRequest(request)) });
+	function destination(value) {
+		if (!value || Object.keys(value).some(k => !["operationId", "sourceBufferId", "workspaceId", "bufferId", "kind", "created"].includes(k))
+			|| !validMove(value.operationId) || ![value.sourceBufferId, value.workspaceId, value.bufferId].every(validId)
+			|| !kinds.includes(value.kind) || typeof value.created !== "boolean") throw Error("Invalid retained Document identity.");
+		return Object.freeze({ ...value });
+	}
+	function load() {
+		if (loaded) return;
+		try {
+			raw = storage.getItem(key) || null;
+			if (raw) {
+				if (raw.length > 60000) throw Error("Oversized Document tracking record.");
+				const value = JSON.parse(raw), version2 = value?.version === 2;
+				if (!value || ![1, 2].includes(value.version) || Object.keys(value).some(k => !(version2 ? ["version", "request", "destinations"] : ["version", "request"]).includes(k))) throw Error("Unknown Document tracking record.");
+				const list = version2 ? value.destinations : [];
+				if (!Array.isArray(list) || list.length > 32) throw Error("Invalid Document destination list.");
+				const restored = list.map(destination);
+				if (new Set(restored.map(d => d.operationId)).size !== restored.length) throw Error("Duplicate Document destination identity.");
+				record = version2 && value.request === null ? null : pending(value.request);
+				destinations = restored;
+			}
+			loaded = true; error = null;
+		} catch (e) { error = fail("tracking-unavailable", e.message || "Document tracking needs inspection. Its bytes were kept."); }
+	}
+	function current() {
+		load(); if (error) return error;
+		try { return (storage.getItem(key) || null) === raw ? { ok: true } : fail("storage-changed", "Document tracking changed independently. Its bytes were kept."); }
+		catch { return fail("storage-unavailable", "Document tracking could not be checked. Keep this page open."); }
+	}
+	function write(nextRecord, nextDestinations) {
+		const checked = current(); if (!checked.ok) return checked;
+		const encoded = nextRecord || nextDestinations.length ? JSON.stringify({ version: 2, request: nextRecord?.request ?? null, destinations: nextDestinations }) : null;
+		if (encoded?.length > 60000) return fail("capacity", "Document tracking is full. Existing identities were kept.");
+		try {
+			if (encoded) storage.setItem(key, encoded); else storage.removeItem(key);
+			if ((storage.getItem(key) || null) !== encoded) return fail("storage-unverified", "Document tracking could not be verified. Keep the original attempt and recheck.");
+			raw = encoded; record = nextRecord; destinations = nextDestinations; return { ok: true };
+		} catch { return fail("storage-unavailable", "Document tracking could not be stored. Keep the original attempt and recheck."); }
+	}
+	function remember(value, nextRecord = record) {
+		const checked = current(); if (!checked.ok) return checked;
+		let next; try { next = destination(value); } catch (e) { return fail("invalid-receipt", e.message); }
+		const existing = destinations.find(d => d.operationId === next.operationId);
+		if (existing && JSON.stringify(existing) !== JSON.stringify(next)) return fail("destination-changed", "This operation belongs to another Document identity. Nothing was replaced.");
+		if (!existing && destinations.length >= 32) return fail("capacity", "The retained Document list is full. Existing identities were kept.");
+		return write(nextRecord, existing ? destinations : [...destinations, next]);
+	}
+	return Object.freeze({
+		peek() { load(); return { record, error, destinations: destinations.map(d => ({ ...d })) }; },
+		current,
+		capture(request) {
+			const checked = current(); if (!checked.ok) return checked;
+			let next; try { next = pending(request); } catch (e) { return fail("invalid-request", e.message); }
+			if (record) return JSON.stringify(record) === JSON.stringify(next) ? { ok: true } : fail("creation-pending", "Recheck the existing attempt before starting another one.");
+			if (destinations.length >= 32) return fail("capacity", "The retained Document list is full. No new Document was requested.");
+			return write(next, destinations);
+		},
+		complete(result) {
+			const checked = current(); if (!checked.ok) return checked;
+			const request = record?.request, kind = request?.kind || "copy";
+			if (!request || result?.ok !== true || result.operationId !== request.operationId || typeof result.created !== "boolean" || (kind !== "file" && !result.created)) return fail("unverified-creation", "Creation was not verified. Keep and recheck the original attempt.");
+			let verified;
+			try { verified = destination({ operationId: request.operationId, sourceBufferId: request.bufferId, workspaceId: result.workspaceId, bufferId: result.bufferId, kind, created: result.created }); }
+			catch (e) { return fail("invalid-receipt", e.message); }
+			return { ...remember(verified, null), destination: { ...verified } };
+		},
+		remember: value => { load(); return remember(value, record); },
+		clear(confirmed) {
+			if (confirmed !== true) return fail("confirmation-required", "Confirm forgetting this attempt. Existing Documents will not be deleted.");
+			const checked = current(); if (!checked.ok) return checked;
+			return write(null, destinations);
+		},
+	});
+}
+
+export function createStudioDocumentCopyIntent(storage, key) {
+	return createStudioDocumentCreationIntent(storage, key, p => {
+		if (!p || Object.keys(p).some(k => !["operationId", "bufferId", "documentEpoch", "expectedRevision"].includes(k))
+			|| !validMove(p.operationId) || !validMove(p.expectedRevision) || !/^[a-zA-Z0-9_-]{1,128}$/.test(p.bufferId || "")
+			|| !Number.isSafeInteger(p.documentEpoch) || p.documentEpoch < 1) throw Error("Invalid copy intent.");
+		return { operationId: p.operationId, bufferId: p.bufferId, documentEpoch: p.documentEpoch, expectedRevision: p.expectedRevision };
+	}, ["copy", "move"]);
+}
+
+export function createStudioDocumentEscrow(storage, key) {
+	let loaded = false, record = null, raw = null, readable = true, stored = false, error = null;
+	function load() {
+		if (loaded) return; loaded = true;
+		try { raw = storage.getItem(key); }
+		catch { readable = false; return; }
+		if (!raw) return;
+		try {
+			if (raw.length > 6_100_000) throw Error("Oversized handoff backup");
+			const value = JSON.parse(raw);
+			if (value.version !== 1 || !validMove(value.moveId)) throw Error("Unknown handoff backup");
+			const document = createStudioBuffer(value.document);
+			if (document.role !== "document") throw Error("Not a Document backup");
+			record = { version: 1, moveId: value.moveId, document }; stored = true;
+		} catch { error = fail("escrow-invalid", "An existing handoff backup needs inspection. It was not replaced."); }
+	}
+	function persist() {
+		if (!readable || !record) return;
+		try {
+			if ((storage.getItem(key) || null) !== (raw || null)) { stored = false; return fail("storage-changed", "The handoff backup changed independently. Both copies were kept."); }
+			const next = JSON.stringify(record); storage.setItem(key, next);
+			if (storage.getItem(key) !== next) { stored = false; return fail("storage-unverified", "The handoff backup could not be verified. Keep this page open."); }
+			raw = next; stored = true;
+		} catch { stored = false; }
+	}
+	return Object.freeze({
+		capture(moveId, document) {
+			load(); if (error) return error;
+			if (!validMove(moveId) || document?.role !== "document") return fail("invalid-move", "A Document move identity is required.");
+			if (record && (record.moveId !== moveId || JSON.stringify(record.document) !== JSON.stringify(document))) {
+				return fail("handoff-pending", "The earlier document still has a handoff backup. Open its destination or explicitly discard that backup before moving another document.");
+			}
+			record ??= { version: 1, moveId, document: createStudioBuffer(document) };
+			const result = persist(); if (result) return result;
+			return { ok: true, stored };
+		},
+		peek() { load(); return { record, stored, error }; },
+		resolve(moveId) {
+			load(); if (!record || record.moveId !== moveId) return fail("wrong-handoff", "The handoff backup belongs to another move.");
+			try {
+				if (readable && (storage.getItem(key) || null) !== (raw || null)) return fail("storage-changed", "The handoff backup changed. It was not removed.");
+				if (readable && raw) { if (storage.removeItem) storage.removeItem(key); else storage.setItem(key, ""); }
+			} catch { return fail("storage-unavailable", "The resolved backup could not be removed; inspect it before starting another move."); }
+			record = null; raw = null; stored = false; return { ok: true };
+		},
+		retry() { load(); return persist(); },
+	});
+}