astroshot 0.2.1 → 0.2.2

package/node_modules/@archastro/astroshot-review/dist/images/png.d.ts

@@ -0,0 +1,14 @@
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** Read width/height from a PNG's IHDR chunk without decoding pixels. */
+export declare function readPngSize(bytes: Buffer): ImageSize | null;
+/** Read just enough of a file to learn its pixel size. */
+export declare function readPngSizeFromFile(filePath: string): Promise<ImageSize | null>;
+export declare function isPngPath(filePath: string): boolean;
+/**
+ * Largest box that fits inside `bounds` while keeping `source`'s aspect
+ * ratio. Never scales up: a small source keeps its own size.
+ */
+export declare function fitInside(source: ImageSize, bounds: ImageSize): ImageSize;

package/node_modules/@archastro/astroshot-review/dist/images/png.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+/** Read width/height from a PNG's IHDR chunk without decoding pixels. */
+export function readPngSize(bytes) {
+    if (bytes.length < 24)
+        return null;
+    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+        return null;
+    if (bytes.toString("ascii", 12, 16) !== "IHDR")
+        return null;
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    if (width === 0 || height === 0)
+        return null;
+    return { width, height };
+}
+/** Read just enough of a file to learn its pixel size. */
+export async function readPngSizeFromFile(filePath) {
+    const handle = await fs.promises.open(filePath, "r");
+    try {
+        const header = Buffer.alloc(32);
+        const { bytesRead } = await handle.read(header, 0, 32, 0);
+        return readPngSize(header.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function isPngPath(filePath) {
+    return /\.png$/i.test(filePath);
+}
+/**
+ * Largest box that fits inside `bounds` while keeping `source`'s aspect
+ * ratio. Never scales up: a small source keeps its own size.
+ */
+export function fitInside(source, bounds) {
+    if (source.width <= bounds.width && source.height <= bounds.height) {
+        return { width: source.width, height: source.height };
+    }
+    const scale = Math.min(bounds.width / source.width, bounds.height / source.height);
+    return {
+        width: Math.max(1, Math.round(source.width * scale)),
+        height: Math.max(1, Math.round(source.height * scale)),
+    };
+}

package/node_modules/@archastro/astroshot-review/dist/images/scale.d.ts

@@ -0,0 +1,31 @@
+import { type ImageSize } from "./png.js";
+export type ScaledFormat = "png" | "rgb";
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScaleRequest {
+    bytes: Buffer;
+    target: ImageSize;
+    /** png keeps alpha; rgb returns packed 3-byte pixels for cell art. */
+    format: ScaledFormat;
+    /** Optional source-pixel crop applied before scaling (for zoom). */
+    crop?: Rect;
+}
+/** Copy a sub-rectangle out of an RGBA buffer, clamped to the image bounds. */
+export declare function cropRgba(source: Buffer, size: ImageSize, rect: Rect): {
+    data: Buffer;
+    size: ImageSize;
+};
+export interface ScaledImage {
+    width: number;
+    height: number;
+    format: ScaledFormat;
+    data: Buffer;
+}
+/** Area-average RGBA resample. Exact for integer ratios, good enough otherwise. */
+export declare function resampleRgba(source: Buffer, sourceSize: ImageSize, target: ImageSize): Buffer;
+export declare function rgbaToRgb(rgba: Buffer, pixelCount: number, background?: number[]): Buffer;
+export declare function scaleImage(request: ScaleRequest): ScaledImage;

package/node_modules/@archastro/astroshot-review/dist/images/scale.js

@@ -0,0 +1,102 @@
+/**
+ * Pure-JS PNG decode, area-average downscale, and re-encode. Runs either on
+ * a worker thread or inline; it has no dependency on threads itself.
+ */
+import { PNG } from "pngjs";
+import { fitInside } from "./png.js";
+/** Copy a sub-rectangle out of an RGBA buffer, clamped to the image bounds. */
+export function cropRgba(source, size, rect) {
+    const x = Math.max(0, Math.min(size.width - 1, Math.round(rect.x)));
+    const y = Math.max(0, Math.min(size.height - 1, Math.round(rect.y)));
+    const width = Math.max(1, Math.min(size.width - x, Math.round(rect.width)));
+    const height = Math.max(1, Math.min(size.height - y, Math.round(rect.height)));
+    const out = Buffer.alloc(width * height * 4);
+    for (let row = 0; row < height; row += 1) {
+        const srcStart = ((y + row) * size.width + x) * 4;
+        source.copy(out, row * width * 4, srcStart, srcStart + width * 4);
+    }
+    return { data: out, size: { width, height } };
+}
+/** Area-average RGBA resample. Exact for integer ratios, good enough otherwise. */
+export function resampleRgba(source, sourceSize, target) {
+    const { width: sw, height: sh } = sourceSize;
+    const { width: tw, height: th } = target;
+    const out = Buffer.alloc(tw * th * 4);
+    const xRatio = sw / tw;
+    const yRatio = sh / th;
+    for (let ty = 0; ty < th; ty += 1) {
+        const y0 = Math.floor(ty * yRatio);
+        const y1 = Math.max(y0 + 1, Math.floor((ty + 1) * yRatio));
+        for (let tx = 0; tx < tw; tx += 1) {
+            const x0 = Math.floor(tx * xRatio);
+            const x1 = Math.max(x0 + 1, Math.floor((tx + 1) * xRatio));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            let count = 0;
+            for (let y = y0; y < y1 && y < sh; y += 1) {
+                let offset = (y * sw + x0) * 4;
+                for (let x = x0; x < x1 && x < sw; x += 1) {
+                    const alpha = source[offset + 3];
+                    // Premultiply so transparent pixels do not bleed their color.
+                    r += source[offset] * alpha;
+                    g += source[offset + 1] * alpha;
+                    b += source[offset + 2] * alpha;
+                    a += alpha;
+                    count += 1;
+                    offset += 4;
+                }
+            }
+            const index = (ty * tw + tx) * 4;
+            if (a > 0) {
+                out[index] = Math.round(r / a);
+                out[index + 1] = Math.round(g / a);
+                out[index + 2] = Math.round(b / a);
+                out[index + 3] = Math.round(a / count);
+            }
+        }
+    }
+    return out;
+}
+export function rgbaToRgb(rgba, pixelCount, background = [24, 24, 28]) {
+    const out = Buffer.alloc(pixelCount * 3);
+    for (let index = 0; index < pixelCount; index += 1) {
+        const alpha = rgba[index * 4 + 3] / 255;
+        for (let channel = 0; channel < 3; channel += 1) {
+            const value = rgba[index * 4 + channel];
+            out[index * 3 + channel] = Math.round(value * alpha + background[channel] * (1 - alpha));
+        }
+    }
+    return out;
+}
+export function scaleImage(request) {
+    const decoded = PNG.sync.read(request.bytes);
+    let sourceData = decoded.data;
+    let sourceSize = { width: decoded.width, height: decoded.height };
+    if (request.crop) {
+        const cropped = cropRgba(sourceData, sourceSize, request.crop);
+        sourceData = cropped.data;
+        sourceSize = cropped.size;
+    }
+    const target = fitInside(sourceSize, request.target);
+    const rgba = target.width === sourceSize.width && target.height === sourceSize.height
+        ? sourceData
+        : resampleRgba(sourceData, sourceSize, target);
+    if (request.format === "rgb") {
+        return {
+            width: target.width,
+            height: target.height,
+            format: "rgb",
+            data: rgbaToRgb(rgba, target.width * target.height),
+        };
+    }
+    const png = new PNG({ width: target.width, height: target.height });
+    png.data = rgba;
+    return {
+        width: target.width,
+        height: target.height,
+        format: "png",
+        data: PNG.sync.write(png, { deflateLevel: 6 }),
+    };
+}

package/node_modules/@archastro/astroshot-review/dist/images/service.d.ts

@@ -0,0 +1,54 @@
+import { type ImageSize } from "./png.js";
+import type { Rect } from "./scale.js";
+import { type ScaledFormat } from "./scale.js";
+export interface PreparedImage {
+    key: string;
+    path: string;
+    /** Pixel size of the prepared payload. */
+    width: number;
+    height: number;
+    /** Pixel size of the source file. */
+    sourceWidth: number;
+    sourceHeight: number;
+    format: ScaledFormat;
+    data: Buffer;
+    /** True when `data` is the untouched file, so a file-path transmission is valid. */
+    isOriginal: boolean;
+    mtimeMs: number;
+    size: number;
+}
+export interface ImageServiceOptions {
+    /** 0 runs decode inline (tests); default is min(2, cpus-1). */
+    workers?: number;
+    /** Memory budget for prepared payloads. */
+    cacheBytes?: number;
+    /** A source at most this many times larger than the target is sent as-is. */
+    passthroughRatio?: number;
+}
+export declare class ImageService {
+    private readonly cache;
+    private readonly cacheOrder;
+    private cachedBytes;
+    private readonly cacheBytes;
+    private readonly passthroughRatio;
+    private readonly workerCount;
+    private workers;
+    private nextWorker;
+    private nextJobId;
+    private readonly pending;
+    private disposed;
+    constructor(options?: ImageServiceOptions);
+    /** Identity + target size key. Callers can use it for placement bookkeeping. */
+    static cacheKey(filePath: string, stat: {
+        mtimeMs: number;
+        size: number;
+    }, target: ImageSize, format: ScaledFormat, crop?: Rect): string;
+    prepare(filePath: string, target: ImageSize, format?: ScaledFormat, crop?: Rect): Promise<PreparedImage>;
+    private build;
+    private scale;
+    private pickWorker;
+    private touch;
+    private account;
+    private evict;
+    dispose(): Promise<void>;
+}

package/node_modules/@archastro/astroshot-review/dist/images/service.js

@@ -0,0 +1,163 @@
+/**
+ * Prepares image bytes for the terminal: reads the file, decides whether the
+ * original PNG is already small enough, otherwise downsamples on a worker
+ * thread, and caches the result by file identity and target size.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import { Worker } from "node:worker_threads";
+import { fitInside, readPngSize } from "./png.js";
+import { scaleImage } from "./scale.js";
+export class ImageService {
+    cache = new Map();
+    cacheOrder = [];
+    cachedBytes = 0;
+    cacheBytes;
+    passthroughRatio;
+    workerCount;
+    workers = [];
+    nextWorker = 0;
+    nextJobId = 1;
+    pending = new Map();
+    disposed = false;
+    constructor(options = {}) {
+        this.workerCount =
+            options.workers ?? Math.max(0, Math.min(2, os.availableParallelism() - 1));
+        this.cacheBytes = options.cacheBytes ?? 96 * 1024 * 1024;
+        this.passthroughRatio = options.passthroughRatio ?? 1.35;
+    }
+    /** Identity + target size key. Callers can use it for placement bookkeeping. */
+    static cacheKey(filePath, stat, target, format, crop) {
+        const cropKey = crop ? `|${Math.round(crop.x)},${Math.round(crop.y)},${Math.round(crop.width)},${Math.round(crop.height)}` : "";
+        return `${filePath}|${Math.round(stat.mtimeMs)}|${stat.size}|${target.width}x${target.height}|${format}${cropKey}`;
+    }
+    async prepare(filePath, target, format = "png", crop) {
+        const stat = await fs.promises.stat(filePath);
+        const key = ImageService.cacheKey(filePath, stat, target, format, crop);
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.touch(key);
+            return cached;
+        }
+        const job = this.build(filePath, stat, target, format, key, crop);
+        this.cache.set(key, job);
+        this.cacheOrder.push(key);
+        job.then((prepared) => this.account(key, prepared.data.length), () => this.evict(key));
+        return job;
+    }
+    async build(filePath, stat, target, format, key, crop) {
+        const bytes = await fs.promises.readFile(filePath);
+        const source = readPngSize(bytes);
+        if (!source)
+            throw new Error(`Not a PNG image: ${filePath}`);
+        const base = {
+            key,
+            path: filePath,
+            sourceWidth: source.width,
+            sourceHeight: source.height,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+        };
+        if (!crop) {
+            const fitted = fitInside(source, target);
+            const ratio = Math.max(source.width / fitted.width, source.height / fitted.height);
+            if (format === "png" && ratio <= this.passthroughRatio) {
+                return { ...base, width: source.width, height: source.height, format: "png", data: bytes, isOriginal: true };
+            }
+        }
+        const scaled = await this.scale(bytes, target, format, crop);
+        return { ...base, ...scaled, isOriginal: false };
+    }
+    async scale(bytes, target, format, crop) {
+        if (this.workerCount === 0) {
+            const scaled = scaleImage({ bytes, target, format, crop });
+            return { width: scaled.width, height: scaled.height, format: scaled.format, data: scaled.data };
+        }
+        const worker = this.pickWorker();
+        const id = this.nextJobId++;
+        const payload = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const response = await new Promise((resolve) => {
+            this.pending.set(id, { resolve });
+            const request = {
+                id,
+                bytes: payload,
+                targetWidth: target.width,
+                targetHeight: target.height,
+                format,
+                crop,
+            };
+            worker.postMessage(request, [payload]);
+        });
+        if (!response.ok)
+            throw new Error(response.error);
+        return {
+            width: response.width,
+            height: response.height,
+            format: response.format,
+            data: Buffer.from(response.data),
+        };
+    }
+    pickWorker() {
+        if (this.workers.length < this.workerCount) {
+            const worker = new Worker(new URL("./worker.js", import.meta.url));
+            worker.unref();
+            worker.on("message", (response) => {
+                const job = this.pending.get(response.id);
+                if (!job)
+                    return;
+                this.pending.delete(response.id);
+                job.resolve(response);
+            });
+            worker.on("error", (error) => {
+                for (const [id, job] of this.pending) {
+                    job.resolve({ id, ok: false, error: error.message });
+                }
+                this.pending.clear();
+                this.workers = this.workers.filter((candidate) => candidate !== worker);
+            });
+            this.workers.push(worker);
+            return worker;
+        }
+        const worker = this.workers[this.nextWorker % this.workers.length];
+        this.nextWorker += 1;
+        return worker;
+    }
+    touch(key) {
+        const index = this.cacheOrder.indexOf(key);
+        if (index !== -1) {
+            this.cacheOrder.splice(index, 1);
+            this.cacheOrder.push(key);
+        }
+    }
+    account(key, bytes) {
+        this.cachedBytes += bytes;
+        while (this.cachedBytes > this.cacheBytes && this.cacheOrder.length > 1) {
+            const oldest = this.cacheOrder[0];
+            if (oldest === key)
+                break;
+            this.evict(oldest);
+        }
+    }
+    evict(key) {
+        const job = this.cache.get(key);
+        if (!job)
+            return;
+        this.cache.delete(key);
+        const index = this.cacheOrder.indexOf(key);
+        if (index !== -1)
+            this.cacheOrder.splice(index, 1);
+        job.then((prepared) => {
+            this.cachedBytes -= prepared.data.length;
+        }, () => undefined);
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await Promise.all(this.workers.map((worker) => worker.terminate()));
+        this.workers = [];
+        this.cache.clear();
+        this.cacheOrder.length = 0;
+        this.cachedBytes = 0;
+    }
+}

package/node_modules/@archastro/astroshot-review/dist/images/worker.d.ts

@@ -0,0 +1,21 @@
+import { type Rect, type ScaledFormat } from "./scale.js";
+export interface WorkerRequest {
+    id: number;
+    bytes: ArrayBuffer;
+    targetWidth: number;
+    targetHeight: number;
+    format: ScaledFormat;
+    crop?: Rect;
+}
+export type WorkerResponse = {
+    id: number;
+    ok: true;
+    width: number;
+    height: number;
+    format: ScaledFormat;
+    data: ArrayBuffer;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};

package/node_modules/@archastro/astroshot-review/dist/images/worker.js

@@ -0,0 +1,30 @@
+import { parentPort } from "node:worker_threads";
+import { scaleImage } from "./scale.js";
+parentPort?.on("message", (request) => {
+    try {
+        const scaled = scaleImage({
+            bytes: Buffer.from(request.bytes),
+            target: { width: request.targetWidth, height: request.targetHeight },
+            format: request.format,
+            crop: request.crop,
+        });
+        const data = scaled.data.buffer.slice(scaled.data.byteOffset, scaled.data.byteOffset + scaled.data.byteLength);
+        const response = {
+            id: request.id,
+            ok: true,
+            width: scaled.width,
+            height: scaled.height,
+            format: scaled.format,
+            data,
+        };
+        parentPort?.postMessage(response, [data]);
+    }
+    catch (error) {
+        const response = {
+            id: request.id,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+        parentPort?.postMessage(response);
+    }
+});

package/node_modules/@archastro/astroshot-review/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { main, parseArgs, reviewHelp } from "./cli.js";
+export { ReviewStore } from "./data/store.js";
+export type { StoreState } from "./data/store.js";
+export { findAstroshotDirs, scanTree } from "./data/scan.js";
+export { markSeen, addComment, readReviewDocument, snapshotFromEntry } from "./data/review-store.js";
+export type { Shot, FrictionLog, FrictionRun, FrictionStep, ReviewSnapshot } from "./data/model.js";
+export { probeTerminal, parseProbeResponse } from "./terminal/probe.js";
+export type { TerminalCapabilities } from "./terminal/probe.js";
+export { encodeTransmit, encodePlace, encodeDelete, parseGraphicsCommand } from "./terminal/kitty.js";
+export { ImageLayer } from "./terminal/image-layer.js";
+export { ImageService } from "./images/service.js";
+export { detectFfmpeg, FramePlayer, probeVideo, splitPngStream } from "./video/ffmpeg.js";

package/node_modules/@archastro/astroshot-review/dist/index.js

@@ -0,0 +1,9 @@
+export { main, parseArgs, reviewHelp } from "./cli.js";
+export { ReviewStore } from "./data/store.js";
+export { findAstroshotDirs, scanTree } from "./data/scan.js";
+export { markSeen, addComment, readReviewDocument, snapshotFromEntry } from "./data/review-store.js";
+export { probeTerminal, parseProbeResponse } from "./terminal/probe.js";
+export { encodeTransmit, encodePlace, encodeDelete, parseGraphicsCommand } from "./terminal/kitty.js";
+export { ImageLayer } from "./terminal/image-layer.js";
+export { ImageService } from "./images/service.js";
+export { detectFfmpeg, FramePlayer, probeVideo, splitPngStream } from "./video/ffmpeg.js";

package/node_modules/@archastro/astroshot-review/dist/terminal/graphics-stdout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The stdout Ink renders into. It forwards everything to the real stream and
+ * splices kitty placements into each frame so pictures and text arrive in
+ * the same synchronized update.
+ */
+import type { ImageLayer } from "./image-layer.js";
+export declare function hasPrintableText(chunk: string): boolean;
+export declare function spliceGraphics(chunk: string, graphics: string): string;
+export declare function createGraphicsStdout(real: NodeJS.WriteStream, layer: ImageLayer): NodeJS.WriteStream;

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

@@ -0,0 +1,36 @@
+const ENTER_ALT_SCREEN = "\x1b[?1049h";
+const END_SYNC = "\x1b[?2026l";
+const ANSI_PATTERN = /\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b_[^\x1b]*\x1b\\|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[@-_]/g;
+export function hasPrintableText(chunk) {
+    return chunk.replace(ANSI_PATTERN, "").trim().length > 0;
+}
+export function spliceGraphics(chunk, graphics) {
+    if (!graphics)
+        return chunk;
+    return chunk.endsWith(END_SYNC)
+        ? chunk.slice(0, -END_SYNC.length) + graphics + END_SYNC
+        : chunk + graphics;
+}
+export function createGraphicsStdout(real, layer) {
+    const write = (chunk, ...rest) => {
+        let text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+        if (text.includes(ENTER_ALT_SCREEN)) {
+            // Ink enters the alternate screen without homing the cursor. Frames
+            // must start at the top-left so layout coordinates map to screen cells.
+            text = text.replace(ENTER_ALT_SCREEN, `${ENTER_ALT_SCREEN}\x1b[H\x1b[2J`);
+            layer.invalidate();
+        }
+        if (hasPrintableText(text)) {
+            text = spliceGraphics(text, layer.render());
+        }
+        return real.write(text, ...rest);
+    };
+    return new Proxy(real, {
+        get(target, property, receiver) {
+            if (property === "write")
+                return write;
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}

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

@@ -0,0 +1,61 @@
+export interface HerdrAddress {
+    socket: string;
+    pane: string;
+}
+export declare function herdrAddress(env?: NodeJS.ProcessEnv): HerdrAddress | null;
+/**
+ * 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 declare function probeHerdrSet(address: HerdrAddress): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export interface HerdrDiscovery {
+    ok: boolean;
+    cellWidth?: number;
+    cellHeight?: number;
+    maxLayers?: number;
+    /** Actionable reason when graphics can't be used yet. */
+    reason?: string;
+}
+/** Poll `pane.graphics.info` until herdr reports the cell size, or give up. */
+export declare function discoverHerdr(address: HerdrAddress, options?: {
+    timeoutMs?: number;
+    retryMs?: number;
+    onWaiting?: () => void;
+}): Promise<HerdrDiscovery>;
+export interface HerdrPlacement {
+    col: number;
+    row: number;
+    cols: number;
+    rows: number;
+    z: number;
+}
+/**
+ * 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 declare class HerdrSink {
+    private readonly address;
+    private readonly onError;
+    private readonly layers;
+    /** Every socket opened and not yet closed, whether or not its layer is still mapped. */
+    private readonly connections;
+    private disposed;
+    private generationCount;
+    constructor(address: HerdrAddress, onError: (error: Error) => void);
+    /** Bumps when a layer stream drops unexpectedly, so callers re-send. */
+    get generation(): number;
+    set(layerId: string, png: Buffer, _imageWidth: number, _imageHeight: number, placement: HerdrPlacement): void;
+    clear(layerId: string): void;
+    private close;
+    clearAll(): void;
+    private open;
+    private flush;
+    dispose(): void;
+}