pi-studio 0.9.63 → 0.10.1

package/shared/studio-buffer-decisions.js

@@ -0,0 +1,129 @@
+import { createStudioBuffer, validateStudioBufferWorkspace } from "./studio-buffer-store.js";
+import { STUDIO_BUFFER_RECOVERY_PREFIX, STUDIO_BUFFER_LEGACY_TAB_PREFIX, STUDIO_BUFFER_RECOVERY_MAX_SERIALIZED_CHARS,
+	decodeStudioBufferRecovery, migrateStudioWorkspaceV1, createStudioBufferRecoveryStorage } from "./studio-buffer-recovery.js";
+import { isStudioSingleEditorBufferState, projectStudioBufferEditor } from "./studio-buffer-client.js";
+import { isStudioPromptDocumentBufferState } from "./studio-buffer-switching.js";
+
+const fail = (reason, message) => ({ ok: false, reason, message });
+
+// Explicit recovery is a FORK into a fresh namespace, never an overwrite/repair
+// of the originals. Paths remain claims; compatibility and mode gates still apply.
+export function createStudioBufferRecoveryDecisions(options) {
+	const { storage, workspaceId, mode, readRemote, canRestore, makeWorkspaceId } = options;
+	const expected = { workspaceId, mode };
+	const localKeys = [
+		["browser-v2", "Browser buffers", STUDIO_BUFFER_RECOVERY_PREFIX + workspaceId, "v2"],
+		["browser-legacy", "Browser single-editor copy", STUDIO_BUFFER_LEGACY_TAB_PREFIX + workspaceId, "legacy"],
+		["browser-unscoped", "Older browser copy (no tab identity)", "piStudio.workspaceState.v1", "legacy"],
+	];
+	let records = [], errors = [], handles = new Map(), epoch = 0, disposed = false;
+	function localRaw(key) {
+		try { const raw = storage.getItem(key); if (raw !== null && typeof raw !== "string") throw new Error(); return { ok: true, raw }; }
+		catch { return fail("unavailable", "Browser recovery could not be read. Nothing was treated as empty."); }
+	}
+	async function remoteRaw() {
+		try {
+			const result = await readRemote();
+			if (!result?.ok) return result || fail("unavailable", "Server copies could not be read.");
+			if (result.workspaceId !== workspaceId || result.mode !== mode || !Array.isArray(result.records) || result.records.length !== 2
+				|| !["v2", "legacy"].every(kind => result.records.filter(r => r.kind === kind && (r.raw === null || typeof r.raw === "string")).length === 1)) {
+				return fail("invalid-state", "Server inspection did not match this workspace. It was not used.");
+			}
+			return result;
+		} catch { return fail("unavailable", "Server copies could not be read. Browser copies and live text were kept."); }
+	}
+	function validate(raw, kind) {
+		if (raw.length > STUDIO_BUFFER_RECOVERY_MAX_SERIALIZED_CHARS) return fail("limit-exceeded", "Too large for this build; download the original archive.");
+		if (kind === "v2") return decodeStudioBufferRecovery(raw, expected);
+		let value; try { value = JSON.parse(raw); } catch { return fail("invalid-json", "Malformed recovery; download the original archive."); }
+		let id = 0;
+		return migrateStudioWorkspaceV1(value, { ...expected, makeBufferId: () => "recovered-" + ++id });
+	}
+	function compatible(state) {
+		if (!(options.switching === true && mode === "full" ? isStudioPromptDocumentBufferState(state) : isStudioSingleEditorBufferState(state))) return fail("unsupported-collection", "This copy contains other buffers. Export them or use a build that can display the whole collection.");
+		if (!canRestore(projectStudioBufferEditor(state))) return fail("wrong-document", "This copy belongs to another source. Export its text; it cannot replace this document.");
+		return { ok: true };
+	}
+	function add(id, label, raw, kind, key = null) {
+		if (raw === null) return;
+		const result = validate(raw, kind);
+		const compatibility = result.ok ? compatible(result.state) : result;
+		const record = Object.freeze({ id, label, raw, state: result.ok ? result.state : null,
+			canUse: compatibility.ok, message: compatibility.ok ? "Compatible copy" : compatibility.message });
+		records.push(record); handles.set(record, { kind, key });
+	}
+	function seed(state, isStillCurrent) {
+		if (disposed || !isStillCurrent()) return fail("editor-changed", "Editor changed while recovery was open. Current text and original copies were kept.");
+		const compatibleResult = compatible(state); if (!compatibleResult.ok) return compatibleResult;
+		const nextId = makeWorkspaceId();
+		if (nextId === workspaceId) return fail("collision", "A fresh workspace identity is required.");
+		try {
+			const local = createStudioBufferRecoveryStorage({ storage, workspaceId: nextId, mode });
+			if (storage.getItem(local.key + ":serverAck") !== null) return fail("collision", "That workspace identity already has recovery metadata.");
+			const checked = validateStudioBufferWorkspace({ ...state, workspaceId: nextId }, { workspaceId: nextId, mode });
+			if (!checked.ok) return checked;
+			const written = local.write(checked.state, { expectedRaw: null });
+			if (!written.ok) return written;
+			// A re-entrant storage implementation cannot turn old consent into authority.
+			// Leave a successfully prepared copy intact if the final guard fails.
+			if (disposed || !isStillCurrent()) return fail("editor-changed", "Editor changed; the prepared copy was retained but navigation was cancelled.");
+			return { ok: true, workspaceId: nextId, state: written.state };
+		} catch { return fail("unavailable", "A fresh recovery copy could not be prepared. Original data and current text were kept."); }
+	}
+	return Object.freeze({
+		async inspect() {
+			if (disposed) return fail("cancelled", "This inspection has closed.");
+			const operation = ++epoch;
+			const remote = await remoteRaw();
+			if (disposed || operation !== epoch) return fail("cancelled", "Recovery inspection closed or was superseded.");
+			records = []; errors = []; handles = new Map();
+			for (const [id, label, key, kind] of localKeys) {
+				const result = localRaw(key);
+				if (result.ok) add(id, label, result.raw, kind, key); else errors.push(label + ": " + result.message);
+			}
+			if (remote.ok) for (const { kind, raw } of remote.records) add("server-" + kind, kind === "v2" ? "Server buffers" : "Server single-editor copy", raw, kind);
+			else errors.push(remote.message || "Server copies could not be read.");
+			return { ok: true, records: Object.freeze([...records]), errors: Object.freeze([...errors]) };
+		},
+		archive(currentText) {
+			// JSON-stringified raw strings preserve even malformed/future JSON and lone
+			// UTF-16 surrogates. No token, capability, server CAS revision or ack sidecar.
+			return JSON.stringify({ format: "pi-studio-recovery-export", version: 1, workspaceId, mode,
+				currentText, errors, copies: records.map(({ id, label, raw }) => ({ id, label, raw })) }, null, 2);
+		},
+		async use(record, isStillCurrent = () => true) {
+			const target = handles.get(record), operation = epoch;
+			if (disposed || !target || !record.state) return fail("invalid-choice", "Inspect and select a compatible recovery copy first.");
+			let current;
+			if (target.key) current = localRaw(target.key);
+			else {
+				const result = await remoteRaw();
+				current = result.ok ? { ok: true, raw: result.records.find(r => r.kind === target.kind).raw } : result;
+			}
+			if (disposed || operation !== epoch || !handles.has(record)) return fail("cancelled", "Recovery choice was superseded.");
+			if (!current.ok) return current;
+			if (current.raw !== record.raw) return fail("storage-changed", "That copy changed while recovery was open. Recheck the copies and choose again.");
+			return seed(record.state, isStillCurrent);
+		},
+		keepCurrent(editor, baselineText, extra = {}, isStillCurrent = () => true, liveState = null) {
+			let state = liveState;
+			if (!state) {
+				let id = 0;
+				const migrated = migrateStudioWorkspaceV1(editor, { ...expected, makeBufferId: () => "current-" + ++id });
+				if (!migrated.ok) return migrated;
+				state = migrated.state;
+				try {
+					state = { ...state, buffers: state.buffers.map(b => b.id !== state.selectedBufferId ? b : createStudioBuffer({ ...b,
+						baselineText: editor.sourceState.path ? baselineText : b.baselineText,
+						view: { ...b.view, ...extra.view }, metadata: { ...b.metadata, ...extra.metadata } })) };
+				} catch { return fail("invalid-state", "Current editor cannot fit in recovery. Export its full text first."); }
+			}
+			const checked = validateStudioBufferWorkspace(state, expected);
+			if (!checked.ok) return checked;
+			const projected = projectStudioBufferEditor(checked.state);
+			if (["text", "sourceState", "diskRevision", "resourceDir"].some(key => JSON.stringify(projected[key]) !== JSON.stringify(editor[key]))) return fail("editor-changed", "Current editor no longer matches the captured buffer. Try again.");
+			return seed(checked.state, isStillCurrent);
+		},
+		dispose() { disposed = true; epoch++; handles.clear(); },
+	});
+}

