@camstack/system 1.2.263 → 1.2.265

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

@@ -1,4 +1,4 @@
-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-CQ7ItBIG.mjs";
+import { $t as streamCatalogCapability, At as motionCapability, Jt as snapshotCapability, Pn as EventCategory, U as cameraGridLayoutCapability, Y as declarationOwnerNodeId, an as errMsg, b as MOTION_CLOSE_AFTER_MS, bn as createEvent, dn as DeviceFeature, f as DERIVED_CAMERA_SILENCED_CAP_NAMES, i as BaseDevice, on as buildFfmpegArgs, p as DeclaredDevices, pn as DeviceType, sn as BaseAddon, wn as hydrateSchema } from "../../dist-Ck0rjYOQ.mjs";
 import { z } from "zod";
 import { FfmpegProcess } from "@camstack/types/node";
 import { join } from "node:path";
@@ -192,6 +192,10 @@ var GridCameraDevice = class extends BaseDevice {
 			getSnapshot: async ({ deviceId }) => activeRuntime().getSnapshot(deviceId),
 			invalidateCache: async () => {}
 		});
+		this.ctx.registerNativeCap(motionCapability, {
+			getStatus: async ({ deviceId }) => activeRuntime().motionStatus(deviceId),
+			isDetected: async ({ deviceId }) => activeRuntime().motionStatus(deviceId).detected
+		});
 		this.markOnline(true);
 	}
 	catalog() {
@@ -395,6 +399,330 @@ function normalizeGridRows(raw, mintId) {
 	};
 }
 //#endregion
