@camstack/system 1.2.390 → 1.2.391

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

@@ -1,71 +1,108 @@
-import { AddonInitResult, BaseAddon } from '@camstack/types';
+/**
+* `autotrack` — the EMULATED implementation behind the `ptz-autotrack` switch.
+*
+* A camera with firmware autotrack serves `ptz-autotrack` from its own native
+* provider. A camera with a mechanical head and no firmware autotrack gets the
+* same cap from THIS addon, as a wrapper the operator binds per camera —
+* exactly how `snapshot` gives a frame to a device whose driver cannot take
+* one.
+*
+* That is the whole point of the shape (D62, D520): **one switch**. The
+* operator turns autotrack on in the same place whichever implementation is
+* behind it, and the two can never disagree, because there are not two of them
+* on one camera — the binding chooses which one answers.
+*
+* ## What the emulation may do, and what it may never do (D520)
+*
+* It moves a head ONLY with a self-terminating `ptz.move` pulse — never
+* `continuousMove`, whose `stop` would ride on telemetry that may be dropped,
+* and whose worst case is a camera spinning unattended. It refuses to move at
+* all when it cannot read `moveImpulseMs`, because that number is the proof the
+* head stops without a second message. It refuses while the camera's NATIVE
+* autotrack is on. It is declaredly visual: `getPosition` is null on every PTZ
+* driver here, so the loop never knows where the head points.
+*
+* ## Erring direction: CLOSED
+*
+* A gate whose worst error is a spurious event may err OPEN on an unreadable
+* binding (D49). Here it is the opposite: the cost of running when the
+* operator has unbound us is a head that keeps moving on its own. A camera whose binding cannot be
+* confirmed stops. It resumes the moment a read confirms it again, and the
+* stop is logged — a loop that quietly stopped is the same as a loop that
+* never ran.
+*
+* Its own runner, `hub-only`, and no `execution.group`: it drives devices and a
+* co-located crash would respawn everything sharing the runner (D29).
+*/
+import type { AddonInitResult } from "@camstack/types";
+import { BaseAddon } from "@camstack/types";
 /** Persisted shape: one entry per camera the operator has touched. */
 export interface AutotrackConfig {
-    readonly cameras: Record<string, unknown>;
+	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;
+	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

@@ -1,50 +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.
- */
+* 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. */
+*  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;
+	readonly x: number;
+	readonly y: number;
 }
 /** The frame the bbox's pixels are expressed in. */
 export interface FrameGeometry {
-    readonly frameWidth: number;
-    readonly frameHeight: number;
+	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;
+	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).
- */
+* 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

@@ -1,97 +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.
- */
+* 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;
+	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[];
+	/** 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.
- */
+* 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. */
+*  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[];
+	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

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

package/dist/builtins/autotrack/ptz-mirror.d.ts

@@ -1,25 +1,54 @@
-import { NativeAutotrackState } from './autotrack-decision.js';
+/**
+* The in-memory mirror of everything the loop needs to know about the camera
+* that is NOT on the event payload — refreshed off the event path, by timer,
+* and only READ on the event path (D49).
+*
+* Two facts live here:
+*   - `moveImpulseMs` (`ptz.getOptions`) — how long one pulse runs. Without it
+*     nothing proves the pulse self-terminates, and the loop refuses to move.
+*   - the NATIVE autotrack state (`deviceManager.getBindings` +
+*     `ptzAutotrack.getStatus`) — whether the firmware is already driving this
+*     head.
+*
+* ## Why a mirror and not a read on the event path
+*
+* A one-shot decision must never gate on a fallible read (D49). If the loop
+* awaited `getOptions()` per frame, one bad read would look exactly like "this
+* camera has no PTZ" — and at 10 Hz it would also put a tRPC round-trip on the
+* frame path. So the refresh runs on its own timer and the event path reads a
+* field.
+*
+* ## A failed refresh changes nothing
+*
+* {@link applyMirrorRefresh} never downgrades a KNOWN value to `null` on a
+* failed read: a refresh that threw leaves the previous answer standing and
+* records the failure. A value that has never been read stays `unknown`, and
+* `unknown` refuses to move — not-yet-read must not look like not-enabled
+* (D315), and a measurement that failed is `null`, never a convenient zero
+* (D393).
+*/
+import type { NativeAutotrackState } from "./autotrack-decision.js";
 export interface PtzMirror {
-    /** `ptz.getOptions().moveImpulseMs`. `null` = never read, or the driver
-     *  itself reports it cannot say. */
-    readonly moveImpulseMs: number | null;
-    readonly nativeAutotrack: NativeAutotrackState;
-    /** When a refresh last SUCCEEDED. `null` = never. */
-    readonly lastRefreshAtMs: number | null;
-    /** Message of the last failed refresh, `null` once one succeeds again. */
-    readonly lastError: string | null;
-    /** Consecutive failed refreshes since the last success. */
-    readonly consecutiveFailures: number;
+	/** `ptz.getOptions().moveImpulseMs`. `null` = never read, or the driver
+	*  itself reports it cannot say. */
+	readonly moveImpulseMs: number | null;
+	readonly nativeAutotrack: NativeAutotrackState;
+	/** When a refresh last SUCCEEDED. `null` = never. */
+	readonly lastRefreshAtMs: number | null;
+	/** Message of the last failed refresh, `null` once one succeeds again. */
+	readonly lastError: string | null;
+	/** Consecutive failed refreshes since the last success. */
+	readonly consecutiveFailures: number;
 }
 export declare const INITIAL_PTZ_MIRROR: PtzMirror;
 /** What one refresh attempt found. A `failed` outcome carries a reason —
- *  there is no silent failure shape. */
+*  there is no silent failure shape. */
 export type MirrorRefreshOutcome = {
-    readonly kind: 'read';
-    readonly moveImpulseMs: number | null;
-    readonly nativeAutotrack: NativeAutotrackState;
+	readonly kind: "read";
+	readonly moveImpulseMs: number | null;
+	readonly nativeAutotrack: NativeAutotrackState;
 } | {
-    readonly kind: 'failed';
-    readonly error: string;
+	readonly kind: "failed";
+	readonly error: string;
 };
 export declare function applyMirrorRefresh(mirror: PtzMirror, outcome: MirrorRefreshOutcome, nowMs: number): PtzMirror;

