@invinite-org/chartlang-adapter-kit 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @invinite-org/chartlang-adapter-kit
 
+## 1.5.0
+
+### Minor Changes
+
+- 24946e4: Add a library-agnostic pan/zoom interaction layer under `src/interaction/`,
+  exported from the root entry. `createViewController()` holds a user x-window +
+  `userInteracted` flag with pure `resolveXWindow` / `zoomAt` / `panBy` / `reset`
+  transforms (auto-follow live data until the first gesture, then hold the held
+  window, clamped to the data bounds — zoom-out cannot exceed all-data).
+  `yRangeInWindow(candidates, win)` is the shared "auto-fit the price scale to
+  the visible window" helper. `attachInteraction(el, handlers)` wires
+  wheel→zoom / drag→pan / dblclick→reset onto a DOM element (the listener
+  plumbing is the only DOM-bound part; the decision cores `onWheelCore` /
+  `onDragCore` / `onDblCore` are pure). The four example adapters (canvas2d,
+  konva, uplot, echarts) consume these for consistent zoom + drag + auto-fit.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -10,5 +10,7 @@ export type { MockCandleSourceMode, MockCandleSourceOpts } from "./mocks/index.j
 export { BufferingAdapter, PassThroughAdapter } from "./base/index.js";
 export { decomposeDrawing, priceToY, timeToX, worldPointToPixel } from "./geometry/index.js";
 export type { DrawPrimitive, FillStyle, Point2, StrokeStyle, Viewport, } from "./geometry/index.js";
+export { attachInteraction, createViewController, onDblCore, onDragCore, onWheelCore, yRangeInWindow, } from "./interaction/index.js";
+export type { InteractionHandlers, ViewController, ViewControllerOpts, WindowYInput, XWindow, } from "./interaction/index.js";
 export type { Adapter, AdapterSymInfo, AlertChannel, AlertConditionEmission, AlertEmission, Capabilities, CandleEvent, DiagnosticCode, DrawingCounts, DrawingEmission, DrawingKind, InputKind, LogEmission, PlotEmission, PlotKind, PlotOverride, PlotSlotDescriptor, PlotStyle, RunnerEmissions, RuntimeDiagnostic, SymInfoField, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,YAAY,EACR,aAAa,EACb,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,GACX,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACR,OAAO,EACP,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,YAAY,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,YAAY,EACR,aAAa,EACb,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,GACX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,GACjB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACR,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,OAAO,GACV,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACR,OAAO,EACP,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,YAAY,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -7,4 +7,5 @@ export { decodeDrawing, validateEmission } from "./validation/index.js";
 export { mockCandleSource } from "./mocks/index.js";
 export { BufferingAdapter, PassThroughAdapter } from "./base/index.js";
 export { decomposeDrawing, priceToY, timeToX, worldPointToPixel } from "./geometry/index.js";
+export { attachInteraction, createViewController, onDblCore, onDragCore, onWheelCore, yRangeInWindow, } from "./interaction/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nexport { KIND_BUCKET, bucketFor } from \"@invinite-org/chartlang-core\";\nexport type { DrawingBucket, DrawingState } from \"@invinite-org/chartlang-core\";\nexport { defineAdapter } from \"./defineAdapter.js\";\nexport type { DefineAdapterOpts } from \"./defineAdapter.js\";\nexport { PHASE_5_PLOT_KINDS, capabilities } from \"./capabilities/index.js\";\nexport { decodeDrawing, validateEmission } from \"./validation/index.js\";\nexport type { ValidationFail, ValidationOk, ValidationResult } from \"./validation/index.js\";\nexport { mockCandleSource } from \"./mocks/index.js\";\nexport type { MockCandleSourceMode, MockCandleSourceOpts } from \"./mocks/index.js\";\nexport { BufferingAdapter, PassThroughAdapter } from \"./base/index.js\";\nexport { decomposeDrawing, priceToY, timeToX, worldPointToPixel } from \"./geometry/index.js\";\nexport type {\n    DrawPrimitive,\n    FillStyle,\n    Point2,\n    StrokeStyle,\n    Viewport,\n} from \"./geometry/index.js\";\nexport type {\n    Adapter,\n    AdapterSymInfo,\n    AlertChannel,\n    AlertConditionEmission,\n    AlertEmission,\n    Capabilities,\n    CandleEvent,\n    DiagnosticCode,\n    DrawingCounts,\n    DrawingEmission,\n    DrawingKind,\n    InputKind,\n    LogEmission,\n    PlotEmission,\n    PlotKind,\n    PlotOverride,\n    PlotSlotDescriptor,\n    PlotStyle,\n    RunnerEmissions,\n    RuntimeDiagnostic,\n    SymInfoField,\n} from \"./types.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAQ7F,OAAO,EACH,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,GACjB,MAAM,wBAAwB,CAAC","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nexport { KIND_BUCKET, bucketFor } from \"@invinite-org/chartlang-core\";\nexport type { DrawingBucket, DrawingState } from \"@invinite-org/chartlang-core\";\nexport { defineAdapter } from \"./defineAdapter.js\";\nexport type { DefineAdapterOpts } from \"./defineAdapter.js\";\nexport { PHASE_5_PLOT_KINDS, capabilities } from \"./capabilities/index.js\";\nexport { decodeDrawing, validateEmission } from \"./validation/index.js\";\nexport type { ValidationFail, ValidationOk, ValidationResult } from \"./validation/index.js\";\nexport { mockCandleSource } from \"./mocks/index.js\";\nexport type { MockCandleSourceMode, MockCandleSourceOpts } from \"./mocks/index.js\";\nexport { BufferingAdapter, PassThroughAdapter } from \"./base/index.js\";\nexport { decomposeDrawing, priceToY, timeToX, worldPointToPixel } from \"./geometry/index.js\";\nexport type {\n    DrawPrimitive,\n    FillStyle,\n    Point2,\n    StrokeStyle,\n    Viewport,\n} from \"./geometry/index.js\";\nexport {\n    attachInteraction,\n    createViewController,\n    onDblCore,\n    onDragCore,\n    onWheelCore,\n    yRangeInWindow,\n} from \"./interaction/index.js\";\nexport type {\n    InteractionHandlers,\n    ViewController,\n    ViewControllerOpts,\n    WindowYInput,\n    XWindow,\n} from \"./interaction/index.js\";\nexport type {\n    Adapter,\n    AdapterSymInfo,\n    AlertChannel,\n    AlertConditionEmission,\n    AlertEmission,\n    Capabilities,\n    CandleEvent,\n    DiagnosticCode,\n    DrawingCounts,\n    DrawingEmission,\n    DrawingKind,\n    InputKind,\n    LogEmission,\n    PlotEmission,\n    PlotKind,\n    PlotOverride,\n    PlotSlotDescriptor,\n    PlotStyle,\n    RunnerEmissions,\n    RuntimeDiagnostic,\n    SymInfoField,\n} from \"./types.js\";\n"]}

