@camstack/system 1.2.254 → 1.2.256

package/dist/builtins/autotrack/ptz-mirror.d.ts

@@ -0,0 +1,25 @@
+import { NativeAutotrackState } from './autotrack-decision.js';
+export interface PtzMirror {
+    /** `ptz.getOptions().moveImpulseMs`. `null` = never read, or the driver
+     *  itself reports it cannot say. */
+    readonly moveImpulseMs: number | null;
+    readonly nativeAutotrack: NativeAutotrackState;
+    /** When a refresh last SUCCEEDED. `null` = never. */
+    readonly lastRefreshAtMs: number | null;
+    /** Message of the last failed refresh, `null` once one succeeds again. */
+    readonly lastError: string | null;
+    /** Consecutive failed refreshes since the last success. */
+    readonly consecutiveFailures: number;
+}
+export declare const INITIAL_PTZ_MIRROR: PtzMirror;
+/** What one refresh attempt found. A `failed` outcome carries a reason —
+ *  there is no silent failure shape. */
+export type MirrorRefreshOutcome = {
+    readonly kind: 'read';
+    readonly moveImpulseMs: number | null;
+    readonly nativeAutotrack: NativeAutotrackState;
+} | {
+    readonly kind: 'failed';
+    readonly error: string;
+};
+export declare function applyMirrorRefresh(mirror: PtzMirror, outcome: MirrorRefreshOutcome, nowMs: number): PtzMirror;

package/dist/builtins/autotrack/target-selection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Sticky target choice: pick ONE track, then stay on it.
+ *
+ * Re-picking "the best candidate" every frame is oscillation on another axis —
+ * two people a metre apart trade the top score frame to frame and the head
+ * saws between them, having centred neither. So the target is chosen ONCE and
+ * held by `trackId` until it has been gone for the disappear delay. While it
+ * is merely MISSING from a frame nothing is switched and nothing is released:
+ * `present: false` is reported and the decision layer decides what a gap means.
+ *
+ * Pure: state in, state out, no clock read inside — `nowMs` is passed. A new
+ * state object is returned every call; the input is never mutated.
+ */
+/** One candidate of the configured class on this frame. */
+export interface TargetCandidate {
+    readonly trackId: string;
+    /** Pixel area of the box. Used ONLY to break the first choice; it never
+     *  unseats a target that is still alive. */
+    readonly areaPx: number;
+}
+export interface TargetSelectionState {
+    /** The track being followed, or `null` when nothing is held. */
+    readonly trackId: string | null;
+    /** When that track was last OBSERVED on a frame. `null` while nothing is
+     *  held. Never advanced by a frame the track was absent from. */
+    readonly lastSeenAtMs: number | null;
+}
+export declare const INITIAL_TARGET_SELECTION_STATE: TargetSelectionState;
+/** Why the selection came out the way it did — logged on every frame so a
+ *  loop that chooses nothing is distinguishable from a loop that is dead. */
+export type TargetSelectionReason = 
+/** The held track was observed on this frame. */
+'held'
+/** The held track was absent from this frame but is still within its
+ *  disappear delay — nothing is switched, nothing is released. */
+ | 'held-absent'
+/** The held track exceeded its disappear delay and was released; no
+ *  candidate was available to take its place. */
+ | 'released'
+/** The held track was released and a new one was picked on the same frame. */
+ | 'switched'
+/** Nothing was held and a candidate was picked. */
+ | 'acquired'
+/** Nothing was held and no candidate was available. */
+ | 'idle';
+export interface TargetSelectionResult {
+    readonly state: TargetSelectionState;
+    /** The held track, after this frame. `null` when nothing is held. */
+    readonly trackId: string | null;
+    /** Whether the held track was OBSERVED on this frame. This is the boolean
+     *  the absence measurement counts. */
+    readonly present: boolean;
+    readonly reason: TargetSelectionReason;
+}
+export interface TargetSelectionInput {
+    readonly nowMs: number;
+    readonly candidates: readonly TargetCandidate[];
+    readonly disappearDelayMs: number;
+}
+export declare function selectTarget(state: TargetSelectionState, input: TargetSelectionInput): TargetSelectionResult;

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CnQsUe15.js");
+const require_dist = require("../../dist-BJj6Akye.js");
 let node_crypto = require("node:crypto");
 let buffer = require("buffer");
 let node_fs_promises = require("node:fs/promises");

