@vscada/core 0.0.1

package/dist/scheduler/alarm-band.d.ts

@@ -0,0 +1,33 @@
+import type { Threshold } from '../scene/scene-schema';
+import type { VesselAlarmTokens } from '../tokens';
+/**
+ * Story 4.4 Task 3 — originally a core-owned, tag-agnostic MIRROR of what
+ * was then `@vscada/primitives`'s `vessels/alarm.ts` (Story 3.3), kept
+ * duplicated rather than shared because primitives depends on core, never
+ * the reverse, so primitives' copy couldn't be imported here.
+ *
+ * AD-12 fix (architecture-code-audit-2026-08-27) — collapsed the resulting
+ * 3-way duplication (this file, `vessels/alarm.ts`, `instruments/zone.ts`,
+ * all byte-identical `resolveAlarmBand` bodies) the other direction
+ * instead: THIS is now the single canonical implementation, exported
+ * publicly (mirroring the existing `resolveMediumStyle` precedent for a
+ * shared pure core utility primitives are meant to consume), and both
+ * primitive-side copies were deleted in favor of importing from here. The
+ * live-region controller (`scada-view.ts`) still uses it directly for ANY
+ * element with a numeric binding + declared `thresholds`, not just
+ * vessels/gauges.
+ */
+export type AlarmBand = 'normal' | 'low' | 'low-low' | 'high' | 'high-high';
+export declare function resolveAlarmBand(value: number, thresholds: readonly Threshold[]): AlarmBand;
+/**
+ * Band -> token color, with graceful degradation (AD-7: no alarm/zone
+ * tokens registered -> `fallback`, e.g. a plain surface/needle color,
+ * never a literal-color stand-in). `VesselAlarmTokens`'s shape (named
+ * fields, not a `Record`, so a theme can't accidentally omit a band) is
+ * reused as-is by every consumer of this function — `GaugeZoneTokens`
+ * (instruments) is a true type ALIAS of this type (`tokens.ts`), not just
+ * a structural coincidence, so no adapter is needed and the compiler
+ * enforces the two staying compatible.
+ */
+export declare function resolveAlarmColor(tokens: VesselAlarmTokens | undefined, band: AlarmBand, fallback: string | undefined): string | undefined;
+//# sourceMappingURL=alarm-band.d.ts.map

package/dist/scheduler/alarm-band.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-band.d.ts","sourceRoot":"","sources":["../../src/scheduler/alarm-band.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAE5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAW3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAc1I"}

package/dist/scheduler/animation-registry.d.ts

@@ -0,0 +1,38 @@
+import type { AnimationHandle } from '../contracts/handles';
+/**
+ * Story 4.3 Task 2 — LOD's "concurrent animated elements are capped"
+ * priority order: state-lamps survive longest (safety indication),
+ * waves are cut first. `Scheduler` (the sanctioned home for ALL freeze
+ * POLICY, AD-5) reads `registeredEntries()`'s priority tag to decide what
+ * to cap; this registry only tracks the tag, never acts on it itself.
+ */
+export type AnimationPriority = 'state-lamp' | 'flow' | 'rotation' | 'wave';
+/** Lower rank survives longer under a LOD cap. */
+export declare const ANIMATION_PRIORITY_RANK: Record<AnimationPriority, number>;
+export declare class AnimationRegistry {
+    private entries;
+    /** `priority` defaults to `'rotation'` — the middle tier — for any registration site that doesn't (yet) tag itself explicitly. */
+    register(elementId: string, handle: AnimationHandle, priority?: AnimationPriority): void;
+    /** Read-only view for `Scheduler`'s LOD cap policy — one row per registered animation, in registration order. */
+    registeredEntries(): {
+        elementId: string;
+        priority: AnimationPriority;
+    }[];
+    unregisterElement(elementId: string): void;
+    pauseAll(elementId: string): void;
+    resumeAll(elementId: string): void;
+    pauseScene(): void;
+    resumeScene(): void;
+    isPaused(elementId: string): boolean[];
+    /**
+     * Story 1.7: the sanctioned deterministic-frame mechanism for visual
+     * regression — seeks EVERY registered animation's WAAPI `currentTime`,
+     * paused or not. Works only because every continuous animation is
+     * registered (AD-5); an animation that doesn't move when sought is
+     * exactly as designed, and one that keeps moving after a seek is a real
+     * compliance bug (something bypassed the registry) — that's this
+     * method's whole reason for existing.
+     */
+    seekAll(timeMs: number): void;
+}
+//# sourceMappingURL=animation-registry.d.ts.map