package/dist/interaction/domWiring.d.ts

@@ -0,0 +1,90 @@
+import type { ViewController } from "./viewController.js";
+/**
+ * The per-frame projection + data context {@link attachInteraction} needs
+ * to translate pixel gestures into world-x transforms. The adapter supplies
+ * these closing over its latest overlay `Viewport`, so the math always uses
+ * the current frame's scale.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const view: import("./viewController.js").ViewController;
+ *     const h: InteractionHandlers = {
+ *         controller: view,
+ *         pxToWorldX: (px) => px,
+ *         worldXPerPx: () => 1,
+ *         dataBounds: () => ({ xMin: 0, xMax: 100 }),
+ *         requestRender: () => {},
+ *     };
+ *     void h;
+ */
+export type InteractionHandlers = {
+    /** The controller whose window the gestures mutate. */
+    readonly controller: ViewController;
+    /** Map a plot-area pixel x to a world x for the current frame. */
+    readonly pxToWorldX: (px: number) => number;
+    /** World-x units per pixel for the current frame (pan delta scale). */
+    readonly worldXPerPx: () => number;
+    /** The current data x extent (grows as bars stream in). */
+    readonly dataBounds: () => {
+        readonly xMin: number;
+        readonly xMax: number;
+    };
+    /** Re-render the adapter after a gesture mutates the window. */
+    readonly requestRender: () => void;
+    /** Override the wheel zoom sensitivity (default {@link DEFAULT_ZOOM_STEP}). */
+    readonly zoomStep?: number;
+};
+/**
+ * Apply one wheel notch: zoom the controller about the world-x under the
+ * cursor, then request a render. Pure on `(offsetX, deltaY)` so it is unit
+ * tested without a DOM event.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onWheelCore(h, 50, -120); // zoom in about pixel x=50
+ */
+export declare function onWheelCore(h: InteractionHandlers, offsetX: number, deltaY: number): void;
+/**
+ * Apply one drag step: pan the controller by the pixel delta converted to
+ * world x (dragging right reveals earlier data), then request a render.
+ * Pure on `dxPx`.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onDragCore(h, 12); // pan left by 12 px
+ */
+export declare function onDragCore(h: InteractionHandlers, dxPx: number): void;
+/**
+ * Apply a double-click: reset the controller to auto-follow, then request a
+ * render.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onDblCore(h);
+ */
+export declare function onDblCore(h: InteractionHandlers): void;
+/**
+ * Wire wheel-zoom, drag-pan, and double-click-reset on `el`, driving the
+ * supplied {@link InteractionHandlers}. Returns a detach function that
+ * removes every listener (call it from the adapter's `dispose`). The
+ * `addEventListener` plumbing is the only DOM-bound part; the decision
+ * logic lives in {@link onWheelCore} / {@link onDragCore} / {@link
+ * onDblCore}, which are unit tested directly.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const el: HTMLElement;
+ *     declare const h: InteractionHandlers;
+ *     const detach = attachInteraction(el, h);
+ *     detach();
+ */
+export declare function attachInteraction(el: HTMLElement, h: InteractionHandlers): () => void;
+//# sourceMappingURL=domWiring.d.ts.map

