@archastro/astroshot-review 0.2.1

package/dist/terminal/image-layer.js

@@ -0,0 +1,471 @@
+/**
+ * Bridges Ink's layout tree to kitty graphics placements.
+ *
+ * Components register a source path and the DOM element that reserves cells
+ * for the picture. After every Ink frame the layer measures each element,
+ * fits the picture into that box, transmits bytes the terminal has not seen
+ * yet, and (re)places every visible image. Placements share the frame's
+ * synchronized-update block so text and pictures land together.
+ */
+import { measureElement } from "ink";
+import { fitInside } from "../images/png.js";
+import { RESTORE_CURSOR, SAVE_CURSOR, cursorTo, encodeDelete, encodePlace, encodeTransmit, } from "./kitty.js";
+export class ImageLayer {
+    entries = new Map();
+    transmitted = new Map();
+    lastPlacements = new Map();
+    nextEntryId = 1;
+    nextImageId = 1000 + Math.floor(Math.random() * 100_000);
+    tick = 0;
+    resync = true;
+    flushScheduled = false;
+    capabilities;
+    service;
+    write;
+    onReady;
+    onError;
+    onDebug;
+    herdr;
+    herdrLayers = new Map();
+    herdrGeneration = -1;
+    maxTransmitted;
+    lastSummary = "";
+    /** Row offset of the live region's first line, 1-based screen row minus 1. */
+    originRow = 0;
+    originCol = 0;
+    constructor(options) {
+        this.capabilities = options.capabilities;
+        this.service = options.service;
+        this.write = options.write;
+        this.onReady = options.onReady;
+        this.onError = options.onError;
+        this.onDebug = options.onDebug;
+        this.herdr = options.herdr;
+        this.maxTransmitted = options.maxTransmitted ?? 48;
+    }
+    get enabled() {
+        return this.capabilities.graphics === "kitty" || Boolean(this.herdr);
+    }
+    herdrLayerId(entryId) {
+        return `astro-${entryId}`;
+    }
+    register(options) {
+        const id = this.nextEntryId++;
+        const entry = {
+            id,
+            src: options.src,
+            version: options.version ?? 0,
+            z: options.z ?? 0,
+            maxUpscale: options.maxUpscale ?? 1,
+            zoom: options.zoom ?? 1,
+            panX: 0.5,
+            panY: 0.5,
+            node: null,
+            ready: null,
+            requestedKey: null,
+            failed: null,
+            frame: null,
+            frameData: null,
+            kind: "file",
+        };
+        this.entries.set(id, entry);
+        return {
+            id,
+            setNode: (node) => {
+                entry.node = node;
+            },
+            setSource: (src, version = 0) => {
+                if (entry.src === src && entry.version === version)
+                    return;
+                entry.src = src;
+                entry.version = version;
+                entry.ready = null;
+                entry.requestedKey = null;
+                entry.failed = null;
+                this.scheduleFlush();
+            },
+            setView: (view) => {
+                let changed = false;
+                if (view.zoom !== undefined && view.zoom !== entry.zoom) {
+                    entry.zoom = view.zoom;
+                    changed = true;
+                }
+                if (view.panX !== undefined && view.panX !== entry.panX) {
+                    entry.panX = view.panX;
+                    changed = true;
+                }
+                if (view.panY !== undefined && view.panY !== entry.panY) {
+                    entry.panY = view.panY;
+                    changed = true;
+                }
+                if (view.maxUpscale !== undefined && view.maxUpscale !== entry.maxUpscale) {
+                    entry.maxUpscale = view.maxUpscale;
+                    changed = true;
+                }
+                if (changed)
+                    this.scheduleFlush();
+            },
+            unregister: () => {
+                this.entries.delete(id);
+                if (this.herdr) {
+                    this.herdr.clear(this.herdrLayerId(id));
+                    this.herdrLayers.delete(id);
+                }
+                this.scheduleFlush();
+            },
+        };
+    }
+    registerFrames(options = {}) {
+        const id = this.nextEntryId++;
+        const entry = {
+            id,
+            src: null,
+            version: 0,
+            z: options.z ?? 1,
+            maxUpscale: 1,
+            zoom: 1,
+            panX: 0.5,
+            panY: 0.5,
+            node: null,
+            ready: null,
+            requestedKey: null,
+            failed: null,
+            frame: null,
+            frameData: null,
+            kind: "frames",
+        };
+        this.entries.set(id, entry);
+        const dropFrame = () => {
+            if (!entry.frame)
+                return "";
+            const output = encodeDelete({ kind: "image", id: entry.frame.imageId });
+            entry.frame = null;
+            return output;
+        };
+        return {
+            id,
+            setNode: (node) => {
+                entry.node = node;
+            },
+            pushFrame: (frame) => {
+                if (!this.enabled)
+                    return;
+                const imageId = this.nextImageId++;
+                entry.frame = { imageId, width: frame.width, height: frame.height };
+                entry.frameData = frame.png;
+                if (this.herdr) {
+                    const placement = this.placementFor(entry);
+                    if (placement) {
+                        this.herdr.set(this.herdrLayerId(entry.id), frame.png, frame.width, frame.height, placement);
+                        this.herdrLayers.set(entry.id, `frame-${imageId}`);
+                    }
+                    return;
+                }
+                const previous = { imageId: entry.frame.imageId };
+                let output = encodeTransmit({ id: imageId, format: 100, data: frame.png });
+                const placement = this.placementFor(entry);
+                if (placement) {
+                    output += SAVE_CURSOR + this.placeCommand(placement) + RESTORE_CURSOR;
+                    this.lastPlacements.set(entry.id, placement);
+                }
+                void previous;
+                this.write(`\x1b[?2026h${output}\x1b[?2026l`);
+            },
+            clearFrame: () => {
+                entry.frame = null;
+                entry.frameData = null;
+                if (this.herdr) {
+                    this.herdr.clear(this.herdrLayerId(entry.id));
+                    this.herdrLayers.delete(entry.id);
+                    return;
+                }
+                const output = dropFrame();
+                this.lastPlacements.delete(entry.id);
+                if (output)
+                    this.write(output);
+            },
+            unregister: () => {
+                entry.frame = null;
+                entry.frameData = null;
+                if (this.herdr) {
+                    this.herdr.clear(this.herdrLayerId(entry.id));
+                    this.herdrLayers.delete(entry.id);
+                    this.entries.delete(id);
+                    return;
+                }
+                const output = dropFrame();
+                this.entries.delete(id);
+                this.lastPlacements.delete(entry.id);
+                if (output)
+                    this.write(output);
+            },
+        };
+    }
+    /** Where a frame entry's current picture lands, given the live layout. */
+    placementFor(entry) {
+        if (!entry.node || !entry.frame)
+            return null;
+        const box = measureElement(entry.node);
+        if (box.width <= 0 || box.height <= 0)
+            return null;
+        const cellWidth = this.capabilities.cellWidth;
+        const cellHeight = this.capabilities.cellHeight;
+        const targetPx = { width: box.width * cellWidth, height: box.height * cellHeight };
+        const fitted = fitInside({ width: entry.frame.width, height: entry.frame.height }, targetPx);
+        const cols = Math.min(box.width, Math.max(1, Math.round(fitted.width / cellWidth)));
+        const rows = Math.min(box.height, Math.max(1, Math.round(fitted.height / cellHeight)));
+        return {
+            placementId: entry.id,
+            imageId: entry.frame.imageId,
+            col: box.x + Math.floor((box.width - cols) / 2),
+            row: box.y + Math.floor((box.height - rows) / 2),
+            cols,
+            rows,
+            z: entry.z,
+        };
+    }
+    placeCommand(placement) {
+        return (cursorTo(placement.row + 1 + this.originRow, placement.col + 1 + this.originCol) +
+            encodePlace({
+                id: placement.imageId,
+                placementId: placement.placementId,
+                cols: placement.cols,
+                rows: placement.rows,
+                z: placement.z,
+            }));
+    }
+    /** Prepared image for an entry, if any (lets components show dimensions). */
+    prepared(id) {
+        return this.entries.get(id)?.ready ?? null;
+    }
+    failure(id) {
+        return this.entries.get(id)?.failed ?? null;
+    }
+    /** After a resize or screen clear, every placement must be re-sent. */
+    invalidate() {
+        this.resync = true;
+        // Force herdr layers to be re-set at their new positions.
+        this.herdrLayers.clear();
+    }
+    /**
+     * Reconcile the herdr layers with the current placement set: (re)place any
+     * image whose bytes or box changed, and clear layers no longer shown.
+     */
+    syncHerdr(placements, readyByEntry) {
+        const sink = this.herdr;
+        if (!sink)
+            return;
+        // A dropped-and-restored connection loses server-side layers; re-send all.
+        if (sink.generation !== this.herdrGeneration) {
+            this.herdrGeneration = sink.generation;
+            this.herdrLayers.clear();
+        }
+        for (const [entryId, placement] of placements) {
+            const ready = readyByEntry.get(entryId);
+            if (!ready)
+                continue; // frame entries place themselves in pushFrame
+            const signature = `${ready.key}|${placement.col},${placement.row},${placement.cols},${placement.rows},${placement.z}`;
+            if (this.herdrLayers.get(entryId) === signature)
+                continue;
+            sink.set(this.herdrLayerId(entryId), ready.data, ready.width, ready.height, placement);
+            this.herdrLayers.set(entryId, signature);
+        }
+        for (const entryId of [...this.herdrLayers.keys()]) {
+            const entry = this.entries.get(entryId);
+            // Keep active file placements and live frame entries; clear the rest.
+            if (placements.has(entryId))
+                continue;
+            if (entry?.kind === "frames" && entry.frame)
+                continue;
+            sink.clear(this.herdrLayerId(entryId));
+            this.herdrLayers.delete(entryId);
+        }
+    }
+    /** Escape sequences that bring the terminal in line with the current layout. */
+    render() {
+        if (!this.enabled)
+            return "";
+        this.tick += 1;
+        const placements = new Map();
+        const readyByEntry = new Map();
+        let output = "";
+        const cellWidth = this.capabilities.cellWidth;
+        const cellHeight = this.capabilities.cellHeight;
+        for (const entry of this.entries.values()) {
+            if (entry.kind === "frames") {
+                // Frame entries place themselves in pushFrame; on herdr they re-place
+                // there too. Only the kitty escape path needs them re-emitted here.
+                if (!this.herdr) {
+                    const placement = this.placementFor(entry);
+                    if (placement)
+                        placements.set(entry.id, placement);
+                }
+                continue;
+            }
+            if (!entry.src || !entry.node)
+                continue;
+            const box = measureElement(entry.node);
+            if (box.width <= 0 || box.height <= 0)
+                continue;
+            const boxPx = { width: box.width * cellWidth, height: box.height * cellHeight };
+            // Prepare above the cell box so the compositor only ever downscales
+            // (downscaling stays sharp; upscaling blurs). herdr may render the box at
+            // more physical pixels than its reported cell size implies, so oversample.
+            const supersample = this.herdr ? 2 : 1;
+            const targetPx = { width: boxPx.width * supersample, height: boxPx.height * supersample };
+            // Zoom > 1 shows a centered sub-rectangle of the source (a real crop, so
+            // it magnifies instead of squishing); pan slides that rectangle. The
+            // on-screen footprint stays fixed — only the visible region changes.
+            let crop;
+            if (entry.zoom > 1 && entry.ready) {
+                const sourceW = entry.ready.sourceWidth;
+                const sourceH = entry.ready.sourceHeight;
+                const cropW = sourceW / entry.zoom;
+                const cropH = sourceH / entry.zoom;
+                const centerX = Math.max(cropW / 2, Math.min(sourceW - cropW / 2, entry.panX * sourceW));
+                const centerY = Math.max(cropH / 2, Math.min(sourceH - cropH / 2, entry.panY * sourceH));
+                crop = { x: centerX - cropW / 2, y: centerY - cropH / 2, width: cropW, height: cropH };
+            }
+            const cropKey = crop
+                ? `|z${entry.zoom.toFixed(2)}|${Math.round(crop.x)},${Math.round(crop.y)},${Math.round(crop.width)},${Math.round(crop.height)}`
+                : "";
+            const requestKey = `${entry.src}|${entry.version}|${targetPx.width}x${targetPx.height}${cropKey}`;
+            if (entry.requestedKey !== requestKey) {
+                entry.requestedKey = requestKey;
+                entry.failed = null;
+                void this.service.prepare(entry.src, targetPx, "png", crop).then((prepared) => {
+                    if (entry.requestedKey !== requestKey)
+                        return;
+                    entry.ready = prepared;
+                    this.scheduleFlush();
+                    this.onReady?.();
+                }, (error) => {
+                    if (entry.requestedKey !== requestKey)
+                        return;
+                    entry.failed = error instanceof Error ? error.message : String(error);
+                    this.onError?.(entry.src ?? "", error instanceof Error ? error : new Error(String(error)));
+                    this.onReady?.();
+                });
+            }
+            const ready = entry.ready;
+            if (!ready)
+                continue;
+            readyByEntry.set(entry.id, ready);
+            // On-screen footprint from the FULL image aspect (constant across zoom, so
+            // zooming magnifies in place without moving the picture). Fits the box,
+            // upscaling small sources up to `maxUpscale`× to fill.
+            const fullWidth = ready.sourceWidth;
+            const fullHeight = ready.sourceHeight;
+            const containScale = Math.min(boxPx.width / fullWidth, boxPx.height / fullHeight);
+            const scale = Math.min(containScale, Math.max(1, entry.maxUpscale));
+            const cols = Math.min(box.width, Math.max(1, Math.round((fullWidth * scale) / cellWidth)));
+            const rows = Math.min(box.height, Math.max(1, Math.round((fullHeight * scale) / cellHeight)));
+            const col = box.x + Math.floor((box.width - cols) / 2);
+            const row = box.y + Math.floor((box.height - rows) / 2);
+            let imageId = 0;
+            if (!this.herdr) {
+                let image = this.transmitted.get(ready.key);
+                if (!image) {
+                    image = { id: this.nextImageId++, key: ready.key, lastUsed: this.tick };
+                    this.transmitted.set(ready.key, image);
+                    output += encodeTransmit({
+                        id: image.id,
+                        format: 100,
+                        data: ready.data,
+                        filePath: this.capabilities.fileMedium && ready.isOriginal ? ready.path : undefined,
+                    });
+                }
+                image.lastUsed = this.tick;
+                imageId = image.id;
+            }
+            placements.set(entry.id, { placementId: entry.id, imageId, col, row, cols, rows, z: entry.z });
+        }
+        // herdr composits images on named layers over the pane's text; drive its
+        // socket API instead of writing Kitty escapes the multiplexer would drop.
+        if (this.herdr) {
+            this.syncHerdr(placements, readyByEntry);
+            this.lastPlacements = placements;
+            if (this.onDebug) {
+                const summary = `herdr layers=${this.herdrLayers.size} placed=${placements.size}`;
+                if (summary !== this.lastSummary) {
+                    this.lastSummary = summary;
+                    this.onDebug(summary);
+                }
+            }
+            return "";
+        }
+        if (this.resync) {
+            output += encodeDelete({ kind: "all-placements" });
+        }
+        else {
+            for (const [placementId, previous] of this.lastPlacements) {
+                if (!placements.has(placementId)) {
+                    output += encodeDelete({ kind: "placement", id: previous.imageId, placementId });
+                }
+            }
+        }
+        if (placements.size > 0) {
+            output += SAVE_CURSOR;
+            for (const placement of placements.values()) {
+                output += this.placeCommand(placement);
+            }
+            output += RESTORE_CURSOR;
+        }
+        output += this.evictTransmitted(placements);
+        this.lastPlacements = placements;
+        this.resync = false;
+        if (this.onDebug) {
+            const summary = `entries=${this.entries.size} placed=${placements.size} transmitted=${this.transmitted.size} bytes=${output.length}`;
+            if (summary !== this.lastSummary) {
+                this.lastSummary = summary;
+                this.onDebug(summary);
+            }
+        }
+        return output;
+    }
+    evictTransmitted(active) {
+        if (this.transmitted.size <= this.maxTransmitted)
+            return "";
+        const inUse = new Set([...active.values()].map((placement) => placement.imageId));
+        const candidates = [...this.transmitted.values()]
+            .filter((image) => !inUse.has(image.id))
+            .sort((a, b) => a.lastUsed - b.lastUsed);
+        let output = "";
+        while (this.transmitted.size > this.maxTransmitted && candidates.length > 0) {
+            const image = candidates.shift();
+            this.transmitted.delete(image.key);
+            output += encodeDelete({ kind: "image", id: image.id });
+        }
+        return output;
+    }
+    /** Write placements now, outside an Ink frame. Safe for the cursor. */
+    flushNow() {
+        this.flushScheduled = false;
+        if (!this.enabled)
+            return;
+        const output = this.render();
+        if (output)
+            this.write(`\x1b[?2026h${output}\x1b[?2026l`);
+    }
+    scheduleFlush() {
+        if (this.flushScheduled || !this.enabled)
+            return;
+        this.flushScheduled = true;
+        setImmediate(() => {
+            if (this.flushScheduled)
+                this.flushNow();
+        });
+    }
+    /** Remove every placement and free image data in the terminal. */
+    clear() {
+        this.lastPlacements = new Map();
+        this.transmitted.clear();
+        this.resync = true;
+        if (this.herdr) {
+            this.herdr.clearAll();
+            this.herdrLayers.clear();
+            return "";
+        }
+        return this.enabled ? encodeDelete({ kind: "all" }) : "";
+    }
+}

