@camstack/addon-pipeline 1.1.57 → 1.1.59

package/dist/recorder/index.mjs

@@ -1,9 +1,11 @@
-import { A as recordingCapability, B as DeviceType, D as nodePin, I as errMsg, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as hydrateSchema, V as EventCategory, Y as selectAssignedProfileSlots, at as record, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-CL531uVA.mjs";
-import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
-import { t as createFileDataPlaneHandler } from "../model-download-service-C-IHWnXx-3Mmeob3l.mjs";
+import { A as recordingCapability, B as DeviceType, D as nodePin, H as hydrateSchema, I as errMsg, J as selectAssignedProfileSlots, L as BaseAddon, M as storageEvictableCapability, T as migrateConfigToBands, U as isEvent, at as string, it as record, s as EVENT_PAD_MS, st as EventCategory, u as RecordingConfigSchema } from "../dist-DKeNH_5z.mjs";
+import { n as computeSheetGeometry, r as resolveHubHostname, t as allTilePlacements } from "../sheet-geometry-Bk3fR4s7.mjs";
+import { t as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-0wh7OK3s.mjs";
 import { spawn } from "node:child_process";
+import sharp from "sharp";
 import { promises } from "node:fs";
 import path from "node:path";
+import { tmpdir } from "node:os";
 //#region src/recorder/segment-path.ts
 function segmentRelPath(deviceId, profile, startMs, durMs, bytes) {
 	if (profile.includes("/")) throw new Error(`segmentRelPath: profile must not contain '/': ${profile}`);
@@ -197,6 +199,22 @@ var RecordingIndex = class {
 		const next = segs.find((s) => s.startMs >= epochMs);
 		return next ? next.startMs : null;
 	}
+	/**
+	* The exclusive END of the nearest footage ending at-or-before `epochMs`
+	* (the backward covered edge), or null when no footage ends at or before it.
+	* Backward counterpart of `nearestCoveredEdge`: consecutive segments leave
+	* small cracks (`startMs + durMs` < next `startMs` by ~11-17 ms), so a
+	* backward frame-step probing `startMs − 1` lands in a crack — this edge
+	* lets the caller hop to the true previous segment.
+	*/
+	coveredEdgeBefore(deviceId, profile, epochMs) {
+		let best = null;
+		for (const s of this.segments(deviceId, profile)) {
+			const end = s.startMs + s.durMs;
+			if (end <= epochMs && (best === null || end > best)) best = end;
+		}
+		return best;
+	}
 	ranges(deviceId, profile, fromMs, toMs, gapToleranceMs) {
 		return mergeRanges(this.segments(deviceId, profile).filter((s) => s.startMs + s.durMs > fromMs && s.startMs < toMs), gapToleranceMs).map((r) => ({
 			startMs: Math.max(r.startMs, fromMs),
@@ -1043,7 +1061,8 @@ function buildRecordingProvider(deps) {
 			};
 			return {
 				kind: "gap",
-				nearestEdgeMs: deps.index.nearestCoveredEdge(deviceId, profile, epochMs)
+				nearestEdgeMs: deps.index.nearestCoveredEdge(deviceId, profile, epochMs),
+				prevEndMs: deps.index.coveredEdgeBefore(deviceId, profile, epochMs)
 			};
 		},
 		readSegmentBytes: async ({ deviceId, profile, startMs }) => {
@@ -2045,6 +2064,923 @@ function makeBrokerCall(handle) {
 */
 var resolveRecordingHubHostname = resolveHubHostname;
 //#endregion
+//#region src/thumbnails/thumb-index.ts
+/**
+* Build the index + geometry for a window's samples. Samples are sorted by
+* capture time; each gets a row-major placement. Throws when there are no
+* samples (an empty window is never written).
+*/
+function buildThumbnailIndex(input) {
+	if (input.samples.length === 0) throw new Error("buildThumbnailIndex: no samples");
+	const tileWidth = input.tileWidth ?? 320;
+	const tileHeight = input.tileHeight ?? 180;
+	const maxCols = input.maxCols ?? 10;
+	const ordered = [...input.samples].sort((a, b) => a.t - b.t);
+	const geometry = computeSheetGeometry(ordered.length, {
+		tileWidth,
+		tileHeight,
+		maxCols
+	});
+	const placements = allTilePlacements(ordered.length, geometry);
+	const tiles = ordered.map((s, i) => {
+		const p = placements[i];
+		return {
+			t: s.t,
+			x: p.x,
+			y: p.y
+		};
+	});
+	return {
+		index: {
+			version: 1,
+			deviceId: input.deviceId,
+			windowStartMs: input.windowStartMs,
+			windowMs: input.windowMs,
+			intervalMs: input.intervalMs,
+			tileWidth,
+			tileHeight,
+			cols: geometry.cols,
+			rows: geometry.rows,
+			sheet: `sheet-${input.windowStartMs}.jpg`,
+			source: input.source,
+			tiles
+		},
+		geometry,
+		orderedSamples: ordered
+	};
+}
+//#endregion
+//#region src/thumbnails/thumb-window.ts
+/**
+* Thumbnail window + on-disk path math — pure, UTC-aligned, deterministic.
+*
+* A thumbnail "window" is a fixed UTC-aligned span (default 5 min). Every
+* timestamp maps to exactly one window; the window start, its UTC bucket
+* (Y/M/D/H like the segment store), and the sheet/index filenames are all
+* derived from it with NO state — so the recorder writes and the viewer reads
+* the SAME deterministic path from a bare timestamp (no directory listing, no
+* cap round-trip).
+*/
+/** Default window span — 5 minutes. */
+var DEFAULT_WINDOW_MS = 3e5;
+/** Zero-padded 2-digit. */
+function p2(n) {
+	return String(n).padStart(2, "0");
+}
+/** UTC-aligned window start (epoch ms) containing `t`. */
+function windowStartFor(t, windowMs = DEFAULT_WINDOW_MS) {
+	if (!Number.isFinite(t)) throw new Error(`windowStartFor: t must be finite, got ${t}`);
+	if (!(windowMs > 0)) throw new Error(`windowStartFor: windowMs must be > 0, got ${windowMs}`);
+	return Math.floor(t / windowMs) * windowMs;
+}
+/** UTC `Y/M/D/H` bucket dir (relative) for a window start — mirrors
+*  `segmentRelPath`'s bucketing so thumbs co-locate with the same hour tree. */
+function bucketDir(windowStartMs) {
+	const d = new Date(windowStartMs);
+	return `${d.getUTCFullYear()}/${p2(d.getUTCMonth() + 1)}/${p2(d.getUTCDate())}/${p2(d.getUTCHours())}`;
+}
+/** Sheet image filename for a window start. */
+function sheetFileName(windowStartMs) {
+	return `sheet-${windowStartMs}.jpg`;
+}
+/** Index sidecar filename for a window start. */
+function indexFileName(windowStartMs) {
+	return `index-${windowStartMs}.json`;
+}
+/**
+* Device-relative directory (under the thumbs root) for a window:
+* `<deviceId>/<Y>/<M>/<D>/<H>`. The device is the top segment (thumbs are
+* profile-agnostic, unlike segments which nest under a profile).
+*/
+function windowRelDir(deviceId, windowStartMs) {
+	return `${deviceId}/${bucketDir(windowStartMs)}`;
+}
+//#endregion
+//#region src/thumbnails/thumbnail-sink.ts
+var ThumbnailSink = class {
+	deps;
+	now;
+	open = /* @__PURE__ */ new Map();
+	lastFlushed = /* @__PURE__ */ new Map();
+	/** In-flight flush promises per device — chained so a device never composes
+	*  two windows concurrently (ordering + bounded work). */
+	flushChain = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? (() => Date.now());
+	}
+	/** Accept a sampled thumb. Rolls over (flushes) the device's open window when
+	*  a strictly-later window's sample arrives. */
+	add(deviceId, sample) {
+		const windowStartMs = windowStartFor(sample.capturedAt, this.deps.windowMs);
+		const lastFlushed = this.lastFlushed.get(deviceId);
+		if (lastFlushed !== void 0 && windowStartMs <= lastFlushed) return;
+		let cur = this.open.get(deviceId);
+		if (cur && windowStartMs > cur.windowStartMs) {
+			this.scheduleFlush(deviceId, cur);
+			this.open.delete(deviceId);
+			cur = void 0;
+		}
+		if (cur && windowStartMs < cur.windowStartMs) return;
+		if (!cur) {
+			cur = {
+				windowStartMs,
+				samples: []
+			};
+			this.open.set(deviceId, cur);
+		}
+		if (cur.samples.length < this.deps.maxTilesPerWindow) cur.samples.push(sample);
+	}
+	/** Flush every open window whose end + grace has passed (idle cameras). */
+	flushExpired() {
+		const now = this.now();
+		for (const [deviceId, win] of [...this.open]) if (now - (win.windowStartMs + this.deps.windowMs) >= this.deps.idleGraceMs) {
+			this.scheduleFlush(deviceId, win);
+			this.open.delete(deviceId);
+		}
+	}
+	/** Flush all open windows (shutdown). Returns when every flush settles. */
+	async flushAll() {
+		for (const [deviceId, win] of [...this.open]) {
+			this.scheduleFlush(deviceId, win);
+			this.open.delete(deviceId);
+		}
+		await Promise.all([...this.flushChain.values()]);
+	}
+	/** Test/diagnostic: number of open windows. */
+	get openWindowCount() {
+		return this.open.size;
+	}
+	scheduleFlush(deviceId, win) {
+		const next = (this.flushChain.get(deviceId) ?? Promise.resolve()).then(() => this.doFlush(deviceId, win)).catch((err) => {
+			this.deps.logger.warn("thumbnail sink: window flush failed", {
+				tags: { deviceId },
+				meta: {
+					windowStartMs: win.windowStartMs,
+					error: err instanceof Error ? err.message : err
+				}
+			});
+		});
+		this.flushChain.set(deviceId, next);
+		this.lastFlushed.set(deviceId, Math.max(this.lastFlushed.get(deviceId) ?? -1, win.windowStartMs));
+	}
+	async doFlush(deviceId, win) {
+		if (win.samples.length === 0) return;
+		const ordered = [...win.samples].sort((a, b) => a.capturedAt - b.capturedAt);
+		const built = buildThumbnailIndex({
+			deviceId,
+			windowStartMs: win.windowStartMs,
+			windowMs: this.deps.windowMs,
+			intervalMs: this.deps.intervalMs,
+			source: this.deps.source,
+			tileWidth: this.deps.tileWidth,
+			tileHeight: this.deps.tileHeight,
+			maxCols: this.deps.maxCols,
+			samples: ordered.map((s) => ({ t: s.capturedAt }))
+		});
+		const placements = allTilePlacements(ordered.length, built.geometry);
+		const sheetBytes = await this.deps.compose({
+			tiles: ordered.map((s) => s.jpeg),
+			placements,
+			geometry: built.geometry
+		});
+		await this.deps.persist({
+			deviceId,
+			windowStartMs: win.windowStartMs,
+			relDir: windowRelDir(deviceId, win.windowStartMs),
+			sheetName: sheetFileName(win.windowStartMs),
+			sheetBytes,
+			indexName: indexFileName(win.windowStartMs),
+			index: built.index
+		});
+	}
+};
+//#endregion
+//#region src/thumbnails/sheet-composer.ts
+/**
+* Resize each tile to the uniform tile size and composite onto a black canvas
+* at its placement. Returns the sheet JPEG bytes. Throws if tiles/placements
+* lengths disagree.
+*/
+async function composeSheet(sharp, input) {
+	const { tiles, placements, geometry } = input;
+	if (tiles.length !== placements.length) throw new Error(`composeSheet: tiles(${tiles.length}) != placements(${placements.length})`);
+	if (tiles.length === 0) throw new Error("composeSheet: no tiles");
+	const entries = (await Promise.all(tiles.map((t) => sharp(t).resize(geometry.tileWidth, geometry.tileHeight, {
+		fit: "cover",
+		position: "centre"
+	}).jpeg({ quality: input.quality ?? 60 }).toBuffer()))).map((buf, i) => {
+		const p = placements[i];
+		return {
+			input: buf,
+			left: p.x,
+			top: p.y
+		};
+	});
+	return sharp({ create: {
+		width: geometry.sheetWidth,
+		height: geometry.sheetHeight,
+		channels: 3,
+		background: {
+			r: 0,
+			g: 0,
+			b: 0
+		}
+	} }).composite(entries).jpeg({ quality: input.quality ?? 60 }).toBuffer();
+}
+//#endregion
+//#region src/thumbnails/thumbnail-persister.ts
+/**
+* Thumbnail disk persister — writes a window's sheet JPEG + index JSON
+* write-once under `<thumbsRoot>/<dev>/Y/M/D/H/`. Small fs wrapper the recorder
+* wires with a real root; kept separate so the sink stays fs-free and testable.
+*/
+/** Root dir thumbs are written under for a location (`<locationRoot>/.thumbs`). */
+var THUMBS_SUBDIR = ".thumbs";
+/**
+* Persist one window. Writes are best-effort atomic (write to a `.tmp` then
+* rename) so a crash mid-write never leaves a truncated sheet a viewer would
+* cache as `immutable`. Idempotent: an existing sheet is left as-is (write-once).
+*/
+async function persistThumbnailWindow(thumbsRoot, req) {
+	const dir = path.join(thumbsRoot, req.relDir);
+	await promises.mkdir(dir, { recursive: true });
+	const sheetPath = path.join(dir, req.sheetName);
+	const indexPath = path.join(dir, req.indexName);
+	await Promise.all([writeOnce(sheetPath, req.sheetBytes), writeOnce(indexPath, Buffer.from(JSON.stringify(req.index)))]);
+}
+async function writeOnce(absPath, bytes) {
+	try {
+		await promises.access(absPath);
+		return;
+	} catch {}
+	const tmp = `${absPath}.tmp-${process.pid}-${Date.now()}`;
+	await promises.writeFile(tmp, bytes);
+	try {
+		await promises.rename(tmp, absPath);
+	} catch (err) {
+		await promises.rm(tmp, { force: true }).catch(() => {});
+		throw err;
+	}
+}
+var HOUR_MS = 36e5;
+/**
+* Buckets whose whole hour ends before the retention cutoff. Cutoff = the
+* device's oldest indexed segment (thumbs live exactly as long as footage),
+* or `now - fallback` when the device has no segments.
+*/
+function planThumbPrune(input) {
+	const cutoffMs = input.oldestSegmentStartMs ?? input.nowMs - 2592e6;
+	return input.buckets.filter((b) => b.hourStartMs + HOUR_MS <= cutoffMs);
+}
+/**
+* Parse a `Y/M/D/H` relative bucket path (as walked under a device dir) into
+* its UTC hour start. Returns null for anything that isn't a valid bucket
+* (staging debris, foreign files) so the janitor never deletes what it does
+* not understand.
+*/
+function parseHourBucket(relYmdh) {
+	const m = /^(\d{4})\/(\d{2})\/(\d{2})\/(\d{2})$/.exec(relYmdh);
+	if (!m) return null;
+	const [, y, mo, d, h] = m;
+	const year = Number(y);
+	const month = Number(mo);
+	const day = Number(d);
+	const hour = Number(h);
+	if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23) return null;
+	const t = Date.UTC(year, month - 1, day, hour);
+	const dt = new Date(t);
+	if (dt.getUTCFullYear() !== year || dt.getUTCMonth() !== month - 1 || dt.getUTCDate() !== day || dt.getUTCHours() !== hour) return null;
+	return t;
+}
+//#endregion
+//#region src/thumbnails/thumbs-media-handler.ts
+var IMMUTABLE = "public, max-age=31536000, immutable";
+/** Reject traversal / absolute / NUL and normalise leading slashes. Returns the
+*  safe rel path or null. Exported for unit coverage. */
+function sanitizeThumbsPath(url) {
+	const qIdx = url.indexOf("?");
+	const raw = qIdx === -1 ? url : url.slice(0, qIdx);
+	let rel;
+	try {
+		rel = decodeURIComponent(raw.replace(/^\/+/, ""));
+	} catch {
+		return null;
+	}
+	if (rel.length === 0) return null;
+	if (rel.includes("\0")) return null;
+	if (rel.startsWith("/")) return null;
+	if (rel.split("/").some((seg) => seg === ".." || seg === ".")) return null;
+	if (!/\.(jpe?g|json)$/i.test(rel)) return null;
+	return rel;
+}
+/** Content type for a thumbs file by extension. */
+function thumbsContentType(relPath) {
+	if (/\.json$/i.test(relPath)) return "application/json";
+	return "image/jpeg";
+}
+function createThumbsMediaHandler(deps) {
+	return async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" }).end();
+			return;
+		}
+		const rel = sanitizeThumbsPath(req.url ?? "/");
+		if (rel === null) {
+			res.writeHead(404).end();
+			return;
+		}
+		const etag = `"${rel}"`;
+		if (req.headers["if-none-match"] === etag) {
+			res.writeHead(304, {
+				etag,
+				"cache-control": IMMUTABLE
+			}).end();
+			return;
+		}
+		let file;
+		try {
+			file = await deps.getFile(rel);
+		} catch {
+			const body = "Internal server error";
+			res.writeHead(500, {
+				"content-type": "text/plain",
+				"content-length": String(Buffer.byteLength(body))
+			});
+			if (req.method === "HEAD") res.end();
+			else res.end(body);
+			return;
+		}
+		if (file === null) {
+			res.writeHead(404).end();
+			return;
+		}
+		res.writeHead(200, {
+			"content-type": file.contentType,
+			"cache-control": IMMUTABLE,
+			etag,
+			"content-length": String(file.bytes.byteLength)
+		});
+		if (req.method === "HEAD") res.end();
+		else res.end(Buffer.from(file.bytes));
+	};
+}
+//#endregion
+//#region src/thumbnails/thumb-backfill-plan.ts
+/**
+* Backfill PLANNER — pure (no ffmpeg, no I/O). Given a device's low segments
+* and the window starts already covered by a sampled/backfilled index, decide
+* which windows still need a keyframe-only ffmpeg pass and which segments cover
+* each. The executor (recorder) runs at most ONE ffmpeg per planned window,
+* single-flighted; this module owns only the "what to do" decision so it is
+* fully unit-testable.
+*
+* A window is a backfill candidate when:
+*   - at least one low segment overlaps it (there is footage to sample), AND
+*   - no index already covers it (sampling didn't reach it), AND
+*   - the window is fully in the past by `settleMs` (no new segment can still
+*     land in it — mirrors the segment store's current-hour eviction guard).
+*/
+/** True when `[startMs, startMs+durMs)` overlaps `[winStart, winEnd)`. */
+function overlaps(startMs, durMs, winStart, winEnd) {
+	return startMs < winEnd && startMs + durMs > winStart;
+}
+/**
+* Compute the ordered (ascending window) backfill plan. Deterministic and
+* bounded: returns at most `maxWindows` window plans (oldest first), each with
+* its overlapping segments.
+*/
+function planBackfill(input) {
+	const { segments, coveredWindows, windowMs, now, settleMs } = input;
+	const maxWindows = input.maxWindows ?? 500;
+	if (!(windowMs > 0)) return [];
+	const candidates = /* @__PURE__ */ new Set();
+	for (const seg of segments) {
+		if (seg.durMs <= 0) continue;
+		const firstW = windowStartFor(seg.startMs, windowMs);
+		const lastW = windowStartFor(seg.startMs + seg.durMs - 1, windowMs);
+		for (let w = firstW; w <= lastW; w += windowMs) candidates.add(w);
+	}
+	const plans = [];
+	for (const windowStartMs of [...candidates].sort((a, b) => a - b)) {
+		if (coveredWindows.has(windowStartMs)) continue;
+		const windowEndMs = windowStartMs + windowMs;
+		if (now - windowEndMs < settleMs) continue;
+		const covering = segments.filter((s) => s.durMs > 0 && overlaps(s.startMs, s.durMs, windowStartMs, windowEndMs)).sort((a, b) => a.startMs - b.startMs);
+		if (covering.length === 0) continue;
+		plans.push({
+			windowStartMs,
+			windowEndMs,
+			segments: covering
+		});
+		if (plans.length >= maxWindows) break;
+	}
+	return plans;
+}
+//#endregion
+//#region src/thumbnails/backfill-ffmpeg.ts
+/**
+* ffmpeg args to extract keyframes from one segment as scaled JPEGs. `-skip_frame
+* nokey` + `-vsync 0` (a.k.a. passthrough) keeps only I-frames without
+* duplicating; `-an` drops audio. The caller resolves timestamps from the
+* segment start + the extracted frame order (keyframes are ~GOP-spaced).
+*/
+function buildKeyframeExtractArgs(input) {
+	const q = input.quality ?? 4;
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"error",
+		"-skip_frame",
+		"nokey",
+		"-i",
+		input.inputPath,
+		"-an",
+		"-vsync",
+		"0",
+		"-vf",
+		`scale=${input.tileWidth}:-2`,
+		"-q:v",
+		String(q),
+		input.outputPattern
+	];
+}
+//#endregion
+//#region src/recorder/addon/thumbnail-service.ts
+/**
+* Recorder-side scrub-thumbnail SERVICE — the wiring that turns
+* `recording.thumb-sampled` telemetry into served sprite sheets.
+*
+*   runner (any node) --recording.thumb-sampled event--> THIS (recording node)
+*      -> ThumbnailSink accumulates a 5-min window
+*      -> composeSheet (sharp) + persistThumbnailWindow (write-once)
+*      -> data-plane `/addon/recorder/thumbs/<dev>/Y/M/D/H/{sheet,index}`
+*
+* Cross-node decision (documented, simplest per the analysis §3 open
+* questions): the thumb rides the EVENT BUS. The recorder is a SINGLE
+* designated node, so its data-plane prefix (`/addon/recorder/thumbs`) is
+* unambiguous — serving from any decode node's own prefix would be
+* multi-node-ambiguous. Sampling is compressed (~10 KB) at 1/5 Hz — well inside
+* D9 — and telemetry-grade (a lost thumb is a scrub gap the keyframe backfill
+* fills), so no new cap method and no RPC hop are needed.
+*
+* Backfill (phase 2): hourly, for windows with recorded LOW footage but no
+* sampled coverage, ONE keyframe-only ffmpeg pass per window fills quiet-period
+* heartbeat thumbs. Bounded concurrency + single-flight so a burst never spawns
+* a storm.
+*/
+var THUMBS_PREFIX = "thumbs";
+var RECORDER_ADDON_ID$1 = "recorder";
+/** Idle window flush grace — a window whose end passed this long ago is
+*  composed even if no later sample rolled it over (idle camera). */
+var IDLE_GRACE_MS = 3e4;
+/** Flush-timer cadence. */
+var FLUSH_TICK_MS = 15e3;
+/** Backfill scan cadence — 15 min so scrub coverage holes close within the
+*  hour instead of lingering (spawns stay bounded: keyframe-only ffmpeg over
+*  low segments, concurrency-gated, per-device window budget). */
+var BACKFILL_TICK_MS = 15 * 6e4;
+/** A window must have ended this long ago before backfill considers it. */
+var BACKFILL_SETTLE_MS = 5 * DEFAULT_WINDOW_MS;
+/** Max concurrent backfill ffmpeg passes across all cameras. */
+var BACKFILL_MAX_CONCURRENT = 2;
+/** Max windows filled PER DEVICE per backfill pass. A recording camera accrues
+*  ≤12 uncovered 5-min windows/hour, so 24 lets a device also DRAIN backlog.
+*  (This was a GLOBAL cap: 24/pass vs ~12×N windows/hour needed cluster-wide —
+*  devices later in the list starved and coverage grew permanent holes,
+*  live-measured 2026-07-17 on 590: gaps at −55…−110 min.) */
+var BACKFILL_MAX_WINDOWS_PER_DEVICE = 24;
+/** Global safety cap per pass (runaway bound across all cameras). */
+var BACKFILL_MAX_WINDOWS_PER_PASS = 240;
+/** Hard cap on tiles per window (bounds sheet size + compose cost). */
+var MAX_TILES_PER_WINDOW = 90;
+/** Retention-prune cadence (sheets are small — a slow sweep is plenty). */
+var PRUNE_TICK_MS = 6 * 36e5;
+/** First prune runs this long after start (off the boot churn). */
+var PRUNE_INITIAL_DELAY_MS = 10 * 6e4;
+var SHARP = sharp;
+var ThumbnailService = class {
+	deps;
+	sink;
+	unsub = null;
+	dataPlaneDispose = null;
+	flushTimer = null;
+	backfillTimer = null;
+	pruneTimer = null;
+	pruneInitialTimer = null;
+	backfillActive = 0;
+	backfillInFlight = /* @__PURE__ */ new Set();
+	stopped = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.sink = new ThumbnailSink({
+			windowMs: deps.config.windowMs,
+			intervalMs: deps.config.intervalMs,
+			tileWidth: 320,
+			tileHeight: 180,
+			maxCols: 10,
+			maxTilesPerWindow: MAX_TILES_PER_WINDOW,
+			idleGraceMs: IDLE_GRACE_MS,
+			source: "sampled",
+			compose: (req) => composeSheet(SHARP, {
+				tiles: [...req.tiles],
+				placements: req.placements,
+				geometry: req.geometry
+			}),
+			persist: (req) => this.persist(req),
+			logger: deps.logger.child("thumbnail-sink")
+		});
+	}
+	/** First writable thumbs root (`<locationRoot>/.thumbs`), or null when no
+	*  recordings location is resolved yet. */
+	writeRoot() {
+		const loc = this.deps.locations()[0];
+		return loc ? path.join(loc.root, THUMBS_SUBDIR) : null;
+	}
+	/** Every thumbs root (for the data-plane getFile search). */
+	thumbsRoots() {
+		return this.deps.locations().map((l) => path.join(l.root, THUMBS_SUBDIR));
+	}
+	/**
+	* Serve ONLY the `thumbs` data-plane endpoint, without starting the sink /
+	* timers. Called from the recorder's `onInitialize` — BEFORE the
+	* node-registration handshake — because the hub pulls a forked addon's
+	* data-plane endpoints once, off the caps-registered signal: an endpoint
+	* served later (the `start()` in `onHubReachable` lands minutes after boot)
+	* never reaches the reverse-proxy and `/addon/recorder/thumbs/*` 404s to the
+	* SPA (live-diagnosed 2026-07-17). Safe to serve early: the handler resolves
+	* roots lazily per request (mirrors the playback data-plane pattern).
+	* Idempotent — `start()` re-invokes it harmlessly.
+	*/
+	async serveEarly() {
+		if (!this.deps.config.enabled) return;
+		if (this.dataPlaneDispose !== null) return;
+		await this.serveDataPlane();
+	}
+	async start() {
+		if (!this.deps.config.enabled) {
+			this.deps.logger.info("thumbnails disabled — service inert");
+			return;
+		}
+		if (this.unsub !== null) return;
+		this.unsub = this.deps.eventBus.subscribe({ category: EventCategory.RecordingThumbSampled }, (event) => {
+			if (!isEvent(event, EventCategory.RecordingThumbSampled)) return;
+			const d = event.data;
+			try {
+				this.sink.add(d.deviceId, {
+					capturedAt: d.capturedAt,
+					jpeg: Buffer.from(d.jpeg)
+				});
+			} catch (err) {
+				this.deps.logger.debug("thumbnail add failed", {
+					tags: { deviceId: d.deviceId },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			}
+		});
+		if (this.dataPlaneDispose === null) await this.serveDataPlane();
+		this.flushTimer = setInterval(() => this.sink.flushExpired(), FLUSH_TICK_MS);
+		if (typeof this.flushTimer === "object" && "unref" in this.flushTimer) this.flushTimer.unref?.();
+		if (this.deps.config.backfillEnabled) {
+			this.backfillTimer = setInterval(() => {
+				this.runBackfillPass();
+			}, BACKFILL_TICK_MS);
+			this.backfillTimer.unref?.();
+		}
+		this.pruneInitialTimer = setTimeout(() => {
+			this.runPrunePass();
+		}, PRUNE_INITIAL_DELAY_MS);
+		this.pruneInitialTimer.unref?.();
+		this.pruneTimer = setInterval(() => {
+			this.runPrunePass();
+		}, PRUNE_TICK_MS);
+		this.pruneTimer.unref?.();
+		this.deps.logger.info("thumbnail service started", { meta: {
+			windowMs: this.deps.config.windowMs,
+			intervalMs: this.deps.config.intervalMs,
+			backfill: this.deps.config.backfillEnabled
+		} });
+	}
+	async stop() {
+		this.stopped = true;
+		this.unsub?.();
+		this.unsub = null;
+		if (this.flushTimer) clearInterval(this.flushTimer);
+		if (this.backfillTimer) clearInterval(this.backfillTimer);
+		if (this.pruneTimer) clearInterval(this.pruneTimer);
+		if (this.pruneInitialTimer) clearTimeout(this.pruneInitialTimer);
+		this.flushTimer = null;
+		this.backfillTimer = null;
+		this.pruneTimer = null;
+		this.pruneInitialTimer = null;
+		try {
+			await this.sink.flushAll();
+		} catch {}
+		await this.dataPlaneDispose?.().catch(() => {});
+		this.dataPlaneDispose = null;
+	}
+	async serveDataPlane() {
+		const handler = createThumbsMediaHandler({ getFile: async (rel) => {
+			for (const root of this.thumbsRoots()) {
+				const abs = path.join(root, rel);
+				if (!abs.startsWith(root + path.sep)) continue;
+				try {
+					return {
+						bytes: await promises.readFile(abs),
+						contentType: thumbsContentType(rel)
+					};
+				} catch {}
+			}
+			return null;
+		} });
+		try {
+			const served = await this.deps.dataPlane?.serve({
+				prefix: THUMBS_PREFIX,
+				access: "authenticated",
+				handler
+			});
+			if (served) {
+				this.dataPlaneDispose = () => served.dispose();
+				this.deps.logger.info("thumbnail data-plane served", { meta: { clientBase: `/addon/${RECORDER_ADDON_ID$1}/${THUMBS_PREFIX}` } });
+			}
+		} catch (err) {
+			this.deps.logger.warn("thumbnail data-plane failed to serve", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+	/**
+	* One retention sweep: for every device dir under every thumbs root, drop
+	* the hour buckets fully older than the device's oldest indexed segment
+	* (thumbs live exactly as long as footage; fixed fallback age when the
+	* device has no segments). Pure decision in `planThumbPrune`; only valid
+	* `Y/M/D/H` buckets are ever deleted. Best-effort — a failed rm retries on
+	* the next sweep.
+	*/
+	async runPrunePass() {
+		if (this.stopped) return;
+		let pruned = 0;
+		for (const root of this.thumbsRoots()) {
+			let deviceDirs;
+			try {
+				deviceDirs = (await promises.readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory() && /^\d+$/.test(e.name)).map((e) => e.name);
+			} catch {
+				continue;
+			}
+			for (const dev of deviceDirs) {
+				if (this.stopped) return;
+				const deviceId = Number(dev);
+				const deviceDir = path.join(root, dev);
+				const buckets = [];
+				try {
+					for (const rel of await promises.readdir(deviceDir, { recursive: true })) {
+						const relPosix = String(rel).split(path.sep).join("/");
+						const hourStartMs = parseHourBucket(relPosix);
+						if (hourStartMs !== null) buckets.push({
+							relDir: relPosix,
+							hourStartMs
+						});
+					}
+				} catch {
+					continue;
+				}
+				const segments = this.deps.lowSegments(deviceId);
+				const plan = planThumbPrune({
+					buckets,
+					oldestSegmentStartMs: segments.length > 0 ? Math.min(...segments.map((s) => s.startMs)) : null,
+					nowMs: Date.now()
+				});
+				for (const b of plan) try {
+					await promises.rm(path.join(deviceDir, b.relDir), {
+						recursive: true,
+						force: true
+					});
+					pruned += 1;
+				} catch {}
+				if (plan.length > 0) await removeEmptyParents(deviceDir);
+			}
+		}
+		if (pruned > 0) this.deps.logger.info("thumbnail retention prune removed buckets", { meta: { pruned } });
+	}
+	async persist(req) {
+		const root = this.writeRoot();
+		if (!root) {
+			this.deps.logger.warn("thumbnail persist skipped — no recordings location resolved", { tags: { deviceId: req.deviceId } });
+			return;
+		}
+		await persistThumbnailWindow(root, req);
+	}
+	/** One backfill scan: fill uncovered, settled windows with recorded low
+	*  footage, bounded per pass + per concurrency. Best-effort. */
+	async runBackfillPass() {
+		if (this.stopped || !this.deps.config.backfillEnabled) return;
+		const root = this.writeRoot();
+		if (!root) return;
+		let deviceIds;
+		try {
+			deviceIds = await this.deps.recordingDeviceIds();
+		} catch {
+			return;
+		}
+		let filled = 0;
+		for (const deviceId of deviceIds) {
+			if (filled >= BACKFILL_MAX_WINDOWS_PER_PASS || this.stopped) break;
+			const segments = this.deps.lowSegments(deviceId).map((s) => ({
+				startMs: s.startMs,
+				durMs: s.durMs,
+				path: s.path
+			}));
+			if (segments.length === 0) continue;
+			const plans = planBackfill({
+				segments,
+				coveredWindows: await this.readCoveredWindows(root, deviceId),
+				windowMs: this.deps.config.windowMs,
+				now: Date.now(),
+				settleMs: BACKFILL_SETTLE_MS,
+				maxWindows: Math.min(BACKFILL_MAX_WINDOWS_PER_DEVICE, BACKFILL_MAX_WINDOWS_PER_PASS - filled)
+			});
+			let filledForDevice = 0;
+			for (const plan of plans) {
+				if (filled >= BACKFILL_MAX_WINDOWS_PER_PASS || filledForDevice >= BACKFILL_MAX_WINDOWS_PER_DEVICE || this.stopped) break;
+				const key = `${deviceId}:${plan.windowStartMs}`;
+				if (this.backfillInFlight.has(key)) continue;
+				this.backfillInFlight.add(key);
+				try {
+					await this.gateBackfill(() => this.backfillWindow(deviceId, plan.windowStartMs, plan.segments, root));
+					filled += 1;
+					filledForDevice += 1;
+				} catch (err) {
+					this.deps.logger.debug("backfill window failed", {
+						tags: { deviceId },
+						meta: {
+							windowStartMs: plan.windowStartMs,
+							error: err instanceof Error ? err.message : err
+						}
+					});
+				} finally {
+					this.backfillInFlight.delete(key);
+				}
+			}
+		}
+		if (filled > 0) this.deps.logger.info("thumbnail backfill pass filled windows", { meta: { filled } });
+	}
+	/** Bounded-concurrency gate (spin-wait, coarse — backfill is rare/hourly). */
+	async gateBackfill(fn) {
+		while (this.backfillActive >= BACKFILL_MAX_CONCURRENT && !this.stopped) await new Promise((r) => setTimeout(r, 200));
+		this.backfillActive += 1;
+		try {
+			return await fn();
+		} finally {
+			this.backfillActive -= 1;
+		}
+	}
+	/** Which windows already have an index sidecar on disk (sampled or prior backfill). */
+	async readCoveredWindows(root, deviceId) {
+		const covered = /* @__PURE__ */ new Set();
+		const deviceDir = path.join(root, String(deviceId));
+		let entries;
+		try {
+			entries = await promises.readdir(deviceDir, { recursive: true });
+		} catch {
+			return covered;
+		}
+		for (const e of entries) {
+			const m = /index-(\d+)\.json$/.exec(e);
+			if (m) covered.add(Number(m[1]));
+		}
+		return covered;
+	}
+	/** Fill ONE window: extract keyframes from its covering low segments, compose
+	*  a sheet, persist with `source:'backfill'`. */
+	async backfillWindow(deviceId, windowStartMs, segments, root) {
+		const workDir = await promises.mkdtemp(path.join(tmpdir(), `csthumb-${deviceId}-`));
+		try {
+			const samples = [];
+			for (const seg of segments) {
+				const absSeg = this.resolveSegmentAbs(deviceId, seg.path);
+				if (!absSeg) continue;
+				const jpegs = await this.extractKeyframes(absSeg, workDir);
+				const n = jpegs.length;
+				for (let i = 0; i < n; i += 1) {
+					const t = seg.startMs + Math.round(seg.durMs * i / Math.max(1, n));
+					if (t >= windowStartMs && t < windowStartMs + this.deps.config.windowMs) samples.push({
+						t,
+						jpeg: jpegs[i]
+					});
+				}
+			}
+			if (samples.length === 0) return;
+			if (samples.length > MAX_TILES_PER_WINDOW) samples.length = MAX_TILES_PER_WINDOW;
+			const ordered = samples.sort((a, b) => a.t - b.t);
+			const built = buildThumbnailIndex({
+				deviceId,
+				windowStartMs,
+				windowMs: this.deps.config.windowMs,
+				intervalMs: this.deps.config.intervalMs,
+				source: "backfill",
+				tileWidth: 320,
+				tileHeight: 180,
+				maxCols: 10,
+				samples: ordered.map((s) => ({ t: s.t }))
+			});
+			const geometry = computeSheetGeometry(ordered.length, {
+				tileWidth: 320,
+				tileHeight: 180,
+				maxCols: 10
+			});
+			const placements = allTilePlacements(ordered.length, geometry);
+			const sheetBytes = await composeSheet(SHARP, {
+				tiles: ordered.map((s) => s.jpeg),
+				placements,
+				geometry
+			});
+			await persistThumbnailWindow(root, {
+				deviceId,
+				windowStartMs,
+				relDir: `${deviceId}/${bucketDir(windowStartMs)}`,
+				sheetName: sheetFileName(windowStartMs),
+				sheetBytes,
+				indexName: indexFileName(windowStartMs),
+				index: built.index
+			});
+		} finally {
+			await promises.rm(workDir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		}
+	}
+	/** Resolve a low segment's absolute path from its location root + rel path. */
+	resolveSegmentAbs(deviceId, relPath) {
+		const row = this.deps.lowSegments(deviceId).find((r) => r.path === relPath);
+		if (!row) return null;
+		const loc = this.deps.locations().find((l) => l.id === row.locationId);
+		if (!loc) return null;
+		return path.join(loc.root, relPath);
+	}
+	/** Run ONE keyframe-only ffmpeg pass over a segment; return the extracted
+	*  JPEG buffers in order. */
+	async extractKeyframes(absSeg, workDir) {
+		const args = buildKeyframeExtractArgs({
+			inputPath: absSeg,
+			outputPattern: path.join(workDir, "kf-%04d.jpg"),
+			tileWidth: 320
+		});
+		await this.spawnFfmpeg(args);
+		const files = (await promises.readdir(workDir)).filter((f) => /^kf-\d+\.jpg$/.test(f)).sort();
+		const out = [];
+		for (const f of files) {
+			out.push(await promises.readFile(path.join(workDir, f)));
+			await promises.rm(path.join(workDir, f), { force: true }).catch(() => {});
+		}
+		return out;
+	}
+	spawnFfmpeg(args) {
+		return new Promise((resolve, reject) => {
+			let child;
+			try {
+				child = spawn("ffmpeg", [...args], { stdio: [
+					"ignore",
+					"ignore",
+					"ignore"
+				] });
+			} catch (err) {
+				reject(err instanceof Error ? err : new Error(String(err)));
+				return;
+			}
+			const timer = setTimeout(() => {
+				child.kill("SIGKILL");
+				reject(/* @__PURE__ */ new Error("ffmpeg keyframe extract timed out"));
+			}, 3e4);
+			timer.unref?.();
+			child.on("error", (err) => {
+				clearTimeout(timer);
+				reject(err);
+			});
+			child.on("close", (code) => {
+				clearTimeout(timer);
+				if (code === 0) resolve();
+				else reject(/* @__PURE__ */ new Error(`ffmpeg exited ${code}`));
+			});
+		});
+	}
+};
+/**
+* Best-effort removal of now-empty `Y/M/D` parent dirs after a prune (never
+* the device dir itself). `rmdir` refuses non-empty dirs, so this can never
+* delete content — failures are simply left for the next sweep.
+*/
+async function removeEmptyParents(deviceDir) {
+	let entries;
+	try {
+		entries = (await promises.readdir(deviceDir, { recursive: true })).map(String);
+	} catch {
+		return;
+	}
+	const dirs = entries.map((rel) => rel.split(path.sep).join("/")).filter((rel) => /^\d{4}(\/\d{2}){0,3}$/.test(rel)).sort((a, b) => b.length - a.length);
+	for (const rel of dirs) try {
+		await promises.rmdir(path.join(deviceDir, rel));
+	} catch {}
+}
+//#endregion
 //#region src/recorder/addon/index.ts
 /**
 * recorder addon SHELL — recording + storage-evictable providers on the
@@ -2078,7 +3014,9 @@ var DEFAULT_CONFIG = {
 	segmentSeconds: 10,
 	watchIntervalMs: 2e3,
 	recordingNodeId: RECORDING_NODE_DEFAULT,
-	recordingHubHostname: ""
+	recordingHubHostname: "",
+	thumbnailsEnabled: true,
+	thumbnailBackfillEnabled: true
 };
 /** Playback-marker window padding around a motion event (EventMap only; the
 *  controller's events-band gating uses the raw trigger ms, not this pad).
@@ -2118,6 +3056,8 @@ var RecorderV2Addon = class extends BaseAddon {
 	resolvedLocations = [];
 	/** Base URL of the playback HTTP data-plane, null until served in onHubReachable. */
 	playbackBaseUrl = null;
+	/** Scrub-thumbnail service (sink + data-plane + backfill). Null until started. */
+	thumbnailService = null;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -2236,6 +3176,7 @@ var RecorderV2Addon = class extends BaseAddon {
 		} catch (err) {
 			this.ctx.logger.warn("recorder playback data-plane failed to serve", { meta: { error: errMsg(err) } });
 		}
+		await this.ensureThumbnailService().serveEarly();
 		this.ctx.logger.info("recorder addon started (continuous write path active)", {
 			tags: { nodeId: this.nodeId },
 			meta: {
@@ -2257,6 +3198,8 @@ var RecorderV2Addon = class extends BaseAddon {
 		await this.controller?.stop();
 		this.controller = null;
 		this.segmentStore = null;
+		await this.thumbnailService?.stop();
+		this.thumbnailService = null;
 	}
 	/**
 	* Boot hydrate: once the hub is reachable (`ctx.api.*` safe), resolve the
@@ -2309,6 +3252,30 @@ var RecorderV2Addon = class extends BaseAddon {
 				this.controller?.onTrigger(deviceId, "motion", atMs);
 			}
 		});
+		try {
+			await this.ensureThumbnailService().start();
+		} catch (err) {
+			this.ctx.logger.warn("recorder: thumbnail service start failed", { meta: { error: errMsg(err) } });
+		}
+	}
+	/** Construct the thumbnail service once — every dep is a lazy closure, so
+	*  construction is safe in `onInitialize` (before locations resolve). */
+	ensureThumbnailService() {
+		if (this.thumbnailService === null) this.thumbnailService = new ThumbnailService({
+			logger: this.ctx.logger.child("thumbnails"),
+			eventBus: this.ctx.eventBus,
+			...this.ctx.dataPlane !== void 0 ? { dataPlane: this.ctx.dataPlane } : {},
+			locations: () => this.resolvedLocations,
+			lowSegments: (deviceId) => this.index.segments(deviceId, "low"),
+			recordingDeviceIds: async () => [...(await readDeviceConfigs(this.configStore())).keys()],
+			config: {
+				enabled: this.config.thumbnailsEnabled,
+				backfillEnabled: this.config.thumbnailBackfillEnabled,
+				windowMs: DEFAULT_WINDOW_MS,
+				intervalMs: 5e3
+			}
+		});
+		return this.thumbnailService;
 	}
 	/** Re-resolve recordings locations (rescanStorage picks up newly-added disks). */
 	async refreshLocations() {
@@ -2385,6 +3352,24 @@ var RecorderV2Addon = class extends BaseAddon {
 				description: "Advanced: only used when the recording node is an AGENT. The hub's host the agent dials to pull broker streams (the RTSP restream port must be reachable there). Leave empty to auto-derive from the agent's hub connection.",
 				default: ""
 			}]
+		}, {
+			id: "scrub-thumbnails",
+			title: "Scrub thumbnails",
+			description: "Timeline scrub previews. Small JPEG sprite sheets packed from the runner-sampled detection frames (zero extra decode) + an hourly keyframe-only backfill for quiet windows. Served write-once over the authenticated data-plane; works on every viewer platform (no client video decode).",
+			columns: 1,
+			fields: [{
+				type: "boolean",
+				key: "thumbnailsEnabled",
+				label: "Serve scrub thumbnails",
+				description: "Accumulate + serve sprite sheets. Disable to stop packing/serving thumbnails.",
+				default: true
+			}, {
+				type: "boolean",
+				key: "thumbnailBackfillEnabled",
+				label: "Keyframe backfill",
+				description: "Hourly, fill windows that have recorded low footage but no sampled thumbs with a single keyframe-only ffmpeg pass per window (≤24 spawns/day/camera worst case).",
+				default: true
+			}]
 		}] });
 	}
 	/** Durable handle config-store reads/writes the deviceId→config blob on —