@camstack/system 1.2.253 → 1.2.255

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-B9y-3rme.js");
+const require_dist = require("../../dist-BJj6Akye.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { A as addonPagesCapability, Cn as EventCategory, Xt as errMsg, Zt as BaseAddon } from "../../dist-DH6ThyTd.mjs";
+import { Nn as EventCategory, P as addonPagesCapability, in as errMsg, on as BaseAddon } from "../../dist-Ch93tyHB.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-B9y-3rme.js");
+const require_dist = require("../../dist-BJj6Akye.js");
 const require_settle_sources = require("../../settle-sources-Bhsy57y-.js");
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");

package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs

@@ -1,4 +1,4 @@
-import { Cn as EventCategory, M as addonWidgetsCapability, Xt as errMsg, Zt as BaseAddon } from "../../dist-DH6ThyTd.mjs";
+import { I as addonWidgetsCapability, Nn as EventCategory, in as errMsg, on as BaseAddon } from "../../dist-Ch93tyHB.mjs";
 import { t as settleSourcesWithTimeout } from "../../settle-sources-CDtNC8ub.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import * as path$1 from "node:path";

package/dist/builtins/alerts/alerts.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-B9y-3rme.js");
+const require_dist = require("../../dist-BJj6Akye.js");
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/alerts/alerts.addon.mjs

@@ -1,4 +1,4 @@
-import { Cn as EventCategory, N as alertsCapability, Xt as errMsg, Zt as BaseAddon, n as AlertSchema, un as createEvent } from "../../dist-DH6ThyTd.mjs";
+import { L as alertsCapability, Nn as EventCategory, in as errMsg, on as BaseAddon, r as AlertSchema, yn as createEvent } from "../../dist-Ch93tyHB.mjs";
 //#region src/builtins/alerts/prune-policy.ts
 /**
 * Ids older than `cutoffMs`, oldest first.

package/dist/builtins/autotrack/autotrack-cameras.d.ts

@@ -0,0 +1,76 @@
+import { FirstLevelMacroClass, PtzAutotrackSettings, PtzAutotrackStatus } from '@camstack/types';
+import { AutotrackLoopConfig } from './autotrack-config.js';
+/** One camera's record. */
+export interface AutotrackCameraRecord {
+    readonly enabled: boolean;
+    readonly settings: PtzAutotrackSettings;
+}
+/** deviceId → record. */
+export type AutotrackCameraRecords = Readonly<Record<number, AutotrackCameraRecord>>;
+/**
+ * The defaults a camera starts from.
+ *
+ * `disappearDelaySeconds` matches the loop's own default so the two cannot
+ * disagree on the day nobody has opened the form. `stopDelaySeconds` is
+ * persisted and NOT honoured — see {@link loopConfigFor}.
+ */
+export declare const DEFAULT_CAMERA_RECORD: AutotrackCameraRecord;
+/**
+ * What this implementation can follow, as the cap's target options.
+ *
+ * A vendor list would be a lie here: the emulated loop follows what the
+ * DETECTOR emits, and the detector's first-level macro classes are these
+ * three. Reolink's `people` and Hikvision's `human` are vendor words for the
+ * same thing and are normalised in {@link targetClassFor} rather than offered.
+ */
+export declare const EMULATED_TARGET_OPTIONS: PtzAutotrackStatus['supportedTargetTypes'];
+/**
+ * Read the persisted blob.
+ *
+ * A malformed ENTRY falls back to the defaults and keeps its `enabled` flag —
+ * it is never dropped. Dropping it would disarm a function the operator armed,
+ * which is the one direction this must not fail in; a camera that is not in
+ * the blob at all is simply a camera nobody has switched on.
+ */
+export declare function parseCameraRecords(raw: unknown): AutotrackCameraRecords;
+/** Immutable per-camera patch — a NEW map, the previous one untouched. */
+export declare function withCameraPatch(records: AutotrackCameraRecords, deviceId: number, patch: {
+    enabled?: boolean;
+    settings?: Partial<PtzAutotrackSettings>;
+}): AutotrackCameraRecords;
+/**
+ * The detection macro class this camera follows.
+ *
+ * `''` is the cap's "camera default" and means PERSON here — the class an
+ * autotrack is asked for in almost every case, and the one the measurement
+ * slice used. A vendor string (`people`, `human`) normalises to the macro it
+ * names; anything else falls back to person rather than following nothing,
+ * because a loop that silently follows nothing is indistinguishable from one
+ * that is broken.
+ */
+export declare function targetClassFor(settings: PtzAutotrackSettings): FirstLevelMacroClass;
+/**
+ * The loop's config for this camera.
+ *
+ * Only ONE of the cap's three settings reaches the loop:
+ *
+ * - `disappearDelaySeconds` → {@link AutotrackLoopConfig.disappearDelayMs}. Same
+ *   meaning on both sides: how long a target that stopped appearing is held
+ *   before it is released and the head goes home.
+ * - `targetType` → the detection class, through {@link targetClassFor}.
+ * - `stopDelaySeconds` is persisted and NOT honoured. It means "keep tracking a
+ *   STATIONARY target for this long before stopping", and a pulse-based loop
+ *   already does nothing while the subject is inside the dead zone — there is
+ *   no motion to stop. Storing it and ignoring it is deliberate: the cap is
+ *   cross-vendor, a native provider honours it, and dropping it from the
+ *   payload would make a camera that switches from native to emulated lose a
+ *   setting it had. It is reported back by `getStatus` verbatim, never as a
+ *   number this loop acted on.
+ *
+ * Everything else in the loop config is a TUNING CONSTANT that D520 kept out of
+ * the operator surface on purpose (dead zone, settle zone, command ceiling,
+ * pulse dead time). They stay constants.
+ */
+export declare function loopConfigFor(settings: PtzAutotrackSettings): AutotrackLoopConfig;
+/** The cap's status for one camera. */
+export declare function statusFor(record: AutotrackCameraRecord, lastChangedAt: number): PtzAutotrackStatus;

