@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/camera-grid/grid-canvas.d.ts

@@ -1,85 +1,85 @@
 /**
- * The composed picture as a buffer this addon owns.
- *
- * ## Why a canvas instead of ffmpeg's `overlay`
- *
- * `overlay` pairs its inputs BY PTS, and ffmpeg gives every input pts 0 at ITS
- * OWN first frame. Two sources that joined at different moments therefore
- * compose different moments, for the life of the child, with nothing to correct
- * it. Measured on this hub at 4-5 s between two tiles, drifting over hours as
- * the sources' key-frame phases slide through each other (0.5 s at 13:05, 3 s
- * at 13:50 on the same pair, 2026-09-18).
- *
- * It is not reachable from a flag. `-use_wallclock_as_timestamps` re-times by
- * ARRIVAL and wrecked the pacing instead (ten stalls over a second in an 18 s
- * run, against none). `-copyts` changes nothing, because the broker re-bases
- * each session — both restreams report `pts_time:0` — so there is no common
- * timeline to trim against. Serving each dial from the newest key frame it
- * already holds does not help either: those key frames are of different ages,
- * and pts 0 still lands on whatever arrives first.
- *
- * A canvas has no pairing to get wrong. When the output tick fires, each
- * rectangle holds whatever arrived last from its source, and the OUTPUT owns
- * the clock. The gap is zero by construction rather than by tuning, and a cell
- * that has produced nothing yet costs nothing — so the picture appears at once
- * instead of waiting for the slowest source's first key frame. What such a cell
- * shows is the seed the compositor blits in at construction
- * (`grid-canvas-seed.ts`); `clear()` below is what it shows without one.
- *
- * ## Why yuv420p, and why everything here must be even
- *
- * yuv420p is the one pixel format every consumer of a CamStack profile reads,
- * and a plane copy in it is a strided memcpy — no arithmetic per pixel, which
- * is the whole reason compositing can be cheaper than the filter graph it
- * replaces.
- *
- * Its chroma planes are half resolution in BOTH axes. So an odd origin or an
- * odd size would put a tile's chroma half a sample off its luma, and the result
- * is a tile that is subtly TINTED rather than visibly broken — the kind of
- * fault that survives review. Every rectangle is therefore required to be even,
- * and a blit that is not is refused rather than rounded: rounding would move a
- * cell the operator placed.
- */
+* The composed picture as a buffer this addon owns.
+*
+* ## Why a canvas instead of ffmpeg's `overlay`
+*
+* `overlay` pairs its inputs BY PTS, and ffmpeg gives every input pts 0 at ITS
+* OWN first frame. Two sources that joined at different moments therefore
+* compose different moments, for the life of the child, with nothing to correct
+* it. Measured on this hub at 4-5 s between two tiles, drifting over hours as
+* the sources' key-frame phases slide through each other (0.5 s at 13:05, 3 s
+* at 13:50 on the same pair, 2026-09-18).
+*
+* It is not reachable from a flag. `-use_wallclock_as_timestamps` re-times by
+* ARRIVAL and wrecked the pacing instead (ten stalls over a second in an 18 s
+* run, against none). `-copyts` changes nothing, because the broker re-bases
+* each session — both restreams report `pts_time:0` — so there is no common
+* timeline to trim against. Serving each dial from the newest key frame it
+* already holds does not help either: those key frames are of different ages,
+* and pts 0 still lands on whatever arrives first.
+*
+* A canvas has no pairing to get wrong. When the output tick fires, each
+* rectangle holds whatever arrived last from its source, and the OUTPUT owns
+* the clock. The gap is zero by construction rather than by tuning, and a cell
+* that has produced nothing yet costs nothing — so the picture appears at once
+* instead of waiting for the slowest source's first key frame. What such a cell
+* shows is the seed the compositor blits in at construction
+* (`grid-canvas-seed.ts`); `clear()` below is what it shows without one.
+*
+* ## Why yuv420p, and why everything here must be even
+*
+* yuv420p is the one pixel format every consumer of a CamStack profile reads,
+* and a plane copy in it is a strided memcpy — no arithmetic per pixel, which
+* is the whole reason compositing can be cheaper than the filter graph it
+* replaces.
+*
+* Its chroma planes are half resolution in BOTH axes. So an odd origin or an
+* odd size would put a tile's chroma half a sample off its luma, and the result
+* is a tile that is subtly TINTED rather than visibly broken — the kind of
+* fault that survives review. Every rectangle is therefore required to be even,
+* and a blit that is not is refused rather than rounded: rounding would move a
+* cell the operator placed.
+*/
 export interface PixelSize {
-    readonly width: number;
-    readonly height: number;
+	readonly width: number;
+	readonly height: number;
 }
 export interface PixelOrigin {
-    readonly x: number;
-    readonly y: number;
+	readonly x: number;
+	readonly y: number;
 }
 /** Bytes one yuv420p frame of this size occupies. */
 export declare function yuv420pSize(width: number, height: number): number;
 /**
- * Round DOWN to even.
- *
- * Down and not nearest: a tile that rounded UP would claim a row of samples the
- * decoder was never asked to produce, and the copy would either overrun or be
- * refused at the moment the picture is wanted.
- */
+* Round DOWN to even.
+*
+* Down and not nearest: a tile that rounded UP would claim a row of samples the
+* decoder was never asked to produce, and the copy would either overrun or be
+* refused at the moment the picture is wanted.
+*/
 export declare function evenDown(value: number): number;
 export declare class GridCanvas {
-    readonly width: number;
-    readonly height: number;
-    readonly buffer: Buffer;
-    private readonly lumaBytes;
-    private readonly chromaBytes;
-    constructor(width: number, height: number);
-    /**
-     * Legible black — Y 0, chroma 128 (neutral).
-     *
-     * `Buffer.alloc` already zeroes, and zeroed CHROMA is not black: it is a
-     * strong green. A cell nobody has filled yet has to look like an empty cell,
-     * not like a fault.
-     */
-    clear(): void;
-    /**
-     * Copy one decoded tile in at `origin`.
-     *
-     * Returns false — never throws, never writes a partial tile — when the tile
-     * does not fit, is the wrong size for the dimensions it claims, or sits on an
-     * odd boundary. This runs on the output tick, so a bad frame from one source
-     * must cost that source's rectangle and nothing else.
-     */
-    blit(tile: Buffer, size: PixelSize, origin: PixelOrigin): boolean;
+	readonly width: number;
+	readonly height: number;
+	readonly buffer: Buffer;
+	private readonly lumaBytes;
+	private readonly chromaBytes;
+	constructor(width: number, height: number);
+	/**
+	* Legible black — Y 0, chroma 128 (neutral).
+	*
+	* `Buffer.alloc` already zeroes, and zeroed CHROMA is not black: it is a
+	* strong green. A cell nobody has filled yet has to look like an empty cell,
+	* not like a fault.
+	*/
+	clear(): void;
+	/**
+	* Copy one decoded tile in at `origin`.
+	*
+	* Returns false — never throws, never writes a partial tile — when the tile
+	* does not fit, is the wrong size for the dimensions it claims, or sits on an
+	* odd boundary. This runs on the output tick, so a bad frame from one source
+	* must cost that source's rectangle and nothing else.
+	*/
+	blit(tile: Buffer, size: PixelSize, origin: PixelOrigin): boolean;
 }