package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Cn as EventCategory, F as backupCapability, Ut as storageOccupancyCapability, Zt as BaseAddon, xt as mayWriteToLocation } from "../../dist-BhTy3CUQ.mjs";
+import { Dt as mayWriteToLocation, Nn as EventCategory, Xt as storageOccupancyCapability, on as BaseAddon, z as backupCapability } from "../../dist-Ch93tyHB.mjs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "buffer";
 import * as fsp from "node:fs/promises";

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

@@ -0,0 +1,118 @@
+import { AddonInitResult, ConfigUISchema, DeviceProxy, BaseAddon } from '@camstack/types';
+interface CameraGridAddonConfig {
+    /** Operator-written rows. Name only on creation; geometry is added later. */
+    readonly cameraGrids: readonly Record<string, unknown>[];
+    /** Durable deletion intent, so a removed grid is not re-adopted by a sweep. */
+    readonly cameraGridTombstones: readonly string[];
+}
+export declare class CameraGridAddon extends BaseAddon<CameraGridAddonConfig> {
+    private relay;
+    private reconcileTimer;
+    /** Keyed by {@link sessionKey} — one composition per grid per profile. */
+    private readonly sessions;
+    private readonly deviceIdByInstanceId;
+    private readonly tombstones;
+    /**
+     * What each grid can honestly publish, per profile.
+     *
+     * ABSENT means "not asked yet", and it is a REFUSAL to describe — the device
+     * throws rather than answering an empty catalog, because an empty catalog
+     * retracts every stream the broker holds for the grid. It is refreshed on
+     * every reconcile and on every layout save; the window belongs to the READER
+     * (D224), and 60 s is the window for a fact — "does 615 have a low assigned"
+     * — that only changes when an operator changes it.
+     */
+    private readonly offersByInstanceId;
+    private snapshots;
+    private frameSampler;
+    private ffmpegBinaryPath;
+    private integrationId;
+    constructor();
+    protected onInitialize(): Promise<AddonInitResult>;
+    protected onConfigChanged(): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    private instances;
+    private instanceById;
+    /**
+     * Fill in everything a name-only row is missing, and persist if it changed.
+     *
+     * Without this a freshly typed row is unparseable, and `readGridInstances`
+     * IGNORES what it cannot parse — so creation would silently do nothing.
+     */
+    private normalizeRows;
+    private replaceTombstones;
+    private reconcile;
+    private silenceAnalysis;
+    /**
+     * Which profiles each grid can honestly publish, asked of the BROKER.
+     *
+     * `listAllProfileSlots` is the one authority on "does 615 have a low
+     * assigned", and `sourceCamStreamId === null` is its way of saying no. A read
+     * that FAILS leaves the previous answer in place and says so - it is not an
+     * empty catalog, and turning it into one would retract the streams of every
+     * grid on the hub.
+     */
+    private refreshProfileOffers;
+    /**
+     * Say which profiles this grid will NOT publish, and why - once per change.
+     *
+     * A profile silently missing from a catalog is indistinguishable from a
+     * broker that swept it. Logged on the EDGE rather than every minute: a grid
+     * that can only serve `high` would otherwise write two lines a minute for
+     * ever.
+     */
+    private logRefusals;
+    private offeredProfiles;
+    private ensureSessions;
+    private makeSession;
+    /** The session a dial is asking for, or `null` - which the relay answers 404 to. */
+    private sessionFor;
+    /** This grid's sessions, in DESCENDING quality - the snapshot takes the first running one. */
+    private sessionsForDevice;
+    /** A grid that is gone stops immediately - it must not keep N sources dialled. */
+    private retireWithdrawnSessions;
+    /**
+     * A geometry change is a NEW composition. The running child is composing the
+     * old one, and ffmpeg has no way to be told otherwise, so it is stopped: the
+     * consumer's next read re-dials and gets the new picture.
+     */
+    private applyLayoutChanges;
+    private getSnapshot;
+    /**
+     * One frame out of a composition that is ALREADY running.
+     *
+     * `openIfRunning` is the whole guarantee: it refuses a cold session, so a
+     * thumbnail can never be the reason N sources get acquired. A grid that is
+     * not being watched has no fresh frame, and that is the honest answer.
+     */
+    private sampleFrame;
+    /**
+     * Every stream this grid offers, or `null` when the addon cannot say.
+     *
+     * `null` is a refusal to describe and the device turns it into a THROW. An
+     * empty array would be the broker reading "this camera offers nothing" and
+     * sweeping every stream it holds for the grid.
+     */
+    private descriptorsFor;
+    private instanceIdForDevice;
+    private instanceForDevice;
+    private gridViewFor;
+    private saveGridLayout;
+    private resolveFfmpegBinaryPath;
+    /**
+     * The integration page: a list of grids, with a NAME.
+     *
+     * Deliberately nothing else. A generated form for the geometry would render
+     * "cell 1 source = 592, cell 1 crop x = 0.25" and be unusable, so the
+     * geometry lives in a WIDGET on the camera's own device details, declared by
+     * the `camera-grid-layout` CAPABILITY (`camera-grid-layout.cap.ts`). It used
+     * to be a `type:'widget'` field in this addon's own `deviceSettingsSchema()`
+     * and it rendered NOWHERE: that section is only fetched for the four addons
+     * hand-listed in `PIPELINE_CLUSTER_DEVICE_ADDONS`, and an addon not on the
+     * list falls off silently. A cap-declared widget is placed by the framework,
+     * on the camera, beside PTZ and motion zones.
+     */
+    protected globalSettingsSchema(): ConfigUISchema;
+    protected integrationSettingSections(): readonly string[];
+}
+export type { DeviceProxy };

