@camstack/system 1.2.272 → 1.2.274

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.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-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { P as addonPagesCapability, Pn as EventCategory, an as errMsg, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { P as addonPagesCapability, Pn as EventCategory, an as errMsg, sn as BaseAddon } from "../../dist-DchKwh_m.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.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-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { I as addonWidgetsCapability, Pn as EventCategory, an as errMsg, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { I as addonWidgetsCapability, Pn as EventCategory, an as errMsg, sn as BaseAddon } from "../../dist-DchKwh_m.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/alerts/alerts.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.js");
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/alerts/alerts.addon.mjs

@@ -1,4 +1,4 @@
-import { L as alertsCapability, Pn as EventCategory, an as errMsg, bn as createEvent, n as AlertSchema, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { L as alertsCapability, Pn as EventCategory, an as errMsg, bn as createEvent, n as AlertSchema, sn as BaseAddon } from "../../dist-DchKwh_m.mjs";
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/autotrack/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.js");
 //#region src/builtins/autotrack/autotrack-config.ts
 var DEFAULT_AUTOTRACK_LOOP_CONFIG = {
 	deadZoneFraction: .5,

package/dist/builtins/autotrack/index.mjs

@@ -1,4 +1,4 @@
-import { B as bareAddonId, En as isEvent, It as ptzAutotrackCapability, Pn as EventCategory, an as errMsg, h as FIRST_LEVEL_MACRO_CLASSES, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { B as bareAddonId, En as isEvent, It as ptzAutotrackCapability, Pn as EventCategory, an as errMsg, h as FIRST_LEVEL_MACRO_CLASSES, sn as BaseAddon } from "../../dist-DchKwh_m.mjs";
 //#region src/builtins/autotrack/autotrack-config.ts
 var DEFAULT_AUTOTRACK_LOOP_CONFIG = {
 	deadZoneFraction: .5,

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-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.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 { Dt as mayWriteToLocation, Pn as EventCategory, Zt as storageOccupancyCapability, sn as BaseAddon, z as backupCapability } from "../../dist-Diz59Dhi.mjs";
+import { Dt as mayWriteToLocation, Pn as EventCategory, Zt as storageOccupancyCapability, sn as BaseAddon, z as backupCapability } from "../../dist-DchKwh_m.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

@@ -100,6 +100,19 @@ export declare class CameraGridAddon extends BaseAddon<CameraGridAddonConfig> {
      */
     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;

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

@@ -0,0 +1,62 @@
+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.
+ */
+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;
+}
+export interface GridSeedSpec {
+    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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function renderGridSeed(spec: GridSeedSpec): Promise<Buffer>;

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

@@ -21,8 +21,10 @@
  * A canvas has no pairing to get wrong. When the output tick fires, each
  * rectangle holds whatever arrived last from its source, and the OUTPUT owns
  * the clock. The gap is zero by construction rather than by tuning, and a cell
- * that has produced nothing yet is simply black — so the picture appears at
- * once instead of waiting for the slowest source's first key frame.
+ * that has produced nothing yet costs nothing — so the picture appears at once
+ * instead of waiting for the slowest source's first key frame. What such a cell
+ * shows is the seed the compositor blits in at construction
+ * (`grid-canvas-seed.ts`); `clear()` below is what it shows without one.
  *
  * ## Why yuv420p, and why everything here must be even
  *

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

@@ -5,5 +5,15 @@ export interface GridChildContext {
     readonly logger: IScopedLogger;
     /** The COMPOSITE's device id — every line the primitive emits is tagged with it. */
     readonly deviceId: number;
+    /**
+     * The SOURCE cameras' names, for the cards the canvas is seeded with
+     * (`grid-canvas-seed.ts`). Read at the point of use rather than mirrored:
+     * this addon does not own those devices, and a name it cached would be the
+     * second copy of a fact the device manager already owns (D224).
+     *
+     * Optional, and a failure is not one: a card with no name carries the device
+     * id, which is what every log line about that tile carries anyway.
+     */
+    readonly resolveSourceNames?: (deviceIds: readonly number[]) => Promise<ReadonlyMap<number, string>>;
 }
 export declare function startGridChild(ctx: GridChildContext, plan: GridStreamPlan, sources: readonly GridSourceHandle[], onEnded: (reason: string) => void): Promise<GridStreamChild>;

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

@@ -7,6 +7,16 @@ export interface GridCompositorDeps {
      * 345 KB each is how a stalled encoder becomes an OOM.
      */
     readonly write: (frame: Buffer) => boolean;
+    /**
+     * The picture the canvas carries before any tile has arrived — one card per
+     * cell, naming its camera (`grid-canvas-seed.ts`). `null` ⇒ black, which is
+     * what this was before the seed and what it falls back to when the seed
+     * cannot be drawn.
+     *
+     * Blitted ONCE, here, so the very first tick already carries it: the tick
+     * serves every cell and must never wait on a render.
+     */
+    readonly seed: Buffer | null;
 }
 export declare class GridCompositor {
     private readonly deps;

package/dist/builtins/camera-grid/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-C_4Xt0Ya.js");
 let zod = require("zod");
 let _camstack_types_node = require("@camstack/types/node");
 let node_path = require("node:path");
@@ -2026,6 +2026,200 @@ async function silenceAnalysisFor(deps, deviceId) {
 	if (failures.length > 0) throw new Error(`camera grid ${deviceId}: could not switch off ${failures.length} analyzer(s) — it will run at full detection cost (${failures.join("; ")})`);
 }
 //#endregion
+//#region src/builtins/camera-grid/grid-canvas-seed.ts
+/**
+* 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.
+*/
+/**
+* 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.
+*/
+var GRID_SEED_WAITING_LABEL = "Waiting";
+/**
+* Family names, not paths — librsvg resolves them through fontconfig, and the
+* trailing generics keep a host without DejaVu rendering something legible
+* rather than nothing. Same stack as the courtesy frame, for the same reason.
+*/
+var SEED_FONT_STACK = "DejaVu Sans,DejaVu Sans Mono,Helvetica,Arial,sans-serif";
+/** The card. Dark enough to read as "empty", lit enough to read as "a cell". */
+var CARD_FILL = "#1b1b21";
+var CARD_BORDER = "#3f3f4c";
+var CARD_NAME = "#e8e8ee";
+var CARD_STATE = "#8f8f9e";
+/**
+* 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.
+*/
+function gridSeedName(names, deviceId) {
+	const name = names.get(deviceId)?.trim();
+	return name === void 0 || name.length === 0 ? `Camera ${String(deviceId)}` : name;
+}
+/**
+* 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.
+*/
+function buildGridSeedSpec(plan, names) {
+	return {
+		canvas: plan.canvas,
+		cells: plan.tiles.map((tile) => ({
+			origin: tile.origin,
+			size: tile.size,
+			name: gridSeedName(names, tile.deviceId)
+		}))
+	};
+}
+/** XML escaping for text placed inside an SVG `<text>` node. */
+function escapeSeedText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+/**
+* 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.
+*/
+function buildGridSeedSvg(spec) {
+	const parts = [`<svg xmlns="http://www.w3.org/2000/svg" width="${String(spec.canvas.width)}" height="${String(spec.canvas.height)}">`];
+	for (const [index, cell] of spec.cells.entries()) {
+		const { width, height } = cell.size;
+		const nameSize = Math.max(9, Math.min(Math.round(width / 12), Math.round(height / 8)));
+		const stateSize = Math.max(8, Math.round(nameSize * .62));
+		const stroke = Math.max(2, Math.round(Math.min(width, height) / 100));
+		const inset = stroke / 2;
+		const centreX = cell.origin.x + width / 2;
+		const centreY = cell.origin.y + height / 2;
+		const clipId = `seed-cell-${String(index)}`;
+		parts.push(`<clipPath id="${clipId}"><rect x="${String(cell.origin.x)}" y="${String(cell.origin.y)}" width="${String(width)}" height="${String(height)}"/></clipPath>`, `<rect x="${String(cell.origin.x + inset)}" y="${String(cell.origin.y + inset)}" width="${String(width - stroke)}" height="${String(height - stroke)}" fill="${CARD_FILL}" stroke="${CARD_BORDER}" stroke-width="${String(stroke)}"/>`, `<g clip-path="url(#${clipId})" font-family="${SEED_FONT_STACK}" text-anchor="middle">`, `<text x="${String(centreX)}" y="${String(Math.round(centreY))}" font-size="${String(nameSize)}" fill="${CARD_NAME}">${escapeSeedText(cell.name)}</text>`, `<text x="${String(centreX)}" y="${String(Math.round(centreY + nameSize * 1.15))}" font-size="${String(stateSize)}" fill="${CARD_STATE}">${GRID_SEED_WAITING_LABEL}</text>`, `</g>`);
+	}
+	parts.push("</svg>");
+	return parts.join("");
+}
+/** Limited-range BT.601, which is what a raw yuv420p stream handed to x264 is read as. */
+var Y_OFFSET = 16;
+var CHROMA_OFFSET = 128;
+function clampByte(value) {
+	return Math.min(255, Math.max(0, Math.round(value)));
+}
+function luma(r, g, b) {
+	return Y_OFFSET + (65.481 * r + 128.553 * g + 24.966 * b) / 255;
+}
+function chromaU(r, g, b) {
+	return CHROMA_OFFSET + (-37.797 * r - 74.203 * g + 112 * b) / 255;
+}
+function chromaV(r, g, b) {
+	return CHROMA_OFFSET + (112 * r - 93.786 * g - 18.214 * b) / 255;
+}
+/**
+* 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.
+*/
+function rgbToYuv420p(rgb, size) {
+	const { width, height } = size;
+	const out = Buffer.alloc(yuv420pSize(width, height));
+	const lumaBytes = width * height;
+	const chromaBytes = width / 2 * (height / 2);
+	for (let y = 0; y < height; y += 1) for (let x = 0; x < width; x += 1) {
+		const at = (y * width + x) * 3;
+		out[y * width + x] = clampByte(luma(rgb[at] ?? 0, rgb[at + 1] ?? 0, rgb[at + 2] ?? 0));
+	}
+	const halfW = width / 2;
+	for (let y = 0; y < height / 2; y += 1) for (let x = 0; x < halfW; x += 1) {
+		let r = 0;
+		let g = 0;
+		let b = 0;
+		for (let dy = 0; dy < 2; dy += 1) for (let dx = 0; dx < 2; dx += 1) {
+			const at = ((y * 2 + dy) * width + (x * 2 + dx)) * 3;
+			r += rgb[at] ?? 0;
+			g += rgb[at + 1] ?? 0;
+			b += rgb[at + 2] ?? 0;
+		}
+		const at = y * halfW + x;
+		out[lumaBytes + at] = clampByte(chromaU(r / 4, g / 4, b / 4));
+		out[lumaBytes + chromaBytes + at] = clampByte(chromaV(r / 4, g / 4, b / 4));
+	}
+	return out;
+}
+/**
+* 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.
+*/
+async function renderGridSeed(spec) {
+	const { default: sharp } = await import("sharp");
+	const rgb = await sharp(Buffer.from(buildGridSeedSvg(spec))).flatten({ background: {
+		r: 0,
+		g: 0,
+		b: 0
+	} }).raw().toBuffer();
+	const expected = spec.canvas.width * spec.canvas.height * 3;
+	if (rgb.length !== expected) throw new Error(`camera-grid: the seed rasterized to ${String(rgb.length)} bytes, expected ${String(expected)}`);
+	return rgbToYuv420p(rgb, spec.canvas);
+}
+//#endregion
 //#region src/builtins/camera-grid/grid-tile-feed.ts
 /**
 * One source's decoded tiles, of which only the LATEST is ever wanted.
@@ -2120,11 +2314,16 @@ var GridTileFeed = class {
 *
 * ## It also removes the wait
 *
-* A cell with no frame yet is BLACK, not a reason to hold the picture back. The
-* output exists from the first tick and cells fill in as their sources arrive —
+* A cell with no frame yet is not a reason to hold the picture back. The output
+* exists from the first tick and cells fill in as their sources arrive —
 * instead of the whole grid waiting for the slowest source's first key frame,
 * which is what the ~9 s cold start was.
 *
+* What a cell with no frame yet SHOWS is the seed (`grid-canvas-seed.ts`),
+* blitted in once at construction: its own rectangle, with its camera's name
+* and the word `Waiting`. It was black, and black said the same thing about an
+* empty grid, a broken grid and a grid that is merely still opening.
+*
 * ## What it costs
 *
 * The same N decodes ffmpeg already paid, in N children instead of one, plus
@@ -2143,6 +2342,10 @@ var GridCompositor = class {
 	constructor(deps) {
 		this.deps = deps;
 		this.canvas = new GridCanvas(deps.plan.canvas.width, deps.plan.canvas.height);
+		if (deps.seed !== null) this.canvas.blit(deps.seed, deps.plan.canvas, {
+			x: 0,
+			y: 0
+		});
 		for (const tile of deps.plan.tiles) this.placed.set(tile.id, {
 			tile,
 			feed: new GridTileFeed(tile.frameBytes)
@@ -2385,11 +2588,17 @@ function gridCanvasEncoderInvocation(input) {
 *
 * ## The order things start in, and why it is the order
 *
-* The encoder first, then the tick, then the decoders. The tick writes a black
-* canvas from its very first beat, so the encoder produces a stream — and the
-* consumer sees a picture — before any camera has delivered anything. That is
-* the cold start the old shape spent waiting for the slowest source's first key
-* frame, and it is now spent watching cells fill in.
+* The seed first, then the encoder, then the tick, then the decoders. The tick
+* writes the canvas from its very first beat, so the encoder produces a stream
+* — and the consumer sees a picture — before any camera has delivered anything.
+* That is the cold start the old shape spent waiting for the slowest source's
+* first key frame, and it is now spent watching cells fill in.
+*
+* What that first picture SAYS is the seed (`grid-canvas-seed.ts`): one card
+* per cell, at the cell's own rectangle, naming its camera. It is drawn once,
+* here, before the compositor is built — a tick must never wait on a render —
+* and it is bounded and fallible: a seed that cannot be drawn leaves the canvas
+* black, which is what it was before, and never stops the composition.
 *
 * ## Back-pressure is a SKIPPED tick, never a queue
 *
@@ -2436,6 +2645,77 @@ var DECODER_FIRST_DATA_MS = 15e3;
 * simply replaced while its cell holds the last frame it produced.
 */
 var TILE_MAX_RESTARTS = 5;
+/**
+* How long the seed may wait for the source cameras' names.
+*
+* The seed is drawn BEFORE the encoder is spawned — that is what puts it on the
+* first tick — so everything it waits for is added to the cold start the rest
+* of this file exists to keep short. A name is a nicety; the card exists
+* either way, labelled by device id. So the read is bounded and the deadline
+* is not an error.
+*/
+var SEED_NAMES_TIMEOUT_MS = 1500;
+/**
+* The names for the cards, or an empty map.
+*
+* Never throws and never delays past the deadline: an unnamed card is a
+* complete card (`gridSeedName` falls back to the device id), and a grid that
+* started late because a name lookup was slow would be a worse grid.
+*/
+async function resolveSeedNames(ctx, deviceIds) {
+	const resolve = ctx.resolveSourceNames;
+	if (resolve === void 0) return /* @__PURE__ */ new Map();
+	const empty = /* @__PURE__ */ new Map();
+	return new Promise((settle) => {
+		const timer = setTimeout(() => {
+			ctx.logger.warn("camera grid: the seed could not read the source names in time", {
+				tags: { deviceId: ctx.deviceId },
+				meta: {
+					sources: deviceIds.length,
+					timeoutMs: SEED_NAMES_TIMEOUT_MS
+				}
+			});
+			settle(empty);
+		}, SEED_NAMES_TIMEOUT_MS);
+		timer.unref();
+		resolve(deviceIds).then((names) => {
+			clearTimeout(timer);
+			settle(names);
+		}, (error) => {
+			clearTimeout(timer);
+			ctx.logger.warn("camera grid: the seed could not read the source names", {
+				tags: { deviceId: ctx.deviceId },
+				meta: {
+					sources: deviceIds.length,
+					error: require_dist.errMsg(error)
+				}
+			});
+			settle(empty);
+		});
+	});
+}
+/**
+* The picture the canvas starts as: one card per cell, naming its camera.
+*
+* `null` — black, which is what this was before — when it cannot be drawn. A
+* placeholder that refused to render must never be the reason a grid does not
+* start, so every failure here is a warning and a composition that carries on.
+*/
+async function buildCanvasSeed(ctx, tilePlan) {
+	const names = await resolveSeedNames(ctx, [...new Set(tilePlan.tiles.map((tile) => tile.deviceId))]);
+	try {
+		return await renderGridSeed(buildGridSeedSpec(tilePlan, names));
+	} catch (error) {
+		ctx.logger.warn("camera grid: the canvas seed could not be drawn - starting black", {
+			tags: { deviceId: ctx.deviceId },
+			meta: {
+				error: require_dist.errMsg(error),
+				tiles: tilePlan.tiles.length
+			}
+		});
+		return null;
+	}
+}
 async function startGridCompositorChild(ctx, plan, sources, onEnded) {
 	const tilePlan = buildGridTilePlan({
 		canvas: {
@@ -2455,12 +2735,14 @@ async function startGridCompositorChild(ctx, plan, sources, onEnded) {
 		ended = true;
 		onEnded(reason);
 	};
+	const seed = await buildCanvasSeed(ctx, tilePlan);
 	let encoderIn = null;
 	let encoderOut = null;
 	let draining = false;
 	let tick = null;
 	const compositor = new GridCompositor({
 		plan: tilePlan,
+		seed,
 		write: (frame) => {
 			const sink = encoderIn;
 			if (sink === null || draining || sink.destroyed) return false;
@@ -2577,7 +2859,8 @@ async function startGridCompositorChild(ctx, plan, sources, onEnded) {
 		meta: {
 			tiles: tilePlan.tiles.length,
 			canvas: `${String(tilePlan.canvas.width)}x${String(tilePlan.canvas.height)}`,
-			fps: plan.fps
+			fps: plan.fps,
+			seeded: seed !== null
 		}
 	});
 	return {
@@ -3006,11 +3289,39 @@ var CameraGridAddon = class extends require_dist.BaseAddon {
 			this.sessions.set(key, new GridSessionEntry(instanceId, profile, this.makeSession(instanceId, deviceId, profile)));
 		}
 	}
+	/**
+	* 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.
+	*/
+	async sourceNames(deviceIds) {
+		const names = /* @__PURE__ */ new Map();
+		const results = await Promise.allSettled(deviceIds.map(async (deviceId) => {
+			return {
+				deviceId,
+				name: (await this.ctx.api.deviceManager.getDevice.query({ deviceId }))?.name ?? null
+			};
+		}));
+		for (const result of results) {
+			if (result.status !== "fulfilled") continue;
+			const { deviceId, name } = result.value;
+			if (name !== null) names.set(deviceId, name);
+		}
+		return names;
+	}
 	makeSession(instanceId, deviceId, profile) {
 		const childContext = {
 			binaryPath: this.ffmpegBinaryPath,
 			logger: this.ctx.logger,
-			deviceId
+			deviceId,
+			resolveSourceNames: (deviceIds) => this.sourceNames(deviceIds)
 		};
 		const session = new GridStreamSession({
 			deviceId,