package/dist/scheduler/animation-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-registry.d.ts","sourceRoot":"","sources":["../../src/scheduler/animation-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5E,kDAAkD;AAClD,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAKrE,CAAC;AAgBF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAe;IAE9B,kIAAkI;IAClI,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,QAAQ,GAAE,iBAA8B,GAAG,IAAI;IAIpG,iHAAiH;IACjH,iBAAiB,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,EAAE;IAIzE,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI1C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IASjC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IASlC,UAAU,IAAI,IAAI;IASlB,WAAW,IAAI,IAAI;IASnB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAItC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAK9B"}

package/dist/scheduler/lod.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Story 4.3 Task 2 — LOD (level-of-detail) zoom threshold, with hysteresis
+ * so a zoom hovering right at the boundary doesn't flap the simplified
+ * view on and off every frame. Below the threshold the scene is "a
+ * 40-tank overview" (§9.4): liquids simplify to static fills, concurrent
+ * animated elements are capped, and text labels below legibility hide —
+ * see `AnimationRegistry`'s priority tiers and `ScadaView`'s
+ * `vscada-lod-active` class toggle for the rest of the mechanism this
+ * threshold check drives.
+ */
+export declare const DEFAULT_LOD_ZOOM_THRESHOLD = 0.5;
+/** Fraction of the threshold the zoom must cross BEYOND the boundary to flip state (~10%, Dev Notes). */
+export declare const DEFAULT_LOD_HYSTERESIS_FRACTION = 0.1;
+/** Provisional capacity-gate assumption (architecture-time, spine conventions) — the max concurrently-active registered animations once LOD is active. */
+export declare const DEFAULT_LOD_MAX_ACTIVE_ANIMATIONS = 50;
+/**
+ * Per-frame-cheap threshold check (a couple of comparisons, no allocation)
+ * — safe to call unconditionally every scheduler tick. `wasActive` is the
+ * PREVIOUS call's result: crossing INTO the simplified view requires zoom
+ * to fall below `threshold - band`; crossing OUT requires it to rise above
+ * `threshold + band`. A zoom sitting anywhere inside the band keeps
+ * whichever state it already had.
+ */
+export declare function resolveLodActive(zoom: number, wasActive: boolean, threshold?: number, hysteresisFraction?: number): boolean;
+//# sourceMappingURL=lod.d.ts.map

package/dist/scheduler/lod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lod.d.ts","sourceRoot":"","sources":["../../src/scheduler/lod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,yGAAyG;AACzG,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,0JAA0J;AAC1J,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,EAClB,SAAS,GAAE,MAAmC,EAC9C,kBAAkB,GAAE,MAAwC,GAC3D,OAAO,CAIT"}

package/dist/scheduler/quality-overlay.d.ts

@@ -0,0 +1,19 @@
+import type { Renderer } from '../contracts/renderer';
+import type { ThemeContext } from '../contracts/primitive';
+import type { Condition } from './quality';
+/**
+ * The quality/staleness overlay (§4.3) — core-owned, cross-primitive
+ * (Project Structure Notes: "overlay visual helpers in core, not
+ * per-primitive"). Structure is built ONCE per element (AD-2); only
+ * visibility toggling happens per tick, through the renderer seam like any
+ * other scheduler-driven write. `<pattern>` for the bad-quality hatch is
+ * allowed (C7 bans filters, not patterns); desaturation is a grey overlay
+ * rect, never `filter: grayscale()`.
+ */
+export interface QualityOverlay {
+    group: SVGGElement;
+    setCondition(renderer: Renderer, condition: Condition): void;
+    setAgeBadge(renderer: Renderer, text: string | null): void;
+}
+export declare function buildQualityOverlay(w: number, h: number, theme: ThemeContext): QualityOverlay;
+//# sourceMappingURL=quality-overlay.d.ts.map