package/dist/builtins/camera-grid/grid-child.d.ts

@@ -1,19 +1,32 @@
-import { IScopedLogger } from '@camstack/types';
-import { GridSourceHandle, GridStreamChild, GridStreamPlan } from './grid-stream-session.js';
+/**
+* Spawning the composition, through the ONE primitive.
+*
+* `FfmpegProcess` (`@camstack/types`) owns spawn, the first-data deadline, the
+* hardware→software retry, exit classification and the bounded restart. This
+* file owns only the PLUMBING — which bytes go where — because that is the one
+* thing the primitive deliberately does not own.
+*
+* `maxRestarts: 0`. A composite is demand-driven: if the child dies, the
+* session tells every consumer why and tears down, and the consumer's next read
+* starts a cold one with freshly acquired sources. A restart inside the process
+* would reuse broker handles that may already have been released.
+*/
+import { type IScopedLogger } from "@camstack/types";
+import type { GridSourceHandle, GridStreamChild, GridStreamPlan } from "./grid-stream-session.js";
 export interface GridChildContext {
-    readonly binaryPath: string;
-    readonly logger: IScopedLogger;
-    /** The COMPOSITE's device id — every line the primitive emits is tagged with it. */
-    readonly deviceId: number;
-    /**
-     * The SOURCE cameras' names, for the cards the canvas is seeded with
-     * (`grid-canvas-seed.ts`). Read at the point of use rather than mirrored:
-     * this addon does not own those devices, and a name it cached would be the
-     * second copy of a fact the device manager already owns (D224).
-     *
-     * Optional, and a failure is not one: a card with no name carries the device
-     * id, which is what every log line about that tile carries anyway.
-     */
-    readonly resolveSourceNames?: (deviceIds: readonly number[]) => Promise<ReadonlyMap<number, string>>;
+	readonly binaryPath: string;
+	readonly logger: IScopedLogger;
+	/** The COMPOSITE's device id — every line the primitive emits is tagged with it. */
+	readonly deviceId: number;
+	/**
+	* The SOURCE cameras' names, for the cards the canvas is seeded with
+	* (`grid-canvas-seed.ts`). Read at the point of use rather than mirrored:
+	* this addon does not own those devices, and a name it cached would be the
+	* second copy of a fact the device manager already owns (D224).
+	*
+	* Optional, and a failure is not one: a card with no name carries the device
+	* id, which is what every log line about that tile carries anyway.
+	*/
+	readonly resolveSourceNames?: (deviceIds: readonly number[]) => Promise<ReadonlyMap<number, string>>;
 }
 export declare function startGridChild(ctx: GridChildContext, plan: GridStreamPlan, sources: readonly GridSourceHandle[], onEnded: (reason: string) => void): Promise<GridStreamChild>;