package/dist/builtins/autotrack/autotrack-config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Tuning constants for the emulated PTZ autotrack.
+ *
+ * Everything here is a number the OPERATOR does not set: the dead zone, the
+ * settle zone, the command ceiling, the pulse dead time, the refresh cadences.
+ * D520 kept them out of the settings surface on purpose — they are the
+ * behaviour of the control loop, not a preference, and a camera whose dead zone
+ * somebody widened by hand is a camera nobody can reason about.
+ *
+ * What IS per camera lives with the record (`autotrack-cameras.ts`): the switch,
+ * the target class and the disappear delay, all read through the cap's own
+ * settings so there is one place an operator changes them.
+ */
+/**
+ * ## The constants that used to live here
+ *
+ * `AUTOTRACK_ARMED` and `AUTOTRACK_TARGET_DEVICE_ID` were the whole protection
+ * of the measurement slice: arming was a deploy-shaped act because there was no
+ * switch to do it with. There is one now — the emulation registers
+ * `ptz-autotrack` as a wrapper the operator BINDS per camera and switches on
+ * through the cap's own `setEnabled` (D62: one function, one switch). The
+ * protection is no longer a constant; it is that a camera must be both bound
+ * and switched on, and that the loop still refuses to move without
+ * `moveImpulseMs` or while the camera's native autotrack is armed (D520).
+ *
+ * `AUTOTRACK_TARGET_CLASS` went the same way: the class is per camera now,
+ * from the cap's `targetType` setting (`autotrack-cameras.ts`).
+ */
+/** Signed single-axis step handed to `ptz.move` — a DIRECTION, not a delta.
+ *  Every provider reads the sign and ignores the magnitude (reolink:
+ *  `pan > 0 ? 'Right' : 'Left'`), so only -1 / 0 / +1 are meaningful. */
+export type PtzAxisStep = -1 | 0 | 1;
+/** Tuning of the control loop. Every field is a time or a fraction; nothing
+ *  here is derived from `detectionFps` — see {@link maxCommandsPerSecond}. */
+export interface AutotrackLoopConfig {
+    /**
+     * Width/height of the central "do nothing" box, as a fraction of the frame.
+     * `0.5` = the central 50%: a correction starts only once the subject's
+     * centre leaves it (|error| > 0.25 on that axis).
+     */
+    readonly deadZoneFraction: number;
+    /**
+     * Width/height of the TIGHTER box that ENDS a correction, as a fraction of
+     * the frame. Must be smaller than {@link deadZoneFraction}.
+     *
+     * This is the anti-overshoot rule: the loop stops correcting BEFORE the
+     * subject reaches the centre. Aiming at the centre with an estimated gain
+     * overshoots, and an overshoot on the next frame reverses the sign — that is
+     * the oscillation this box exists to prevent.
+     */
+    readonly settleZoneFraction: number;
+    /**
+     * Hard ceiling on commands issued to the camera, in commands per second,
+     * owned by the LOOP.
+     *
+     * Explicitly NOT derived from the analysis rate. `frame-tracked` arrives at
+     * 1–10 Hz; at 10 Hz a per-frame command would be ~10 commands/s, an order of
+     * magnitude above what the hardware takes. The ceiling is measured, in-repo:
+     * a Reolink E1 Outdoor PoE rejects a command issued while the previous one
+     * is still travelling with `response_code 400` — presses 1.2 s apart were
+     * REJECTED, 3 s apart were ACCEPTED (`reolink-camera.ts`, `runZoom`). `1/3`
+     * is that 3 s, and it is the gate that binds in practice.
+     */
+    readonly maxCommandsPerSecond: number;
+    /**
+     * Extra silence after a pulse is expected to have FINISHED, ms.
+     *
+     * The dead time after a command is `moveImpulseMs + pulseSettleMs`: the head
+     * is still travelling for the first part and the detector has not yet seen
+     * the new framing for the second. Commanding inside it measures an error
+     * that the in-flight pulse has already corrected.
+     */
+    readonly pulseSettleMs: number;
+    /**
+     * How long the chosen target may be absent before it is released and the
+     * head is sent home, ms. Also the silence watchdog's budget: if
+     * `frame-tracked` stops arriving entirely, the same delay elapses and the
+     * same release happens — off the event path, by timer.
+     */
+    readonly disappearDelayMs: number;
+    /** Normalized speed (0..1) handed to `ptz.move`. */
+    readonly speed: number;
+    /** How often the off-event-path mirror re-reads `ptz.getOptions` and the
+     *  native-autotrack state, ms. Never on the event path (D49). */
+    readonly mirrorRefreshMs: number;
+    /** How often the measurement aggregates are summarized to the log, ms. */
+    readonly measurementSummaryMs: number;
+}
+export declare const DEFAULT_AUTOTRACK_LOOP_CONFIG: AutotrackLoopConfig;