package/dist/builtins/camera-grid/flv-join.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Making one FLV stream joinable by many readers.
+ *
+ * MPEG-TS is self-describing: a reader attaches mid-stream, waits for the next
+ * PAT/PMT and decodes. FLV is not. Its 9-byte signature, its `onMetaData`
+ * script tag and its AVC sequence header appear ONCE, at the top, and a reader
+ * that arrives later is handed the middle of a tag — ffmpeg answers `Invalid
+ * data found when processing input`, which is exactly what the hub did the
+ * minute the grid started emitting FLV (2026-09-17). The grid emits FLV because
+ * the bundled ffmpeg segfaults remuxing MPEG-TS (D519 notes, same day), so the
+ * format is not negotiable and this is the price of it.
+ *
+ * The join point therefore does two things, and nothing else:
+ *
+ *  - **remembers what describes the stream** — the header, the newest script
+ *    tag, the newest AVC sequence header. Newest, not first: an encoder that
+ *    respawns emits a new sequence header, and a reader handed the old one
+ *    decodes noise;
+ *  - **starts each reader on a tag boundary at a KEYFRAME**, never mid-tag and
+ *    never on an inter frame that references pictures the reader never saw.
+ *
+ * It is a parser, not a buffer: nothing is retained beyond the preamble and the
+ * partial tag currently being assembled. A composite at 10 fps with a 2-second
+ * GOP makes a reader wait at most two seconds to join, which is the same wait
+ * MPEG-TS would have imposed for its next key frame.
+ */
+interface MutableReader {
+    started: boolean;
+    queued: Buffer[];
+}
+/**
+ * One reader's view of the stream.
+ *
+ * Every consumer holds one, the first included: a join point with a privileged
+ * "primary" reader would have two code paths for the same question, and the
+ * grid's first consumer is not special — it just happens to arrive when the
+ * preamble is still being learnt.
+ */
+export declare class FlvReader {
+    private readonly state;
+    private readonly detach;
+    constructor(state: MutableReader, detach: (state: MutableReader) => void);
+    /** True until the preamble and a key frame have been handed over. */
+    get pending(): boolean;
+    /** The bytes owed to this reader since the last call, or `null`. */
+    take(): Buffer | null;
+    /** Stop receiving. Anything queued is dropped with the reader. */
+    close(): void;
+}
+export declare class FlvJoinPoint {
+    private buffer;
+    private header;
+    private script;
+    private sequenceHeader;
+    private readonly readers;
+    /** Attach a reader. It receives the preamble at the next key frame. */
+    join(): FlvReader;
+    /** Feed bytes from the encoder; each reader then takes what it is owed. */
+    accept(chunk: Buffer): void;
+    private consumeHeader;
+    private consumeTags;
+    private dispatch;
+    /** The bytes that describe the stream, or `null` while any is still unknown. */
+    private preamble;
+}
+export {};

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