package/dist/builtins/camera-grid/grid-compositor-child.d.ts

@@ -1,3 +1,3 @@
-import { GridChildContext } from './grid-child.js';
-import { GridSourceHandle, GridStreamChild, GridStreamPlan } from './grid-stream-session.js';
+import type { GridChildContext } from "./grid-child.js";
+import type { GridSourceHandle, GridStreamChild, GridStreamPlan } from "./grid-stream-session.js";
 export declare function startGridCompositorChild(ctx: GridChildContext, plan: GridStreamPlan, sources: readonly GridSourceHandle[], onEnded: (reason: string) => void): Promise<GridStreamChild>;

package/dist/builtins/camera-grid/grid-compositor-invocation.d.ts

@@ -1,19 +1,47 @@
-import { FfmpegInvocation, FfmpegVideoEncoderId } from '@camstack/types';
-import { GridTile } from './grid-tile-plan.js';
-import { PixelSize } from './grid-canvas.js';
+/**
+* The two argv the compositor spawns: a tile DECODER, and the canvas ENCODER.
+*
+* Both go through the shared builder in `@camstack/types`. This addon builds no
+* argv of its own — the repo has already shipped two builders that disagreed
+* about hardware, and `scripts/check-ffmpeg-primitive.ts` refuses a third.
+*
+* ## The decoder pays no codec on the way out
+*
+* A tile is copied into a canvas this process owns, so encoding it and decoding
+* it again would be two codecs paid to deliver frames that were already there.
+* It emits raw yuv420p — the format the canvas is in, so the composition is a
+* strided memcpy rather than a convert.
+*
+* The input flags are the ones D527 measured: the probe returns from the SDP
+* (`0` / `32`) instead of reading media, which is what took the old single
+* child's start from ~9 s to 2.3 s. They matter less here — a compositor does
+* not pair inputs, so a slow open costs that tile's first frame and nothing
+* else — but a tile that appears in 300 ms instead of 4 s is still the
+* difference the operator sees.
+*
+* ## The encoder never decodes
+*
+* It reads the canvas as raw frames on stdin and encodes once. `zerolatency`
+* and a one-second GOP are carried over from the single-child invocation, where
+* they were measured: without `zerolatency` about four seconds of picture sat
+* inside the encoder, which the operator reported as "ritardi di secondi".
+*/
+import type { FfmpegInvocation, FfmpegVideoEncoderId } from "@camstack/types";
+import { type GridTile } from "./grid-tile-plan.js";
+import type { PixelSize } from "./grid-canvas.js";
 export interface GridTileDecoderInput {
-    readonly tile: GridTile;
-    /** A broker restream URL, acquired through `streamBroker.getStreamWithCodec`. */
-    readonly url: string;
-    readonly fps: number;
+	readonly tile: GridTile;
+	/** A broker restream URL, acquired through `streamBroker.getStreamWithCodec`. */
+	readonly url: string;
+	readonly fps: number;
 }
 /** One tile's decoder: dial in, raw yuv420p frames out. */
 export declare function gridTileDecoderInvocation(input: GridTileDecoderInput): FfmpegInvocation;
 export interface GridCanvasEncoderInput {
-    readonly canvas: PixelSize;
-    readonly fps: number;
-    readonly encoder: FfmpegVideoEncoderId;
-    readonly bitrateKbps: number;
+	readonly canvas: PixelSize;
+	readonly fps: number;
+	readonly encoder: FfmpegVideoEncoderId;
+	readonly bitrateKbps: number;
 }
 /** The canvas encoder: raw frames on stdin, one compressed stream out. */
 export declare function gridCanvasEncoderInvocation(input: GridCanvasEncoderInput): FfmpegInvocation;

