@camstack/system 1.2.95 → 1.2.96

package/dist/builtins/snapshot/index.js

@@ -823,11 +823,34 @@ var LINK_MINT_DEADLINE_MS = 2500;
 var LINK_BATCH_WAIT_MS = 750;
 /** Frames older than this are never represented as current by the Viewer. */
 var LINK_CURRENT_MAX_AGE_MS = 15e3;
+/**
+* Memo TTL for the per-device `deviceManager.getDevice` lookup.
+*
+* Every serve decision — each `getSnapshotLinks` target, each media-plane GET,
+* each conditional-GET peek — used to pay this cross-process round trip (plus
+* the battery-slice one) before it could even look at the cache: 21-target
+* grids paid 42 UDS calls per 5 s poll, on top of the captures themselves
+* (live hub, 2026-08-15). Registry facts (name/type/disabled/online/features)
+* change on operator action or provider reconnect, not mid-second, so ten
+* seconds of staleness is invisible next to the poll cadence — and every
+* lifecycle event that changes one of those fields evicts the entry
+* immediately (see the `device.*` subscriptions in `onInitialize`).
+*
+* The BATTERY SLICE is deliberately NOT memoized: sleep/wake transitions must
+* be reactive (a camera that just fell asleep must not be dialed — the
+* Baichuan wake-on-login incident), and `waking` is already live from the
+* in-memory `wakingDevices` map.
+*/
+var DEVICE_META_MEMO_MS = 1e4;
 /** Wake-on-play's 8 s firmware wait + 20 s broker settle, with scheduling
 *  slack. A lost completion event must not leave a camera "Waking" forever. */
 var SNAPSHOT_WAKING_TTL_MS = 35e3;
