@camstack/system 1.2.254 → 1.2.255

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

@@ -0,0 +1,2276 @@
+import { Cn as hydrateSchema, Qt as streamCatalogCapability, U as cameraGridLayoutCapability, Y as declarationOwnerNodeId, a as BaseDevice, an as buildFfmpegArgs, fn as DeviceType, in as errMsg, m as DeclaredDevices, n as AUDIO_ANALYSIS_CAP_NAME, on as BaseAddon, p as DETECTION_PIPELINE_CAP_NAME, qt as snapshotCapability, un as DeviceFeature } from "../../dist-Ch93tyHB.mjs";
+import { z } from "zod";
+import { FfmpegProcess } from "@camstack/types/node";
+import { join } from "node:path";
+import { promises } from "node:fs";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+//#region src/builtins/camera-grid/grid-camera-declarations.ts
+/**
+* Turning persisted grid rows into the camera declarations `DeclaredDevices`
+* reconciles.
+*
+* Modelled on `terminal-camera-declarations.ts`, and for the same reasons: the
+* declaration set is the ONLY thing standing between a transient RPC failure
+* and a sweep that deletes every camera this addon owns.
+*/
+/** The prefix every stable id this addon has ever minted starts with. */
+var GRID_CAMERA_STABLE_ID_PREFIX = "camera-grid-";
+/**
+* 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.
+*/
+function newGridCameraStableId(instanceId) {
+	return `${GRID_CAMERA_STABLE_ID_PREFIX}${instanceId}`;
+}
+/**
+* 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.
+*/
+function buildGridCameraDeclarations(instances) {
+	return instances.filter((instance) => instance.enabled).map((instance) => ({
+		stableId: instance.cameraStableId,
+		name: instance.name,
+		config: { instanceId: instance.id }
+	}));
+}
+/**
+* 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.
+*/
+function gridCameraReconciliationIndex(rows, integrationId, declarations, managedStableIds = /* @__PURE__ */ new Set()) {
+	if (!integrationId) return [];
+	const declared = new Set(declarations.map((camera) => camera.stableId));
+	const owned = rows.filter((row) => row.integrationId === integrationId && (declared.has(row.stableId) || managedStableIds.has(row.stableId) || row.stableId.startsWith(GRID_CAMERA_STABLE_ID_PREFIX)));
+	return [...owned.filter((row) => declared.has(row.stableId)), ...owned.filter((row) => !declared.has(row.stableId)).sort((left, right) => left.id - right.id).slice(0, 32)];
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-device-settings.ts
+/** The widget id, registered in `ui-library`'s `HOST_WIDGETS`. */
+var 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).
+*/
+function buildGridDeviceSchema(isGrid) {
+	if (!isGrid) return null;
+	return { sections: [{
+		id: "camera-grid-layout",
+		tab: "general",
+		title: "Grid layout",
+		order: 20,
+		fields: [{
+			type: "widget",
+			key: "_gridLayout",
+			label: "",
+			widgetId: GRID_LAYOUT_WIDGET_ID
+		}]
+	}] };
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-layout-native-provider.ts
+/**
+* The `camera-grid-layout` provider, contribution included.
+*
+* ## Why the section lives on the DEVICE provider and not on the addon
+*
+* `camera-grid-layout` is registered per device, through
+* `DeviceContext.registerNativeCap`. `child-cap-dispatch` resolves a call that
+* carries a `deviceId` to the device-scoped provider FIRST, and when the method
+* is absent there it throws rather than falling back to the singleton — the
+* fallback exists only for a collection cap's list method. Every contribution
+* method carries a `deviceId` by definition, so an addon-level wrapper is
+* simply never reached: it registered, it type-checked, and the live hub
+* answered HTTP 500 with
+*   `method 'getDeviceSettingsContribution' not found on provider
+*    'camera-grid-layout'`.
+*
+* That is why the whole provider is built here, in one place, and handed to
+* `registerNativeCap` as a single object. `exposesDeviceSettings` widens
+* `InferProvider` and not `InferNativeProvider`, so the type below is the wider
+* one; registering it is safe because a native registration only ever needs a
+* SUBSET of what this carries.
+*
+* The refusal (D526) rides along: a device the addon cannot name as a grid gets
+* `null`, so a camera that is not a grid gets no section at all rather than a
+* panel that renders its own emptiness.
+*/
+function buildGridLayoutNativeProvider(source) {
+	return {
+		getLayout: async ({ deviceId }) => source.getLayout(deviceId),
+		saveLayout: async (patch) => source.saveLayout(patch),
+		getDeviceSettingsContribution: async ({ deviceId }) => {
+			const schema = buildGridDeviceSchema(source.getLayout(deviceId) !== null);
+			return schema === null ? null : hydrateSchema(schema, {});
+		},
+		getDeviceLiveContribution: async () => null,
+		applyDeviceSettingsPatch: async () => ({ success: true })
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-camera-device.ts
+/**
+* The composite camera device.
+*
+* An ORDINARY camera in every respect the rest of the system can see: it
+* records, it appears in the timeline, it has profile slots, it is bound like
+* any other. What makes it a grid is invisible from here — its streams are
+* composed rather than dialled, and object detection is switched off at
+* CREATION (see `silence-analysis.ts`), never re-asserted.
+*
+* ## The three native caps, and why each is native
+*
+* - **`stream-catalog`** — what this grid OFFERS, one descriptor per profile it
+*   can honestly compose. Named on every pull, idle included: the broker sweeps
+*   anything its registry holds that a catalog does not name.
+* - **`camera-grid-layout`** — the geometry, on the camera's own page. Device
+*   scoped so the widget asks THE CAMERA; the addon-scoped custom actions it
+*   replaces could only be reached by a caller that already knew the addon id,
+*   which is why the editor rendered nowhere.
+* - **`snapshot`** — a frame of the composition. It used to be deliberately
+*   ABSENT, on the reasoning that the broker's ordinary grab takes one from the
+*   profile slot and taking one IS a consumer. That is true and it is the
+*   defect: it means a thumbnail in a list starts N decodes, and on a battery
+*   source it would be a wake. A native provider runs BEFORE that grab and
+*   answers from the live composition or from the frame it kept
+*   (`grid-snapshot.ts`).
+*/
+var gridCameraSchema = z.object({ 
+/** The persisted grid row this camera was declared from. */
+instanceId: z.string().min(1) });
+var runtime = null;
+function installGridCameraRuntime(next) {
+	runtime = next;
+}
+function activeRuntime() {
+	if (runtime === null) throw new Error("camera-grid: the addon runtime is not installed");
+	return runtime;
+}
+var GridCameraDevice = class extends BaseDevice {
+	features = [DeviceFeature.NativeSnapshot];
+	constructor(ctx) {
+		super(ctx, gridCameraSchema, { type: ctx.deviceMeta.type });
+		this.ctx.registerNativeCap(streamCatalogCapability, { getCatalog: async ({ deviceId }) => {
+			if (deviceId !== this.id) return [];
+			return this.catalog();
+		} });
+		const layoutProvider = buildGridLayoutNativeProvider({
+			getLayout: (deviceId) => activeRuntime().getLayout(deviceId),
+			saveLayout: (patch) => activeRuntime().saveLayout(patch)
+		});
+		this.ctx.registerNativeCap(cameraGridLayoutCapability, layoutProvider);
+		this.ctx.registerNativeCap(snapshotCapability, {
+			getSnapshot: async ({ deviceId }) => activeRuntime().getSnapshot(deviceId),
+			invalidateCache: async () => {}
+		});
+		this.markOnline(true);
+	}
+	catalog() {
+		const descriptors = activeRuntime().descriptorsFor(this.config.get("instanceId"));
+		if (descriptors === null) throw new Error(`camera-grid: cannot describe the streams of instance ${this.config.get("instanceId")}`);
+		return descriptors;
+	}
+	setAddonOnline(online) {
+		this.markOnline(online);
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-instances.ts
+/**
+* The operator-written grid rows.
+*
+* Shape follows `readTerminalInstances`: a grid is a persisted row that
+* DECLARES a camera, and the declaration reconcile turns rows into devices.
+*
+* Config is operator-writable, so a malformed or duplicate row is IGNORED
+* rather than allowed to make the reconcile destructive. One bad row must never
+* delete every camera this addon declares — that failure mode is why the
+* Terminal addon reads its rows the same way.
+*/
+/** A rectangle in normalized [0,1] coordinates of whatever contains it. */
+var NormalizedRectSchema = z.object({
+	x: z.number().min(0).max(1),
+	y: z.number().min(0).max(1),
+	width: z.number().gt(0).max(1),
+	height: z.number().gt(0).max(1)
+});
+/**
+* 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.
+*/
+var GridCellSchema = z.object({
+	deviceId: z.number().int().positive(),
+	source: NormalizedRectSchema,
+	cell: NormalizedRectSchema
+});
+var GridInstanceSchema = z.object({
+	id: z.string().uuid(),
+	cameraStableId: z.string().min(1).max(256),
+	name: z.string().min(1).max(160),
+	enabled: z.boolean(),
+	/** Canvas size — the composite camera's own resolution. */
+	width: z.number().int().min(160).max(7680),
+	height: z.number().int().min(120).max(4320),
+	fps: z.number().int().min(1).max(60),
+	/**
+	* Empty is the NORMAL freshly-created state: a grid is created from the
+	* integration page with a name only, and laid out afterwards in the camera's
+	* own settings. A grid with no cells declares its camera and emits nothing.
+	*/
+	cells: z.array(GridCellSchema).max(16).default([])
+});
+function readGridInstances(raw, onInvalid) {
+	const ids = /* @__PURE__ */ new Set();
+	const stableIds = /* @__PURE__ */ new Set();
+	const instances = [];
+	for (const value of raw) {
+		const parsed = GridInstanceSchema.safeParse(value);
+		if (!parsed.success) {
+			onInvalid?.("Ignoring malformed camera-grid configuration");
+			continue;
+		}
+		const instance = parsed.data;
+		if (ids.has(instance.id) || stableIds.has(instance.cameraStableId)) {
+			onInvalid?.(`Ignoring duplicate camera-grid instance ${instance.id}`);
+			continue;
+		}
+		ids.add(instance.id);
+		stableIds.add(instance.cameraStableId);
+		instances.push(instance);
+	}
+	return instances;
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-plan.ts
+/**
+* Bits per pixel per frame. A composite is mostly static furniture with a few
+* moving subjects, so it compresses well; this lands a 1920x1080@10 grid near
+* 3 Mbps and a 640x360@10 one near 0.35 Mbps. A single flat number would either
+* starve a 4K canvas or spend a 4K budget on a thumbnail-sized one.
+*/
+var BITS_PER_PIXEL_PER_FRAME = .15;
+var MIN_BITRATE_KBPS = 256;
+var MAX_BITRATE_KBPS = 16e3;
+function bitrateFor(width, height, fps) {
+	const bps = width * height * fps * BITS_PER_PIXEL_PER_FRAME;
+	return Math.min(MAX_BITRATE_KBPS, Math.max(MIN_BITRATE_KBPS, Math.round(bps / 1e3)));
+}
+/** `null` when the grid has nothing to compose — the normal freshly-created state. */
+function gridPlanFor(instance, encode) {
+	if (instance.cells.length === 0) return null;
+	const ordinalByDeviceId = /* @__PURE__ */ new Map();
+	const sourceDeviceIds = [];
+	const cells = instance.cells.map((cell) => {
+		let ordinal = ordinalByDeviceId.get(cell.deviceId);
+		if (ordinal === void 0) {
+			ordinal = sourceDeviceIds.length;
+			ordinalByDeviceId.set(cell.deviceId, ordinal);
+			sourceDeviceIds.push(cell.deviceId);
+		}
+		return {
+			inputIndex: ordinal,
+			source: cell.source,
+			cell: cell.cell
+		};
+	});
+	const canvas = encode.canvas ?? {
+		width: instance.width,
+		height: instance.height
+	};
+	return {
+		layout: {
+			width: canvas.width,
+			height: canvas.height,
+			cells
+		},
+		sourceDeviceIds,
+		encoder: encode.encoder,
+		decodeHwAccel: encode.decodeHwAccel,
+		fps: instance.fps,
+		bitrateKbps: bitrateFor(canvas.width, canvas.height, instance.fps)
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-row-normalization.ts
+/**
+* Creation is NAME ONLY.
+*
+* The operator adds a row on the integration page and types a name. Everything
+* else — the identity the rest of the cluster will reference forever, the
+* canvas, the frame rate, the cells — is filled in here on the way past, and
+* then edited in the camera's own device details.
+*
+* This runs BEFORE `readGridInstances`, which deliberately IGNORES a row it
+* cannot parse so one bad row can never make the declaration reconcile
+* destructive. A freshly typed name is exactly such a row, so without this step
+* a new grid would be silently discarded at the moment of creation.
+*/
+/** Canvas and cadence a grid starts life with, until the layout editor changes them. */
+var DEFAULT_WIDTH = 1920;
+var DEFAULT_HEIGHT = 1080;
+var DEFAULT_FPS = 10;
+function nonEmptyString(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+function positiveInt(value, fallback) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+/**
+* @param mintId a UUID factory — injected so the normalization is testable
+* without reaching for `crypto`.
+*/
+function normalizeGridRows(raw, mintId) {
+	let changed = false;
+	const rows = [];
+	for (const row of raw) {
+		const name = nonEmptyString(row["name"]);
+		if (name === null) {
+			changed = true;
+			continue;
+		}
+		const id = nonEmptyString(row["id"]) ?? mintId();
+		const cameraStableId = nonEmptyString(row["cameraStableId"]) ?? newGridCameraStableId(id);
+		const normalized = {
+			...row,
+			id,
+			cameraStableId,
+			name,
+			enabled: typeof row["enabled"] === "boolean" ? row["enabled"] : true,
+			width: positiveInt(row["width"], DEFAULT_WIDTH),
+			height: positiveInt(row["height"], DEFAULT_HEIGHT),
+			fps: positiveInt(row["fps"], DEFAULT_FPS),
+			cells: Array.isArray(row["cells"]) ? row["cells"] : []
+		};
+		if (!changed) changed = Object.keys(normalized).some((key) => normalized[key] !== row[key]);
+		rows.push(normalized);
+	}
+	return {
+		rows,
+		changed
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-wire-format.ts
+/** What the relay answers with, and what the sampler must demux. */
+var GRID_WIRE_CONTENT_TYPE = "video/x-flv";
+/** `/grid/<instanceId>/<profile>.flv`. */
+var GRID_WIRE_PATH_SUFFIX = ".flv";
+/**
+* How the broker must ingest it: `pull-flv` is documented as ALWAYS read
+* through the ffmpeg source reader with `-c copy`. `pull-http` would have been
+* the intuitive choice and means MJPEG in this broker — it answers with
+* `HTTP_MJPEG_H264_OUTPUT_ARGS` and re-encodes an already-encoded H.264.
+*/
+var GRID_WIRE_STREAM_KIND = "pull-flv";
+//#endregion
+//#region src/builtins/camera-grid/grid-frame-sample.ts
+/**
+* ONE JPEG out of a composition that is already running.
+*
+* ## Why this is not the ffmpeg primitive
+*
+* `FfmpegProcess` + `buildFfmpegArgs` own the STREAM job: a long-lived encode
+* with a hardware cascade, a first-data deadline and a bounded restart. This is
+* the other kind — run-to-completion, no encode plan worth sharing, finishes or
+* is killed — which is the class `scripts/check-ffmpeg-primitive.ts` already
+* carves out by name for `recorder/still/still-frame-service.ts` ("single-JPEG
+* still grab") and `builtins/snapshot/snapshot.addon.ts` ("keyframe snapshot
+* grab"). It is the same job as those two, on a pipe instead of a URL.
+*
+* ## Why a pipe and not the grid's own URL
+*
+* Dialling the relay would be a CONSUMER, and a consumer of a cold grid starts
+* the composition — N broker acquisitions for a thumbnail, which is the one
+* thing the operator ruled out. Reading the bytes of a session that is ALREADY
+* running costs nothing: the child is up, the packets are being produced, and
+* this just takes a copy of them.
+*
+* Bounded on both ends. A composition whose first key frame is far away must
+* not hold an ffmpeg (or this promise) open for ever, so the grab has a
+* deadline and the child is killed at it — a snapshot that did not arrive is
+* `null`, and `null` is a real answer.
+*/
+/** Long enough for a 2 s GOP plus a probe, short enough that a list does not hang. */
+var DEFAULT_TIMEOUT_MS = 8e3;
+/** JPEG quality. 4 is visually clean at thumbnail and list sizes and ~40 KB at 1080p. */
+var JPEG_QUALITY = "4";
+var GridFrameSampler = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* @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.
+	*/
+	async sample(deviceId, source) {
+		const spawnFn = this.options.spawnFn ?? spawn;
+		const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		const child = spawnFn(this.options.binaryPath, [
+			"-hide_banner",
+			"-loglevel",
+			"error",
+			"-f",
+			"flv",
+			"-i",
+			"pipe:0",
+			"-frames:v",
+			"1",
+			"-q:v",
+			JPEG_QUALITY,
+			"-f",
+			"mjpeg",
+			"pipe:1"
+		], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		const chunks = [];
+		child.stdout?.on("data", (chunk) => chunks.push(chunk));
+		child.stderr?.on("data", () => {});
+		const hold = source.attach((chunk) => {
+			if (child.stdin?.writable === true) child.stdin.write(chunk);
+		});
+		if (hold === null) {
+			child.kill("SIGKILL");
+			this.options.logger.warn("camera grid: could not attach to sample a frame", { tags: { deviceId } });
+			return null;
+		}
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, timeoutMs);
+		timer.unref?.();
+		try {
+			await new Promise((resolve) => {
+				child.once("exit", () => resolve());
+				child.once("error", () => resolve());
+			});
+		} finally {
+			clearTimeout(timer);
+			hold.close();
+			try {
+				child.stdin?.end();
+			} catch (error) {
+				this.options.logger.debug("camera grid: the frame grab stdin refused to close", {
+					tags: { deviceId },
+					meta: { error: errMsg(error) }
+				});
+			}
+		}
+		const jpeg = Buffer.concat(chunks);
+		if (jpeg.length === 0) {
+			this.options.logger.warn("camera grid: the frame grab produced no bytes", {
+				tags: { deviceId },
+				meta: { timeoutMs }
+			});
+			return null;
+		}
+		return jpeg;
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-last-frame-store.ts
+/**
+* The last COMPOSED frame per grid, on disk, so it outlives the process.
+*
+* ## Why not `@camstack/system`'s SnapshotDurableStore
+*
+* Because the shape is right and the reach is not: that class lives under
+* `builtins/snapshot/` and `@camstack/system` does not export it — a builtin's
+* internals are not an addon-facing module, and an addon that reached into one
+* would be importing another addon, which this repo forbids outright. What is
+* shared is the REASONING, and it is worth restating rather than linking,
+* because the failure it prevents here is the same one measured on 2026-09-17:
+* the cache is RAM, three server updates emptied it, and a camera that cannot
+* be asked for a fresh frame showed the courtesy card all morning with nothing
+* broken.
+*
+* A grid is that camera by construction. It has no fresh frame whenever nobody
+* is watching it, which is most of the time and is the entire point of D519.
+*
+* ## Shape
+*
+* One file per device under `ctx.dataDir` — `<nodeDataDir>/addons-data/
+* camera-grid`, which this addon owns exclusively — overwritten rather than
+* appended: what is wanted is A recent frame, not a history. A history here
+* would grow without a reaper and compete with the recordings for the disk.
+*
+* Writes are THROTTLED. A composition emits 10 frames a second and a process
+* restarts a few times a week; persisting every frame buys nothing and costs a
+* write per frame.
+*
+* NOTHING here throws. The caller already has its picture; persistence is a
+* bonus for the NEXT boot, and a disk that refuses must never cost a snapshot
+* that succeeded. A frame that cannot be read is reported ABSENT — absent is
+* the truth, and the courtesy card is the correct answer to it.
+*/
+/** One recent frame is the value; a newer one is not worth the disk. */
+var DEFAULT_MIN_INTERVAL_MS = 6e4;
+/** Its own subdirectory, so the addon's other state is never mistaken for a frame. */
+var SUBDIR = "last-frame";
+var GridLastFrameFileStore = class {
+	dir;
+	minIntervalMs;
+	now;
+	/** Last write per device, so the throttle survives without touching disk. */
+	lastWriteMs = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.dir = join(options.dataDir, SUBDIR);
+		this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+		this.now = options.now ?? (() => Date.now());
+	}
+	async put(deviceId, jpeg) {
+		if (jpeg.length === 0) return;
+		const at = this.now();
+		const previous = this.lastWriteMs.get(deviceId);
+		if (previous !== void 0 && at - previous < this.minIntervalMs) return;
+		try {
+			await promises.mkdir(this.dir, { recursive: true });
+			const target = this.pathFor(deviceId);
+			const staging = `${target}.writing`;
+			await promises.writeFile(staging, jpeg);
+			await promises.rename(staging, target);
+			this.lastWriteMs.set(deviceId, at);
+		} catch {}
+	}
+	async get(deviceId) {
+		try {
+			const jpeg = await promises.readFile(this.pathFor(deviceId));
+			return jpeg.length > 0 ? jpeg : null;
+		} catch {
+			return null;
+		}
+	}
+	pathFor(deviceId) {
+		return join(this.dir, `${String(deviceId)}.jpg`);
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-profiles.ts
+/**
+* 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.
+*/
+var GRID_CAM_STREAM_ID = "grid";
+/** Every profile a grid could conceivably compose, in descending quality. */
+var GRID_PROFILES = [
+	"high",
+	"mid",
+	"low"
+];
+/**
+* Canvas scale per profile. Named constants and not a computation: the numbers
+* are a policy (what a `mid` grid is FOR), and a policy that lives in an
+* expression is a policy nobody can find.
+*/
+var CANVAS_SCALE = {
+	high: 1,
+	mid: .5,
+	low: .25
+};
+/**
+* The smallest canvas a composition is allowed to shrink to. A grid of four
+* cells at 40x30 is not a cheaper picture, it is no picture.
+*/
+var MIN_CANVAS_WIDTH = 160;
+var MIN_CANVAS_HEIGHT = 90;
+/** The cam-stream id a grid publishes for one profile. */
+function gridCamStreamId(profile) {
+	return profile === "high" ? GRID_CAM_STREAM_ID : `${GRID_CAM_STREAM_ID}-${profile}`;
+}
+/** Even, floored, scaled by the profile. libx264 refuses an odd dimension. */
+function gridCanvasFor(canvas, profile) {
+	const scale = CANVAS_SCALE[profile];
+	return {
+		width: evenAtLeast(canvas.width * scale, MIN_CANVAS_WIDTH),
+		height: evenAtLeast(canvas.height * scale, MIN_CANVAS_HEIGHT)
+	};
+}
+function evenAtLeast(value, floor) {
+	const rounded = Math.max(floor, Math.round(value));
+	return rounded % 2 === 0 ? rounded : rounded + 1;
+}
+/**
+* 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.
+*/
+function offeredGridProfiles(input) {
+	const served = /* @__PURE__ */ new Map();
+	for (const deviceId of input.sourceDeviceIds) served.set(deviceId, input.profilesServedBy(deviceId));
+	return GRID_PROFILES.map((profile) => {
+		if (input.sourceDeviceIds.length === 0) return {
+			profile,
+			offered: false,
+			missingSources: []
+		};
+		const missingSources = input.sourceDeviceIds.filter((deviceId) => {
+			const profiles = served.get(deviceId);
+			return profiles === null || profiles === void 0 || !profiles.includes(profile);
+		});
+		return missingSources.length === 0 ? {
+			profile,
+			offered: true
+		} : {
+			profile,
+			offered: false,
+			missingSources
+		};
+	});
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-sentry-sources.ts
+function gridSourceDial(acquired) {
+	const sentryUrl = acquired.sentryUrl;
+	if (typeof sentryUrl === "string" && sentryUrl.length > 0) return {
+		url: sentryUrl,
+		pipelineKey: acquired.pipelineKey,
+		mode: "sentry"
+	};
+	return {
+		url: acquired.url,
+		pipelineKey: acquired.pipelineKey,
+		mode: "live"
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-snapshot.ts
+/**
+* Which of the three answers applies. Pure, so the rule can be read — and
+* sabotaged — without a socket, a file or an ffmpeg.
+*/
+function gridSnapshotAnswerFor(input) {
+	if (input.running) return { kind: "live" };
+	if (input.hasStoredFrame) return { kind: "stored" };
+	return {
+		kind: "none",
+		reason: "never-composed"
+	};
+}
+var GridSnapshotSource = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async getSnapshot(deviceId) {
+		const sessions = this.deps.sessionsFor(deviceId);
+		if (sessions.length === 0) return null;
+		const live = sessions.find((session) => session.isRunning()) ?? null;
+		const stored = await this.readStored(deviceId);
+		const answer = gridSnapshotAnswerFor({
+			running: live !== null,
+			hasStoredFrame: stored !== null
+		});
+		if (answer.kind === "live" && live !== null) {
+			const sampled = await this.sample(deviceId, live);
+			if (sampled !== null) {
+				await this.keep(deviceId, sampled);
+				return toImage(sampled);
+			}
+			if (stored !== null) return toImage(stored);
+			this.deps.logger.warn("camera grid: the composition is running but produced no frame, and none was kept", {
+				tags: { deviceId },
+				meta: { profile: live.profile }
+			});
+			return null;
+		}
+		if (answer.kind === "stored" && stored !== null) return toImage(stored);
+		this.deps.logger.warn("camera grid: no frame for this grid — nothing is composing it and none was ever kept", {
+			tags: { deviceId },
+			meta: {
+				reason: "never-composed",
+				profiles: sessions.length
+			}
+		});
+		return null;
+	}
+	async sample(deviceId, session) {
+		try {
+			const jpeg = await this.deps.sampleFrame(session);
+			if (jpeg !== null && jpeg.length > 0) return jpeg;
+			this.deps.logger.warn("camera grid: could not sample a frame from the live composition", {
+				tags: { deviceId },
+				meta: { profile: session.profile }
+			});
+			return null;
+		} catch (error) {
+			this.deps.logger.warn("camera grid: could not sample a frame from the live composition", {
+				tags: { deviceId },
+				meta: {
+					profile: session.profile,
+					error: errMsg(error)
+				}
+			});
+			return null;
+		}
+	}
+	async readStored(deviceId) {
+		try {
+			const jpeg = await this.deps.store.get(deviceId);
+			return jpeg !== null && jpeg.length > 0 ? jpeg : null;
+		} catch (error) {
+			this.deps.logger.warn("camera grid: the kept frame could not be read", {
+				tags: { deviceId },
+				meta: { error: errMsg(error) }
+			});
+			return null;
+		}
+	}
+	async keep(deviceId, jpeg) {
+		try {
+			await this.deps.store.put(deviceId, jpeg);
+		} catch (error) {
+			this.deps.logger.warn("camera grid: the composed frame could not be kept", {
+				tags: { deviceId },
+				meta: { error: errMsg(error) }
+			});
+		}
+	}
+};
+function toImage(jpeg) {
+	return {
+		base64: jpeg.toString("base64"),
+		contentType: "image/jpeg"
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-stream-relay.ts
+/**
+* The loopback HTTP endpoint the broker dials to consume a grid.
+*
+* A GET is the demand signal and the transport in one: the connection opening
+* is the first consumer arriving, and the connection closing is it leaving.
+* There is no other way to start or stop a composition, which is what makes
+* "off when nobody watches" true by construction rather than by a policy
+* somebody has to remember to apply.
+*
+* Bound on 127.0.0.1 only. The broker is hub-only and so is this addon
+* ({@link ../package.json} `placement: hub-only`), so the endpoint never needs
+* to be reachable from another node — and an MPEG-TS of every camera in the
+* grid is not something to expose on a LAN interface by accident.
+*/
+var PATH_PREFIX = "/grid/";
+var PATH_SUFFIX = GRID_WIRE_PATH_SUFFIX;
+/** How long a reader may refuse to drain before it is cut. */
+var SLOW_READER_MS = 5e3;
+function asProfile(raw) {
+	return GRID_PROFILES.find((profile) => profile === raw) ?? null;
+}
+/** `/grid/<instanceId>/<profile>.flv`, or `null` when it is anything else. */
+function parseGridStreamPath(url) {
+	const path = (url ?? "").split("?")[0] ?? "";
+	if (!path.startsWith(PATH_PREFIX) || !path.endsWith(PATH_SUFFIX)) return null;
+	const raw = path.slice(6, path.length - PATH_SUFFIX.length);
+	const at = raw.lastIndexOf("/");
+	if (at <= 0) return null;
+	const profile = asProfile(raw.slice(at + 1));
+	if (profile === null) return null;
+	try {
+		const instanceId = decodeURIComponent(raw.slice(0, at));
+		return instanceId.length > 0 ? {
+			instanceId,
+			profile
+		} : null;
+	} catch {
+		return null;
+	}
+}
+var GridStreamRelay = class {
+	deps;
+	server = null;
+	baseUrl = "";
+	open = /* @__PURE__ */ new Set();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async start() {
+		if (this.server) return;
+		const server = createServer((req, res) => {
+			const request = parseGridStreamPath(req.url);
+			if (req.method !== "GET" || request === null) {
+				res.writeHead(404).end();
+				return;
+			}
+			this.serve(request, res);
+		});
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(0, "127.0.0.1", resolve);
+		});
+		const address = server.address();
+		if (typeof address !== "object" || address === null) {
+			server.close();
+			throw new Error("camera-grid: the stream relay did not bind a TCP port");
+		}
+		this.server = server;
+		this.baseUrl = `http://127.0.0.1:${String(address.port)}`;
+	}
+	/** The URL a grid's catalog descriptor advertises. Empty before {@link start}. */
+	streamUrl(request) {
+		if (!this.baseUrl) throw new Error("camera-grid: the stream relay is not started");
+		const instance = encodeURIComponent(request.instanceId);
+		return `${this.baseUrl}${PATH_PREFIX}${instance}/${request.profile}${PATH_SUFFIX}`;
+	}
+	async serve(request, res) {
+		const { instanceId, profile } = request;
+		const session = this.deps.sessionFor(request);
+		if (session === null) {
+			this.deps.logger.warn("camera grid: a stream was requested for an unknown grid", { meta: {
+				instanceId,
+				profile
+			} });
+			res.writeHead(404).end();
+			return;
+		}
+		this.open.add(res);
+		let hold = null;
+		let stallTimer = null;
+		const sendHead = () => {
+			if (res.headersSent) return;
+			res.writeHead(200, {
+				"content-type": GRID_WIRE_CONTENT_TYPE,
+				"cache-control": "no-store",
+				connection: "keep-alive"
+			});
+			res.flushHeaders();
+		};
+		const clearStall = () => {
+			if (stallTimer === null) return;
+			clearTimeout(stallTimer);
+			stallTimer = null;
+		};
+		res.on("drain", clearStall);
+		try {
+			hold = await session.open({
+				onData: (chunk) => {
+					if (res.writableEnded || res.destroyed) return;
+					sendHead();
+					if (res.write(chunk) || stallTimer !== null) return;
+					stallTimer = setTimeout(() => {
+						stallTimer = null;
+						this.deps.logger.warn("camera grid: cutting a reader that never drained — it was holding the composition", {
+							tags: { deviceId: session.deviceId },
+							meta: {
+								instanceId,
+								profile,
+								stalledForMs: SLOW_READER_MS
+							}
+						});
+						res.destroy();
+					}, SLOW_READER_MS);
+					stallTimer.unref?.();
+				},
+				onClose: (reason) => {
+					this.deps.logger.info("camera grid: ending a reader", {
+						tags: { deviceId: session.deviceId },
+						meta: {
+							instanceId,
+							profile,
+							reason
+						}
+					});
+					clearStall();
+					res.end();
+				}
+			});
+		} catch (error) {
+			this.deps.logger.warn("camera grid: could not serve a grid stream", {
+				tags: { deviceId: session.deviceId },
+				meta: {
+					instanceId,
+					profile,
+					error: errMsg(error)
+				}
+			});
+			if (!res.headersSent) res.writeHead(503, { "content-type": "text/plain" });
+			res.end("camera grid unavailable");
+			this.open.delete(res);
+			return;
+		}
+		sendHead();
+		res.on("close", () => {
+			this.open.delete(res);
+			clearStall();
+			hold?.close();
+		});
+	}
+	async dispose() {
+		for (const res of this.open) res.destroy();
+		this.open.clear();
+		const server = this.server;
+		this.server = null;
+		this.baseUrl = "";
+		if (server) await new Promise((resolve) => server.close(() => resolve()));
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-stream-descriptor.ts
+/**
+* `profileHint` is load-bearing, not decoration.
+*
+* A device publishing a SINGLE stream with no hint is ranked by pixel count,
+* and a single stream ranks into `mid` — the slot `recordings` does not select
+* on its own (`high|mid` picks high), that `recordingsLow` ignores, and that
+* 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.
+*/
+function gridStreamDescriptor(input) {
+	return {
+		camStreamId: gridCamStreamId(input.profile),
+		kind: GRID_WIRE_STREAM_KIND,
+		url: input.url,
+		codec: "h264",
+		resolution: {
+			width: input.width,
+			height: input.height
+		},
+		fps: input.fps,
+		label: `Grid composition (${input.profile})`,
+		profileHint: input.profile,
+		autoEligible: true
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/flv-join.ts
+/**
+* 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.
+*/
+/** FLV tag header: type(1) + dataSize(3) + timestamp(3) + extended(1) + streamId(3). */
+var TAG_HEADER_BYTES = 11;
+/** Every tag is followed by its own size as a 4-byte trailer. */
+var TAG_TRAILER_BYTES = 4;
+/** `FLV` + version(1) + flags(1) + dataOffset(4), then PreviousTagSize0(4). */
+var FLV_HEADER_BYTES = 13;
+var TAG_TYPE_SCRIPT = 18;
+var TAG_TYPE_VIDEO = 9;
+/** High nibble of a video tag's first byte: 1 = key frame. */
+var VIDEO_FRAME_TYPE_KEY = 1;
+/** Second byte of an AVC video tag: 0 = sequence header, 1 = NALU. */
+var AVC_PACKET_TYPE_SEQUENCE_HEADER = 0;
+/**
+* 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.
+*/
+var FlvReader = class {
+	state;
+	detach;
+	constructor(state, detach) {
+		this.state = state;
+		this.detach = detach;
+	}
+	/** True until the preamble and a key frame have been handed over. */
+	get pending() {
+		return !this.state.started;
+	}
+	/** The bytes owed to this reader since the last call, or `null`. */
+	take() {
+		const queued = this.state.queued;
+		if (queued.length === 0) return null;
+		this.state.queued = [];
+		return queued.length === 1 ? queued[0] ?? null : Buffer.concat(queued);
+	}
+	/** Stop receiving. Anything queued is dropped with the reader. */
+	close() {
+		this.state.queued = [];
+		this.detach(this.state);
+	}
+};
+function parseVideoFlags(body) {
+	const first = body[0];
+	const second = body[1];
+	if (first === void 0) return {
+		isKeyFrame: false,
+		isSequenceHeader: false
+	};
+	const frameType = first >> 4;
+	const sequenceHeader = second === AVC_PACKET_TYPE_SEQUENCE_HEADER;
+	return {
+		isKeyFrame: frameType === VIDEO_FRAME_TYPE_KEY && !sequenceHeader,
+		isSequenceHeader: sequenceHeader
+	};
+}
+var FlvJoinPoint = class {
+	buffer = Buffer.alloc(0);
+	header = null;
+	script = null;
+	sequenceHeader = null;
+	readers = /* @__PURE__ */ new Set();
+	/** Attach a reader. It receives the preamble at the next key frame. */
+	join() {
+		const state = {
+			started: false,
+			queued: []
+		};
+		this.readers.add(state);
+		return new FlvReader(state, (gone) => this.readers.delete(gone));
+	}
+	/** Feed bytes from the encoder; each reader then takes what it is owed. */
+	accept(chunk) {
+		this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+		this.consumeHeader();
+		for (const tag of this.consumeTags()) this.dispatch(tag);
+	}
+	consumeHeader() {
+		if (this.header !== null) return;
+		if (this.buffer.length < FLV_HEADER_BYTES) return;
+		this.header = this.buffer.subarray(0, FLV_HEADER_BYTES);
+		this.buffer = this.buffer.subarray(FLV_HEADER_BYTES);
+	}
+	*consumeTags() {
+		if (this.header === null) return;
+		for (;;) {
+			if (this.buffer.length < TAG_HEADER_BYTES) return;
+			const dataSize = this.buffer.readUIntBE(1, 3);
+			const total = TAG_HEADER_BYTES + dataSize + TAG_TRAILER_BYTES;
+			if (this.buffer.length < total) return;
+			const bytes = this.buffer.subarray(0, total);
+			const type = bytes.readUInt8(0);
+			const body = bytes.subarray(TAG_HEADER_BYTES, TAG_HEADER_BYTES + dataSize);
+			const flags = type === TAG_TYPE_VIDEO ? parseVideoFlags(body) : {
+				isKeyFrame: false,
+				isSequenceHeader: false
+			};
+			this.buffer = this.buffer.subarray(total);
+			yield {
+				bytes,
+				type,
+				...flags
+			};
+		}
+	}
+	dispatch(tag) {
+		if (tag.type === TAG_TYPE_SCRIPT) this.script = tag.bytes;
+		if (tag.isSequenceHeader) this.sequenceHeader = tag.bytes;
+		for (const reader of this.readers) {
+			if (reader.started) {
+				reader.queued.push(tag.bytes);
+				continue;
+			}
+			if (!tag.isKeyFrame) continue;
+			const preamble = this.preamble();
+			if (preamble === null) continue;
+			reader.started = true;
+			reader.queued.push(preamble, tag.bytes);
+		}
+	}
+	/** The bytes that describe the stream, or `null` while any is still unknown. */
+	preamble() {
+		if (this.header === null || this.sequenceHeader === null) return null;
+		const parts = [this.header];
+		if (this.script !== null) parts.push(this.script);
+		parts.push(this.sequenceHeader);
+		return Buffer.concat(parts);
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-stream-session.ts
+var DEFAULT_LINGER_MS = 3e3;
+var GridStreamSession = class {
+	options;
+	consumers = /* @__PURE__ */ new Map();
+	/**
+	* The FLV stream's describing bytes, and where each reader may start.
+	*
+	* Rebuilt with every cold start: a new child means a new header and a new
+	* sequence header, and handing a reader the previous child's would decode
+	* noise. See `flv-join.ts` for why FLV needs this and MPEG-TS did not.
+	*/
+	join = new FlvJoinPoint();
+	running = null;
+	starting = null;
+	lingerTimer = null;
+	teardown = null;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+	}
+	get logTags() {
+		return { deviceId: this.options.deviceId };
+	}
+	/** The COMPOSITE camera's device id — what every log line about this grid is tagged with. */
+	get deviceId() {
+		return this.options.deviceId;
+	}
+	isRunning() {
+		return this.running !== null;
+	}
+	consumerCount() {
+		return this.consumers.size;
+	}
+	/** Resolves once any in-flight start or teardown has finished. For tests and shutdown. */
+	async settled() {
+		await this.starting?.catch(() => void 0);
+		await this.teardown;
+	}
+	/**
+	* Attach a consumer, starting the composition if this is the first one.
+	*
+	* @throws when the grid has nothing to compose, or a source could not be
+	* acquired. Both are LOGGED before they are thrown: a branch that accepts a
+	* consumer and then produces no media is exactly the branch that reads as
+	* "nothing ever happened".
+	*/
+	async open(consumer) {
+		if (this.disposed) throw new Error("camera-grid: this stream session is disposed");
+		this.cancelLinger();
+		this.consumers.set(consumer, this.join.join());
+		try {
+			await this.ensureRunning();
+		} catch (error) {
+			this.dropConsumer(consumer);
+			this.scheduleTeardownIfIdle();
+			throw error;
+		}
+		let closed = false;
+		return { close: () => {
+			if (closed) return;
+			closed = true;
+			this.dropConsumer(consumer);
+			this.options.deps.logger.debug("camera grid: consumer left", {
+				tags: this.logTags,
+				meta: { remaining: this.consumers.size }
+			});
+			this.scheduleTeardownIfIdle();
+		} };
+	}
+	/**
+	* Attach to a composition that is ALREADY running, or refuse.
+	*
+	* The whole difference from {@link open} is the refusal, and the refusal is
+	* the feature. A snapshot of a grid is a frame of the composition — which
+	* only exists while something is watching it — and the operator's rule is
+	* that producing a thumbnail must never be the reason N cameras get dialled.
+	* `open()` would start the composition, acquire every source, and on a
+	* battery camera that is a wake nobody asked for.
+	*
+	* `null` is a real answer: "there is no composition to take a frame from",
+	* which the caller turns into the stored last frame, or into nothing.
+	*/
+	openIfRunning(consumer) {
+		if (this.disposed || this.running === null) return null;
+		this.cancelLinger();
+		this.consumers.set(consumer, this.join.join());
+		let closed = false;
+		return { close: () => {
+			if (closed) return;
+			closed = true;
+			this.dropConsumer(consumer);
+			this.scheduleTeardownIfIdle();
+		} };
+	}
+	/** Forget a consumer AND the reader holding bytes on its behalf. */
+	dropConsumer(consumer) {
+		this.consumers.get(consumer)?.close();
+		this.consumers.delete(consumer);
+	}
+	/**
+	* The child ended on its own. Every consumer is told WHY — a stream that
+	* simply stops is indistinguishable from a stalled one at the far end.
+	*/
+	onChildEnded(reason) {
+		if (this.running === null) return;
+		this.options.deps.logger.warn("camera grid: the composition ended", {
+			tags: this.logTags,
+			meta: {
+				reason,
+				consumers: this.consumers.size
+			}
+		});
+		for (const [consumer, reader] of [...this.consumers]) {
+			reader.close();
+			consumer.onClose(reason);
+		}
+		this.consumers.clear();
+		this.teardown = this.stopNow();
+	}
+	async dispose() {
+		this.disposed = true;
+		this.cancelLinger();
+		for (const [consumer, reader] of [...this.consumers]) {
+			reader.close();
+			consumer.onClose("shutdown");
+		}
+		this.consumers.clear();
+		await this.settled();
+		await this.stopNow();
+	}
+	async ensureRunning() {
+		if (this.running) return this.running;
+		if (this.starting) return this.starting;
+		const starting = this.startCold();
+		this.starting = starting;
+		try {
+			const state = await starting;
+			this.running = state;
+			return state;
+		} finally {
+			if (this.starting === starting) this.starting = null;
+		}
+	}
+	async startCold() {
+		const plan = this.options.resolvePlan();
+		if (plan === null || plan.layout.cells.length === 0 || plan.sourceDeviceIds.length === 0) {
+			this.options.deps.logger.warn("camera grid: a consumer attached but the grid has no cells — nothing to compose", { tags: this.logTags });
+			throw new Error("camera-grid: this grid has no cells to compose");
+		}
+		const acquired = [];
+		try {
+			for (const sourceDeviceId of plan.sourceDeviceIds) acquired.push(await this.options.deps.acquireSource(sourceDeviceId));
+		} catch (error) {
+			this.options.deps.logger.error("camera grid: could not acquire every source — releasing the ones already taken", {
+				tags: this.logTags,
+				meta: {
+					acquired: acquired.length,
+					error: errMsg(error)
+				}
+			});
+			await this.releaseAll(acquired);
+			throw error;
+		}
+		try {
+			this.join = new FlvJoinPoint();
+			for (const consumer of this.consumers.keys()) this.consumers.set(consumer, this.join.join());
+			const child = await this.options.deps.startChild(plan, acquired);
+			child.stdout.on("data", (chunk) => {
+				this.join.accept(chunk);
+				for (const [consumer, reader] of this.consumers) {
+					const owed = reader.take();
+					if (owed !== null) consumer.onData(owed);
+				}
+			});
+			this.options.deps.logger.info("camera grid: composition started", {
+				tags: this.logTags,
+				meta: {
+					cells: plan.layout.cells.length,
+					sources: [...plan.sourceDeviceIds],
+					canvas: `${String(plan.layout.width)}x${String(plan.layout.height)}`,
+					fps: plan.fps
+				}
+			});
+			return {
+				child,
+				sources: acquired
+			};
+		} catch (error) {
+			this.options.deps.logger.error("camera grid: the composition failed to start", {
+				tags: this.logTags,
+				meta: { error: errMsg(error) }
+			});
+			await this.releaseAll(acquired);
+			throw error;
+		}
+	}
+	scheduleTeardownIfIdle() {
+		if (this.consumers.size > 0) return;
+		if (this.running === null && this.starting === null) return;
+		const lingerMs = this.options.deps.lingerMs ?? DEFAULT_LINGER_MS;
+		if (lingerMs <= 0) {
+			this.teardown = this.stopNow();
+			return;
+		}
+		this.cancelLinger();
+		this.lingerTimer = setTimeout(() => {
+			this.lingerTimer = null;
+			if (this.consumers.size > 0) return;
+			this.teardown = this.stopNow();
+		}, lingerMs);
+		this.lingerTimer.unref?.();
+	}
+	cancelLinger() {
+		if (this.lingerTimer === null) return;
+		clearTimeout(this.lingerTimer);
+		this.lingerTimer = null;
+	}
+	async stopNow() {
+		const state = this.running;
+		this.running = null;
+		if (state === null) return;
+		try {
+			await state.child.stop();
+		} catch (error) {
+			this.options.deps.logger.warn("camera grid: the composition did not stop cleanly", {
+				tags: this.logTags,
+				meta: { error: errMsg(error) }
+			});
+		}
+		await this.releaseAll(state.sources);
+		this.options.deps.logger.info("camera grid: composition stopped — no consumers left", {
+			tags: this.logTags,
+			meta: { released: state.sources.length }
+		});
+	}
+	async releaseAll(sources) {
+		for (const source of sources) try {
+			await this.options.deps.releaseSource(source.pipelineKey);
+		} catch (error) {
+			this.options.deps.logger.error("camera grid: could NOT release a source handle", {
+				tags: this.logTags,
+				meta: {
+					pipelineKey: source.pipelineKey,
+					error: errMsg(error)
+				}
+			});
+		}
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/silence-analysis.ts
+/**
+* Every analyzer a composite camera is created with switched OFF.
+*
+* A grid is a picture we composed from cameras that are ALREADY analyzed. Running
+* detection on the composite would pay for the same subjects a second time, and
+* would attribute them to a camera that does not exist as a viewpoint — a person
+* detected in the bottom-right cell is a person on THAT camera, not on the grid.
+*
+* `motion-detection` sits first deliberately: it is the one that holds the decode
+* session open, so its absence is the difference between a grid costing a
+* composition and costing a full decode pipeline. Same ordering, and the same
+* reason, as the Terminal addon's list.
+*
+* Called ONLY on creation. An operator who deliberately turns detection back on
+* for a grid must win, and a reconcile that re-asserted every pass would silently
+* overrule them once a minute.
+*/
+var GRID_SILENCED_CAP_NAMES = [
+	"motion-detection",
+	DETECTION_PIPELINE_CAP_NAME,
+	AUDIO_ANALYSIS_CAP_NAME
+];
+/**
+* Resolve the addon currently providing `capName` for this device, from the
+* device's OWN bindings. `listBindableCapsForDeviceType` answers for the device
+* TYPE and would happily name a wrapper that is not the one bound here.
+*
+* `null` when the cap is not bound at all — not an error: a deployment with no
+* audio analyzer has nothing to switch off, and demanding one would make every
+* grid creation fail on a perfectly valid hub.
+*/
+async function resolveBoundWrapper(api, deviceId, capName) {
+	const bindings = await api.deviceManager.getBindings.query({ deviceId });
+	for (const entry of bindings.entries) {
+		if (entry.capName !== capName) continue;
+		if (entry.kind !== "wrapped") continue;
+		if (entry.providerAddonId === "") return null;
+		return entry.providerAddonId;
+	}
+	return null;
+}
+/**
+* @throws if a cap IS bound and the write to its authority failed. The composite
+* would then be running a full analyzer over a picture whose subjects are already
+* counted elsewhere — exactly the cost this removes — and a silent version of
+* that failure is unfindable.
+*/
+async function silenceAnalysisFor(deps, deviceId) {
+	const failures = [];
+	for (const capName of GRID_SILENCED_CAP_NAMES) try {
+		const wrapperAddonId = await resolveBoundWrapper(deps.api, deviceId, capName);
+		if (wrapperAddonId === null) {
+			deps.logger.debug("camera grid: no analyzer bound for this capability", {
+				tags: { deviceId },
+				meta: { capName }
+			});
+			continue;
+		}
+		await deps.api.deviceManager.setWrapperActive.mutate({
+			deviceId,
+			capName,
+			wrapperAddonId,
+			active: false
+		});
+		deps.logger.info("camera grid: analyzer switched off at its authority", {
+			tags: { deviceId },
+			meta: {
+				capName,
+				wrapperAddonId
+			}
+		});
+	} catch (err) {
+		failures.push(`${capName}: ${errMsg(err)}`);
+		deps.logger.error("camera grid: could NOT switch an analyzer off", {
+			tags: { deviceId },
+			meta: {
+				capName,
+				error: errMsg(err)
+			}
+		});
+	}
+	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-filter-graph.ts
+var CANVAS_LABEL = "canvas";
+var OUT_LABEL = "grid";
+/** Full-frame within a tolerance, i.e. nothing to crop. */
+var FULL_FRAME_EPSILON = 1e-6;
+function isFullFrame(rect) {
+	return Math.abs(rect.x) < FULL_FRAME_EPSILON && Math.abs(rect.y) < FULL_FRAME_EPSILON && Math.abs(rect.width - 1) < FULL_FRAME_EPSILON && Math.abs(rect.height - 1) < FULL_FRAME_EPSILON;
+}
+/**
+* yuv420p subsamples chroma 2x2, so an odd width or height is rejected by every
+* encoder we use. Rounding here lets the reason be stated; rounding inside the
+* child is a start-up failure with no context.
+*/
+function toEven(value) {
+	const rounded = Math.round(value);
+	const even = rounded % 2 === 0 ? rounded : rounded - 1;
+	return Math.max(2, even);
+}
+function assertWithin(rect, what, cellIndex) {
+	if (rect.x < 0 || rect.y < 0 || rect.width <= 0 || rect.height <= 0 || rect.x + rect.width > 1.000001 || rect.y + rect.height > 1.000001) throw new Error(`camera-grid: cell ${cellIndex} falls ${what} (x=${rect.x} y=${rect.y} w=${rect.width} h=${rect.height}) — ffmpeg would render this as a silently clipped picture`);
+}
+/**
+* `crop` resolved against the source's OWN size at runtime (`iw`/`ih`), never
+* against a resolution guessed here. That is what makes the stored rectangle
+* survive a source that changes resolution.
+*/
+function cropExpression(source) {
+	return `crop=iw*${source.width}:ih*${source.height}:iw*${source.x}:ih*${source.y}`;
+}
+function buildGridFilterGraph(layout) {
+	if (layout.cells.length === 0) throw new Error("camera-grid: a composite needs at least one cell to emit anything");
+	const steps = [`color=c=black:s=${layout.width}x${layout.height}:d=1[${CANVAS_LABEL}]`];
+	const cellLabels = [];
+	layout.cells.forEach((cell, index) => {
+		assertWithin(cell.source, "outside its source", index);
+		assertWithin(cell.cell, "outside the canvas", index);
+		const targetWidth = toEven(cell.cell.width * layout.width);
+		const targetHeight = toEven(cell.cell.height * layout.height);
+		const label = `c${index}`;
+		const filters = [...isFullFrame(cell.source) ? [] : [cropExpression(cell.source)], `scale=${targetWidth}:${targetHeight}`];
+		steps.push(`[${cell.inputIndex}:v]${filters.join(",")}[${label}]`);
+		cellLabels.push(label);
+	});
+	let base = CANVAS_LABEL;
+	layout.cells.forEach((cell, index) => {
+		const x = Math.round(cell.cell.x * layout.width);
+		const y = Math.round(cell.cell.y * layout.height);
+		const out = index === layout.cells.length - 1 ? OUT_LABEL : `s${index}`;
+		steps.push(`[${base}][${cellLabels[index]}]overlay=${x}:${y}[${out}]`);
+		base = out;
+	});
+	return {
+		graph: steps.join(";"),
+		videoOutLabel: OUT_LABEL
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-stream-invocation.ts
+/**
+* The encoder preset. `veryfast` because a composite is the one encode in the
+* cluster whose input cost already scales with the number of cameras in it —
+* the decode side of a 2x2 is four decodes — so the encode side is where a
+* cheap default matters most.
+*/
+var PRESET = "veryfast";
+/**
+* `-tune zerolatency`, and this one is worth several SECONDS.
+*
+* x264's defaults hold frames before emitting any: a rate-control lookahead of
+* ~40 frames plus B-frames. At a composite's 10 fps that lookahead alone is
+* about four seconds of picture sitting inside the encoder — the operator saw
+* it as "ritardi di secondi" and it was not the network, the relay or the
+* broker. `zerolatency` sets `rc-lookahead=0`, `sync-lookahead=0` and
+* `bframes=0`, which is exactly the trade a live composite wants: a few percent
+* more bitrate for the same picture, in exchange for the encoder emitting each
+* frame as it arrives.
+*
+* It is not a preset. `veryfast` says how hard the encoder searches; this says
+* how long it is allowed to WAIT, and the two are independent.
+*/
+var TUNE = "zerolatency";
+/** yuv420p: the only pixel format every consumer of a CamStack profile reads. */
+var PIXEL_FORMAT = "yuv420p";
+/**
+* Key-frame cadence, in seconds.
+*
+* Two things ride on this and they pull the same way. A recorder cuts its
+* segments on a key frame, so a long GOP produces long segments and a scrub
+* that lands far from where the operator clicked. And every consumer — the
+* broker's reader included — starts at a key frame, so the GOP is the WORST
+* CASE wait before a grid appears at all: at two seconds a viewer could stare
+* at nothing for two seconds after pressing play.
+*
+* One second halves that wait. It costs bitrate (an IDR is expensive and there
+* are now twice as many), which is why it is not lower: below a second the
+* bitrate paid buys a wait nobody can feel.
+*/
+var GOP_SECONDS = 1;
+/**
+* `-analyzeduration` / `-probesize`, well under ffmpeg's 5 s / 5 MB defaults.
+*
+* Safe on RTSP specifically: the SDP already declares the codec, so the probe
+* has nothing to discover. It matters more here than anywhere else in the repo
+* because the probes are PARALLEL inputs of one child — the composite emits
+* nothing until the LAST of them has finished, so the default budget is paid
+* once per grid, at the slowest source's pace.
+*/
+var ANALYZE_DURATION_US = 1e6;
+var PROBE_SIZE_BYTES = 1e6;
+function inputPlanFor(source) {
+	return {
+		url: source.url,
+		rtspTransport: "tcp",
+		fflags: ["+discardcorrupt+nobuffer"],
+		lowDelay: true,
+		analyzeDurationUs: ANALYZE_DURATION_US,
+		probeSizeBytes: PROBE_SIZE_BYTES
+	};
+}
+/**
+* @throws when the layout addresses an input the sources do not contain, or
+* when there is nothing to compose. Both are plan errors: ffmpeg would refuse
+* them at start-up with a message about a filter pad, which names the graph
+* rather than the configuration that produced it.
+*/
+function gridStreamInvocation(input) {
+	if (input.sources.length === 0 || input.layout.cells.length === 0) throw new Error("camera-grid: a composite needs at least one cell with a source before it can emit anything");
+	for (const cell of input.layout.cells) if (cell.inputIndex < 0 || cell.inputIndex >= input.sources.length) throw new Error(`camera-grid: cell addresses input ordinal ${cell.inputIndex}, but only ${input.sources.length} input(s) were acquired`);
+	const graph = buildGridFilterGraph(input.layout);
+	const [first, ...rest] = input.sources;
+	if (first === void 0) throw new Error("camera-grid: a composite needs at least one cell with a source");
+	const video = {
+		kind: "encode",
+		encoder: input.encoder,
+		preset: PRESET,
+		tune: TUNE,
+		pixelFormat: PIXEL_FORMAT,
+		fps: input.fps,
+		gopFrames: input.fps * GOP_SECONDS,
+		bitrateKbps: input.bitrateKbps,
+		scale: null
+	};
+	return {
+		logLevel: "error",
+		decodeHwAccel: input.decodeHwAccel,
+		input: inputPlanFor(first),
+		extraInputs: rest.map(inputPlanFor),
+		filterGraph: graph,
+		video,
+		audio: { kind: "none" },
+		threadCount: 0,
+		outputArgs: [],
+		sink: {
+			kind: "stdout",
+			container: "flv"
+		}
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-child.ts
+/**
+* Spawning the composition, through the ONE primitive.
+*
+* `FfmpegProcess` (`@camstack/types`) owns spawn, the first-data deadline, the
+* hardware→software retry, exit classification and the bounded restart. This
+* file owns only the PLUMBING — which bytes go where — because that is the one
+* thing the primitive deliberately does not own.
+*
+* `maxRestarts: 0`. A composite is demand-driven: if the child dies, the
+* session tells every consumer why and tears down, and the consumer's next read
+* starts a cold one with freshly acquired sources. A restart inside the process
+* would reuse broker handles that may already have been released.
+*/
+/** No first-data deadline retry loop: one attempt, and the session hears about it. */
+var FIRST_DATA_TIMEOUT_MS = 15e3;
+async function startGridChild(ctx, plan, sources, onEnded) {
+	const invocation = (decodeHwAccel) => gridStreamInvocation({
+		layout: plan.layout,
+		sources: plan.sourceDeviceIds.map((deviceId, index) => ({
+			deviceId,
+			url: sources[index]?.url ?? ""
+		})),
+		decodeHwAccel,
+		encoder: plan.encoder,
+		fps: plan.fps,
+		bitrateKbps: plan.bitrateKbps
+	});
+	let stdout = null;
+	const process = new FfmpegProcess({
+		binaryPath: ctx.binaryPath,
+		buildArgs: (decodeHwAccel) => buildFfmpegArgs(invocation(decodeHwAccel)),
+		decodeHwAccel: plan.decodeHwAccel,
+		logger: ctx.logger,
+		deviceId: ctx.deviceId,
+		role: "camera-grid",
+		tags: {
+			cells: plan.layout.cells.length,
+			inputs: plan.sourceDeviceIds.length
+		},
+		firstDataTimeoutMs: FIRST_DATA_TIMEOUT_MS,
+		maxRestarts: 0,
+		onChild: (child) => {
+			if (child.stdout) stdout = child.stdout;
+			child.stderr?.on("data", () => {});
+		},
+		onExit: (exit) => {
+			onEnded(exit.classification);
+		}
+	});
+	await process.start();
+	if (stdout === null) {
+		await process.stop();
+		throw new Error("camera-grid: the composition child produced no stdout to read");
+	}
+	return {
+		stdout,
+		stop: async () => {
+			await process.stop();
+		}
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/addon.ts
+var INTEGRATION_NAME = "Camera Grids";
+var RECONCILE_MS = 6e4;
+var DEFAULTS = {
+	cameraGrids: [],
+	cameraGridTombstones: []
+};
+/** One session per (grid, profile). A grid composes each profile separately. */
+function sessionKey(instanceId, profile) {
+	return `${instanceId}::${profile}`;
+}
+/**
+* One grid's composition of one profile, and enough about it for the snapshot
+* to choose between them without reaching into the session.
+*/
+var GridSessionEntry = class {
+	instanceId;
+	profile;
+	session;
+	constructor(instanceId, profile, session) {
+		this.instanceId = instanceId;
+		this.profile = profile;
+		this.session = session;
+	}
+	isRunning() {
+		return this.session.isRunning();
+	}
+};
+var CameraGridAddon = class extends BaseAddon {
+	relay = null;
+	reconcileTimer = null;
+	/** Keyed by {@link sessionKey} — one composition per grid per profile. */
+	sessions = /* @__PURE__ */ new Map();
+	deviceIdByInstanceId = /* @__PURE__ */ new Map();
+	tombstones = /* @__PURE__ */ new Set();
+	/**
+	* 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.
+	*/
+	offersByInstanceId = /* @__PURE__ */ new Map();
+	snapshots = null;
+	frameSampler = null;
+	ffmpegBinaryPath = "ffmpeg";
+	integrationId;
+	constructor() {
+		super({ ...DEFAULTS });
+	}
+	async onInitialize() {
+		this.replaceTombstones(this.config.cameraGridTombstones);
+		await this.normalizeRows();
+		if (declarationOwnerNodeId(this.ctx.kernel.localNodeId) === "hub") {
+			this.ffmpegBinaryPath = await this.resolveFfmpegBinaryPath();
+			const relay = new GridStreamRelay({
+				logger: this.ctx.logger.child("relay"),
+				sessionFor: (request) => this.sessionFor(request)
+			});
+			await relay.start();
+			this.relay = relay;
+			this.frameSampler = new GridFrameSampler({
+				binaryPath: this.ffmpegBinaryPath,
+				logger: this.ctx.logger.child("snapshot")
+			});
+			this.snapshots = new GridSnapshotSource({
+				logger: this.ctx.logger.child("snapshot"),
+				sessionsFor: (deviceId) => this.sessionsForDevice(deviceId),
+				sampleFrame: async (session) => this.sampleFrame(session),
+				store: new GridLastFrameFileStore({ dataDir: this.ctx.dataDir })
+			});
+			installGridCameraRuntime({
+				descriptorsFor: (instanceId) => this.descriptorsFor(instanceId),
+				getLayout: (deviceId) => this.gridViewFor(deviceId),
+				saveLayout: async (patch) => this.saveGridLayout(patch),
+				getSnapshot: async (deviceId) => this.getSnapshot(deviceId)
+			});
+			await this.reconcile().catch((error) => {
+				this.ctx.logger.warn("camera grid: initial reconciliation failed — will retry", { meta: { error: errMsg(error) } });
+			});
+			this.reconcileTimer = setInterval(() => {
+				this.reconcile().catch((error) => {
+					this.ctx.logger.warn("camera grid: reconciliation failed", { meta: { error: errMsg(error) } });
+				});
+			}, RECONCILE_MS);
+			this.reconcileTimer.unref?.();
+		}
+		return { providers: [{
+			capability: cameraGridLayoutCapability,
+			provider: buildGridLayoutNativeProvider({
+				getLayout: (deviceId) => this.gridViewFor(deviceId),
+				saveLayout: (patch) => this.saveGridLayout(patch)
+			})
+		}] };
+	}
+	async onConfigChanged() {
+		this.replaceTombstones(this.config.cameraGridTombstones);
+		await this.normalizeRows();
+		await this.applyLayoutChanges();
+		if (this.relay) this.reconcile().catch((error) => {
+			this.ctx.logger.warn("camera grid: reconciliation after a config change failed", { meta: { error: errMsg(error) } });
+		});
+	}
+	async onShutdown() {
+		if (this.reconcileTimer) clearInterval(this.reconcileTimer);
+		this.reconcileTimer = null;
+		installGridCameraRuntime(null);
+		await this.relay?.dispose();
+		this.relay = null;
+		for (const entry of this.sessions.values()) await entry.session.dispose();
+		this.sessions.clear();
+		this.snapshots = null;
+		this.frameSampler = null;
+	}
+	instances() {
+		return readGridInstances(this.config.cameraGrids, (message) => {
+			this.ctx.logger.warn(message);
+		});
+	}
+	instanceById(instanceId) {
+		return this.instances().find((instance) => instance.id === instanceId);
+	}
+	/**
+	* 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.
+	*/
+	async normalizeRows() {
+		const normalized = normalizeGridRows(this.config.cameraGrids, () => crypto.randomUUID());
+		if (!normalized.changed) return;
+		this.ctx.logger.info("camera grid: completing operator-created rows", { meta: {
+			rows: normalized.rows.length,
+			wasRows: this.config.cameraGrids.length
+		} });
+		await this.updateGlobalSettings({ cameraGrids: [...normalized.rows] });
+	}
+	replaceTombstones(stableIds) {
+		this.tombstones.clear();
+		for (const stableId of stableIds) if (typeof stableId === "string" && stableId.length > 0) this.tombstones.add(stableId);
+	}
+	async reconcile() {
+		if (!this.relay) return;
+		const instances = this.instances();
+		const declarations = buildGridCameraDeclarations(instances);
+		await this.refreshProfileOffers(instances);
+		await this.retireWithdrawnSessions(instances);
+		const result = await new DeclaredDevices({
+			logger: this.ctx.logger.child("declaration"),
+			addonId: this.ctx.id,
+			devices: this.ctx.kernel.devices,
+			localNodeId: this.ctx.kernel.localNodeId,
+			getIntegration: async (addonId) => {
+				const integration = await this.ctx.api.integrations.getByAddonId.query({ addonId });
+				this.integrationId = integration?.id ?? null;
+				return integration;
+			},
+			createIntegration: async (input) => {
+				const integration = await this.ctx.api.integrations.create.mutate(input);
+				this.integrationId = integration.id;
+				return integration;
+			},
+			updateIntegration: async ({ id, info }) => {
+				await this.ctx.api.integrations.update.mutate({
+					id,
+					info,
+					skipRestart: true
+				});
+			},
+			listOwnDevices: async () => {
+				return gridCameraReconciliationIndex(await this.ctx.api.deviceManager.listAll.query({ addonId: this.ctx.id }), this.integrationId, declarations, this.tombstones);
+			}
+		}).reconcile({
+			integrationName: INTEGRATION_NAME,
+			placement: "hub",
+			devices: declarations.map((camera) => ({
+				stableId: camera.stableId,
+				name: camera.name,
+				type: DeviceType.Camera,
+				DeviceClass: GridCameraDevice,
+				config: camera.config,
+				role: "camera-grid"
+			}))
+		});
+		const declaredByStableId = new Map(declarations.map((camera) => [camera.stableId, camera]));
+		for (const outcome of result.devices) {
+			if (!(outcome.device instanceof GridCameraDevice)) continue;
+			const declaration = declaredByStableId.get(outcome.stableId);
+			if (!declaration) continue;
+			const config = outcome.device.config;
+			if (config.get("instanceId") !== declaration.config.instanceId) await config.setAll(declaration.config);
+			const instanceId = declaration.config.instanceId;
+			this.deviceIdByInstanceId.set(instanceId, outcome.device.id);
+			this.ensureSessions(instanceId, outcome.device.id);
+			if (outcome.created) await this.silenceAnalysis(outcome.device.id);
+			outcome.device.setAddonOnline(true);
+		}
+	}
+	async silenceAnalysis(deviceId) {
+		try {
+			await silenceAnalysisFor({
+				api: this.ctx.api,
+				logger: this.ctx.logger
+			}, deviceId);
+		} catch (error) {
+			this.ctx.logger.error("camera grid: a new grid could not be silenced", {
+				tags: { deviceId },
+				meta: { error: errMsg(error) }
+			});
+		}
+	}
+	/**
+	* 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.
+	*/
+	async refreshProfileOffers(instances) {
+		let slots;
+		try {
+			slots = await this.ctx.api.streamBroker.listAllProfileSlots.query();
+		} catch (error) {
+			this.ctx.logger.warn("camera grid: could not read the broker profile slots - keeping the last answer", { meta: {
+				error: errMsg(error),
+				grids: instances.length
+			} });
+			return;
+		}
+		const servedBy = /* @__PURE__ */ new Map();
+		for (const slot of slots) {
+			if (slot.sourceCamStreamId === null) continue;
+			const profiles = servedBy.get(slot.deviceId) ?? [];
+			profiles.push(slot.profile);
+			servedBy.set(slot.deviceId, profiles);
+		}
+		for (const instance of instances) {
+			const offers = offeredGridProfiles({
+				sourceDeviceIds: [...new Set(instance.cells.map((cell) => cell.deviceId))],
+				profilesServedBy: (deviceId) => servedBy.get(deviceId) ?? null
+			});
+			const previous = this.offersByInstanceId.get(instance.id);
+			this.offersByInstanceId.set(instance.id, offers);
+			this.logRefusals(instance, offers, previous);
+		}
+	}
+	/**
+	* 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.
+	*/
+	logRefusals(instance, offers, previous) {
+		if (previous !== void 0 && JSON.stringify(previous) === JSON.stringify(offers)) return;
+		const deviceId = this.deviceIdByInstanceId.get(instance.id) ?? 0;
+		for (const offer of offers) {
+			if (offer.offered) continue;
+			if (offer.missingSources.length === 0) continue;
+			this.ctx.logger.info("camera grid: a profile is NOT on offer", {
+				tags: { deviceId },
+				meta: {
+					instanceId: instance.id,
+					profile: offer.profile,
+					missingSources: [...offer.missingSources]
+				}
+			});
+		}
+		this.ctx.logger.info("camera grid: published profiles", {
+			tags: { deviceId },
+			meta: {
+				instanceId: instance.id,
+				offered: offers.filter((offer) => offer.offered).map((offer) => offer.profile)
+			}
+		});
+	}
+	offeredProfiles(instanceId) {
+		const offers = this.offersByInstanceId.get(instanceId);
+		if (offers === void 0) return null;
+		return offers.filter((offer) => offer.offered).map((offer) => offer.profile);
+	}
+	ensureSessions(instanceId, deviceId) {
+		const offered = this.offeredProfiles(instanceId) ?? [];
+		for (const profile of GRID_PROFILES) {
+			const key = sessionKey(instanceId, profile);
+			if (!offered.includes(profile)) {
+				const stale = this.sessions.get(key);
+				if (stale) {
+					this.sessions.delete(key);
+					stale.session.dispose();
+				}
+				continue;
+			}
+			if (this.sessions.has(key)) continue;
+			const session = this.makeSession(instanceId, deviceId, profile);
+			this.sessions.set(key, new GridSessionEntry(instanceId, profile, session));
+		}
+	}
+	makeSession(instanceId, deviceId, profile) {
+		const childContext = {
+			binaryPath: this.ffmpegBinaryPath,
+			logger: this.ctx.logger,
+			deviceId
+		};
+		const session = new GridStreamSession({
+			deviceId,
+			deps: {
+				logger: this.ctx.logger,
+				acquireSource: async (sourceDeviceId) => {
+					const dial = gridSourceDial(await this.ctx.api.streamBroker.getStreamWithCodec.mutate({
+						deviceId: sourceDeviceId,
+						video: "copy",
+						audio: "none",
+						profile,
+						tag: `camera-grid:${String(deviceId)}:${profile}`
+					}));
+					this.ctx.logger.info("camera grid: source acquired", {
+						tags: { deviceId },
+						meta: {
+							instanceId,
+							profile,
+							sourceDeviceId,
+							mode: dial.mode,
+							...dial.mode === "sentry" ? { why: "battery source - the sentry dial never asks for the camera" } : {}
+						}
+					});
+					return {
+						url: dial.url,
+						pipelineKey: dial.pipelineKey
+					};
+				},
+				releaseSource: async (pipelineKey) => {
+					await this.ctx.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey });
+				},
+				startChild: async (plan, sources) => startGridChild(childContext, plan, sources, (reason) => {
+					session.onChildEnded(reason);
+				})
+			},
+			resolvePlan: () => {
+				const instance = this.instanceById(instanceId);
+				if (!instance) return null;
+				return gridPlanFor(instance, {
+					encoder: "libx264",
+					decodeHwAccel: null,
+					canvas: gridCanvasFor({
+						width: instance.width,
+						height: instance.height
+					}, profile)
+				});
+			}
+		});
+		return session;
+	}
+	/** The session a dial is asking for, or `null` - which the relay answers 404 to. */
+	sessionFor(request) {
+		return this.sessions.get(sessionKey(request.instanceId, request.profile))?.session ?? null;
+	}
+	/** This grid's sessions, in DESCENDING quality - the snapshot takes the first running one. */
+	sessionsForDevice(deviceId) {
+		const instanceId = this.instanceIdForDevice(deviceId);
+		if (instanceId === null) return [];
+		const entries = [];
+		for (const profile of GRID_PROFILES) {
+			const entry = this.sessions.get(sessionKey(instanceId, profile));
+			if (entry) entries.push(entry);
+		}
+		return entries;
+	}
+	/** A grid that is gone stops immediately - it must not keep N sources dialled. */
+	async retireWithdrawnSessions(instances) {
+		const live = new Set(instances.filter((instance) => instance.enabled).map((i) => i.id));
+		for (const [key, entry] of [...this.sessions]) {
+			if (live.has(entry.instanceId)) continue;
+			this.ctx.logger.info("camera grid: retiring a withdrawn grid", {
+				tags: { deviceId: this.deviceIdByInstanceId.get(entry.instanceId) ?? 0 },
+				meta: {
+					instanceId: entry.instanceId,
+					profile: entry.profile
+				}
+			});
+			this.sessions.delete(key);
+			await entry.session.dispose();
+		}
+		for (const instanceId of [...this.deviceIdByInstanceId.keys()]) {
+			if (live.has(instanceId)) continue;
+			this.deviceIdByInstanceId.delete(instanceId);
+			this.offersByInstanceId.delete(instanceId);
+		}
+	}
+	/**
+	* 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.
+	*/
+	async applyLayoutChanges() {
+		for (const entry of this.sessions.values()) {
+			if (!entry.session.isRunning()) continue;
+			this.ctx.logger.info("camera grid: the layout changed - restarting the composition", {
+				tags: { deviceId: this.deviceIdByInstanceId.get(entry.instanceId) ?? 0 },
+				meta: {
+					instanceId: entry.instanceId,
+					profile: entry.profile
+				}
+			});
+			entry.session.onChildEnded("layout-changed");
+		}
+	}
+	async getSnapshot(deviceId) {
+		const snapshots = this.snapshots;
+		if (snapshots === null) return null;
+		return snapshots.getSnapshot(deviceId);
+	}
+	/**
+	* 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.
+	*/
+	async sampleFrame(entry) {
+		const sampler = this.frameSampler;
+		if (sampler === null) return null;
+		return sampler.sample(entry.session.deviceId, { attach: (onChunk) => entry.session.openIfRunning({
+			onData: onChunk,
+			onClose: () => {}
+		}) });
+	}
+	/**
+	* 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.
+	*/
+	descriptorsFor(instanceId) {
+		const instance = this.instanceById(instanceId);
+		const relay = this.relay;
+		const offered = this.offeredProfiles(instanceId);
+		if (!instance || !relay || offered === null) return null;
+		return offered.map((profile) => {
+			const canvas = gridCanvasFor({
+				width: instance.width,
+				height: instance.height
+			}, profile);
+			return gridStreamDescriptor({
+				profile,
+				width: canvas.width,
+				height: canvas.height,
+				fps: instance.fps,
+				url: relay.streamUrl({
+					instanceId,
+					profile
+				})
+			});
+		});
+	}
+	instanceIdForDevice(deviceId) {
+		for (const [instanceId, id] of this.deviceIdByInstanceId) if (id === deviceId) return instanceId;
+		return null;
+	}
+	instanceForDevice(deviceId) {
+		const instanceId = this.instanceIdForDevice(deviceId);
+		return instanceId === null ? null : this.instanceById(instanceId) ?? null;
+	}
+	gridViewFor(deviceId) {
+		const instance = this.instanceForDevice(deviceId);
+		if (!instance) return null;
+		return {
+			instanceId: instance.id,
+			deviceId,
+			name: instance.name,
+			width: instance.width,
+			height: instance.height,
+			fps: instance.fps,
+			cells: instance.cells.map((cell) => ({
+				deviceId: cell.deviceId,
+				source: cell.source,
+				cell: cell.cell
+			})),
+			profiles: (this.offersByInstanceId.get(instance.id) ?? []).map((offer) => ({
+				profile: offer.profile,
+				offered: offer.offered,
+				missingSources: offer.offered ? [] : [...offer.missingSources]
+			}))
+		};
+	}
+	async saveGridLayout(input) {
+		const instance = this.instanceForDevice(input.deviceId);
+		if (!instance) throw new Error(`camera-grid: device ${String(input.deviceId)} is not a grid camera`);
+		const updated = {
+			...instance,
+			...input.name !== void 0 ? { name: input.name.trim() } : {},
+			...input.width !== void 0 ? { width: input.width } : {},
+			...input.height !== void 0 ? { height: input.height } : {},
+			...input.fps !== void 0 ? { fps: input.fps } : {},
+			cells: input.cells.map((cell) => ({ ...cell }))
+		};
+		this.ctx.logger.info("camera grid: layout saved", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				cells: updated.cells.length,
+				sources: [...new Set(updated.cells.map((cell) => cell.deviceId))],
+				canvas: `${String(updated.width)}x${String(updated.height)}`
+			}
+		});
+		await this.updateGlobalSettings({ cameraGrids: this.config.cameraGrids.map((row) => row["id"] === instance.id ? {
+			...row,
+			...updated
+		} : row) });
+		await this.refreshProfileOffers(this.instances());
+		this.ensureSessions(instance.id, input.deviceId);
+		const view = this.gridViewFor(input.deviceId);
+		if (!view) throw new Error("camera-grid: the grid vanished while it was being saved");
+		return view;
+	}
+	async resolveFfmpegBinaryPath() {
+		try {
+			return await this.ctx.deps.ensureFfmpeg();
+		} catch (error) {
+			this.ctx.logger.error("camera grid: ensureFfmpeg() failed to provision ffmpeg — falling back to PATH \"ffmpeg\"", { meta: { error: errMsg(error) } });
+			return "ffmpeg";
+		}
+	}
+	/**
+	* 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.
+	*/
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "camera-grids",
+			title: "Camera grids",
+			description: "A grid is a composite camera: several cameras composed into one picture, recorded and played back like any other camera. Create one here with a name; open its camera to lay it out. Object detection is switched OFF on a new grid — the cameras it is composed from are already analysed.",
+			columns: 1,
+			fields: [this.field({
+				type: "editable-array",
+				key: "cameraGrids",
+				label: "Grids",
+				default: [],
+				maxRows: 16,
+				addLabel: "Add grid",
+				emptyMessage: "No camera grids yet.",
+				rowTitleTemplate: "{name}",
+				defaultItem: {
+					name: "",
+					enabled: true
+				},
+				itemFields: [{
+					type: "text",
+					key: "name",
+					label: "Name",
+					required: true
+				}, {
+					type: "boolean",
+					key: "enabled",
+					label: "Enabled",
+					description: "A disabled grid withdraws its camera.",
+					default: true
+				}]
+			})]
+		}] });
+	}
+	integrationSettingSections() {
+		return ["camera-grids"];
+	}
+};
+//#endregion
+export { CameraGridAddon, CameraGridAddon as default, GRID_CAM_STREAM_ID, GRID_PROFILES, GRID_SILENCED_CAP_NAMES, GridCameraDevice, GridFrameSampler, GridLastFrameFileStore, GridSnapshotSource, GridStreamRelay, GridStreamSession, buildGridCameraDeclarations, buildGridFilterGraph, gridCamStreamId, gridCameraReconciliationIndex, gridCanvasFor, gridPlanFor, gridSnapshotAnswerFor, gridSourceDial, gridStreamDescriptor, gridStreamInvocation, installGridCameraRuntime, newGridCameraStableId, normalizeGridRows, offeredGridProfiles, parseGridStreamPath, readGridInstances, silenceAnalysisFor, startGridChild };