@camstack/system 1.2.390 → 1.2.391

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

@@ -1,580 +1,581 @@
-import { AddonApi, ProfileSlot, ProviderRegistration, RtspRestreamEntry, BaseAddon } from '@camstack/types';
-import { JpegResizer } from './snapshot-resize.js';
+import type { AddonApi, ConfigUISchema, ProfileSlot, ProviderRegistration, RtspRestreamEntry } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
+import { type JpegResizer } from "./snapshot-resize.js";
 interface SnapshotAddonConfig {
-    /**
-     * Last-resort cache age (ms): if every live capture path fails
-     * (native + stream-broker fallback) AND a stale entry is older
-     * than this, the wrapper still returns the stale image rather
-     * than `null`. Keeps the UI from going blank during transient
-     * camera unreachability. Per-device freshness is governed by
-     * `snapshotMaxAgeS` instead.
-     */
-    readonly staleTtlMs: number;
+	/**
+	* Last-resort cache age (ms): if every live capture path fails
+	* (native + stream-broker fallback) AND a stale entry is older
+	* than this, the wrapper still returns the stale image rather
+	* than `null`. Keeps the UI from going blank during transient
+	* camera unreachability. Per-device freshness is governed by
+	* `snapshotMaxAgeS` instead.
+	*/
+	readonly staleTtlMs: number;
 }
 /**
- * SnapshotAddon — wrapper over the `snapshot` capability.
- *
- * Activated per-device (toggleable by user; default active). When active,
- * caches fresh snapshots in memory. On cache miss, delegates to the native
- * provider for this device via `ctx.getNativeProvider(snapshotCapability, id)`.
- *
- * No silent fallback — if the native fails, propagate the error up. Stale
- * cache is returned ONLY when the native throws AND a stale entry exists,
- * and the failure is logged so the fallback is never silent.
- *
- * Frame-grab fallback: when the native provider is absent (or returns null /
- * throws), we ask the `stream-broker` capability for the device's RTSP
- * restream URL and pipe one JPEG out of ffmpeg. stream-broker intentionally
- * does NOT expose a `grabFrame` method — the orchestration (native-first,
- * ffmpeg fallback, caching) is this addon's concern; stream-broker only
- * publishes stream endpoints.
- */
+* SnapshotAddon — wrapper over the `snapshot` capability.
+*
+* Activated per-device (toggleable by user; default active). When active,
+* caches fresh snapshots in memory. On cache miss, delegates to the native
+* provider for this device via `ctx.getNativeProvider(snapshotCapability, id)`.
+*
+* No silent fallback — if the native fails, propagate the error up. Stale
+* cache is returned ONLY when the native throws AND a stale entry exists,
+* and the failure is logged so the fallback is never silent.
+*
+* Frame-grab fallback: when the native provider is absent (or returns null /
+* throws), we ask the `stream-broker` capability for the device's RTSP
+* restream URL and pipe one JPEG out of ffmpeg. stream-broker intentionally
+* does NOT expose a `grabFrame` method — the orchestration (native-first,
+* ffmpeg fallback, caching) is this addon's concern; stream-broker only
+* publishes stream endpoints.
+*/
 export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