package/dist/terminal/kitty.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Kitty terminal graphics protocol encoder.
+ *
+ * Only the subset the review tray needs: transmit PNG or raw RGB data by id,
+ * place a transmitted image over a cell box, and delete placements or image
+ * data. Every command is emitted quietly (q=2) so the terminal never answers
+ * on stdin while Ink owns it.
+ *
+ * Spec: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+ */
+export declare const APC = "\u001B_G";
+export declare const ST = "\u001B\\";
+/** Payload chunk size; the protocol caps chunks at 4096 bytes. */
+export declare const CHUNK_SIZE = 4096;
+export type ImageFormat = 100 | 24 | 32;
+export interface TransmitRequest {
+    id: number;
+    /** 100 = PNG bytes, 24 = RGB, 32 = RGBA. */
+    format: ImageFormat;
+    data: Buffer;
+    /** Required for raw formats. */
+    width?: number;
+    height?: number;
+    /** Raw payload is zlib-compressed (o=z). */
+    compressed?: boolean;
+    /**
+     * When set the payload is a base64 file path the terminal reads itself
+     * (t=f). Only valid when the terminal runs on this machine.
+     */
+    filePath?: string;
+}
+export interface PlaceRequest {
+    id: number;
+    placementId: number;
+    cols: number;
+    rows: number;
+    /** Stacking order; images with z >= 0 draw above text. */
+    z?: number;
+}
+export type DeleteRequest = {
+    kind: "placement";
+    id: number;
+    placementId: number;
+} | {
+    kind: "image";
+    id: number;
+} | {
+    kind: "all-placements";
+} | {
+    kind: "all";
+};
+export declare function chunkPayload(base64: string, size?: number): string[];
+/** Transmit image data without displaying it (a=t). */
+export declare function encodeTransmit(request: TransmitRequest): string;
+/**
+ * Display a transmitted image over a c×r cell box at the cursor (a=p). C=1
+ * keeps the cursor where it was so Ink's own cursor bookkeeping stays valid.
+ * A placement with the same (i, p) pair replaces the previous one.
+ */
+export declare function encodePlace(request: PlaceRequest): string;
+export declare function encodeDelete(request: DeleteRequest): string;
+/** The 1×1 RGB query kitty documents for capability detection. */
+export declare function encodeQuery(id: number): string;
+export declare function encodeFileQuery(id: number, filePath: string): string;
+/** Move the cursor to a 1-based row/column (CUP). */
+export declare function cursorTo(row: number, col: number): string;
+export declare const SAVE_CURSOR = "\u001B7";
+export declare const RESTORE_CURSOR = "\u001B8";
+export interface ParsedGraphicsCommand {
+    keys: Record<string, string>;
+    payload: string;
+}
+/** Parse one `ESC _ G <keys> ; <payload> ESC \` command body. */
+export declare function parseGraphicsCommand(body: string): ParsedGraphicsCommand;

