@camstack/system 1.2.390 → 1.2.392

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

@@ -1,50 +1,91 @@
-import { FrameResult, IEventBus, IScopedLogger } from '@camstack/types';
-import { GridMotionState } from './grid-activity-mirror.js';
-import { GridMappingCell } from './grid-detection-mapping.js';
+/**
+* The grid's own motion / audio / detection, forwarded from its sources.
+*
+* ## Why the grid speaks a camera's language instead of a new one
+*
+* The operator asked for the grid's tile to light up in the viewer exactly as a
+* camera's card does, with NO app change. The app already knows how: it filters
+* `motion.on-motion-changed` by `deviceId` for the motion ring,
+* `pipeline.audio-inference-result` for the audio one, and `detection.result`
+* for the detection one. So the grid answers those three questions about its
+* own device id, in the same shapes. Nothing new is invented, and nothing in
+* the viewer is touched.
+*
+* The rules are the operator's: motion if AT LEAST ONE source has it, and the
+* LOUDEST source's level for audio.
+*
+* ## What speaking a camera's language costs, and why it is safe here
+*
+* Those categories have other listeners, and emitting on them makes the grid a
+* motion source for the whole system. Checked, one by one, before shipping:
+* the recorder's event capture, the HomeKit and Alexa exports and the Home
+* Assistant export are all per-device and do nothing until an operator enables
+* them for this camera — and if an operator DOES export a grid to HomeKit, a
+* grid reporting motion is correct, not a surprise.
+*
+* The one listener with no gate of its own was `pipeline-analytics`, which
+* would have opened a motion EPISODE per grid, duplicating the rows its sources
+* already write. Its gate turned out to be the `pipeline-analytics` WRAPPER
+* BINDING, so the answer is the one the operator gave: a derived camera is
+* created with the analytics wrappers OFF (`grid-analytics-defaults.ts`).
+* That is a binding, not a new flag, so an operator who wants a grid analysed
+* can simply turn it back on.
+*
+* ## Detection carries boxes whether or not anyone wanted them
+*
+* `detection.result` is the same event the viewer draws BOXES from, so a grid
+* that reports detections reports boxes. Sending the source's own pixel box
+* would draw it against the composed canvas at confidently wrong coordinates,
+* so every box is carried through the cell geometry first
+* (`grid-detection-mapping.ts`) and lands where the subject actually is.
+*/
+import { type FrameResult, type IEventBus, type IScopedLogger } from "@camstack/types";
+import { type GridMotionState } from "./grid-activity-mirror.js";
+import { type GridMappingCell } from "./grid-detection-mapping.js";
 /** Everything this needs to know about one grid, re-read on every event. */
 export interface GridActivityTarget {
-    readonly deviceId: number;
-    readonly canvas: {
-        readonly width: number;
-        readonly height: number;
-    };
-    /** Every cell this source appears in. Empty ⇒ the grid does not show it. */
-    cellsForSource(sourceDeviceId: number): readonly GridMappingCell[];
-    /** Every source this grid composes, for the mirror's housekeeping. */
-    readonly sourceDeviceIds: readonly number[];
+	readonly deviceId: number;
+	readonly canvas: {
+		readonly width: number;
+		readonly height: number;
+	};
+	/** Every cell this source appears in. Empty ⇒ the grid does not show it. */
+	cellsForSource(sourceDeviceId: number): readonly GridMappingCell[];
+	/** Every source this grid composes, for the mirror's housekeeping. */
+	readonly sourceDeviceIds: readonly number[];
 }
 export interface GridActivityDeps {
-    readonly eventBus: IEventBus;
-    readonly logger: IScopedLogger;
-    readonly addonId: string;
-    /** The grids that contain this source, or empty. */
-    gridsForSource(sourceDeviceId: number): readonly GridActivityTarget[];
-    readonly now: () => number;
+	readonly eventBus: IEventBus;
+	readonly logger: IScopedLogger;
+	readonly addonId: string;
+	/** The grids that contain this source, or empty. */
+	gridsForSource(sourceDeviceId: number): readonly GridActivityTarget[];
+	readonly now: () => number;
 }
 /**
- * One mirror per grid, and the emission that follows an update.
- *
- * Deliberately NOT one mirror per source: the question is always "is THIS grid
- * lit", and a source shared by two grids answers it twice, differently, because
- * the other cells differ.
- */
+* One mirror per grid, and the emission that follows an update.
+*
+* Deliberately NOT one mirror per source: the question is always "is THIS grid
+* lit", and a source shared by two grids answers it twice, differently, because
+* the other cells differ.
+*/
 export declare class GridActivityForwarder {
-    private readonly deps;
-    private readonly mirrors;
-    constructor(deps: GridActivityDeps);
-    /** A source camera's motion push. */
-    onSourceMotion(sourceDeviceId: number, detected: boolean, atMs: number): void;
-    /** A source camera's audio window. */
-    onSourceAudio(sourceDeviceId: number, dbfs: number, atMs: number): void;
-    /** A source camera's detection frame, with its boxes in SOURCE pixels. */
-    onSourceDetections(frame: FrameResult): void;
-    /** The grid's own motion answer, for `motion.getStatus`. */
-    motionStatusFor(deviceId: number, nowMs: number): GridMotionState;
-    /** Drop the mirror of a grid that no longer exists. */
-    forget(deviceId: number): void;
-    private mirrorFor;
-    private source;
-    private emitMotion;
-    private emitAudio;
-    private emitDetections;
+	private readonly deps;
+	private readonly mirrors;
+	constructor(deps: GridActivityDeps);
+	/** A source camera's motion push. */
+	onSourceMotion(sourceDeviceId: number, detected: boolean, atMs: number): void;
+	/** A source camera's audio window. */
+	onSourceAudio(sourceDeviceId: number, dbfs: number, atMs: number): void;
+	/** A source camera's detection frame, with its boxes in SOURCE pixels. */
+	onSourceDetections(frame: FrameResult): void;
+	/** The grid's own motion answer, for `motion.getStatus`. */
+	motionStatusFor(deviceId: number, nowMs: number): GridMotionState;
+	/** Drop the mirror of a grid that no longer exists. */
+	forget(deviceId: number): void;
+	private mirrorFor;
+	private source;
+	private emitMotion;
+	private emitAudio;
+	private emitDetections;
 }

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