-/** Default cache window for non-battery cams (seconds). 10s feels live. */
-var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
+/** Default cache window for non-battery cams (seconds). Matches the Viewer's
+*  15 s currency contract (`LINK_CURRENT_MAX_AGE_MS`): a frame younger than
+*  that is presented as current, so re-capturing INSIDE the window bought
+*  nothing the client would show — under the 5 s links poll it made every
+*  other poll recapture the whole fleet through the 6-permit grab pools. */
+var NON_BATTERY_DEFAULT_MAX_AGE_S = 15;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
 var BATTERY_DEFAULT_MAX_AGE_S = 3600;
 /**
@@ -879,6 +902,15 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	/** Devices inside the explicit battery wake-in-progress window. */
 	wakingDevices = /* @__PURE__ */ new Map();
 	/**
+	* Short-TTL memo for `lookupDeviceMeta` (see {@link DEVICE_META_MEMO_MS}).
+	* The PROMISE is stored (not the resolved value), so a burst of concurrent
+	* callers — a links batch plus the image fetches it mints — joins one
+	* in-flight lookup instead of stampeding `deviceManager.getDevice`.
+	* `fetchDeviceMeta` never rejects (failure → null), so a settled rejection
+	* can never be served from the memo.
+	*/
+	deviceMetaMemo = /* @__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.
@@ -949,6 +981,17 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			const deviceId = event.data.deviceId;
 			if (typeof deviceId === "number") this.evictRemovedDevice(deviceId, "device-unregistered");
 		});
+		const dropMetaMemo = (data) => {
+			const deviceId = data?.deviceId;
+			if (typeof deviceId === "number") this.deviceMetaMemo.delete(deviceId);
+		};
+		this.subscribe({ category: require_dist.EventCategory.DeviceRegistered }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceEnabled }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceDisabled }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceMetaChanged }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceOnline }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceOffline }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: require_dist.EventCategory.DeviceBindingsChanged }, (event) => dropMetaMemo(event.data));
 		this.subscribe({ category: require_dist.EventCategory.BatteryOnWakeStarted }, (event) => {
 			this.wakingDevices.set(event.data.deviceId, Date.now());
 		});
@@ -1245,7 +1288,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
 			force
-		}, 0, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, resolutionMeta);
+		}, 0, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, resolutionMeta, 0);
 		if (!image) return null;
 		const capturedAt = this.cache.get(deviceId, streamId)?.ts ?? Date.now();
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
@@ -1350,6 +1393,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		this.variants.clear();
 		this.stateFrames.clear();
 		this.wakingDevices.clear();
+		this.deviceMetaMemo.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -1382,7 +1426,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY, resolutionMeta) {
+	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY, resolutionMeta, staleWaitCapMs = Number.POSITIVE_INFINITY) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1445,7 +1489,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, Math.min(Math.max(decision.waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
+		const waitMs = !force && decision.staleFallback && hit !== void 0 ? Math.min(decision.waitMs, staleWaitCapMs) : decision.waitMs;
+		const raced = await raceForResult(flight, Math.min(Math.max(waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
 		if (raced.settled) try {
 			const resolved = await this.resolveOutcome(raced.value, deviceId, hit, log);
 			if (resolved !== null) return resolved;
@@ -1745,6 +1790,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		this.variants.deleteDevice(deviceId);
 		this.stateFrames.delete(deviceId);
 		this.wakingDevices.delete(deviceId);
+		this.deviceMetaMemo.delete(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 	}
 	/**
@@ -2052,17 +2098,35 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 	}
 	/**
-	* Single-trip device lookup against device-manager. Returns the
-	* stable registry fields the wrapper consults. Battery classification is
-	* completed by `resolveSnapshotState` from this feature flag PLUS the
-	* canonical runtime-state mirror, so a stale persisted feature projection
-	* cannot authorize a snapshot dial against a known sleeping battery camera.
+	* Single-trip device lookup against device-manager — memoized for
+	* {@link DEVICE_META_MEMO_MS} (promise-keyed, so bursts single-flight).
+	* Registry facts only; nothing battery-runtime lives here, so the TTL never
+	* masks a sleep/wake transition. Announced changes evict immediately (the
+	* `device.*` subscriptions in `onInitialize`); the TTL bounds silent drift.
+	*/
+	lookupDeviceMeta(deviceId) {
+		const hit = this.deviceMetaMemo.get(deviceId);
+		if (hit !== void 0 && Date.now() - hit.ts < DEVICE_META_MEMO_MS) return hit.promise;
+		const promise = this.fetchDeviceMeta(deviceId);
+		this.deviceMetaMemo.set(deviceId, {
+			ts: Date.now(),
+			promise
+		});
+		return promise;
+	}
+	/**
+	* The actual `deviceManager.getDevice` round trip behind
+	* {@link lookupDeviceMeta}. Returns the stable registry fields the wrapper
+	* consults. Battery classification is completed by `resolveSnapshotState`
+	* from this feature flag PLUS the canonical runtime-state mirror, so a stale
+	* persisted feature projection cannot authorize a snapshot dial against a
+	* known sleeping battery camera.
 	*
 	* Logged at debug + null return on failure: every call site already
 	* has a sensible fallback path (cache hit, conservative default, …),
 	* so we don't want a transient device-manager hiccup to throw.
 	*/
