@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/snapshot/snapshot-resize.d.ts

@@ -1,114 +1,75 @@
-/**
- * Downscaling a captured frame to a card-sized thumbnail.
- *
- * Applied AFTER capture rather than during it, and that is deliberate: the two
- * capture paths (the vendor's native HTTP snapshot and the ffmpeg keyframe
- * grab) produce a JPEG by different routes, and only one of them has an
- * ffmpeg filter chain to hook into. Resizing the finished bytes gives both the
- * same behaviour with one implementation.
- *
- * ── Why sharp and not ffmpeg (2026-08-11) ─────────────────────────────────
- * This used to `spawn('ffmpeg')` per resize. The snapshot wrapper is a system
- * builtin, so it loads in the hub's ROOT process: sampled on the live hub,
- * ~1.6 of those children were running at any instant, every one of them
- * parented by the root PID.
- *
- * Be precise about what that cost the root process, because it is easy to
- * overstate. The transcode itself ran in the CHILD and was charged to ffmpeg
- * (16 % + 13 % of a core in that same sample), not to the parent. What the
- * parent paid was the fork, the exec, the JPEG written into one pipe and read
- * back out of the other, and the base64 — real event-loop work, on the loop
- * that also serves the tRPC API, but NOT the 52 ms below.
- *
- * Benchmarked in that container, 2560×1440 → 640 wide, wall-clock per resize:
- *
- *     ffmpeg   52.0 ms   (fork + exec + pipe round-trip + teardown)
- *     sharp     4.8 ms   (in-process libvips, on its own threadpool)
- *
- * So this removes ~29 % of a core of container CPU and the per-resize process
- * churn from the root process. It was NOT verified to be the cause of that
- * process sitting at 90 % — nobody has profiled it.
- *
- * `sharp` is not a new dependency: it is already a host-external
- * (`HOST_EXTERNAL_SPECIFIERS`), already resolved from the framework closure at
- * runtime, and already used by the terminal frame renderer. The build preset
- * keeps it out of the bundle, so this import costs nothing at pack time.
- *
- * The cost is still one resize per (device, stream, width) per cache window —
- * not one per request. What changed is what a resize COSTS.
- */
 /** Runs the resize. Injected so the caller is testable without a real ffmpeg. */
 export type JpegResizer = (bytes: Buffer, width: number) => Promise<Buffer>;
