@timurproko/a1 0.1.8-dev.282 → 0.1.8-dev.289

package/bin/ui.js

@@ -2,6 +2,16 @@
 
 const startup = await import("../dist/foundation/startup/index.js");
 startup.enableEnvironmentCompileCache(process.env);
+const profile = process.env.A1_LAUNCH_PROFILE ?? "a1";
+const { installFatalExit } = await import("../dist/foundation/terminal-cleanup/index.js");
+const { resolveProductPaths } = await import("../dist/foundation/lifecycle/index.js");
+const { join } = await import("node:path");
+let runningApplication;
+const fatal = profile === "a1" ? installFatalExit({
+  directory: join(resolveProductPaths().runtimeDir, "crashes"),
+  releaseId: process.env.A1_RELEASE_ID,
+  dispose: () => runningApplication?.dispose(),
+}) : undefined;
 // Performance: begin the exact launch graph together while the trace write is pending.
 // Direct owned-module entries avoid evaluating unrelated barrel exports before first paint.
 const modules = Promise.all([
@@ -32,7 +42,6 @@ assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), m
 await startup.markStartupPhase(process.env, "ui-modules-loaded");
 
 const sessionSelection = parseSessionSelection(process.argv.slice(2));
-const profile = process.env.A1_LAUNCH_PROFILE ?? "a1";
 Promise.resolve().then(() => {
   if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
   return runSelectedInteractiveRuntime(profile, {
@@ -45,12 +54,15 @@ Promise.resolve().then(() => {
         sessionForkPrompt: createConsoleSessionForkPrompt(),
         ...(sessionSelection === undefined ? {} : { sessionSelection }),
       });
+      runningApplication = application;
       return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
     },
   });
 }).then(
-  code => { process.exitCode = code; },
+  code => { fatal?.remove(); process.exitCode = code; },
   error => {
+    if (fatal && error?.name !== "PiSessionSelectionError") { fatal.fail(error); return; }
+    fatal?.remove();
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = error?.name === "PiSessionSelectionError" ? error.exitCode : 1;
   },

package/dist/contracts/owned-ui/image-attachments.d.ts

@@ -0,0 +1,29 @@
+import type { OwnedUiImageAttachment } from "./model.js";
+export declare const MAX_PROMPT_IMAGES = 8;
+/** Limit applies to canonical ASCII base64, not decoded image bytes. */
+export declare const MAX_IMAGE_DATA_BYTES: number;
+declare const MESSAGES: {
+    readonly "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.";
+    readonly "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.";
+    readonly "image-data": "Image data is invalid. Paste a valid image again.";
+    readonly "image-mime": "Image MIME type is invalid. Paste a supported image again.";
+    readonly "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.";
+    readonly "image-pixels": "Source image exceeds 40 million pixels or a 32768-pixel dimension. Reduce its dimensions and paste again.";
+    readonly "image-conversion": "This image cannot be safely resized. Paste a PNG or JPEG screenshot instead.";
+    readonly "image-codec": "Image preparation is unavailable. Check the installation and paste again.";
+    readonly "image-output": "Image cannot fit the output limits without excessive quality loss. Crop it and paste again.";
+    readonly "image-timeout": "Image preparation timed out. Remove the failed image and paste again.";
+    readonly "image-busy": "Image preparation is full (8 pending images). Wait or remove an image before pasting again.";
+    readonly "image-canceled": "Image preparation was canceled. Paste the image again.";
+    readonly "image-pending": "Image is still preparing. Wait before submitting.";
+};
+/** Trusted, payload-free diagnostics for user-correctable attachment failures. */
+export declare class ImageAttachmentError extends TypeError {
+    readonly code: keyof typeof MESSAGES;
+    constructor(code: keyof typeof MESSAGES);
+}
+/** Checks encoded length before decoding or copying a clipboard payload. */
+export declare function assertImageEncodedSize(data: string): void;
+/** Final command admission also covers restored and deferred non-clipboard inputs. */
+export declare function assertPromptImages(images: readonly OwnedUiImageAttachment[]): void;
+export {};

package/dist/contracts/owned-ui/image-attachments.js

@@ -0,0 +1,60 @@
+export const MAX_PROMPT_IMAGES = 8;
+/** Limit applies to canonical ASCII base64, not decoded image bytes. */
+export const MAX_IMAGE_DATA_BYTES = 8 * 1024 * 1024;
+const MESSAGES = {
+    "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.",
+    "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.",
+    "image-data": "Image data is invalid. Paste a valid image again.",
+    "image-mime": "Image MIME type is invalid. Paste a supported image again.",
+    "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.",
+    "image-pixels": "Source image exceeds 40 million pixels or a 32768-pixel dimension. Reduce its dimensions and paste again.",
+    "image-conversion": "This image cannot be safely resized. Paste a PNG or JPEG screenshot instead.",
+    "image-codec": "Image preparation is unavailable. Check the installation and paste again.",
+    "image-output": "Image cannot fit the output limits without excessive quality loss. Crop it and paste again.",
+    "image-timeout": "Image preparation timed out. Remove the failed image and paste again.",
+    "image-busy": "Image preparation is full (8 pending images). Wait or remove an image before pasting again.",
+    "image-canceled": "Image preparation was canceled. Paste the image again.",
+    "image-pending": "Image is still preparing. Wait before submitting.",
+};
+/** Trusted, payload-free diagnostics for user-correctable attachment failures. */
+export class ImageAttachmentError extends TypeError {
+    code;
+    constructor(code) {
+        super(MESSAGES[code]);
+        this.code = code;
+        this.name = "ImageAttachmentError";
+    }
+}
+/** Checks encoded length before decoding or copying a clipboard payload. */
+export function assertImageEncodedSize(data) {
+    if (typeof data !== "string" || data.length === 0)
+        throw new ImageAttachmentError("image-data");
+    if (Math.ceil(data.length / 4) * 4 > MAX_IMAGE_DATA_BYTES)
+        throw new ImageAttachmentError("image-size");
+}
+const VALIDATED_IMAGES = new WeakSet();
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Final command admission also covers restored and deferred non-clipboard inputs. */
+export function assertPromptImages(images) {
+    if (!Array.isArray(images) || images.length > MAX_PROMPT_IMAGES)
+        throw new ImageAttachmentError("image-count");
+    for (const image of images) {
+        if (!image || image.type !== "image")
+            throw new ImageAttachmentError("image-data");
+        if (VALIDATED_IMAGES.has(image))
+            continue;
+        assertImageEncodedSize(image.data);
+        if (!/^[A-Za-z0-9+/]+={0,2}$/.test(image.data) || image.data.length % 4 !== 0
+            || (image.data.endsWith("==") && (BASE64_ALPHABET.indexOf(image.data.at(-3) ?? "") & 15) !== 0)
+            || (image.data.endsWith("=") && !image.data.endsWith("==") && (BASE64_ALPHABET.indexOf(image.data.at(-2) ?? "") & 3) !== 0)) {
+            throw new ImageAttachmentError("image-data");
+        }
+        if (typeof image.mimeType !== "string" || image.mimeType.length > 256 || !/^image\/[a-z0-9.+-]+$/i.test(image.mimeType)) {
+            throw new ImageAttachmentError("image-mime");
+        }
+        // Security: cache only immutable own data properties, never frozen objects with changing getters.
+        if (Object.isFrozen(image) && ["type", "data", "mimeType"].every(key => Object.getOwnPropertyDescriptor(image, key)?.value === image[key])) {
+            VALIDATED_IMAGES.add(image);
+        }
+    }
+}

package/dist/contracts/owned-ui/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./image-attachments.js";
 export * from "./prompt-suggestions.js";
 export * from "./validation.js";

package/dist/contracts/owned-ui/index.js

@@ -1,4 +1,5 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./image-attachments.js";
 export * from "./prompt-suggestions.js";
 export * from "./validation.js";

package/dist/contracts/owned-ui/validation.js

@@ -1,12 +1,11 @@
 import { OWNED_UI_CONTRACT_VERSION, } from "./model.js";
+import { assertPromptImages } from "./image-attachments.js";
 const MAX_ID_LENGTH = 128;
 const MAX_LABEL_LENGTH = 256;
 const MAX_MESSAGE_LENGTH = 4_096;
 const MAX_TEXT_BYTES = 256 * 1024;
 const MAX_PAYLOAD_BYTES = 64 * 1024;
 const MAX_SESSION_VIEW_BYTES = 1024 * 1024;
-const MAX_IMAGE_DATA_BYTES = 8 * 1024 * 1024;
-const MAX_PROMPT_IMAGES = 8;
 const MAX_BLOCKS = 10_000;
 const MAX_CUSTOMIZATIONS = 1_000;
 const MAX_DIAGNOSTICS = 1_000;
@@ -57,13 +56,7 @@ export function assertOwnedUiCommand(command) {
         case "follow-up":
             assertBoundedText(command.text, "owned-UI prompt text", MAX_TEXT_BYTES);
             if (command.images !== undefined) {
-                assertCollection(command.images, "owned-UI prompt images", MAX_PROMPT_IMAGES);
-                for (const image of command.images) {
-                    if (image.type !== "image")
-                        throw new TypeError("owned-UI prompt image type is invalid");
-                    assertBoundedText(image.data, "owned-UI prompt image data", MAX_IMAGE_DATA_BYTES);
-                    assertBoundedText(image.mimeType, "owned-UI prompt image MIME type", MAX_LABEL_LENGTH);
-                }
+                assertPromptImages(command.images);
             }
             return;
         case "abort":

package/dist/features/owned-ui/run.js

@@ -1,6 +1,9 @@
 import { markStartupPhase } from "../../foundation/startup/index.js";
+import { boundedCleanup } from "../../foundation/terminal-cleanup/index.js";
 export async function runOwnedUi(options) {
     const { application, settings } = options;
+    let failed = false;
+    let originalFailure;
     try {
         if (settings)
             await settings.load();
@@ -11,7 +14,19 @@ export async function runOwnedUi(options) {
             await application.waitUntilStopped();
         return 0;
     }
+    catch (error) {
+        failed = true;
+        originalFailure = error;
+        throw error;
+    }
     finally {
-        await application.dispose();
+        try {
+            await boundedCleanup(() => application.dispose(), 2500);
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([originalFailure, error], "Owned UI run and cleanup failed", { cause: originalFailure });
+            throw error;
+        }
     }
 }

package/dist/foundation/release/bootstrap.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { restoreAfterOwnedExit } from "../terminal-cleanup/index.js";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { connect } from "node:net";
 import { platform } from "node:os";
@@ -234,7 +235,7 @@ async function launchUi(release, environment, sessionArgs) {
             windowsHide: false,
         });
         child.once("error", rejectPromise);
-        child.once("close", (code, signal) => resolvePromise(code ?? (signal ? 1 : 0)));
+        child.once("close", (code, signal) => resolvePromise(restoreAfterOwnedExit(environment[PRODUCT_IDENTITY.environment.launchProfile] === "a1", code, signal)));
     });
 }
 export function releaseEnvironment(environment, release) {

package/dist/foundation/terminal-cleanup/fatal-exit.d.ts

@@ -0,0 +1,12 @@
+export interface FatalExitOptions {
+    readonly directory: string;
+    readonly releaseId?: string;
+    readonly restore?: () => void;
+    readonly dispose?: () => Promise<unknown> | void;
+    readonly timeoutMs?: number;
+}
+export declare function writeFatalDiagnostic(directory: string, origin: string, error: unknown, releaseId?: string): Promise<string | null>;
+export declare function installFatalExit(options: FatalExitOptions): {
+    fail(error: unknown): void;
+    remove(): void;
+};

package/dist/foundation/terminal-cleanup/fatal-exit.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { writeSync } from "node:fs";
+import { join } from "node:path";
+import { boundedCleanup, restoreProcessTerminal } from "./terminal-reset.js";
+export async function writeFatalDiagnostic(directory, origin, error, releaseId) {
+    try {
+        // Security: only known classifications and code locations are retained. Error messages,
+        // function names, arbitrary paths, and request objects are never persisted.
+        const cleanupFailed = error instanceof AggregateError && error.cause instanceof Error;
+        const primary = cleanupFailed ? error.cause : error;
+        const classification = primary instanceof TypeError ? "TypeError" : primary instanceof RangeError ? "RangeError" : "Error";
+        const stack = primary instanceof Error && typeof primary.stack === "string" ? primary.stack.slice(0, 32768) : "";
+        const locations = stack.split("\n").slice(1).flatMap(line => {
+            const match = /\/(?:dist|src)\/([a-zA-Z0-9_./-]+\.[cm]?[jt]s):(\d+):(\d+)\)?$/.exec(line.replaceAll("\\", "/"));
+            return match ? [{ file: match[1].slice(0, 160), line: Number(match[2]), column: Number(match[3]) }] : [];
+        }).slice(0, 16);
+        const record = {
+            timestamp: new Date().toISOString(),
+            origin: ["uncaughtException", "unhandledRejection", "entry"].includes(origin) ? origin : "entry",
+            classification, cleanupFailed, locations, node: process.version, platform: process.platform,
+            releaseId: releaseId && /^[a-zA-Z0-9._-]{1,128}$/.test(releaseId) ? releaseId : "unknown",
+        };
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const name = `fatal-${Date.now()}-${randomUUID()}.json`;
+        const path = join(directory, name);
+        const text = JSON.stringify(record, null, 2);
+        if (Buffer.byteLength(text) > 16 * 1024)
+            return null;
+        await writeFile(path, text, { flag: "wx", mode: 0o600 });
+        const names = (await readdir(directory)).filter(file => /^fatal-\d+-[a-f0-9-]+\.json$/.test(file)).sort().reverse();
+        await Promise.all(names.slice(10).map(file => unlink(join(directory, file)).catch(() => undefined)));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function installFatalExit(options) {
+    let failing = false;
+    const restore = () => { try {
+        (options.restore ?? restoreProcessTerminal)();
+    }
+    catch { } };
+    const terminate = (origin, error) => {
+        if (failing)
+            return;
+        failing = true;
+        process.exitCode = 1;
+        // Security: stop accepting input immediately; fatal errors never resume normal work.
+        try {
+            process.stdin.pause();
+            process.stdin.removeAllListeners("data");
+        }
+        catch { }
+        restore();
+        let record = null;
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            restore();
+            try {
+                const location = record?.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 512);
+                writeSync(2, `A1 stopped after an unexpected error.${location ? ` Diagnostic: ${location}` : " Diagnostic storage unavailable."}\n`);
+            }
+            catch { }
+            process.exit(1);
+        };
+        const deadline = setTimeout(finish, options.timeoutMs ?? 1000);
+        void Promise.all([
+            writeFatalDiagnostic(options.directory, origin, error, options.releaseId).then(path => { record = path; }),
+            boundedCleanup(() => options.dispose?.(), options.timeoutMs ?? 1000).catch(() => undefined),
+        ]).then(() => { clearTimeout(deadline); finish(); }, finish);
+    };
+    const exception = (error) => terminate("uncaughtException", error);
+    const rejection = (error) => terminate("unhandledRejection", error);
+    process.on("uncaughtException", exception);
+    process.on("unhandledRejection", rejection);
+    return {
+        fail: error => terminate("entry", error),
+        remove() { process.off("uncaughtException", exception); process.off("unhandledRejection", rejection); },
+    };
+}

