@camstack/system 1.1.41 → 1.1.43

package/dist/builtins/snapshot/index.mjs

@@ -1,5 +1,200 @@
-import { $ as errMsg, K as snapshotCapability, L as nodePin, Y as streamQualityLabel, et as BaseAddon, it as DeviceFeature, ot as DeviceType } from "../../dist-ClOjKsC4.mjs";
+import { $ as errMsg, K as snapshotCapability, L as nodePin, Y as streamQualityLabel, et as BaseAddon, it as DeviceFeature, ot as DeviceType } from "../../dist-C68OyuEd.mjs";
 import { execFile } from "node:child_process";
+//#region src/builtins/snapshot/snapshot-coalescing.ts
+/**
+* Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
+* primitives for the snapshot wrapper.
+*
+* These are extracted from `SnapshotAddon` so the decision logic is unit-testable
+* without instantiating the addon (no camera, no ffmpeg, no tRPC). The addon wires
+* them to its cache + ladder; this module owns only the mechanics:
+*
+*   - {@link decideSnapshotServe} — the pure serve/refresh decision (fresh cache vs
+*     stale-while-revalidate vs cold blocking capture) keyed off the cached frame
+*     age, the per-device max-age, and whether the caller forced a refresh.
+*   - {@link Semaphore} — a counting semaphore bounding concurrent grabs.
+*   - {@link SingleFlight} — de-dupes concurrent captures for the same key and
+*     retains a SETTLED success for a short hold window so a mount burst collapses
+*     into one capture.
+*   - {@link raceForResult} — races a promise against a wait bound without
+*     cancelling the promise (the loser keeps running in the background).
+*/
+/**
+* Retain a SETTLED single-flight capture this long so a grid-mount burst of
+* `getSnapshot` calls (and a row of refresh buttons) collapses into ONE capture
+* instead of one dial per tile. Only success outcomes are held — a null/failed
+* capture expires immediately so a transiently-unreachable camera is retried on
+* the next call rather than pinned blank for the window.
+*/
+var COALESCE_MS = 4e3;
+/**
+* Stale-while-revalidate: when a cached frame exists but is past its max-age,
+* start the refresh and wait at most this long for it to land before returning
+* the STALE frame (the refresh keeps running and populates the cache for the
+* next poll). Keeps a grid mount painting instantly from cache.
+*/
+var SWR_STALE_WAIT_MS = 2500;
+/**
+* Cold path (no cached frame) or a forced refresh: wait up to this long for a
+* fresh capture. On a cold miss there is nothing to fall back to, so we block
+* (bounded) on the capture; on a forced refresh with a stale frame available we
+* still prefer a fresh one but cap the wait, falling back to stale on timeout.
+*/
+var SWR_COLD_WAIT_MS = 1e4;
+/**
+* Pure serve/refresh decision.
+*
+*   - fresh cache + !force            -> serve-cache
+*   - stale cache + !force            -> SWR: wait SWR_STALE_WAIT_MS, then stale
+*   - no cache   + !force             -> cold: wait SWR_COLD_WAIT_MS, no fallback
+*   - force (cache present or not)    -> prefer fresh: wait SWR_COLD_WAIT_MS,
+*                                       fall back to stale only if a frame exists
+*/
+function decideSnapshotServe(input) {
+	const { now, cachedAt, effectiveMaxAgeMs, force } = input;
+	const hasFrame = cachedAt !== null;
+	const fresh = hasFrame && now - cachedAt < effectiveMaxAgeMs;
+	if (!force && fresh) return { kind: "serve-cache" };
+	if (force) return {
+		kind: "await-refresh",
+		waitMs: SWR_COLD_WAIT_MS,
+		staleFallback: hasFrame
+	};
+	if (hasFrame) return {
+		kind: "await-refresh",
+		waitMs: SWR_STALE_WAIT_MS,
+		staleFallback: true
+	};
+	return {
+		kind: "await-refresh",
+		waitMs: SWR_COLD_WAIT_MS,
+		staleFallback: false
+	};
+}
+/**
+* A counting semaphore. `run` acquires a permit, awaits `fn`, and releases the
+* permit (even if `fn` throws), so at most `max` `fn`s run concurrently. Waiters
+* are served FIFO.
+*/
+var Semaphore = class {
+	available;
+	waiters = [];
+	constructor(max) {
+		if (!Number.isInteger(max) || max < 1) throw new Error(`Semaphore max must be a positive integer, got ${String(max)}`);
+		this.available = max;
+	}
+	async run(fn) {
+		const release = await this.acquire();
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+	async acquire() {
+		if (this.available > 0) {
+			this.available -= 1;
+			return this.makeReleaser();
+		}
+		await new Promise((resolve) => this.waiters.push(resolve));
+		return this.makeReleaser();
+	}
+	makeReleaser() {
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const next = this.waiters.shift();
+			if (next) {
+				next();
+				return;
+			}
+			this.available += 1;
+		};
+	}
+};
+/**
+* One in-flight capture per key. A settled SUCCESS is retained for `holdMs` so a
+* burst collapses into one capture; a settled failure/empty expires immediately
+* so the next caller retries. Concurrent callers ALWAYS join the running flight
+* regardless of eventual outcome.
+*/
+var Flight = class {
+	promise;
+	settledAt = null;
+	hold = false;
+	constructor(factory, now, holdWorthy) {
+		this.promise = (async () => {
+			try {
+				const value = await factory();
+				this.hold = holdWorthy(value);
+				return value;
+			} catch (err) {
+				this.hold = false;
+				throw err;
+			} finally {
+				this.settledAt = now();
+			}
+		})();
+	}
+};
+var SingleFlight = class {
+	holdMs;
+	holdWorthy;
+	now;
+	flights = /* @__PURE__ */ new Map();
+	/**
+	* @param holdMs      how long a settled hold-worthy result is reused
+	* @param holdWorthy  predicate deciding whether a settled value is worth holding
+	*                    (e.g. a successful capture with a real frame)
+	* @param now         clock injection for tests
+	*/
+	constructor(holdMs, holdWorthy, now = () => Date.now()) {
+		this.holdMs = holdMs;
+		this.holdWorthy = holdWorthy;
+		this.now = now;
+	}
+	run(key, factory) {
+		const existing = this.flights.get(key);
+		if (existing && this.isReusable(existing)) return existing.promise;
+		const flight = new Flight(factory, this.now, this.holdWorthy);
+		this.flights.set(key, flight);
+		return flight.promise;
+	}
+	/** Drop every held flight whose key starts with `prefix` (e.g. `"<deviceId>:"`). */
+	invalidatePrefix(prefix) {
+		for (const key of [...this.flights.keys()]) if (key.startsWith(prefix)) this.flights.delete(key);
+	}
+	clear() {
+		this.flights.clear();
+	}
+	isReusable(flight) {
+		if (flight.settledAt === null) return true;
+		if (!flight.hold) return false;
+		return this.now() - flight.settledAt < this.holdMs;
+	}
+};
+/**
+* Race `promise` against a `timeoutMs` bound WITHOUT cancelling it — on timeout
+* the promise keeps running (its result lands in the cache for the next poll).
+* Rejections propagate: if `promise` rejects before the timeout, this rejects.
+* The caller passes a promise that never rejects (a settled outcome union) when
+* background continuation must stay unhandled-safe.
+*/
+function raceForResult(promise, timeoutMs) {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve({ settled: false }), timeoutMs);
+	});
+	const settled = promise.then((value) => ({
+		settled: true,
+		value
+	}));
+	return Promise.race([settled, timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+//#endregion
 //#region src/builtins/snapshot/snapshot.addon.ts
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
@@ -26,6 +221,16 @@ var BATTERY_DEFAULT_MAX_AGE_S = 3600;
 var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	cache = /* @__PURE__ */ new Map();
 	/**
+	* De-dupes concurrent captures per `${deviceId}:${streamId}` and holds a
+	* settled SUCCESS for COALESCE_MS so a grid-mount burst (and a row of refresh
+	* buttons) collapses into one capture instead of one dial per tile.
+	*/
+	captureFlight = new SingleFlight(COALESCE_MS, (outcome) => outcome.ok && outcome.image !== null);
+	/** Bounds simultaneous ffmpeg keyframe grabs (the wrapper path — common case). */
+	grabPool = new Semaphore(3);
+	/** Bounds simultaneous native (vendor HTTP/ONVIF) snapshot fetches. */
+	nativePool = new Semaphore(6);
+	/**
 	* Cached resolution of `pipelineOrchestrator.getIngestOwner` — SnapshotAddon
 	* has no per-request attach hook to resolve this fresh, so it's cached with
 	* a short TTL and invalidated on `onConfigChanged` (covers the common case
@@ -48,12 +253,14 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 				getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
 				getDeviceLiveContribution: async () => null,
 				applyDeviceSettingsPatch: (input) => this.saveDeviceSettingsPatch(input.deviceId, input.patch),
-				getStatus: async (input) => this.getStatus(input.deviceId)
+				getStatus: async (input) => this.getStatus(input.deviceId),
+				getSnapshotOverview: (input) => this.getSnapshotOverview(input)
 			}
 		}];
 	}
 	async onShutdown() {
 		this.cache.clear();
+		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
 	/**
@@ -86,7 +293,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}] });
 	}
 	async getSnapshot(input) {
-		const { deviceId, force } = input;
+		const { deviceId } = input;
+		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
 		const deviceName = meta?.name;
 		const isBatteryDevice = meta?.isBattery ?? false;
@@ -105,8 +313,14 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		});
 		const defaultMaxAgeS = isBatteryDevice ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
 		const effectiveMaxAgeMs = (typeof prefs.snapshotMaxAgeS === "number" && prefs.snapshotMaxAgeS >= 0 ? prefs.snapshotMaxAgeS : defaultMaxAgeS) * 1e3;
-		if (!force && hit && now - hit.ts < effectiveMaxAgeMs) {
-			if (prefs.snapshotDebug) log.debug("snapshot: cache hit", {
+		const decision = decideSnapshotServe({
+			now,
+			cachedAt: hit?.ts ?? null,
+			effectiveMaxAgeMs,
+			force
+		});
+		if (decision.kind === "serve-cache") {
+			if (prefs.snapshotDebug && hit) log.debug("snapshot: cache hit", {
 				tags: { deviceId },
 				meta: {
 					ageMs: now - hit.ts,
@@ -114,21 +328,97 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					isBattery: isBatteryDevice
 				}
 			});
+			return hit ? hit.data : null;
+		}
+		const flightKey = `${deviceId}:${effectiveStreamId ?? "auto"}`;
+		const flight = this.captureFlight.run(flightKey, () => this.captureFresh({
+			deviceId,
+			input,
+			effectiveStreamId,
+			isBatteryDevice,
+			log
+		}));
+		flight.catch(() => void 0);
+		const raced = await raceForResult(flight, decision.waitMs);
+		if (raced.settled) return this.resolveOutcome(raced.value, deviceId, hit, log);
+		if (decision.staleFallback && hit) {
+			if (prefs.snapshotDebug) log.debug("snapshot: SWR — returning stale frame; refresh continues in background", {
+				tags: { deviceId },
+				meta: {
+					ageMs: now - hit.ts,
+					waitMs: decision.waitMs
+				}
+			});
+			return hit.data;
+		}
+		return null;
+	}
+	/**
+	* Map a settled capture outcome onto the response, preserving the legacy
+	* semantics: a fresh frame wins; a soft miss (native null + broker null)
+	* falls back to stale cache (or null); a HARD native error with no frame
+	* and no cache propagates.
+	*/
+	resolveOutcome(outcome, deviceId, hit, log) {
+		if (outcome.ok) {
+			if (outcome.image) return outcome.image;
+			if (hit) {
+				const ageMs = Date.now() - hit.ts;
+				if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
+					tags: { deviceId },
+					meta: { ageMs }
+				});
+				return hit.data;
+			}
+			return null;
+		}
+		if (hit) {
+			const ageMs = Date.now() - hit.ts;
+			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: native failed — serving stale cache", {
+				tags: { deviceId },
+				meta: { ageMs }
+			});
 			return hit.data;
 		}