package/shared/studio-buffer-lineage.js

@@ -0,0 +1,48 @@
+// Browser-safe verification of server-issued, capability-scoped recovery lineage.
+// A timestamp or matching text alone is never an ancestry/ownership proof.
+import { validateStudioBufferWorkspace } from "./studio-buffer-store.js";
+
+export async function studioBufferDigest(value) {
+	const bytes = new TextEncoder().encode(JSON.stringify(value));
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function reconcileStudioHostingLineage({ local, remote, revision, checkpoint, lineage, now = Date.now }) {
+	if (!checkpoint || !Array.isArray(lineage) || lineage.length > 16) return null;
+	const start = lineage.findIndex(r => r.fromRevision === checkpoint.remoteRevision);
+	if (start < 0) return null;
+	const chain = lineage.slice(start);
+	let head = checkpoint.remoteRevision;
+	for (const receipt of chain) {
+		if (receipt.fromRevision !== head || typeof receipt.toRevision !== "string") return null;
+		head = receipt.toRevision;
+	}
+	if (head !== revision || chain[0].fromWorkspaceRevision !== checkpoint.workspaceRevision
+		|| await studioBufferDigest(remote) !== chain.at(-1).toDigest) return null;
+	if (await studioBufferDigest(local) === chain[0].fromDigest) return { state: remote, rebased: false };
+	if (local.revision <= checkpoint.workspaceRevision) return null;
+	// A local branch may contain newer Prompt work. Apply only a proven slot
+	// replacement; never replace an independently changed moving document.
+	let state = local;
+	for (const receipt of chain) {
+		if (receipt.kind === "cancel") continue;
+		if (!receipt.slot) return null;
+		const { beforeId, beforeDigest, afterId } = receipt.slot;
+		const old = state.buffers.find(b => b.id === beforeId), next = remote.buffers.find(b => b.id === afterId);
+		if (!old || !next || await studioBufferDigest(old) !== beforeDigest
+			|| state.activePromptId !== receipt.beforePromptId
+			|| JSON.stringify(state.order) !== JSON.stringify(receipt.beforeOrder)
+			|| state.selectedBufferId !== receipt.beforeSelected) return null;
+		for (const [id, digest] of Object.entries(receipt.unchanged || {})) {
+			const entry = remote.buffers.find(b => b.id === id);
+			if (!entry || await studioBufferDigest(entry) !== digest || !state.buffers.some(b => b.id === id)) return null;
+		}
+		if (state.buffers.length !== Object.keys(receipt.unchanged || {}).length + 1) return null;
+		state = { ...state, buffers: state.buffers.map(b => b.id === beforeId ? next : b),
+			order: state.order.map(id => id === beforeId ? afterId : id),
+			selectedBufferId: state.selectedBufferId === beforeId ? afterId : state.selectedBufferId };
+	}
+	const checked = validateStudioBufferWorkspace({ ...state, revision: Math.max(local.revision, remote.revision) + 1,
+		savedAt: Math.max(local.savedAt, remote.savedAt, now()) + 1 }, remote);
+	return checked.ok ? { state: checked.state, rebased: true } : null;
+}

package/shared/studio-buffer-recovery-panel.js

@@ -0,0 +1,132 @@
+// Browser-only, plain-text recovery UI. Stored text is never rendered as HTML.
+export function createStudioBufferRecoveryPanel(options) {
+	const { document } = options;
+	const element = (tag, text, parent) => { const el = document.createElement(tag); if (text) el.textContent = text; parent?.appendChild(el); return el; };
+	const dialog = element("dialog"); dialog.className = "studio-buffer-recovery-dialog";
+	dialog.dataset.bufferRecovery = "true"; dialog.setAttribute("aria-labelledby", "bufferRecoveryTitle");
+	element("h2", "Recover unsaved text", dialog).id = "bufferRecoveryTitle";
+	element("p", "Find an earlier copy if unsaved edits are missing. Looking here won’t change your editor.", dialog);
+	element("p", "These copies are temporary. Save files normally; recovery is not a backup.", dialog);
+	const message = element("p", "", dialog); message.setAttribute("role", "status"); message.dataset.recoveryMessage = "true";
+	const choicesLabel = element("label", "Stored copy ", dialog);
+	const choices = element("select", "", choicesLabel); choices.dataset.recoveryCopies = "true";
+	const detail = element("p", "", dialog);
+	const bufferLabel = element("label", "Text to preview/export ", dialog);
+	const buffers = element("select", "", bufferLabel); buffers.dataset.recoveryBuffers = "true";
+	const preview = element("textarea", "", dialog); preview.readOnly = true; preview.setAttribute("aria-label", "Recovery text preview"); preview.spellcheck = false;
+	const previewNote = element("p", "Preview limited to 20,000 characters; downloads include the full text.", dialog);
+	previewNote.className = "studio-buffer-recovery-note";
+	const actions = element("div", "", dialog); actions.className = "studio-buffer-recovery-actions";
+	let decisions = null, records = [], generation = 0, busy = false, removed = false, resolveConfirmation = null;
+	const confirmation = element("section", "", dialog); confirmation.hidden = true; confirmation.dataset.recoveryConfirmation = "true";
+	const confirmationTitle = element("h3", "", confirmation);
+	const confirmationText = element("p", "", confirmation);
+	const cancelConfirm = element("button", "Cancel — keep current text", confirmation); cancelConfirm.type = "button"; cancelConfirm.dataset.recoveryConfirm = "cancel";
+	const acceptConfirm = element("button", "Continue", confirmation); acceptConfirm.type = "button"; acceptConfirm.dataset.recoveryConfirm = "accept";
+	function finishConfirmation(value) { confirmation.hidden = true; const resolve = resolveConfirmation; resolveConfirmation = null; resolve?.(value); }
+	cancelConfirm.addEventListener("click", () => finishConfirmation(false)); acceptConfirm.addEventListener("click", () => finishConfirmation(true));
+	function confirm(text) { confirmationText.textContent = text; confirmation.hidden = false; cancelConfirm.focus(); return new Promise(resolve => { resolveConfirmation = resolve; }); }
+	const buttons = [];
+	function button(label, action, id) {
+		const btn = element("button", label, actions); btn.type = "button"; btn.dataset.recoveryAction = id; buttons.push(btn);
+		btn.addEventListener("click", async () => {
+			if (busy) return;
+			const operation = generation;
+			try { await action(); } catch (error) { if (dialog.open && operation === generation) message.textContent = error.message || "Recovery action failed. Current text was kept."; }
+		}); return btn;
+	}
+	const selected = () => records[Number(choices.value)] || null;
+	const selectedText = () => selected()?.state?.buffers[Number(buffers.value)]?.text ?? null;
+	function controls() {
+		for (const btn of buttons) btn.disabled = busy;
+		use.disabled = busy || !selected()?.canUse;
+		copy.disabled = downloadText.disabled = busy || selectedText() === null;
+		retry.disabled = busy || !options.canRetry();
+		choices.disabled = buffers.disabled = busy;
+	}
+	function showText() { preview.value = (selectedText() ?? selected()?.raw ?? "").slice(0, 20000); controls(); }
+	function showChoice() {
+		const record = selected(); buffers.replaceChildren();
+		for (const [i, b] of (record?.state?.buffers || []).entries()) {
+			const option = element("option", (b.sourceState.path || b.sourceState.label || b.role) + " — " + b.text.length + " characters", buffers);
+			option.value = String(i); option.selected = b.id === record.state.selectedBufferId;
+		}
+		bufferLabel.hidden = !record?.state;
+		const date = record?.state ? new Date(record.state.savedAt) : null;
+		const recorded = record?.state?.savedAt > 0 && Number.isFinite(date?.getTime()) ? "Recorded: " + date.toLocaleString() : "Time not recorded";
+		detail.textContent = record ? record.message + (record.state ? " · " + recorded : " · Raw data; download the archive to keep it.") : "No stored copies were found.";
+		showText();
+	}
+	async function recheck() {
+		busy = true; controls(); message.textContent = "Reading recovery copies…";
+		const operation = generation, owner = decisions;
+		const result = await owner.inspect();
+		if (!dialog.open || operation !== generation) return;
+		busy = false;
+		if (!result.ok) { message.textContent = result.message; controls(); return; }
+		records = result.records; choices.replaceChildren();
+		for (const [i, record] of records.entries()) { const option = element("option", record.label, choices); option.value = String(i); }
+		message.textContent = result.errors.join(" ") || "Your editor is unchanged.";
+		showChoice();
+	}
+	async function choose(current) {
+		if (!options.canChange()) { message.textContent = "Studio is busy. You can still copy or download text."; return; }
+		const consent = options.captureConsent(), operation = generation, record = selected();
+		busy = true; controls();
+		confirmationTitle.textContent = current ? "Keep current text?" : "Use this copy?";
+		const previewOnly = record?.state?.buffers[Number(buffers.value)]?.id !== record?.state?.selectedBufferId;
+		const selectionNote = previewOnly ? "This restores the stored editor, not the text chosen for preview/export. " : "";
+		const confirmed = await confirm(current
+			? "Restart recovery with your current editor text? Older copies are kept. No file is saved and nothing is submitted."
+			: "Replace your editor with this stored copy? " + selectionNote + "Copy or download current edits first. Older copies are kept; no file is saved and nothing is submitted.");
+		const isCurrent = () => dialog.open && operation === generation && options.consentIsCurrent(consent) && options.canChange();
+		if (!confirmed || !isCurrent()) {
+			if (dialog.open && operation === generation) { busy = false; message.textContent = confirmed ? "Editor or connection changed. Kept current text; try again." : "Kept the current editor and recovery copies."; controls(); }
+			return;
+		}
+		const result = current ? options.keepCurrent(decisions, isCurrent) : await decisions.use(record, isCurrent);
+		if (!dialog.open || operation !== generation) return;
+		busy = false;
+		if (!result.ok || !isCurrent()) { message.textContent = result.message || "Editor changed. Navigation cancelled; copies were retained."; controls(); return; }
+		options.navigate(result, consent);
+	}
+	button("Recheck copies", recheck, "inspect");
+	const retry = button("Retry recovery", async () => {
+		if (!options.canChange()) { message.textContent = "Studio is busy. Wait before retrying recovery."; return; }
+		const operation = generation, consent = options.captureConsent(); busy = true; controls();
+		const result = await options.retry(() => dialog.open && operation === generation && options.consentIsCurrent(consent));
+		if (!dialog.open || operation !== generation) return;
+		busy = false; message.textContent = result.ok ? "Current text has a temporary recovery copy on the server. Your file has not been saved." : result.message; controls();
+	}, "retry");
+	button("Download recovery archive", () => options.download(decisions.archive(options.currentText()), "studio-recovery-archive.json", "application/json"), "archive");
+	button("Download current text", () => options.download(options.currentText(), "studio-current-editor.txt", "text/plain"), "current-text");
+	const copy = button("Copy selected text", async () => { const operation = generation; const ok = await options.copy(selectedText()); if (dialog.open && operation === generation) message.textContent = ok ? "Selected text copied." : "Clipboard unavailable. Download the text instead."; }, "copy-text");
+	const downloadText = button("Download selected text", () => options.download(selectedText(), "studio-recovered-text.txt", "text/plain"), "selected-text");
+	const use = button("Use selected copy…", () => choose(false), "use");
+	button("Keep current text…", () => choose(true), "keep-current");
+	const close = element("button", "Close — keep editing", dialog); close.type = "button"; close.dataset.recoveryAction = "close";
+	close.addEventListener("click", () => dialog.close());
+	const about = element("details", "", dialog); about.className = "studio-buffer-recovery-note";
+	element("summary", "About these copies", about);
+	element("p", "Copies live in browser storage and the running Studio process; they may disappear when either closes. Recorded times come from the stored data, not an independent check of which copy is newest.", about);
+	element("p", "Downloads may contain private text and file paths. Rechecking replaces this list; download an archive first if you want to keep it.", about);
+	element("p", "Copies from another source or an unsupported format can be exported, but not restored here. Using a copy restarts recovery separately and leaves the originals untouched.", about);
+	choices.addEventListener("change", showChoice); buffers.addEventListener("change", showText);
+	dialog.addEventListener("keydown", event => event.stopPropagation());
+	dialog.addEventListener("close", () => {
+		// Native close events are queued. A close/reopen in one task must not dispose
+		// the new inspection or resolve its confirmation using the old event.
+		if (dialog.open) return;
+		generation++; finishConfirmation(false); decisions?.dispose(); decisions = null; records = []; busy = false; options.onClose?.();
+	});
+	document.body.appendChild(dialog);
+	return Object.freeze({
+		async open() {
+			if (removed || dialog.open) return;
+			generation++; finishConfirmation(false); decisions?.dispose(); decisions = options.createDecisions(); records = []; choices.replaceChildren(); buffers.replaceChildren(); preview.value = "";
+			dialog.showModal(); await recheck();
+		},
+		isOpen: () => dialog.open,
+		dispose() { removed = true; generation++; decisions?.dispose(); if (dialog.open) dialog.close(); dialog.remove(); },
+	});
+}

package/shared/studio-buffer-recovery.js

@@ -0,0 +1,181 @@
+import {
+	StudioBufferStateError,
+	createStudioBuffer,
+	validateStudioBufferWorkspace,
+} from "./studio-buffer-store.js";
+
+// The old key contains "v2" but its payload schema is v1. Never reuse that namespace.
+export const STUDIO_BUFFER_RECOVERY_PREFIX = "piStudio.bufferWorkspace.v2:";
+export const STUDIO_BUFFER_LEGACY_TAB_PREFIX = "piStudio.workspaceState.v2:";
+export const STUDIO_BUFFER_RECOVERY_MAX_SERIALIZED_CHARS = 20_000_000;
+const LEGACY_KEYS = ["version", "savedAt", "sourceState", "diskRevision", "resourceDir", "editorView", "rightView", "editorLanguage", "followLatest", "responseHistoryIndex", "selectionStart", "selectionEnd", "scrollTop", "text"];
+const fail = (reason, message) => ({ ok: false, reason, message });
+
+function parse(raw) {
+	if (typeof raw !== "string") return fail("invalid-state", "Recovery must be serialized text.");
+	if (raw.length > STUDIO_BUFFER_RECOVERY_MAX_SERIALIZED_CHARS) return fail("limit-exceeded", "Recovery exceeds the serialized size limit; preserve the original data.");
+	try { return { ok: true, value: JSON.parse(raw) }; }
+	catch { return fail("invalid-json", "Recovery could not be parsed; preserve the original data."); }
+}
+export function decodeStudioBufferRecovery(raw, expected) {
+	const parsed = parse(raw);
+	return parsed.ok ? validateStudioBufferWorkspace(parsed.value, expected) : parsed;
+}
+export function encodeStudioBufferRecovery(state, expected) {
+	const checked = validateStudioBufferWorkspace(state, expected);
+	if (!checked.ok) return checked;
+	const raw = JSON.stringify(checked.state);
+	if (raw.length > STUDIO_BUFFER_RECOVERY_MAX_SERIALIZED_CHARS) return fail("limit-exceeded", "Recovery exceeds the serialized size limit; nothing was replaced.");
+	return { ...checked, raw };
+}
+
+// No disk reads: v1 did not persist a baseline, so a recovered file is conservatively dirty.
+// mode/workspaceId come from the launch owner, not a field in the legacy payload.
+export function migrateStudioWorkspaceV1(value, { workspaceId, mode, makeBufferId } = {}) {
+	try {
+		if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1) return fail("unsupported-version", "Only schema v1 can be migrated here.");
+		if (Object.keys(value).some((key) => !LEGACY_KEYS.includes(key))) return fail("unknown-field", "Legacy recovery has unsupported fields; retain the original payload.");
+		if (typeof value.text !== "string") return fail("invalid-state", "Legacy editor text is missing.");
+		if (!["full", "editor-only"].includes(mode)) return fail("wrong-workspace", "An editable launch mode is required for migration.");
+		if (typeof makeBufferId !== "function") return fail("invalid-state", "Migration requires a buffer ID allocator.");
+		const sourceState = value.sourceState === undefined ? {} : value.sourceState;
+		if (!sourceState || typeof sourceState !== "object" || Array.isArray(sourceState)) return fail("invalid-state", "Invalid legacy source identity.");
+		if (["recovery-omitted", "recovery-cleared"].includes(sourceState.source)) return fail("legacy-marker", "This is a recovery omission/reset marker, not a draft to migrate.");
+		const fileBacked = typeof sourceState.path === "string" && sourceState.path.length > 0;
+		const role = mode === "full" && !fileBacked ? "prompt" : "document";
+		const id = makeBufferId();
+		const diskRevision = typeof value.diskRevision === "string" ? value.diskRevision.trim().toLowerCase() : value.diskRevision ?? null;
+		const selection = (input, fallback) => {
+			if (input === undefined) return fallback;
+			if (!Number.isSafeInteger(input) || input < 0) throw new StudioBufferStateError("invalid-state", "Invalid legacy selection.");
+			return Math.min(input, value.text.length);
+		};
+		const start = selection(value.selectionStart, 0);
+		const end = Math.max(start, selection(value.selectionEnd, start));
+		const entry = createStudioBuffer({
+			id, role, text: value.text, baselineText: fileBacked ? null : "", diskRevision,
+			sourceState: { source: "blank", label: "", path: null, draftId: null, ...sourceState },
+			resourceDir: value.resourceDir === undefined ? "" : value.resourceDir,
+			view: {
+				editorView: value.editorView === undefined ? "markdown" : value.editorView,
+				rightView: value.rightView === undefined ? "editor-preview" : value.rightView,
+				editorLanguage: value.editorLanguage === undefined ? "markdown" : value.editorLanguage,
+				followLatest: value.followLatest === undefined ? false : value.followLatest,
+				responseHistoryIndex: value.responseHistoryIndex === undefined ? -1 : value.responseHistoryIndex,
+				selectionStart: start, selectionEnd: end, scrollTop: value.scrollTop === undefined ? 0 : value.scrollTop,
+			},
+		});
+		const buffers = [entry];
+		let activePromptId = role === "prompt" ? id : null;
+		if (mode === "full" && role === "document") {
+			const prompt = createStudioBuffer({ id: makeBufferId(), role: "prompt" });
+			buffers.unshift(prompt);
+			activePromptId = prompt.id;
+		}
+		return validateStudioBufferWorkspace({ version: 2, workspaceId, mode, revision: 0, savedAt: value.savedAt === undefined ? 0 : value.savedAt,
+			selectedBufferId: id, activePromptId, order: buffers.map((entry) => entry.id), buffers }, { workspaceId, mode });
+	} catch (error) {
+		return fail(error.reason || "invalid-state", error instanceof StudioBufferStateError ? error.message : "Migration failed; preserve the original legacy payload.");
+	}
+}
+
+// Synchronous, same-page sessionStorage adapter, NOT a cross-client lease or server CAS.
+// No methods erase recovery. The caller must display errors and offer export/retry/discard
+// before activating a recovered editor. The opt-in client/decision layer does this;
+// the default production path still uses the separate v1 implementation.
+export function createStudioBufferRecoveryStorage({ storage, workspaceId, mode }) {
+	if (typeof workspaceId !== "string" || !/^[a-zA-Z0-9_-]{20,128}$/.test(workspaceId) || !["full", "editor-only"].includes(mode)) {
+		throw new StudioBufferStateError("wrong-workspace", "An explicit editable workspace identity and mode are required.");
+	}
+	const expected = { workspaceId, mode };
+	const key = STUDIO_BUFFER_RECOVERY_PREFIX + workspaceId;
+	const legacyKey = STUDIO_BUFFER_LEGACY_TAB_PREFIX + workspaceId;
+	function readRaw(which) {
+		try {
+			if (!storage || typeof storage.getItem !== "function") throw new Error("unavailable");
+			const raw = storage.getItem(which);
+			if (raw !== null && typeof raw !== "string") throw new Error("invalid storage result");
+			return { ok: true, raw };
+		} catch { return fail("storage-unavailable", "Recovery storage could not be read; no replacement is safe."); }
+	}
+	function legacyConflict(state) {
+		const legacy = readRaw(legacyKey);
+		if (!legacy.ok || legacy.raw === null) return legacy.ok ? { ok: true } : legacy;
+		const parsed = parse(legacy.raw);
+		let id = 0;
+		const checked = parsed.ok ? migrateStudioWorkspaceV1(parsed.value, { ...expected, makeBufferId: () => "legacy-check-" + ++id }) : parsed;
+		if (!checked.ok) return fail("legacy-conflict", "Legacy recovery is malformed, unsupported or a reset/omission marker; preserve both copies for a recovery decision.");
+		if (checked.state.savedAt > state.savedAt) return fail("legacy-newer", "A newer single-editor recovery exists; resolve it before writing or restoring v2.");
+		return { ok: true };
+	}
+	function write(state, options = {}, migratingLegacyRaw) {
+		if (!("expectedRaw" in options) || (options.expectedRaw !== null && typeof options.expectedRaw !== "string")) return fail("expected-state-required", "Read recovery before writing it.");
+		const encoded = encodeStudioBufferRecovery(state, expected);
+		if (!encoded.ok) return encoded;
+		const current = readRaw(key);
+		if (!current.ok) return current;
+		if (current.raw !== options.expectedRaw) return fail("storage-changed", "Recovery changed since it was read; retain the current editor and retry explicitly.");
+		let conflictBaseline = encoded.state;
+		if (current.raw !== null) {
+			const previous = decodeStudioBufferRecovery(current.raw, expected);
+			if (!previous.ok) return previous; // Exact-match consent cannot authorize erasing unknown/future data.
+			if (encoded.raw !== current.raw && (state.revision <= previous.state.revision || state.savedAt < previous.state.savedAt)) return fail("stale-state", "Recovery update is not newer than the stored workspace.");
+			conflictBaseline = previous.state; // A new candidate timestamp must not hide newer v1 work.
+		} else {
+			const legacy = readRaw(legacyKey);
+			if (!legacy.ok) return legacy;
+			if (legacy.raw !== null && legacy.raw !== migratingLegacyRaw) return fail("migration-required", "Legacy recovery must be migrated explicitly before creating a v2 workspace.");
+		}
+		const conflict = legacyConflict(conflictBaseline);
+		if (!conflict.ok) return conflict;
+		try {
+			if (!storage || typeof storage.setItem !== "function") throw new Error("unavailable");
+			storage.setItem(key, encoded.raw);
+		} catch { return fail("storage-write-failed", "Recovery could not be stored. Existing recovery and live buffers must be kept."); }
+		const verified = readRaw(key);
+		if (!verified.ok || verified.raw !== encoded.raw) return fail("storage-unverified", "Recovery write could not be verified; retain the original draft and legacy data.");
+		const decoded = decodeStudioBufferRecovery(verified.raw, expected);
+		return decoded.ok ? { ...decoded, raw: verified.raw } : decoded;
+	}
+	return Object.freeze({
+		key, legacyKey, write: (state, options) => write(state, options),
+		// Adopt a validated server/v1 candidate only against the exact local legacy read.
+		// Legacy bytes remain untouched; write() still validates their schema/timestamp.
+		adopt(state, { expectedLegacyRaw } = {}) {
+			const legacy = readRaw(legacyKey);
+			if (!legacy.ok) return legacy;
+			if (legacy.raw !== expectedLegacyRaw) return fail("storage-changed", "Legacy recovery changed before adoption.");
+			return write(state, { expectedRaw: null }, legacy.raw);
+		},
+		read() {
+			const current = readRaw(key);
+			if (!current.ok) return current;
+			if (current.raw !== null) {
+				const decoded = decodeStudioBufferRecovery(current.raw, expected);
+				if (!decoded.ok) return { ...decoded, key };
+				const conflict = legacyConflict(decoded.state);
+				return conflict.ok ? { ...decoded, raw: current.raw, status: "found" } : conflict;
+			}
+			const legacy = readRaw(legacyKey);
+			if (!legacy.ok) return legacy;
+			return { ok: true, status: legacy.raw === null ? "empty" : "legacy", raw: null, legacyRaw: legacy.raw };
+		},
+		migrateLegacy({ expectedLegacyRaw, makeBufferId }) {
+			const current = readRaw(key);
+			if (!current.ok) return current;
+			if (current.raw !== null) return fail("already-present", "A v2 recovery already exists; migration will not replace it.");
+			const legacy = readRaw(legacyKey);
+			if (!legacy.ok) return legacy;
+			if (typeof expectedLegacyRaw !== "string" || legacy.raw !== expectedLegacyRaw) return fail("storage-changed", "Legacy recovery changed or is missing; read it again before migrating.");
+			const parsed = parse(legacy.raw);
+			if (!parsed.ok) return parsed;
+			const migrated = migrateStudioWorkspaceV1(parsed.value, { ...expected, makeBufferId });
+			if (!migrated.ok) return migrated;
+			// ID allocators are caller code. Recheck both source and destination after invoking one.
+			const latest = readRaw(legacyKey);
+			if (!latest.ok) return latest;
+			if (latest.raw !== legacy.raw) return fail("storage-changed", "Legacy recovery changed during migration; nothing was replaced.");
+			return write(migrated.state, { expectedRaw: null }, legacy.raw); // Retain the exact legacy bytes, even after success.
+		},
+	});
+}