@camstack/system 1.2.261 → 1.2.263

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

@@ -8,7 +8,7 @@ interface CameraGridAddonConfig {
 export declare class CameraGridAddon extends BaseAddon<CameraGridAddonConfig> {
     private relay;
     private reconcileTimer;
-    /** Keyed by {@link sessionKey} — one composition per grid per profile. */
+    /** Keyed by instance id — ONE composition per grid. */
     private readonly sessions;
     private readonly deviceIdByInstanceId;
     private readonly tombstones;
@@ -22,7 +22,7 @@ export declare class CameraGridAddon extends BaseAddon<CameraGridAddonConfig> {
      * (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 readonly planByInstanceId;
     private snapshots;
     private frameSampler;
     private ffmpegBinaryPath;
@@ -44,30 +44,35 @@ export declare class CameraGridAddon extends BaseAddon<CameraGridAddonConfig> {
     private reconcile;
     private silenceAnalysis;
     /**
-     * Which profiles each grid can honestly publish, asked of the BROKER.
+     * 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
+     * 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;
+    private refreshSourcePlans;
     /**
-     * Say which profiles this grid will NOT publish, and why - once per change.
+     * Say WHICH stream each cell is read at, and who could not be read - 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.
+     * 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 logRefusals;
-    private offeredProfiles;
+    private logSourcePlan;
+    private planFor;
     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. */
+    /** This grid's composition, as the list the snapshot source expects. */
     private sessionsForDevice;
     /** A grid that is gone stops immediately - it must not keep N sources dialled. */
     private retireWithdrawnSessions;

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

@@ -1,47 +1,42 @@
 import { CamProfile } from '@camstack/types';
 /**
- * One id, for every grid, forever — for the HIGH composition.
+ * One id, for every grid, forever.
  *
- * 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.
+ * D519's reason 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. It was `high` on the live hub before the per-profile
+ * detour and it is `high` again, so nothing an operator assigned is disturbed.
  */
 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 {
+/**
+ * The slot the single composition claims.
+ *
+ * NOT decoration. A device publishing one stream with no hint is ranked by
+ * pixel count and lands in `mid` — the slot `recordings` does not select on its
+ * own, that `recordingsLow` ignores, and that scrub never reads. The Dreame
+ * robot's single 720p relay landed exactly there and its footage was written
+ * where nothing looked.
+ */
+export declare const GRID_OUTPUT_PROFILE: CamProfile;
+/** The cheapest stream this source serves, or `null` when it serves none. */
+export declare function lowestServedProfile(served: readonly CamProfile[]): CamProfile | null;
+export interface GridSourceProfilesInput {
     /** 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.
+     * saying so separately 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. */
+export interface GridSourcePlan {
+    /** True when every source can be read — the only case a grid is on offer. */
+    readonly offered: boolean;
+    /** Which stream each source is read at. Only contains readable sources. */
+    readonly profileBySource: ReadonlyMap<number, CamProfile>;
+    /** The sources that serve nothing, or that nobody could answer for. */
     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[];
+}
+/** Which stream to read each source at, and who cannot be read at all. */
+export declare function gridSourceProfiles(input: GridSourceProfilesInput): GridSourcePlan;

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

@@ -1,4 +1,3 @@
-import { CamProfile } from '@camstack/types';
 import { GridStreamLogger } from './grid-stream-session.js';
 /** Where a grid's last composed frame is kept between compositions. */
 export interface GridLastFrameStore {
@@ -8,7 +7,6 @@ export interface GridLastFrameStore {
 }
 /** Just enough of a session for the snapshot to choose one and read its state. */
 export interface GridSnapshotSession {
-    readonly profile: CamProfile;
     isRunning(): boolean;
 }
 export interface GridSnapshotAnswerInput {
@@ -40,8 +38,10 @@ export interface GridSnapshotImage {
 export interface GridSnapshotDeps<S extends GridSnapshotSession = GridSnapshotSession> {
     readonly logger: GridStreamLogger;
     /**
-     * This grid's sessions, one per published profile, in descending quality.
-     * EMPTY means this addon does not own the device — never "no picture".
+     * This grid's compositions — one, since the collapse to a single output.
+     * Kept as a LIST because the choosing logic below is the same either way and
+     * a list of one costs nothing. EMPTY means this addon does not own the
+     * device — never "no picture".
      */
     readonly sessionsFor: (deviceId: number) => readonly S[];
     /**

package/dist/builtins/camera-grid/grid-stream-descriptor.d.ts

@@ -1,7 +1,5 @@
-import { CamProfile, CamStreamDescriptor } from '@camstack/types';
+import { CamStreamDescriptor } from '@camstack/types';
 export interface GridStreamDescriptorInput {
-    /** Which composition this is. Also the `profileHint` — see below. */
-    readonly profile: CamProfile;
     readonly width: number;
     readonly height: number;
     readonly fps: number;
@@ -17,8 +15,8 @@ export interface GridStreamDescriptorInput {
  * scrub never reads. The Dreame robot's one 720p relay landed exactly there and
  * its footage was written nowhere anything looked.
  *
- * With several compositions published the hint does a second job: it is the
- * only thing that says which slot each one is FOR. Ranked by pixels a grid's
- * `mid` would take the `high` slot on any grid whose `high` was not offered.
+ * So the single composition claims `high` EXPLICITLY (`GRID_OUTPUT_PROFILE`).
+ * It is also the slot this stream held before the per-profile detour, which is
+ * what keeps an operator's existing assignment intact.
  */
 export declare function gridStreamDescriptor(input: GridStreamDescriptorInput): CamStreamDescriptor;

package/dist/builtins/camera-grid/grid-stream-relay.d.ts

@@ -1,21 +1,17 @@
-import { CamProfile } from '@camstack/types';
 import { GridStreamLogger, GridStreamSession } from './grid-stream-session.js';
 /**
- * Which grid, and WHICH COMPOSITION of it.
+ * Which grid. There is one composition of it, so that is the whole address.
  *
- * The profile is a path segment and not a query string for the reason the
- * restream suffixes are (`restream-intent.ts`): the choice belongs to the URL
- * the consumer was handed, so a broker configured once keeps asking for the
- * same thing. It is also REQUIRED — there is no default composition. A grid
- * publishes one stream per profile it can serve, and a dial that named none
- * would be the broker asking for "whichever", which is how a `low` slot ends
- * up holding a `high` composition.
+ * The path used to carry a profile segment, because a grid published one
+ * composition per profile and a dial naming none would have been the broker
+ * asking for "whichever". With a single output "whichever" is well defined,
+ * and the segment would be a choice with one option — which is not a choice,
+ * it is a way to spell one stream two ways.
  */
 export interface GridStreamRequest {
     readonly instanceId: string;
-    readonly profile: CamProfile;
 }
-/** `/grid/<instanceId>/<profile>.flv`, or `null` when it is anything else. */
+/** `/grid/<instanceId>.flv`, or `null` when it is anything else. */
 export declare function parseGridStreamPath(url: string | undefined): GridStreamRequest | null;
 export interface GridStreamRelayDeps {
     readonly logger: GridStreamLogger;

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

@@ -22,8 +22,8 @@ export type { GridPlanEncodeContext } from './grid-plan.js';
 export { normalizeGridRows } from './grid-row-normalization.js';
 export type { NormalizedGridRows } from './grid-row-normalization.js';
 export { gridStreamDescriptor } from './grid-stream-descriptor.js';
-export { GRID_CAM_STREAM_ID, GRID_PROFILES, gridCamStreamId, gridCanvasFor, offeredGridProfiles, } from './grid-profiles.js';
-export type { GridCanvas, GridProfileOffer } from './grid-profiles.js';
+export { GRID_CAM_STREAM_ID, GRID_OUTPUT_PROFILE, gridSourceProfiles, lowestServedProfile, } from './grid-profiles.js';
+export type { GridSourcePlan } from './grid-profiles.js';
 export { gridSourceDial } from './grid-sentry-sources.js';
 export type { GridSourceAcquisition, GridSourceDial } from './grid-sentry-sources.js';
 export { GridSnapshotSource, gridSnapshotAnswerFor } from './grid-snapshot.js';