@camstack/system 1.2.390 → 1.2.392

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

@@ -1,179 +1,205 @@
-import { AddonInitResult, ConfigUISchema, DeviceProxy, BaseAddon } from '@camstack/types';
+/**
+* Camera Grids — several cameras composed into one, emitted as an ordinary
+* camera.
+*
+* ## What it is
+*
+* A grid is a DEVICE this addon declares, with one stream that is composed
+* rather than dialled. Everything downstream treats it as a camera: it records,
+* it appears in the timeline, it has a profile slot, it is bound like any other
+* — with ONE deliberate exception, object detection, which is switched off at
+* creation (see `silence-analysis.ts` for why, and for why it is never
+* re-asserted afterwards).
+*
+* ## Hub-only, one process
+*
+* `placement: hub-only`, `instanceMode: unique`, and NOT in any `execution.group`
+* (D2/D29): it runs ffmpeg children over live media, and a co-located crash
+* would respawn the whole runner.
+*
+* ## The lifecycle, in one line
+*
+* No prebuffer. The composition runs while a consumer is reading it and not one
+* second longer — see `grid-stream-session.ts`, which owns that rule, and
+* `grid-stream-relay.ts`, where an open socket IS the consumer.
+*/
+import type { AddonInitResult, ConfigUISchema, DeviceProxy } from "@camstack/types";
+import { 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[];
+	/** 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 instance id — ONE composition per grid. */
-    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 plansByInstanceId;
-    private activity;
-    private snapshots;
-    private frameSampler;
-    /** The node's pinned ffmpeg (D540). `null` until init resolved it — a
-     *  composition then refuses by name; there is no PATH default. */
-    private ffmpegBinaryPath;
-    /** The node's pinned build, remembered only on success (D540). */
-    private readonly pinnedFfmpeg;
-    /** A resolution in flight, so a reconcile pass never starts a second. */
-    private ffmpegResolving;
-    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;
-    /**
-     * Listen to the SOURCES, so the grid can say the same things about itself.
-     *
-     * Filtered by source id inside the handler rather than by subscribing per
-     * camera: the bus filter is per category, the set of sources changes whenever
-     * an operator drags a cell, and a per-camera subscription would have to be
-     * torn down and rebuilt on every layout save.
-     *
-     * Every handler is TOTAL — a malformed payload is ignored, never thrown out
-     * of. These are telemetry events on a shared bus (D8/D11), and a throw here
-     * would take the grid's forwarding down for every grid because one camera
-     * emitted something unexpected.
-     */
-    private subscribeSourceActivity;
-    /**
-     * Which grids show this camera. Empty for the overwhelming majority of
-     * events, which is why it is the FIRST thing every handler asks.
-     */
-    private gridsForSource;
-    /**
-     * Which stream each grid reads each of its sources at, 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 refreshSourcePlans;
-    /**
-     * Say WHICH stream each cell is read at, and who could not be read - once per
-     * change.
-     *
-     * Both halves earn their line. A grid silently missing from a catalog is
-     * indistinguishable from a broker that swept it, so the refusal names the
-     * sources. And the chosen profiles are the answer to "why is this tile
-     * soft?" — a camera whose only assigned slot is `high` is read at `high`, and
-     * nothing else in the system would ever say so.
-     *
-     * Logged on the EDGE: a grid that cannot be composed would otherwise write a
-     * line a minute for ever.
-     */
-    private logSourcePlan;
-    private plansFor;
-    private planFor;
-    /**
-     * The canvas of the BEST profile this grid offers.
-     *
-     * Used where a single geometry is needed for something that is not a
-     * composition — the detection boxes a grid forwards (`grid-activity`), which
-     * are normalized against whatever picture the viewer is looking at. The best
-     * offered one is the honest default; a grid offering nothing has no geometry
-     * and says so.
-     */
-    private canvasFor;
-    private ensureSessions;
-    /**
-     * The source cameras' names, for the cards the canvas is seeded with.
-     *
-     * Asked of the device manager, which OWNS the name, at the moment the seed is
-     * drawn — never kept here. A consumer that mirrored this would be stale on
-     * exactly the write an operator makes (D224), for a label.
-     *
-     * A device that cannot be read is simply absent from the map, and its card
-     * carries the device id instead. One unreadable camera never costs the other
-     * cards their names, which is why these are settled rather than awaited as
-     * one batch.
-     */
-    private sourceNames;
-    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;
-    /**
-     * Resolve the pinned build, single-flighted, and hand it to the frame sampler.
-     * Never throws: a failure is an ERROR and leaves the binary unknown, so the
-     * next pass that wants a composition asks again. Never PATH: the host's
-     * ffmpeg is not ours (`packages/types/src/deps/ffmpeg-binary-source.ts`).
-     */
-    private resolveFfmpeg;
-    /**
-     * 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[];
+	private relay;
+	private reconcileTimer;
+	/** Keyed by instance id — ONE composition per grid. */
+	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 plansByInstanceId;
+	private activity;
+	private snapshots;
+	private frameSampler;
+	/** The node's pinned ffmpeg (D540). `null` until init resolved it — a
+	*  composition then refuses by name; there is no PATH default. */
+	private ffmpegBinaryPath;
+	/** The node's pinned build, remembered only on success (D540). */
+	private readonly pinnedFfmpeg;
+	/** A resolution in flight, so a reconcile pass never starts a second. */
+	private ffmpegResolving;
+	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;
+	/**
+	* Listen to the SOURCES, so the grid can say the same things about itself.
+	*
+	* Filtered by source id inside the handler rather than by subscribing per
+	* camera: the bus filter is per category, the set of sources changes whenever
+	* an operator drags a cell, and a per-camera subscription would have to be
+	* torn down and rebuilt on every layout save.
+	*
+	* Every handler is TOTAL — a malformed payload is ignored, never thrown out
+	* of. These are telemetry events on a shared bus (D8/D11), and a throw here
+	* would take the grid's forwarding down for every grid because one camera
+	* emitted something unexpected.
+	*/
+	private subscribeSourceActivity;
+	/**
+	* Which grids show this camera. Empty for the overwhelming majority of
+	* events, which is why it is the FIRST thing every handler asks.
+	*/
+	private gridsForSource;
+	/**
+	* Which stream each grid reads each of its sources at, 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 refreshSourcePlans;
+	/**
+	* Say WHICH stream each cell is read at, and who could not be read - once per
+	* change.
+	*
+	* Both halves earn their line. A grid silently missing from a catalog is
+	* indistinguishable from a broker that swept it, so the refusal names the
+	* sources. And the chosen profiles are the answer to "why is this tile
+	* soft?" — a camera whose only assigned slot is `high` is read at `high`, and
+	* nothing else in the system would ever say so.
+	*
+	* Logged on the EDGE: a grid that cannot be composed would otherwise write a
+	* line a minute for ever.
+	*/
+	private logSourcePlan;
+	private plansFor;
+	private planFor;
+	/**
+	* The canvas of the BEST profile this grid offers.
+	*
+	* Used where a single geometry is needed for something that is not a
+	* composition — the detection boxes a grid forwards (`grid-activity`), which
+	* are normalized against whatever picture the viewer is looking at. The best
+	* offered one is the honest default; a grid offering nothing has no geometry
+	* and says so.
+	*/
+	private canvasFor;
+	private ensureSessions;
+	/**
+	* The source cameras' names, for the cards the canvas is seeded with.
+	*
+	* Asked of the device manager, which OWNS the name, at the moment the seed is
+	* drawn — never kept here. A consumer that mirrored this would be stale on
+	* exactly the write an operator makes (D224), for a label.
+	*
+	* A device that cannot be read is simply absent from the map, and its card
+	* carries the device id instead. One unreadable camera never costs the other
+	* cards their names, which is why these are settled rather than awaited as
+	* one batch.
+	*/
+	private sourceNames;
+	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;
+	/**
+	* Resolve the pinned build, single-flighted, and hand it to the frame sampler.
+	* Never throws: a failure is an ERROR and leaves the binary unknown, so the
+	* next pass that wants a composition asks again. Never PATH: the host's
+	* ffmpeg is not ours (`packages/types/src/deps/ffmpeg-binary-source.ts`).
+	*/
+	private resolveFfmpeg;
+	/**
+	* 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 override globalSettingsSchema(): ConfigUISchema;
+	protected override integrationSettingSections(): readonly string[];
 }
 export type { DeviceProxy };

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

@@ -1,66 +1,40 @@
-/**
- * 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[];
+	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.
- */
+* 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;
+	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;
+	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-activity-mirror.d.ts

@@ -1,42 +1,42 @@
 /** The grid's own motion answer, in the shape the `motion` cap publishes. */
 export interface GridMotionState {
-    readonly detected: boolean;
-    /** Ms epoch of the most recent rising edge on ANY source (never a heartbeat). Null if never. */
-    readonly lastDetectedAt: number | null;
+	readonly detected: boolean;
+	/** Ms epoch of the most recent rising edge on ANY source (never a heartbeat). Null if never. */
+	readonly lastDetectedAt: number | null;
 }
 export declare class GridActivityMirror {
-    private readonly motion;
-    private readonly audio;
-    private lastDetectedAt;
-    /**
-     * One source's motion push. `detected: false` is as important as `true`.
-     *
-     * `lastDetectedAt` moves only on a source's RISING edge — the source was not
-     * moving, or its last `true` had expired. A source's pushes include a
-     * heartbeat (the bridge's sustain ticks, every `true` a camera re-sends while
-     * a subject stays), and moving the stamp on each one made the grid's
-     * `lastDetectedAt` "the last tick of any cell" while every camera's is its
-     * last effective RISE (D696): the viewer's Motion order then ranked the grid
-     * above the very cells it shows (2026-10-06).
-     */
-    noteMotion(sourceDeviceId: number, detected: boolean, atMs: number): void;
-    /** One source's audio window. `dbfs` is the level, on the analyzer's scale. */
-    noteAudio(sourceDeviceId: number, dbfs: number, atMs: number): void;
-    /**
-     * Drop every source this grid no longer composes.
-     *
-     * A cell removed while its camera was moving would otherwise hold the grid
-     * lit until the expiry, for a picture the source is not even in.
-     */
-    keepOnly(sourceDeviceIds: readonly number[]): void;
-    /** At least one source moving, as of `nowMs`. */
-    motionAt(nowMs: number): GridMotionState;
-    /**
-     * The loudest CURRENT reading, or `null` when nothing fresh has been heard.
-     *
-     * Null and not `-Infinity`: "nobody has reported a level" is a different
-     * answer from "it is silent", and a number here would have the viewer draw a
-     * level for a grid whose sources are not being analysed at all.
-     */
-    loudestAt(nowMs: number): number | null;
+	private readonly motion;
+	private readonly audio;
+	private lastDetectedAt;
+	/**
+	* One source's motion push. `detected: false` is as important as `true`.
+	*
+	* `lastDetectedAt` moves only on a source's RISING edge — the source was not
+	* moving, or its last `true` had expired. A source's pushes include a
+	* heartbeat (the bridge's sustain ticks, every `true` a camera re-sends while
+	* a subject stays), and moving the stamp on each one made the grid's
+	* `lastDetectedAt` "the last tick of any cell" while every camera's is its
+	* last effective RISE (D696): the viewer's Motion order then ranked the grid
+	* above the very cells it shows (2026-10-06).
+	*/
+	noteMotion(sourceDeviceId: number, detected: boolean, atMs: number): void;
+	/** One source's audio window. `dbfs` is the level, on the analyzer's scale. */
+	noteAudio(sourceDeviceId: number, dbfs: number, atMs: number): void;
+	/**
+	* Drop every source this grid no longer composes.
+	*
+	* A cell removed while its camera was moving would otherwise hold the grid
+	* lit until the expiry, for a picture the source is not even in.
+	*/
+	keepOnly(sourceDeviceIds: readonly number[]): void;
+	/** At least one source moving, as of `nowMs`. */
+	motionAt(nowMs: number): GridMotionState;
+	/**
+	* The loudest CURRENT reading, or `null` when nothing fresh has been heard.
+	*
+	* Null and not `-Infinity`: "nobody has reported a level" is a different
+	* answer from "it is silent", and a number here would have the viewer draw a
+	* level for a grid whose sources are not being analysed at all.
+	*/
+	loudestAt(nowMs: number): number | null;
 }