@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/app/session-shell/helper-pool.js

@@ -0,0 +1,98 @@
+/** How long an unused spare helper may idle before it is stopped so a background session holds no extra process. */
+export const HELPER_SPARE_IDLE_MS = 5 * 60_000;
+/**
+ * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
+ * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
+ * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
+ */
+export class HelperPool {
+    #fork;
+    #stop;
+    #idleMs;
+    #spare;
+    #enabled = false;
+    #disposed = false;
+    constructor(options) {
+        this.#fork = options.fork;
+        this.#stop = options.stop;
+        this.#idleMs = options.idleMs ?? HELPER_SPARE_IDLE_MS;
+    }
+    /** Whether a spare is currently held (ready or still starting). */
+    get warmed() { return this.#spare !== undefined; }
+    /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
+    warm() {
+        if (this.#disposed)
+            return;
+        this.#enabled = true;
+        this.replenish();
+    }
+    /** Forks the next spare after a request released its child; a no-op until the owner warmed the pool. A fork failure leaves the pool empty. */
+    replenish() {
+        if (!this.#enabled || this.#disposed || this.#spare !== undefined)
+            return;
+        let child;
+        try {
+            child = this.#fork();
+        }
+        catch {
+            return;
+        }
+        const onMessage = (value) => {
+            if (this.#spare?.child === child && value?.kind === "ready")
+                this.#spare.ready = true;
+        };
+        const onExit = () => { if (this.#spare?.child === child) {
+            this.#drop();
+        } };
+        const detach = () => {
+            child.off("message", onMessage);
+            child.off("exit", onExit);
+            child.off("close", onExit);
+            child.off("error", onExit);
+        };
+        // Performance: an idle spare must not keep a background session alive or hold a process forever.
+        const timer = setTimeout(() => { if (this.#spare?.child === child)
+            this.#discard(); }, this.#idleMs);
+        timer.unref();
+        child.on("message", onMessage);
+        child.once("exit", onExit);
+        child.once("close", onExit);
+        child.once("error", onExit);
+        // Invariant: an idle spare never keeps the owner's process alive; taking it refs it again.
+        child.unref();
+        child.channel?.unref();
+        this.#spare = { child, ready: false, timer, detach };
+    }
+    /** Hands the spare to a request, with the pool's listeners removed; returns nothing when no live spare is held. */
+    take() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return undefined;
+        this.#drop();
+        if (spare.child.exitCode !== null || spare.child.signalCode !== null || !spare.child.connected)
+            return undefined;
+        spare.child.ref();
+        spare.child.channel?.ref();
+        return { child: spare.child, ready: spare.ready };
+    }
+    /** Stops the held spare and refuses further warming. */
+    dispose() {
+        this.#disposed = true;
+        this.#discard();
+    }
+    #drop() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return;
+        this.#spare = undefined;
+        clearTimeout(spare.timer);
+        spare.detach();
+    }
+    #discard() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return;
+        this.#drop();
+        this.#stop(spare.child);
+    }
+}

package/dist/app/session-shell/image-preparation-client.d.ts

@@ -0,0 +1,20 @@
+import type { PiShellClipboardContent } from "../../integrations/pi/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>;

package/dist/app/session-shell/image-preparation-client.js

@@ -0,0 +1,145 @@
+import { Worker } from "node:worker_threads";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+import { IMAGE_PREPARATION_MS, MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
+/** Owns bounded paste acquisition and one off-thread conversion, canceled on session disposal. */
+export class ImagePreparationClient {
+    #active = new Set();
+    #queue = [];
+    #stopping = new Set();
+    #converting = false;
+    #disposed = false;
+    start(read, limits = {}) {
+        const controller = new AbortController();
+        if (this.#disposed || this.#active.size >= 8) {
+            const result = Promise.reject(new ImageAttachmentError(this.#disposed ? "image-canceled" : "image-busy"));
+            void result.catch(() => { });
+            return { result, cancel: () => { } };
+        }
+        this.#active.add(controller);
+        const deadline = setTimeout(() => controller.abort(new ImageAttachmentError("image-timeout")), IMAGE_PREPARATION_MS);
+        const result = new Promise((resolve, reject) => {
+            controller.signal.addEventListener("abort", () => reject(abortError(controller.signal)), { once: true });
+            // Concurrency: the pending marker gets a render opportunity before any acquisition starts.
+            setImmediate(() => {
+                if (controller.signal.aborted)
+                    return;
+                const acquire = read === undefined
+                    ? runImageWorker({ kind: "clipboard" }, controller.signal)
+                    : Promise.resolve().then(() => read(controller.signal));
+                void acquire.then(content => {
+                    if (controller.signal.aborted)
+                        return;
+                    if (content?.kind !== "image") {
+                        resolve(content);
+                        return;
+                    }
+                    if (Math.ceil(content.data.length / 4) * 3 > MAX_SOURCE_IMAGE_BYTES + 2)
+                        throw new ImageAttachmentError("image-source-size");
+                    this.#queue.push({ signal: controller.signal, run: async () => {
+                            try {
+                                const image = await runImageWorker({ kind: "prepare", source: content, limits }, controller.signal);
+                                resolve({ kind: "image", ...image });
+                            }
+                            catch (error) {
+                                reject(error);
+                            }
+                        } });
+                    this.#drain();
+                }).catch(reject);
+            });
+        }).finally(() => {
+            clearTimeout(deadline);
+            this.#active.delete(controller);
+            const stopped = waitForImageWorkers(controller.signal);
+            this.#stopping.add(stopped);
+            void stopped.finally(() => this.#stopping.delete(stopped));
+            const index = this.#queue.findIndex(item => item.signal === controller.signal);
+            if (index >= 0)
+                this.#queue.splice(index, 1);
+        });
+        void result.catch(() => { });
+        return { result, cancel: () => controller.abort(new ImageAttachmentError("image-canceled")) };
+    }
+    async dispose() {
+        this.#disposed = true;
+        for (const controller of this.#active)
+            controller.abort(new ImageAttachmentError("image-canceled"));
+        this.#queue.length = 0;
+        await Promise.resolve();
+        await Promise.all(this.#stopping);
+    }
+    #drain() {
+        if (this.#converting)
+            return;
+        const next = this.#queue.shift();
+        if (next === undefined)
+            return;
+        if (next.signal.aborted) {
+            this.#drain();
+            return;
+        }
+        this.#converting = true;
+        void next.run().finally(() => { this.#converting = false; this.#drain(); });
+    }
+}
+const ACTIVE_IMAGE_WORKERS = new Map();
+async function waitForImageWorkers(signal) {
+    await Promise.all([...ACTIVE_IMAGE_WORKERS].filter(([, owner]) => owner === signal)
+        .map(([worker]) => new Promise(resolve => { worker.once("exit", () => resolve()); })));
+}
+export function runImageWorker(request, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        if (ACTIVE_IMAGE_WORKERS.size >= 8) {
+            reject(new ImageAttachmentError("image-busy"));
+            return;
+        }
+        // Compatibility: production uses the emitted sibling; source tests load TypeScript through tsx.
+        const source = import.meta.url.endsWith(".ts");
+        const entry = new URL(source ? "./image-worker.ts" : "./image-worker.js", import.meta.url);
+        const worker = source
+            ? new Worker(`import('tsx/esm/api').then(({ tsImport }) => tsImport(${JSON.stringify(entry.href)}, ${JSON.stringify(import.meta.url)}))`, { eval: true, workerData: request, stdout: true, stderr: true })
+            : new Worker(entry, { workerData: request, stdout: true, stderr: true });
+        // Security: native/codec output is not trusted diagnostics and must never reach the terminal or logs.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        ACTIVE_IMAGE_WORKERS.set(worker, signal);
+        let outcome;
+        let stop;
+        const requestStop = () => {
+            if (stop !== undefined)
+                return;
+            worker.postMessage("cancel");
+            // Security: allow clipboard subprocess abort first; a busy codec cannot handle messages.
+            stop = setTimeout(() => { void worker.terminate().catch(() => { }); }, 50);
+            stop.unref();
+        };
+        const abort = () => { outcome = { error: abortError(signal) }; requestStop(); };
+        signal.addEventListener("abort", abort, { once: true });
+        worker.once("message", (message) => {
+            if (!signal.aborted)
+                outcome = message?.ok === true
+                    ? { value: message.value }
+                    : { error: new ImageAttachmentError(message?.code ?? "image-codec") };
+            requestStop();
+        });
+        worker.once("error", () => { outcome = { error: new ImageAttachmentError("image-codec") }; requestStop(); });
+        worker.once("exit", () => {
+            ACTIVE_IMAGE_WORKERS.delete(worker);
+            if (stop !== undefined)
+                clearTimeout(stop);
+            signal.removeEventListener("abort", abort);
+            // Concurrency: release the conversion slot only after the old executor has actually stopped.
+            if (outcome === undefined || outcome.error !== undefined)
+                reject(outcome?.error ?? new ImageAttachmentError("image-codec"));
+            else
+                resolve(outcome.value);
+        });
+    });
+}
+function abortError(signal) {
+    return signal.reason instanceof ImageAttachmentError ? signal.reason : new ImageAttachmentError("image-canceled");
+}

package/dist/app/session-shell/image-preparation.d.ts

@@ -0,0 +1,18 @@
+export interface ImagePreparationLimits {
+    readonly encodedBytes?: number;
+    readonly decodedBytes?: number;
+    readonly maxDimension?: number;
+}
+export interface PreparedImage {
+    readonly data: string;
+    readonly mimeType: string;
+    readonly width: number;
+    readonly height: number;
+    readonly transformed: boolean;
+}
+export declare const IMAGE_TARGET_BASE64_BYTES: number;
+export declare const IMAGE_TARGET_DECODED_BYTES: number;
+export declare function prepareImage(source: {
+    readonly data: string;
+    readonly mimeType: string;
+}, limits?: ImagePreparationLimits): Promise<PreparedImage>;

package/dist/app/session-shell/image-preparation.js

@@ -0,0 +1,126 @@
+import { isMainThread } from "node:worker_threads";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { sourceImageInfo } from "./image-source.js";
+export const IMAGE_TARGET_BASE64_BYTES = 4.5 * 1024 * 1024;
+export const IMAGE_TARGET_DECODED_BYTES = 5 * 1024 * 1024;
+export async function prepareImage(source, limits = {}) {
+    // Performance: an async signature does not move synchronous WASM work off the interactive thread.
+    if (isMainThread)
+        throw new Error("Image preparation requires a worker");
+    const canonical = canonicalizeClipboardImage(source, true);
+    if (canonical === null)
+        throw new ImageAttachmentError("image-data");
+    const bytes = Buffer.from(canonical.data, "base64");
+    const metadata = sourceImageInfo(bytes, canonical.mimeType);
+    const encodedLimit = Math.min(IMAGE_TARGET_BASE64_BYTES - 1, positive(limits.encodedBytes, Infinity));
+    const decodedLimit = Math.min(IMAGE_TARGET_DECODED_BYTES, positive(limits.decodedBytes, Infinity));
+    const maxDimension = positive(limits.maxDimension, Infinity);
+    const fits = (length) => length <= decodedLimit && 4 * Math.ceil(length / 3) <= encodedLimit;
+    if (fits(bytes.length) && Math.max(metadata.width, metadata.height) <= maxDimension) {
+        return { ...canonical, width: metadata.width, height: metadata.height, transformed: false };
+    }
+    if (metadata.conversionUnsafe)
+        throw new ImageAttachmentError("image-conversion");
+    const photon = await import("@silvia-odwyer/photon-node").catch(() => { throw new ImageAttachmentError("image-codec"); });
+    let image;
+    try {
+        image = photon.PhotonImage.new_from_byteslice(bytes);
+        if (image.get_width() !== metadata.width || image.get_height() !== metadata.height)
+            throw new ImageAttachmentError("image-data");
+        if (metadata.orientation !== 1) {
+            const raw = image.get_raw_pixels();
+            const oriented = orientPixels(raw, metadata.width, metadata.height, metadata.orientation);
+            image.free();
+            image = undefined;
+            image = new photon.PhotonImage(oriented.pixels, oriented.width, oriented.height);
+        }
+        const width = image.get_width(), height = image.get_height();
+        let scale = Math.min(1, 2000 / Math.max(width, height), maxDimension / Math.max(width, height));
+        const floor = Math.min(Math.max(width, height), 1024, maxDimension);
+        for (let level = 0; level < 4; level++, scale *= 0.75) {
+            const w = Math.max(1, Math.round(width * scale)), h = Math.max(1, Math.round(height * scale));
+            if (Math.max(w, h) < floor)
+                break;
+            const resized = photon.resize(image, w, h, photon.SamplingFilter.Lanczos3);
+            let opaque;
+            try {
+                const png = resized.get_bytes();
+                if (fits(png.length))
+                    return result(png, "image/png", w, h);
+                const pixels = resized.get_raw_pixels();
+                for (let p = 0; p < pixels.length; p += 4) {
+                    const alpha = (pixels[p + 3] ?? 255) / 255;
+                    for (let c = 0; c < 3; c++)
+                        pixels[p + c] = Math.round((pixels[p + c] ?? 0) * alpha + 255 * (1 - alpha));
+                    pixels[p + 3] = 255;
+                }
+                opaque = new photon.PhotonImage(pixels, w, h);
+                for (const quality of [85, 70, 55, 40]) {
+                    const jpeg = opaque.get_bytes_jpeg(quality);
+                    if (fits(jpeg.length))
+                        return result(jpeg, "image/jpeg", w, h);
+                }
+            }
+            finally {
+                opaque?.free();
+                resized.free();
+            }
+        }
+        throw new ImageAttachmentError("image-output");
+    }
+    catch (error) {
+        if (error instanceof ImageAttachmentError)
+            throw error;
+        throw new ImageAttachmentError("image-conversion");
+    }
+    finally {
+        image?.free();
+    }
+}
+function positive(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 1)
+        throw new ImageAttachmentError("image-output");
+    return Math.floor(value);
+}
+function result(bytes, mimeType, width, height) {
+    return { data: Buffer.from(bytes).toString("base64"), mimeType, width, height, transformed: true };
+}
+function orientPixels(pixels, width, height, orientation) {
+    const swapped = orientation >= 5;
+    const outputWidth = swapped ? height : width, outputHeight = swapped ? width : height;
+    const output = new Uint8Array(pixels.length);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            let dx = x, dy = y;
+            if (orientation === 2)
+                dx = width - 1 - x;
+            if (orientation === 3) {
+                dx = width - 1 - x;
+                dy = height - 1 - y;
+            }
+            if (orientation === 4)
+                dy = height - 1 - y;
+            if (orientation === 5) {
+                dx = y;
+                dy = x;
+            }
+            if (orientation === 6) {
+                dx = height - 1 - y;
+                dy = x;
+            }
+            if (orientation === 7) {
+                dx = height - 1 - y;
+                dy = width - 1 - x;
+            }
+            if (orientation === 8) {
+                dx = y;
+                dy = width - 1 - x;
+            }
+            const from = (y * width + x) * 4, to = (dy * outputWidth + dx) * 4;
+            output.set(pixels.subarray(from, from + 4), to);
+        }
+    return { pixels: output, width: outputWidth, height: outputHeight };
+}

package/dist/app/session-shell/image-source.d.ts

@@ -0,0 +1,13 @@
+export declare const MAX_SOURCE_IMAGE_BYTES: number;
+export declare const MAX_SOURCE_PIXELS = 40000000;
+export declare const MAX_SOURCE_DIMENSION = 32768;
+export declare const IMAGE_PREPARATION_MS = 15000;
+export interface ImageSourceInfo {
+    readonly width: number;
+    readonly height: number;
+    readonly mimeType: string;
+    readonly orientation: number;
+    readonly conversionUnsafe: boolean;
+}
+export declare function assertSourceBytes(length: number): void;
+export declare function sourceImageInfo(bytes: Uint8Array, mimeType: string): ImageSourceInfo;

package/dist/app/session-shell/image-source.js

@@ -0,0 +1,171 @@
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+export const MAX_SOURCE_IMAGE_BYTES = 20 * 1024 * 1024;
+export const MAX_SOURCE_PIXELS = 40_000_000;
+export const MAX_SOURCE_DIMENSION = 32_768;
+export const IMAGE_PREPARATION_MS = 15_000;
+export function assertSourceBytes(length) {
+    if (length > MAX_SOURCE_IMAGE_BYTES)
+        throw new ImageAttachmentError("image-source-size");
+    if (!Number.isSafeInteger(length) || length <= 0)
+        throw new ImageAttachmentError("image-data");
+}
+export function sourceImageInfo(bytes, mimeType) {
+    assertSourceBytes(bytes.length);
+    try {
+        const info = readHeader(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+        if (info.mimeType !== mimeType.toLowerCase())
+            throw new ImageAttachmentError("image-mime");
+        if (info.width <= 0 || info.height <= 0)
+            throw new ImageAttachmentError("image-data");
+        if (info.width > MAX_SOURCE_DIMENSION || info.height > MAX_SOURCE_DIMENSION || info.width * info.height > MAX_SOURCE_PIXELS) {
+            throw new ImageAttachmentError("image-pixels");
+        }
+        return info;
+    }
+    catch (error) {
+        if (error instanceof ImageAttachmentError)
+            throw error;
+        throw new ImageAttachmentError("image-data");
+    }
+}
+function readHeader(b) {
+    let orientation = 1;
+    let conversionUnsafe = false;
+    const info = (width, height, mimeType) => ({ width, height, mimeType, orientation, conversionUnsafe });
+    if (b.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+        if (b.toString("ascii", 12, 16) !== "IHDR" || b.readUInt32BE(8) !== 13)
+            throw new ImageAttachmentError("image-data");
+        for (let p = 8; p + 12 <= b.length;) {
+            const n = b.readUInt32BE(p);
+            if (p + n + 12 > b.length)
+                throw new ImageAttachmentError("image-data");
+            const type = b.toString("ascii", p + 4, p + 8);
+            if (type === "eXIf")
+                orientation = exifOrientation(b.subarray(p + 8, p + 8 + n));
+            if (type === "acTL" || type === "iCCP" || (type === "IHDR" && b[p + 16] === 16))
+                conversionUnsafe = true;
+            p += n + 12;
+        }
+        return info(b.readUInt32BE(16), b.readUInt32BE(20), "image/png");
+    }
+    if (b[0] === 255 && b[1] === 216) {
+        let width = 0, height = 0;
+        for (let p = 2; p < b.length;) {
+            if (b[p++] !== 255)
+                throw new ImageAttachmentError("image-data");
+            while (b[p] === 255)
+                p++;
+            const marker = b[p++];
+            if (marker === 218 || marker === 217)
+                break;
+            if (marker === 1 || (marker !== undefined && marker >= 208 && marker <= 215))
+                continue;
+            const n = b.readUInt16BE(p);
+            if (n < 2 || p + n > b.length)
+                throw new ImageAttachmentError("image-data");
+            if (marker === 225 && b.toString("ascii", p + 2, p + 8) === "Exif\0\0")
+                orientation = exifOrientation(b.subarray(p + 8, p + n));
+            if (marker === 226 && b.toString("ascii", p + 2, p + 13) === "ICC_PROFILE")
+                conversionUnsafe = true;
+            if (marker !== undefined && [192, 193, 194].includes(marker)) {
+                height = b.readUInt16BE(p + 3);
+                width = b.readUInt16BE(p + 5);
+                if (b[p + 7] === 4)
+                    conversionUnsafe = true;
+            }
+            p += n;
+        }
+        return info(width, height, "image/jpeg");
+    }
+    if (/^GIF8[79]a$/.test(b.toString("ascii", 0, 6))) {
+        conversionUnsafe = gifFrameCount(b) > 1;
+        return info(b.readUInt16LE(6), b.readUInt16LE(8), "image/gif");
+    }
+    if (b.toString("ascii", 0, 2) === "BM") {
+        const dib = b.readUInt32LE(14);
+        if (dib === 12)
+            return info(b.readUInt16LE(18), b.readUInt16LE(20), "image/bmp");
+        if (dib < 40)
+            throw new ImageAttachmentError("image-data");
+        return info(b.readInt32LE(18), Math.abs(b.readInt32LE(22)), "image/bmp");
+    }
+    if (b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP") {
+        const kind = b.toString("ascii", 12, 16);
+        if (kind === "VP8X") {
+            conversionUnsafe = ((b[20] ?? 0) & 0x22) !== 0;
+            for (let p = 12; p + 8 <= b.length;) {
+                const n = b.readUInt32LE(p + 4);
+                if (p + n + 8 > b.length)
+                    throw new ImageAttachmentError("image-data");
+                if (b.toString("ascii", p, p + 4) === "EXIF")
+                    orientation = exifOrientation(b.subarray(p + 8, p + 8 + n));
+                p += 8 + n + (n % 2);
+            }
+            return info(1 + b.readUIntLE(24, 3), 1 + b.readUIntLE(27, 3), "image/webp");
+        }
+        if (kind === "VP8 " && b.toString("hex", 23, 26) === "9d012a")
+            return info(b.readUInt16LE(26) & 0x3fff, b.readUInt16LE(28) & 0x3fff, "image/webp");
+        if (kind === "VP8L" && b[20] === 47) {
+            const bits = b.readUInt32LE(21);
+            return info((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1, "image/webp");
+        }
+    }
+    throw new ImageAttachmentError("image-conversion");
+}
+function gifFrameCount(b) {
+    let p = 13 + (((b[10] ?? 0) & 128) ? 3 * 2 ** (((b[10] ?? 0) & 7) + 1) : 0);
+    let frames = 0;
+    const skipBlocks = () => {
+        while (p < b.length) {
+            const length = b[p++] ?? 0;
+            if (length === 0)
+                return;
+            p += length;
+            if (p > b.length)
+                throw new ImageAttachmentError("image-data");
+        }
+        throw new ImageAttachmentError("image-data");
+    };
+    while (p < b.length) {
+        const marker = b[p++];
+        if (marker === 59)
+            return frames;
+        if (marker === 33) {
+            p++;
+            skipBlocks();
+            continue;
+        }
+        if (marker !== 44 || p + 9 > b.length)
+            throw new ImageAttachmentError("image-data");
+        frames++;
+        const packed = b[p + 8] ?? 0;
+        p += 9 + ((packed & 128) ? 3 * 2 ** ((packed & 7) + 1) : 0);
+        p++;
+        skipBlocks();
+    }
+    throw new ImageAttachmentError("image-data");
+}
+function exifOrientation(input) {
+    const b = input.toString("ascii", 0, 6) === "Exif\0\0" ? input.subarray(6) : input;
+    const little = b.toString("ascii", 0, 2) === "II";
+    if (!little && b.toString("ascii", 0, 2) !== "MM")
+        throw new ImageAttachmentError("image-conversion");
+    const u16 = (p) => little ? b.readUInt16LE(p) : b.readUInt16BE(p);
+    const u32 = (p) => little ? b.readUInt32LE(p) : b.readUInt32BE(p);
+    if (u16(2) !== 42)
+        throw new ImageAttachmentError("image-conversion");
+    const directory = u32(4);
+    const count = u16(directory);
+    if (directory + 2 + count * 12 > b.length)
+        throw new ImageAttachmentError("image-conversion");
+    for (let i = 0; i < count; i++) {
+        const p = directory + 2 + i * 12;
+        if (u16(p) !== 274)
+            continue;
+        const value = u16(p + 8);
+        if (u16(p + 2) !== 3 || u32(p + 4) !== 1 || value < 1 || value > 8)
+            throw new ImageAttachmentError("image-conversion");
+        return value;
+    }
+    return 1;
+}

package/dist/app/session-shell/image-worker.d.ts

@@ -0,0 +1,17 @@
+import { type ImagePreparationLimits } from "./image-preparation.js";
+export type ImageWorkerRequest = {
+    readonly kind: "clipboard";
+} | {
+    readonly kind: "canonicalize";
+    readonly source: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+} | {
+    readonly kind: "prepare";
+    readonly source: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+    readonly limits?: ImagePreparationLimits;
+};

package/dist/app/session-shell/image-worker.js

@@ -0,0 +1,23 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+import { prepareImage } from "./image-preparation.js";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { readSystemClipboardContent } from "./system-clipboard.js";
+const controller = new AbortController();
+parentPort?.on("message", message => { if (message === "cancel")
+    controller.abort(); });
+const request = workerData;
+try {
+    const value = request.kind === "clipboard"
+        ? await readSystemClipboardContent(controller.signal)
+        : request.kind === "canonicalize" ? canonicalizeClipboardImage(request.source, true)
+            : await prepareImage(request.source, request.limits);
+    parentPort?.postMessage({ ok: true, value });
+}
+catch (error) {
+    // Security: never forward native/codec exceptions which may contain input data.
+    parentPort?.postMessage({ ok: false, code: error instanceof ImageAttachmentError ? error.code : "image-codec" });
+}
+finally {
+    parentPort?.close();
+}

package/dist/app/session-shell/index.d.ts

@@ -0,0 +1,7 @@
+export { ClipboardDiagnosticCapture } from "./clipboard-diagnostics.js";
+export { ContextualPromptSuggestionController, samePromptSuggestionIdentity } from "./prompt-suggestion-controller.js";
+export type { ContextualPromptSuggestionControllerOptions, ContextualPromptSuggestionSurface } from "./prompt-suggestion-controller.js";
+export { OwnedUiSessionShell, OwnedUiSessionShellRoot, formatSessionResumeCommand, quoteCommandArgument } from "./session-shell.js";
+export type { OwnedUiSessionShellOptions, OwnedUiShellDiagnosticOptions, OwnedUiShellEngineOptions, OwnedUiShellHistoryOptions, OwnedUiShellPresentationOptions, OwnedUiShellSuggestionOptions, SessionResumeCommandMetadata, } from "./session-shell.js";
+export { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer } from "./stream-presentation-coalescer.js";
+export type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";

package/dist/app/session-shell/index.js

@@ -0,0 +1,4 @@
+export { ClipboardDiagnosticCapture } from "./clipboard-diagnostics.js";
+export { ContextualPromptSuggestionController, samePromptSuggestionIdentity } from "./prompt-suggestion-controller.js";
+export { OwnedUiSessionShell, OwnedUiSessionShellRoot, formatSessionResumeCommand, quoteCommandArgument } from "./session-shell.js";
+export { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer } from "./stream-presentation-coalescer.js";

package/dist/app/session-shell/paste-executor.d.ts

@@ -0,0 +1,18 @@
+import { type ChildProcess } from "node:child_process";
+import type { PiShellClipboardContent } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PreparedPaste, type PasteEvent } from "./paste-protocol.js";
+import { HelperPool } from "./helper-pool.js";
+export interface PasteExecutorJob {
+    readonly result: Promise<PreparedPaste>;
+    readonly stopped: Promise<void>;
+    cancel(): void;
+}
+export type PastePhase = (phase: PasteEvent["phase"], bytes?: number) => void;
+/** Forks one paste helper: no inherited descriptors, JSON IPC only, and its own process group on POSIX. */
+export declare function forkPasteHelper(helper?: URL): ChildProcess;
+/** Kills a paste helper and everything it spawned, then lets the parent exit without waiting for it. */
+export declare function stopPasteHelper(child: ChildProcess): void;
+/** A spare-of-one pool of paste helpers; `startPasteExecutor` takes its child and warms the next one after each paste. */
+export declare function createPasteHelperPool(helper?: URL, idleMs?: number): HelperPool;
+/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
+export declare function startPasteExecutor(content: PiShellClipboardContent | undefined, signal: AbortSignal, phase?: PastePhase, helper?: URL, pool?: HelperPool): PasteExecutorJob;