package/dist/builtins/camera-grid/grid-compositor.d.ts

@@ -1,54 +1,54 @@
-import { GridTilePlan } from './grid-tile-plan.js';
+import type { GridTilePlan } from "./grid-tile-plan.js";
 export interface GridCompositorDeps {
-    readonly plan: GridTilePlan;
-    /**
-     * Hand one composed frame to the encoder. `false` means the sink is not
-     * draining — the caller slows down rather than queueing raw frames, which at
-     * 345 KB each is how a stalled encoder becomes an OOM.
-     */
-    readonly write: (frame: Buffer) => boolean;
-    /**
-     * The picture the canvas carries before any tile has arrived — one card per
-     * cell, naming its camera (`grid-canvas-seed.ts`). `null` ⇒ black, which is
-     * what this was before the seed and what it falls back to when the seed
-     * cannot be drawn.
-     *
-     * Blitted ONCE, here, so the very first tick already carries it: the tick
-     * serves every cell and must never wait on a render.
-     */
-    readonly seed: Buffer | null;
+	readonly plan: GridTilePlan;
+	/**
+	* Hand one composed frame to the encoder. `false` means the sink is not
+	* draining — the caller slows down rather than queueing raw frames, which at
+	* 345 KB each is how a stalled encoder becomes an OOM.
+	*/
+	readonly write: (frame: Buffer) => boolean;
+	/**
+	* The picture the canvas carries before any tile has arrived — one card per
+	* cell, naming its camera (`grid-canvas-seed.ts`). `null` ⇒ black, which is
+	* what this was before the seed and what it falls back to when the seed
+	* cannot be drawn.
+	*
+	* Blitted ONCE, here, so the very first tick already carries it: the tick
+	* serves every cell and must never wait on a render.
+	*/
+	readonly seed: Buffer | null;
 }
 export declare class GridCompositor {
-    private readonly deps;
-    private readonly canvas;
-    /** Keyed by tile id — unique per CELL, because one camera can hold two. */
-    private readonly placed;
-    private closed;
-    constructor(deps: GridCompositorDeps);
-    /**
-     * Raw bytes from one decoder output.
-     *
-     * A tile this composition has no rectangle for is IGNORED, never thrown on: a
-     * child that outlives a layout change would otherwise take the tick down with
-     * it, and the tick is what every other cell depends on.
-     */
-    onTile(tileId: string, chunk: Buffer): void;
-    /**
-     * Compose and emit one frame. Returns what the sink said about back-pressure.
-     *
-     * Every tile is redrawn, fresh or not: a tile that produced nothing this tick
-     * is a still picture, not a hole, and clearing it would make a late source
-     * flicker. The canvas is never cleared between ticks for the same reason.
-     */
-    tick(): boolean;
-    /**
-     * A tile's decoder was replaced: drop its half frame, keep its picture.
-     *
-     * Without this the new decoder's bytes would be appended to the old one's
-     * partial frame and every frame after would be sheared — raw video has no
-     * framing to re-sync on.
-     */
-    resetTile(tileId: string): void;
-    /** After this, a tick emits nothing — a dead child must not keep writing. */
-    close(): void;
+	private readonly deps;
+	private readonly canvas;
+	/** Keyed by tile id — unique per CELL, because one camera can hold two. */
+	private readonly placed;
+	private closed;
+	constructor(deps: GridCompositorDeps);
+	/**
+	* Raw bytes from one decoder output.
+	*
+	* A tile this composition has no rectangle for is IGNORED, never thrown on: a
+	* child that outlives a layout change would otherwise take the tick down with
+	* it, and the tick is what every other cell depends on.
+	*/
+	onTile(tileId: string, chunk: Buffer): void;
+	/**
+	* Compose and emit one frame. Returns what the sink said about back-pressure.
+	*
+	* Every tile is redrawn, fresh or not: a tile that produced nothing this tick
+	* is a still picture, not a hole, and clearing it would make a late source
+	* flicker. The canvas is never cleared between ticks for the same reason.
+	*/
+	tick(): boolean;
+	/**
+	* A tile's decoder was replaced: drop its half frame, keep its picture.
+	*
+	* Without this the new decoder's bytes would be appended to the old one's
+	* partial frame and every frame after would be sheared — raw video has no
+	* framing to re-sync on.
+	*/
+	resetTile(tileId: string): void;
+	/** After this, a tick emits nothing — a dead child must not keep writing. */
+	close(): void;
 }