package/dist/terminal/kitty.js

@@ -0,0 +1,112 @@
+/**
+ * Kitty terminal graphics protocol encoder.
+ *
+ * Only the subset the review tray needs: transmit PNG or raw RGB data by id,
+ * place a transmitted image over a cell box, and delete placements or image
+ * data. Every command is emitted quietly (q=2) so the terminal never answers
+ * on stdin while Ink owns it.
+ *
+ * Spec: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+ */
+export const APC = "\x1b_G";
+export const ST = "\x1b\\";
+/** Payload chunk size; the protocol caps chunks at 4096 bytes. */
+export const CHUNK_SIZE = 4096;
+function control(pairs) {
+    return Object.entries(pairs)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(",");
+}
+export function chunkPayload(base64, size = CHUNK_SIZE) {
+    if (base64.length === 0)
+        return [""];
+    const chunks = [];
+    for (let offset = 0; offset < base64.length; offset += size) {
+        chunks.push(base64.slice(offset, offset + size));
+    }
+    return chunks;
+}
+/** Transmit image data without displaying it (a=t). */
+export function encodeTransmit(request) {
+    const base = {
+        a: "t",
+        i: request.id,
+        f: request.format,
+        q: 2,
+        s: request.format === 100 ? undefined : request.width,
+        v: request.format === 100 ? undefined : request.height,
+        o: request.compressed ? "z" : undefined,
+    };
+    if (request.filePath) {
+        const payload = Buffer.from(request.filePath, "utf8").toString("base64");
+        return `${APC}${control({ ...base, t: "f" })};${payload}${ST}`;
+    }
+    const chunks = chunkPayload(request.data.toString("base64"));
+    return chunks
+        .map((chunk, index) => {
+        const more = index < chunks.length - 1 ? 1 : 0;
+        const keys = index === 0 ? control({ ...base, t: "d", m: more }) : `m=${more}`;
+        return `${APC}${keys};${chunk}${ST}`;
+    })
+        .join("");
+}
+/**
+ * Display a transmitted image over a c×r cell box at the cursor (a=p). C=1
+ * keeps the cursor where it was so Ink's own cursor bookkeeping stays valid.
+ * A placement with the same (i, p) pair replaces the previous one.
+ */
+export function encodePlace(request) {
+    return `${APC}${control({
+        a: "p",
+        i: request.id,
+        p: request.placementId,
+        c: request.cols,
+        r: request.rows,
+        z: request.z ?? 0,
+        C: 1,
+        q: 2,
+    })}${ST}`;
+}
+export function encodeDelete(request) {
+    switch (request.kind) {
+        case "placement":
+            return `${APC}${control({ a: "d", d: "i", i: request.id, p: request.placementId, q: 2 })}${ST}`;
+        case "image":
+            return `${APC}${control({ a: "d", d: "I", i: request.id, q: 2 })}${ST}`;
+        case "all-placements":
+            return `${APC}${control({ a: "d", d: "a", q: 2 })}${ST}`;
+        case "all":
+            return `${APC}${control({ a: "d", d: "A", q: 2 })}${ST}`;
+    }
+}
+/** The 1×1 RGB query kitty documents for capability detection. */
+export function encodeQuery(id) {
+    return `${APC}${control({ i: id, s: 1, v: 1, a: "q", t: "d", f: 24 })};AAAA${ST}`;
+}
+export function encodeFileQuery(id, filePath) {
+    const payload = Buffer.from(filePath, "utf8").toString("base64");
+    return `${APC}${control({ i: id, a: "q", t: "f", f: 100 })};${payload}${ST}`;
+}
+/** Move the cursor to a 1-based row/column (CUP). */
+export function cursorTo(row, col) {
+    return `\x1b[${row};${col}H`;
+}
+export const SAVE_CURSOR = "\x1b7";
+export const RESTORE_CURSOR = "\x1b8";
+/** Parse one `ESC _ G <keys> ; <payload> ESC \` command body. */
+export function parseGraphicsCommand(body) {
+    const separator = body.indexOf(";");
+    const keyText = separator === -1 ? body : body.slice(0, separator);
+    const payload = separator === -1 ? "" : body.slice(separator + 1);
+    const keys = {};
+    for (const pair of keyText.split(",")) {
+        if (!pair)
+            continue;
+        const equals = pair.indexOf("=");
+        if (equals === -1)
+            continue;
+        keys[pair.slice(0, equals)] = pair.slice(equals + 1);
+    }
+    return { keys, payload };
+}