package/dist/builtins/autotrack/target-selection.d.ts

@@ -1,60 +1,46 @@
 /**
- * Sticky target choice: pick ONE track, then stay on it.
- *
- * Re-picking "the best candidate" every frame is oscillation on another axis —
- * two people a metre apart trade the top score frame to frame and the head
- * saws between them, having centred neither. So the target is chosen ONCE and
- * held by `trackId` until it has been gone for the disappear delay. While it
- * is merely MISSING from a frame nothing is switched and nothing is released:
- * `present: false` is reported and the decision layer decides what a gap means.
- *
- * Pure: state in, state out, no clock read inside — `nowMs` is passed. A new
- * state object is returned every call; the input is never mutated.
- */
+* Sticky target choice: pick ONE track, then stay on it.
+*
+* Re-picking "the best candidate" every frame is oscillation on another axis —
+* two people a metre apart trade the top score frame to frame and the head
+* saws between them, having centred neither. So the target is chosen ONCE and
+* held by `trackId` until it has been gone for the disappear delay. While it
+* is merely MISSING from a frame nothing is switched and nothing is released:
+* `present: false` is reported and the decision layer decides what a gap means.
+*
+* Pure: state in, state out, no clock read inside — `nowMs` is passed. A new
+* state object is returned every call; the input is never mutated.
+*/
 /** One candidate of the configured class on this frame. */
 export interface TargetCandidate {
-    readonly trackId: string;
-    /** Pixel area of the box. Used ONLY to break the first choice; it never
-     *  unseats a target that is still alive. */
-    readonly areaPx: number;
+	readonly trackId: string;
+	/** Pixel area of the box. Used ONLY to break the first choice; it never
+	*  unseats a target that is still alive. */
+	readonly areaPx: number;
 }
 export interface TargetSelectionState {
-    /** The track being followed, or `null` when nothing is held. */
-    readonly trackId: string | null;
-    /** When that track was last OBSERVED on a frame. `null` while nothing is
-     *  held. Never advanced by a frame the track was absent from. */
-    readonly lastSeenAtMs: number | null;
+	/** The track being followed, or `null` when nothing is held. */
+	readonly trackId: string | null;
+	/** When that track was last OBSERVED on a frame. `null` while nothing is
+	*  held. Never advanced by a frame the track was absent from. */
+	readonly lastSeenAtMs: number | null;
 }
 export declare const INITIAL_TARGET_SELECTION_STATE: TargetSelectionState;
 /** Why the selection came out the way it did — logged on every frame so a
- *  loop that chooses nothing is distinguishable from a loop that is dead. */
-export type TargetSelectionReason = 
-/** The held track was observed on this frame. */
-'held'
-/** The held track was absent from this frame but is still within its
- *  disappear delay — nothing is switched, nothing is released. */
- | 'held-absent'
-/** The held track exceeded its disappear delay and was released; no
- *  candidate was available to take its place. */
- | 'released'
-/** The held track was released and a new one was picked on the same frame. */
- | 'switched'
-/** Nothing was held and a candidate was picked. */
- | 'acquired'
-/** Nothing was held and no candidate was available. */
- | 'idle';
+*  loop that chooses nothing is distinguishable from a loop that is dead. */
+export type TargetSelectionReason = "held" | "held-absent" | "released" | "switched" | "acquired" | "idle";
 export interface TargetSelectionResult {
-    readonly state: TargetSelectionState;
-    /** The held track, after this frame. `null` when nothing is held. */
-    readonly trackId: string | null;
-    /** Whether the held track was OBSERVED on this frame. This is the boolean
-     *  the absence measurement counts. */
-    readonly present: boolean;
-    readonly reason: TargetSelectionReason;
+	readonly state: TargetSelectionState;
+	/** The held track, after this frame. `null` when nothing is held. */
+	readonly trackId: string | null;
+	/** Whether the held track was OBSERVED on this frame. This is the boolean
+	*  the absence measurement counts. */
+	readonly present: boolean;
+	readonly reason: TargetSelectionReason;
 }
 export interface TargetSelectionInput {
-    readonly nowMs: number;
-    readonly candidates: readonly TargetCandidate[];
-    readonly disappearDelayMs: number;
+	readonly nowMs: number;
+	readonly candidates: readonly TargetCandidate[];
+	readonly disappearDelayMs: number;
 }
 export declare function selectTarget(state: TargetSelectionState, input: TargetSelectionInput): TargetSelectionResult;