@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-8LQ4lDEB.js");
+const require_dist = require("../../dist-XTkzsnz-.js");
 const require_snapshot_courtesy = require("../../snapshot-courtesy-D_C5-nC0.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { Bn as streamQualityLabel, Br as nodePin, Pn as snapshotCapability, Q as batteryCapability, Z as bareAddonId, a as BatteryStatusSchema, cr as DeviceType, in as memoizePinnedFfmpeg, lr as errMsg, ni as EventCategory, or as DeviceFeature, ur as BaseAddon, vt as deriveBatteryPresence } from "../../dist-Biqn3TEn.mjs";
+import { Bn as streamQualityLabel, Br as nodePin, Pn as snapshotCapability, Q as batteryCapability, Z as bareAddonId, a as BatteryStatusSchema, cr as DeviceType, in as memoizePinnedFfmpeg, lr as errMsg, ni as EventCategory, or as DeviceFeature, ur as BaseAddon, vt as deriveBatteryPresence } from "../../dist-byg8IP4Q.mjs";
 import { i as renderCourtesyOverlayJpeg, n as courtesyCacheKey, r as renderCourtesyJpeg } from "../../snapshot-courtesy-CyFs1M3I.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";

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

@@ -1,108 +1,108 @@
 /**
- * The per-device snapshot cache, keyed by (device, STREAM).
- *
- * It used to be keyed by device alone, and `getSnapshot` served the hit before
- * it had resolved which stream the caller asked for — so `?streamId=low`
- * silently returned whatever was already cached. In production that meant the
- * 4K main frame: probing a live camera with `low`, `sub` and `high` returned
- * three byte-identical 1.2 MB responses. The parameter existed, was documented,
- * and did nothing.
- *
- * Two views still need to ask a device-wide question — "when did this camera
- * last produce a frame" (`getSnapshotOverview`, `getStatus`) — so
- * {@link SnapshotCache.latest} answers it across streams rather than making
- * every caller guess a key.
- */
+* The per-device snapshot cache, keyed by (device, STREAM).
+*
+* It used to be keyed by device alone, and `getSnapshot` served the hit before
+* it had resolved which stream the caller asked for — so `?streamId=low`
+* silently returned whatever was already cached. In production that meant the
+* 4K main frame: probing a live camera with `low`, `sub` and `high` returned
+* three byte-identical 1.2 MB responses. The parameter existed, was documented,
+* and did nothing.
+*
+* Two views still need to ask a device-wide question — "when did this camera
+* last produce a frame" (`getSnapshotOverview`, `getStatus`) — so
+* {@link SnapshotCache.latest} answers it across streams rather than making
+* every caller guess a key.
+*/
 /** The cached frame. Structurally the addon's `SnapshotImage` — declared here
- *  rather than imported so the cache does not depend on the 1,100-line addon. */
+*  rather than imported so the cache does not depend on the 1,100-line addon. */
 export interface SnapshotCacheImage {
-    readonly base64: string;
-    readonly contentType: string;
+	readonly base64: string;
+	readonly contentType: string;
 }
 export interface SnapshotCacheEntry {
-    readonly data: SnapshotCacheImage;
-    readonly ts: number;
-    /** Stream id resolved at capture time — 'high' | 'mid' | 'low' | custom | null. */
-    readonly streamId: string | null;
+	readonly data: SnapshotCacheImage;
+	readonly ts: number;
+	/** Stream id resolved at capture time — 'high' | 'mid' | 'low' | custom | null. */
+	readonly streamId: string | null;
 }
 /**
- * Byte budget across every cached frame.
- *
- * The cache shipped with NO bound of any kind: no TTL, no LRU, no size cap. It
- * holds base64 JPEG payloads — a 4K main-stream frame is ~1.6 MB as base64 —
- * keyed by (device, stream), so the ceiling was "every camera × every stream it
- * was ever asked for", which is not a ceiling.
- *
- * 64 MiB is roughly 40 main-stream frames, comfortably above the live 27-camera
- * roster's working set (the whole `snapshot` runner measures 185 MB RSS, of
- * which the node baseline is ~130 MB), so nothing an operator does today starts
- * evicting. It exists so a roster that grows, or a device that gets probed on
- * many stream ids, cannot walk this structure into the OOM.
- */
+* Byte budget across every cached frame.
+*
+* The cache shipped with NO bound of any kind: no TTL, no LRU, no size cap. It
+* holds base64 JPEG payloads — a 4K main-stream frame is ~1.6 MB as base64 —
+* keyed by (device, stream), so the ceiling was "every camera × every stream it
+* was ever asked for", which is not a ceiling.
+*
+* 64 MiB is roughly 40 main-stream frames, comfortably above the live 27-camera
+* roster's working set (the whole `snapshot` runner measures 185 MB RSS, of
+* which the node baseline is ~130 MB), so nothing an operator does today starts
+* evicting. It exists so a roster that grows, or a device that gets probed on
+* many stream ids, cannot walk this structure into the OOM.
+*/
 export declare const SNAPSHOT_CACHE_MAX_BYTES: number;
 /**
- * Drop an entry nobody has READ for this long.
- *
- * Deliberately an IDLE timeout and not a capture-age one. Capture age is
- * already governed per device by `snapshotMaxAgeS` (default 15s, but one HOUR
- * for battery cameras), so a TTL on age would either fight those rules or have
- * to sit above the largest of them and bound nothing. "Nobody has looked at
- * this in an hour" is orthogonal to freshness and is the actual condition under
- * which the bytes are dead weight — a removed camera, an unreachable one, a
- * stream id probed once by a debug view.
- */
-export declare const SNAPSHOT_CACHE_IDLE_TTL_MS = 3600000;
+* Drop an entry nobody has READ for this long.
+*
+* Deliberately an IDLE timeout and not a capture-age one. Capture age is
+* already governed per device by `snapshotMaxAgeS` (default 15s, but one HOUR
+* for battery cameras), so a TTL on age would either fight those rules or have
+* to sit above the largest of them and bound nothing. "Nobody has looked at
+* this in an hour" is orthogonal to freshness and is the actual condition under
+* which the bytes are dead weight — a removed camera, an unreachable one, a
+* stream id probed once by a debug view.
+*/
+export declare const SNAPSHOT_CACHE_IDLE_TTL_MS = 36e5;
 /** Why an entry was dropped. `budget` = the byte ceiling; `idle` = unread for
- *  {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
-export type SnapshotCacheEvictReason = 'budget' | 'idle';
+*  {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
+export type SnapshotCacheEvictReason = "budget" | "idle";
 /** Notified for every eviction so the owner can put it on the record with the
- *  device tag. A cached frame that vanishes is the explanation for a later
- *  capture that did not have to happen; silence reads as "never happened". */
+*  device tag. A cached frame that vanishes is the explanation for a later
+*  capture that did not have to happen; silence reads as "never happened". */
 export type SnapshotCacheEvictListener = (deviceId: number, streamId: string | null, reason: SnapshotCacheEvictReason) => void;
 export interface SnapshotCacheOptions {
-    /** Total base64 bytes held across all entries. Default {@link SNAPSHOT_CACHE_MAX_BYTES}. */
-    readonly maxBytes?: number;
-    /** Idle timeout. Default {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
-    readonly idleTtlMs?: number;
-    /** Injected clock — the bounds must be testable without waiting an hour. */
-    readonly now?: () => number;
-    readonly onEvict?: SnapshotCacheEvictListener;
+	/** Total base64 bytes held across all entries. Default {@link SNAPSHOT_CACHE_MAX_BYTES}. */
+	readonly maxBytes?: number;
+	/** Idle timeout. Default {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
+	readonly idleTtlMs?: number;
+	/** Injected clock — the bounds must be testable without waiting an hour. */
+	readonly now?: () => number;
+	readonly onEvict?: SnapshotCacheEvictListener;
 }
 export declare class SnapshotCache {
-    private readonly byKey;
-    /** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
-    private readonly keysByDevice;
-    private readonly maxBytes;
-    private readonly idleTtlMs;
-    private readonly now;
-    private readonly onEvict;
-    private totalBytes;
-    constructor(options?: SnapshotCacheOptions);
-    get(deviceId: number, streamId: string | undefined): SnapshotCacheEntry | undefined;
-    set(deviceId: number, streamId: string | undefined, entry: SnapshotCacheEntry): void;
-    /** The newest entry for a device, whichever stream produced it. */
-    latest(deviceId: number): SnapshotCacheEntry | undefined;
-    /** Base64 bytes currently retained. The number the budget is enforced on. */
-    sizeBytes(): number;
-    /** Entries currently retained. */
-    entryCount(): number;
-    /** Read through the idle timeout: an entry nobody has touched inside
-     *  `idleTtlMs` is dropped here rather than on a sweep, so the cost is paid by
-     *  the caller that proves it was not wanted. */
-    private read;
-    /** Evict least-recently-ACCESSED first until the budget holds. `protectedKey`
-     *  is the entry just written — evicting it would make `set` a no-op. */
-    private enforceBudget;
-    private evict;
-    /** Remove a key and everything that indexes or accounts for it. */
-    private forget;
-    /**
-     * Drop every stream of one device.
-     *
-     * Device-wide on purpose: a settings change or an operator refresh
-     * invalidates the CAMERA, and leaving a sibling entry behind would keep
-     * serving the pre-change frame from the other key.
-     */
-    deleteDevice(deviceId: number): void;
-    clear(): void;
+	private readonly byKey;
+	/** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
+	private readonly keysByDevice;
+	private readonly maxBytes;
+	private readonly idleTtlMs;
+	private readonly now;
+	private readonly onEvict;
+	private totalBytes;
+	constructor(options?: SnapshotCacheOptions);
+	get(deviceId: number, streamId: string | undefined): SnapshotCacheEntry | undefined;
+	set(deviceId: number, streamId: string | undefined, entry: SnapshotCacheEntry): void;
+	/** The newest entry for a device, whichever stream produced it. */
+	latest(deviceId: number): SnapshotCacheEntry | undefined;
+	/** Base64 bytes currently retained. The number the budget is enforced on. */
+	sizeBytes(): number;
+	/** Entries currently retained. */
+	entryCount(): number;
+	/** Read through the idle timeout: an entry nobody has touched inside
+	*  `idleTtlMs` is dropped here rather than on a sweep, so the cost is paid by
+	*  the caller that proves it was not wanted. */
+	private read;
+	/** Evict least-recently-ACCESSED first until the budget holds. `protectedKey`
+	*  is the entry just written — evicting it would make `set` a no-op. */
+	private enforceBudget;
+	private evict;
+	/** Remove a key and everything that indexes or accounts for it. */
+	private forget;
+	/**
+	* Drop every stream of one device.
+	*
+	* Device-wide on purpose: a settings change or an operator refresh
+	* invalidates the CAMERA, and leaving a sibling entry behind would keep
+	* serving the pre-change frame from the other key.
+	*/
+	deleteDevice(deviceId: number): void;
+	clear(): void;
 }

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