+		throw outcome.error;
+	}
+	/**
+	* Run the capture ladder ONCE for a device: native provider first, then the
+	* stream-broker ffmpeg fallback. Never rejects — resolves a {@link
+	* CaptureOutcome}. On a produced frame it populates the cache (so a
+	* background SWR refresh lands for the next poll) and returns it. A hard
+	* native error with no broker frame resolves `{ ok:false }` so the caller
+	* can surface it; a soft miss resolves `{ ok:true, image:null }`.
+	*
+	* TODO(decoded-frame fast path): for a device whose detection pipeline is
+	* already decoding (the always-on subscription, see docs/design/decode-path.md),
+	* the freshest decoded frame is already in the shared-memory ring — a single
+	* JPEG encode of the latest FrameHandle would cost zero dials and beat the
+	* ffmpeg grab for the wrapper fleet. Slotting it as native -> latest-decoded
+	* -> broker needs cross-addon plumbing not cheaply reachable from the hub
+	* builtin today: frames are session-scoped (decoder `pullHandles`/`getFrame`
+	* need the device's active session id) and raw-pixel (need a JPEG encoder the
+	* builtin lacks). Deferred as its own slice.
+	*/
+	async captureFresh(args) {
+		const { deviceId, input, effectiveStreamId, isBatteryDevice, log } = args;
+		const now = Date.now();
 		let nativeError = null;
 		let nativeAbsent = false;
 		try {
 			const native = this.ctx.getNativeProvider(snapshotCapability, deviceId);
 			if (native) {
-				const result = await native.getSnapshot(input);
+				const result = await this.nativePool.run(() => native.getSnapshot(input));
 				if (result) {
 					this.cache.set(deviceId, {
 						data: result,
 						ts: now,
 						streamId: effectiveStreamId ?? null
 					});
-					return result;
+					return {
+						ok: true,
+						image: result
+					};
 				}
 				log.debug("native snapshot returned null — falling through to broker", { tags: { deviceId } });
 			} else {
@@ -159,7 +449,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					ts: now,
 					streamId: effectiveStreamId ?? null
 				});
-				return fallback;
+				return {
+					ok: true,
+					image: fallback
+				};
 			}
 		} catch (err) {
 			log.warn("stream-broker snapshot fallback failed", {
@@ -168,25 +461,16 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			});
 		}
 		else log.debug("snapshot: skipping broker fallback — battery device with absent native and no streaming broker", { tags: { deviceId } });