@@ -1,59 +1,59 @@
-import { GridInstance } from './grid-instances.js';
+import type { GridInstance } from "./grid-instances.js";
 /**
- * The stable id is `camera-grid-<instance uuid>` and NOTHING else.
- *
- * A stable id is permanent the instant it is minted: bindings, grid layouts in
- * other addons, recording rows, the timeline and this addon's own tombstones
- * all reference it, and a device whose stable id changes is a NEW camera with
- * an empty history. So it may only be derived from something that itself never
- * changes.
- *
- * The instance uuid is the only such thing here. Deriving it from the NAME
- * would rename-break every reference; deriving it from the CELLS would mint a
- * new camera every time the operator drags a rectangle — which is the entire
- * activity this addon exists for. Terminal learned the same lesson from the
- * other end: its original one-camera-per-node id is permanent, and its profile
- * migration had to ENRICH that row rather than mint a replacement.
- */
+* The stable id is `camera-grid-<instance uuid>` and NOTHING else.
+*
+* A stable id is permanent the instant it is minted: bindings, grid layouts in
+* other addons, recording rows, the timeline and this addon's own tombstones
+* all reference it, and a device whose stable id changes is a NEW camera with
+* an empty history. So it may only be derived from something that itself never
+* changes.
+*
+* The instance uuid is the only such thing here. Deriving it from the NAME
+* would rename-break every reference; deriving it from the CELLS would mint a
+* new camera every time the operator drags a rectangle — which is the entire
+* activity this addon exists for. Terminal learned the same lesson from the
+* other end: its original one-camera-per-node id is permanent, and its profile
+* migration had to ENRICH that row rather than mint a replacement.
+*/
 export declare function newGridCameraStableId(instanceId: string): string;
 /** The config a declared grid camera device carries. */
 export interface GridCameraConfig {
-    readonly instanceId: string;
-    /** `DeviceDeclaration.config` is an open record; this keeps the named type assignable. */
-    readonly [key: string]: unknown;
+	readonly instanceId: string;
+	/** `DeviceDeclaration.config` is an open record; this keeps the named type assignable. */
+	readonly [key: string]: unknown;
 }
 export interface GridCameraDeclaration {
-    readonly stableId: string;
-    readonly name: string;
-    readonly config: GridCameraConfig;
+	readonly stableId: string;
+	readonly name: string;
+	readonly config: GridCameraConfig;
 }
 export interface ExistingGridCameraRow {
-    readonly id: number;
-    readonly stableId: string;
-    readonly integrationId?: string | null;
-    readonly config: Readonly<Record<string, unknown>>;
+	readonly id: number;
+	readonly stableId: string;
+	readonly integrationId?: string | null;
+	readonly config: Readonly<Record<string, unknown>>;
 }
 /**
- * Explicit persisted instances only. A grid camera exists because an operator
- * created a grid, never because some source camera happens to exist.
- *
- * A grid with NO cells is declared like any other: creation is name-only and
- * the layout is authored afterwards in the camera's own device details, so
- * "no cells yet" is the normal first state, not an invalid row.
- */
+* Explicit persisted instances only. A grid camera exists because an operator
+* created a grid, never because some source camera happens to exist.
+*
+* A grid with NO cells is declared like any other: creation is name-only and
+* the layout is authored afterwards in the camera's own device details, so
+* "no cells yet" is the normal first state, not an invalid row.
+*/
 export declare function buildGridCameraDeclarations(instances: readonly GridInstance[]): readonly GridCameraDeclaration[];
 /**
- * The rows `DeclaredDevices` is allowed to consider — every live declaration
- * plus ONE bounded batch of orphans.
- *
- * Two guards, both copied from Terminal because both were paid for there:
- *
- * 1. **An unknown integration id yields an EMPTY index.** `null`/`undefined`
- *    means "the integration lookup has not answered", which is not the same
- *    fact as "this addon owns no rows" — and only the second one may drive a
- *    withdrawal.
- * 2. **The orphan batch is bounded and deterministically ordered.** The generic
- *    sweep refuses an over-limit set outright; selecting a batch here drains a
- *    large historical orphan set across passes without weakening that guard.
- */
+* The rows `DeclaredDevices` is allowed to consider — every live declaration
+* plus ONE bounded batch of orphans.
+*
+* Two guards, both copied from Terminal because both were paid for there:
+*
+* 1. **An unknown integration id yields an EMPTY index.** `null`/`undefined`
+*    means "the integration lookup has not answered", which is not the same
+*    fact as "this addon owns no rows" — and only the second one may drive a
+*    withdrawal.
+* 2. **The orphan batch is bounded and deterministically ordered.** The generic
+*    sweep refuses an over-limit set outright; selecting a batch here drains a
+*    large historical orphan set across passes without weakening that guard.
+*/
 export declare function gridCameraReconciliationIndex(rows: readonly ExistingGridCameraRow[], integrationId: string | null | undefined, declarations: readonly GridCameraDeclaration[], managedStableIds?: ReadonlySet<string>): readonly ExistingGridCameraRow[];

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