-export declare const RESIZE_TIMEOUT_MS = 10000;
+export declare const RESIZE_TIMEOUT_MS = 1e4;
 /**
- * Scale to `width`, preserving aspect ratio.
- *
- * Rejects on failure or timeout. It NEVER falls back to the original silently —
- * a caller that quietly served the 4K frame when the resize failed would
- * reproduce exactly the bug this whole module exists to fix, and nobody would
- * see it. The caller decides, and logs.
- *
- * It DOES upscale a source narrower than `width`, and that is deliberate. A
- * `withoutEnlargement: true` was tried first — it is the obvious saving, since
- * upscaling pays encode cost for a blurrier, larger image. But the caller
- * stamps the response ETag from the width it asked for, and its resize-FAILURE
- * path already returns `width: undefined` specifically so a response can never
- * "claim a width the bytes do not have". Silently returning 320 px bytes for a
- * `w=640` request breaks that invariant on the SUCCESS path, where nobody is
- * looking. Honest output width beats a few saved pixels; revisit only together
- * with the ETag.
- */
+* Scale to `width`, preserving aspect ratio.
+*
+* Rejects on failure or timeout. It NEVER falls back to the original silently —
+* a caller that quietly served the 4K frame when the resize failed would
+* reproduce exactly the bug this whole module exists to fix, and nobody would
+* see it. The caller decides, and logs.
+*
+* It DOES upscale a source narrower than `width`, and that is deliberate. A
+* `withoutEnlargement: true` was tried first — it is the obvious saving, since
+* upscaling pays encode cost for a blurrier, larger image. But the caller
+* stamps the response ETag from the width it asked for, and its resize-FAILURE
+* path already returns `width: undefined` specifically so a response can never
+* "claim a width the bytes do not have". Silently returning 320 px bytes for a
+* `w=640` request breaks that invariant on the SUCCESS path, where nobody is
+* looking. Honest output width beats a few saved pixels; revisit only together
+* with the ETag.
+*/
 export declare function resizeJpeg(bytes: Buffer, width: number, timeoutMs?: number): Promise<Buffer>;
 /**
- * Resized frames, keyed by (device, stream, width, state treatment) AND
- * validated against the source frame's timestamp.
- *
- * The timestamp is the whole correctness argument: a variant outlives nothing.
- * When the underlying frame is recaptured its `capturedAt` moves, every variant
- * derived from the old one stops matching, and the next request re-derives.
- * Without that check a card would keep showing a thumbnail of a frame the
- * full-size view had already replaced.
- */
+* Resized frames, keyed by (device, stream, width, state treatment) AND
+* validated against the source frame's timestamp.
+*
+* The timestamp is the whole correctness argument: a variant outlives nothing.
+* When the underlying frame is recaptured its `capturedAt` moves, every variant
+* derived from the old one stops matching, and the next request re-derives.
+* Without that check a card would keep showing a thumbnail of a frame the
+* full-size view had already replaced.
+*/
 /**
- * Byte budget across every retained variant.
- *
- * Variants are small individually (a card-sized JPEG is tens of KB) but the key
- * space is a product — device × stream × width × state treatment — and the map
- * had no cap at all. 16 MiB is hundreds of thumbnails, far beyond any real
- * roster's working set, and turns an unbounded product into a ceiling.
- */
+* Byte budget across every retained variant.
+*
+* Variants are small individually (a card-sized JPEG is tens of KB) but the key
+* space is a product — device × stream × width × state treatment — and the map
+* had no cap at all. 16 MiB is hundreds of thumbnails, far beyond any real
+* roster's working set, and turns an unbounded product into a ceiling.
+*/
 export declare const SNAPSHOT_VARIANT_CACHE_MAX_BYTES: number;
 export interface SnapshotVariantCacheOptions {
-    /** Total variant bytes retained. Default {@link SNAPSHOT_VARIANT_CACHE_MAX_BYTES}. */
-    readonly maxBytes?: number;
-    /** Injected clock, so LRU order is testable without real time passing. */
-    readonly now?: () => number;
+	/** Total variant bytes retained. Default {@link SNAPSHOT_VARIANT_CACHE_MAX_BYTES}. */
+	readonly maxBytes?: number;
+	/** Injected clock, so LRU order is testable without real time passing. */
+	readonly now?: () => number;
 }
 export declare class SnapshotVariantCache {
-    private readonly byKey;
-    private readonly keysByDevice;
-    private readonly maxBytes;
-    private readonly now;
-    private totalBytes;
-    constructor(options?: SnapshotVariantCacheOptions);
-    private static key;
-    /** The variant for this exact frame, or undefined when it is missing or was
-     *  derived from an older capture.
-     *
-     *  A superseded variant is DELETED here, not merely reported missing. It used
-     *  to be left in the map: unreachable by every future read (its `sourceTs` can
-     *  never match again) and removed by nothing, so every recapture added a dead
-     *  key. Returning `undefined` while retaining the bytes is the leak. */
-    get(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, variantKey?: string): Buffer | undefined;
-    set(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, bytes: Buffer, variantKey?: string): void;
-    /** Variant bytes currently retained. */
-    sizeBytes(): number;
-    /** Variants currently retained — including any that are no longer readable.
-     *  The number that used to only ever go up. */
-    entryCount(): number;
-    /** Evict least-recently-accessed first until the budget holds. */
-    private enforceBudget;
-    private forget;
-    deleteDevice(deviceId: number): void;
-    clear(): void;
+	private readonly byKey;
+	private readonly keysByDevice;
+	private readonly maxBytes;
+	private readonly now;
+	private totalBytes;
+	constructor(options?: SnapshotVariantCacheOptions);
+	private static key;
+	/** The variant for this exact frame, or undefined when it is missing or was
+	*  derived from an older capture.
+	*
+	*  A superseded variant is DELETED here, not merely reported missing. It used
+	*  to be left in the map: unreachable by every future read (its `sourceTs` can
+	*  never match again) and removed by nothing, so every recapture added a dead
+	*  key. Returning `undefined` while retaining the bytes is the leak. */
+	get(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, variantKey?: string): Buffer | undefined;
+	set(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, bytes: Buffer, variantKey?: string): void;
+	/** Variant bytes currently retained. */
+	sizeBytes(): number;
+	/** Variants currently retained — including any that are no longer readable.
+	*  The number that used to only ever go up. */
+	entryCount(): number;
+	/** Evict least-recently-accessed first until the budget holds. */
+	private enforceBudget;
+	private forget;
+	deleteDevice(deviceId: number): void;
+	clear(): void;
 }