@@ -0,0 +1,59 @@
+import { 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.
+ */
+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;
+}
+export interface GridCameraDeclaration {
+    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>>;
+}
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,32 @@
+import { BaseDevice, CamStreamDescriptor, DeviceContext, DeviceFeature, GridLayoutPatch, GridLayoutView } from '@camstack/types';
+import { z } from 'zod';
+import { GridSnapshotImage } from './grid-snapshot.js';
+declare const gridCameraSchema: z.ZodObject<{
+    instanceId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 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>;
+}
+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;
+}
+export {};

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

@@ -0,0 +1,9 @@
+import { IScopedLogger } from '@camstack/types';
+import { 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;
+}
+export declare function startGridChild(ctx: GridChildContext, plan: GridStreamPlan, sources: readonly GridSourceHandle[], onEnded: (reason: string) => void): Promise<GridStreamChild>;

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

@@ -0,0 +1,11 @@
+import { 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).
+ */
+export declare function buildGridDeviceSchema(isGrid: boolean): ConfigUISchema | null;

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

@@ -0,0 +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.
+ */
+/** 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;
+}
+/** 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;
+}
+export interface GridLayout {
+    /** 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;
+}
+export declare function buildGridFilterGraph(layout: GridLayout): GridFilterGraph;

package/dist/builtins/camera-grid/grid-frame-sample.d.ts

@@ -0,0 +1,27 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { GridStreamLogger } from './grid-stream-session.js';
+export type GridSpawn = typeof nodeSpawn;
+export interface GridFrameSamplerOptions {
+    readonly binaryPath: string;
+    readonly logger: GridStreamLogger;
+    readonly timeoutMs?: number;
+    /** Injectable for tests. */
+    readonly spawnFn?: GridSpawn;
+}
+/** How a caller feeds the sampler: it hands over chunks and a way to stop. */
+export interface GridFrameSource {
+    /** Start receiving MPEG-TS chunks. Returns the handle that stops them. */
+    attach(onChunk: (chunk: Buffer) => void): {
+        close(): void;
+    } | null;
+}
+export declare class GridFrameSampler {
+    private readonly options;
+    constructor(options: GridFrameSamplerOptions);
+    /**
+     * @returns the JPEG, or `null` — a grab that produced nothing, could not be
+     * attached, or ran out of time. Every one of those is logged with the
+     * device: a branch that accepts the request and produces nothing must say so.
+     */
+    sample(deviceId: number, source: GridFrameSource): Promise<Buffer | null>;
+}

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

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * One source camera, the part of its picture taken, and where that part lands
+ * on the composite's canvas. Both rectangles are NORMALIZED so a source that
+ * changes resolution does not silently start cutting the wrong region.
+ */
+declare const GridCellSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    source: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    cell: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type GridCellConfig = z.infer<typeof GridCellSchema>;
+declare const GridInstanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    cameraStableId: z.ZodString;
+    name: z.ZodString;
+    enabled: z.ZodBoolean;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    fps: z.ZodNumber;
+    cells: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        source: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        cell: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type GridInstance = z.infer<typeof GridInstanceSchema>;
+export declare function readGridInstances(raw: readonly Record<string, unknown>[], onInvalid?: (message: string) => void): readonly GridInstance[];
+export {};

package/dist/builtins/camera-grid/grid-last-frame-store.d.ts

@@ -0,0 +1,19 @@
+import { GridLastFrameStore } from './grid-snapshot.js';
+export interface GridLastFrameFileStoreOptions {
+    /** `ctx.dataDir` — the addon's exclusive directory. */
+    readonly dataDir: string;
+    readonly minIntervalMs?: number;
+    /** Injectable for tests; `Date.now` otherwise. */
+    readonly now?: () => number;
+}
+export declare class GridLastFrameFileStore implements GridLastFrameStore {
+    private readonly dir;
+    private readonly minIntervalMs;
+    private readonly now;
+    /** Last write per device, so the throttle survives without touching disk. */
+    private readonly lastWriteMs;
+    constructor(options: GridLastFrameFileStoreOptions);
+    put(deviceId: number, jpeg: Buffer): Promise<void>;
+    get(deviceId: number): Promise<Buffer | null>;
+    private pathFor;
+}

package/dist/builtins/camera-grid/grid-layout-native-provider.d.ts