package/dist/builtins/autotrack/autotrack-decision.d.ts

@@ -0,0 +1,99 @@
+import { AutotrackLoopConfig, PtzAxisStep } from './autotrack-config.js';
+import { NormalizedError } from './frame-error.js';
+/**
+ * What the loop knows about the camera's NATIVE autotrack, from the
+ * off-event-path mirror.
+ *
+ * Native and emulated are two implementations of ONE function and must never
+ * be two switches an operator can set to disagree (D62). Until that single
+ * switch exists, this slice refuses to move a head whose firmware may also be
+ * moving it — and `unknown` refuses too, because not-yet-read must not look
+ * like not-enabled (D315, D393).
+ */
+export type NativeAutotrackState = 
+/** The camera has no `ptz-autotrack` binding at all. No conflict possible. */
+'absent'
+/** Bound and reported OFF. */
+ | 'disabled'
+/** Bound and reported ON — the firmware is driving this head. */
+ | 'enabled'
+/** Never successfully read, or the last read failed. */
+ | 'unknown';
+/** Why the loop did NOT move. Every one of these is logged, per frame, with
+ *  the measured error: a loop that decides not to move must not be
+ *  indistinguishable from a dead one (D391). */
+export type AutotrackHoldReason = 
+/** `AUTOTRACK_ARMED` is false, or no target camera is configured. */
+'disarmed'
+/** No target has ever been held. */
+ | 'no-target'
+/** The held target was absent from this frame, inside its disappear delay. */
+ | 'target-absent'
+/** The target is gone and the head has already been sent home. */
+ | 'home-already-issued'
+/** The frame did not say how big it is — the error is unknowable (D393). */
+ | 'frame-geometry-unknown'
+/** The subject's centre is inside the central dead zone. THE NORMAL CASE. */
+ | 'inside-dead-zone'
+/** A correction was running and the subject reached the tighter inner box.
+ *  The correction ENDS here, deliberately short of the centre. */
+ | 'settled'
+/** The driver does not report `moveImpulseMs`, so nothing proves the pulse
+ *  self-terminates. */
+ | 'impulse-duration-unknown'
+/** The camera's own autotrack is armed — two sources, one mechanism. */
+ | 'native-autotrack-enabled'
+/** The camera's own autotrack state has never been read. */
+ | 'native-autotrack-unknown'
+/** The previous pulse is still travelling, or the detector has not yet seen
+ *  the framing it produced. */
+ | 'pulse-dead-time'
+/** The loop's own commands-per-second ceiling. */
+ | 'rate-limited';
+export type AutotrackDecision = {
+    readonly action: 'hold';
+    readonly reason: AutotrackHoldReason;
+} | {
+    readonly action: 'pulse';
+    readonly pan: PtzAxisStep;
+    readonly tilt: PtzAxisStep;
+    readonly speed: number;
+} | {
+    readonly action: 'home';
+    readonly reason: 'target-gone';
+};
+export interface AutotrackLoopState {
+    /** A correction is in progress on this axis: it ends at the tighter inner
+     *  box, not at the dead zone it started outside of. */
+    readonly correctingX: boolean;
+    readonly correctingY: boolean;
+    /** When the last command (pulse or home) was issued. `null` = never. */
+    readonly lastCommandAtMs: number | null;
+    /** Whether the head has already been sent home for the current absence. */
+    readonly homeIssued: boolean;
+}
+export declare const INITIAL_AUTOTRACK_LOOP_STATE: AutotrackLoopState;
+/** The held target as this frame saw it. `error` is `null` when the frame's
+ *  geometry was unreadable — present-but-unmeasurable, which is NOT absent. */
+export interface AutotrackTargetFrame {
+    readonly trackId: string;
+    readonly error: NormalizedError | null;
+}
+export interface AutotrackDecisionInput {
+    readonly nowMs: number;
+    /** Armed AND pointed at a camera. False ⇒ the loop only measures. */
+    readonly armed: boolean;
+    /** The held target if it was OBSERVED on this frame, else `null`. */
+    readonly target: AutotrackTargetFrame | null;
+    /** When the held target was last observed. `null` = nothing held. */
+    readonly targetLastSeenAtMs: number | null;
+    /** `ptz.getOptions().moveImpulseMs`, from the mirror. `null` = unknown. */
+    readonly moveImpulseMs: number | null;
+    readonly nativeAutotrack: NativeAutotrackState;
+    readonly config: AutotrackLoopConfig;
+}
+export interface AutotrackDecisionResult {
+    readonly state: AutotrackLoopState;
+    readonly decision: AutotrackDecision;
+}
+export declare function decideAutotrack(state: AutotrackLoopState, input: AutotrackDecisionInput): AutotrackDecisionResult;