-    /**
-     * The frame cache. Bounded by a byte budget + an idle timeout — it used to be
-     * unbounded in both. Every eviction is logged with the device tag: a frame
-     * that silently left the cache is the reason a later capture had to happen,
-     * and per-camera is the only way that question is ever asked.
-     */
-    /** Cameras resting after a native miss — see `snapshot-fatigue.ts`. */
-    private readonly fatigue;
-    /**
-     * The last good frame per camera, on disk, so it outlives the process.
-     *
-     * The cache above is RAM-only and the cameras that most need it are the ones
-     * that can never be asked for a fresh frame: a sleeping battery camera
-     * refuses every snapshot without `force`, and the background callers that
-     * would want one deliberately never pass it. Measured 2026-09-17 — the baby
-     * monitor showed the courtesy card all morning because three server updates
-     * had emptied this cache and the camera had been asleep since.
-     */
-    private durableStore;
-    /**
-     * Built on first use, never in a field initializer: `ctx` does not exist
-     * until `initialize()`, and reading it at construction throws
-     * "ctx accessed before initialize()" for the whole addon.
-     */
-    private get durable();
-    private readonly cache;
-    /** Card-sized derivatives of the frames above, keyed by width and validated
-     *  against the source frame's timestamp. */
-    private readonly variants;
-    /**
-     * Rendered courtesy frames, by (reason, size, device name).
-     *
-     * A courtesy frame is a pure function of those three, so it is rendered once
-     * and reused for as long as the process lives — a disabled camera must not
-     * cost an ffmpeg run per poll. Unbounded on purpose: the key space is
-     * (state reasons × this node's own cameras), not user input.
-     */
-    private readonly courtesyFrames;
-    /** State overlays over real cached frames, grouped by device so invalidation
-     *  can discard every generation in O(1). */
-    private readonly stateFrames;
-    /** Devices inside the explicit battery wake-in-progress window. */
-    private readonly wakingDevices;
-    /** Last sleeping flag per battery device, for wake-EDGE detection (the map
-     *  starts empty; only an observed true→false transition is a wake). */
-    private readonly lastKnownSleeping;
-    /**
-     * 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
-     * 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;
-    /** This node's PINNED ffmpeg (D540), asked once. The keyframe grab used to
-     *  spawn a bare `'ffmpeg'` — the HOST's binary — off PATH. */
-    private readonly pinnedFfmpeg;
-    /** 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
-     * a short TTL and invalidated on `onConfigChanged` (covers the common case
-     * of an operator re-saving cluster/agent settings). A stale owner for up to
-     * `OWNER_CACHE_TTL_MS` just means a snapshot fallback briefly targets the
-     * previous ingest owner — self-heals on the next resolve.
-     */
-    private ownerCache;
-    private static readonly OWNER_CACHE_TTL_MS;
-    /**
-     * Handle for the `/addon/snapshot/media/<deviceId>.jpg` HTTP data-plane
-     * endpoint (§3.1). Null when the host provides no `ctx.dataPlane` facility
-     * (the tRPC `getSnapshot` base64 surface still works — the endpoint is a
-     * strictly-additive delivery path). Disposed on shutdown.
-     */
-    private mediaDataPlane;
-    /**
-     * The PUBLIC, signature-authenticated twin of the media plane. Null when the
-     * host has no `ctx.dataPlane` facility, or before the per-install secret has
-     * been minted — in which case `getSnapshotLinks` reports `url: null` and the
-     * client keeps using the authenticated plane exactly as before.
-     */
-    private linkDataPlane;
-    /** Per-install HMAC secret for link signatures. Minted once and persisted: a
-     *  secret that rolled on every boot would invalidate every link a client is
-     *  currently holding, which is a fleet-wide blank grid after each restart. */
-    private linkSecret;
-    /**
-     * In-flight `serveLinkDataPlane` attempt, so the retry below cannot start a
-     * second one while the first is still awaiting the settings store.
-     */
-    private linkPlaneAttempt;
-    /**
-     * How a full frame becomes a card-sized one. Defaults to the real ffmpeg
-     * resize; injectable so the wrapper's own logic is testable without spawning a
-     * process for every fixture. `JpegResizer` was declared for exactly this and
-     * had no injector — which is why the resize-failure path had never been
-     * exercised anywhere but production.
-     */
-    private readonly resize;
-    constructor(resize?: JpegResizer);
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    /**
-     * Serve the per-device snapshot image endpoint on the addon data-plane
-     * (§3.1). Delivery: `GET /addon/snapshot/media/<deviceId>.jpg` → raw JPEG with
-     * `ETag` + `Cache-Control: private, max-age=<device maxAgeS>`, so a grid is N
-     * independent `<Image>` tiles served from the coalesced server cache (no
-     * base64 tax, no batch head-of-line blocking, browser/`expo-image` caching for
-     * free). Best-effort: a host without a `dataPlane` facility keeps the tRPC
-     * base64 path.
-     */
-    private serveMediaDataPlane;
-    /**
-     * Serve the link plane if it is not already served — at init, and again on
-     * the first `getSnapshotLinks` after an attempt that could not finish.
-     *
-     * The retry is not defensive padding, it is the whole reason this wrapper
-     * exists. The plane needs a persisted signing secret, and the secret needs
-     * the settings store; this addon now boots in its OWN process, so "the store
-     * is not answering yet" is a state it can genuinely observe. A one-shot
-     * attempt turns that instant into a permanent condition: `linkDataPlane`
-     * stays null, every `getSnapshotLinks` row answers `url: null`, and every
-     * tile on every grid stays blank until someone restarts the runner. Nothing
-     * in the logs would say why, because nothing failed twice.
-     *
-     * Single-flighted: a burst of link requests joins one attempt.
-     */
-    private ensureLinkDataPlane;
-    /**
-     * Serve the PUBLIC link plane: `GET /addon/snapshot/link/<deviceId>.jpg?w&v&exp&sig`.
-     *
-     * `access: 'public'` is deliberate and is the only interesting decision here.
-     * The authority is the HMAC, exactly as for the notification artifact plane
-     * and the Home Assistant media plane — but unlike those, what sits behind it
-     * is a LIVE view of the operator's home, so the compensating choices are
-     * explicit: a short TTL (`SNAPSHOT_LINK_TTL_MS`), the width inside the signed
-     * identity so a leaked tile cannot be escalated to the full frame, and
-     * **`force` is not honoured on this route at all** — a public URL must never
-     * be able to wake a battery camera.
-     *
-     * A leaked link therefore grants: one camera, at one thumbnail width, for at
-     * most the TTL. No token, no other device, no session.
-     */
-    private serveLinkDataPlane;
-    /**
-     * Verify first, then hand the request to the ordinary media handler with a
-     * REWRITTEN url carrying only the signed `(deviceId, width)`.
-     *
-     * Rewriting rather than passing the original through is what stops an unsigned
-     * query parameter reaching the capture path: `force`, `streamId` and any other
-     * lever the authenticated plane honours are simply not present in what the
-     * handler parses.
-     */
-    private handleLinkRequest;
-    private linkRoutePrefix;
-    /**
-     * Mint-once-and-persist the signing secret. Null when it cannot be
-     * ESTABLISHED — a secret held only in memory would break every outstanding
-     * link on restart, so no plane is better than a plane whose links die
-     * unpredictably.
-     *
-     * A null is never cached, so the next `getSnapshotLinks` tries again. That
-     * matters now the wrapper runs in its own process: the settings store can be
-     * a moment behind at boot, and this used to be a one-shot.
-     *
-     * The read-back is the gate. `state.get()` cannot distinguish "no secret
-     * yet" from "the store could not be read" — `readAddonStoreWithRetry` gives
-     * up and answers `{}` — so a store that is merely slow reads as empty and
-     * this would mint a SECOND secret over a perfectly good first one, silently
-     * invalidating every link a client is holding. Reading back what we just
-     * wrote is the only evidence available at this layer that the store is
-     * actually answering, and a mismatch means it is not.
-     */
-    private ensureLinkSecret;
-    /**
-     * Mint signed links for the tiles a surface is rendering — and, in the same
-     * call, make those tiles CURRENT.
-     *
-     * This is the demand signal the design was missing. Under D93 enrolment rode
-     * on the image request, and D93/D94/D95 each fixed a different way for that
-     * request not to happen; none of them could fix the last one, because the
-     * client's own image cache answers a repeated URL with no network at all. An
-     * RPC has no such cache in front of it.
-     *
-     * So: note every target (creating a subscription, which `getSnapshotOverview`
-     * deliberately cannot), then join the ordinary non-forced capture path and
-     * wait a BOUNDED time for it. The Viewer never presents a frame older than
-     * 15 seconds as current, so this path tightens a looser per-device cache
-     * window to that contract without using `force` (and its battery-wake
-     * semantics). What comes back is the identity of the frame the link serves.
-     *
-     * The bound matters more than its exact value. A cold fleet is paced by
-     * `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
-     * the last of them would hold the whole batch well past any sensible paint
-     * budget. Devices that miss the bound return their real, older `capturedAt` —
-     * honest rather than blocking — and the client's next poll carries them
-     * forward.
-     */
-    private getSnapshotLinks;
-    /**
-     * The debug readout's data — the decision chain for one device, cache-only
-     * and capture-free (a debug poll must never wake a battery camera).
-     */
-    private getSnapshotDebugState;
-    /**
-     * Join the ordinary capture path for one device and wait, bounded, for it.
-     *
-     * Deliberately `getSnapshot` with `force: false`: the single flight, grab
-     * pool, and sleeping-battery refusal apply unchanged. The only override is
-     * the Viewer's 15-second currency contract and the link-mint wait bound.
-     */
-    private awaitFreshEnough;
-    /**
-     * The one fresh frame an awake battery camera gets outside an active stream:
-     * captured at the WAKE edge, because the link poll deliberately never
-     * recaptures an idle-awake battery camera (every capture is a camera hit
-     * that would keep it out of sleep — the link-mint gate documents the
-     * incident).
-     *
-     * `force: true` is correct here — not a violation of "never wake for a
-     * snapshot": the camera is ALREADY awake (the status edge is what fired),
-     * and the battery 1 h cache default would otherwise answer the wake with
-     * the pre-sleep frame. The single flight coalesces a burst of edges; one
-     * delayed retry covers a camera whose status flipped a beat before its
-     * snapshot endpoint is actually answering (firmware boot lag).
-     */
-    private captureOnWake;
-    /** Resolve the state advertised by a minted link before deciding whether a
-     *  background capture is allowed. */
-    private snapshotStateForLink;
-    /**
-     * Resolve a device (+ optional stream, + force) to renderable JPEG bytes for
-     * the HTTP endpoint. Runs the same coalesced capture ladder as the tRPC
-     * `getSnapshot` (so every consumer shares one upstream pull), then decodes the
-     * base64 cache into raw bytes and stamps the frame identity: `capturedAt` from
-     * the cache entry (matching the ETag `getSnapshotOverview` advertises) and the
-     * effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
-     */
-    private resolveSnapshotMedia;
-    /**
-     * Cache-only freshness peek for the data-plane's conditional-GET fast path.
-     * Never captures, never resizes, never dials anything: a cached frame that is
-     * still inside its per-device max-age, or null.
-     *
-     * Returning null for a STALE entry is the important half. A 304 there would
-     * pin the tile to the old frame for as long as the client kept revalidating,
-     * which is the exact staleness this change exists to remove.
-     */
-    private peekFreshFrame;
-    /**
-     * The frame at a card-sized width, derived once per
-     * (device, stream, width, state treatment) per capture.
-     *
-     * A failed resize falls back to the FULL frame — a visible card beats a
-     * broken one — but never silently: the card would otherwise keep costing a
-     * megabyte with nothing anywhere saying why, which is the shape of the bug
-     * this whole change came from.
-     */
-    private thumbnailBytes;
-    protected onShutdown(): Promise<void>;
-    /**
-     * Drop the cached ingest owner whenever addon-level settings change —
-     * cheap, correct-by-construction refresh point (BaseAddon calls this
-     * after every `updateGlobalSettings`/`updateAddonSettings`). Combined
-     * with the TTL in `resolveIngestOwner`, a cluster topology change is
-     * picked up either on the next settings save or within
-     * `OWNER_CACHE_TTL_MS`, whichever comes first.
-     */
-    protected onConfigChanged(): Promise<void>;
-    protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
-    private getSnapshot;
-    /**
-     * 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;
-    /**
-     * Reconcile backstop for a stale hit: is the frame we are about to serve the
-     * property of a device that no longer exists?
-     *
-     * Asked ONLY past `staleTtlMs`, which is already the "something is wrong"
-     * threshold — so the common path costs nothing. A `true` answer evicts and
-     * the caller returns null; anything else leaves the existing
-     * keep-the-UI-from-going-blank contract untouched.
-     */
-    private staleHitBelongsToRemovedDevice;
-    /**
-     * 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.
-     *
-     * Stream selection strategy (picks the broker that won't stall):
-     *   1. Explicit `preferredStreamId` (user set in per-device settings)
-     *      — always honoured, even if currently idle. Operator choice
-     *      wins.
-     *   2. Auto: highest-quality broker currently in `streaming` state.
-     *      This is the whole point — prefer the stream that has active
-     *      subscribers (usually `low` for detection, but `mid`/`high`
-     *      if WebRTC is watching) so ffmpeg hits a warm pipe and
-     *      doesn't race the broker's resume.
-     *   3. Fallback: highest-quality enabled entry regardless of status
-     *      (will wake a suspended broker — retry-guarded against the
-     *      cold-start error).
-     *
-     * The stream-broker auto-suspends idle streams on the "no demand"
-     * signal; snapshots used to default to `high` which was often the
-     * first to go idle, racing every snapshot with a broker resume.
-     * Now we ask the orchestrator of streams which one is warm and grab
-     * from there.
-     *
-     * Source acquisition is pinned to the cluster's ingest owner (the node
-     * the stream-broker actually runs on) instead of the device-scoped
-     * `dev.cameraStreams` facade — `dev.cameraStreams` resolves against
-     * whichever node the cap-router picks by default, which double-pulls
-     * the camera (or dials a hub-local restream that isn't serving) when
-     * `ingestNode != hub`. `fetchSnapshotBrokerEntries` does the pinned
-     * fetch + owner-relative URL host rewrite; hub-owner + no reachable
-     * host is byte-identical to the previous unpinned call.
-     */
-    private grabFrameFromBroker;
-    /**
-     * Cached, TTL-bounded resolution of the cluster's camera-source owner.
-     * See `ownerCache` doc for the invalidation story.
-     */
-    private resolveIngestOwner;
-    /**
-     * Same graceful degrade as the recorder's `resolveIngestOwner`
-     * (`packages/addon-pipeline/src/recorder/addon/index.ts`) — the cap may
-     * not be mounted yet (pre-image-release) or the pipeline-orchestrator
-     * addon may be absent entirely; either way we fall back to `'hub'`,
-     * which is byte-identical to the previous hardcoded hub-only behaviour.
-     */
-    private fetchIngestOwner;
-    /**
-     * Ffmpeg grab with one retry on the broker-cold-start error
-     * signature. Covers the window between "client connected" and
-     * "first keyframe" when a suspended broker resumes.
-     */
-    private runGrabWithResumeRetry;
-    private invalidateCache;
-    /** Forget every cached artefact of one device: frames, derived variants and
-     *  any settled single-flight result that would answer the next request. */
-    private dropDeviceCaches;
-    /**
-     * The device is GONE — drop its cached frames and say so.
-     *
-     * Distinct from `invalidateCache` (a refresh, expected and silent): this is
-     * the terminal case, and a deleted camera that keeps answering with its last
-     * JPEG looks to an operator exactly like a camera that was never deleted.
-     */
-    private evictRemovedDevice;
-    /**
-     * Does device-manager still know this id?
-     *
-     * `null` means the question could not be answered — a transport hiccup is
-     * not a deletion (D49), and the caller keeps serving what it has. Only an
-     * explicit "no such device" evicts.
-     */
-    private deviceStillExists;
-    /**
-     * Resolve the state that must be visible on a snapshot.
-     *
-     * Uses the same two canonical sources as wake-on-play:
-     *  1. `deviceManager.getDevice` for the registry's BatteryOperated feature;
-     *  2. `deviceState.getCapSlice('battery')` for the durable runtime mirror.
-     *
-     * A valid battery slice is itself positive evidence that the device is
-     * battery-operated. That closes the field failure where "Baby monitor" had a
-     * sleeping battery slice but a stale persisted feature projection, so the
-     * snapshot wrapper classified it as mains and a Viewer thumbnail logged in
-     * to the sleeping camera. The reverse is deliberately not guessed: no
-     * feature + no valid slice remains a mains/unknown camera and follows the
-     * ordinary capture path.
-     *
-     * Once battery-operated is established, a missing slice fails safe toward
-     * `sleeping` through the shared `deriveBatteryPresence` function. This avoids
-     * a background wake without inventing an `unreachable` fault.
-     */
-    private resolveSnapshotState;
-    private isDeviceWaking;
-    /**
-     * True when at least one of the device's brokers is actively
-     * streaming (status === 'streaming'). Used by the battery-cam guard
-     * around `grabFrameFromBroker` to allow the fallback ONLY when
-     * grabbing a frame is free (a consumer is already keeping the
-     * stream warm). When everything is suspended, the fallback would
-     * dial the camera and wake it — defeats the sleeping cache.
-     *
-     * Pinned to the ingest owner via `fetchSnapshotBrokerEntries` — same
-     * rationale as `grabFrameFromBroker`: the device-scoped
-     * `dev.cameraStreams` facade resolves against whichever node the
-     * cap-router picks by default, which is wrong once `ingestNode !=
-     * hub` (queries the hub for slots that only exist on the agent,
-     * always reporting no streaming broker). Owner === hub (no reachable
-     * 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
-     * captured, how stale the cached image is, its size, and which stream
-     * was used. Returns null when the device has never been captured
-     * (cache miss) since the addon started.
-     */
-    private getStatus;
-    private readDeviceSettings;
-    private buildDeviceSettingsContribution;
-    /**
-     * The frame a camera that CANNOT capture answers with.
-     *
-     * Returns null only if rendering itself fails — the caller then falls through
-     * to its previous behaviour, so a broken courtesy path degrades to the old
-     * 404 rather than masking a real capture failure as a placeholder.
-     *
-     * Rendered at the full tile size; the existing resize ladder derives the
-     * card-sized variants from it exactly as it does for a real frame, so no
-     * downstream consumer needs to know this frame is synthetic.
-     */
-    private courtesyFrame;
-    /** A courtesy frame shaped as the cap's response, or null when unrenderable. */
-    private courtesyImage;
-    /**
-     * The answer for a camera the hub cannot reach: its last good frame, with
-     * `Offline` painted over it, and `offline` stamped on the response identity.
-     *
-     * Called only AFTER the ladder has run (offline is not in
-     * {@link CAPTURE_BLOCKING_REASONS}), so this dresses a frame that could not be
-     * refreshed — never one that just landed.
-     *
-     * The `stateReason` is set FIRST and unconditionally, because it is what a
-     * surface labels the tile from and what puts `offline` in the ETag: a client
-     * holding the live frame has to see a new identity the moment the camera
-     * drops, or it paints the unlabelled photograph until the camera comes back.
-     * A failed render therefore degrades to the raw frame rather than to nothing —
-     * the metadata still says offline, so the tile is still honest.
-     */
-    private offlineImage;
-    /**
-     * Render a state-labelled answer. A cached real frame is the background, not
-     * the answer by itself; if it cannot be decoded, fall back to the generated
-     * courtesy background rather than leaking an unlabelled stale frame.
-     */
-    /** The persisted frame as a cache entry, with its real age. */
-    private durableEntry;
-    private stateImage;
-    /**
-     * 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 fetchDeviceMeta;
-    /** Settings-UI helper — battery flag drives the default max-age in the field description. */
-    private isDeviceBattery;
-    /**
-     * Feeds the settings-UI stream picker. Pinned to the ingest owner via
-     * `fetchSnapshotBrokerEntries` — the device-scoped `dev.cameraStreams`
-     * facade this used to call resolves against whichever node the
-     * cap-router picks by default, which is empty once `ingestNode !=
-     * hub` (the picker would render nothing but "Auto"). Owner === hub
-     * (no reachable host) is byte-identical to the previous unpinned call.
-     */
-    private getStreamOptions;
-    private saveDeviceSettingsPatch;
+	/**
+	* The frame cache. Bounded by a byte budget + an idle timeout — it used to be
+	* unbounded in both. Every eviction is logged with the device tag: a frame
+	* that silently left the cache is the reason a later capture had to happen,
+	* and per-camera is the only way that question is ever asked.
+	*/
+	/** Cameras resting after a native miss — see `snapshot-fatigue.ts`. */
+	private readonly fatigue;
+	/**
+	* The last good frame per camera, on disk, so it outlives the process.
+	*
+	* The cache above is RAM-only and the cameras that most need it are the ones
+	* that can never be asked for a fresh frame: a sleeping battery camera
+	* refuses every snapshot without `force`, and the background callers that
+	* would want one deliberately never pass it. Measured 2026-09-17 — the baby
+	* monitor showed the courtesy card all morning because three server updates
+	* had emptied this cache and the camera had been asleep since.
+	*/
+	private durableStore;
+	/**
+	* Built on first use, never in a field initializer: `ctx` does not exist
+	* until `initialize()`, and reading it at construction throws
+	* "ctx accessed before initialize()" for the whole addon.
+	*/
+	private get durable();
+	private readonly cache;
+	/** Card-sized derivatives of the frames above, keyed by width and validated
+	*  against the source frame's timestamp. */
+	private readonly variants;
+	/**
+	* Rendered courtesy frames, by (reason, size, device name).
+	*
+	* A courtesy frame is a pure function of those three, so it is rendered once
+	* and reused for as long as the process lives — a disabled camera must not
+	* cost an ffmpeg run per poll. Unbounded on purpose: the key space is
+	* (state reasons × this node's own cameras), not user input.
+	*/
+	private readonly courtesyFrames;
+	/** State overlays over real cached frames, grouped by device so invalidation
+	*  can discard every generation in O(1). */
+	private readonly stateFrames;
+	/** Devices inside the explicit battery wake-in-progress window. */
+	private readonly wakingDevices;
+	/** Last sleeping flag per battery device, for wake-EDGE detection (the map
+	*  starts empty; only an observed true→false transition is a wake). */
+	private readonly lastKnownSleeping;
+	/**
+	* 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
+	* 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;
+	/** This node's PINNED ffmpeg (D540), asked once. The keyframe grab used to
+	*  spawn a bare `'ffmpeg'` — the HOST's binary — off PATH. */
+	private readonly pinnedFfmpeg;
+	/** 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
+	* a short TTL and invalidated on `onConfigChanged` (covers the common case
+	* of an operator re-saving cluster/agent settings). A stale owner for up to
+	* `OWNER_CACHE_TTL_MS` just means a snapshot fallback briefly targets the
+	* previous ingest owner — self-heals on the next resolve.
+	*/
+	private ownerCache;
+	private static readonly OWNER_CACHE_TTL_MS;
+	/**
+	* Handle for the `/addon/snapshot/media/<deviceId>.jpg` HTTP data-plane
+	* endpoint (§3.1). Null when the host provides no `ctx.dataPlane` facility
+	* (the tRPC `getSnapshot` base64 surface still works — the endpoint is a
+	* strictly-additive delivery path). Disposed on shutdown.
+	*/
+	private mediaDataPlane;
+	/**
+	* The PUBLIC, signature-authenticated twin of the media plane. Null when the
+	* host has no `ctx.dataPlane` facility, or before the per-install secret has
+	* been minted — in which case `getSnapshotLinks` reports `url: null` and the
+	* client keeps using the authenticated plane exactly as before.
+	*/
+	private linkDataPlane;
+	/** Per-install HMAC secret for link signatures. Minted once and persisted: a
+	*  secret that rolled on every boot would invalidate every link a client is
+	*  currently holding, which is a fleet-wide blank grid after each restart. */
+	private linkSecret;
+	/**
+	* In-flight `serveLinkDataPlane` attempt, so the retry below cannot start a
+	* second one while the first is still awaiting the settings store.
+	*/
+	private linkPlaneAttempt;
+	/**
+	* How a full frame becomes a card-sized one. Defaults to the real ffmpeg
+	* resize; injectable so the wrapper's own logic is testable without spawning a
+	* process for every fixture. `JpegResizer` was declared for exactly this and
+	* had no injector — which is why the resize-failure path had never been
+	* exercised anywhere but production.
+	*/
+	private readonly resize;
+	constructor(resize?: JpegResizer);
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	/**
+	* Serve the per-device snapshot image endpoint on the addon data-plane
+	* (§3.1). Delivery: `GET /addon/snapshot/media/<deviceId>.jpg` → raw JPEG with
+	* `ETag` + `Cache-Control: private, max-age=<device maxAgeS>`, so a grid is N
+	* independent `<Image>` tiles served from the coalesced server cache (no
+	* base64 tax, no batch head-of-line blocking, browser/`expo-image` caching for
+	* free). Best-effort: a host without a `dataPlane` facility keeps the tRPC
+	* base64 path.
+	*/
+	private serveMediaDataPlane;
+	/**
+	* Serve the link plane if it is not already served — at init, and again on
+	* the first `getSnapshotLinks` after an attempt that could not finish.
+	*
+	* The retry is not defensive padding, it is the whole reason this wrapper
+	* exists. The plane needs a persisted signing secret, and the secret needs
+	* the settings store; this addon now boots in its OWN process, so "the store
+	* is not answering yet" is a state it can genuinely observe. A one-shot
+	* attempt turns that instant into a permanent condition: `linkDataPlane`
+	* stays null, every `getSnapshotLinks` row answers `url: null`, and every
+	* tile on every grid stays blank until someone restarts the runner. Nothing
+	* in the logs would say why, because nothing failed twice.
+	*
+	* Single-flighted: a burst of link requests joins one attempt.
+	*/
+	private ensureLinkDataPlane;
+	/**
+	* Serve the PUBLIC link plane: `GET /addon/snapshot/link/<deviceId>.jpg?w&v&exp&sig`.
+	*
+	* `access: 'public'` is deliberate and is the only interesting decision here.
+	* The authority is the HMAC, exactly as for the notification artifact plane
+	* and the Home Assistant media plane — but unlike those, what sits behind it
+	* is a LIVE view of the operator's home, so the compensating choices are
+	* explicit: a short TTL (`SNAPSHOT_LINK_TTL_MS`), the width inside the signed
+	* identity so a leaked tile cannot be escalated to the full frame, and
+	* **`force` is not honoured on this route at all** — a public URL must never
+	* be able to wake a battery camera.
+	*
+	* A leaked link therefore grants: one camera, at one thumbnail width, for at
+	* most the TTL. No token, no other device, no session.
+	*/
+	private serveLinkDataPlane;
+	/**
+	* Verify first, then hand the request to the ordinary media handler with a
+	* REWRITTEN url carrying only the signed `(deviceId, width)`.
+	*
+	* Rewriting rather than passing the original through is what stops an unsigned
+	* query parameter reaching the capture path: `force`, `streamId` and any other
+	* lever the authenticated plane honours are simply not present in what the
+	* handler parses.
+	*/
+	private handleLinkRequest;
+	private linkRoutePrefix;
+	/**
+	* Mint-once-and-persist the signing secret. Null when it cannot be
+	* ESTABLISHED — a secret held only in memory would break every outstanding
+	* link on restart, so no plane is better than a plane whose links die
+	* unpredictably.
+	*
+	* A null is never cached, so the next `getSnapshotLinks` tries again. That
+	* matters now the wrapper runs in its own process: the settings store can be
+	* a moment behind at boot, and this used to be a one-shot.
+	*
+	* The read-back is the gate. `state.get()` cannot distinguish "no secret
+	* yet" from "the store could not be read" — `readAddonStoreWithRetry` gives
+	* up and answers `{}` — so a store that is merely slow reads as empty and
+	* this would mint a SECOND secret over a perfectly good first one, silently
+	* invalidating every link a client is holding. Reading back what we just
+	* wrote is the only evidence available at this layer that the store is
+	* actually answering, and a mismatch means it is not.
+	*/
+	private ensureLinkSecret;
+	/**
+	* Mint signed links for the tiles a surface is rendering — and, in the same
+	* call, make those tiles CURRENT.
+	*
+	* This is the demand signal the design was missing. Under D93 enrolment rode
+	* on the image request, and D93/D94/D95 each fixed a different way for that
+	* request not to happen; none of them could fix the last one, because the
+	* client's own image cache answers a repeated URL with no network at all. An
+	* RPC has no such cache in front of it.
+	*
+	* So: note every target (creating a subscription, which `getSnapshotOverview`
+	* deliberately cannot), then join the ordinary non-forced capture path and
+	* wait a BOUNDED time for it. The Viewer never presents a frame older than
+	* 15 seconds as current, so this path tightens a looser per-device cache
+	* window to that contract without using `force` (and its battery-wake
+	* semantics). What comes back is the identity of the frame the link serves.
+	*
+	* The bound matters more than its exact value. A cold fleet is paced by
+	* `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
+	* the last of them would hold the whole batch well past any sensible paint
+	* budget. Devices that miss the bound return their real, older `capturedAt` —
+	* honest rather than blocking — and the client's next poll carries them
+	* forward.
+	*/
+	private getSnapshotLinks;
+	/**
+	* The debug readout's data — the decision chain for one device, cache-only
+	* and capture-free (a debug poll must never wake a battery camera).
+	*/
+	private getSnapshotDebugState;
+	/**
+	* Join the ordinary capture path for one device and wait, bounded, for it.
+	*
+	* Deliberately `getSnapshot` with `force: false`: the single flight, grab
+	* pool, and sleeping-battery refusal apply unchanged. The only override is
+	* the Viewer's 15-second currency contract and the link-mint wait bound.
+	*/
+	private awaitFreshEnough;
+	/**
+	* The one fresh frame an awake battery camera gets outside an active stream:
+	* captured at the WAKE edge, because the link poll deliberately never
+	* recaptures an idle-awake battery camera (every capture is a camera hit
+	* that would keep it out of sleep — the link-mint gate documents the
+	* incident).
+	*
+	* `force: true` is correct here — not a violation of "never wake for a
+	* snapshot": the camera is ALREADY awake (the status edge is what fired),
+	* and the battery 1 h cache default would otherwise answer the wake with
+	* the pre-sleep frame. The single flight coalesces a burst of edges; one
+	* delayed retry covers a camera whose status flipped a beat before its
+	* snapshot endpoint is actually answering (firmware boot lag).
+	*/
+	private captureOnWake;
+	/** Resolve the state advertised by a minted link before deciding whether a
+	*  background capture is allowed. */
+	private snapshotStateForLink;
+	/**
+	* Resolve a device (+ optional stream, + force) to renderable JPEG bytes for
+	* the HTTP endpoint. Runs the same coalesced capture ladder as the tRPC
+	* `getSnapshot` (so every consumer shares one upstream pull), then decodes the
+	* base64 cache into raw bytes and stamps the frame identity: `capturedAt` from
+	* the cache entry (matching the ETag `getSnapshotOverview` advertises) and the
+	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
+	*/
+	private resolveSnapshotMedia;
+	/**
+	* Cache-only freshness peek for the data-plane's conditional-GET fast path.
+	* Never captures, never resizes, never dials anything: a cached frame that is
+	* still inside its per-device max-age, or null.
+	*
+	* Returning null for a STALE entry is the important half. A 304 there would
+	* pin the tile to the old frame for as long as the client kept revalidating,
+	* which is the exact staleness this change exists to remove.
+	*/
+	private peekFreshFrame;
+	/**
+	* The frame at a card-sized width, derived once per
+	* (device, stream, width, state treatment) per capture.
+	*
+	* A failed resize falls back to the FULL frame — a visible card beats a
+	* broken one — but never silently: the card would otherwise keep costing a
+	* megabyte with nothing anywhere saying why, which is the shape of the bug
+	* this whole change came from.
+	*/
+	private thumbnailBytes;
+	protected onShutdown(): Promise<void>;
+	/**
+	* Drop the cached ingest owner whenever addon-level settings change —
+	* cheap, correct-by-construction refresh point (BaseAddon calls this
+	* after every `updateGlobalSettings`/`updateAddonSettings`). Combined
+	* with the TTL in `resolveIngestOwner`, a cluster topology change is
+	* picked up either on the next settings save or within
+	* `OWNER_CACHE_TTL_MS`, whichever comes first.
+	*/
+	protected onConfigChanged(): Promise<void>;
+	protected globalSettingsSchema(): ConfigUISchema;
+	private getSnapshot;
+	/**
+	* 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;
+	/**
+	* Reconcile backstop for a stale hit: is the frame we are about to serve the
+	* property of a device that no longer exists?
+	*
+	* Asked ONLY past `staleTtlMs`, which is already the "something is wrong"
+	* threshold — so the common path costs nothing. A `true` answer evicts and
+	* the caller returns null; anything else leaves the existing
+	* keep-the-UI-from-going-blank contract untouched.
+	*/
+	private staleHitBelongsToRemovedDevice;
+	/**
+	* 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.
+	*
+	* Stream selection strategy (picks the broker that won't stall):
+	*   1. Explicit `preferredStreamId` (user set in per-device settings)
+	*      — always honoured, even if currently idle. Operator choice
+	*      wins.
+	*   2. Auto: highest-quality broker currently in `streaming` state.
+	*      This is the whole point — prefer the stream that has active
+	*      subscribers (usually `low` for detection, but `mid`/`high`
+	*      if WebRTC is watching) so ffmpeg hits a warm pipe and
+	*      doesn't race the broker's resume.
+	*   3. Fallback: highest-quality enabled entry regardless of status
+	*      (will wake a suspended broker — retry-guarded against the
+	*      cold-start error).
+	*
+	* The stream-broker auto-suspends idle streams on the "no demand"
+	* signal; snapshots used to default to `high` which was often the
+	* first to go idle, racing every snapshot with a broker resume.
+	* Now we ask the orchestrator of streams which one is warm and grab
+	* from there.
+	*
+	* Source acquisition is pinned to the cluster's ingest owner (the node
+	* the stream-broker actually runs on) instead of the device-scoped
+	* `dev.cameraStreams` facade — `dev.cameraStreams` resolves against
+	* whichever node the cap-router picks by default, which double-pulls
+	* the camera (or dials a hub-local restream that isn't serving) when
+	* `ingestNode != hub`. `fetchSnapshotBrokerEntries` does the pinned
+	* fetch + owner-relative URL host rewrite; hub-owner + no reachable
+	* host is byte-identical to the previous unpinned call.
+	*/
+	private grabFrameFromBroker;
+	/**
+	* Cached, TTL-bounded resolution of the cluster's camera-source owner.
+	* See `ownerCache` doc for the invalidation story.
+	*/
+	private resolveIngestOwner;
+	/**
+	* Same graceful degrade as the recorder's `resolveIngestOwner`
+	* (`packages/addon-pipeline/src/recorder/addon/index.ts`) — the cap may
+	* not be mounted yet (pre-image-release) or the pipeline-orchestrator
+	* addon may be absent entirely; either way we fall back to `'hub'`,
+	* which is byte-identical to the previous hardcoded hub-only behaviour.
+	*/
+	private fetchIngestOwner;
+	/**
+	* Ffmpeg grab with one retry on the broker-cold-start error
+	* signature. Covers the window between "client connected" and
+	* "first keyframe" when a suspended broker resumes.
+	*/
+	private runGrabWithResumeRetry;
+	private invalidateCache;
+	/** Forget every cached artefact of one device: frames, derived variants and
+	*  any settled single-flight result that would answer the next request. */
+	private dropDeviceCaches;
+	/**
+	* The device is GONE — drop its cached frames and say so.
+	*
+	* Distinct from `invalidateCache` (a refresh, expected and silent): this is
+	* the terminal case, and a deleted camera that keeps answering with its last
+	* JPEG looks to an operator exactly like a camera that was never deleted.
+	*/
+	private evictRemovedDevice;
+	/**
+	* Does device-manager still know this id?
+	*
+	* `null` means the question could not be answered — a transport hiccup is
+	* not a deletion (D49), and the caller keeps serving what it has. Only an
+	* explicit "no such device" evicts.
+	*/
+	private deviceStillExists;
+	/**
+	* Resolve the state that must be visible on a snapshot.
+	*
+	* Uses the same two canonical sources as wake-on-play:
+	*  1. `deviceManager.getDevice` for the registry's BatteryOperated feature;
+	*  2. `deviceState.getCapSlice('battery')` for the durable runtime mirror.
+	*
+	* A valid battery slice is itself positive evidence that the device is
+	* battery-operated. That closes the field failure where "Baby monitor" had a
+	* sleeping battery slice but a stale persisted feature projection, so the
+	* snapshot wrapper classified it as mains and a Viewer thumbnail logged in
+	* to the sleeping camera. The reverse is deliberately not guessed: no
+	* feature + no valid slice remains a mains/unknown camera and follows the
+	* ordinary capture path.
+	*
+	* Once battery-operated is established, a missing slice fails safe toward
+	* `sleeping` through the shared `deriveBatteryPresence` function. This avoids
+	* a background wake without inventing an `unreachable` fault.
+	*/
+	private resolveSnapshotState;
+	private isDeviceWaking;
+	/**
+	* True when at least one of the device's brokers is actively
+	* streaming (status === 'streaming'). Used by the battery-cam guard
+	* around `grabFrameFromBroker` to allow the fallback ONLY when
+	* grabbing a frame is free (a consumer is already keeping the
+	* stream warm). When everything is suspended, the fallback would
+	* dial the camera and wake it — defeats the sleeping cache.
+	*
+	* Pinned to the ingest owner via `fetchSnapshotBrokerEntries` — same
+	* rationale as `grabFrameFromBroker`: the device-scoped
+	* `dev.cameraStreams` facade resolves against whichever node the
+	* cap-router picks by default, which is wrong once `ingestNode !=
+	* hub` (queries the hub for slots that only exist on the agent,
+	* always reporting no streaming broker). Owner === hub (no reachable
+	* 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
+	* captured, how stale the cached image is, its size, and which stream
+	* was used. Returns null when the device has never been captured
+	* (cache miss) since the addon started.
+	*/
+	private getStatus;
+	private readDeviceSettings;
+	private buildDeviceSettingsContribution;
+	/**
+	* The frame a camera that CANNOT capture answers with.
+	*
+	* Returns null only if rendering itself fails — the caller then falls through
+	* to its previous behaviour, so a broken courtesy path degrades to the old
+	* 404 rather than masking a real capture failure as a placeholder.
+	*
+	* Rendered at the full tile size; the existing resize ladder derives the
+	* card-sized variants from it exactly as it does for a real frame, so no
+	* downstream consumer needs to know this frame is synthetic.
+	*/
+	private courtesyFrame;
+	/** A courtesy frame shaped as the cap's response, or null when unrenderable. */
+	private courtesyImage;
+	/**
+	* The answer for a camera the hub cannot reach: its last good frame, with
+	* `Offline` painted over it, and `offline` stamped on the response identity.
+	*
+	* Called only AFTER the ladder has run (offline is not in
+	* {@link CAPTURE_BLOCKING_REASONS}), so this dresses a frame that could not be
+	* refreshed — never one that just landed.
+	*
+	* The `stateReason` is set FIRST and unconditionally, because it is what a
+	* surface labels the tile from and what puts `offline` in the ETag: a client
+	* holding the live frame has to see a new identity the moment the camera
+	* drops, or it paints the unlabelled photograph until the camera comes back.
+	* A failed render therefore degrades to the raw frame rather than to nothing —
+	* the metadata still says offline, so the tile is still honest.
+	*/
+	private offlineImage;
+	/**
+	* Render a state-labelled answer. A cached real frame is the background, not
+	* the answer by itself; if it cannot be decoded, fall back to the generated
+	* courtesy background rather than leaking an unlabelled stale frame.
+	*/
+	/** The persisted frame as a cache entry, with its real age. */
+	private durableEntry;
+	private stateImage;
+	/**
+	* 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 fetchDeviceMeta;
+	/** Settings-UI helper — battery flag drives the default max-age in the field description. */
+	private isDeviceBattery;
+	/**
+	* Feeds the settings-UI stream picker. Pinned to the ingest owner via
+	* `fetchSnapshotBrokerEntries` — the device-scoped `dev.cameraStreams`
+	* facade this used to call resolves against whichever node the
+	* cap-router picks by default, which is empty once `ingestNode !=
+	* hub` (the picker would render nothing but "Auto"). Owner === hub
+	* (no reachable host) is byte-identical to the previous unpinned call.
+	*/
+	private getStreamOptions;
+	private saveDeviceSettingsPatch;
 }
 /** Result of {@link fetchSnapshotBrokerEntries} — this device's RTSP entries + profile slots. */
 interface SnapshotBrokerEntries {
-    readonly entries: readonly RtspRestreamEntry[];
-    readonly slots: readonly ProfileSlot[];
+	readonly entries: readonly RtspRestreamEntry[];
+	readonly slots: readonly ProfileSlot[];
 }
 /**
- * Pinned, testable fetch of this device's RTSP restream entries + profile
- * slots from the system `streamBroker` cap. Module-level (not a class
- * method) so `grabFrameFromBroker`'s owner-pin + host-rewrite contract is
- * directly unit-testable without instantiating the addon — mirrors
- * `acquireSessionDecodeRestreamFrom` in `pipeline-runner/index.ts`.
- *
- * Replaces the former `dev.cameraStreams.getRtspEntries({})` /
- * `getBrokerStreams({})` device-scoped facade calls, which resolve against
- * whichever node the cap-router picks by default — wrong once
- * `ingestNode != hub` (double-pulls the camera, or dials a hub-local
- * restream nobody is serving). `getAllRtspEntries`/`listAllProfileSlots`
- * are cluster-wide system-cap methods; pinning the call with `nodePin` +
- * filtering by the `${deviceId}/` brokerId prefix reproduces the exact
- * device-scoped result set the facade used to return.
- *
- * `reachableHost`, when present, rides as the cap's own `hostname` input —
- * the broker rewrites the returned URLs' host itself (same mechanism
- * `getStreamWithCodec` callers use for cross-node pulls), so no separate
- * client-side host-substitution is needed here. Omitting `hostname`
- * (owner === hub, no reachable host registered) leaves the broker's
- * default `127.0.0.1` URLs untouched — byte-identical to today.
- */
+* Pinned, testable fetch of this device's RTSP restream entries + profile
+* slots from the system `streamBroker` cap. Module-level (not a class
+* method) so `grabFrameFromBroker`'s owner-pin + host-rewrite contract is
+* directly unit-testable without instantiating the addon — mirrors
+* `acquireSessionDecodeRestreamFrom` in `pipeline-runner/index.ts`.
+*
+* Replaces the former `dev.cameraStreams.getRtspEntries({})` /
+* `getBrokerStreams({})` device-scoped facade calls, which resolve against
+* whichever node the cap-router picks by default — wrong once
+* `ingestNode != hub` (double-pulls the camera, or dials a hub-local
+* restream nobody is serving). `getAllRtspEntries`/`listAllProfileSlots`
+* are cluster-wide system-cap methods; pinning the call with `nodePin` +
+* filtering by the `${deviceId}/` brokerId prefix reproduces the exact
+* device-scoped result set the facade used to return.
+*
+* `reachableHost`, when present, rides as the cap's own `hostname` input —
+* the broker rewrites the returned URLs' host itself (same mechanism
+* `getStreamWithCodec` callers use for cross-node pulls), so no separate
+* client-side host-substitution is needed here. Omitting `hostname`
+* (owner === hub, no reachable host registered) leaves the broker's
+* default `127.0.0.1` URLs untouched — byte-identical to today.
+*/
 export declare function fetchSnapshotBrokerEntries(api: AddonApi, params: {
-    readonly deviceId: number;
-    readonly ownerNodeId: string;
-    readonly reachableHost?: string;
+	readonly deviceId: number;
+	readonly ownerNodeId: string;
+	readonly reachableHost?: string;
 }): Promise<SnapshotBrokerEntries>;
 export {};