@@ -1,42 +1,68 @@
-import { BaseDevice, CamStreamDescriptor, DeviceContext, DeviceFeature, GridLayoutPatch, GridLayoutView, MotionStatus } from '@camstack/types';
-import { z } from 'zod';
-import { GridSnapshotImage } from './grid-snapshot.js';
+/**
+* The composite camera device.
+*
+* An ORDINARY camera in every respect the rest of the system can see: it
+* records, it appears in the timeline, it has profile slots, it is bound like
+* any other. What makes it a grid is invisible from here — its streams are
+* composed rather than dialled, and object detection is switched off at
+* CREATION (see `silence-analysis.ts`), never re-asserted.
+*
+* ## The three native caps, and why each is native
+*
+* - **`stream-catalog`** — what this grid OFFERS, one descriptor per profile it
+*   can honestly compose. Named on every pull, idle included: the broker sweeps
+*   anything its registry holds that a catalog does not name.
+* - **`camera-grid-layout`** — the geometry, on the camera's own page. Device
+*   scoped so the widget asks THE CAMERA; the addon-scoped custom actions it
+*   replaces could only be reached by a caller that already knew the addon id,
+*   which is why the editor rendered nowhere.
+* - **`snapshot`** — a frame of the composition. It used to be deliberately
+*   ABSENT, on the reasoning that the broker's ordinary grab takes one from the
+*   profile slot and taking one IS a consumer. That is true and it is the
+*   defect: it means a thumbnail in a list starts N decodes, and on a battery
+*   source it would be a wake. A native provider runs BEFORE that grab and
+*   answers from the live composition or from the frame it kept
+*   (`grid-snapshot.ts`).
+*/
+import { BaseDevice, type CamStreamDescriptor, type DeviceContext, DeviceFeature, type GridLayoutPatch, type GridLayoutView, type MotionStatus } from "@camstack/types";
+import { z } from "zod";
+import type { GridSnapshotImage } from "./grid-snapshot.js";
 declare const gridCameraSchema: z.ZodObject<{
-    instanceId: z.ZodString;
-}, z.core.$strip>;
+	instanceId: z.ZodString;
+}>;
 /**
- * What the device needs from the running addon. Installed as a module
- * singleton, like the Terminal camera's relay: `DeclaredDevices` constructs
- * devices, so a device cannot be handed a constructor dependency.
- */
+* What the device needs from the running addon. Installed as a module
+* singleton, like the Terminal camera's relay: `DeclaredDevices` constructs
+* devices, so a device cannot be handed a constructor dependency.
+*/
 export interface GridCameraRuntime {
-    /**
-     * The catalog descriptors for this grid — one per OFFERED profile — or `null`
-     * when the addon cannot say. `null` is a REFUSAL to describe, never an empty
-     * catalog with a shrug: see the note on the empty branch below.
-     */
-    descriptorsFor(instanceId: string): readonly CamStreamDescriptor[] | null;
-    /** The grid behind a device, or `null` — which means "answered: not a grid". */
-    getLayout(deviceId: number): GridLayoutView | null;
-    saveLayout(patch: GridLayoutPatch): Promise<GridLayoutView>;
-    /** A frame of the composition, or `null`. Never starts one. */
-    getSnapshot(deviceId: number): Promise<GridSnapshotImage | null>;
-    /**
-     * This grid's own motion, derived from its sources (`grid-activity-mirror`).
-     *
-     * The device answers `motion.getStatus` from it because the VIEWER polls that
-     * as its backstop — it subscribes to `motion.on-motion-changed` and polls the
-     * status in case an event was missed. A grid that emitted the event but could
-     * not answer the poll would light up and then, on any dropped edge, be
-     * unrecoverably dark until the next one.
-     */
-    motionStatus(deviceId: number): MotionStatus;
+	/**
+	* The catalog descriptors for this grid — one per OFFERED profile — or `null`
+	* when the addon cannot say. `null` is a REFUSAL to describe, never an empty
+	* catalog with a shrug: see the note on the empty branch below.
+	*/
+	descriptorsFor(instanceId: string): readonly CamStreamDescriptor[] | null;
+	/** The grid behind a device, or `null` — which means "answered: not a grid". */
+	getLayout(deviceId: number): GridLayoutView | null;
+	saveLayout(patch: GridLayoutPatch): Promise<GridLayoutView>;
+	/** A frame of the composition, or `null`. Never starts one. */
+	getSnapshot(deviceId: number): Promise<GridSnapshotImage | null>;
+	/**
+	* This grid's own motion, derived from its sources (`grid-activity-mirror`).
+	*
+	* The device answers `motion.getStatus` from it because the VIEWER polls that
+	* as its backstop — it subscribes to `motion.on-motion-changed` and polls the
+	* status in case an event was missed. A grid that emitted the event but could
+	* not answer the poll would light up and then, on any dropped edge, be
+	* unrecoverably dark until the next one.
+	*/
+	motionStatus(deviceId: number): MotionStatus;
 }
 export declare function installGridCameraRuntime(next: GridCameraRuntime | null): void;
 export declare class GridCameraDevice extends BaseDevice<typeof gridCameraSchema> {
-    readonly features: readonly DeviceFeature[];
-    constructor(ctx: DeviceContext);
-    private catalog;
-    setAddonOnline(online: boolean): void;
+	readonly features: readonly DeviceFeature[];
+	constructor(ctx: DeviceContext);
+	private catalog;
+	setAddonOnline(online: boolean): void;
 }
 export {};

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