package/dist/builtins/camera-grid/grid-detection-mapping.d.ts

@@ -1,31 +1,61 @@
-import { DetectionBoundingBox } from '@camstack/types';
-import { NormalizedRect } from './grid-filter-graph.js';
+/**
+* A detection seen by a SOURCE camera, placed where the operator is looking.
+*
+* ## Why a grid maps boxes at all
+*
+* The viewer feeds the detection ring and the box overlay from the SAME event
+* (`detection.result`). So a grid that reports detections — which is what makes
+* its tile light up — reports boxes too, whether or not anyone asked for them.
+* The only choices are to send the source's own box, which would be drawn
+* against the composed canvas at confidently wrong coordinates, or to carry it
+* through the geometry the composition already uses. Both rectangles are
+* normalized on both sides (D519), so carrying it is a multiplication.
+*
+* ## Three ways to be subtly wrong
+*
+* - **A camera can appear in SEVERAL cells.** A wide shot and a crop of the
+*   same street is the case composites are asked for most, and `grid-plan.ts`
+*   already makes both read ONE input. One detection therefore lands once per
+*   cell that shows it — or not at all.
+* - **A cell shows only PART of its source.** A detection outside the crop is
+*   not in the picture, and drawing it at the cell's edge would invent a
+*   subject standing where nobody is.
+* - **A detection can straddle the crop edge.** Half a subject really is half
+*   visible, so the box is clipped to what the cell shows rather than dropped.
+*
+* This deliberately does not go through `deriveDetailCropRect` (D52): that
+* function exists to keep every crop feeding a VECTOR INDEX cut the same way.
+* This is presentation, feeds no index, and routing it through there would add
+* a second cutter to the one thing D52 keeps single.
+*/
+import type { DetectionBoundingBox } from "@camstack/types";
+import type { NormalizedRect } from "./grid-filter-graph.js";
 /** One place a source appears: the part taken, and where that part lands. */
 export interface GridMappingCell {
-    /** The part of the source this cell shows, normalized against the SOURCE. */
-    readonly source: NormalizedRect;
-    /** Where it lands, normalized against the CANVAS. */
-    readonly cell: NormalizedRect;
+	/** The part of the source this cell shows, normalized against the SOURCE. */
+	readonly source: NormalizedRect;
+	/** Where it lands, normalized against the CANVAS. */
+	readonly cell: NormalizedRect;
 }
 export interface GridFrameSize {
-    readonly width: number;
-    readonly height: number;
+	readonly width: number;
+	readonly height: number;
 }
 export interface MapDetectionInput {
-    /** The detection's box, in ABSOLUTE pixels of the source frame. */
-    readonly bbox: DetectionBoundingBox;
-    /** The frame those pixels are measured against (`FrameResult.width/height`). */
-    readonly sourceFrame: GridFrameSize;
-    /** The composed canvas the result is measured against. */
-    readonly canvas: GridFrameSize;
-    /** Every cell this source appears in. */
-    readonly cells: readonly GridMappingCell[];
+	/** The detection's box, in ABSOLUTE pixels of the source frame. */
+	readonly bbox: DetectionBoundingBox;
+	/** The frame those pixels are measured against (`FrameResult.width/height`). */
+	readonly sourceFrame: GridFrameSize;
+	/** The composed canvas the result is measured against. */
+	readonly canvas: GridFrameSize;
+	/** Every cell this source appears in. */
+	readonly cells: readonly GridMappingCell[];
 }
 /**
- * Where this detection lands on the canvas — once per cell that shows it.
- *
- * Empty is a real answer: the subject is in a part of the source this grid does
- * not display, or the frame arrived with no size to measure against. Neither is
- * a reason to guess.
- */
+* Where this detection lands on the canvas — once per cell that shows it.
+*
+* Empty is a real answer: the subject is in a part of the source this grid does
+* not display, or the frame arrived with no size to measure against. Neither is
+* a reason to guess.
+*/
 export declare function mapDetectionToCanvas(input: MapDetectionInput): readonly DetectionBoundingBox[];