package/dist/builtins/autotrack/autotrack-loop.d.ts

@@ -0,0 +1,75 @@
+import { IScopedLogger, ObjectDetection } from '@camstack/types';
+import { AutotrackLoopConfig, PtzAxisStep } from './autotrack-config.js';
+import { MirrorRefreshOutcome, PtzMirror } from './ptz-mirror.js';
+import { TargetCandidate } from './target-selection.js';
+export interface PulseCommand {
+    readonly deviceId: number;
+    readonly pan: PtzAxisStep;
+    readonly tilt: PtzAxisStep;
+    readonly speed: number;
+}
+/** The only way this loop touches the camera. One self-terminating pulse, or
+ *  home. There is deliberately no `continuousMove` and no `stop`. */
+export interface AutotrackCommands {
+    pulse(command: PulseCommand): Promise<void>;
+    goHome(deviceId: number): Promise<void>;
+}
+export interface AutotrackLoopDeps {
+    readonly deviceId: number;
+    readonly targetClass: string;
+    readonly armed: boolean;
+    readonly config: AutotrackLoopConfig;
+    readonly logger: IScopedLogger;
+    readonly commands: AutotrackCommands;
+    readonly now: () => number;
+}
+/** The subset of the `frame-tracked` payload this loop reads. Named so the
+ *  tests can build one without the event envelope. */
+export interface TrackedFrame {
+    readonly deviceId: number;
+    readonly timestamp: number;
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+    readonly detections: readonly ObjectDetection[];
+}
+/**
+ * Candidates of the configured class on this frame.
+ *
+ * A detection counts only when it carries a `track` — `buildOverlayDetections`
+ * attaches one exactly to the boxes a tracked entry was ASSOCIATED with on this
+ * frame, so this set is the observed-and-tracked set and nothing else.
+ */
+export declare function candidatesFromFrame(detections: readonly ObjectDetection[], targetClass: string): readonly TargetCandidate[];
+export declare class AutotrackLoop {
+    private readonly deps;
+    private selection;
+    private loopState;
+    private mirror;
+    private latency;
+    private presence;
+    private lastFrameAtMs;
+    private lastSummaryAtMs;
+    constructor(deps: AutotrackLoopDeps);
+    /** Read-only view of the mirror, for the addon's startup log. */
+    get ptzMirror(): PtzMirror;
+    /** Fold one refresh outcome into the mirror. Called by the TIMER, never from
+     *  {@link onFrame}. */
+    applyMirror(outcome: MirrorRefreshOutcome): void;
+    /** One analysed frame. Measures first, then decides. */
+    onFrame(frame: TrackedFrame): Promise<void>;
+    /**
+     * Off-event-path tick: the silence watchdog.
+     *
+     * Evaluates the SAME disappear delay against the time since the last frame.
+     * A stream that died is a target that is gone, and the head goes home —
+     * which is also the only thing that would otherwise never happen, because
+     * every other release is driven by a frame arriving.
+     */
+    tick(): Promise<void>;
+    /** Emit the aggregates now, whatever the schedule says. Used at shutdown so
+     *  a short run still reports what it measured. */
+    logSummary(): void;
+    private maybeSummarize;
+    private dispatch;
+    private logDecision;
+}

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