package/dist/interaction/domWiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domWiring.d.ts","sourceRoot":"","sources":["../../src/interaction/domWiring.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5C,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAC;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAGtD;AAED;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAwCrF"}

package/dist/interaction/domWiring.js

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+// Wheel notch → zoom factor sensitivity. A positive `deltaY` (scroll down)
+// yields a factor > 1 (zoom out); negative (scroll up) yields < 1 (zoom in).
+// `Math.exp` keeps both directions symmetric, so zoom-out always exists —
+// the bug the native-default drag-zoom-in lacked.
+const DEFAULT_ZOOM_STEP = 0.0015;
+/**
+ * Apply one wheel notch: zoom the controller about the world-x under the
+ * cursor, then request a render. Pure on `(offsetX, deltaY)` so it is unit
+ * tested without a DOM event.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onWheelCore(h, 50, -120); // zoom in about pixel x=50
+ */
+export function onWheelCore(h, offsetX, deltaY) {
+    const factor = Math.exp(deltaY * (h.zoomStep ?? DEFAULT_ZOOM_STEP));
+    const { xMin, xMax } = h.dataBounds();
+    h.controller.zoomAt(h.pxToWorldX(offsetX), factor, xMin, xMax);
+    h.requestRender();
+}
+/**
+ * Apply one drag step: pan the controller by the pixel delta converted to
+ * world x (dragging right reveals earlier data), then request a render.
+ * Pure on `dxPx`.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onDragCore(h, 12); // pan left by 12 px
+ */
+export function onDragCore(h, dxPx) {
+    const { xMin, xMax } = h.dataBounds();
+    h.controller.panBy(-dxPx * h.worldXPerPx(), xMin, xMax);
+    h.requestRender();
+}
+/**
+ * Apply a double-click: reset the controller to auto-follow, then request a
+ * render.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const h: InteractionHandlers;
+ *     onDblCore(h);
+ */
+export function onDblCore(h) {
+    h.controller.reset();
+    h.requestRender();
+}
+/**
+ * Wire wheel-zoom, drag-pan, and double-click-reset on `el`, driving the
+ * supplied {@link InteractionHandlers}. Returns a detach function that
+ * removes every listener (call it from the adapter's `dispose`). The
+ * `addEventListener` plumbing is the only DOM-bound part; the decision
+ * logic lives in {@link onWheelCore} / {@link onDragCore} / {@link
+ * onDblCore}, which are unit tested directly.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     declare const el: HTMLElement;
+ *     declare const h: InteractionHandlers;
+ *     const detach = attachInteraction(el, h);
+ *     detach();
+ */
+/* v8 ignore start -- DOM event plumbing; the pure cores above carry the coverage */
+export function attachInteraction(el, h) {
+    let dragging = false;
+    let lastX = 0;
+    const onWheel = (e) => {
+        e.preventDefault();
+        onWheelCore(h, e.offsetX, e.deltaY);
+    };
+    const onPointerDown = (e) => {
+        dragging = true;
+        lastX = e.clientX;
+        el.setPointerCapture(e.pointerId);
+    };
+    const onPointerMove = (e) => {
+        if (!dragging)
+            return;
+        const dx = e.clientX - lastX;
+        lastX = e.clientX;
+        onDragCore(h, dx);
+    };
+    const onPointerUp = (e) => {
+        dragging = false;
+        if (el.hasPointerCapture(e.pointerId))
+            el.releasePointerCapture(e.pointerId);
+    };
+    const onDblClick = () => {
+        onDblCore(h);
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    el.addEventListener("pointerdown", onPointerDown);
+    el.addEventListener("pointermove", onPointerMove);
+    el.addEventListener("pointerup", onPointerUp);
+    el.addEventListener("dblclick", onDblClick);
+    return () => {
+        el.removeEventListener("wheel", onWheel);
+        el.removeEventListener("pointerdown", onPointerDown);
+        el.removeEventListener("pointermove", onPointerMove);
+        el.removeEventListener("pointerup", onPointerUp);
+        el.removeEventListener("dblclick", onDblClick);
+    };
+}
+/* v8 ignore stop */
+//# sourceMappingURL=domWiring.js.map

package/dist/interaction/domWiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domWiring.js","sourceRoot":"","sources":["../../src/interaction/domWiring.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nimport type { ViewController } from \"./viewController.js\";\n\n// Wheel notch → zoom factor sensitivity. A positive `deltaY` (scroll down)\n// yields a factor > 1 (zoom out); negative (scroll up) yields < 1 (zoom in).\n// `Math.exp` keeps both directions symmetric, so zoom-out always exists —\n// the bug the native-default drag-zoom-in lacked.\nconst DEFAULT_ZOOM_STEP = 0.0015;\n\n/**\n * The per-frame projection + data context {@link attachInteraction} needs\n * to translate pixel gestures into world-x transforms. The adapter supplies\n * these closing over its latest overlay `Viewport`, so the math always uses\n * the current frame's scale.\n *\n * @since 1.6\n * @stable\n * @example\n *     declare const view: import(\"./viewController.js\").ViewController;\n *     const h: InteractionHandlers = {\n *         controller: view,\n *         pxToWorldX: (px) => px,\n *         worldXPerPx: () => 1,\n *         dataBounds: () => ({ xMin: 0, xMax: 100 }),\n *         requestRender: () => {},\n *     };\n *     void h;\n */\nexport type InteractionHandlers = {\n    /** The controller whose window the gestures mutate. */\n    readonly controller: ViewController;\n    /** Map a plot-area pixel x to a world x for the current frame. */\n    readonly pxToWorldX: (px: number) => number;\n    /** World-x units per pixel for the current frame (pan delta scale). */\n    readonly worldXPerPx: () => number;\n    /** The current data x extent (grows as bars stream in). */\n    readonly dataBounds: () => { readonly xMin: number; readonly xMax: number };\n    /** Re-render the adapter after a gesture mutates the window. */\n    readonly requestRender: () => void;\n    /** Override the wheel zoom sensitivity (default {@link DEFAULT_ZOOM_STEP}). */\n    readonly zoomStep?: number;\n};\n\n/**\n * Apply one wheel notch: zoom the controller about the world-x under the\n * cursor, then request a render. Pure on `(offsetX, deltaY)` so it is unit\n * tested without a DOM event.\n *\n * @since 1.6\n * @stable\n * @example\n *     declare const h: InteractionHandlers;\n *     onWheelCore(h, 50, -120); // zoom in about pixel x=50\n */\nexport function onWheelCore(h: InteractionHandlers, offsetX: number, deltaY: number): void {\n    const factor = Math.exp(deltaY * (h.zoomStep ?? DEFAULT_ZOOM_STEP));\n    const { xMin, xMax } = h.dataBounds();\n    h.controller.zoomAt(h.pxToWorldX(offsetX), factor, xMin, xMax);\n    h.requestRender();\n}\n\n/**\n * Apply one drag step: pan the controller by the pixel delta converted to\n * world x (dragging right reveals earlier data), then request a render.\n * Pure on `dxPx`.\n *\n * @since 1.6\n * @stable\n * @example\n *     declare const h: InteractionHandlers;\n *     onDragCore(h, 12); // pan left by 12 px\n */\nexport function onDragCore(h: InteractionHandlers, dxPx: number): void {\n    const { xMin, xMax } = h.dataBounds();\n    h.controller.panBy(-dxPx * h.worldXPerPx(), xMin, xMax);\n    h.requestRender();\n}\n\n/**\n * Apply a double-click: reset the controller to auto-follow, then request a\n * render.\n *\n * @since 1.6\n * @stable\n * @example\n *     declare const h: InteractionHandlers;\n *     onDblCore(h);\n */\nexport function onDblCore(h: InteractionHandlers): void {\n    h.controller.reset();\n    h.requestRender();\n}\n\n/**\n * Wire wheel-zoom, drag-pan, and double-click-reset on `el`, driving the\n * supplied {@link InteractionHandlers}. Returns a detach function that\n * removes every listener (call it from the adapter's `dispose`). The\n * `addEventListener` plumbing is the only DOM-bound part; the decision\n * logic lives in {@link onWheelCore} / {@link onDragCore} / {@link\n * onDblCore}, which are unit tested directly.\n *\n * @since 1.6\n * @stable\n * @example\n *     declare const el: HTMLElement;\n *     declare const h: InteractionHandlers;\n *     const detach = attachInteraction(el, h);\n *     detach();\n */\n/* v8 ignore start -- DOM event plumbing; the pure cores above carry the coverage */\nexport function attachInteraction(el: HTMLElement, h: InteractionHandlers): () => void {\n    let dragging = false;\n    let lastX = 0;\n\n    const onWheel = (e: WheelEvent): void => {\n        e.preventDefault();\n        onWheelCore(h, e.offsetX, e.deltaY);\n    };\n    const onPointerDown = (e: PointerEvent): void => {\n        dragging = true;\n        lastX = e.clientX;\n        el.setPointerCapture(e.pointerId);\n    };\n    const onPointerMove = (e: PointerEvent): void => {\n        if (!dragging) return;\n        const dx = e.clientX - lastX;\n        lastX = e.clientX;\n        onDragCore(h, dx);\n    };\n    const onPointerUp = (e: PointerEvent): void => {\n        dragging = false;\n        if (el.hasPointerCapture(e.pointerId)) el.releasePointerCapture(e.pointerId);\n    };\n    const onDblClick = (): void => {\n        onDblCore(h);\n    };\n\n    el.addEventListener(\"wheel\", onWheel, { passive: false });\n    el.addEventListener(\"pointerdown\", onPointerDown);\n    el.addEventListener(\"pointermove\", onPointerMove);\n    el.addEventListener(\"pointerup\", onPointerUp);\n    el.addEventListener(\"dblclick\", onDblClick);\n\n    return (): void => {\n        el.removeEventListener(\"wheel\", onWheel);\n        el.removeEventListener(\"pointerdown\", onPointerDown);\n        el.removeEventListener(\"pointermove\", onPointerMove);\n        el.removeEventListener(\"pointerup\", onPointerUp);\n        el.removeEventListener(\"dblclick\", onDblClick);\n    };\n}\n/* v8 ignore stop */\n"]}