+//#region src/builtins/camera-grid/grid-activity-mirror.ts
+/**
+* What a grid says about ITSELF, kept from what its sources said.
+*
+* ## Why the grid answers at all
+*
+* A grid is a camera, and the viewer already knows how to light a camera: the
+* motion ring keys off `motion.on-motion-changed` filtered by `deviceId`, the
+* audio one off `pipeline.audio-inference-result`. So the grid does not need a
+* new channel, a new cap or a line of app code — it needs to answer those
+* questions about its own device id. The operator set both rules: motion is on
+* if AT LEAST ONE source has it, and the audio level is the LOUDEST of them.
+*
+* It is derived from the SOURCES' events and never from the composed picture.
+* Analysing the composite would be a second motion authority for cameras that
+* already have one, and a decode this addon does not pay today.
+*
+* ## The falling edge is the whole difficulty
+*
+* Bus events are telemetry and may be dropped (D8/D11). A lost `detected:
+* false` would leave a grid lit for ever, and the grid has no phase machine to
+* produce a falling edge of its own — a real camera's comes from the pipeline
+* runner, which a grid deliberately does not run.
+*
+* So a source's motion is remembered WITH ITS TIME and expires on its own. That
+* is D49's shape: in-memory state refreshed off the event path, never a gate
+* that re-reads something fallible in order to decide. A dropped clear costs a
+* ring that stays lit until the expiry instead of for ever, and a subject that
+* is genuinely still there keeps renewing it.
+*
+* The expiry is `MOTION_CLOSE_AFTER_MS`, imported and not re-spelled: it is the
+* system's one answer to "how long after the last push is a camera still
+* moving", and a second number here would be a second authority disagreeing
+* with the first on exactly the cameras that make up the grid.
+*/
+/**
+* How long an audio reading counts as current.
+*
+* The analyzer emits one per window per camera, so a source that has gone quiet
+* simply stops arriving — there is no "silence" event to wait for. Without a
+* window the loudest reading of the day would be the grid's level for ever.
+* Chosen to span several analysis windows so an ordinary gap does not blink the
+* level away, and to be far shorter than a person notices a stale ring.
+*/
+var AUDIO_FRESH_MS = 5e3;
+var GridActivityMirror = class {
+	motion = /* @__PURE__ */ new Map();
+	audio = /* @__PURE__ */ new Map();
+	lastDetectedAt = null;
+	/** One source's motion push. `detected: false` is as important as `true`. */
+	noteMotion(sourceDeviceId, detected, atMs) {
+		this.motion.set(sourceDeviceId, {
+			detected,
+			atMs
+		});
+		if (detected) this.lastDetectedAt = Math.max(this.lastDetectedAt ?? 0, atMs);
+	}
+	/** One source's audio window. `dbfs` is the level, on the analyzer's scale. */
+	noteAudio(sourceDeviceId, dbfs, atMs) {
+		this.audio.set(sourceDeviceId, {
+			dbfs,
+			atMs
+		});
+	}
+	/**
+	* Drop every source this grid no longer composes.
+	*
+	* A cell removed while its camera was moving would otherwise hold the grid
+	* lit until the expiry, for a picture the source is not even in.
+	*/
+	keepOnly(sourceDeviceIds) {
+		const keep = new Set(sourceDeviceIds);
+		const motionIds = Array.from(this.motion.keys());
+		const audioIds = Array.from(this.audio.keys());
+		for (const id of motionIds) if (!keep.has(id)) this.motion.delete(id);
+		for (const id of audioIds) if (!keep.has(id)) this.audio.delete(id);
+	}
+	/** At least one source moving, as of `nowMs`. */
+	motionAt(nowMs) {
+		let detected = false;
+		for (const state of this.motion.values()) {
+			if (!state.detected) continue;
+			if (nowMs - state.atMs > 15e3) continue;
+			detected = true;
+			break;
+		}
+		return {
+			detected,
+			lastDetectedAt: this.lastDetectedAt
+		};
+	}
+	/**
+	* The loudest CURRENT reading, or `null` when nothing fresh has been heard.
+	*
+	* Null and not `-Infinity`: "nobody has reported a level" is a different
+	* answer from "it is silent", and a number here would have the viewer draw a
+	* level for a grid whose sources are not being analysed at all.
+	*/
+	loudestAt(nowMs) {
+		let loudest = null;
+		for (const state of this.audio.values()) {
+			if (nowMs - state.atMs > AUDIO_FRESH_MS) continue;
+			if (loudest === null || state.dbfs > loudest) loudest = state.dbfs;
+		}
+		return loudest;
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-detection-mapping.ts
+/**
+* Where this detection lands on the canvas — once per cell that shows it.
+*
+* Empty is a real answer: the subject is in a part of the source this grid does
+* not display, or the frame arrived with no size to measure against. Neither is
+* a reason to guess.
+*/
+function mapDetectionToCanvas(input) {
+	const { width: frameW, height: frameH } = input.sourceFrame;
+	if (frameW <= 0 || frameH <= 0) return [];
+	const left = input.bbox.x / frameW;
+	const top = input.bbox.y / frameH;
+	const right = (input.bbox.x + input.bbox.width) / frameW;
+	const bottom = (input.bbox.y + input.bbox.height) / frameH;
+	const out = [];
+	for (const { source, cell } of input.cells) {
+		if (source.width <= 0 || source.height <= 0) continue;
+		const l = Math.max(left, source.x);
+		const t = Math.max(top, source.y);
+		const r = Math.min(right, source.x + source.width);
+		const b = Math.min(bottom, source.y + source.height);
+		if (r <= l || b <= t) continue;
+		const cx = (l - source.x) / source.width;
+		const cy = (t - source.y) / source.height;
+		const cw = (r - l) / source.width;
+		const ch = (b - t) / source.height;
+		out.push({
+			x: (cell.x + cx * cell.width) * input.canvas.width,
+			y: (cell.y + cy * cell.height) * input.canvas.height,
+			width: cw * cell.width * input.canvas.width,
+			height: ch * cell.height * input.canvas.height
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-activity.ts
+/**
+* The grid's own motion / audio / detection, forwarded from its sources.
+*
+* ## Why the grid speaks a camera's language instead of a new one
+*
+* The operator asked for the grid's tile to light up in the viewer exactly as a
+* camera's card does, with NO app change. The app already knows how: it filters
+* `motion.on-motion-changed` by `deviceId` for the motion ring,
+* `pipeline.audio-inference-result` for the audio one, and `detection.result`
+* for the detection one. So the grid answers those three questions about its
+* own device id, in the same shapes. Nothing new is invented, and nothing in
+* the viewer is touched.
+*
+* The rules are the operator's: motion if AT LEAST ONE source has it, and the
+* LOUDEST source's level for audio.
+*
+* ## What speaking a camera's language costs, and why it is safe here
+*
+* Those categories have other listeners, and emitting on them makes the grid a
+* motion source for the whole system. Checked, one by one, before shipping:
+* the recorder's event capture, the HomeKit and Alexa exports and the Home
+* Assistant export are all per-device and do nothing until an operator enables
+* them for this camera — and if an operator DOES export a grid to HomeKit, a
+* grid reporting motion is correct, not a surprise.
+*
+* The one listener with no gate of its own was `pipeline-analytics`, which
+* would have opened a motion EPISODE per grid, duplicating the rows its sources
+* already write. Its gate turned out to be the `pipeline-analytics` WRAPPER
+* BINDING, so the answer is the one the operator gave: a derived camera is
+* created with the analytics wrappers OFF (`grid-analytics-defaults.ts`).
+* That is a binding, not a new flag, so an operator who wants a grid analysed
+* can simply turn it back on.
+*
+* ## Detection carries boxes whether or not anyone wanted them
+*
+* `detection.result` is the same event the viewer draws BOXES from, so a grid
+* that reports detections reports boxes. Sending the source's own pixel box
+* would draw it against the composed canvas at confidently wrong coordinates,
+* so every box is carried through the cell geometry first
+* (`grid-detection-mapping.ts`) and lands where the subject actually is.
+*/
+/**
+* One mirror per grid, and the emission that follows an update.
+*
+* Deliberately NOT one mirror per source: the question is always "is THIS grid
+* lit", and a source shared by two grids answers it twice, differently, because
+* the other cells differ.
+*/
+var GridActivityForwarder = class {
+	deps;
+	mirrors = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** A source camera's motion push. */
+	onSourceMotion(sourceDeviceId, detected, atMs) {
+		for (const grid of this.deps.gridsForSource(sourceDeviceId)) {
+			const mirror = this.mirrorFor(grid);
+			const before = mirror.motionAt(atMs).detected;
+			mirror.noteMotion(sourceDeviceId, detected, atMs);
+			const after = mirror.motionAt(atMs);
+			if (after.detected === before) continue;
+			this.emitMotion(grid.deviceId, after, atMs);
+		}
+	}
+	/** A source camera's audio window. */
+	onSourceAudio(sourceDeviceId, dbfs, atMs) {
+		for (const grid of this.deps.gridsForSource(sourceDeviceId)) {
+			const mirror = this.mirrorFor(grid);
+			mirror.noteAudio(sourceDeviceId, dbfs, atMs);
+			const loudest = mirror.loudestAt(atMs);
+			if (loudest === null) continue;
+			this.emitAudio(grid.deviceId, loudest, atMs);
+		}
+	}
+	/** A source camera's detection frame, with its boxes in SOURCE pixels. */
+	onSourceDetections(frame) {
+		for (const grid of this.deps.gridsForSource(frame.deviceId)) {
+			const cells = grid.cellsForSource(frame.deviceId);
+			if (cells.length === 0) continue;
+			const detections = [];
+			for (const detection of frame.detections) for (const bbox of mapDetectionToCanvas({
+				bbox: detection.bbox,
+				sourceFrame: {
+					width: frame.width,
+					height: frame.height
+				},
+				canvas: grid.canvas,
+				cells
+			})) {
+				const { refinedBbox: _refined, mask: _mask, ...rest } = detection;
+				detections.push({
+					...rest,
+					bbox
+				});
+			}
+			if (detections.length === 0) continue;
+			this.emitDetections(grid, frame, detections);
+		}
+	}
+	/** The grid's own motion answer, for `motion.getStatus`. */
+	motionStatusFor(deviceId, nowMs) {
+		return this.mirrors.get(deviceId)?.motionAt(nowMs) ?? {
+			detected: false,
+			lastDetectedAt: null
+		};
+	}
+	/** Drop the mirror of a grid that no longer exists. */
+	forget(deviceId) {
+		this.mirrors.delete(deviceId);
+	}
+	mirrorFor(grid) {
+		let mirror = this.mirrors.get(grid.deviceId);
+		if (mirror === void 0) {
+			mirror = new GridActivityMirror();
+			this.mirrors.set(grid.deviceId, mirror);
+		}
+		mirror.keepOnly(grid.sourceDeviceIds);
+		return mirror;
+	}
+	source(deviceId) {
+		return {
+			type: "device",
+			id: deviceId,
+			addonId: this.deps.addonId,
+			deviceId
+		};
+	}
+	emitMotion(deviceId, state, atMs) {
+		const payload = {
+			deviceId,
+			detected: state.detected,
+			timestamp: atMs,
+			source: "onboard"
+		};
+		this.deps.eventBus.emit(createEvent(EventCategory.MotionOnMotionChanged, this.source(deviceId), payload));
+		this.deps.logger.debug("camera grid: motion forwarded", {
+			tags: { deviceId },
+			meta: { detected: state.detected }
+		});
+	}
+	emitAudio(deviceId, dbfs, atMs) {
+		const payload = {
+			deviceId,
+			frame: {
+				kind: "audio-window",
+				windowId: `grid-${String(deviceId)}-${String(atMs)}`,
+				deviceId,
+				timestamp: atMs,
+				startMs: atMs,
+				endMs: atMs,
+				level: {
+					rms: 0,
+					dbfs
+				},
+				detections: []
+			},
+			nodeId: "hub"
+		};
+		this.deps.eventBus.emit(createEvent(EventCategory.PipelineAudioInferenceResult, this.source(deviceId), payload));
+	}
+	emitDetections(grid, sourceFrame, detections) {
+		const payload = {
+			frame: {
+				kind: "frame",
+				frameId: `grid-${String(grid.deviceId)}-${sourceFrame.frameId}`,
+				deviceId: grid.deviceId,
+				timestamp: sourceFrame.timestamp,
+				width: grid.canvas.width,
+				height: grid.canvas.height,
+				detections
+			},
+			analysisResults: []
+		};
+		this.deps.eventBus.emit(createEvent(EventCategory.DetectionResult, this.source(grid.deviceId), payload));
+	}
+};
+//#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";
@@ -1397,11 +1725,14 @@ var GridStreamSession = class {
 * 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
-];
+/**
+* The list lives in `@camstack/types` now, and this is an alias rather than a
+* second copy. There WERE two — this one and the Terminal addon's — and they
+* had drifted: neither named `pipeline-analytics`, the one cap with no gate of
+* its own, which is what a grid forwarding its sources' motion would have used
+* to write a duplicate motion episode per event.
+*/
+var GRID_SILENCED_CAP_NAMES = DERIVED_CAMERA_SILENCED_CAP_NAMES;
 /**
 * Resolve the addon currently providing `capName` for this device, from the
 * device's OWN bindings. `listBindableCapsForDeviceType` answers for the device
@@ -1464,267 +1795,561 @@ 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-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;
+//#region src/builtins/camera-grid/grid-canvas.ts
+/** Bytes one yuv420p frame of this size occupies. */
+function yuv420pSize(width, height) {
+	return width * height + 2 * (width / 2) * (height / 2);
 }
 /**
-* 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.
+* Round DOWN to even.
+*
+* Down and not nearest: a tile that rounded UP would claim a row of samples the
+* decoder was never asked to produce, and the copy would either overrun or be
+* refused at the moment the picture is wanted.
 */
-function toEven(value) {
-	const rounded = Math.round(value);
-	const even = rounded % 2 === 0 ? rounded : rounded - 1;
-	return Math.max(2, even);
+function evenDown(value) {
+	return Math.max(0, Math.floor(value / 2) * 2);
 }
-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`);
+var GridCanvas = class {
+	width;
+	height;
+	buffer;
+	lumaBytes;
+	chromaBytes;
+	constructor(width, height) {
+		this.width = width;
+		this.height = height;
+		this.lumaBytes = width * height;
+		this.chromaBytes = width / 2 * (height / 2);
+		this.buffer = Buffer.alloc(yuv420pSize(width, height));
+		this.clear();
+	}
+	/**
+	* Legible black — Y 0, chroma 128 (neutral).
+	*
+	* `Buffer.alloc` already zeroes, and zeroed CHROMA is not black: it is a
+	* strong green. A cell nobody has filled yet has to look like an empty cell,
+	* not like a fault.
+	*/
+	clear() {
+		this.buffer.fill(0, 0, this.lumaBytes);
+		this.buffer.fill(128, this.lumaBytes);
+	}
+	/**
+	* Copy one decoded tile in at `origin`.
+	*
+	* Returns false — never throws, never writes a partial tile — when the tile
+	* does not fit, is the wrong size for the dimensions it claims, or sits on an
+	* odd boundary. This runs on the output tick, so a bad frame from one source
+	* must cost that source's rectangle and nothing else.
+	*/
+	blit(tile, size, origin) {
+		if (!isEven(size.width) || !isEven(size.height)) return false;
+		if (!isEven(origin.x) || !isEven(origin.y)) return false;
+		if (size.width <= 0 || size.height <= 0) return false;
+		if (origin.x < 0 || origin.y < 0) return false;
+		if (origin.x + size.width > this.width) return false;
+		if (origin.y + size.height > this.height) return false;
+		if (tile.length !== yuv420pSize(size.width, size.height)) return false;
+		for (let row = 0; row < size.height; row += 1) {
+			const from = row * size.width;
+			const to = (origin.y + row) * this.width + origin.x;
+			tile.copy(this.buffer, to, from, from + size.width);
+		}
+		const tileLuma = size.width * size.height;
+		const tileChroma = size.width / 2 * (size.height / 2);
+		const halfW = size.width / 2;
+		const halfH = size.height / 2;
+		const canvasHalfW = this.width / 2;
+		for (let plane = 0; plane < 2; plane += 1) {
+			const tileBase = tileLuma + plane * tileChroma;
+			const canvasBase = this.lumaBytes + plane * this.chromaBytes;
+			for (let row = 0; row < halfH; row += 1) {
+				const from = tileBase + row * halfW;
+				const to = canvasBase + (origin.y / 2 + row) * canvasHalfW + origin.x / 2;
+				tile.copy(this.buffer, to, from, from + halfW);
+			}
+		}
+		return true;
+	}
+};
+function isEven(value) {
+	return Number.isInteger(value) && value % 2 === 0;
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-tile-feed.ts
+/**
+* One source's decoded tiles, of which only the LATEST is ever wanted.
+*
+* ## Why dropping is the point, not a compromise
+*
+* ffmpeg's `overlay` consumes one frame per input per output frame, so an input
+* that got ahead of another stays ahead for the life of the child — that is the
+* tile gap. A canvas asks a different question: "what does this camera look
+* like NOW". Everything behind the newest frame is not a backlog to work
+* through, it is history, and dropping it is what keeps every tile at the same
+* moment however unevenly their frames arrive.
+*
+* It is also the only bound on memory here. A decoder child that outruns the
+* output tick — or a tick that stalls — would otherwise grow an unbounded queue
+* of raw frames, and a raw frame is 345 KB at 640x360.
+*
+* ## The last frame is HELD
+*
+* A tick that finds nothing new redraws what was there. A tile must not blink
+* because a source was 40 ms late, and a source that has genuinely stopped is a
+* still picture — which is legible, and which the snapshot path already treats
+* as the honest answer for a camera that is not sending.
+*/
+var GridTileFeed = class {
+	frameBytes;
+	partial = Buffer.alloc(0);
+	newest = null;
+	fresh = false;
+	constructor(frameBytes) {
+		this.frameBytes = frameBytes;
+	}
+	/** Feed bytes from the decoder. Any whole frames inside replace the newest. */
+	push(chunk) {
+		let buf = this.partial.length === 0 ? chunk : Buffer.concat([this.partial, chunk]);
+		while (buf.length >= this.frameBytes) {
+			this.newest = Buffer.from(buf.subarray(0, this.frameBytes));
+			this.fresh = true;
+			buf = buf.subarray(this.frameBytes);
+		}
+		this.partial = buf.length === 0 ? Buffer.alloc(0) : Buffer.from(buf);
+	}
+	/** The newest whole frame, or `null` while none has arrived. */
+	latest() {
+		this.fresh = false;
+		return this.newest;
+	}
+	/** Has a new frame arrived since the last {@link latest}? */
+	hasFresh() {
+		return this.fresh;
+	}
+	/** For the bound in the spec: one frame plus at most a partial one. */
+	bufferedBytes() {
+		return (this.newest?.length ?? 0) + this.partial.length;
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-compositor.ts
+/**
+* The composition, driven by the OUTPUT's clock.
+*
+* ## What this replaces, and why it is the only thing that works
+*
+* `overlay` pairs its inputs BY PTS and ffmpeg gives each input pts 0 at its
+* own first frame, so two sources that joined at different moments compose
+* different moments for the life of the child. Measured at 4-5 s on this hub,
+* drifting over hours as the sources' key-frame phases slide through each other.
+* Every cheaper fix was tried and measured: `-use_wallclock_as_timestamps`
+* re-times by arrival and wrecked the pacing; `-copyts` changes nothing because
+* the broker re-bases each session (both restreams report `pts_time:0`), so
+* there is no shared timeline to align against; and serving each dial from the
+* newest key frame it already holds only moves the offsets into the past,
+* because those key frames are of different ages.
+*
+* Here there is nothing to pair. Every tick asks each source "what do you look
+* like NOW" and the answer is whatever arrived last. The gap is zero by
+* construction rather than by tuning.
+*
+* ## 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 —
+* instead of the whole grid waiting for the slowest source's first key frame,
+* which is what the ~9 s cold start was.
+*
+* ## What it costs
+*
+* The same N decodes ffmpeg already paid, in N children instead of one, plus
+* one strided memcpy per tile per tick (`grid-canvas.ts`). It does NOT reuse the
+* frames the detection pipeline decodes: those live in per-session decode
+* workers behind two process boundaries, the shm plane that once joined them was
+* removed on 2026-07-16, and what the pipeline retains is a model-sized view
+* (320x180 JPEG, on demand), not a tile.
+*/
+var GridCompositor = class {
+	deps;
+	canvas;
+	/** Keyed by tile id — unique per CELL, because one camera can hold two. */
+	placed = /* @__PURE__ */ new Map();
+	closed = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.canvas = new GridCanvas(deps.plan.canvas.width, deps.plan.canvas.height);
+		for (const tile of deps.plan.tiles) this.placed.set(tile.id, {
+			tile,
+			feed: new GridTileFeed(tile.frameBytes)
+		});
+	}
+	/**
+	* Raw bytes from one decoder output.
+	*
+	* A tile this composition has no rectangle for is IGNORED, never thrown on: a
+	* child that outlives a layout change would otherwise take the tick down with
+	* it, and the tick is what every other cell depends on.
+	*/
+	onTile(tileId, chunk) {
+		this.placed.get(tileId)?.feed.push(chunk);
+	}
+	/**
+	* Compose and emit one frame. Returns what the sink said about back-pressure.
+	*
+	* Every tile is redrawn, fresh or not: a tile that produced nothing this tick
+	* is a still picture, not a hole, and clearing it would make a late source
+	* flicker. The canvas is never cleared between ticks for the same reason.
+	*/
+	tick() {
+		if (this.closed) return true;
+		for (const { tile, feed } of this.placed.values()) {
+			const frame = feed.latest();
+			if (frame === null) continue;
+			this.canvas.blit(frame, tile.size, tile.origin);
+		}
+		return this.deps.write(this.canvas.buffer);
+	}
+	/** After this, a tick emits nothing — a dead child must not keep writing. */
+	close() {
+		this.closed = true;
+	}
+};
+//#endregion
+//#region src/builtins/camera-grid/grid-tile-plan.ts
+/**
+* The operator's layout, as one decoder child per CELL.
+*
+* ## Why per cell, when `grid-plan.ts` dedupes per source
+*
+* The single ffmpeg that this replaces made a camera used by two cells ONE
+* input, because decoding it twice doubles the expensive half of the job. A
+* compositor cannot do that with the same shape: this repo has exactly one
+* ffmpeg argv builder (`scripts/check-ffmpeg-primitive.ts`, Rule 1) and it
+* expresses one output per process, so a source feeding two differently cropped
+* and differently scaled tiles needs two children.
+*
+* The trade is small and worth stating: since D528 every source is read at its
+* CHEAPEST stream, so the duplicate is a second 640x360 sub-stream decode, not a
+* second 4 MP one. Teaching the builder several outputs would buy that back, and
+* is the right change to make if a grid ever shows one camera many times — it is
+* deliberately not made for a case that costs this little.
+*
+* ## Why the tile is scaled in the DECODER
+*
+* ffmpeg's scaler is SIMD and already there. Scaling in this process would be a
+* per-pixel loop in JavaScript, on the event loop that also answers the grid's
+* RPCs. Handing each child the exact pixel size its rectangle needs makes the
+* composition a strided memcpy (`grid-canvas.ts`) and keeps the only per-pixel
+* work where it belongs.
+*
+* ## Even, and snapped DOWN
+*
+* yuv420p subsamples chroma 2x2, so an odd origin lands a tile's chroma half a
+* sample off its luma — which TINTS the tile instead of breaking it, and
+* survives review. Sizes round DOWN so a tile never claims a row the decoder
+* was not asked to produce; a cell that rounds away to nothing is dropped
+* rather than emitted at zero size, because a zero-size output is an ffmpeg
+* start-up failure that would take the whole grid with it.
+*/
+/** Smallest tile worth decoding. Below this it is not a cheaper picture, it is none. */
+var MIN_TILE_PX = 2;
+/** The one pixel format the canvas is in, so a blit is a copy and not a convert. */
+var TILE_PIXEL_FORMAT = "yuv420p";
+var FULL_FRAME_EPSILON$1 = 1e-6;
+function isFullFrame$1(rect) {
+	return Math.abs(rect.x) < FULL_FRAME_EPSILON$1 && Math.abs(rect.y) < FULL_FRAME_EPSILON$1 && Math.abs(rect.width - 1) < FULL_FRAME_EPSILON$1 && Math.abs(rect.height - 1) < FULL_FRAME_EPSILON$1;
 }
 /**
 * `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.
+* against a resolution guessed here — which is what lets a stored rectangle
+* survive a camera that changes resolution under us.
 */
-function cropExpression(source) {
+function cropExpression$1(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;
-	});
+function buildGridTilePlan(input) {
+	const tiles = [];
+	for (const [index, cell] of input.cells.entries()) {
+		const width = evenDown(cell.cell.width * input.canvas.width);
+		const height = evenDown(cell.cell.height * input.canvas.height);
+		if (width < MIN_TILE_PX || height < MIN_TILE_PX) continue;
+		const x = Math.min(evenDown(cell.cell.x * input.canvas.width), evenDown(input.canvas.width - width));
+		const y = Math.min(evenDown(cell.cell.y * input.canvas.height), evenDown(input.canvas.height - height));
+		tiles.push({
+			id: `cell-${String(index)}`,
+			deviceId: cell.deviceId,
+			size: {
+				width,
+				height
+			},
+			origin: {
+				x,
+				y
+			},
+			frameBytes: yuv420pSize(width, height),
+			filter: [
+				...isFullFrame$1(cell.source) ? [] : [cropExpression$1(cell.source)],
+				`scale=${String(width)}:${String(height)}`,
+				`format=${TILE_PIXEL_FORMAT}`
+			].join(",")
+		});
+	}
 	return {
-		graph: steps.join(";"),
-		videoOutLabel: OUT_LABEL
+		canvas: input.canvas,
+		tiles
 	};
 }
 //#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";
+//#region src/builtins/camera-grid/grid-compositor-invocation.ts
+/** See D527: the probe returns from the SDP instead of reading media. */
+var ANALYZE_DURATION_US$1 = 0;
+var PROBE_SIZE_BYTES$1 = 32;
+var PRESET$1 = "veryfast";
+var TUNE$1 = "zerolatency";
+var GOP_SECONDS$1 = 1;
+/** One tile's decoder: dial in, raw yuv420p frames out. */
+function gridTileDecoderInvocation(input) {
+	return {
+		logLevel: "error",
+		decodeHwAccel: null,
+		input: {
+			url: input.url,
+			rtspTransport: "tcp",
+			fflags: ["+discardcorrupt"],
+			lowDelay: true,
+			analyzeDurationUs: ANALYZE_DURATION_US$1,
+			probeSizeBytes: PROBE_SIZE_BYTES$1
+		},
+		video: {
+			kind: "raw",
+			pixelFormat: TILE_PIXEL_FORMAT,
+			filter: input.tile.filter,
+			fps: input.fps
+		},
+		audio: { kind: "none" },
+		threadCount: 0,
+		outputArgs: [],
+		sink: {
+			kind: "stdout",
+			container: "rawvideo"
+		}
+	};
+}
+/** The canvas encoder: raw frames on stdin, one compressed stream out. */
+function gridCanvasEncoderInvocation(input) {
+	const video = {
+		kind: "encode",
+		encoder: input.encoder,
+		preset: PRESET$1,
+		tune: TUNE$1,
+		pixelFormat: TILE_PIXEL_FORMAT,
+		fps: input.fps,
+		gopFrames: input.fps * GOP_SECONDS$1,
+		bitrateKbps: input.bitrateKbps,
+		scale: null
+	};
+	return {
+		logLevel: "error",
+		decodeHwAccel: null,
+		input: {
+			url: "pipe:0",
+			rawVideo: {
+				pixelFormat: TILE_PIXEL_FORMAT,
+				width: input.canvas.width,
+				height: input.canvas.height,
+				framerate: input.fps
+			}
+		},
+		video,
+		audio: { kind: "none" },
+		threadCount: 0,
+		outputArgs: [],
+		sink: {
+			kind: "stdout",
+			container: "flv"
+		}
+	};
+}
+//#endregion
+//#region src/builtins/camera-grid/grid-compositor-child.ts
 /**
-* `-tune zerolatency`, and this one is worth several SECONDS.
+* The composition as processes: one decoder per tile, one encoder, one tick.
 *
-* 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 presents the SAME shape the single ffmpeg did — `{ stdout, stop }` — so
+* `GridStreamSession` is untouched. The seam is deliberate: the session owns
+* demand, acquisition and teardown, and none of that changes because the
+* picture is assembled differently.
 *
-* 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.
+* ## The order things start in, and why it is the order
 *
-* 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.
+* 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.
 *
-* 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`, as small as ffmpeg allows.
+* ## Back-pressure is a SKIPPED tick, never a queue
 *
-* ## The probes are SEQUENTIAL, and this is what the tile skew was
+* A raw canvas frame is 3.1 MB at 1080p. If the encoder stops draining, the one
+* safe thing is to stop composing until it drains again: a queue of raw frames
+* is how a stalled encoder becomes an OOM, and a dropped frame in a live
+* composite costs nothing anybody can see.
 *
-* The sentence that used to be here said the probes are "PARALLEL inputs of one
-* child". They are not. ffmpeg opens its inputs one after another and each open
-* BLOCKS in `avformat_find_stream_info` until its budget is spent — so input 0
-* is already connected and receiving while ffmpeg is still opening input 1, its
-* frames pile up, and `overlay` (which pairs inputs BY PTS) marries input 0's
-* oldest frame to input 1's newest. The lag is fixed for the life of the child:
-* both tiles then advance one frame per output frame, so nothing ever closes it.
-* The FIRST cell is the most behind; the last is live.
+* ## Any child exiting ends the composition
 *
-* Reproduced in one command on 2026-09-18 — two sources hstacked, one frame,
-* reading the cameras' own burnt-in clocks out of the composed picture:
-*
-* ```
-* 13:11:21 | 13:11:23      two seconds, and the earlier input is the late one
-* ```
-*
-* ## Why the old numbers cost seconds
-*
-* `-probesize` is a BYTE budget, and 1 MB of a 640x360 sub-stream is tens of
-* seconds of video — so `-analyzeduration 1s` never got the chance to stop it
-* and each open ran until the byte budget filled. Zero and 32 make the probe
-* return from the SDP, which already declares the codec, without reading media.
-*
-* Measured on this hub, the two sources of the live grid, three runs each,
-* production input args otherwise identical — time to the first composed frame,
-* and the skew read off the two burnt-in clocks in that frame:
-*
-* ```
-*   1 s / 1 MB     8986, 9728, 9712 ms      skew 5 s, 5 s, 4 s
-*   0   / 32       2281, 2270, 2304 ms      skew 1 s, 1 s, 0 s
-* ```
-*
-* The same numbers are the ~9 s cold start the operator had accepted: it was a
-* SUM of the opens, never the wait for the slowest source.
-*
-* Checked before shipping, because a probe that reads nothing has to survive
-* what it is not told: h264, h265 and a derived (`mid-to-low`) source all open
-* with `rc=0`, a 20 s run produces 200 frames of 200 either way (so the pacing
-* this file already lost once is untouched), and the skew is still 0 at 25 s
-* into a run — it is set at start-up and does not drift.
-*
-* What remains is the spread in when each source's first key frame arrives, and
-* a `/muted` dial waits for the next IDR. That spread is small here; if it ever
-* is not, the answer is to start the inputs from a join point we hold, NOT to
-* re-time the inputs (see `useWallclockTimestamps` below).
+* Same policy as the single child (`maxRestarts: 0`): the session tells its
+* consumers why and tears down, and the next read starts a cold composition
+* with freshly acquired sources. Leaving a dead tile frozen while the others
+* run would be a nicer picture and a worse fact — the operator would be looking
+* at a camera that stopped minutes ago with nothing saying so.
 */
-var ANALYZE_DURATION_US = 0;
-var PROBE_SIZE_BYTES = 32;
-function inputPlanFor(source) {
-	return {
-		url: source.url,
-		rtspTransport: "tcp",
-		fflags: ["+discardcorrupt"],
-		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.
+* The encoder must produce its first bytes quickly, because the tick feeds it a
+* black canvas immediately — a silence here is the encoder failing to start,
+* not a camera being slow.
 */
-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
+var ENCODER_FIRST_DATA_MS = 5e3;
 /**
-* 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.
+* A decoder's first frame waits for its source's next key frame, which on this
+* fleet is up to a GOP. Generous, and it costs only that tile: the picture is
+* already on screen.
 */
-/** 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
+var DECODER_FIRST_DATA_MS = 15e3;
+async function startGridCompositorChild(ctx, plan, sources, onEnded) {
+	const tilePlan = buildGridTilePlan({
+		canvas: {
+			width: plan.layout.width,
+			height: plan.layout.height
+		},
+		cells: plan.layout.cells.map((cell) => ({
+			deviceId: plan.sourceDeviceIds[cell.inputIndex] ?? 0,
+			source: cell.source,
+			cell: cell.cell
+		}))
 	});
-	let stdout = null;
-	const process = new FfmpegProcess({
+	if (tilePlan.tiles.length === 0) throw new Error("camera-grid: every cell rounded away to nothing — there is no picture to make");
+	let ended = false;
+	const end = (reason) => {
+		if (ended) return;
+		ended = true;
+		onEnded(reason);
+	};
+	let encoderIn = null;
+	let encoderOut = null;
+	const encoder = new FfmpegProcess({
 		binaryPath: ctx.binaryPath,
-		buildArgs: (decodeHwAccel) => buildFfmpegArgs(invocation(decodeHwAccel)),
-		decodeHwAccel: plan.decodeHwAccel,
-		logger: ctx.logger,
+		buildArgs: () => buildFfmpegArgs(gridCanvasEncoderInvocation({
+			canvas: tilePlan.canvas,
+			fps: plan.fps,
+			encoder: plan.encoder,
+			bitrateKbps: plan.bitrateKbps
+		})),
+		decodeHwAccel: null,
+		logger: ctx.logger.child("encode"),
 		deviceId: ctx.deviceId,
-		role: "camera-grid",
-		tags: {
-			cells: plan.layout.cells.length,
-			inputs: plan.sourceDeviceIds.length
-		},
-		firstDataTimeoutMs: FIRST_DATA_TIMEOUT_MS,
+		role: "camera-grid-encode",
+		tags: { tiles: tilePlan.tiles.length },
+		firstDataTimeoutMs: ENCODER_FIRST_DATA_MS,
 		maxRestarts: 0,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
 		onChild: (child) => {
-			if (child.stdout) stdout = child.stdout;
+			encoderIn = child.stdin;
+			if (child.stdout) encoderOut = child.stdout;
 			child.stderr?.on("data", () => {});
+			child.stdin?.on("error", () => {});
 		},
-		onExit: (exit) => {
-			onEnded(exit.classification);
+		onExit: (exit) => end(`encoder:${exit.classification}`)
+	});
+	await encoder.start();
+	if (encoderIn === null || encoderOut === null) {
+		await encoder.stop();
+		throw new Error("camera-grid: the canvas encoder exposed no stdin/stdout to compose into");
+	}
+	let draining = false;
+	const sink = encoderIn;
+	sink.on("drain", () => {
+		draining = false;
+	});
+	const compositor = new GridCompositor({
+		plan: tilePlan,
+		write: (frame) => {
+			if (draining || sink.destroyed) return false;
+			const accepted = sink.write(frame);
+			if (!accepted) draining = true;
+			return accepted;
 		}
 	});
-	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();
+	const tick = setInterval(() => {
+		compositor.tick();
+	}, Math.max(1, Math.round(1e3 / plan.fps)));
+	tick.unref();
+	const urlByDeviceId = /* @__PURE__ */ new Map();
+	for (const [index, deviceId] of plan.sourceDeviceIds.entries()) {
+		const url = sources[index]?.url;
+		if (url !== void 0) urlByDeviceId.set(deviceId, url);
+	}
+	const decoders = [];
+	const startDecoder = async (tile) => {
+		const url = urlByDeviceId.get(tile.deviceId);
+		if (url === void 0) throw new Error(`camera-grid: no acquired source for device ${String(tile.deviceId)}`);
+		const decoder = new FfmpegProcess({
+			binaryPath: ctx.binaryPath,
+			buildArgs: () => buildFfmpegArgs(gridTileDecoderInvocation({
+				tile,
+				url,
+				fps: plan.fps
+			})),
+			decodeHwAccel: null,
+			logger: ctx.logger.child("tile"),
+			deviceId: tile.deviceId,
+			role: "camera-grid-tile",
+			tags: {
+				tile: tile.id,
+				width: tile.size.width,
+				height: tile.size.height
+			},
+			firstDataTimeoutMs: DECODER_FIRST_DATA_MS,
+			maxRestarts: 0,
+			onChild: (child) => {
+				child.stdout?.on("data", (chunk) => {
+					compositor.onTile(tile.id, chunk);
+				});
+				child.stderr?.on("data", () => {});
+			},
+			onExit: (exit) => end(`tile ${tile.id}:${exit.classification}`)
+		});
+		decoders.push(decoder);
+		await decoder.start();
+	};
+	const stopAll = async () => {
+		clearInterval(tick);
+		compositor.close();
+		await Promise.allSettled(decoders.map((d) => d.stop()));
+		await encoder.stop();
+	};
+	try {
+		for (const tile of tilePlan.tiles) await startDecoder(tile);
+	} catch (error) {
+		await stopAll();
+		throw error;
+	}
+	ctx.logger.info("camera grid: composing on an output clock", {
+		tags: { deviceId: ctx.deviceId },
+		meta: {
+			tiles: tilePlan.tiles.length,
+			canvas: `${String(tilePlan.canvas.width)}x${String(tilePlan.canvas.height)}`,
+			fps: plan.fps
 		}
+	});
+	return {
+		stdout: encoderOut,
+		stop: stopAll
 	};
 }
 //#endregion
@@ -1778,6 +2403,7 @@ var CameraGridAddon = class extends BaseAddon {
 	* — that only changes when an operator changes it.
 	*/
 	planByInstanceId = /* @__PURE__ */ new Map();
+	activity = null;
 	snapshots = null;
 	frameSampler = null;
 	ffmpegBinaryPath = "ffmpeg";
@@ -1806,11 +2432,29 @@ var CameraGridAddon = class extends BaseAddon {
 				sampleFrame: async (session) => this.sampleFrame(session),
 				store: new GridLastFrameFileStore({ dataDir: this.ctx.dataDir })
 			});
+			this.activity = new GridActivityForwarder({
+				eventBus: this.ctx.eventBus,
+				logger: this.ctx.logger.child("activity"),
+				addonId: this.ctx.id,
+				gridsForSource: (sourceDeviceId) => this.gridsForSource(sourceDeviceId),
+				now: () => Date.now()
+			});
+			this.subscribeSourceActivity();
 			installGridCameraRuntime({
 				descriptorsFor: (instanceId) => this.descriptorsFor(instanceId),
 				getLayout: (deviceId) => this.gridViewFor(deviceId),
 				saveLayout: async (patch) => this.saveGridLayout(patch),
-				getSnapshot: async (deviceId) => this.getSnapshot(deviceId)
+				getSnapshot: async (deviceId) => this.getSnapshot(deviceId),
+				motionStatus: (deviceId) => {
+					const state = this.activity?.motionStatusFor(deviceId, Date.now()) ?? {
+						detected: false,
+						lastDetectedAt: null
+					};
+					return {
+						...state,
+						autoClearAfterMs: state.detected ? MOTION_CLOSE_AFTER_MS : null
+					};
+				}
 			});
 			await this.reconcile().catch((error) => {
 				this.ctx.logger.warn("camera grid: initial reconciliation failed — will retry", { meta: { error: errMsg(error) } });
@@ -1947,6 +2591,64 @@ var CameraGridAddon = class extends BaseAddon {
 		}
 	}
 	/**
+	* Listen to the SOURCES, so the grid can say the same things about itself.
+	*
+	* Filtered by source id inside the handler rather than by subscribing per
+	* camera: the bus filter is per category, the set of sources changes whenever
+	* an operator drags a cell, and a per-camera subscription would have to be
+	* torn down and rebuilt on every layout save.
+	*
+	* Every handler is TOTAL — a malformed payload is ignored, never thrown out
+	* of. These are telemetry events on a shared bus (D8/D11), and a throw here
+	* would take the grid's forwarding down for every grid because one camera
+	* emitted something unexpected.
+	*/
+	subscribeSourceActivity() {
+		this.subscribe({ category: EventCategory.MotionOnMotionChanged }, (event) => {
+			const data = event.data;
+			if (typeof data.deviceId !== "number" || typeof data.detected !== "boolean") return;
+			const at = typeof data.timestamp === "number" ? data.timestamp : Date.now();
+			this.activity?.onSourceMotion(data.deviceId, data.detected, at);
+		});
+		this.subscribe({ category: EventCategory.PipelineAudioInferenceResult }, (event) => {
+			const data = event.data;
+			const dbfs = data.frame?.level?.dbfs;
+			if (typeof data.deviceId !== "number" || typeof dbfs !== "number") return;
+			this.activity?.onSourceAudio(data.deviceId, dbfs, Date.now());
+		});
+		this.subscribe({ category: EventCategory.DetectionResult }, (event) => {
+			const frame = event.data.frame;
+			if (frame === void 0 || frame.kind !== "frame") return;
+			this.activity?.onSourceDetections(frame);
+		});
+	}
+	/**
+	* Which grids show this camera. Empty for the overwhelming majority of
+	* events, which is why it is the FIRST thing every handler asks.
+	*/
+	gridsForSource(sourceDeviceId) {
+		const targets = [];
+		for (const [instanceId, deviceId] of this.deviceIdByInstanceId) {
+			const instance = this.instanceById(instanceId);
+			if (!instance || !instance.enabled) continue;
+			if (sourceDeviceId === deviceId) continue;
+			if (instance.cells.filter((cell) => cell.deviceId === sourceDeviceId).length === 0) continue;
+			targets.push({
+				deviceId,
+				canvas: {
+					width: instance.width,
+					height: instance.height
+				},
+				cellsForSource: (id) => instance.cells.filter((cell) => cell.deviceId === id).map((cell) => ({
+					source: cell.source,
+					cell: cell.cell
+				})),
+				sourceDeviceIds: [...new Set(instance.cells.map((cell) => cell.deviceId))]
+			});
+		}
+		return targets;
+	}
+	/**
 	* Which stream each grid reads each of its sources at, asked of the BROKER.
 	*
 	* `listAllProfileSlots` is the one authority on "does 615 have a low
@@ -2090,7 +2792,7 @@ var CameraGridAddon = class extends BaseAddon {
 				releaseSource: async (pipelineKey) => {
 					await this.ctx.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey });
 				},
-				startChild: async (plan, sources) => startGridChild(childContext, plan, sources, (reason) => {
+				startChild: async (plan, sources) => startGridCompositorChild(childContext, plan, sources, (reason) => {
 					session.onChildEnded(reason);
 				})
 			},
@@ -2130,6 +2832,7 @@ var CameraGridAddon = class extends BaseAddon {
 		}
 		for (const instanceId of [...this.deviceIdByInstanceId.keys()]) {
 			if (live.has(instanceId)) continue;
+			this.activity?.forget(this.deviceIdByInstanceId.get(instanceId) ?? 0);
 			this.deviceIdByInstanceId.delete(instanceId);
 			this.planByInstanceId.delete(instanceId);
 		}
@@ -2312,4 +3015,268 @@ var CameraGridAddon = class extends BaseAddon {
 	}
 };
 //#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`, as small as ffmpeg allows.
+*
+* ## The probes are SEQUENTIAL, and this is what the tile skew was
+*
+* The sentence that used to be here said the probes are "PARALLEL inputs of one
+* child". They are not. ffmpeg opens its inputs one after another and each open
+* BLOCKS in `avformat_find_stream_info` until its budget is spent — so input 0
+* is already connected and receiving while ffmpeg is still opening input 1, its
+* frames pile up, and `overlay` (which pairs inputs BY PTS) marries input 0's
+* oldest frame to input 1's newest. The lag is fixed for the life of the child:
+* both tiles then advance one frame per output frame, so nothing ever closes it.
+* The FIRST cell is the most behind; the last is live.
+*
+* Reproduced in one command on 2026-09-18 — two sources hstacked, one frame,
+* reading the cameras' own burnt-in clocks out of the composed picture:
+*
+* ```
+* 13:11:21 | 13:11:23      two seconds, and the earlier input is the late one
+* ```
+*
+* ## Why the old numbers cost seconds
+*
+* `-probesize` is a BYTE budget, and 1 MB of a 640x360 sub-stream is tens of
+* seconds of video — so `-analyzeduration 1s` never got the chance to stop it
+* and each open ran until the byte budget filled. Zero and 32 make the probe
+* return from the SDP, which already declares the codec, without reading media.
+*
+* Measured on this hub, the two sources of the live grid, three runs each,
+* production input args otherwise identical — time to the first composed frame,
+* and the skew read off the two burnt-in clocks in that frame:
+*
+* ```
+*   1 s / 1 MB     8986, 9728, 9712 ms      skew 5 s, 5 s, 4 s
+*   0   / 32       2281, 2270, 2304 ms      skew 1 s, 1 s, 0 s
+* ```
+*
+* The same numbers are the ~9 s cold start the operator had accepted: it was a
+* SUM of the opens, never the wait for the slowest source.
+*
+* Checked before shipping, because a probe that reads nothing has to survive
+* what it is not told: h264, h265 and a derived (`mid-to-low`) source all open
+* with `rc=0`, a 20 s run produces 200 frames of 200 either way (so the pacing
+* this file already lost once is untouched), and the skew is still 0 at 25 s
+* into a run — it is set at start-up and does not drift.
+*
+* What remains is the spread in when each source's first key frame arrives, and
+* a `/muted` dial waits for the next IDR. That spread is small here; if it ever
+* is not, the answer is to start the inputs from a join point we hold, NOT to
+* re-time the inputs (see `useWallclockTimestamps` below).
+*/
+var ANALYZE_DURATION_US = 0;
+var PROBE_SIZE_BYTES = 32;
+function inputPlanFor(source) {
+	return {
+		url: source.url,
+		rtspTransport: "tcp",
+		fflags: ["+discardcorrupt"],
+		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
 export { CameraGridAddon, CameraGridAddon as default, GRID_CAM_STREAM_ID, GRID_OUTPUT_PROFILE, GRID_SILENCED_CAP_NAMES, GridCameraDevice, GridFrameSampler, GridLastFrameFileStore, GridSnapshotSource, GridStreamRelay, GridStreamSession, buildGridCameraDeclarations, buildGridFilterGraph, gridCameraReconciliationIndex, gridPlanFor, gridSnapshotAnswerFor, gridSourceDial, gridSourceProfiles, gridStreamDescriptor, gridStreamInvocation, installGridCameraRuntime, lowestServedProfile, newGridCameraStableId, normalizeGridRows, parseGridStreamPath, readGridInstances, silenceAnalysisFor, startGridChild };