@@ -0,0 +1,71 @@
+import { AddonInitResult, BaseAddon } from '@camstack/types';
+/** Persisted shape: one entry per camera the operator has touched. */
+export interface AutotrackConfig {
+    readonly cameras: Record<string, unknown>;
+}
+export declare class AutotrackAddon extends BaseAddon<AutotrackConfig> {
+    private records;
+    private readonly sessions;
+    /** Cameras whose `ptz-autotrack` binding names THIS addon, last time we read. */
+    private bound;
+    /**
+     * Cameras that ALSO have a `ptz-autotrack` provider that is not us.
+     *
+     * This is the only way to ask about a firmware autotrack without asking
+     * ourselves: on a camera where our wrapper is the binding, `ptzAutotrack.
+     * getStatus` resolves to THIS addon and returns our own switch — so a loop
+     * that read it would see `enabled: true` the moment the operator turned it
+     * on, conclude the firmware was driving the head, and refuse to move. A
+     * self-deadlock that would have looked exactly like the safety gate working.
+     */
+    private foreignProvider;
+    private readonly lastChangedAt;
+    private unsubscribeFrames;
+    private unsubscribeBindings;
+    private mirrorTimer;
+    private watchdogTimer;
+    constructor();
+    protected onInitialize(): Promise<AddonInitResult>;
+    protected onShutdown(): Promise<void>;
+    protected onConfigChanged(): Promise<void>;
+    private recordOf;
+    private statusOf;
+    private patchCamera;
+    private serialiseRecords;
+    /** Bindings first, then sessions: a session must never outlive its binding. */
+    private refreshEverything;
+    /**
+     * Which cameras have this addon bound as their `ptz-autotrack` provider.
+     *
+     * Only cameras the operator has a record for are asked about: a wrapper that
+     * enumerated every camera on every refresh would walk the whole fleet to
+     * learn nothing about the ones nobody switched on.
+     *
+     * A read that FAILS leaves the previous answer standing (D49) — a transient
+     * store blip must not stop a running loop. A read that SUCCEEDS and omits us
+     * is believed immediately: unlike a doorbell press, the cost of erring open
+     * here is a head that keeps moving after the operator unbound it.
+     */
+    private refreshBindings;
+    /** Start a loop for every camera that is bound AND switched on; stop the rest. */
+    private reconcileSessions;
+    private startSession;
+    private stopSession;
+    /**
+     * One off-event-path refresh of a camera's mirror.
+     *
+     * Two reads, and either one failing fails the whole refresh: a mirror half
+     * from now and half from twenty minutes ago is worse than one that says it
+     * is stale. The previous answers stand (D49).
+     */
+    private refreshMirror;
+    /**
+     * Is the camera's OWN autotrack on?
+     *
+     * `null` when the camera has no native autotrack at all — which is the case
+     * this addon exists for, and is NOT an error. A camera that HAS one and has
+     * it armed makes this loop refuse: two implementations driving one head is
+     * the thing the single-switch rule exists to prevent (D62).
+     */
+    private readNativeAutotrack;
+}