package/dist/foundation/terminal-cleanup/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./terminal-reset.js";
+export * from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/index.js

@@ -0,0 +1,2 @@
+export * from "./terminal-reset.js";
+export * from "./fatal-exit.js";

package/dist/foundation/terminal-cleanup/terminal-reset.d.ts

@@ -0,0 +1,4 @@
+export declare const EMERGENCY_TERMINAL_RESET: string;
+export declare function restoreProcessTerminal(): void;
+export declare function restoreAfterOwnedExit(ownsTerminal: boolean, code: number | null, signal: string | null, restore?: () => void): number;
+export declare function boundedCleanup(cleanup: () => Promise<unknown> | void, timeoutMs?: number): Promise<void>;

package/dist/foundation/terminal-cleanup/terminal-reset.js

@@ -0,0 +1,40 @@
+import { writeSync } from "node:fs";
+// Protocol: reset modes on both screens; setting keyboard flags to zero is idempotent,
+// unlike repeatedly popping a keyboard-protocol stack owned by a parent application.
+export const EMERGENCY_TERMINAL_RESET = "\x1b[?2026l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1004l\x1b[?1006l"
+    + "\x1b[?2004l\x1b[=0u\x1b[>4;0m\x1b]8;;\x1b\\\x1b[0m\x1b[r\x1b[?7h\x1b[?25h"
+    + "\x1b[?1049l\x1b[r\x1b[?7h\x1b[?25h\x1b]9;4;0\x07";
+export function restoreProcessTerminal() {
+    try {
+        if (process.stdout.isTTY)
+            writeSync(process.stdout.fd, EMERGENCY_TERMINAL_RESET);
+    }
+    catch { }
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(false);
+    }
+    catch { }
+}
+export function restoreAfterOwnedExit(ownsTerminal, code, signal, restore = restoreProcessTerminal) {
+    const outcome = code ?? (signal ? 1 : 0);
+    if (ownsTerminal && outcome !== 0) {
+        try {
+            restore();
+        }
+        catch { }
+    }
+    return outcome;
+}
+export async function boundedCleanup(cleanup, timeoutMs = 1000) {
+    let timer;
+    try {
+        await Promise.race([
+            Promise.resolve().then(cleanup),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Cleanup deadline exceeded")), timeoutMs); }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/integrations/pi/components/owned-editor-ux.d.ts

@@ -15,6 +15,7 @@ export interface OwnedEditorUxInterceptor {
     hasSelection?(): boolean;
     ownsPointer?(): boolean;
     pasteClipboard?(): boolean;
+    cancelPendingPastes?(): void;
 }
 export interface OwnedEditorPointerEvent {
     readonly kind: "press" | "motion" | "release";
@@ -36,6 +37,7 @@ export declare class OwnedEditorUxInterception {
     handleInput(data: string): void;
     render(width: number): string[];
     reset(): void;
+    cancelPendingPastes(): void;
     handlePointer(event: OwnedEditorPointerEvent): boolean;
     hasSelection(): boolean;
     ownsPointer(): boolean;
@@ -44,6 +46,10 @@ export declare class OwnedEditorUxInterception {
 export interface PromptSelectionUxOptions {
     readonly copyText: (text: string) => void;
     readonly readClipboardContent: () => Promise<PiShellClipboardContent | null>;
+    readonly beginClipboardPaste?: () => {
+        readonly marker: string;
+        readonly result: Promise<string>;
+    };
     readonly transformPastedContent: (content: PiShellClipboardContent) => string;
     readonly atomicRanges: (line: string) => readonly PiShellEditorTextRange[];
     readonly expandCopiedText: (text: string) => string;

package/dist/integrations/pi/components/owned-editor-ux.js

@@ -31,6 +31,10 @@ export class OwnedEditorUxInterception {
         for (const interceptor of this.interceptors)
             interceptor.reset();
     }
+    cancelPendingPastes() {
+        for (const interceptor of this.interceptors)
+            interceptor.cancelPendingPastes?.();
+    }
     handlePointer(event) {
         return this.interceptors.some(interceptor => interceptor.handlePointer?.(event) === true);
     }
@@ -60,6 +64,7 @@ class PromptSelectionInterceptor {
     #lastClick;
     #redoStack = [];
     #selectionRevision = 0;
+    #pasteGeneration = 0;
     #wordDirection;
     #geometry;
     constructor(editor, keybindings, options) {
@@ -245,6 +250,7 @@ class PromptSelectionInterceptor {
         this.#redoStack = [];
         this.#selectionRevision += 1;
     }
+    cancelPendingPastes() { this.#pasteGeneration += 1; }
     hasSelection() {
         return this.#activeRange() !== undefined;
     }
@@ -404,6 +410,20 @@ class PromptSelectionInterceptor {
         this.#requestRender();
     }
     #pasteFromClipboard() {
+        if (this.options.beginClipboardPaste !== undefined) {
+            const generation = this.#pasteGeneration;
+            const restore = this.#orderedSelection() === undefined ? "" : this.#selectedText();
+            const paste = this.options.beginClipboardPaste();
+            if (this.#orderedSelection() !== undefined)
+                this.#replaceSelection(paste.marker);
+            else
+                this.editor.insertTextAtCursor(paste.marker);
+            this.#requestRender();
+            const replace = (text) => { if (generation === this.#pasteGeneration)
+                this.#replacePasteMarker(paste.marker, text || restore); };
+            void paste.result.then(replace).catch(() => replace(restore));
+            return;
+        }
         const revision = this.#selectionRevision;
         const selection = this.#orderedSelection();
         const atomicFocus = this.#atomicFocus();
@@ -428,6 +448,44 @@ class PromptSelectionInterceptor {
             this.#requestRender();
         }).catch(() => { });
     }
+    #replacePasteMarker(marker, replacement) {
+        const current = this.editor.getText();
+        const from = current.indexOf(marker);
+        if (from < 0)
+            return;
+        const to = from + marker.length;
+        const text = normalizeInsertedText(replacement);
+        const lines = editorState(this.editor).lines;
+        const remap = (position) => {
+            const offset = positionOffset(lines, position);
+            return offset <= from ? offset : offset >= to ? offset + text.length - marker.length : from + text.length;
+        };
+        const cursor = remap(this.#cursor());
+        const selection = this.#selection === undefined ? undefined : { anchor: remap(this.#selection.anchor), head: remap(this.#selection.head) };
+        const next = current.slice(0, from) + text + current.slice(to);
+        // Compatibility: completing a paste updates its provisional undo snapshots, not the user's undo history.
+        editorState(this.editor).lines = next.split("\n");
+        const undo = Reflect.get(this.editor, "undoStack");
+        const snapshots = typeof undo === "object" && undo !== null ? Reflect.get(undo, "stack") : undefined;
+        if (Array.isArray(snapshots))
+            for (const snapshot of snapshots) {
+                const state = typeof snapshot === "object" && snapshot !== null ? Reflect.get(snapshot, "state") : undefined;
+                if (isEditorState(state))
+                    replaceSnapshotMarker(state, marker, text);
+            }
+        for (const snapshot of this.#redoStack) {
+            const state = { lines: snapshot.text.split("\n"), cursorLine: snapshot.cursor.line, cursorCol: snapshot.cursor.col };
+            replaceSnapshotMarker(state, marker, text);
+            snapshot.text = state.lines.join("\n");
+            snapshot.cursor = { line: state.cursorLine, col: state.cursorCol };
+        }
+        this.#setCursor(positionAtOffset(next, cursor));
+        this.editor.onChange?.(this.editor.getText());
+        this.editor.invalidate();
+        if (selection !== undefined)
+            this.#selection = { anchor: positionAtOffset(next, selection.anchor), head: positionAtOffset(next, selection.head) };
+        this.#requestRender();
+    }
     #replaceSelection(text) {
         const selection = this.#orderedSelection();
         if (selection === undefined) {
@@ -825,6 +883,19 @@ function positionAtOffset(text, requestedOffset) {
     const before = text.slice(0, offset).split("\n");
     return { line: before.length - 1, col: (before.at(-1) ?? "").length };
 }
+function replaceSnapshotMarker(state, marker, replacement) {
+    const text = state.lines.join("\n");
+    const from = text.indexOf(marker);
+    if (from < 0)
+        return;
+    const cursor = positionOffset(state.lines, { line: state.cursorLine, col: state.cursorCol });
+    const offset = cursor <= from ? cursor : cursor >= from + marker.length ? cursor + replacement.length - marker.length : from + replacement.length;
+    const next = text.slice(0, from) + replacement + text.slice(from + marker.length);
+    const position = positionAtOffset(next, offset);
+    state.lines = next.split("\n");
+    state.cursorLine = position.line;
+    state.cursorCol = position.col;
+}
 function normalizeInsertedText(text) {
     return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\t/g, "    ");
 }

package/dist/integrations/pi/components/shell-editor-autocomplete.js

@@ -54,6 +54,7 @@ export function createPiShellEditor(options) {
             createPromptSelectionInterceptor(editor, keybindings, {
                 copyText: options.onCopyText ?? (() => { }),
                 readClipboardContent: options.readClipboardContent ?? (async () => null),
+                ...(options.beginClipboardPaste === undefined ? {} : { beginClipboardPaste: options.beginClipboardPaste }),
                 transformPastedContent: options.transformPastedContent ?? (content => content.kind === "text" ? content.text : ""),
                 atomicRanges: options.editorAtomicRanges ?? (() => []),
                 expandCopiedText: options.expandCopiedEditorText ?? (text => text),
@@ -202,6 +203,7 @@ export function createPiShellEditor(options) {
         ownsPointer: () => editorUx?.ownsPointer() ?? false,
         handlePointer: event => editorUx?.handlePointer(event) ?? false,
         pasteClipboard: () => editorUx?.pasteClipboard() ?? false,
+        cancelPendingPastes: () => editorUx?.cancelPendingPastes(),
     };
 }
 function autocompleteCommand(command, addition) {

package/dist/integrations/pi/components/shell-shared-facade.d.ts

@@ -47,6 +47,7 @@ export interface PiShellEditorPort extends PiShellComponentPort {
     ownsPointer(): boolean;
     handlePointer(event: PiShellEditorPointerEvent): boolean;
     pasteClipboard(): boolean;
+    cancelPendingPastes?(): void;
 }
 export interface PiShellAutocompleteCommand {
     readonly name: string;
@@ -135,7 +136,11 @@ export interface PiShellEditorOptions {
     readonly onDequeue?: (() => void) | undefined;
     readonly onPromptSuggestionAccepted?: (text: string) => void;
     readonly onCopyText?: (text: string) => void;
-    readonly readClipboardContent?: () => Promise<PiShellClipboardContent | null>;
+    readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
+    readonly beginClipboardPaste?: () => {
+        readonly marker: string;
+        readonly result: Promise<string>;
+    };
     readonly transformPastedContent?: (content: PiShellClipboardContent) => string;
     readonly editorAtomicRanges?: (line: string) => readonly PiShellEditorTextRange[];
     readonly expandCopiedEditorText?: (text: string) => string;

package/dist/integrations/pi/session-ui/clipboard-image.d.ts

@@ -7,5 +7,5 @@ export interface ClipboardImageData {
  * Clipboard adapters are untrusted at this boundary, so reject representations
  * that Node's permissive base64 decoder would otherwise partially accept.
  */
-export declare function canonicalizeClipboardImage(image: ClipboardImageData): ClipboardImageData | null;
-export declare function canonicalizeStandardBase64(value: string): string | null;
+export declare function canonicalizeClipboardImage(image: ClipboardImageData, source?: boolean): ClipboardImageData | null;
+export declare function canonicalizeStandardBase64(value: string, source?: boolean): string | null;

package/dist/integrations/pi/session-ui/clipboard-image.js

@@ -1,15 +1,22 @@
+import { ImageAttachmentError, MAX_IMAGE_DATA_BYTES } from "../../../contracts/owned-ui/index.js";
+import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
 const STANDARD_BASE64 = /^[A-Za-z0-9+/]*={0,2}$/u;
 /**
  * Converts valid padded or unpadded standard base64 into its unique padded form.
  * Clipboard adapters are untrusted at this boundary, so reject representations
  * that Node's permissive base64 decoder would otherwise partially accept.
  */
-export function canonicalizeClipboardImage(image) {
-    const data = canonicalizeStandardBase64(image.data);
+export function canonicalizeClipboardImage(image, source = false) {
+    const data = canonicalizeStandardBase64(image.data, source);
     return data === null ? null : { data, mimeType: image.mimeType };
 }
-export function canonicalizeStandardBase64(value) {
-    if (value.length === 0 || !STANDARD_BASE64.test(value))
+export function canonicalizeStandardBase64(value, source = false) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const maximum = source ? Math.ceil(MAX_SOURCE_IMAGE_BYTES / 3) * 4 : MAX_IMAGE_DATA_BYTES;
+    if (Math.ceil(value.length / 4) * 4 > maximum)
+        throw new ImageAttachmentError(source ? "image-source-size" : "image-size");
+    if (!STANDARD_BASE64.test(value))
         return null;
     const paddingStart = value.indexOf("=");
     const core = paddingStart < 0 ? value : value.slice(0, paddingStart);
@@ -22,6 +29,8 @@ export function canonicalizeStandardBase64(value) {
         return null;
     const padded = `${core}${"=".repeat(requiredPadding)}`;
     const decoded = Buffer.from(padded, "base64");
+    if (source && decoded.length > MAX_SOURCE_IMAGE_BYTES)
+        throw new ImageAttachmentError("image-source-size");
     if (decoded.length === 0)
         return null;
     const canonical = decoded.toString("base64");

package/dist/integrations/pi/session-ui/image-preparation-client.d.ts

@@ -0,0 +1,20 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+import type { ImagePreparationLimits, PreparedImage } from "./image-preparation.js";
+import type { ImageWorkerRequest } from "./image-worker.js";
+export type PreparedClipboardContent = {
+    readonly kind: "text";
+    readonly text: string;
+} | ({
+    readonly kind: "image";
+} & PreparedImage) | null;
+export interface ImagePasteJob {
+    readonly result: Promise<PreparedClipboardContent>;
+    cancel(): void;
+}
+/** Owns bounded paste acquisition and one off-thread conversion, canceled on session disposal. */
+export declare class ImagePreparationClient {
+    #private;
+    start(read?: (signal: AbortSignal) => Promise<PiShellClipboardContent | null>, limits?: ImagePreparationLimits): ImagePasteJob;
+    dispose(): Promise<void>;
+}
+export declare function runImageWorker<T>(request: ImageWorkerRequest, signal: AbortSignal): Promise<T>;