package/dist/interaction/index.d.ts

@@ -0,0 +1,5 @@
+export { createViewController, yRangeInWindow } from "./viewController.js";
+export type { ViewController, ViewControllerOpts, WindowYInput, XWindow, } from "./viewController.js";
+export { attachInteraction, onDblCore, onDragCore, onWheelCore } from "./domWiring.js";
+export type { InteractionHandlers } from "./domWiring.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/interaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EACR,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,OAAO,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/interaction/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+export { createViewController, yRangeInWindow } from "./viewController.js";
+export { attachInteraction, onDblCore, onDragCore, onWheelCore } from "./domWiring.js";
+//# sourceMappingURL=index.js.map

package/dist/interaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO3E,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\nexport { createViewController, yRangeInWindow } from \"./viewController.js\";\nexport type {\n    ViewController,\n    ViewControllerOpts,\n    WindowYInput,\n    XWindow,\n} from \"./viewController.js\";\nexport { attachInteraction, onDblCore, onDragCore, onWheelCore } from \"./domWiring.js\";\nexport type { InteractionHandlers } from \"./domWiring.js\";\n"]}

package/dist/interaction/viewController.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A visible window into the world x axis (bar times in UTC ms). The two
+ * self-scaled adapters (canvas2d, konva) resolve one per frame from a
+ * {@link ViewController} and feed `xMin`/`xMax` into their `Viewport`.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const win: XWindow = { xMin: 0, xMax: 100 };
+ *     void win;
+ */
+export type XWindow = {
+    readonly xMin: number;
+    readonly xMax: number;
+};
+/**
+ * Construction options for {@link createViewController}. `minSpan` is the
+ * smallest world-x span a zoom-in can reach (so the window never collapses
+ * to a point); `maxSpanFactor` is the largest span a zoom-out can reach as
+ * a multiple of the current data span (default `1` ⇒ cannot zoom out past
+ * "all data visible").
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const opts: ViewControllerOpts = { minSpan: 1, maxSpanFactor: 1 };
+ *     void opts;
+ */
+export type ViewControllerOpts = {
+    readonly minSpan?: number;
+    readonly maxSpanFactor?: number;
+};
+/**
+ * Stateful, library-agnostic pan/zoom controller for an adapter that
+ * computes its own x scale every frame. It holds a user x-window plus a
+ * `userInteracted` flag: until the user wheels or drags, {@link
+ * ViewController.resolveXWindow} returns the full data range (auto-follow
+ * live bars); after the first interaction it returns the held window
+ * (re-clamped as data grows), so live frames stop snapping the view back.
+ *
+ * All transforms are pure functions of the current state + the supplied
+ * data bounds — there is no DOM or library coupling. The example adapters
+ * wire DOM events to {@link ViewController.zoomAt} / {@link
+ * ViewController.panBy} / {@link ViewController.reset} via {@link
+ * attachInteraction}.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const view = createViewController();
+ *     view.resolveXWindow(0, 100); // { xMin: 0, xMax: 100 } (auto-follow)
+ *     view.panBy(10, 0, 100);
+ *     view.userInteracted; // true
+ */
+export type ViewController = {
+    /** `true` once the user has zoomed or panned (auto-follow is paused). */
+    readonly userInteracted: boolean;
+    /**
+     * The x-window to render this frame: `[dataXMin, dataXMax]` while not
+     * interacted (auto-follow), else the held window clamped into the
+     * current data bounds.
+     */
+    resolveXWindow(dataXMin: number, dataXMax: number): XWindow;
+    /** Zoom by `factor` (`<1` in, `>1` out) about a world-x pivot. */
+    zoomAt(pivotX: number, factor: number, dataXMin: number, dataXMax: number): void;
+    /** Pan the window by a signed world-x delta. */
+    panBy(deltaWorldX: number, dataXMin: number, dataXMax: number): void;
+    /** Clear the held window + flag so the view auto-follows again. */
+    reset(): void;
+};
+/**
+ * Build a {@link ViewController}. Pass `opts` to tune the zoom-in floor
+ * (`minSpan`) and zoom-out ceiling (`maxSpanFactor`); both default to a
+ * "1 ms floor, all-data ceiling" policy.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const view = createViewController({ minSpan: 2, maxSpanFactor: 1 });
+ *     view.zoomAt(50, 0.5, 0, 100); // zoom in 2× about x=50
+ *     void view.resolveXWindow(0, 100);
+ */
+export declare function createViewController(opts?: ViewControllerOpts): ViewController;
+/**
+ * One candidate row for {@link yRangeInWindow}: a world `x` (bar time) plus
+ * the low / high values to fold into the y range when `x` is inside the
+ * window. Bars pass `{ x: time, lo: low, hi: high }`; a scalar series point
+ * passes `lo === hi === value`.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const c: WindowYInput = { x: 10, lo: 99, hi: 101 };
+ *     void c;
+ */
+export type WindowYInput = {
+    readonly x: number;
+    readonly lo: number;
+    readonly hi: number;
+};
+/**
+ * Fold the y range of every candidate whose `x` falls inside `win` — the
+ * shared "auto-fit the price scale to the visible window" helper (matching
+ * lightweight-charts' auto price scale). Non-finite `lo`/`hi` rows are
+ * skipped. Returns `undefined` when no finite in-window candidate is seen,
+ * so the caller keeps its own degenerate-range fallback. Horizontal lines
+ * (no `x`) are folded in by the caller, not here.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const r = yRangeInWindow([{ x: 5, lo: 1, hi: 3 }], { xMin: 0, xMax: 10 });
+ *     // r === { yMin: 1, yMax: 3 }
+ *     void r;
+ */
+export declare function yRangeInWindow(candidates: Iterable<WindowYInput>, win: XWindow): {
+    readonly yMin: number;
+    readonly yMax: number;
+} | undefined;
+//# sourceMappingURL=viewController.d.ts.map

