astroshot 0.2.1 → 0.2.2

package/node_modules/@archastro/astroshot-review/dist/terminal/herdr.js

@@ -0,0 +1,327 @@
+/**
+ * herdr pane-graphics transport.
+ *
+ * herdr (an agent terminal multiplexer) emulates the terminal itself and does
+ * not forward a program's raw Kitty escapes. Instead it exposes a unix-socket
+ * JSON API — `pane.graphics.set` / `pane.graphics.clear` place and remove
+ * images on named layers composited over the pane's text. This module speaks
+ * that API so the review tray shows pixel-perfect images inside herdr.
+ *
+ * Enabling it needs `[experimental] kitty_graphics = true` in herdr's
+ * config.toml AND a client reattach: herdr 0.8.2 latches the client's graphics
+ * setting at startup, so a client started with it off reports the host cell
+ * size as unavailable until it is detached and reattached once.
+ *
+ * Wire format: newline-delimited JSON over the socket named by
+ * HERDR_SOCKET_PATH, targeting HERDR_PANE_ID.
+ */
+import { createConnection } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+export function herdrAddress(env = process.env) {
+    if (env.HERDR_ENV !== "1")
+        return null;
+    if (!env.HERDR_SOCKET_PATH || !env.HERDR_PANE_ID)
+        return null;
+    return { socket: env.HERDR_SOCKET_PATH, pane: env.HERDR_PANE_ID };
+}
+/** A short-lived request/response over the socket. */
+function request(socket, method, params) {
+    return new Promise((resolve, reject) => {
+        const client = createConnection(socket);
+        let text = "";
+        const fail = (error) => {
+            client.removeAllListeners();
+            client.destroy();
+            reject(error);
+        };
+        client.on("connect", () => client.write(JSON.stringify({ id: "astroshot-review", method, params }) + "\n"));
+        client.on("data", (chunk) => {
+            text += chunk.toString();
+            const end = text.indexOf("\n");
+            if (end < 0) {
+                if (text.length > 1024 * 1024)
+                    fail(new Error("herdr response too large"));
+                return;
+            }
+            try {
+                const reply = JSON.parse(text.slice(0, end));
+                client.removeAllListeners();
+                client.destroy();
+                resolve(reply);
+            }
+            catch {
+                fail(new Error("invalid herdr response"));
+            }
+        });
+        client.on("error", fail);
+        client.setTimeout(2500, () => fail(new Error("herdr request timed out")));
+    });
+}
+// 1x1 transparent PNG, for probing whether pane.graphics.set is accepted.
+const PROBE_PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64");
+/**
+ * Confirm herdr accepts a `pane.graphics.stream` layer. A missing ack is
+ * treated as success — the open reply may be silent — so only an explicit
+ * error reply rejects it. The probe stream is closed immediately, which makes
+ * herdr drop its layer.
+ */
+export async function probeHerdrSet(address) {
+    return new Promise((resolve) => {
+        const client = createConnection(address.socket);
+        let text = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            client.destroy();
+            resolve(result);
+        };
+        client.on("connect", () => client.write(JSON.stringify({ id: "astroshot-review", method: "pane.graphics.stream", params: { pane_id: address.pane, layer_id: "astroshot-review-probe", z_index: -1 } }) + "\n"));
+        client.on("data", (chunk) => {
+            text += chunk.toString();
+            const end = text.indexOf("\n");
+            if (end < 0)
+                return;
+            try {
+                const reply = JSON.parse(text.slice(0, end));
+                finish(reply.error ? { ok: false, reason: reasonFor(reply) } : { ok: true });
+            }
+            catch {
+                finish({ ok: true });
+            }
+        });
+        client.on("error", () => finish({ ok: true }));
+        setTimeout(() => finish({ ok: true }), 600);
+    });
+}
+function reasonFor(reply) {
+    if (reply.error?.code === "feature_disabled") {
+        return "herdr image rendering is off — set [experimental] kitty_graphics = true in ~/.config/herdr/config.toml, run `herdr server reload-config`, then reattach the herdr client";
+    }
+    if (reply.error?.code === "cell_size_unavailable") {
+        return "herdr hasn't reported pixel size — detach and reattach the herdr client once (its graphics setting latches at startup)";
+    }
+    if (reply.error)
+        return `herdr graphics unavailable (${reply.error.code})`;
+    return "herdr returned no pixel dimensions for this pane";
+}
+/** Poll `pane.graphics.info` until herdr reports the cell size, or give up. */
+export async function discoverHerdr(address, options = {}) {
+    const deadline = Date.now() + (options.timeoutMs ?? 5000);
+    let announced = false;
+    for (;;) {
+        let reply;
+        try {
+            reply = await request(address.socket, "pane.graphics.info", { pane_id: address.pane });
+        }
+        catch (error) {
+            return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+        if (reply.error?.code === "cell_size_unavailable" && Date.now() < deadline) {
+            if (!announced) {
+                announced = true;
+                options.onWaiting?.();
+            }
+            await delay(Math.min(options.retryMs ?? 150, Math.max(1, deadline - Date.now())));
+            continue;
+        }
+        if (reply.error || !reply.result?.cell_width_px || !reply.result?.cell_height_px) {
+            return { ok: false, reason: reasonFor(reply) };
+        }
+        return {
+            ok: true,
+            cellWidth: reply.result.cell_width_px,
+            cellHeight: reply.result.cell_height_px,
+            maxLayers: reply.result.max_layers_per_pane || 16,
+        };
+    }
+}
+/** Extract PNG pixel dimensions from the IHDR chunk. */
+function pngSize(png) {
+    return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+}
+/**
+ * Places images on herdr via one `pane.graphics.stream` connection PER layer.
+ * herdr removes a stream's layer the moment its socket closes, so closing a
+ * layer's connection — or the whole process dying — cleans up automatically,
+ * with no persistent server-side state to leak (the trap of pane.graphics.set).
+ */
+export class HerdrSink {
+    address;
+    onError;
+    layers = new Map();
+    /** Every socket opened and not yet closed, whether or not its layer is still mapped. */
+    connections = new Set();
+    disposed = false;
+    generationCount = 0;
+    constructor(address, onError) {
+        this.address = address;
+        this.onError = onError;
+    }
+    /** Bumps when a layer stream drops unexpectedly, so callers re-send. */
+    get generation() {
+        return this.generationCount;
+    }
+    set(layerId, png, _imageWidth, _imageHeight, placement) {
+        if (this.disposed)
+            return;
+        let layer = this.layers.get(layerId);
+        if (!layer) {
+            layer = { socket: null, opening: false, ready: false, z: placement.z, pending: null, draining: false };
+            this.layers.set(layerId, layer);
+        }
+        layer.pending = { png, placement };
+        if (layer.ready && !layer.draining) {
+            this.flush(layerId, layer);
+        }
+        else if (!layer.opening && !layer.socket) {
+            this.open(layerId, layer);
+        }
+    }
+    clear(layerId) {
+        const layer = this.layers.get(layerId);
+        if (!layer)
+            return;
+        this.layers.delete(layerId);
+        layer.pending = null;
+        layer.opening = false;
+        layer.ready = false;
+        const socket = layer.socket;
+        layer.socket = null;
+        // Closing the connection makes herdr drop this layer. This must happen
+        // even mid-handshake: a connection that outlives its layer keeps a ghost
+        // layer in herdr and keeps this process alive after the tray quits.
+        if (socket)
+            this.close(socket);
+    }
+    close(socket) {
+        this.connections.delete(socket);
+        try {
+            socket.destroy();
+        }
+        catch {
+            // already gone
+        }
+    }
+    clearAll() {
+        for (const layerId of [...this.layers.keys()])
+            this.clear(layerId);
+    }
+    open(layerId, layer) {
+        const client = createConnection(this.address.socket);
+        // The layer owns its socket from the first moment, not from the open ack:
+        // clear() and dispose() close whatever is here, handshake or not.
+        layer.opening = true;
+        layer.ready = false;
+        layer.socket = client;
+        this.connections.add(client);
+        let text = "";
+        let opened = false;
+        // Still the mapped layer's current socket, on a live sink.
+        const current = () => !this.disposed && this.layers.get(layerId) === layer && layer.socket === client;
+        const markOpen = () => {
+            if (opened)
+                return;
+            opened = true;
+            if (!current()) {
+                this.close(client);
+                return;
+            }
+            layer.opening = false;
+            layer.ready = true;
+            this.flush(layerId, layer);
+        };
+        client.on("connect", () => {
+            client.write(JSON.stringify({ id: "astroshot-review", method: "pane.graphics.stream", params: { pane_id: this.address.pane, layer_id: layerId, z_index: layer.z } }) + "\n");
+        });
+        client.on("data", (chunk) => {
+            text += chunk.toString();
+            let end;
+            while ((end = text.indexOf("\n")) >= 0) {
+                const line = text.slice(0, end);
+                text = text.slice(end + 1);
+                let reply;
+                try {
+                    reply = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (reply.error) {
+                    this.onError(new Error(`herdr stream ${layerId}: ${reply.error.code}`));
+                    continue;
+                }
+                markOpen();
+            }
+        });
+        const drop = (reason) => {
+            clearTimeout(grace);
+            this.connections.delete(client);
+            // A socket that clear() already detached says nothing about the layer.
+            if (layer.socket !== client)
+                return;
+            layer.socket = null;
+            layer.ready = false;
+            layer.opening = false;
+            // Unexpected drop (not from clear/dispose): let callers re-send everything.
+            if (this.layers.get(layerId) === layer && !this.disposed) {
+                this.generationCount += 1;
+                this.onError(new Error(`herdr stream ${layerId} ${reason}`));
+            }
+        };
+        client.on("error", () => drop("error"));
+        client.on("close", () => drop("closed"));
+        // If the open reply never comes, assume success after a short grace so a
+        // silent-ack build still renders.
+        const grace = setTimeout(markOpen, 400);
+    }
+    flush(layerId, layer) {
+        const socket = layer.socket;
+        const frame = layer.pending;
+        if (!socket || !frame)
+            return;
+        layer.pending = null;
+        const size = pngSize(frame.png);
+        const header = {
+            format: "png",
+            image_width: size.width,
+            image_height: size.height,
+            data_length: frame.png.length,
+            placement: {
+                viewport_col: frame.placement.col,
+                viewport_row: frame.placement.row,
+                grid_cols: frame.placement.cols,
+                grid_rows: frame.placement.rows,
+            },
+        };
+        let ok = false;
+        try {
+            ok = socket.write(Buffer.concat([Buffer.from(JSON.stringify(header) + "\n"), frame.png]));
+        }
+        catch (error) {
+            this.onError(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        if (!ok) {
+            // Backpressure: wait for drain, then send only the newest pending frame.
+            layer.draining = true;
+            socket.once("drain", () => {
+                layer.draining = false;
+                if (layer.pending)
+                    this.flush(layerId, layer);
+            });
+        }
+        else if (layer.pending) {
+            this.flush(layerId, layer);
+        }
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const socket of [...this.connections])
+            this.close(socket);
+        this.layers.clear();
+    }
+}

package/node_modules/@archastro/astroshot-review/dist/terminal/image-layer.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 { type DOMElement } from "ink";
+import type { ImageService, PreparedImage } from "../images/service.js";
+import type { HerdrSink } from "./herdr.js";
+import type { TerminalCapabilities } from "./probe.js";
+export interface ImageHandle {
+    readonly id: number;
+    setNode(node: DOMElement | null): void;
+    /** `version` (for example the file's mtime) forces a fresh decode when the bytes change. */
+    setSource(src: string | null, version?: number): void;
+    /** Update the view: zoom (1 = whole image), pan center in [0,1], and the fill cap. */
+    setView(view: {
+        zoom?: number;
+        panX?: number;
+        panY?: number;
+        maxUpscale?: number;
+    }): void;
+    unregister(): void;
+}
+/** A picture that changes every few milliseconds (movie playback). */
+export interface FrameHandle {
+    readonly id: number;
+    setNode(node: DOMElement | null): void;
+    /** Transmit and show a new PNG frame immediately. */
+    pushFrame(frame: {
+        png: Buffer;
+        width: number;
+        height: number;
+    }): void;
+    /** Drop the current frame (the poster shows through again). */
+    clearFrame(): void;
+    unregister(): void;
+}
+export interface Placement {
+    placementId: number;
+    imageId: number;
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    z: number;
+}
+export interface ImageLayerOptions {
+    capabilities: TerminalCapabilities;
+    service: ImageService;
+    /** Writes straight to the terminal, bypassing Ink (used for async readiness). */
+    write: (data: string) => void;
+    /** Called when an image finished preparing and the screen should refresh. */
+    onReady?: () => void;
+    onError?: (src: string, error: Error) => void;
+    /** Diagnostics sink (enabled by ASTROSHOT_REVIEW_DEBUG). */
+    onDebug?: (message: string) => void;
+    /** When present, images are placed through herdr's socket API instead of Kitty escapes. */
+    herdr?: HerdrSink;
+    maxTransmitted?: number;
+}
+export declare class ImageLayer {
+    private readonly entries;
+    private readonly transmitted;
+    private lastPlacements;
+    private nextEntryId;
+    private nextImageId;
+    private tick;
+    private resync;
+    private flushScheduled;
+    private readonly capabilities;
+    private readonly service;
+    private readonly write;
+    private readonly onReady?;
+    private readonly onError?;
+    private readonly onDebug?;
+    private readonly herdr?;
+    private readonly herdrLayers;
+    private herdrGeneration;
+    private readonly maxTransmitted;
+    private lastSummary;
+    /** Row offset of the live region's first line, 1-based screen row minus 1. */
+    originRow: number;
+    originCol: number;
+    constructor(options: ImageLayerOptions);
+    get enabled(): boolean;
+    private herdrLayerId;
+    register(options: {
+        src: string | null;
+        version?: number;
+        z?: number;
+        maxUpscale?: number;
+        zoom?: number;
+    }): ImageHandle;
+    registerFrames(options?: {
+        z?: number;
+    }): FrameHandle;
+    /** Where a frame entry's current picture lands, given the live layout. */
+    private placementFor;
+    private placeCommand;
+    /** Prepared image for an entry, if any (lets components show dimensions). */
+    prepared(id: number): PreparedImage | null;
+    failure(id: number): string | null;
+    /** After a resize or screen clear, every placement must be re-sent. */
+    invalidate(): void;
+    /**
+     * Reconcile the herdr layers with the current placement set: (re)place any
+     * image whose bytes or box changed, and clear layers no longer shown.
+     */
+    private syncHerdr;
+    /** Escape sequences that bring the terminal in line with the current layout. */
+    render(): string;
+    private evictTransmitted;
+    /** Write placements now, outside an Ink frame. Safe for the cursor. */
+    flushNow(): void;
+    scheduleFlush(): void;
+    /** Remove every placement and free image data in the terminal. */
+    clear(): string;
+}