package/dist/builtins/autotrack/frame-error.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The frame-space error term: where the subject's centre sits relative to the
+ * centre of the frame, normalized to ±0.5 on each axis.
+ *
+ * ## There is no letterbox to discount here, and that was checked
+ *
+ * The detector runs on a 640×640 `fit: 'contain'` view
+ * (`SPLIT_DETECTION_VIEW`, `packages/addon-pipeline/src/pipeline-runner/
+ * index.ts`), so the raster the model sees IS letterboxed. The coordinates that
+ * reach this module are not: `ObjectDetection.bbox` is documented — and
+ * produced — as "absolute pixel coordinates in the SOURCE frame"
+ * (`packages/types/src/types/detection.ts`), and the same payload carries the
+ * `frameWidth` / `frameHeight` those pixels are expressed in
+ * (`PipelineAnalyticsFrameTrackedPayload`). The un-letterboxing has already
+ * happened upstream; doing it again here would double-count the bars.
+ *
+ * ## A geometry we cannot read is `null`, never centred (D393)
+ *
+ * A frame that arrives with a zero or non-finite width has not told us the
+ * subject is centred — it has told us nothing. Folding that into `{x:0, y:0}`
+ * would read as "perfectly on target" and silence the loop exactly when it
+ * should complain, the same shape as the unreadable `statfs` folded into "0
+ * bytes of headroom". The return type says so, and every caller must branch.
+ */
+/** Signed offset of the subject's centre from the frame centre, in fractions
+ *  of the frame: `-0.5` = hard left/top edge, `0` = centred, `+0.5` = hard
+ *  right/bottom edge. `y` grows DOWNWARD, as image coordinates do. */
+export interface NormalizedError {
+    readonly x: number;
+    readonly y: number;
+}
+/** The frame the bbox's pixels are expressed in. */
+export interface FrameGeometry {
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+}
+/** Absolute-pixel box in the source frame (`ObjectDetection.bbox`). */
+export interface FrameBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Error of one subject box against the frame centre.
+ *
+ * `null` when the frame geometry or the box is unreadable — never a centred
+ * zero (D393).
+ */
+export declare function computeNormalizedError(box: FrameBox, geometry: FrameGeometry): NormalizedError | null;

