pi-studio 0.9.57 → 0.9.59

package/client/studio.css

@@ -362,6 +362,55 @@
       user-select: none;
     }
 
+    body[data-studio-layout="editor-top"] main,
+    body[data-studio-layout="response-top"] main {
+      grid-template-columns: minmax(0, 1fr);
+      gap: 0;
+    }
+
+    body[data-studio-layout="editor-top"] main {
+      grid-template-rows: minmax(140px, var(--studio-left-pane-fr, 1fr)) 10px minmax(140px, var(--studio-right-pane-fr, 1fr));
+    }
+
+    body[data-studio-layout="response-top"] main {
+      grid-template-rows: minmax(140px, var(--studio-right-pane-fr, 1fr)) 10px minmax(140px, var(--studio-left-pane-fr, 1fr));
+    }
+
+    body[data-studio-layout="editor-top"] .pane-resize-handle,
+    body[data-studio-layout="response-top"] .pane-resize-handle {
+      display: block;
+      align-self: stretch;
+      min-width: 0;
+      min-height: 10px;
+      cursor: row-resize;
+    }
+
+    body[data-studio-layout="editor-top"] .pane-resize-handle::before,
+    body[data-studio-layout="response-top"] .pane-resize-handle::before {
+      top: 50%;
+      right: 8px;
+      bottom: auto;
+      left: 8px;
+      width: auto;
+      height: 2px;
+      transform: translateY(-50%);
+    }
+
+    body[data-studio-layout="editor-top"] .pane-resize-handle:hover::before,
+    body[data-studio-layout="editor-top"] .pane-resize-handle:focus-visible::before,
+    body[data-studio-layout="editor-top"].pane-resizing .pane-resize-handle::before,
+    body[data-studio-layout="response-top"] .pane-resize-handle:hover::before,
+    body[data-studio-layout="response-top"] .pane-resize-handle:focus-visible::before,
+    body[data-studio-layout="response-top"].pane-resizing .pane-resize-handle::before {
+      width: auto;
+      height: 3px;
+    }
+
+    body[data-studio-layout="editor-top"].pane-resizing,
+    body[data-studio-layout="response-top"].pane-resizing {
+      cursor: row-resize;
+    }
+
     section {
       border: 1px solid var(--panel-border);
       border-radius: 10px;
@@ -387,6 +436,13 @@
       gap: 12px;
     }
 
+    body[data-studio-layout="editor-top"].pane-focus-left main,
+    body[data-studio-layout="editor-top"].pane-focus-right main,
+    body[data-studio-layout="response-top"].pane-focus-left main,
+    body[data-studio-layout="response-top"].pane-focus-right main {
+      grid-template-rows: minmax(0, 1fr);
+    }
+
     body.pane-focus-left #rightPane,
     body.pane-focus-right #leftPane,
     body.pane-focus-left #paneResizeHandle,
@@ -513,6 +569,7 @@
     body[data-studio-mode="editor-only"] #sendRunBtn,
     body[data-studio-mode="editor-only"] #queueSteerBtn,
     body[data-studio-mode="editor-only"] #sendEditorBtn,
+    body[data-studio-mode="editor-only"] #clearPiEditorBtn,
     body[data-studio-mode="editor-only"] #lensSelect,
     body[data-studio-mode="editor-only"] #critiqueBtn,
     body[data-studio-mode="editor-only"] #showMeBtn,
@@ -4579,6 +4636,107 @@
       background: var(--error-soft);
     }
 