@@ -0,0 +1,8 @@
+import { GridLayoutPatch, GridLayoutView, ICameraGridLayoutSettingsProvider } from '@camstack/types';
+/** What the provider needs from the running addon — nothing more. */
+export interface GridLayoutSource {
+    /** The grid behind a device, or `null` — "answered: not a grid". */
+    getLayout(deviceId: number): GridLayoutView | null;
+    saveLayout(patch: GridLayoutPatch): Promise<GridLayoutView>;
+}
+export declare function buildGridLayoutNativeProvider(source: GridLayoutSource): ICameraGridLayoutSettingsProvider;

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

@@ -0,0 +1,22 @@
+import { FfmpegVideoEncoderId } from '@camstack/types';
+import { GridInstance } from './grid-instances.js';
+import { GridStreamPlan } from './grid-stream-session.js';
+export interface GridPlanEncodeContext {
+    readonly encoder: FfmpegVideoEncoderId;
+    readonly decodeHwAccel: string | null;
+    /**
+     * The canvas to compose onto, when it is not the one the operator laid out.
+     *
+     * A grid publishes one composition per profile, and `mid`/`low` compose onto
+     * a SCALED copy of the operator's canvas (`grid-profiles.ts` owns the
+     * scale). The geometry needs no second version of itself: every rectangle is
+     * normalized on both sides (D519), so the same fractions land correctly on a
+     * smaller picture. Absent ⇒ the operator's own canvas, which is `high`.
+     */
+    readonly canvas?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** `null` when the grid has nothing to compose — the normal freshly-created state. */
+export declare function gridPlanFor(instance: GridInstance, encode: GridPlanEncodeContext): GridStreamPlan | null;

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

@@ -0,0 +1,47 @@
+import { CamProfile } from '@camstack/types';
+/**
+ * One id, for every grid, forever — for the HIGH composition.
+ *
+ * D519's reason still holds and is what keeps this id bare: a per-instance or
+ * newly-spelled id mints a second cam-stream and orphans whatever profile
+ * assignment the operator had made. `grid` was `high` on the live hub before
+ * this change, so `high` keeps it and the other two are new.
+ */
+export declare const GRID_CAM_STREAM_ID = "grid";
+/** Every profile a grid could conceivably compose, in descending quality. */
+export declare const GRID_PROFILES: readonly CamProfile[];
+export interface GridCanvas {
+    readonly width: number;
+    readonly height: number;
+}
+/** The cam-stream id a grid publishes for one profile. */
+export declare function gridCamStreamId(profile: CamProfile): string;
+/** Even, floored, scaled by the profile. libx264 refuses an odd dimension. */
+export declare function gridCanvasFor(canvas: GridCanvas, profile: CamProfile): GridCanvas;
+export interface OfferedGridProfilesInput {
+    /** Every camera the composition takes a cell from, deduplicated. */
+    readonly sourceDeviceIds: readonly number[];
+    /**
+     * Which profiles this source can serve, or `null` when nobody could say.
+     * `null` is not an empty list: an unanswerable question is a refusal, and
+     * saying so separately is what keeps "we did not ask" out of the catalog.
+     */
+    readonly profilesServedBy: (deviceId: number) => readonly CamProfile[] | null;
+}
+export type GridProfileOffer = {
+    readonly profile: CamProfile;
+    readonly offered: true;
+} | {
+    readonly profile: CamProfile;
+    readonly offered: false;
+    /** The sources that could not serve it. Empty only when there are none at all. */
+    readonly missingSources: readonly number[];
+};
+/**
+ * What this grid can honestly publish, per profile, with the refusal named.
+ *
+ * Every profile gets a row whether it is offered or not: an absent row says
+ * nothing, and the caller logging a refusal needs the reason more than the
+ * caller publishing an offer needs the offer.
+ */
+export declare function offeredGridProfiles(input: OfferedGridProfilesInput): readonly GridProfileOffer[];

package/dist/builtins/camera-grid/grid-row-normalization.d.ts

@@ -0,0 +1,10 @@
+export interface NormalizedGridRows {
+    readonly rows: readonly Record<string, unknown>[];
+    /** `true` when the rows differ from what was read, i.e. they must be persisted. */
+    readonly changed: boolean;
+}
+/**
+ * @param mintId a UUID factory — injected so the normalization is testable
+ * without reaching for `crypto`.
+ */
+export declare function normalizeGridRows(raw: readonly Record<string, unknown>[], mintId: () => string): NormalizedGridRows;