-		if (hit) {
-			const ageMs = now - hit.ts;
-			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
-				tags: { deviceId },
-				meta: { ageMs }
-			});
-			return hit.data;
-		}
-		if (nativeError) throw nativeError;
-		if (nativeAbsent) return null;
-		return null;
+		if (nativeError) return {
+			ok: false,
+			error: nativeError
+		};
+		return {
+			ok: true,
+			image: null
+		};
 	}
 	/**
-	* Tell apart "native provider isn't registered for this device" from
-	* "native provider ran and threw a real error". The former is the steady
-	* state for cameras without a vendor snapshot endpoint and should not
-	* propagate as a 500; the latter should.
-	*/
-	/**
 	* Pull one JPEG from the device's stream-broker RTSP restream using
 	* a short-lived ffmpeg invocation.
 	*
@@ -291,12 +575,12 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	async runGrabWithResumeRetry(url, deviceId) {
 		let buf;
 		try {
-			buf = await runFfmpegFrameGrab(url, 15e3);
+			buf = await this.grabPool.run(() => runFfmpegFrameGrab(url, 15e3));
 		} catch (err) {
 			if (isBrokerColdError(errMsg(err))) {
 				this.ctx.logger.debug("grabFrame: broker-resume race — retrying in 1500ms", { tags: { deviceId } });
 				await new Promise((r) => setTimeout(r, 1500));
-				buf = await runFfmpegFrameGrab(url, 15e3);
+				buf = await this.grabPool.run(() => runFfmpegFrameGrab(url, 15e3));
 			} else throw err;
 		}
 		if (buf.length === 0) return null;
@@ -307,6 +591,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	}
 	async invalidateCache(input) {
 		this.cache.delete(input.deviceId);
+		this.captureFlight.invalidatePrefix(`${input.deviceId}:`);
 	}
 	/**
 	* Non-throwing probe of the device's battery cap. Returns true only
@@ -346,6 +631,30 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}
 	}
 	/**
+	* Cache-only batch overview — O(n) over the in-memory cache, NEVER triggers
+	* a capture. Lets a grid skip requesting images for devices that never
+	* produced a frame, and hands each an ETag for conditional image fetches.
+	*/
+	getSnapshotOverview(input) {
+		const now = Date.now();
+		const rows = input.deviceIds.map((deviceId) => {
+			const hit = this.cache.get(deviceId);
+			if (!hit) return {
+				deviceId,
+				lastCapturedAt: null,
+				cacheAgeMs: null,
+				etag: null
+			};
+			return {
+				deviceId,
+				lastCapturedAt: hit.ts,
+				cacheAgeMs: now - hit.ts,
+				etag: `"${deviceId}-${hit.ts}"`
+			};
+		});
+		return Promise.resolve(rows);
+	}
+	/**
 	* Diagnostic status for the `status` auto-injected cap method. Reports
 	* the cache bookkeeping for this device — when the last snapshot was
 	* captured, how stale the cached image is, its size, and which stream
@@ -502,6 +811,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}
 		await this.ctx.settings.writeDeviceStore(deviceId, next);
 		this.cache.delete(deviceId);
+		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 		return { success: true };
 	}
 };

package/dist/builtins/snapshot/snapshot-coalescing.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
+ * primitives for the snapshot wrapper.
+ *
+ * These are extracted from `SnapshotAddon` so the decision logic is unit-testable
+ * without instantiating the addon (no camera, no ffmpeg, no tRPC). The addon wires
+ * them to its cache + ladder; this module owns only the mechanics:
+ *
+ *   - {@link decideSnapshotServe} — the pure serve/refresh decision (fresh cache vs
+ *     stale-while-revalidate vs cold blocking capture) keyed off the cached frame
+ *     age, the per-device max-age, and whether the caller forced a refresh.
+ *   - {@link Semaphore} — a counting semaphore bounding concurrent grabs.
+ *   - {@link SingleFlight} — de-dupes concurrent captures for the same key and
+ *     retains a SETTLED success for a short hold window so a mount burst collapses
+ *     into one capture.
+ *   - {@link raceForResult} — races a promise against a wait bound without
+ *     cancelling the promise (the loser keeps running in the background).
+ */
+/**
+ * Retain a SETTLED single-flight capture this long so a grid-mount burst of
+ * `getSnapshot` calls (and a row of refresh buttons) collapses into ONE capture
+ * instead of one dial per tile. Only success outcomes are held — a null/failed
+ * capture expires immediately so a transiently-unreachable camera is retried on
+ * the next call rather than pinned blank for the window.
+ */
+export declare const COALESCE_MS = 4000;
+/**
+ * Stale-while-revalidate: when a cached frame exists but is past its max-age,
+ * start the refresh and wait at most this long for it to land before returning
+ * the STALE frame (the refresh keeps running and populates the cache for the
+ * next poll). Keeps a grid mount painting instantly from cache.
+ */
+export declare const SWR_STALE_WAIT_MS = 2500;
+/**
+ * Cold path (no cached frame) or a forced refresh: wait up to this long for a
+ * fresh capture. On a cold miss there is nothing to fall back to, so we block
+ * (bounded) on the capture; on a forced refresh with a stale frame available we
+ * still prefer a fresh one but cap the wait, falling back to stale on timeout.
+ */
+export declare const SWR_COLD_WAIT_MS = 10000;
+/**
+ * Max simultaneous ffmpeg keyframe grabs — the WRAPPER path, the common case for
+ * cameras with no vendor snapshot URL. A 20-cam grid mount spawns at most this
+ * many ffmpeg processes; the rest serve cached frames (SWR) or queue.
+ */
+export declare const MAX_CONCURRENT_GRABS = 3;
+/**
+ * Max simultaneous cheap native snapshot fetches (vendor HTTP/ONVIF). Higher than
+ * the ffmpeg bound because a native fetch is a lightweight HTTP round-trip, not a
+ * decode pipeline.
+ */
+export declare const MAX_CONCURRENT_NATIVE = 6;
+/**
+ * Serve either the fresh cache directly, or start/join a refresh and wait a
+ * bounded time. `await-refresh` always runs (or joins) the single flight;
+ * `waitMs` bounds how long the caller waits before, when `staleFallback` is set
+ * and a cached frame exists, returning the stale frame while the refresh
+ * continues in the background.
+ */
+export type SnapshotServeDecision = {
+    readonly kind: 'serve-cache';
+} | {
+    readonly kind: 'await-refresh';
+    readonly waitMs: number;
+    readonly staleFallback: boolean;
+};
+export interface SnapshotServeInputs {
+    readonly now: number;
+    /** Epoch ms of the cached frame, or null when nothing is cached. */
+    readonly cachedAt: number | null;
+    /** Effective per-device max cache age in ms (battery-aware default or override). */
+    readonly effectiveMaxAgeMs: number;
+    /** Caller forced a refresh (UI refresh button) — bypass the freshness gate. */
+    readonly force: boolean;
+}
+/**
+ * Pure serve/refresh decision.
+ *
+ *   - fresh cache + !force            -> serve-cache
+ *   - stale cache + !force            -> SWR: wait SWR_STALE_WAIT_MS, then stale
+ *   - no cache   + !force             -> cold: wait SWR_COLD_WAIT_MS, no fallback
+ *   - force (cache present or not)    -> prefer fresh: wait SWR_COLD_WAIT_MS,
+ *                                       fall back to stale only if a frame exists
+ */
+export declare function decideSnapshotServe(input: SnapshotServeInputs): SnapshotServeDecision;
+/**
+ * A counting semaphore. `run` acquires a permit, awaits `fn`, and releases the
+ * permit (even if `fn` throws), so at most `max` `fn`s run concurrently. Waiters
+ * are served FIFO.
+ */
+export declare class Semaphore {
+    private available;
+    private readonly waiters;
+    constructor(max: number);
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    private acquire;
+    private makeReleaser;
+}
+export declare class SingleFlight<T> {
+    private readonly holdMs;
+    private readonly holdWorthy;
+    private readonly now;
+    private readonly flights;
+    /**
+     * @param holdMs      how long a settled hold-worthy result is reused
+     * @param holdWorthy  predicate deciding whether a settled value is worth holding
+     *                    (e.g. a successful capture with a real frame)
+     * @param now         clock injection for tests
+     */
+    constructor(holdMs: number, holdWorthy: (value: T) => boolean, now?: () => number);
+    run(key: string, factory: () => Promise<T>): Promise<T>;
+    /** Drop every held flight whose key starts with `prefix` (e.g. `"<deviceId>:"`). */
+    invalidatePrefix(prefix: string): void;
+    clear(): void;
+    private isReusable;
+}
+export type RaceOutcome<T> = {
+    readonly settled: true;
+    readonly value: T;
+} | {
+    readonly settled: false;
+};
+/**
+ * Race `promise` against a `timeoutMs` bound WITHOUT cancelling it — on timeout
+ * the promise keeps running (its result lands in the cache for the next poll).
+ * Rejections propagate: if `promise` rejects before the timeout, this rejects.
+ * The caller passes a promise that never rejects (a settled outcome union) when
+ * background continuation must stay unhandled-safe.
+ */
+export declare function raceForResult<T>(promise: Promise<T>, timeoutMs: number): Promise<RaceOutcome<T>>;

