@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/dist/rendering/scene/createScene.js

@@ -0,0 +1,117 @@
+/**
+ * Scene factory — composition, ordered iteration, lifecycle.
+ *
+ * Design notes:
+ * - The layer list is stored in **registration order** in a private array.
+ *   `paintPane` performs a stable sort by `z` at paint time. We do not
+ *   maintain a sorted invariant on the array itself because:
+ *     1. Add/remove must remain O(n), and z is a number, so a sorted
+ *        insert is O(n) anyway.
+ *     2. Stable sort by z gives the documented tie-breaker (registration
+ *        order) "for free" without parallel arrays or registration counters.
+ * - The `layers` signal exposes a snapshot. Every mutation produces a NEW
+ *   array via spread or filter — never mutate the previous value. This is
+ *   the immutability contract framework adapters rely on.
+ * - After `dispose`, every public method becomes a no-op. The `disposed`
+ *   flag is checked at the top of each method; this matches the renderer's
+ *   "dispose freezes" semantic and prevents callers from leaking listeners
+ *   into a torn-down scene.
+ */
+import { createSignal } from '../../foundation/reactivity/signal';
+export function createScene() {
+    // ---- internal state ----------------------------------------------------
+    // Mutable list held outside the signal so that signal.set always receives
+    // a fresh frozen-shape snapshot. We never expose this array directly.
+    let layerList = [];
+    let disposed = false;
+    const layersSignal = createSignal([]);
+    const publish = () => {
+        layersSignal.set([...layerList]);
+    };
+    // ---- public API --------------------------------------------------------
+    const addLayer = (layer) => {
+        if (disposed)
+            return;
+        // Reject duplicate ids silently — protects against double-registration
+        // races where two systems (e.g. an indicator controller + a config
+        // restore) both attempt to add the same layer. The first wins.
+        if (layerList.some((existing) => existing.id === layer.id))
+            return;
+        layerList = [...layerList, layer];
+        publish();
+    };
+    const removeLayer = (id) => {
+        if (disposed)
+            return false;
+        const next = layerList.filter((layer) => layer.id !== id);
+        if (next.length === layerList.length)
+            return false;
+        layerList = next;
+        publish();
+        return true;
+    };
+    const getLayer = (id) => {
+        if (disposed)
+            return null;
+        const hit = layerList.find((layer) => layer.id === id);
+        return hit ?? null;
+    };
+    const setLayerVisibility = (id, visible) => {
+        if (disposed)
+            return false;
+        const layer = layerList.find((l) => l.id === id);
+        if (!layer)
+            return false;
+        // `visible` is a mutable field on the layer (per the interface);
+        // mutating it does not affect the `layers` signal's identity because
+        // subscribers care about membership, not field state. This matches
+        // how chart adapters batch visibility toggles (no re-render storm).
+        layer.visible = visible;
+        return true;
+    };
+    const paintPane = (ctx, roles) => {
+        if (disposed)
+            return;
+        let candidates = layerList.filter((layer) => (layer.paneRole === ctx.paneRole || layer.paneRole === 'global') && layer.visible);
+        if (roles) {
+            candidates = candidates.filter((layer) => roles.includes(layer.role));
+        }
+        // Stable-sort by z. Native Array.prototype.sort is required
+        // by ECMAScript 2019+ to be stable, so equal z values preserve the
+        // surviving registration order from the filter pass.
+        candidates.sort((a, b) => a.z - b.z);
+        for (const layer of candidates) {
+            layer.paint(ctx);
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        // Snapshot first because layer.dispose may attempt further mutations
+        // through a stale reference — we want predictable iteration here.
+        const snapshot = layerList;
+        layerList = [];
+        for (const layer of snapshot) {
+            try {
+                layer.dispose();
+            }
+            catch {
+                // Swallow per-layer dispose errors so one broken layer can't
+                // strand the rest. A logger would go here in production; the
+                // headless core does not own a logger contract yet.
+            }
+        }
+        layersSignal.set([]);
+    };
+    return {
+        layers: layersSignal,
+        addLayer,
+        removeLayer,
+        getLayer,
+        setLayerVisibility,
+        paintPane,
+        dispose,
+    };
+}
+//# sourceMappingURL=createScene.js.map

package/dist/rendering/scene/createScene.js.map

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

package/dist/rendering/scene/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rendering/scene/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAE9E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/rendering/scene/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rendering/scene/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAI1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/rendering/scene/layerRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerRegistry.d.ts","sourceRoot":"","sources":["../../../src/rendering/scene/layerRegistry.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,GAAG,OAAO;IAC7C,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,SAAS,CAAA;IACf,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAAA;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;IACrC;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IACnC,qEAAqE;IACrE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAA;IACxC,4EAA4E;IAC5E,IAAI,IAAI,aAAa,CAAC,YAAY,CAAC,CAAA;CACpC;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAwBnD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAatB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/rendering/scene/layerRegistry.js

@@ -0,0 +1,43 @@
+import { KLineChartError } from '../../errors';
+export function createLayerRegistry() {
+    // Map preserves insertion order, which makes `list()` deterministic —
+    // useful for snapshot tests and for UI surfaces (e.g. an "available
+    // layers" picker) that render the list in registration order.
+    const factories = new Map();
+    const register = (factory) => {
+        if (factories.has(factory.typeId)) {
+            throw new KLineChartError('NOT_REGISTERED', `LayerRegistry: typeId "${factory.typeId}" is already registered`);
+        }
+        factories.set(factory.typeId, factory);
+    };
+    const unregister = (typeId) => factories.delete(typeId);
+    const get = (typeId) => factories.get(typeId) ?? null;
+    const list = () => [...factories.values()];
+    return { register, unregister, get, list };
+}
+/**
+ * Canonical typeIds for the layer types this codebase intends to ship.
+ *
+ * Grouped into:
+ * - "builtin:" — layers backed by existing v0 WebGL renderers (will arrive
+ *   via adapter factories in a follow-up PR).
+ * - "component:" — the three P1 differentiating components from ROADMAP §3.
+ *
+ * These are string constants (not enums) so external code can pass through
+ * string literal types without an enum import — useful for config blobs.
+ */
+export const BUILTIN_LAYER_TYPES = {
+    // Existing in v0 (handled by legacy renderers)
+    CANDLE: 'builtin:candle',
+    VOLUME: 'builtin:volume',
+    INDICATOR_MA: 'builtin:indicator:ma',
+    INDICATOR_BOLL: 'builtin:indicator:boll',
+    DRAWING: 'builtin:drawing',
+    CROSSHAIR: 'builtin:crosshair',
+    GRID: 'builtin:grid',
+    // P1 component layers (controllers from sibling agents will provide factories)
+    VOLUME_PROFILE: 'component:volume-profile',
+    ORDER_BOOK_HEATMAP: 'component:order-book-heatmap',
+    FOOTPRINT: 'component:footprint',
+};
+//# sourceMappingURL=layerRegistry.js.map

package/dist/rendering/scene/layerRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerRegistry.js","sourceRoot":"","sources":["../../../src/rendering/scene/layerRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AA8D9C,MAAM,UAAU,mBAAmB;IACjC,sEAAsE;IACtE,oEAAoE;IACpE,8DAA8D;IAC9D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAA;IAEjD,MAAM,QAAQ,GAAG,CAAC,OAAqB,EAAQ,EAAE;QAC/C,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,0BAA0B,OAAO,CAAC,MAAM,yBAAyB,CAClE,CAAA;QACH,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,CAAC,CAAA;IAED,MAAM,UAAU,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAExE,MAAM,GAAG,GAAG,CAAC,MAAc,EAAuB,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAA;IAElF,MAAM,IAAI,GAAG,GAAgC,EAAE,CAC7C,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAgC,CAAA;IAExD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,+CAA+C;IAC/C,MAAM,EAAE,gBAAgB;IACxB,MAAM,EAAE,gBAAgB;IACxB,YAAY,EAAE,sBAAsB;IACpC,cAAc,EAAE,wBAAwB;IACxC,OAAO,EAAE,iBAAiB;IAC1B,SAAS,EAAE,mBAAmB;IAC9B,IAAI,EAAE,cAAc;IACpB,+EAA+E;IAC/E,cAAc,EAAE,0BAA0B;IAC1C,kBAAkB,EAAE,8BAA8B;IAClD,SAAS,EAAE,qBAAqB;CACxB,CAAA"}

package/dist/rendering/scene/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Scene + Layer type definitions.
+ *
+ * The scene is the level above `render` in core's dependency stack
+ * (see `docs/ROADMAP.md` §0):
+ *
+ *     interaction → store → scene → render
+ *
+ * A `Layer` is a self-contained drawing module — candles, volume bars,
+ * indicator plots, drawings, crosshair, and the P1 component layers
+ * (Volume Profile, Order Book Heatmap, Footprint) all conform to the same
+ * shape. The scene composes layers, owns ordering, and drives per-frame
+ * paint dispatch; it does NOT know which GPU backend is underneath
+ * because `paint()` only sees a `Renderer` reference via `PaintContext`.
+ *
+ * This file is **pure interface** — `createScene.ts` implements `Scene`,
+ * but the types here are zero-runtime so framework adapters and indicator
+ * controllers can compile against them without pulling in the implementation.
+ */
+import type { Signal } from '../../foundation/reactivity/signal';
+import type { Renderer } from '../render/Renderer';
+import type { SurfaceRegion } from '../render/SurfaceBackend';
+/**
+ * Roles let the scene group layers and let other systems target them
+ * (e.g. picking ignores `background`; drawings live above indicators).
+ *
+ * The ordering here is informational, not enforced — z-order is the
+ * authoritative paint order. Roles exist so a follow-up PR can build
+ * features like "hit-test only drawing + component layers" without
+ * peeking at layer ids.
+ */
+export type LayerRole = 'background' | 'primary' | 'indicator' | 'component' | 'drawing' | 'overlay';
+/**
+ * Which pane a layer belongs to. The chart has a main pane (candles +
+ * primary indicators) and zero-or-more sub panes (volume, RSI, MACD).
+ * Layers declare their pane statically; the scene's `paintPane` filters
+ * by this field so each pane's region only sees its own layers.
+ *
+ * NOTE for implementations: this PR uses a flat 'main' / 'sub' split.
+ * If a future iteration needs to address a specific sub-pane (e.g. the
+ * volume pane vs the RSI pane), extend this to a string id (e.g. 'sub:rsi')
+ * — the Layer / Scene contract here does not pre-commit a multi-sub-pane
+ * scheme on purpose.
+ */
+export type PaneRole = 'main' | 'sub' | 'global';
+/**
+ * Stateless paint context handed to each layer per frame.
+ *
+ * The layer reads what it needs from the store via subscriptions
+ * (the store reference is held by the layer itself, set up at construction
+ * time by its factory); this context is the per-frame state.
+ *
+ * Invariants:
+ * - `renderer` MUST already be inside a `beginFrame` / `endFrame` pair
+ *   when paint runs. The scene does not call beginFrame/endFrame itself —
+ *   that's the chart engine's responsibility (see `docs/ROADMAP.md` §0
+ *   for the layered call chain).
+ * - `region` is the surface region for the pane currently being painted.
+ *   Layers MUST treat all coordinates as logical pixels relative to this
+ *   region's origin (the renderer's surface handles DPR scaling).
+ * - `frameNumber` is monotonic across the chart's lifetime; layers can use
+ *   it to drive animations or detect skipped frames.
+ * - `deltaMs` is the wall-clock delta since the previous paint of any pane,
+ *   in milliseconds. May be `0` on the very first frame.
+ */
+export interface PaintContext {
+    renderer: Renderer;
+    region: SurfaceRegion;
+    paneRole: PaneRole;
+    /** The pane id being painted (e.g. 'main', 'RSI_0') — used by sub-pane layers */
+    paneId: string;
+    /** monotonically increasing frame counter for animation/timing */
+    frameNumber: number;
+    /** time elapsed since last frame in ms (for animations) */
+    deltaMs: number;
+}
+/**
+ * A Layer is a self-contained drawing module.
+ *
+ * The contract:
+ * - Pure function `paint()`: given context, produce GPU commands.
+ * - `paint()` MUST NOT mutate any shared state visible to other layers.
+ *   Layer-private state (cached buffers, last-seen frame number) is fine.
+ * - `paint()` runs in scene-defined order; order matters for visual stacking
+ *   (lower z paints first, so higher-z layers visually sit on top).
+ * - `dispose()` MUST release any renderer resources the layer allocated
+ *   (buffers, pipelines). After dispose, the layer is dead — the scene
+ *   removes it and will not call paint again.
+ * - `visible` is a runtime toggle. Invisible layers are skipped entirely
+ *   (no paint() call); the layer keeps its allocated resources so a flip
+ *   back to visible is cheap.
+ */
+export interface Layer {
+    readonly id: string;
+    readonly role: LayerRole;
+    /** which pane this layer belongs to */
+    readonly paneRole: PaneRole;
+    /** lower z first; ties broken by registration order */
+    readonly z: number;
+    /** quick toggle without removing the layer from the scene */
+    visible: boolean;
+    paint(ctx: PaintContext): void;
+    dispose(): void;
+}
+/**
+ * The Scene composes layers and exposes them to subscribers via a Signal.
+ *
+ * Add/remove operations produce a NEW array on the `layers` signal — never
+ * mutate the previous value in place. This guarantees framework adapters
+ * (React, Vue, Angular) using `Object.is` equality detect changes correctly.
+ *
+ * `paintPane` is the only entry point that draws anything; it filters layers
+ * by `paneRole`, drops invisible layers, and dispatches in z order with ties
+ * broken by registration order (FIFO stable sort).
+ *
+ * `dispose` tears down every layer the scene currently owns and freezes the
+ * scene — subsequent add/remove/setLayerVisibility/paintPane calls are silent
+ * no-ops. This matches the renderer's "dispose freezes the object" semantics.
+ */
+export interface Scene {
+    readonly layers: Signal<ReadonlyArray<Layer>>;
+    addLayer(layer: Layer): void;
+    removeLayer(id: string): boolean;
+    getLayer(id: string): Layer | null;
+    setLayerVisibility(id: string, visible: boolean): boolean;
+    /**
+     * paint layers for one pane in z-order, then by registration order
+     * @param roles - if provided, only paint layers whose role is in this list
+     */
+    paintPane(ctx: PaintContext, roles?: ReadonlyArray<LayerRole>): void;
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rendering/scene/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rendering/scene/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,SAAS,GACT,WAAW,GACX,WAAW,GACX,SAAS,GACT,SAAS,CAAA;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,QAAQ,CAAA;IAClB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAEhB,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAA;IAC9B,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;IAE7C,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IAC5B,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAA;IAClC,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;IAEzD;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI,CAAA;IAEpE,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/dist/rendering/scene/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rendering/scene/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/rendering/scheduler/createFrameBudget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Frame budget scheduler — adaptive workload manager.
+ *
+ * Real-time finance charts share a constraint with games and trading
+ * terminals: the renderer has a wall-clock budget per frame (16.67 ms
+ * at 60 fps, 6.94 ms at 144 fps), and exceeding it means dropped frames.
+ * Work that doesn't fit gets deferred to the next frame, but the work
+ * *queue* must not grow without bound — a stale indicator update is
+ * worse than a missed update.
+ *
+ * This module owns the policy. Consumers submit prioritised tasks;
+ * `flush(deadline)` drains as many as fit; the rest stay queued until
+ * the next call. A rolling-average frame-time signal lets components
+ * back off proactively rather than waiting for budget exhaustion.
+ *
+ * Pure data: no requestAnimationFrame, no performance.now() side effects.
+ * The host (browser / Node test / Deno) supplies the clock via a `now`
+ * function. Default: `performance.now()` if available, else `Date.now()`.
+ *
+ *   const budget = createFrameBudget({ targetMs: 16 })
+ *
+ *   // Host's rAF loop:
+ *   function tick(t) {
+ *     budget.beginFrame(t)
+ *     budget.submit({ id: 'indicators', priority: 'high', work: recompute })
+ *     budget.submit({ id: 'labels',     priority: 'low',  work: drawLabels })
+ *     budget.flush(t + budget.targetMs)
+ *     budget.endFrame(performance.now())
+ *     requestAnimationFrame(tick)
+ *   }
+ *
+ *   // Consumers can read the load signal to back off:
+ *   if (budget.recentFrameMs() > 18) skipLowPriorityWork()
+ */
+import { type Signal } from '../../foundation/reactivity/index';
+export type TaskPriority = 'high' | 'medium' | 'low';
+export interface FrameTask {
+    /** Stable id. Duplicate submissions with the same id are coalesced — the
+     *  later submission's `work` and `priority` win. */
+    readonly id: string;
+    readonly priority: TaskPriority;
+    /** Synchronous unit of work. Throws are caught and logged but do NOT
+     *  abort the frame; the task is dropped. */
+    readonly work: () => void;
+}
+export interface FrameBudgetOptions {
+    /** Target frame budget in milliseconds. Default 16 (≈60 fps). */
+    readonly targetMs?: number;
+    /** Rolling window for `recentFrameMs`. Default 60 frames (1 s at 60 fps). */
+    readonly historySize?: number;
+    /**
+     * Clock function. Default: `performance.now()` if available, else
+     * `Date.now()`. Injected for tests so timing is deterministic.
+     */
+    readonly now?: () => number;
+    /**
+     * Maximum queued tasks. Older low/medium tasks are dropped when the
+     * queue exceeds this. Default 256 — high enough that legitimate
+     * workloads never hit it, low enough that runaway producers fail loud.
+     */
+    readonly maxQueueSize?: number;
+}
+export interface FrameBudget {
+    readonly targetMs: number;
+    /** Current rolling-average frame time in ms. */
+    readonly recentFrameMs: Signal<number>;
+    /** Number of tasks currently queued (not yet flushed). */
+    readonly queueDepth: Signal<number>;
+    /** Frames whose work exceeded targetMs (cumulative). */
+    readonly overruns: Signal<number>;
+    /** Mark the start of a frame. Pass `performance.now()` (or test clock). */
+    beginFrame(t: number): void;
+    /** Queue a task. Coalesces on id (later submission wins). */
+    submit(task: FrameTask): void;
+    /**
+     * Drain queued tasks until the deadline (absolute timestamp in the
+     * `now`-clock's scale). Returns the number of tasks completed.
+     *
+     * Tasks run in priority order: all `high` first, then `medium`, then
+     * `low`. Within a priority, FIFO. A task that throws is caught and
+     * dropped; remaining tasks continue.
+     */
+    flush(deadlineAbs: number): number;
+    /** Mark the end of a frame. Updates `recentFrameMs` + overrun count. */
+    endFrame(t: number): void;
+    /** Drop all queued tasks. */
+    clear(): void;
+    dispose(): void;
+}
+export declare function createFrameBudget(opts?: FrameBudgetOptions): FrameBudget;
+//# sourceMappingURL=createFrameBudget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createFrameBudget.d.ts","sourceRoot":"","sources":["../../../src/rendering/scheduler/createFrameBudget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,mCAAmC,CAAA;AAM7E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEpD,MAAM,WAAW,SAAS;IACxB;wDACoD;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B;gDAC4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACnC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAEjC,2EAA2E;IAC3E,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,6DAA6D;IAC7D,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAC7B;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;IAClC,wEAAwE;IACxE,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,6BAA6B;IAC7B,KAAK,IAAI,IAAI,CAAA;IACb,OAAO,IAAI,IAAI,CAAA;CAChB;AAkBD,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,kBAAuB,GAAG,WAAW,CAsM5E"}

package/dist/rendering/scheduler/createFrameBudget.js

@@ -0,0 +1,232 @@
+/**
+ * Frame budget scheduler — adaptive workload manager.
+ *
+ * Real-time finance charts share a constraint with games and trading
+ * terminals: the renderer has a wall-clock budget per frame (16.67 ms
+ * at 60 fps, 6.94 ms at 144 fps), and exceeding it means dropped frames.
+ * Work that doesn't fit gets deferred to the next frame, but the work
+ * *queue* must not grow without bound — a stale indicator update is
+ * worse than a missed update.
+ *
+ * This module owns the policy. Consumers submit prioritised tasks;
+ * `flush(deadline)` drains as many as fit; the rest stay queued until
+ * the next call. A rolling-average frame-time signal lets components
+ * back off proactively rather than waiting for budget exhaustion.
+ *
+ * Pure data: no requestAnimationFrame, no performance.now() side effects.
+ * The host (browser / Node test / Deno) supplies the clock via a `now`
+ * function. Default: `performance.now()` if available, else `Date.now()`.
+ *
+ *   const budget = createFrameBudget({ targetMs: 16 })
+ *
+ *   // Host's rAF loop:
+ *   function tick(t) {
+ *     budget.beginFrame(t)
+ *     budget.submit({ id: 'indicators', priority: 'high', work: recompute })
+ *     budget.submit({ id: 'labels',     priority: 'low',  work: drawLabels })
+ *     budget.flush(t + budget.targetMs)
+ *     budget.endFrame(performance.now())
+ *     requestAnimationFrame(tick)
+ *   }
+ *
+ *   // Consumers can read the load signal to back off:
+ *   if (budget.recentFrameMs() > 18) skipLowPriorityWork()
+ */
+import { KLineChartError } from '../../errors';
+import { createSignal } from '../../foundation/reactivity/index';
+const PRIORITY_ORDER = ['high', 'medium', 'low'];
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function defaultNow() {
+    const perf = globalThis.performance;
+    if (typeof perf?.now === 'function')
+        return perf.now();
+    return Date.now();
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createFrameBudget(opts = {}) {
+    const targetMs = opts.targetMs ?? 16;
+    const historySize = opts.historySize ?? 60;
+    const maxQueueSize = opts.maxQueueSize ?? 256;
+    const now = opts.now ?? defaultNow;
+    if (!(targetMs > 0) || !Number.isFinite(targetMs)) {
+        throw new KLineChartError('INVALID_PARAM', `createFrameBudget: targetMs must be > 0, got ${targetMs}`);
+    }
+    if (!(historySize > 0) || !Number.isInteger(historySize)) {
+        throw new KLineChartError('INVALID_PARAM', `createFrameBudget: historySize must be a positive integer, got ${historySize}`);
+    }
+    if (!(maxQueueSize > 0) || !Number.isInteger(maxQueueSize)) {
+        throw new KLineChartError('INVALID_PARAM', `createFrameBudget: maxQueueSize must be a positive integer, got ${maxQueueSize}`);
+    }
+    const recentFrameMs = createSignal(0);
+    const queueDepth = createSignal(0);
+    const overruns = createSignal(0);
+    // One queue per priority; preserves FIFO inside a tier.
+    const queues = {
+        high: [],
+        medium: [],
+        low: [],
+    };
+    // Reverse lookup so coalesce-by-id is O(1).
+    const byId = new Map();
+    const frameTimes = [];
+    let frameStart = 0;
+    let disposed = false;
+    function publishDepth() {
+        queueDepth.set(queues.high.length + queues.medium.length + queues.low.length);
+    }
+    function totalQueued() {
+        return queues.high.length + queues.medium.length + queues.low.length;
+    }
+    function dropOldestLowOrMedium() {
+        // Prefer dropping low first, then medium. We never drop high.
+        if (queues.low.length > 0) {
+            const dropped = queues.low.shift();
+            byId.delete(dropped.id);
+            return;
+        }
+        if (queues.medium.length > 0) {
+            const dropped = queues.medium.shift();
+            byId.delete(dropped.id);
+            return;
+        }
+        // Only high tasks remain. We don't drop high tasks for queue
+        // pressure; the producer is misbehaving. Surface via overruns
+        // signal so the host can decide.
+    }
+    function submit(task) {
+        if (disposed)
+            return;
+        if (task.id === '' || typeof task.id !== 'string') {
+            throw new KLineChartError('INVALID_PARAM', `FrameBudget.submit: task.id must be a non-empty string`);
+        }
+        // Coalesce by id — replace existing entry.
+        const existing = byId.get(task.id);
+        if (existing !== undefined) {
+            queues[existing.tier][existing.index] = task;
+            // The tier might be changing; if it is, we need to re-bucket.
+            if (existing.tier !== task.priority) {
+                // Mark old slot as a tombstone (we can't splice cheaply mid-iteration
+                // in some paths). The flush loop tolerates undefined entries.
+                ;
+                queues[existing.tier][existing.index] = undefined;
+                queues[task.priority].push(task);
+                byId.set(task.id, {
+                    tier: task.priority,
+                    index: queues[task.priority].length - 1,
+                });
+            }
+            publishDepth();
+            return;
+        }
+        // Enforce maxQueueSize by dropping older low/medium first.
+        while (totalQueued() >= maxQueueSize) {
+            dropOldestLowOrMedium();
+            // If only high tasks left and we're still at the cap, bail.
+            if (totalQueued() >= maxQueueSize && queues.low.length === 0 && queues.medium.length === 0) {
+                break;
+            }
+        }
+        queues[task.priority].push(task);
+        byId.set(task.id, {
+            tier: task.priority,
+            index: queues[task.priority].length - 1,
+        });
+        publishDepth();
+    }
+    function flush(deadlineAbs) {
+        if (disposed)
+            return 0;
+        let completed = 0;
+        for (const tier of PRIORITY_ORDER) {
+            const q = queues[tier];
+            while (q.length > 0) {
+                if (now() >= deadlineAbs) {
+                    // Compact the tier so later flushes skip tombstones.
+                    queues[tier] = q.filter((t) => t !== undefined);
+                    // Rebuild byId indices for this tier.
+                    for (let i = 0; i < queues[tier].length; i++) {
+                        const t = queues[tier][i];
+                        byId.set(t.id, { tier, index: i });
+                    }
+                    publishDepth();
+                    return completed;
+                }
+                const task = q.shift();
+                if (task === undefined)
+                    continue; // tombstone
+                byId.delete(task.id);
+                try {
+                    task.work();
+                    completed++;
+                }
+                catch {
+                    // Task threw; drop it. We don't propagate — one
+                    // bad task must not poison the frame.
+                }
+            }
+        }
+        publishDepth();
+        return completed;
+    }
+    function beginFrame(t) {
+        if (disposed)
+            return;
+        if (!Number.isFinite(t)) {
+            throw new KLineChartError('INVALID_PARAM', `FrameBudget.beginFrame: t must be finite, got ${t}`);
+        }
+        frameStart = t;
+    }
+    function endFrame(t) {
+        if (disposed)
+            return;
+        if (!Number.isFinite(t)) {
+            throw new KLineChartError('INVALID_PARAM', `FrameBudget.endFrame: t must be finite, got ${t}`);
+        }
+        const dur = Math.max(0, t - frameStart);
+        frameTimes.push(dur);
+        while (frameTimes.length > historySize)
+            frameTimes.shift();
+        let sum = 0;
+        for (const v of frameTimes)
+            sum += v;
+        recentFrameMs.set(sum / frameTimes.length);
+        if (dur > targetMs)
+            overruns.set(overruns.peek() + 1);
+    }
+    function clear() {
+        if (disposed)
+            return;
+        queues.high = [];
+        queues.medium = [];
+        queues.low = [];
+        byId.clear();
+        publishDepth();
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        queues.high = [];
+        queues.medium = [];
+        queues.low = [];
+        byId.clear();
+        frameTimes.length = 0;
+    }
+    return {
+        targetMs,
+        recentFrameMs,
+        queueDepth,
+        overruns,
+        beginFrame,
+        submit,
+        flush,
+        endFrame,
+        clear,
+        dispose,
+    };
+}
+//# sourceMappingURL=createFrameBudget.js.map