@@ -1,135 +1,135 @@
 /**
- * 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).
- */
+* 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;
+* 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 = 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.
- */
+* 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;
+* 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 = 1e4;
 /**
- * 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.
- *
- * Raised 3 → 6 on 2026-08-12 (operator): a 17-camera cold start serialised
- * into 6 waves and the client-side "image displayed" clustering matched the
- * pool exactly (p90 10.8 s). Measured client-side after the raise — if the
- * hub shows decode pressure, this is the first knob to lower.
- */
+* 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.
+*
+* Raised 3 → 6 on 2026-08-12 (operator): a 17-camera cold start serialised
+* into 6 waves and the client-side "image displayed" clustering matched the
+* pool exactly (p90 10.8 s). Measured client-side after the raise — if the
+* hub shows decode pressure, this is the first knob to lower.
+*/
 export declare const MAX_CONCURRENT_GRABS = 6;
 /**
- * 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.
- */
+* 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.
- */
+* 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: "serve-cache";
 } | {
-    readonly kind: 'await-refresh';
-    readonly waitMs: number;
-    readonly staleFallback: boolean;
+	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;
+	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
- */
+* 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.
- */
+* 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;
+	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;
+	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: true;
+	readonly value: T;
 } | {
-    readonly settled: false;
+	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.
- */
+* 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-courtesy.d.ts

@@ -1,68 +1,68 @@
 /**
- * Why a camera cannot produce a frame right now.
- *
- * `sleeping` and `unreachable` are deliberately two reasons and not one. A
- * battery camera in low-power mode is WORKING — that tile must not read as a
- * fault, which is D62's rule in the third state — while a battery camera
- * nothing has been heard from for hours is a genuine fault the operator has to
- * see (a flat battery, or a camera off the LAN). Painting the second as the
- * first is how a dead camera stayed green for 30 hours. The two are separated
- * by `deriveBatteryPresence`, never by a caller's own guess.
- */
-export type CourtesyReason = 'disabled' | 'offline' | 'sleeping' | 'unreachable' | 'waking';
+* Why a camera cannot produce a frame right now.
+*
+* `sleeping` and `unreachable` are deliberately two reasons and not one. A
+* battery camera in low-power mode is WORKING — that tile must not read as a
+* fault, which is D62's rule in the third state — while a battery camera
+* nothing has been heard from for hours is a genuine fault the operator has to
+* see (a flat battery, or a camera off the LAN). Painting the second as the
+* first is how a dead camera stayed green for 30 hours. The two are separated
+* by `deriveBatteryPresence`, never by a caller's own guess.
+*/
+export type CourtesyReason = "disabled" | "offline" | "sleeping" | "unreachable" | "waking";
 /** Default tile size when the caller asks for no particular width. */
 export declare const COURTESY_DEFAULT_WIDTH = 640;
 /** The word the frame carries. Deliberately the operator's vocabulary. */
 export declare function courtesyLabel(reason: CourtesyReason): string;
 /**
- * Background per reason. A disabled camera is a DELIBERATE state and must not
- * read as an alarm, so it is neutral grey; offline is a fault and is warmer.
- */
+* Background per reason. A disabled camera is a DELIBERATE state and must not
+* read as an alarm, so it is neutral grey; offline is a fault and is warmer.
+*/
 export declare function courtesyBackground(reason: CourtesyReason): string;
 /** XML escaping for text placed inside an SVG `<text>` node. */
 export declare function escapeCourtesyText(value: string): string;
 export interface CourtesyFrameSpec {
-    readonly deviceName: string;
-    readonly reason: CourtesyReason;
-    readonly width: number;
-    readonly height: number;
+	readonly deviceName: string;
+	readonly reason: CourtesyReason;
+	readonly width: number;
+	readonly height: number;
 }
 /**
- * The SVG the frame is rasterized from: the state large and centred, the
- * camera's name under it, smaller and dimmer.
- *
- * Sizes derive from the width so a 240 px grid tile and a 1920 px full-bleed
- * frame read the same, with a floor so a thumbnail stays legible.
- */
+* The SVG the frame is rasterized from: the state large and centred, the
+* camera's name under it, smaller and dimmer.
+*
+* Sizes derive from the width so a 240 px grid tile and a 1920 px full-bleed
+* frame read the same, with a floor so a thumbnail stays legible.
+*/
 export declare function buildCourtesySvg(spec: CourtesyFrameSpec): string;
 /**
- * The state treatment for a frame that HAS a picture under it: a band along the
- * bottom, and nothing else touched.
- *
- * It was a full-frame wash at 0.62 opacity, under a docblock claiming the frame
- * "remains visible underneath". A 38 % view of a dark room is not a view of it,
- * and the operator read the result as a placeholder rather than as their own
- * camera: *"ma perché Waking? Dovremmo mostrare l'ultimo snapshot
- * disponibile"* [but why Waking? We should show the last available snapshot] (Baby monitor, 2026-09-16).
- *
- * The marker still has to earn its place — a stale frame shown clean gets
- * mistaken for live, which is the reason the treatment exists at all. A band
- * says the same thing a wash said. Covering the picture was never the message.
- */
+* The state treatment for a frame that HAS a picture under it: a band along the
+* bottom, and nothing else touched.
+*
+* It was a full-frame wash at 0.62 opacity, under a docblock claiming the frame
+* "remains visible underneath". A 38 % view of a dark room is not a view of it,
+* and the operator read the result as a placeholder rather than as their own
+* camera: *"ma perché Waking? Dovremmo mostrare l'ultimo snapshot
+* disponibile"* [but why Waking? We should show the last available snapshot] (Baby monitor, 2026-09-16).
+*
+* The marker still has to earn its place — a stale frame shown clean gets
+* mistaken for live, which is the reason the treatment exists at all. A band
+* says the same thing a wash said. Covering the picture was never the message.
+*/
 export declare function buildCourtesyOverlaySvg(spec: CourtesyFrameSpec): string;
 /** Cache key — a courtesy frame is a pure function of these four. */
 export declare function courtesyCacheKey(spec: CourtesyFrameSpec): string;
 /**
- * Render the frame.
- *
- * Rejects on failure — the caller decides what to do, exactly as `resizeJpeg`
- * does, so a broken courtesy path is never mistaken for a broken camera.
- */
+* Render the frame.
+*
+* Rejects on failure — the caller decides what to do, exactly as `resizeJpeg`
+* does, so a broken courtesy path is never mistaken for a broken camera.
+*/
 export declare function renderCourtesyJpeg(spec: CourtesyFrameSpec): Promise<Buffer>;
 /**
- * Paint the state treatment over a real cached frame.
- *
- * The source dimensions are authoritative: overlays preserve the original
- * frame rather than resizing it to the generated courtesy-frame default.
- */
-export declare function renderCourtesyOverlayJpeg(background: Buffer, spec: Pick<CourtesyFrameSpec, 'deviceName' | 'reason'>): Promise<Buffer>;
+* Paint the state treatment over a real cached frame.
+*
+* The source dimensions are authoritative: overlays preserve the original
+* frame rather than resizing it to the generated courtesy-frame default.
+*/
+export declare function renderCourtesyOverlayJpeg(background: Buffer, spec: Pick<CourtesyFrameSpec, "deviceName" | "reason">): Promise<Buffer>;