package/dist/scheduler/quality-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-overlay.d.ts","sourceRoot":"","sources":["../../src/scheduler/quality-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAK3C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7D,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CAC5D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,cAAc,CAyF7F"}

package/dist/scheduler/quality.d.ts

@@ -0,0 +1,15 @@
+import type { BufferEntry } from '../store/value-store';
+export type Condition = 'good' | 'uncertain' | 'stale' | 'bad';
+export declare function worseCondition(a: Condition, b: Condition): Condition;
+/**
+ * Per-tag condition (§4.3). `bad` quality wins outright — a value can be
+ * simultaneously old AND explicitly bad-quality, and bad quality is the
+ * worse of the two per the stated precedence. Age is computed against the
+ * declared `timestamp` when present, falling back to `arrivalTime` (§4.2).
+ */
+export declare function tagCondition(entry: Readonly<BufferEntry>, now: number, stalenessTimeoutMs: number): Condition;
+/** Worst-of aggregation across every tag an element is bound to (design decision — one overlay tier per element). */
+export declare function worstOf(conditions: Condition[]): Condition;
+/** `47s` under a minute, `3m` at/above — deliberately coarse (§4.3's badge is a glance-level cue, not a stopwatch). */
+export declare function formatAge(ms: number): string;
+//# sourceMappingURL=quality.d.ts.map