@@ -1,19 +1,54 @@
-import { PixelSize } from './grid-canvas.js';
-import { NormalizedRect } from './grid-filter-graph.js';
+/**
+* The canvas is a RESULT, not a field.
+*
+* ## Why the operator stopped typing it
+*
+* A grid's resolution used to be two numbers in the editor, beside FPS. They
+* looked harmless and were not: that number silently decided how much the
+* composite cost and how sharp it was. An operator typing 1920x1080 was, without
+* being told, committing the hub to reading two 4 MP streams — or, with the
+* rule before it, to upscaling a 640x360 sub-stream by 3x. Neither is a thing
+* anyone can be expected to work out from a text field.
+*
+* ## What it is derived from
+*
+* The operator draws two rectangles per camera — which part of the source to
+* take, and where it lands — and both are fractions, so nothing is pixels yet.
+* Exactly one number is missing: how many pixels the whole canvas is worth.
+*
+* A cell has `sourceResolution x crop` REAL pixels behind it. Showing them 1:1
+* neither invents nor discards anything, so the cell should be exactly that
+* many pixels — and since the cell is a fraction `f` of the canvas, the canvas
+* it implies is `real / f`. Each cell proposes one, and the LARGEST wins: the
+* hungriest cell is served 1:1 and the others scale down by a hair, never up.
+*
+* Gaps change nothing. Cells need not cover the canvas, and an uncovered part
+* is background — it has no pixels to propose.
+*
+* ## One per profile
+*
+* A source is a different size at each profile, so each profile derives its own
+* canvas: a grid's `low` composes its sources' `low` onto the canvas their
+* `low` implies. That is what makes the three outputs 1:1 with what they are
+* made of, and what lets a viewer's adaptive pick a rung without the grid
+* needing to know it exists.
+*/
+import { type PixelSize } from "./grid-canvas.js";
+import type { NormalizedRect } from "./grid-filter-graph.js";
 export interface GridCanvasCell {
-    /** 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 source's size AT THE PROFILE being derived for. */
-    readonly sourceSize: PixelSize;
+	/** 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 source's size AT THE PROFILE being derived for. */
+	readonly sourceSize: PixelSize;
 }
 /**
- * The canvas these cells imply, or `null` when they imply none.
- *
- * `null` for a grid with no cells — the normal freshly-created state — and for
- * a layout whose every rectangle is degenerate. Both are "there is no picture
- * to size", which the caller turns into "this profile is not on offer" rather
- * than into a guess.
- */
+* The canvas these cells imply, or `null` when they imply none.
+*
+* `null` for a grid with no cells — the normal freshly-created state — and for
+* a layout whose every rectangle is degenerate. Both are "there is no picture
+* to size", which the caller turns into "this profile is not on offer" rather
+* than into a guess.
+*/
 export declare function deriveGridCanvas(cells: readonly GridCanvasCell[]): PixelSize | null;

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