+    .repl-quick-composer {
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+      padding: 10px;
+      border: 1px solid var(--panel-border);
+      border-radius: 8px;
+      background: color-mix(in srgb, var(--panel-2) 58%, var(--panel));
+    }
+
+    .repl-quick-header,
+    .repl-quick-actions {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 10px;
+    }
+
+    .repl-quick-header > div,
+    .repl-quick-actions > div {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      min-width: 0;
+    }
+
+    .repl-quick-target {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      max-width: min(48vw, 460px);
+      min-height: 0;
+      margin-left: 5px;
+      padding: 2px 4px;
+      overflow: hidden;
+      border-color: transparent;
+      border-radius: 5px;
+      background: transparent;
+      color: var(--muted);
+      font-family: var(--font-mono);
+      font-size: 11px;
+      line-height: 1.25;
+      vertical-align: bottom;
+      white-space: nowrap;
+    }
+
+    .repl-quick-target:not(:disabled):hover,
+    .repl-quick-target:focus-visible {
+      border-color: transparent;
+      background: var(--studio-header-action-hover-bg, var(--panel-2));
+      color: var(--text);
+    }
+
+    .repl-quick-target-label {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .repl-quick-target-arrow {
+      flex: 0 0 auto;
+      color: var(--studio-info-text, var(--muted));
+      font-family: var(--font-ui);
+      font-size: 10px;
+      font-weight: 700;
+    }
+
+    .repl-quick-hint,
+    .repl-quick-actions > span {
+      color: var(--muted);
+      font-size: 11px;
+    }
+
+    .repl-quick-composer textarea {
+      box-sizing: border-box;
+      min-height: 72px;
+      max-height: 260px;
+      margin: 0;
+      resize: vertical;
+    }
+
+    .repl-quick-composer textarea:focus-visible {
+      border-color: color-mix(in srgb, var(--accent) 65%, var(--control-border));
+      outline: 2px solid color-mix(in srgb, var(--accent) 28%, transparent);
+      outline-offset: 1px;
+    }
+
+    .repl-quick-actions {
+      align-items: flex-end;
+    }
+
+    .repl-quick-actions > span {
+      line-height: 1.35;
+    }
+
+    .repl-quick-send-btn {
+      border-color: color-mix(in srgb, var(--accent) 58%, var(--control-border));
+      background: color-mix(in srgb, var(--accent) 14%, var(--panel));
+      color: var(--text);
+    }
+
     .repl-journal,
     .repl-mirror {
       border: 1px solid var(--panel-border);
@@ -5726,6 +5884,20 @@
       .pane-resize-handle {
         display: none;
       }
+
+      .repl-quick-header,
+      .repl-quick-actions {
+        align-items: stretch;
+        flex-direction: column;
+      }
+
+      .repl-quick-target {
+        max-width: 66vw;
+      }
+
+      .repl-quick-actions > div {
+        align-self: flex-end;
+      }
     }
 
     /* Default Studio layout. The legacy classic layout remains available only via ?uiRefresh=0. */

package/index.ts

@@ -29,6 +29,11 @@ import {
 	saveStudioDiskFileAs,
 	saveStudioDiskFileIfRevision,
 } from "./shared/studio-disk-revisions.js";
+import {
+	consumeStudioPiEditorDraftSnapshot,
+	createStudioPiEditorDraftSnapshot,
+	normalizeStudioPiEditorDraftSnapshot,
+} from "./shared/studio-pi-editor-draft.js";
 import { normalizeStudioMarkdownSmartFences } from "./shared/studio-markdown-fences.js";
 import {
 	extractStandaloneLatexDefinitionsFromMarkdown,
@@ -646,10 +651,16 @@ interface AnnotationRequestMessage {
 	text: string;
 }
 
+interface StudioPiEditorDraftSnapshot {
+	fingerprint: string;
+	byteLength: number;
+}
+
 interface SendRunRequestMessage {
 	type: "send_run_request";
 	requestId: string;
 	text: string;
+	piEditorDraftSnapshot?: StudioPiEditorDraftSnapshot;
 }
 
 interface CompletionSuggestionRequestMessage {
@@ -839,6 +850,11 @@ interface GetFromEditorRequestMessage {
 	requestId: string;
 }
 
+interface ClearPiEditorRequestMessage {
+	type: "clear_pi_editor_request";
+	requestId: string;
+}
+
 interface QuartoPreviewCheckRequestMessage {
 	type: "quarto_preview_check_request";
 	requestId: string;
@@ -922,6 +938,7 @@ type IncomingStudioMessage =
 	| WatchFileSubscribeMessage
 	| SendToEditorRequestMessage
 	| GetFromEditorRequestMessage
+	| ClearPiEditorRequestMessage
 	| QuartoPreviewCheckRequestMessage
 	| QuartoPreviewStartRequestMessage
 	| QuartoPreviewStopRequestMessage
@@ -9917,10 +9934,15 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 	}
 
 	if (msg.type === "send_run_request" && typeof msg.requestId === "string" && typeof msg.text === "string") {
+		const piEditorDraftSnapshot = msg.piEditorDraftSnapshot === undefined
+			? undefined
+			: normalizeStudioPiEditorDraftSnapshot(msg.piEditorDraftSnapshot);
+		if (msg.piEditorDraftSnapshot !== undefined && !piEditorDraftSnapshot) return null;
 		return {
 			type: "send_run_request",
 			requestId: msg.requestId,
 			text: msg.text,
+			piEditorDraftSnapshot: piEditorDraftSnapshot ?? undefined,
 		};
 	}
 
@@ -10200,6 +10222,13 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 		};
 	}
 
+	if (msg.type === "clear_pi_editor_request" && typeof msg.requestId === "string") {
+		return {
+			type: "clear_pi_editor_request",
+			requestId: msg.requestId,
+		};
+	}
+
 	if (
 		msg.type === "quarto_preview_check_request"
 		&& typeof msg.requestId === "string"
@@ -11530,10 +11559,11 @@ function stripStudioReplSubmissionEcho(output: string): string {
 	let value = String(output || "").replace(/^\s+/, "");
 	// The raw tmux mirror should stay raw, but Studio/tool result output should not
 	// expose the temp-file wrapper used to submit multiline snippets safely. The
-	// The root fragment catches both legacy long Studio paths and compact private
-	// control paths when IPython wraps them across continuation prompt lines.
+	// root fragment catches both legacy long Studio paths and compact private
+	// control paths. Match the Python wrapper by its final double close rather
+	// than the word `globals`, which IPython may split across continuation lines.
 	const submissionEchoPatterns = [
-		/^.*exec\(open\([\s\S]*?(?:pi-studio-re|pi-rc-)[\s\S]*?globals\(\)\)\s*$/gm,
+		/^.*exec\(open\([\s\S]*?(?:pi-studio-re|pi-rc-)[\s\S]*?\)\)\s*$/gm,
 		/^.*include\([\s\S]*?(?:pi-studio-re|pi-rc-)[\s\S]*?\.jl"\)\s*$/gm,
 		/^.*source\([\s\S]*?(?:pi-studio-re|pi-rc-)[\s\S]*?local\s*=\s*\.GlobalEnv\)\s*$/gm,
 		/^.*:script\s+[\s\S]*?(?:pi-studio-re|pi-rc-)[\s\S]*?\.ghci"?\s*$/gm,
@@ -12384,7 +12414,7 @@ ${cssVarsBlock}
       <button id="clearWorkspaceBtn" type="button" title="Clear editor text and reset this tab to a fresh blank draft. Saved files and responses are not changed.">Reset editor</button>
       <button id="importFileBtn" type="button" title="Import a file as an editable copy.">Import file copy…</button>
       <input id="fileInput" class="file-input-hidden" type="file" tabindex="-1" aria-hidden="true" accept=".md,.markdown,.mdx,.qmd,.js,.mjs,.cjs,.jsx,.ts,.mts,.cts,.tsx,.py,.pyw,.sh,.bash,.zsh,.json,.jsonc,.json5,.rs,.c,.h,.cpp,.cxx,.cc,.hpp,.hxx,.jl,.f90,.f95,.f03,.f,.for,.r,.R,.m,.tex,.latex,.diff,.patch,.java,.go,.rb,.swift,.html,.htm,.css,.xml,.yaml,.yml,.toml,.lua,.txt,.rst,.adoc" />
-      <button id="getEditorBtn" type="button" title="Load the current terminal editor draft into Studio.">Load from pi editor</button>
+      <button id="getEditorBtn" type="button" aria-keyshortcuts="Meta+Shift+L Control+Shift+L" title="Copy the current Pi terminal input draft into Studio without clearing it. A later Studio Run clears that draft only if it remains unchanged. Shortcut: Cmd/Ctrl+Shift+L.">Load from pi editor</button>
       <button id="hideStudioHeaderBtn" class="header-visibility-btn" type="button" aria-controls="studioHeader" title="Hide the global Studio header. Restore it from the top-right edge.">Hide header</button>
       <button id="zenModeBtn" class="zen-mode-btn" type="button" title="Hide the Studio header and secondary controls. Shortcut: F9.">Zen</button>
     </div>
@@ -12425,7 +12455,7 @@ ${cssVarsBlock}
           </div>
           <div class="source-actions">
             <div class="source-actions-row">
-              <button id="sendRunBtn" type="button" title="Run editor text. While a direct run is active, this button becomes Stop. Cmd/Ctrl+Enter queues steering from the current editor text. Stop the active request with Esc.">Run editor text</button>
+              <button id="sendRunBtn" type="button" title="Run editor text. If Studio loaded or staged an unchanged Pi terminal draft, clear that draft after Pi accepts the run. While a direct run is active, this button becomes Stop. Cmd/Ctrl+Enter queues steering from the current editor text. Stop the active request with Esc.">Run editor text</button>
               <button id="queueSteerBtn" type="button" title="Queue steering is available while Run editor text is active." disabled>Queue steering</button>
             </div>
             <div class="source-actions-row repl-action-line" hidden>
@@ -12452,7 +12482,8 @@ ${cssVarsBlock}
                 <option value="current" selected>Suggestion model: current Pi model</option>
               </select>
               <button id="openCompanionBtn" type="button" title="Open a blank editor-only Studio tab.">New editor tab</button>
-              <button id="sendEditorBtn" type="button">Send current text to Pi editor</button>
+              <button id="sendEditorBtn" type="button" title="Replace the Pi terminal input draft with the current Studio text. A later Studio Run clears that staged draft only if it remains unchanged.">Send current text to Pi editor</button>
+              <button id="clearPiEditorBtn" type="button" title="Clear text currently waiting in the Pi terminal input editor without changing Studio text or conversation history.">Clear Pi editor text…</button>
             </div>
             <div class="source-actions-row">
               <button id="insertHeaderBtn" type="button" title="Insert annotated-reply protocol header (source metadata, [an: ...] syntax hint, precedence note, and end marker).">Annotation header</button>
@@ -12508,6 +12539,15 @@ ${cssVarsBlock}
                 <option value="off">Line numbers: Off</option>
                 <option value="on" selected>Line numbers: On</option>
               </select>
+              <select id="studioPaneLayoutSelect" class="studio-flat-select" aria-label="Studio pane layout" title="Choose whether the two main panes sit side by side or in a vertical stack.">
+                <option value="side-by-side">Layout: Side by side</option>
+                <option value="editor-top">Layout: Editor above</option>
+                <option value="response-top">Layout: Response above</option>
+              </select>
+              <select id="activityTrackingSelect" class="studio-flat-select" aria-label="Follow main Pi activity" title="Optionally follow main Pi activity from Working to the response view; off by default.">
+                <option value="off">Follow activity: Off</option>
+                <option value="on">Follow activity: On</option>
+              </select>
               <select id="editorFontSizeSelect" class="studio-flat-select" aria-label="Editor text size" title="Adjust raw editor text size.">
                 <option value="10">Editor text: 10px</option>
                 <option value="11">Editor text: 11px</option>
@@ -12607,7 +12647,7 @@ ${cssVarsBlock}
       <div id="rightSectionHeader" class="section-header">
         <div class="section-header-main">
           <span id="rightViewSelectWrap" class="studio-header-select-wrap">
-            <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/F/Q keep mnemonic shortcuts for Preview, Editor Preview, Working, Files, and Side questions.">
+            <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/F/R/Q keep mnemonic shortcuts for Preview, Editor Preview, Working, Files, REPL, and Side questions.">
               <option value="markdown">Response (Raw)</option>
               <option value="preview" selected>Response (Preview)</option>
               <option value="editor-preview">Editor (Preview)</option>
@@ -12725,6 +12765,7 @@ ${cssVarsBlock}
             <div><dt>Cmd/Ctrl+Alt+E</dt><dd>Switch the right pane directly to Editor Preview</dd></div>
             <div><dt>Cmd/Ctrl+Alt+W</dt><dd>Switch the right pane directly to Working</dd></div>
             <div><dt>Cmd/Ctrl+Alt+F</dt><dd>Switch the right pane directly to Files</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+R</dt><dd>Switch the right pane directly to REPL and focus Quick send when a session is selected</dd></div>
             <div><dt>Cmd/Ctrl+Alt+Q</dt><dd>Switch the right pane directly to Side questions</dd></div>
             <div><dt>F8</dt><dd>Focus editor text</dd></div>
             <div><dt>Shift+F8</dt><dd>Focus right-pane content</dd></div>
@@ -12740,7 +12781,7 @@ ${cssVarsBlock}
             <div><dt>Alt/Option+=</dt><dd>Increase the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+-</dt><dd>Decrease the active pane's text size when not editing text</dd></div>
             <div><dt>Alt/Option+0</dt><dd>Reset the active pane's text size when not editing text</dd></div>
-            <div><dt>Cmd/Ctrl+Alt+R</dt><dd>Refresh the focused or visible PDF preview from disk</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+Shift+R</dt><dd>Refresh the focused or visible PDF preview from disk</dd></div>
           </dl>
         </section>
         <section class="shortcuts-group">
@@ -12748,6 +12789,7 @@ ${cssVarsBlock}
           <dl>
             <div><dt>Cmd/Ctrl+S</dt><dd>Save editor when the disk revision still matches</dd></div>
             <div><dt>Cmd/Ctrl+Shift+S</dt><dd>Save editor as a new file</dd></div>
+            <div><dt>Cmd/Ctrl+Shift+L</dt><dd>Load the current Pi terminal input draft without clearing it</dd></div>
             <div class="shortcuts-full-only"><dt>Cmd/Ctrl+Enter</dt><dd>Run editor text, or queue steering during an active run</dd></div>
             <div><dt>Option/Alt+Tab or Cmd/Ctrl+Shift+Space</dt><dd>Suggest a completion at the editor cursor</dd></div>
             <div><dt>Tab</dt><dd>Insert a visible completion suggestion; otherwise indent selected editor text</dd></div>
@@ -12772,6 +12814,7 @@ ${cssVarsBlock}
         <section class="shortcuts-group">
           <h3>REPL</h3>
           <dl>
+            <div><dt>Cmd/Ctrl+Enter</dt><dd>Send exact Quick send text while its REPL composer is focused; Enter adds a new line</dd></div>
             <div><dt>Cmd/Ctrl+Shift+Enter</dt><dd>Send selection, chunks, or editor text to the active REPL when the right pane is REPL</dd></div>
           </dl>
         </section>
@@ -13637,6 +13680,23 @@ export default function (pi: ExtensionAPI) {
 		}
 	};
 
+	const reportPiEditorDraftDisposition = (
+		client: WebSocket,
+		requestId: string,
+		snapshot: StudioPiEditorDraftSnapshot | undefined,
+	) => {
+		if (!snapshot) return;
+		const result = consumeStudioPiEditorDraftSnapshot(lastCommandCtx?.ui, snapshot);
+		if (result.status === "not-requested") return;
+		emitDebugEvent("pi_editor_draft_disposition", { requestId, outcome: result.status });
+		sendToClient(client, {
+			type: "pi_editor_draft_result",
+			requestId,
+			outcome: result.status,
+			piEditorDraftSnapshot: snapshot,
+		});
+	};
+
 	const broadcast = (payload: unknown) => {
 		if (!serverState) return;
 		const serialized = JSON.stringify(payload);
@@ -15731,6 +15791,7 @@ export default function (pi: ExtensionAPI) {
 						queuedSteeringCount: getQueuedStudioSteeringCount(),
 					});
 					broadcastState();
+					reportPiEditorDraftDisposition(client, msg.requestId, msg.piEditorDraftSnapshot);
 				} catch (error) {
 					queuedStudioDirectRequests = queuedStudioDirectRequests.filter((request) => request.requestId !== msg.requestId);
 					if (studioDirectRunChain?.steeringPrompts.length) {
@@ -15754,6 +15815,7 @@ export default function (pi: ExtensionAPI) {
 
 			try {
 				pi.sendUserMessage(msg.text);
+				reportPiEditorDraftDisposition(client, msg.requestId, msg.piEditorDraftSnapshot);
 			} catch (error) {
 				clearStudioDirectRunState();
 				clearActiveRequest();
@@ -16498,7 +16560,8 @@ export default function (pi: ExtensionAPI) {
 				sendToClient(client, {
 					type: "editor_loaded",
 					requestId: msg.requestId,
-					message: "Draft loaded into pi editor.",
+					message: "Draft loaded into pi editor. A Studio Run will clear it if it remains unchanged.",
+					piEditorDraftSnapshot: createStudioPiEditorDraftSnapshot(msg.content),
 				});
 			} catch (error) {
 				sendToClient(client, {
@@ -16534,6 +16597,7 @@ export default function (pi: ExtensionAPI) {
 					type: "editor_snapshot",
 					requestId: msg.requestId,
 					content,
+					piEditorDraftSnapshot: createStudioPiEditorDraftSnapshot(content),
 				});
 			} catch (error) {
 				sendToClient(client, {
@@ -16544,6 +16608,43 @@ export default function (pi: ExtensionAPI) {
 			}
 			return;
 		}
+
+		if (msg.type === "clear_pi_editor_request") {
+			if (!isValidRequestId(msg.requestId)) {
+				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Invalid request ID." });
+				return;
+			}
+			if (isStudioBusy()) {
+				sendToClient(client, { type: "busy", requestId: msg.requestId, message: "Studio is busy." });
+				return;
+			}
+			if (!lastCommandCtx || !lastCommandCtx.hasUI) {
+				sendToClient(client, {
+					type: "error",
+					requestId: msg.requestId,
+					message: "No interactive pi editor context is available.",
+				});
+				return;
+			}
+
+			try {
+				const hadContent = lastCommandCtx.ui.getEditorText().length > 0;
+				if (hadContent) lastCommandCtx.ui.setEditorText("");
+				lastCommandCtx.ui.notify(hadContent ? "Pi editor text cleared from Studio." : "Pi editor text is already empty.", "info");
+				sendToClient(client, {
+					type: "pi_editor_cleared",
+					requestId: msg.requestId,
+					cleared: hadContent,
+				});
+			} catch (error) {
+				sendToClient(client, {
+					type: "error",
+					requestId: msg.requestId,
+					message: `Failed to clear pi editor text: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			}
+			return;
+		}
 	};
 
 	const disposePreparedPdfExport = (entry: PreparedStudioPdfExport | null | undefined) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.57",
+  "version": "0.9.59",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/studio-pi-editor-draft.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+
+export const STUDIO_PI_EDITOR_DRAFT_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+export function createStudioPiEditorDraftSnapshot(content) {
+	const buffer = Buffer.from(String(content ?? ""), "utf8");
+	return Object.freeze({
+		fingerprint: `sha256:${createHash("sha256").update(buffer).digest("hex")}`,
+		byteLength: buffer.length,
+	});
+}
+
+export function normalizeStudioPiEditorDraftSnapshot(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const fingerprint = typeof value.fingerprint === "string"
+		? value.fingerprint.trim().toLowerCase()
+		: "";
+	const byteLength = value.byteLength;
+	if (!STUDIO_PI_EDITOR_DRAFT_FINGERPRINT_PATTERN.test(fingerprint)) return null;
+	if (typeof byteLength !== "number" || !Number.isSafeInteger(byteLength) || byteLength < 0) return null;
+	return Object.freeze({ fingerprint, byteLength });
+}
+
+export function studioPiEditorDraftMatchesSnapshot(content, snapshot) {
+	const expected = normalizeStudioPiEditorDraftSnapshot(snapshot);
+	if (!expected) return false;
+	const current = createStudioPiEditorDraftSnapshot(content);
+	return current.byteLength === expected.byteLength && current.fingerprint === expected.fingerprint;
+}
+
+export function consumeStudioPiEditorDraftSnapshot(ui, snapshot) {
+	const expected = normalizeStudioPiEditorDraftSnapshot(snapshot);
+	if (!expected) return Object.freeze({ status: "not-requested" });
+	if (!ui || typeof ui.getEditorText !== "function" || typeof ui.setEditorText !== "function") {
+		return Object.freeze({ status: "unavailable" });
+	}
+
+	try {
+		const current = String(ui.getEditorText() ?? "");
+		if (current.length === 0) return Object.freeze({ status: "already-empty" });
+		if (!studioPiEditorDraftMatchesSnapshot(current, expected)) {
+			return Object.freeze({ status: "changed" });
+		}
+		ui.setEditorText("");
+		return Object.freeze({ status: "cleared" });
+	} catch {
+		return Object.freeze({ status: "unavailable" });
+	}
+}