package/dist/builtins/autotrack/frame-measurements.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The two measurements this slice exists to produce. Pure reducers: a tally in,
+ * a NEW tally out, nothing mutated, no clock read inside.
+ *
+ * ## 1. Bus latency — how old a `frame-tracked` payload is when a hub-only
+ *    subscriber gets it
+ *
+ * `Date.now() - payload.timestamp`, per frame. Nobody has measured this hop.
+ * The only latency number in the docs (p90 381 ms, max 22 s) is a DIFFERENT hop
+ * and must not be reused for it. It decides whether a visual control loop is
+ * viable at all: the error the loop acts on is this many milliseconds stale, so
+ * a subject walking at 1 m/s has already moved `latency × 1 m/s` by the time a
+ * pulse is issued.
+ *
+ * ## 2. Track absence — the empirical test of the loop's SAFETY PREMISE
+ *
+ * The premise is that every bbox on `frame-tracked` is an OBSERVED detection,
+ * never a coasted `SortTracker` prediction. It is INFERRED, not measured:
+ * `buildOverlayDetections` (`addon-post-analysis/src/pipeline-analytics/
+ * overlay-frame-builder.ts`) iterates the REAL frame detections and attaches a
+ * track only to the ones a tracked entry was associated with, so a coasted
+ * track contributes no box. `matchedThisFrame` is not on the wire, so the
+ * premise cannot be read off the payload — only inferred from the SHAPE of the
+ * gaps.
+ *
+ * If the premise HOLDS, an absence is a genuine miss and gaps are ragged: runs
+ * of 1, the odd 2, no preferred length. If it is FALSE — if a coasted
+ * prediction is being published as a box — the loop would be chasing a
+ * fabricated position, and the tell is the opposite: long stretches with NO
+ * gaps at all (the tracker filling every miss), then a gap exactly as long as
+ * the tracker's max age when it finally gives up. That is what
+ * {@link PresenceTally.gapRunHistogram} is for; a run-length distribution with
+ * a spike at one value is coasting, a decaying distribution is honest misses.
+ */
+/** Rolling aggregate of the bus-latency measurement. */
+export interface LatencyTally {
+    readonly frames: number;
+    readonly sumMs: number;
+    readonly minMs: number | null;
+    readonly maxMs: number | null;
+    /** Upper bounds, ms, of the histogram buckets — the last bucket is the
+     *  overflow above the final bound. */
+    readonly bucketBoundsMs: readonly number[];
+    /** One count per bucket bound, plus one trailing overflow count. */
+    readonly bucketCounts: readonly number[];
+    /** Frames whose `timestamp` produced a NEGATIVE age. A clock skew between
+     *  the analytics node and the hub shows up here and nowhere else; counted
+     *  separately rather than folded into the mean, which would hide it. */
+    readonly negativeAgeFrames: number;
+}
+export declare const LATENCY_BUCKET_BOUNDS_MS: readonly number[];
+export declare const INITIAL_LATENCY_TALLY: LatencyTally;
+export declare function recordLatency(tally: LatencyTally, latencyMs: number): LatencyTally;
+/** Rolling aggregate of the track-absence measurement. */
+export interface PresenceTally {
+    /** Frames counted while a target was HELD — the denominator. A frame with
+     *  no target held at all is not evidence about absence and is excluded. */
+    readonly framesWithTarget: number;
+    /** Of those, how many did not carry a box for the held track. */
+    readonly absentFrames: number;
+    /** Length of the gap currently open, in frames. */
+    readonly currentGapFrames: number;
+    /** Longest gap seen. */
+    readonly maxGapFrames: number;
+    /** How many CLOSED gaps had length 1, 2, 3, … The index is `length - 1`;
+     *  lengths beyond {@link GAP_HISTOGRAM_LENGTHS} land in the final overflow
+     *  slot. The SHAPE of this is the premise test — see the module docblock. */
+    readonly gapRunHistogram: readonly number[];
+}
+export declare const GAP_HISTOGRAM_LENGTHS = 8;
+export declare const INITIAL_PRESENCE_TALLY: PresenceTally;
+/**
+ * Count one frame on which a target was held.
+ *
+ * `present` is "the held track carried a box on THIS frame". A closing gap is
+ * binned at the moment it closes, which is why the open gap is reported
+ * separately (`currentGapFrames`) instead of being counted twice.
+ */
+export declare function recordPresence(tally: PresenceTally, present: boolean): PresenceTally;
+/** Flat, log-friendly view of both tallies. Every field is a number so the log
+ *  line can be grouped and diffed per camera. */
+export interface MeasurementSummary {
+    readonly frames: number;
+    readonly latencyMeanMs: number | null;
+    readonly latencyMinMs: number | null;
+    readonly latencyMaxMs: number | null;
+    readonly latencyBucketsMs: readonly number[];
+    readonly latencyBucketCounts: readonly number[];
+    readonly negativeAgeFrames: number;
+    readonly framesWithTarget: number;
+    readonly absentFrames: number;
+    readonly absentFraction: number | null;
+    readonly maxGapFrames: number;
+    readonly openGapFrames: number;
+    readonly gapRunHistogram: readonly number[];
+}
+export declare function summarize(latency: LatencyTally, presence: PresenceTally): MeasurementSummary;

package/dist/builtins/autotrack/index.d.ts

@@ -0,0 +1,2 @@
+export { AutotrackAddon } from './autotrack.addon.js';
+export { AutotrackAddon as default } from './autotrack.addon.js';