package/dist/builtins/camera-grid/grid-device-settings.d.ts

@@ -1,11 +1,35 @@
-import { ConfigUISchema } from '@camstack/types';
+/**
+* The grid's own section on the camera page — built HERE, not derived by the
+* framework.
+*
+* The section this returns is what `getDeviceSettingsContribution` hands the
+* device-page aggregation. It carries the layout widget, and it carries the
+* placement with it: the addon names its own tab, location and order, the way
+* any other setting does.
+*
+* The alternative the framework offers — a `deviceConfig.ui` block on the cap —
+* renders the same widget, and is what seven other widgets still use. It was
+* rejected here for two reasons that are not cosmetic:
+*
+*  - placement would be a CAP declaration, so changing where a grid's editor
+*    lives would mean a framework change and a published server;
+*  - it cannot DECLINE. A `deviceConfig.ui` section is emitted for every device
+*    the cap is bound to, so a camera that is not a grid would get a panel that
+*    renders its own "this is not a grid" state — a UI that exists to say it
+*    should not exist.
+*
+* `recording` is the precedent (`recorder/recording-device-settings.ts`):
+* returning `null` is how it keeps the Recording tab off a device that is not
+* a camera.
+*/
+import type { ConfigUISchema } from "@camstack/types";
 /** The widget id, registered in `ui-library`'s `HOST_WIDGETS`. */
 export declare const GRID_LAYOUT_WIDGET_ID = "host/camera-grid-layout";
 /**
- * The layout section, or `null` when this device is not a grid.
- *
- * `isGrid` is the ANSWER to "is this a grid", never "do we know yet". A caller
- * that cannot tell must not call this — an unresolved read rendered as `null`
- * would hide the editor from a real grid (D315).
- */
+* The layout section, or `null` when this device is not a grid.
+*
+* `isGrid` is the ANSWER to "is this a grid", never "do we know yet". A caller
+* that cannot tell must not call this — an unresolved read rendered as `null`
+* would hide the editor from a real grid (D315).
+*/
 export declare function buildGridDeviceSchema(isGrid: boolean): ConfigUISchema | null;

package/dist/builtins/camera-grid/grid-filter-graph.d.ts