package/dist/interaction/viewController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewController.d.ts","sourceRoot":"","sources":["../../src/interaction/viewController.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5D,kEAAkE;IAClE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjF,gDAAgD;IAChD,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAC;CACjB,CAAC;AAsCF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAgD9E;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC1B,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,EAClC,GAAG,EAAE,OAAO,GACb;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAW9D"}

package/dist/interaction/viewController.js

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+const DEFAULT_MIN_SPAN = 1;
+const DEFAULT_MAX_SPAN_FACTOR = 1;
+// Clamp a candidate window: bound its span to [minSpan, maxSpan] (maxSpan =
+// dataSpan * maxSpanFactor), then shift it to sit inside [dataMin, dataMax]
+// when it fits, or pin it to the full data range when it is at least as wide
+// as the data. The single clamp shared by zoom / pan / resolve.
+function clampWindow(win, dataMin, dataMax, minSpan, maxSpanFactor) {
+    const dataSpan = Math.max(0, dataMax - dataMin);
+    const maxSpan = dataSpan * maxSpanFactor;
+    let span = win.xMax - win.xMin;
+    if (maxSpan > 0 && span > maxSpan)
+        span = maxSpan;
+    if (span < minSpan)
+        span = minSpan;
+    const center = (win.xMin + win.xMax) / 2;
+    let xMin = center - span / 2;
+    let xMax = center + span / 2;
+    if (span <= dataSpan) {
+        if (xMin < dataMin) {
+            xMax += dataMin - xMin;
+            xMin = dataMin;
+        }
+        if (xMax > dataMax) {
+            xMin -= xMax - dataMax;
+            xMax = dataMax;
+        }
+        return { xMin, xMax };
+    }
+    return { xMin: dataMin, xMax: dataMax };
+}
+/**
+ * Build a {@link ViewController}. Pass `opts` to tune the zoom-in floor
+ * (`minSpan`) and zoom-out ceiling (`maxSpanFactor`); both default to a
+ * "1 ms floor, all-data ceiling" policy.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const view = createViewController({ minSpan: 2, maxSpanFactor: 1 });
+ *     view.zoomAt(50, 0.5, 0, 100); // zoom in 2× about x=50
+ *     void view.resolveXWindow(0, 100);
+ */
+export function createViewController(opts) {
+    const minSpan = opts?.minSpan ?? DEFAULT_MIN_SPAN;
+    const maxSpanFactor = opts?.maxSpanFactor ?? DEFAULT_MAX_SPAN_FACTOR;
+    let held;
+    let interacted = false;
+    const base = (dataMin, dataMax) => held ?? { xMin: dataMin, xMax: dataMax };
+    return {
+        get userInteracted() {
+            return interacted;
+        },
+        resolveXWindow(dataMin, dataMax) {
+            if (!interacted || held === undefined)
+                return { xMin: dataMin, xMax: dataMax };
+            return clampWindow(held, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        zoomAt(pivotX, factor, dataMin, dataMax) {
+            interacted = true;
+            const b = base(dataMin, dataMax);
+            const span = b.xMax - b.xMin;
+            const frac = span === 0 ? 0.5 : (pivotX - b.xMin) / span;
+            const newSpan = span * factor;
+            const xMin = pivotX - frac * newSpan;
+            held = clampWindow({ xMin, xMax: xMin + newSpan }, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        panBy(deltaWorldX, dataMin, dataMax) {
+            interacted = true;
+            const b = base(dataMin, dataMax);
+            held = clampWindow({ xMin: b.xMin + deltaWorldX, xMax: b.xMax + deltaWorldX }, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        reset() {
+            held = undefined;
+            interacted = false;
+        },
+    };
+}
+/**
+ * Fold the y range of every candidate whose `x` falls inside `win` — the
+ * shared "auto-fit the price scale to the visible window" helper (matching
+ * lightweight-charts' auto price scale). Non-finite `lo`/`hi` rows are
+ * skipped. Returns `undefined` when no finite in-window candidate is seen,
+ * so the caller keeps its own degenerate-range fallback. Horizontal lines
+ * (no `x`) are folded in by the caller, not here.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const r = yRangeInWindow([{ x: 5, lo: 1, hi: 3 }], { xMin: 0, xMax: 10 });
+ *     // r === { yMin: 1, yMax: 3 }
+ *     void r;
+ */
+export function yRangeInWindow(candidates, win) {
+    let yMin = Number.POSITIVE_INFINITY;
+    let yMax = Number.NEGATIVE_INFINITY;
+    for (const c of candidates) {
+        if (c.x < win.xMin || c.x > win.xMax)
+            continue;
+        if (!Number.isFinite(c.lo) || !Number.isFinite(c.hi))
+            continue;
+        if (c.lo < yMin)
+            yMin = c.lo;
+        if (c.hi > yMax)
+            yMax = c.hi;
+    }
+    if (!Number.isFinite(yMin) || !Number.isFinite(yMax))
+        return undefined;
+    return { yMin, yMax };
+}
+//# sourceMappingURL=viewController.js.map

package/dist/interaction/viewController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewController.js","sourceRoot":"","sources":["../../src/interaction/viewController.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\n/**\n * A visible window into the world x axis (bar times in UTC ms). The two\n * self-scaled adapters (canvas2d, konva) resolve one per frame from a\n * {@link ViewController} and feed `xMin`/`xMax` into their `Viewport`.\n *\n * @since 1.6\n * @stable\n * @example\n *     const win: XWindow = { xMin: 0, xMax: 100 };\n *     void win;\n */\nexport type XWindow = { readonly xMin: number; readonly xMax: number };\n\n/**\n * Construction options for {@link createViewController}. `minSpan` is the\n * smallest world-x span a zoom-in can reach (so the window never collapses\n * to a point); `maxSpanFactor` is the largest span a zoom-out can reach as\n * a multiple of the current data span (default `1` ⇒ cannot zoom out past\n * \"all data visible\").\n *\n * @since 1.6\n * @stable\n * @example\n *     const opts: ViewControllerOpts = { minSpan: 1, maxSpanFactor: 1 };\n *     void opts;\n */\nexport type ViewControllerOpts = {\n    readonly minSpan?: number;\n    readonly maxSpanFactor?: number;\n};\n\n/**\n * Stateful, library-agnostic pan/zoom controller for an adapter that\n * computes its own x scale every frame. It holds a user x-window plus a\n * `userInteracted` flag: until the user wheels or drags, {@link\n * ViewController.resolveXWindow} returns the full data range (auto-follow\n * live bars); after the first interaction it returns the held window\n * (re-clamped as data grows), so live frames stop snapping the view back.\n *\n * All transforms are pure functions of the current state + the supplied\n * data bounds — there is no DOM or library coupling. The example adapters\n * wire DOM events to {@link ViewController.zoomAt} / {@link\n * ViewController.panBy} / {@link ViewController.reset} via {@link\n * attachInteraction}.\n *\n * @since 1.6\n * @stable\n * @example\n *     const view = createViewController();\n *     view.resolveXWindow(0, 100); // { xMin: 0, xMax: 100 } (auto-follow)\n *     view.panBy(10, 0, 100);\n *     view.userInteracted; // true\n */\nexport type ViewController = {\n    /** `true` once the user has zoomed or panned (auto-follow is paused). */\n    readonly userInteracted: boolean;\n    /**\n     * The x-window to render this frame: `[dataXMin, dataXMax]` while not\n     * interacted (auto-follow), else the held window clamped into the\n     * current data bounds.\n     */\n    resolveXWindow(dataXMin: number, dataXMax: number): XWindow;\n    /** Zoom by `factor` (`<1` in, `>1` out) about a world-x pivot. */\n    zoomAt(pivotX: number, factor: number, dataXMin: number, dataXMax: number): void;\n    /** Pan the window by a signed world-x delta. */\n    panBy(deltaWorldX: number, dataXMin: number, dataXMax: number): void;\n    /** Clear the held window + flag so the view auto-follows again. */\n    reset(): void;\n};\n\nconst DEFAULT_MIN_SPAN = 1;\nconst DEFAULT_MAX_SPAN_FACTOR = 1;\n\n// Clamp a candidate window: bound its span to [minSpan, maxSpan] (maxSpan =\n// dataSpan * maxSpanFactor), then shift it to sit inside [dataMin, dataMax]\n// when it fits, or pin it to the full data range when it is at least as wide\n// as the data. The single clamp shared by zoom / pan / resolve.\nfunction clampWindow(\n    win: XWindow,\n    dataMin: number,\n    dataMax: number,\n    minSpan: number,\n    maxSpanFactor: number,\n): XWindow {\n    const dataSpan = Math.max(0, dataMax - dataMin);\n    const maxSpan = dataSpan * maxSpanFactor;\n    let span = win.xMax - win.xMin;\n    if (maxSpan > 0 && span > maxSpan) span = maxSpan;\n    if (span < minSpan) span = minSpan;\n    const center = (win.xMin + win.xMax) / 2;\n    let xMin = center - span / 2;\n    let xMax = center + span / 2;\n    if (span <= dataSpan) {\n        if (xMin < dataMin) {\n            xMax += dataMin - xMin;\n            xMin = dataMin;\n        }\n        if (xMax > dataMax) {\n            xMin -= xMax - dataMax;\n            xMax = dataMax;\n        }\n        return { xMin, xMax };\n    }\n    return { xMin: dataMin, xMax: dataMax };\n}\n\n/**\n * Build a {@link ViewController}. Pass `opts` to tune the zoom-in floor\n * (`minSpan`) and zoom-out ceiling (`maxSpanFactor`); both default to a\n * \"1 ms floor, all-data ceiling\" policy.\n *\n * @since 1.6\n * @stable\n * @example\n *     const view = createViewController({ minSpan: 2, maxSpanFactor: 1 });\n *     view.zoomAt(50, 0.5, 0, 100); // zoom in 2× about x=50\n *     void view.resolveXWindow(0, 100);\n */\nexport function createViewController(opts?: ViewControllerOpts): ViewController {\n    const minSpan = opts?.minSpan ?? DEFAULT_MIN_SPAN;\n    const maxSpanFactor = opts?.maxSpanFactor ?? DEFAULT_MAX_SPAN_FACTOR;\n    let held: XWindow | undefined;\n    let interacted = false;\n\n    const base = (dataMin: number, dataMax: number): XWindow =>\n        held ?? { xMin: dataMin, xMax: dataMax };\n\n    return {\n        get userInteracted(): boolean {\n            return interacted;\n        },\n        resolveXWindow(dataMin: number, dataMax: number): XWindow {\n            if (!interacted || held === undefined) return { xMin: dataMin, xMax: dataMax };\n            return clampWindow(held, dataMin, dataMax, minSpan, maxSpanFactor);\n        },\n        zoomAt(pivotX: number, factor: number, dataMin: number, dataMax: number): void {\n            interacted = true;\n            const b = base(dataMin, dataMax);\n            const span = b.xMax - b.xMin;\n            const frac = span === 0 ? 0.5 : (pivotX - b.xMin) / span;\n            const newSpan = span * factor;\n            const xMin = pivotX - frac * newSpan;\n            held = clampWindow(\n                { xMin, xMax: xMin + newSpan },\n                dataMin,\n                dataMax,\n                minSpan,\n                maxSpanFactor,\n            );\n        },\n        panBy(deltaWorldX: number, dataMin: number, dataMax: number): void {\n            interacted = true;\n            const b = base(dataMin, dataMax);\n            held = clampWindow(\n                { xMin: b.xMin + deltaWorldX, xMax: b.xMax + deltaWorldX },\n                dataMin,\n                dataMax,\n                minSpan,\n                maxSpanFactor,\n            );\n        },\n        reset(): void {\n            held = undefined;\n            interacted = false;\n        },\n    };\n}\n\n/**\n * One candidate row for {@link yRangeInWindow}: a world `x` (bar time) plus\n * the low / high values to fold into the y range when `x` is inside the\n * window. Bars pass `{ x: time, lo: low, hi: high }`; a scalar series point\n * passes `lo === hi === value`.\n *\n * @since 1.6\n * @stable\n * @example\n *     const c: WindowYInput = { x: 10, lo: 99, hi: 101 };\n *     void c;\n */\nexport type WindowYInput = { readonly x: number; readonly lo: number; readonly hi: number };\n\n/**\n * Fold the y range of every candidate whose `x` falls inside `win` — the\n * shared \"auto-fit the price scale to the visible window\" helper (matching\n * lightweight-charts' auto price scale). Non-finite `lo`/`hi` rows are\n * skipped. Returns `undefined` when no finite in-window candidate is seen,\n * so the caller keeps its own degenerate-range fallback. Horizontal lines\n * (no `x`) are folded in by the caller, not here.\n *\n * @since 1.6\n * @stable\n * @example\n *     const r = yRangeInWindow([{ x: 5, lo: 1, hi: 3 }], { xMin: 0, xMax: 10 });\n *     // r === { yMin: 1, yMax: 3 }\n *     void r;\n */\nexport function yRangeInWindow(\n    candidates: Iterable<WindowYInput>,\n    win: XWindow,\n): { readonly yMin: number; readonly yMax: number } | undefined {\n    let yMin = Number.POSITIVE_INFINITY;\n    let yMax = Number.NEGATIVE_INFINITY;\n    for (const c of candidates) {\n        if (c.x < win.xMin || c.x > win.xMax) continue;\n        if (!Number.isFinite(c.lo) || !Number.isFinite(c.hi)) continue;\n        if (c.lo < yMin) yMin = c.lo;\n        if (c.hi > yMax) yMax = c.hi;\n    }\n    if (!Number.isFinite(yMin) || !Number.isFinite(yMax)) return undefined;\n    return { yMin, yMax };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invinite-org/chartlang-adapter-kit",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "license": "MIT",
   "description": "SDK for writing chartlang adapters in consumer repos",