@@ -1,62 +1,112 @@
-import { PixelOrigin, PixelSize } from './grid-canvas.js';
-import { GridTilePlan } from './grid-tile-plan.js';
 /**
- * The word a card carries. Deliberately not a fault: nothing has arrived YET,
- * which is true of a camera that is slow and of one that is broken, and this
- * placeholder knows which it is for neither.
- */
+* What the canvas SAYS before a single camera has delivered a frame.
+*
+* ## Why black was not good enough
+*
+* The compositor emits from its very first tick (`grid-compositor.ts`) — that
+* is the whole point of a canvas, and it is what removed the ~9 s cold start.
+* But what it emitted until now was black, and black is the same picture for
+* four different situations: a grid with no cells, a grid whose sources are all
+* broken, a grid whose sources are merely slow, and a viewer that connected to
+* the wrong camera. An operator cannot tell them apart, and the one they
+* actually hit — sources still opening — is the one that fixes itself.
+*
+* The seed paints the LAYOUT instead: one card per cell, at the cell's own
+* rectangle, carrying the camera's name and the word `Waiting`. Three states
+* become three pictures — "no cards" is an empty grid, "a card still there" is
+* a tile that has not arrived, and "a picture" is a tile that has.
+*
+* It is honest about what it is. It is not a stand-in picture of the camera,
+* and it never carries a state it has not been told (a tile whose source is
+* genuinely broken is a matter for the tile's own decoder and its logs — this
+* says only "nothing has arrived here yet", which is true of both).
+*
+* ## Drawn ONCE, before the tick exists
+*
+* The seed is a full-canvas frame blitted in at the compositor's construction,
+* so the first tick already carries it and the tick never waits on anything.
+* Rendering it is the only asynchronous part, and it happens BEFORE the
+* compositor is built — never on the tick, which serves every cell.
+*
+* ## Why SVG → sharp, and why the conversion is here
+*
+* `snapshot-courtesy.ts` already renders text this way and states the reason:
+* shelling out to ffmpeg's `drawtext` was 52 ms against sharp's 4.8 ms, and an
+* SVG names a font FAMILY that fontconfig resolves instead of a font PATH that
+* has to be probed. This is that pattern, not a second one.
+*
+* What is different is the output. The canvas is yuv420p — that is what makes a
+* blit a strided memcpy — and sharp has no yuv output, so the raster is
+* converted once, here, by `rgbToYuv420p`. Once per composition start, over a
+* frame that is already being allocated; never per tick.
+*
+* ## Even, like everything else that touches the canvas
+*
+* The cards are the TILES' own rectangles, which `buildGridTilePlan` has
+* already snapped to even pixels — yuv420p subsamples chroma 2×2, and an odd
+* rectangle tints a tile rather than breaking it. Nothing here re-derives a
+* rectangle; it copies the one the decoder was sized against, so a card cannot
+* land anywhere other than exactly where its picture will.
+*/
+import { type PixelOrigin, type PixelSize } from "./grid-canvas.js";
+import type { GridTilePlan } from "./grid-tile-plan.js";
+/**
+* The word a card carries. Deliberately not a fault: nothing has arrived YET,
+* which is true of a camera that is slow and of one that is broken, and this
+* placeholder knows which it is for neither.
+*/
 export declare const GRID_SEED_WAITING_LABEL = "Waiting";
 export interface GridSeedCell {
-    readonly origin: PixelOrigin;
-    readonly size: PixelSize;
-    /** What the card is labelled with — a camera name, or its id. */
-    readonly name: string;
+	readonly origin: PixelOrigin;
+	readonly size: PixelSize;
+	/** What the card is labelled with — a camera name, or its id. */
+	readonly name: string;
 }
 export interface GridSeedSpec {
-    readonly canvas: PixelSize;
-    readonly cells: readonly GridSeedCell[];
+	readonly canvas: PixelSize;
+	readonly cells: readonly GridSeedCell[];
 }
 /**
- * The label for one source.
- *
- * A name we could not read is not a reason to paint an anonymous rectangle: the
- * DEVICE ID is what every log line about that tile carries, so it is the one
- * label an operator can act on. A blank or whitespace name is treated as no
- * name for the same reason.
- */
+* The label for one source.
+*
+* A name we could not read is not a reason to paint an anonymous rectangle: the
+* DEVICE ID is what every log line about that tile carries, so it is the one
+* label an operator can act on. A blank or whitespace name is treated as no
+* name for the same reason.
+*/
 export declare function gridSeedName(names: ReadonlyMap<number, string>, deviceId: number): string;
 /**
- * The seed a tile plan implies — pure, and the plan is the ONLY input to the
- * geometry. A card is its tile's rectangle, never a recomputed one.
- */
+* The seed a tile plan implies — pure, and the plan is the ONLY input to the
+* geometry. A card is its tile's rectangle, never a recomputed one.
+*/
 export declare function buildGridSeedSpec(plan: GridTilePlan, names: ReadonlyMap<number, string>): GridSeedSpec;
 /**
- * The document the seed is rasterized from.
- *
- * No full-bleed background: the uncovered part of a canvas is NOT a cell — the
- * cells need not cover it (`grid-canvas-derivation.ts`) — and painting a card's
- * treatment over it would say "waiting" about a tile that does not exist. It
- * stays the canvas' own black.
- *
- * Each card clips its own text. A camera named for a whole street would
- * otherwise spill across the cell next to it, and a label on the wrong tile is
- * worse than a truncated one.
- */
+* The document the seed is rasterized from.
+*
+* No full-bleed background: the uncovered part of a canvas is NOT a cell — the
+* cells need not cover it (`grid-canvas-derivation.ts`) — and painting a card's
+* treatment over it would say "waiting" about a tile that does not exist. It
+* stays the canvas' own black.
+*
+* Each card clips its own text. A camera named for a whole street would
+* otherwise spill across the cell next to it, and a label on the wrong tile is
+* worse than a truncated one.
+*/
 export declare function buildGridSeedSvg(spec: GridSeedSpec): string;
 /**
- * Packed RGB → yuv420p, once.
- *
- * Chroma is the average of each 2×2 block's colour, converted once per block —
- * which is what 4:2:0 means, and what keeps a card's border from fringing.
- * Sizes must be even; the canvas refuses anything else, so a caller that got
- * here with an odd size has a bug the blit would hide.
- */
+* Packed RGB → yuv420p, once.
+*
+* Chroma is the average of each 2×2 block's colour, converted once per block —
+* which is what 4:2:0 means, and what keeps a card's border from fringing.
+* Sizes must be even; the canvas refuses anything else, so a caller that got
+* here with an odd size has a bug the blit would hide.
+*/
 export declare function rgbToYuv420p(rgb: Buffer, size: PixelSize): Buffer;
 /**
- * Render the seed as one yuv420p frame the canvas can take whole.
- *
- * Rejects on failure rather than answering black: the caller decides, and it
- * decides to carry on without a seed — a grid that would not start because its
- * placeholder would not draw is a worse grid than one that starts black.
- */
+* Render the seed as one yuv420p frame the canvas can take whole.
+*
+* Rejects on failure rather than answering black: the caller decides, and it
+* decides to carry on without a seed — a grid that would not start because its
+* placeholder would not draw is a worse grid than one that starts black.
+*/
 export declare function renderGridSeed(spec: GridSeedSpec): Promise<Buffer>;