@@ -1,53 +1,53 @@
 /**
- * The composite's geometry, as the `-filter_complex` the extended ffmpeg
- * primitive carries.
- *
- * ## Why normalized, and why not `deriveDetailCropRect`
- *
- * Both rectangles -- the crop taken OUT of a source and the cell it lands IN --
- * are normalized [0,1]. A source camera can change resolution under us (a
- * profile switch, a firmware update, a substream that comes back different) and
- * a rectangle stored in pixels would quietly start cutting the wrong part of
- * the picture, with nothing to say so.
- *
- * This deliberately does NOT go through `deriveDetailCropRect`. D52 -- "one
- * vector index = one crop derivation" -- protects the COMPARABILITY of a vector
- * index: every crop that feeds it must be cut the same way. This is
- * presentation, feeds no index, and routing it through that function would add
- * a second cutter to the one thing D52 exists to keep single.
- *
- * ## Why a canvas and overlays rather than stacks
- *
- * `hstack`/`vstack` only express a regular grid of equal tiles. The operator
- * composes *arbitrary* rectangles -- "a 16:9 from the middle of two streams" is
- * the case this was asked for -- so every cell is scaled and overlaid onto one
- * explicit canvas at its own origin. The canvas is also what makes a missing
- * cell legible: a gap is black, not a stretched neighbour.
- */
+* The composite's geometry, as the `-filter_complex` the extended ffmpeg
+* primitive carries.
+*
+* ## Why normalized, and why not `deriveDetailCropRect`
+*
+* Both rectangles -- the crop taken OUT of a source and the cell it lands IN --
+* are normalized [0,1]. A source camera can change resolution under us (a
+* profile switch, a firmware update, a substream that comes back different) and
+* a rectangle stored in pixels would quietly start cutting the wrong part of
+* the picture, with nothing to say so.
+*
+* This deliberately does NOT go through `deriveDetailCropRect`. D52 -- "one
+* vector index = one crop derivation" -- protects the COMPARABILITY of a vector
+* index: every crop that feeds it must be cut the same way. This is
+* presentation, feeds no index, and routing it through that function would add
+* a second cutter to the one thing D52 exists to keep single.
+*
+* ## Why a canvas and overlays rather than stacks
+*
+* `hstack`/`vstack` only express a regular grid of equal tiles. The operator
+* composes *arbitrary* rectangles -- "a 16:9 from the middle of two streams" is
+* the case this was asked for -- so every cell is scaled and overlaid onto one
+* explicit canvas at its own origin. The canvas is also what makes a missing
+* cell legible: a gap is black, not a stretched neighbour.
+*/
 /** A rectangle in normalized [0,1] coordinates of whatever contains it. */
 export interface NormalizedRect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
 }
 /** One source, the part of it taken, and where that part lands. */
 export interface GridCell {
-    /** Which ffmpeg input this cell reads — its ORDINAL among the invocation's inputs. */
-    readonly inputIndex: number;
-    /** The part of the source to take, normalized against the SOURCE. */
-    readonly source: NormalizedRect;
-    /** Where it lands, normalized against the CANVAS. */
-    readonly cell: NormalizedRect;
+	/** Which ffmpeg input this cell reads — its ORDINAL among the invocation's inputs. */
+	readonly inputIndex: number;
+	/** The part of the source to take, normalized against the SOURCE. */
+	readonly source: NormalizedRect;
+	/** Where it lands, normalized against the CANVAS. */
+	readonly cell: NormalizedRect;
 }
 export interface GridLayout {
-    /** Canvas size in pixels — the composite camera's own resolution. */
-    readonly width: number;
-    readonly height: number;
-    readonly cells: readonly GridCell[];
+	/** Canvas size in pixels — the composite camera's own resolution. */
+	readonly width: number;
+	readonly height: number;
+	readonly cells: readonly GridCell[];
 }
 export interface GridFilterGraph {
-    readonly graph: string;
-    readonly videoOutLabel: string;
+	readonly graph: string;
+	readonly videoOutLabel: string;
 }
 export declare function buildGridFilterGraph(layout: GridLayout): GridFilterGraph;