package/dist/scheduler/quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.d.ts","sourceRoot":"","sources":["../../src/scheduler/quality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,GAAG,KAAK,CAAC;AAK/D,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAM7G;AAED,qHAAqH;AACrH,wBAAgB,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,CAE1D;AAED,uHAAuH;AACvH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI5C"}

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,243 @@
+import type { Handle } from '../contracts/handles';
+import type { Renderer } from '../contracts/renderer';
+import type { TimeSource } from '../contracts/time-source';
+import type { ConnectionState } from '../contracts/connection-state';
+import type { ValueStore } from '../store/value-store';
+import { type AnimationRegistry } from './animation-registry';
+import type { QualityOverlay } from './quality-overlay';
+import { type Condition } from './quality';
+import type { FlowInferenceCache } from '../topology/inference';
+/**
+ * Default numeric jump beyond which a value snaps instead of tweening
+ * (§9.2 "cap it"). Chosen so a typical 0–100% level/position range still
+ * tweens smoothly for normal process changes but a full-range jump (tank
+ * emptied a valve open→closed, a mode switch) snaps instead of visibly
+ * animating over the tween window. Configurable per component instance.
+ */
+export declare const DEFAULT_SNAP_THRESHOLD = 50;
+/** §3.2 `mode` — see `Scheduler.mode`'s own doc for the static/live transition contract (Story 4.1). */
+export type SchedulerMode = 'live' | 'static';
+/** §3.2 default `stalenessTimeout`. */
+export declare const DEFAULT_STALENESS_TIMEOUT_MS = 10000;
+/** Story 4.3 Task 3 — how often staleness/flow evaluation keeps running (via `setInterval`, independent of rAF) while the scene is paused for off-screen/hidden-tab (rAF itself may be throttled to near-zero by the browser in a hidden tab — this is the explicit fallback). */
+export declare const OFFSCREEN_QUALITY_POLL_MS = 1000;
+/** §3.4 `render-stats` detail shape — emitted at 1Hz only while `debug` is enabled (Task 4). */
+export interface RenderStats {
+    fps: number;
+    elementCount: number;
+    droppedFrames: number;
+}
+export interface SchedulerOptions {
+    /** Numeric jump beyond which a value snaps instead of tweening. */
+    snapThreshold?: number;
+}
+/**
+ * The single coalescing rAF loop (§9.1, AD-1) — and, as of Story 1.6, the
+ * ONLY place staleness/quality is evaluated (AD-5: "this logic lives HERE
+ * and nowhere else"). One instance per `<scada-view>` — multi-instance
+ * sharing is explicitly Deferred (spine). Values land in the store
+ * synchronously via `ValueStore.setValues()`; DOM writes happen ONLY here,
+ * on ticks. Coalescing multiple pushes into one write per handle per frame
+ * falls out of the architecture by construction — no extra dedup
+ * bookkeeping is needed for that guarantee.
+ */
+export declare class Scheduler {
+    private timeSource;
+    private store;
+    private renderer;
+    private animationRegistry;
+    private registrations;
+    private tickables;
+    private overlays;
+    private elementQuality;
+    private stopTick;
+    private wasSceneFrozen;
+    /** Story 2.4 Task 2/3: topology-inference read seam — set via `registerFlowInference`. */
+    private flowInference;
+    /** Per-id (element or connection) "currently frozen for a flow reason" — independent bookkeeping from `elementQuality`'s own transition tracking, so the two tiers never fight over the SAME `pauseAll`/`resumeAll` call (AD-5, AD-12). */
+    private flowFrozen;
+    /** Per-id "currently showing the reused isolated/grey overlay" — only touched when quality is 'good' (AD-12: quality tier owns the overlay slot otherwise). */
+    private flowIsolatedOverlay;
+    /** §3.2 — Story 1.3 Task 4's "configurable component-level option" (mutable, like `stalenessTimeout`, not fixed at construction). */
+    snapThreshold: number;
+    /** Story 2.6 AC2: last `store.tagPrefixVersion` seen — a change is polled once per tick (never per-registration) and triggers `_resetInterpolationState`. */
+    private lastSeenTagPrefixVersion;
+    /** Story 4.3 Task 2 — per-id "currently paused for the LOD cap", independent bookkeeping from `flowFrozen`/quality's own tier (AD-5/AD-12: freeze tiers never fight over the same `pauseAll`/`resumeAll` call). */
+    private lodFrozen;
+    private lodActiveValue;
+    /** Cap on concurrently-active registered animations once LOD is active — a token (Dev Notes: "cap + priorities as tokens"), overridable per instance. */
+    lodMaxActiveAnimations: number;
+    /** Story 4.3 Task 3 — true while paused for off-screen/hidden-tab (`pauseForOffscreen`). */
+    private visibilityPaused;
+    private offscreenTimerId;
+    /** Story 4.3 Task 4 — render-stats accounting; all zero-cost when `debug` is off (never even read). */
+    private debugEnabled;
+    private statsFrameCount;
+    private statsDroppedFrames;
+    private statsWindowStart;
+    private lastTickTime;
+    private statsCallback;
+    /** Story 4.4 Task 3 — the ARIA live-region's quality/staleness seam; unconditional (unlike `statsCallback`, never gated behind `debug`). */
+    private conditionCallback;
+    /** §3.2 property — configuring the TIMEOUT is allowed; disabling the freeze BEHAVIOR is not (NFR4). */
+    stalenessTimeout: number;
+    /** §3.2 property. `'degraded'` is intentionally a documented no-op (see Dev Notes) — not yet given a visual treatment. */
+    connectionState: ConnectionState;
+    /** Story 4.1 §8.3 — "static mode is live mode with tween duration zero and timers off. One code path." Gates `start()` (no rAF subscription while static, AC1/FR16) and drives the snap-then-stop / restart transition below (AC2). */
+    private _mode;
+    /** Story 4.1 §3.2 `animate` — master switch for continuous (registry-driven) animation, ORTHOGONAL to `mode`: a live dashboard can pause animation, and a static export can keep pumps spinning (§8.1 default). */
+    private _animateEnabled;
+    constructor(timeSource: TimeSource, store: ValueStore, renderer: Renderer, animationRegistry: AnimationRegistry, options?: SchedulerOptions);
+    /**
+     * Animation-kind handles are not registered here — they go through the
+     * AnimationRegistry. Tween-kind handles go into a separate unconditional
+     * per-tick list (`tag` is unused for them — see `TweenHandle`'s doc).
+     */
+    registerHandle(elementId: string, tag: string, handle: Handle): void;
+    /** Story 1.6: registers the pre-built quality overlay this element's structure carries (core-owned, cross-primitive). */
+    registerQualityOverlay(elementId: string, overlay: QualityOverlay): void;
+    /**
+     * Story 2.4 Task 2/3: wires a `FlowInferenceCache` (the topology module's
+     * OWN cache — recomputed only on source/valve FSM state-change events,
+     * never here) into the tick's read-only resolver pass. `ids` are every
+     * element/connection id this scheduler should apply inferred flow state
+     * to (node ids for equipment, edge/connection ids for pipes).
+     */
+    registerFlowInference(cache: FlowInferenceCache, ids: Iterable<string>): void;
+    unregisterElement(elementId: string): void;
+    get registrationCount(): number;
+    /**
+     * §3.2 `mode` (Story 4.1). live→static: snaps every in-flight tween/
+     * interpolation to its target (reusing AC4's `snapToTargets()` verbatim —
+     * "one code path", §8.3) then `stop()`s the tick + offscreen-poll timer
+     * entirely (AC1: no rAF loop, no staleness timers while static — `tick()`
+     * itself is never reached, so it needs no static-aware branch of its
+     * own). static→live: `start()` resumes normal ticking; staleness simply
+     * starts being evaluated again on the next tick, computed from each tag's
+     * stored `timestamp`/`arrivalTime` exactly as if the gap had been live the
+     * whole time — data that aged past `stalenessTimeout` while static
+     * correctly (and intentionally) freezes on that very first live tick.
+     */
+    get mode(): SchedulerMode;
+    set mode(value: SchedulerMode);
+    /**
+     * §3.2 `animate` (Story 4.1 AC1) — orthogonal to `mode`: pauses/resumes
+     * every registered continuous animation via the SAME `AnimationRegistry`
+     * pause/resume surface every other freeze tier uses. Resuming reuses the
+     * cross-tier-aware discipline `resumeFromOffscreen`/`applyLod` already
+     * establish: an id independently frozen by quality/flow/LOD/offscreen
+     * stays frozen — this switch only ever releases ITS OWN hold.
+     */
+    get animate(): boolean;
+    set animate(value: boolean);
+    /** Story 4.1 AC1/FR16 — no-op while `mode === 'static'`: no rAF loop is ever scheduled (`TimeSource.onTick` is never called). */
+    start(): void;
+    stop(): void;
+    get isRunning(): boolean;
+    /** Story 4.3 Task 2 — the LOD zoom-threshold module's own output; a per-frame-cheap threshold check elsewhere feeds this, `applyLod()` (called every tick, cheap no-op when inactive) enforces the resulting cap. */
+    get lodActive(): boolean;
+    set lodActive(value: boolean);
+    /** §3.2 `debug` — gates render-stats accounting entirely (Task 4: "zero overhead when debug off"). */
+    get debug(): boolean;
+    set debug(value: boolean);
+    /** Registers the 1Hz `render-stats` consumer (`ScadaView` dispatches the CustomEvent from here). Returns an unsubscribe function. */
+    onRenderStats(cb: (stats: RenderStats) => void): () => void;
+    /**
+     * Story 4.4 Task 3 — fires exactly once per real per-element condition
+     * change (`evaluateQuality`'s own transition detection, the SAME edge
+     * `handleConditionTransition`'s pause/resume already reacts to) — never
+     * on every tick, never for an unchanged condition. The ARIA live-region
+     * controller is the one consumer; disambiguating "stale because
+     * disconnected" from "stale because this one tag timed out" is the
+     * CALLER's job (read `connectionState` at callback time), since by this
+     * point both causes have already collapsed into the same `Condition`
+     * value (§4.3's `worstOf`). Single-callback, same convention as
+     * `onRenderStats` — not a multi-listener event bus.
+     */
+    onConditionTransition(cb: (elementId: string, previous: Condition, next: Condition) => void): () => void;
+    get isPausedForOffscreen(): boolean;
+    /**
+     * Story 4.3 Task 3 — off-screen (`IntersectionObserver`) / hidden-tab
+     * (`visibilitychange`) pause: stops the main rAF-driven tick (DOM writes
+     * + animation playback) entirely, but keeps staleness/flow evaluation
+     * running on a `setInterval` fallback (`OFFSCREEN_QUALITY_POLL_MS`) —
+     * §9.4's "control room dashboard with six hidden tabs will melt a
+     * workstation" is about ANIMATION cost, not about the freeze rule
+     * silently going stale itself. `AnimationRegistry.pauseScene()` is the
+     * SAME blunt entering-edge call `tick()`'s own `sceneFrozen` transition
+     * already uses; resuming is deliberately selective (see
+     * `resumeFromOffscreen`), never a blind `resumeScene()`.
+     */
+    pauseForOffscreen(): void;
+    /** Reverses `pauseForOffscreen()` — resumes only animations not ALSO independently frozen by quality/flow/LOD (the same cross-tier-aware pattern `applyFlowInference`/`applyLod` already use), then restarts the normal tick. */
+    resumeFromOffscreen(): void;
+    /** The fallback poll while paused-for-offscreen — staleness/flow only, no DOM writes, no tween/animation playback. */
+    private offscreenTick;
+    /** AC4: every in-flight tween AND data interpolation completes to its target immediately (Story 4.1's static-mode switch depends on this). */
+    snapToTargets(): void;
+    private tick;
+    /**
+     * Story 4.3 Task 2 — enforces the LOD-active animation cap by priority
+     * (`AnimationPriority`'s rank: state-lamps survive longest, waves are
+     * cut first). Cheap no-op when LOD has never engaged (`!lodActiveValue
+     * && lodFrozen.size===0`), so calling it unconditionally every tick is
+     * the "per-frame-cheap threshold check" Dev Notes calls for without
+     * real cost in the common (zoomed-in) case. Reuses the SAME
+     * cross-tier-aware discipline `applyFlowInference` established:
+     * pausing is always safe/idempotent; resuming checks that no OTHER
+     * freeze tier (quality/flow) still wants the element frozen first.
+     */
+    private applyLod;
+    /** Story 4.3 Task 4 — cheap per-tick counters, flushed to `render-stats` at 1Hz. Only ever called while `debugEnabled` (zero overhead off). */
+    private accountFrame;
+    private countDistinctElements;
+    /**
+     * Story 2.6 AC2 — "changing tagPrefix at runtime re-resolves and clears
+     * interpolation state for affected tags (equivalent to a data reset)."
+     * `ValueStore.resolve()` is already always fresh (no caching), so the
+     * ONLY thing that can go stale across a prefix change is THIS scheduler's
+     * own per-registration bookkeeping (`lastWritten`/`lastArrivalTimeSeen`):
+     * left alone, the next tick would tween from the OLD tag's last value
+     * toward the NEW tag's value as if they were the same continuously-
+     * evolving quantity — a meaningless cross-tag blend. Polled once per
+     * tick (not per-registration lookup) via the store's own version
+     * counter — a pull, not a push, keeping the store ignorant of the
+     * scheduler (AD-1's unidirectional pipeline: store never reaches
+     * upstream into the scheduler).
+     */
+    private syncTagPrefixIfChanged;
+    private isElementFrozen;
+    /**
+     * AD-5: the ONLY place staleness/quality is evaluated — the top
+     * precedence tier of the (future, 2.4) visual-state resolver. Covers
+     * every element OR connection with tag-bound handles, whether or not it
+     * has a visual overlay: a pipe's flow-dash animation must freeze on
+     * stale data exactly like a pump's impeller, even though a multi-segment
+     * pipe path has no well-defined bounding box for a dashed-border/hatch
+     * overlay (Story 1.4/1.6 don't give connections one).
+     */
+    private evaluateQuality;
+    /**
+     * Story 2.4 Task 1/2/3 — the explicit⟩inferred tiers of the AD-12
+     * resolver, slotted beneath 1.6's quality tier (`evaluateQuality`, run
+     * just before this on the SAME tick). Per id: only an O(1) cache read
+     * (`FlowInferenceCache.getState`) — the expensive graph pass already
+     * happened, event-driven, elsewhere (AD-4). No `explicit` producer exists
+     * in the product yet (no primitive emits a tag-bound flow state), so it
+     * is always `undefined` here — the seam is real and tested via
+     * `resolveVisualState` directly, ready for a future story to feed it.
+     *
+     * Reuses the EXACT AD-5 pause/resume path (`animationRegistry.pauseAll` /
+     * `resumeAll`) `handleConditionTransition` above already uses for
+     * staleness — same idempotent per-entry `paused` flag, so this can run
+     * independently every tick without fighting the quality tier's own
+     * pause/resume calls (verified idempotent by Story 1.6, see its Debug Log).
+     * Isolation reuses 1.6's EXACT quality overlay (`QualityOverlay.setCondition`,
+     * `'stale'` = the grey desaturate treatment) — never a second desaturation
+     * path — but only while quality itself is `'good'` (AD-12: the quality
+     * tier owns the overlay slot outright whenever it isn't).
+     */
+    private applyFlowInference;
+    private handleConditionTransition;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/scheduler/visual-state-resolver.d.ts

@@ -0,0 +1,31 @@
+import type { Condition } from './quality';
+/**
+ * The AD-12 resolver (Story 2.4, Task 1) — completes the seam Story 1.6
+ * deliberately left open ("explicit-vs-inferred tiers arrive in 2.4").
+ * Fixed precedence, non-negotiable: quality/staleness overlay ⟩ explicit
+ * tag-bound state ⟩ topology-inferred state ⟩ defaults. ONE function, pure,
+ * no store/clock access — every caller (scheduler tick, tests) goes through
+ * this instead of hand-rolling its own if/else precedence chain.
+ *
+ * Quality wins the tier whenever it isn't `'good'` — this mirrors the
+ * spine's literal wording ("quality/staleness overlay" is ONE tier sitting
+ * above explicit/inferred, not split further here). Callers that need to
+ * distinguish "frozen" (stale/bad) from "merely uncertain" for animation
+ * pause/resume purposes do that with their OWN narrower check on the
+ * returned quality value (see `scheduler.ts`'s `isFlowFreezingCondition`) —
+ * this resolver only decides which TIER wins, not what each tier does.
+ */
+export type ResolverTier = 'quality' | 'explicit' | 'inferred' | 'default';
+export interface ResolvedVisualState<S> {
+    tier: ResolverTier;
+    /** The winning value — a `Condition` when `tier === 'quality'`, otherwise an `S`. */
+    value: Condition | S;
+}
+export interface VisualStateResolverInput<S> {
+    quality: Condition;
+    explicit?: S;
+    inferred?: S;
+    defaultValue: S;
+}
+export declare function resolveVisualState<S>(input: VisualStateResolverInput<S>): ResolvedVisualState<S>;
+//# sourceMappingURL=visual-state-resolver.d.ts.map

package/dist/scheduler/visual-state-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-state-resolver.d.ts","sourceRoot":"","sources":["../../src/scheduler/visual-state-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,qFAAqF;IACrF,KAAK,EAAE,SAAS,GAAG,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,YAAY,EAAE,CAAC,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAWhG"}

package/dist/store/value-store.d.ts

@@ -0,0 +1,65 @@
+import type { TagValue, TagValueQuality, ValueWarningDetail } from '../contracts/tag-value';
+import type { TimeSource } from '../contracts/time-source';
+/**
+ * The interpolation buffer (spec §9.3) — "the only unavoidable internal
+ * state," per AD-4. `quality`/`timestamp` beyond the spec's illustrative
+ * 3-field snippet are retained for two concrete, in-scope reasons, not
+ * speculative growth: (1) AD-13 idempotence needs to compare an incoming
+ * TagValue against what's already stored, and (2) Story 1.6's freeze rule
+ * will need per-tag quality without redesigning this store. Tween-progress
+ * bookkeeping (AD-4's separate "tween layer" state bucket) deliberately
+ * does NOT live here — that's the scheduler's job.
+ */
+export interface BufferEntry {
+    previousValue: TagValue['value'];
+    currentValue: TagValue['value'];
+    arrivalTime: number;
+    quality: TagValueQuality;
+    timestamp: number | undefined;
+}
+export declare class ValueStore {
+    private timeSource;
+    private onWarning?;
+    private buffer;
+    private _tagPrefix;
+    private _tagPrefixVersion;
+    constructor(timeSource: TimeSource, onWarning?: ((detail: ValueWarningDetail) => void) | undefined, tagPrefix?: string);
+    /**
+     * §3.2 — "one scene serves multiple identical units" (Story 2.6 AC2).
+     * The instance owns the mapping; the scene's bindings stay portable and
+     * unprefixed. Empty string (the default) is identity — every scene/test
+     * predating this story resolves byte-identical to before. Setting a NEW
+     * value bumps `tagPrefixVersion`, the seam the scheduler polls once per
+     * tick to detect a runtime change and reset its own per-registration
+     * interpolation bookkeeping (equivalent to a data reset for affected
+     * elements — see scheduler.ts).
+     */
+    get tagPrefix(): string;
+    set tagPrefix(prefix: string);
+    /** Read-only change counter for `tagPrefix` — see the property doc above. */
+    get tagPrefixVersion(): number;
+    /** Partial update (§4.2): merges, never clears on absence. Empty array is a no-op. */
+    setValues(values: TagValue[]): void;
+    /** Resets the buffer — the ONLY way values are cleared (never an empty `setValues([])`). */
+    clearValues(): void;
+    /**
+     * Raw, unprefixed buffer accessor — looks up exactly the tag name given,
+     * no mapping applied. This is what `ScadaView.values` enumerates through
+     * (it already has the real/full buffered tag from `tags()`); it must NOT
+     * also apply `tagPrefix`, or a non-empty prefix would double-prepend.
+     */
+    get(tag: string): Readonly<BufferEntry> | undefined;
+    /**
+     * THE single choke point for tag-lookup resolution (Story 2.6 AC2/Task 2):
+     * every binding/threshold/summaryTag/state-map tag a scene declares is
+     * portable and unprefixed; this is where `tagPrefix` gets applied, at
+     * lookup time, for ALL of them alike — none of those call sites need (or
+     * get) their own ad-hoc prefixing logic.
+     */
+    resolve(tag: string): Readonly<BufferEntry> | undefined;
+    get size(): number;
+    tags(): IterableIterator<string>;
+    private ingestOne;
+    private checkTimestamp;
+}
+//# sourceMappingURL=value-store.d.ts.map

package/dist/store/value-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-store.d.ts","sourceRoot":"","sources":["../../src/store/value-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAID,qBAAa,UAAU;IAMnB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,SAAS,CAAC;IANpB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAAK;gBAGpB,UAAU,EAAE,UAAU,EACtB,SAAS,CAAC,GAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,aAAA,EACxD,SAAS,SAAK;IAKhB;;;;;;;;;OASG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,SAAS,CAAC,MAAM,EAAE,MAAM,EAI3B;IAED,6EAA6E;IAC7E,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,sFAAsF;IACtF,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI;IAMnC,4FAA4F;IAC5F,WAAW,IAAI,IAAI;IAInB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,SAAS;IAInD;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,SAAS;IAIvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIhC,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,cAAc;CAoBvB"}