@camstack/system 1.2.264 → 1.2.266

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

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BhYweLVr.js");
+const require_dist = require("../../dist-BbPssgI6.js");
 let zod = require("zod");
 let _camstack_types_node = require("@camstack/types/node");
 let node_path = require("node:path");
@@ -1800,196 +1800,373 @@ 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;
-}
-/**
-* 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`);
+//#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);
 }
 /**
-* `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.
+* 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 cropExpression(source) {
-	return `crop=iw*${source.width}:ih*${source.height}:iw*${source.x}:ih*${source.y}`;
+function evenDown(value) {
+	return Math.max(0, Math.floor(value / 2) * 2);
 }
-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
-	};
+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-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-tile-feed.ts
 /**
-* `-tune zerolatency`, and this one is worth several SECONDS.
+* One source's decoded tiles, of which only the LATEST is ever wanted.
 *
-* 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.
+* ## Why dropping is the point, not a compromise
 *
-* 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.
+* 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.
 *
-* 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.
+* 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.
 *
-* 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.
+* ## 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 GOP_SECONDS = 1;
+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
 /**
-* `-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).
+* 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 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
-	};
+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;
 }
 /**
-* @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.
+* `crop` resolved against the source's OWN size at runtime (`iw`/`ih`), never
+* against a resolution guessed here — which is what lets a stored rectangle
+* survive a camera that changes resolution under us.
 */
-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");
+function cropExpression$1(source) {
+	return `crop=iw*${source.width}:ih*${source.height}:iw*${source.x}:ih*${source.y}`;
+}
+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 {
+		canvas: input.canvas,
+		tiles
+	};
+}
+//#endregion
+//#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,
-		tune: TUNE,
-		pixelFormat: PIXEL_FORMAT,
+		preset: PRESET$1,
+		tune: TUNE$1,
+		pixelFormat: TILE_PIXEL_FORMAT,
 		fps: input.fps,
-		gopFrames: input.fps * GOP_SECONDS,
+		gopFrames: input.fps * GOP_SECONDS$1,
 		bitrateKbps: input.bitrateKbps,
 		scale: null
 	};
 	return {
 		logLevel: "error",
-		decodeHwAccel: input.decodeHwAccel,
-		input: inputPlanFor(first),
-		extraInputs: rest.map(inputPlanFor),
-		filterGraph: graph,
+		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,
@@ -2001,66 +2178,194 @@ function gridStreamInvocation(input) {
 	};
 }
 //#endregion
-//#region src/builtins/camera-grid/grid-child.ts
+//#region src/builtins/camera-grid/grid-compositor-child.ts
 /**
-* Spawning the composition, through the ONE primitive.
+* The composition as processes: one decoder per tile, one encoder, one tick.
 *
-* `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.
+* 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.
 *
-* `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.
+* ## The order things start in, and why it is the order
+*
+* The encoder first, then the tick, then the decoders. The tick writes a black
+* canvas from its very first beat, so the encoder produces a stream — and the
+* consumer sees a picture — before any camera has delivered anything. That is
+* the cold start the old shape spent waiting for the slowest source's first key
+* frame, and it is now spent watching cells fill in.
+*
+* ## Back-pressure is a SKIPPED tick, never a queue
+*
+* 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.
+*
+* ## Any child exiting ends the composition
+*
+* 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.
 */
-/** 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
+/**
+* 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.
+*/
+var ENCODER_FIRST_DATA_MS = 5e3;
+/**
+* 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.
+*/
+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 _camstack_types_node.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;
+	let draining = false;
+	let tick = null;
+	const compositor = new GridCompositor({
+		plan: tilePlan,
+		write: (frame) => {
+			const sink = encoderIn;
+			if (sink === null || draining || sink.destroyed) return false;
+			const accepted = sink.write(frame);
+			if (!accepted) draining = true;
+			return accepted;
+		}
+	});
+	const startTick = () => {
+		if (tick !== null) return;
+		tick = setInterval(() => {
+			compositor.tick();
+		}, Math.max(1, Math.round(1e3 / plan.fps)));
+		tick.unref();
+	};
+	const encoder = new _camstack_types_node.FfmpegProcess({
 		binaryPath: ctx.binaryPath,
-		buildArgs: (decodeHwAccel) => require_dist.buildFfmpegArgs(invocation(decodeHwAccel)),
-		decodeHwAccel: plan.decodeHwAccel,
-		logger: ctx.logger,
+		buildArgs: () => require_dist.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.stdin?.on("drain", () => {
+				draining = false;
+			});
+			startTick();
 			child.stderr?.on("data", () => {});
+			child.stdin?.on("error", () => {});
 		},
-		onExit: (exit) => {
-			onEnded(exit.classification);
+		onExit: (exit) => end(`encoder:${exit.classification}`)
+	});
+	try {
+		await encoder.start();
+	} catch (error) {
+		if (tick !== null) clearInterval(tick);
+		compositor.close();
+		throw error;
+	}
+	if (encoderIn === null || encoderOut === null) {
+		await encoder.stop();
+		throw new Error("camera-grid: the canvas encoder exposed no stdin/stdout to compose into");
+	}
+	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 _camstack_types_node.FfmpegProcess({
+			binaryPath: ctx.binaryPath,
+			buildArgs: () => require_dist.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 () => {
+		if (tick !== null) 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
 		}
 	});
-	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();
-		}
+		stdout: encoderOut,
+		stop: stopAll
 	};
 }
 //#endregion
@@ -2503,7 +2808,7 @@ var CameraGridAddon = class extends require_dist.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);
 				})
 			},
@@ -2726,6 +3031,270 @@ var CameraGridAddon = class extends require_dist.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 _camstack_types_node.FfmpegProcess({
+		binaryPath: ctx.binaryPath,
+		buildArgs: (decodeHwAccel) => require_dist.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
 exports.CameraGridAddon = CameraGridAddon;
 exports.GRID_CAM_STREAM_ID = GRID_CAM_STREAM_ID;
 exports.GRID_OUTPUT_PROFILE = GRID_OUTPUT_PROFILE;