-	async lookupDeviceMeta(deviceId) {
+	async fetchDeviceMeta(deviceId) {
 		const api = this.ctx.api;
 		if (!api) return null;
 		try {

package/dist/builtins/snapshot/index.mjs

@@ -817,11 +817,34 @@ var LINK_MINT_DEADLINE_MS = 2500;
 var LINK_BATCH_WAIT_MS = 750;
 /** Frames older than this are never represented as current by the Viewer. */
 var LINK_CURRENT_MAX_AGE_MS = 15e3;
+/**
+* Memo TTL for the per-device `deviceManager.getDevice` lookup.
+*
+* Every serve decision — each `getSnapshotLinks` target, each media-plane GET,
+* each conditional-GET peek — used to pay this cross-process round trip (plus
+* the battery-slice one) before it could even look at the cache: 21-target
+* grids paid 42 UDS calls per 5 s poll, on top of the captures themselves
+* (live hub, 2026-08-15). Registry facts (name/type/disabled/online/features)
+* change on operator action or provider reconnect, not mid-second, so ten
+* seconds of staleness is invisible next to the poll cadence — and every
+* lifecycle event that changes one of those fields evicts the entry
+* immediately (see the `device.*` subscriptions in `onInitialize`).
+*
+* The BATTERY SLICE is deliberately NOT memoized: sleep/wake transitions must
+* be reactive (a camera that just fell asleep must not be dialed — the
+* Baichuan wake-on-login incident), and `waking` is already live from the
+* in-memory `wakingDevices` map.
+*/
+var DEVICE_META_MEMO_MS = 1e4;
 /** Wake-on-play's 8 s firmware wait + 20 s broker settle, with scheduling
 *  slack. A lost completion event must not leave a camera "Waking" forever. */
 var SNAPSHOT_WAKING_TTL_MS = 35e3;
-/** Default cache window for non-battery cams (seconds). 10s feels live. */
-var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
+/** Default cache window for non-battery cams (seconds). Matches the Viewer's
+*  15 s currency contract (`LINK_CURRENT_MAX_AGE_MS`): a frame younger than
+*  that is presented as current, so re-capturing INSIDE the window bought
+*  nothing the client would show — under the 5 s links poll it made every
+*  other poll recapture the whole fleet through the 6-permit grab pools. */
+var NON_BATTERY_DEFAULT_MAX_AGE_S = 15;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
 var BATTERY_DEFAULT_MAX_AGE_S = 3600;
 /**
@@ -873,6 +896,15 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	/** Devices inside the explicit battery wake-in-progress window. */
 	wakingDevices = /* @__PURE__ */ new Map();
 	/**
+	* Short-TTL memo for `lookupDeviceMeta` (see {@link DEVICE_META_MEMO_MS}).
+	* The PROMISE is stored (not the resolved value), so a burst of concurrent
+	* callers — a links batch plus the image fetches it mints — joins one
+	* in-flight lookup instead of stampeding `deviceManager.getDevice`.
+	* `fetchDeviceMeta` never rejects (failure → null), so a settled rejection
+	* can never be served from the memo.
+	*/
+	deviceMetaMemo = /* @__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.
@@ -943,6 +975,17 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			const deviceId = event.data.deviceId;
 			if (typeof deviceId === "number") this.evictRemovedDevice(deviceId, "device-unregistered");
 		});
+		const dropMetaMemo = (data) => {
+			const deviceId = data?.deviceId;
+			if (typeof deviceId === "number") this.deviceMetaMemo.delete(deviceId);
+		};
+		this.subscribe({ category: EventCategory.DeviceRegistered }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceEnabled }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceDisabled }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceMetaChanged }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceOnline }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceOffline }, (event) => dropMetaMemo(event.data));
+		this.subscribe({ category: EventCategory.DeviceBindingsChanged }, (event) => dropMetaMemo(event.data));
 		this.subscribe({ category: EventCategory.BatteryOnWakeStarted }, (event) => {
 			this.wakingDevices.set(event.data.deviceId, Date.now());
 		});
@@ -1239,7 +1282,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
 			force
-		}, 0, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, resolutionMeta);
+		}, 0, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, resolutionMeta, 0);
 		if (!image) return null;
 		const capturedAt = this.cache.get(deviceId, streamId)?.ts ?? Date.now();
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
@@ -1344,6 +1387,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		this.variants.clear();
 		this.stateFrames.clear();
 		this.wakingDevices.clear();
+		this.deviceMetaMemo.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -1376,7 +1420,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY, resolutionMeta) {
+	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY, resolutionMeta, staleWaitCapMs = Number.POSITIVE_INFINITY) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1439,7 +1483,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, Math.min(Math.max(decision.waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
+		const waitMs = !force && decision.staleFallback && hit !== void 0 ? Math.min(decision.waitMs, staleWaitCapMs) : decision.waitMs;
+		const raced = await raceForResult(flight, Math.min(Math.max(waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
 		if (raced.settled) try {
 			const resolved = await this.resolveOutcome(raced.value, deviceId, hit, log);
 			if (resolved !== null) return resolved;
@@ -1739,6 +1784,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		this.variants.deleteDevice(deviceId);
 		this.stateFrames.delete(deviceId);
 		this.wakingDevices.delete(deviceId);
+		this.deviceMetaMemo.delete(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 	}
 	/**
@@ -2046,17 +2092,35 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}
 	}
 	/**
-	* Single-trip device lookup against device-manager. Returns the
-	* stable registry fields the wrapper consults. Battery classification is
-	* completed by `resolveSnapshotState` from this feature flag PLUS the
-	* canonical runtime-state mirror, so a stale persisted feature projection
-	* cannot authorize a snapshot dial against a known sleeping battery camera.
+	* Single-trip device lookup against device-manager — memoized for
+	* {@link DEVICE_META_MEMO_MS} (promise-keyed, so bursts single-flight).
+	* Registry facts only; nothing battery-runtime lives here, so the TTL never
+	* masks a sleep/wake transition. Announced changes evict immediately (the
+	* `device.*` subscriptions in `onInitialize`); the TTL bounds silent drift.
+	*/
+	lookupDeviceMeta(deviceId) {
+		const hit = this.deviceMetaMemo.get(deviceId);
+		if (hit !== void 0 && Date.now() - hit.ts < DEVICE_META_MEMO_MS) return hit.promise;
+		const promise = this.fetchDeviceMeta(deviceId);
+		this.deviceMetaMemo.set(deviceId, {
+			ts: Date.now(),
+			promise
+		});
+		return promise;
+	}
+	/**
+	* The actual `deviceManager.getDevice` round trip behind
+	* {@link lookupDeviceMeta}. Returns the stable registry fields the wrapper
+	* consults. Battery classification is completed by `resolveSnapshotState`
+	* from this feature flag PLUS the canonical runtime-state mirror, so a stale
+	* persisted feature projection cannot authorize a snapshot dial against a
+	* known sleeping battery camera.
 	*
 	* Logged at debug + null return on failure: every call site already
 	* has a sensible fallback path (cache hit, conservative default, …),
 	* so we don't want a transient device-manager hiccup to throw.
 	*/
-	async lookupDeviceMeta(deviceId) {
+	async fetchDeviceMeta(deviceId) {
 		const api = this.ctx.api;
 		if (!api) return null;
 		try {

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

@@ -48,6 +48,15 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
     private readonly stateFrames;
     /** Devices inside the explicit battery wake-in-progress window. */
     private readonly wakingDevices;
+    /**
+     * Short-TTL memo for `lookupDeviceMeta` (see {@link DEVICE_META_MEMO_MS}).
+     * The PROMISE is stored (not the resolved value), so a burst of concurrent
+     * callers — a links batch plus the image fetches it mints — joins one
+     * in-flight lookup instead of stampeding `deviceManager.getDevice`.
+     * `fetchDeviceMeta` never rejects (failure → null), so a settled rejection
+     * can never be served from the memo.
+     */
+    private readonly deviceMetaMemo;
     /**
      * 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
@@ -433,17 +442,26 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      */
     private stateImage;
     /**
-     * Single-trip device lookup against device-manager. Returns the
-     * stable registry fields the wrapper consults. Battery classification is
-     * completed by `resolveSnapshotState` from this feature flag PLUS the
-     * canonical runtime-state mirror, so a stale persisted feature projection
-     * cannot authorize a snapshot dial against a known sleeping battery camera.
+     * Single-trip device lookup against device-manager — memoized for
+     * {@link DEVICE_META_MEMO_MS} (promise-keyed, so bursts single-flight).
+     * Registry facts only; nothing battery-runtime lives here, so the TTL never
+     * masks a sleep/wake transition. Announced changes evict immediately (the
+     * `device.*` subscriptions in `onInitialize`); the TTL bounds silent drift.
+     */
+    private lookupDeviceMeta;
+    /**
+     * The actual `deviceManager.getDevice` round trip behind
+     * {@link lookupDeviceMeta}. Returns the stable registry fields the wrapper
+     * consults. Battery classification is completed by `resolveSnapshotState`
+     * from this feature flag PLUS the canonical runtime-state mirror, so a stale
+     * persisted feature projection cannot authorize a snapshot dial against a
+     * known sleeping battery camera.
      *
      * Logged at debug + null return on failure: every call site already
      * has a sensible fallback path (cache hit, conservative default, …),
      * so we don't want a transient device-manager hiccup to throw.
      */
-    private lookupDeviceMeta;
+    private fetchDeviceMeta;
     /** Settings-UI helper — battery flag drives the default max-age in the field description. */
     private isDeviceBattery;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.95",
+  "version": "1.2.96",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",