package/dist/builtins/snapshot/snapshot.addon.d.ts

@@ -30,6 +30,16 @@ interface SnapshotAddonConfig {
  */
 export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
     private readonly cache;
+    /**
+     * De-dupes concurrent captures per `${deviceId}:${streamId}` and holds a
+     * settled SUCCESS for COALESCE_MS so a grid-mount burst (and a row of refresh
+     * buttons) collapses into one capture instead of one dial per tile.
+     */
+    private readonly captureFlight;
+    /** Bounds simultaneous ffmpeg keyframe grabs (the wrapper path — common case). */
+    private readonly grabPool;
+    /** Bounds simultaneous native (vendor HTTP/ONVIF) snapshot fetches. */
+    private readonly nativePool;
     /**
      * Cached resolution of `pipelineOrchestrator.getIngestOwner` — SnapshotAddon
      * has no per-request attach hook to resolve this fresh, so it's cached with
@@ -55,11 +65,31 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
     protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
     private getSnapshot;
     /**
-     * Tell apart "native provider isn't registered for this device" from
-     * "native provider ran and threw a real error". The former is the steady
-     * state for cameras without a vendor snapshot endpoint and should not
-     * propagate as a 500; the latter should.
+     * Map a settled capture outcome onto the response, preserving the legacy
+     * semantics: a fresh frame wins; a soft miss (native null + broker null)
+     * falls back to stale cache (or null); a HARD native error with no frame
+     * and no cache propagates.
      */
+    private resolveOutcome;
+    /**
+     * Run the capture ladder ONCE for a device: native provider first, then the
+     * stream-broker ffmpeg fallback. Never rejects — resolves a {@link
+     * CaptureOutcome}. On a produced frame it populates the cache (so a
+     * background SWR refresh lands for the next poll) and returns it. A hard
+     * native error with no broker frame resolves `{ ok:false }` so the caller
+     * can surface it; a soft miss resolves `{ ok:true, image:null }`.
+     *
+     * TODO(decoded-frame fast path): for a device whose detection pipeline is
+     * already decoding (the always-on subscription, see docs/design/decode-path.md),
+     * the freshest decoded frame is already in the shared-memory ring — a single
+     * JPEG encode of the latest FrameHandle would cost zero dials and beat the
+     * ffmpeg grab for the wrapper fleet. Slotting it as native -> latest-decoded
+     * -> broker needs cross-addon plumbing not cheaply reachable from the hub
+     * builtin today: frames are session-scoped (decoder `pullHandles`/`getFrame`
+     * need the device's active session id) and raw-pixel (need a JPEG encoder the
+     * builtin lacks). Deferred as its own slice.
+     */
+    private captureFresh;
     /**
      * Pull one JPEG from the device's stream-broker RTSP restream using
      * a short-lived ffmpeg invocation.
@@ -138,6 +168,12 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      * host) is byte-identical to the previous unpinned call.
      */
     private hasStreamingBrokerForDevice;
+    /**
+     * Cache-only batch overview — O(n) over the in-memory cache, NEVER triggers
+     * a capture. Lets a grid skip requesting images for devices that never
+     * produced a frame, and hands each an ETag for conditional image fetches.
+     */
+    private getSnapshotOverview;
     /**
      * Diagnostic status for the `status` auto-injected cap method. Reports
      * the cache bookkeeping for this device — when the last snapshot was

package/dist/builtins/sqlite-storage/filesystem-storage.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BCseJMTD.js");
+const require_dist = require("../../dist-BP89I7gi.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { E as filesystemBrowseCapability, J as storageProviderCapability, et as BaseAddon } from "../../dist-ClOjKsC4.mjs";
+import { E as filesystemBrowseCapability, J as storageProviderCapability, et as BaseAddon } from "../../dist-C68OyuEd.mjs";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
 import { basename, dirname, join, resolve, sep } from "node:path";

package/dist/builtins/sqlite-storage/sqlite-settings.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BCseJMTD.js");
+const require_dist = require("../../dist-BP89I7gi.js");
 let node_crypto = require("node:crypto");
 let better_sqlite3 = require("better-sqlite3");
 better_sqlite3 = require_chunk.__toESM(better_sqlite3);