@pibbl/core 0.0.1 → 0.0.3-alpha.85.1

package/dist/features/viz/inspection/handler.js

@@ -0,0 +1,91 @@
+import {
+  borrowDispatchResource,
+  withHooksForbidden
+} from "@pibbl/core/internal";
+const dispatchKey = {};
+function copyArguments(value, depth = 0) {
+  if (value === null || typeof value !== "object") return value;
+  if (depth > 2 || Object.getPrototypeOf(value) !== Object.prototype)
+    throw new TypeError(
+      "Inspection arguments must contain plain scalar options and logical points."
+    );
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      copyArguments(item, depth + 1)
+    ])
+  );
+}
+function sameArguments(a, b) {
+  if (Object.is(a, b)) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+  const aa = a, bb = b;
+  const keys = Object.keys(aa);
+  return keys.length === Object.keys(bb).length && keys.every(
+    (key) => Object.hasOwn(bb, key) && sameArguments(aa[key], bb[key])
+  );
+}
+function withInspection(handler) {
+  return (event) => {
+    let live = true;
+    const borrow = () => {
+      if (!live)
+        throw new Error(
+          "Inspection context has expired; use it synchronously within dispatch."
+        );
+      return borrowDispatchResource(
+        event,
+        dispatchKey,
+        () => {
+          const value = {
+            live: true,
+            renders: /* @__PURE__ */ new Map(),
+            memo: []
+          };
+          return {
+            value,
+            dispose: () => {
+              value.live = false;
+              value.renders.clear();
+              value.memo.length = 0;
+            }
+          };
+        }
+      );
+    };
+    const context = Object.freeze({
+      rendered(ref) {
+        const state = borrow();
+        if (!state.renders.has(ref)) state.renders.set(ref, ref.rendered());
+        return state.renders.get(ref);
+      },
+      request(query, rendered, options) {
+        const state = borrow();
+        const args = copyArguments(options);
+        const cached = state.memo.find(
+          (memo) => memo.query === query && memo.rendered === rendered && sameArguments(memo.options, args)
+        );
+        if (cached) return cached.result;
+        const result = withHooksForbidden(
+          "Inspection queries must be pure synchronous functions.",
+          () => query(rendered, options)
+        );
+        if (result && typeof result.then === "function")
+          throw new TypeError("Inspection queries must be synchronous.");
+        state.memo.push({ query, rendered, options: args, result });
+        return result;
+      }
+    });
+    try {
+      const result = handler(event, context);
+      if (result && typeof result.then === "function")
+        throw new TypeError("Inspection handlers must be synchronous.");
+    } finally {
+      live = false;
+    }
+  };
+}
+export {
+  withInspection
+};
+//# sourceMappingURL=handler.js.map

package/dist/features/viz/inspection/handler.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/handler.ts"],
+  "sourcesContent": ["import type { PibblEvent } from \"@pibbl/core\";\nimport {\n  borrowDispatchResource,\n  withHooksForbidden,\n} from \"@pibbl/core/internal\";\n\n/** A mount-owned source of borrowed committed render records.\n * @see {@link InspectionContext}\n */\nexport interface InspectionRef<S> {\n  /** Returns the current committed record.\n   * @returns Borrowed record or undefined before paint/after disposal.\n   */\n  rendered(): S | undefined;\n}\n\n/** Lazy synchronous inspection; expires when its handler returns.\n * @see {@link InspectionRef}\n */\nexport interface InspectionContext {\n  /** Pins one receiver's committed generation for this logical dispatch.\n   * @param ref - Explicit ref identifying the mounted receiver.\n   * @returns Borrowed generation or undefined before paint/after disposal.\n   */\n  rendered<S>(ref: InspectionRef<S>): S | undefined;\n  /**\n   * Executes only on demand and memoizes equal requests, including no result.\n   * Options contain plain scalar fields, function identities and logical points.\n   * @param query - Pure synchronous query with a stable result contract.\n   * @param rendered - Committed generation pinned for this request.\n   * @param options - Named query parameters; functions compare by identity.\n   * @returns Query result, including undefined, reused for equal requests in dispatch.\n   */\n  request<S, A, R>(\n    query: (rendered: S, options: A) => R,\n    rendered: S,\n    options: A,\n  ): R;\n}\n\nconst dispatchKey = {};\ninterface Memo {\n  query: unknown;\n  rendered: unknown;\n  options: unknown;\n  result: unknown;\n}\ninterface DispatchInspection {\n  live: boolean;\n  renders: Map<object, unknown>;\n  memo: Memo[];\n}\n\nfunction copyArguments(value: unknown, depth = 0): unknown {\n  if (value === null || typeof value !== \"object\") return value;\n  if (depth > 2 || Object.getPrototypeOf(value) !== Object.prototype)\n    throw new TypeError(\n      \"Inspection arguments must contain plain scalar options and logical points.\",\n    );\n  return Object.fromEntries(\n    Object.entries(value).map(([key, item]) => [\n      key,\n      copyArguments(item, depth + 1),\n    ]),\n  );\n}\nfunction sameArguments(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true;\n  if (!a || !b || typeof a !== \"object\" || typeof b !== \"object\") return false;\n  const aa = a as Record<string, unknown>,\n    bb = b as Record<string, unknown>;\n  const keys = Object.keys(aa);\n  return (\n    keys.length === Object.keys(bb).length &&\n    keys.every(\n      (key) => Object.hasOwn(bb, key) && sameArguments(aa[key], bb[key]),\n    )\n  );\n}\n\n/**\n * Adapts an ordinary handler to lazy typed inspection without changing its event.\n * @param handler - Synchronous callback receiving the unchanged event and an expiring context.\n * @returns An ordinary event handler. Searches occur only on request; memo state releases at dispatch end.\n * @see {@link InspectionContext}\n */\nexport function withInspection<E extends PibblEvent>(\n  handler: (event: E, context: InspectionContext) => void,\n): (event: E) => void {\n  return (event) => {\n    let live = true;\n    const borrow = () => {\n      if (!live)\n        throw new Error(\n          \"Inspection context has expired; use it synchronously within dispatch.\",\n        );\n      return borrowDispatchResource<DispatchInspection>(\n        event,\n        dispatchKey,\n        () => {\n          const value: DispatchInspection = {\n            live: true,\n            renders: new Map(),\n            memo: [],\n          };\n          return {\n            value,\n            dispose: () => {\n              value.live = false;\n              value.renders.clear();\n              value.memo.length = 0;\n            },\n          };\n        },\n      );\n    };\n    const context: InspectionContext = Object.freeze({\n      rendered<S>(ref: InspectionRef<S>): S | undefined {\n        const state = borrow();\n        if (!state.renders.has(ref)) state.renders.set(ref, ref.rendered());\n        return state.renders.get(ref) as S | undefined;\n      },\n      request<S, A, R>(\n        query: (rendered: S, options: A) => R,\n        rendered: S,\n        options: A,\n      ): R {\n        const state = borrow();\n        const args = copyArguments(options);\n        const cached = state.memo.find(\n          (memo) =>\n            memo.query === query &&\n            memo.rendered === rendered &&\n            sameArguments(memo.options, args),\n        );\n        if (cached) return cached.result as R;\n        const result = withHooksForbidden(\n          \"Inspection queries must be pure synchronous functions.\",\n          () => query(rendered, options),\n        );\n        if (result && typeof (result as { then?: unknown }).then === \"function\")\n          throw new TypeError(\"Inspection queries must be synchronous.\");\n        state.memo.push({ query, rendered, options: args, result });\n        return result;\n      },\n    });\n    try {\n      const result = handler(event, context) as unknown;\n      if (result && typeof (result as { then?: unknown }).then === \"function\")\n        throw new TypeError(\"Inspection handlers must be synchronous.\");\n    } finally {\n      live = false;\n    }\n  };\n}\n"],
+  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAoCP,MAAM,cAAc,CAAC;AAarB,SAAS,cAAc,OAAgB,QAAQ,GAAY;AACzD,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AACxD,MAAI,QAAQ,KAAK,OAAO,eAAe,KAAK,MAAM,OAAO;AACvD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM;AAAA,MACzC;AAAA,MACA,cAAc,MAAM,QAAQ,CAAC;AAAA,IAC/B,CAAC;AAAA,EACH;AACF;AACA,SAAS,cAAc,GAAY,GAAqB;AACtD,MAAI,OAAO,GAAG,GAAG,CAAC,EAAG,QAAO;AAC5B,MAAI,CAAC,KAAK,CAAC,KAAK,OAAO,MAAM,YAAY,OAAO,MAAM,SAAU,QAAO;AACvE,QAAM,KAAK,GACT,KAAK;AACP,QAAM,OAAO,OAAO,KAAK,EAAE;AAC3B,SACE,KAAK,WAAW,OAAO,KAAK,EAAE,EAAE,UAChC,KAAK;AAAA,IACH,CAAC,QAAQ,OAAO,OAAO,IAAI,GAAG,KAAK,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAAA,EACnE;AAEJ;AAQO,SAAS,eACd,SACoB;AACpB,SAAO,CAAC,UAAU;AAChB,QAAI,OAAO;AACX,UAAM,SAAS,MAAM;AACnB,UAAI,CAAC;AACH,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AACF,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA,MAAM;AACJ,gBAAM,QAA4B;AAAA,YAChC,MAAM;AAAA,YACN,SAAS,oBAAI,IAAI;AAAA,YACjB,MAAM,CAAC;AAAA,UACT;AACA,iBAAO;AAAA,YACL;AAAA,YACA,SAAS,MAAM;AACb,oBAAM,OAAO;AACb,oBAAM,QAAQ,MAAM;AACpB,oBAAM,KAAK,SAAS;AAAA,YACtB;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,UAAM,UAA6B,OAAO,OAAO;AAAA,MAC/C,SAAY,KAAsC;AAChD,cAAM,QAAQ,OAAO;AACrB,YAAI,CAAC,MAAM,QAAQ,IAAI,GAAG,EAAG,OAAM,QAAQ,IAAI,KAAK,IAAI,SAAS,CAAC;AAClE,eAAO,MAAM,QAAQ,IAAI,GAAG;AAAA,MAC9B;AAAA,MACA,QACE,OACA,UACA,SACG;AACH,cAAM,QAAQ,OAAO;AACrB,cAAM,OAAO,cAAc,OAAO;AAClC,cAAM,SAAS,MAAM,KAAK;AAAA,UACxB,CAAC,SACC,KAAK,UAAU,SACf,KAAK,aAAa,YAClB,cAAc,KAAK,SAAS,IAAI;AAAA,QACpC;AACA,YAAI,OAAQ,QAAO,OAAO;AAC1B,cAAM,SAAS;AAAA,UACb;AAAA,UACA,MAAM,MAAM,UAAU,OAAO;AAAA,QAC/B;AACA,YAAI,UAAU,OAAQ,OAA8B,SAAS;AAC3D,gBAAM,IAAI,UAAU,yCAAyC;AAC/D,cAAM,KAAK,KAAK,EAAE,OAAO,UAAU,SAAS,MAAM,OAAO,CAAC;AAC1D,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AACD,QAAI;AACF,YAAM,SAAS,QAAQ,OAAO,OAAO;AACrC,UAAI,UAAU,OAAQ,OAA8B,SAAS;AAC3D,cAAM,IAAI,UAAU,0CAA0C;AAAA,IAClE,UAAE;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/features/viz/inspection/ohlc-bar.d.ts

@@ -0,0 +1,132 @@
+import type { OhlcBarSeriesProps } from "../lib/ohlc-bar-series.js";
+import { type NumericPositionScale } from "../lib/series-position.js";
+import type { ResolvedContinuousScale } from "../lib/types.js";
+import type { NumericRenderedSeries, RenderedSeriesPoint } from "./query-types.js";
+/** One original OHLC record and its values and geometry as evaluated during paint.
+ * @see {@link OhlcBarRenderedSeries}
+ */
+export interface OhlcBarObservation<D> {
+    /** Caller-owned original record. */
+    readonly datum: D;
+    /** Original source index, including skipped rows. */
+    readonly sourceIndex: number;
+    /** Evaluated UTC-millisecond timestamp. */
+    readonly time: number;
+    /** Evaluated opening value. */
+    readonly open: number;
+    /** Evaluated high value. */
+    readonly high: number;
+    /** Evaluated low value. */
+    readonly low: number;
+    /** Evaluated closing value. */
+    readonly close: number;
+    /** Closing endpoint in series-local coordinates. */ readonly anchorLocal: Readonly<RenderedSeriesPoint>;
+    /** Closing endpoint in root-logical coordinates. */ readonly anchorRoot: Readonly<RenderedSeriesPoint>;
+    /** High/low segment before world transforms. */ readonly stemLocal: Readonly<{
+        /** Horizontal center. */ x: number;
+        /** Mapped high endpoint. */ highY: number;
+        /** Mapped low endpoint. */ lowY: number;
+    }>;
+    /** Left-facing opening segment before world transforms. */ readonly openTickLocal: Readonly<{
+        /** Left endpoint. */ x1: number;
+        /** Center endpoint. */ x2: number;
+        /** Mapped opening ordinate. */ y: number;
+    }>;
+    /** Right-facing closing segment before world transforms. */ readonly closeTickLocal: Readonly<{
+        /** Center endpoint. */ x1: number;
+        /** Right endpoint. */ x2: number;
+        /** Mapped closing ordinate. */ y: number;
+    }>;
+}
+/** A nearest-time OHLC candidate with committed clip eligibility.
+ * @see {@link nearestRecordedOhlcBarX}
+ */
+export interface OhlcBarInspectionCandidate<D> extends OhlcBarObservation<D> {
+    /** @returns Whether the close anchor lies inside every committed clip. */
+    anchorInsideClips(): boolean;
+}
+/** Original OHLC selected by nearest timestamp.
+ * @see {@link nearestRecordedOhlcBarX}
+ */
+export interface NearestOhlcBarHit<D> extends OhlcBarObservation<D> {
+    /** Absolute UTC-millisecond distance from the requested timestamp. */
+    readonly timeDelta: number;
+}
+/** An actual painted OHLC stroke segment covering a root-logical point.
+ * @see {@link paintedOhlcBarAt}
+ */
+export interface PaintedOhlcBarHit<D> extends OhlcBarObservation<D> {
+    /** Last painted matching segment. */
+    readonly part: "stem" | "openTick" | "closeTick";
+}
+/** @internal Local OHLC paint capture. */
+export interface CapturedOhlcBarMark<D> extends Omit<OhlcBarObservation<D>, "anchorRoot"> {
+    readonly strokeWidthLocal: number;
+}
+/** Borrowed committed OHLC generation.
+ * @see {@link OhlcBarInspectionRef}
+ */
+export interface OhlcBarRenderedSeries<D> {
+    /** Captured original observations in source order. */
+    readonly observations: readonly OhlcBarObservation<D>[];
+    /** Throws after replacement or disposal. */
+    assertLive(): void;
+    /** Inverts a root-logical point to a timestamp.
+     * @param pointRoot - Root-logical point.
+     * @returns Timestamp, or undefined for a singular transform.
+     */
+    timeAtRoot(pointRoot: Readonly<RenderedSeriesPoint>): number | undefined;
+    /** Tests a local point against every committed clip.
+     * @param pointLocal - Series-local point.
+     * @returns Whether every committed clip contains it.
+     */
+    anchorInsideClips(pointLocal: Readonly<RenderedSeriesPoint>): boolean;
+    /** @internal */ readonly marks: readonly CapturedOhlcBarMark<D>[];
+    /** @internal */ readonly numeric: NumericRenderedSeries<D>;
+    /** @internal Converts a root-logical point to local geometry.
+     * @param point - Root-logical coordinate.
+     * @returns Local coordinate, or undefined for a singular transform.
+     */ localAtRoot(point: Readonly<RenderedSeriesPoint>): Readonly<RenderedSeriesPoint> | undefined;
+}
+/** Mount-owned optional OHLC bar receiver.
+ * @see {@link useOhlcBarInspection}
+ */
+export interface OhlcBarInspectionRef<D> {
+    /** @returns Current borrowed generation, or undefined before paint and after disposal. */
+    rendered(): OhlcBarRenderedSeries<D> | undefined;
+    /** @internal Records completed local paint without querying.
+     * @param input - Captured marks and committed mappings.
+     */ capture(input: {
+        /** Local marks in source order. */
+        marks: readonly CapturedOhlcBarMark<D>[];
+        /** Committed horizontal mapping. */
+        xScale: NumericPositionScale;
+        /** Committed price mapping. */
+        yScale: ResolvedContinuousScale;
+    }): void;
+}
+/** Creates a stable OHLC-bar inspection ref without reading data or subscribing.
+ * @param _inputs - Inputs retained only to infer the original datum type.
+ * @returns A ref for exactly one OhlcBarSeries inspection prop.
+ * @see {@link OhlcBarInspectionRef}
+ */
+export declare function useOhlcBarInspection<D>(_inputs: Pick<OhlcBarSeriesProps<D>, "data" | "time" | "open" | "high" | "low" | "close">): OhlcBarInspectionRef<D>;
+/** Selects captured original OHLC by nearest timestamp, retaining source-order ties.
+ * @param rendered - Borrowed committed OHLC generation.
+ * @param options - Timestamp and optional pure candidate filter.
+ * @returns First source-order match on a tie, or undefined when none qualifies.
+ * @see {@link NearestOhlcBarHit}
+ */
+export declare function nearestRecordedOhlcBarX<D>(rendered: OhlcBarRenderedSeries<D>, options: {
+    time: number;
+    filter?: (observation: OhlcBarInspectionCandidate<D>) => boolean;
+}): NearestOhlcBarHit<D> | undefined;
+/** Finds the last-painted OHLC segment covering a root-logical point.
+ * @param rendered - Borrowed committed OHLC generation.
+ * @param options - Root-logical point; clips and singular transforms produce no result.
+ * @returns Captured OHLC record and painted segment, or undefined for gaps.
+ * @see {@link PaintedOhlcBarHit}
+ */
+export declare function paintedOhlcBarAt<D>(rendered: OhlcBarRenderedSeries<D>, options: {
+    rootPoint: Readonly<RenderedSeriesPoint>;
+}): PaintedOhlcBarHit<D> | undefined;

package/dist/features/viz/inspection/ohlc-bar.js

@@ -0,0 +1,118 @@
+import {
+  invertNumericPosition
+} from "../lib/series-position.js";
+import { useRenderedRef } from "./owned-ref.js";
+import { nearestRecordedX } from "./queries.js";
+function useOhlcBarInspection(_inputs) {
+  return useRenderedRef("ohlcBarInspection", (candidate, geometry) => {
+    const observations = Object.freeze(
+      candidate.marks.map(
+        (mark) => Object.freeze({
+          datum: mark.datum,
+          sourceIndex: mark.sourceIndex,
+          time: mark.time,
+          open: mark.open,
+          high: mark.high,
+          low: mark.low,
+          close: mark.close,
+          anchorLocal: mark.anchorLocal,
+          anchorRoot: geometry.rootAtLocal(mark.anchorLocal),
+          stemLocal: mark.stemLocal,
+          openTickLocal: mark.openTickLocal,
+          closeTickLocal: mark.closeTickLocal
+        })
+      )
+    );
+    const numeric = Object.freeze({
+      observations: Object.freeze(
+        observations.map(
+          (row) => Object.freeze({
+            ...row,
+            domainX: row.time,
+            domainY: row.close,
+            run: 0
+          })
+        )
+      ),
+      assertLive: geometry.assertLive,
+      domainXAtRoot(point) {
+        const local = geometry.localAtRoot(point);
+        return local ? invertNumericPosition(candidate.xScale, local.x) : void 0;
+      },
+      anchorInsideClips: geometry.anchorInsideClips,
+      anchorAtDomain(point) {
+        geometry.assertLive();
+        const anchorLocal = Object.freeze({
+          x: candidate.xScale.map(point.domainX),
+          y: candidate.yScale.map(point.domainY)
+        });
+        return Object.freeze({
+          anchorLocal,
+          anchorRoot: geometry.rootAtLocal(anchorLocal)
+        });
+      }
+    });
+    return Object.freeze({
+      observations,
+      marks: Object.freeze(candidate.marks.slice()),
+      numeric,
+      assertLive: geometry.assertLive,
+      localAtRoot: geometry.localAtRoot,
+      anchorInsideClips: geometry.anchorInsideClips,
+      timeAtRoot: numeric.domainXAtRoot
+    });
+  });
+}
+function nearestRecordedOhlcBarX(rendered, options) {
+  const hit = nearestRecordedX(rendered.numeric, {
+    domainX: options.time,
+    filter: options.filter ? (candidate) => options.filter(
+      candidate
+    ) : void 0
+  });
+  if (!hit) return void 0;
+  const row = rendered.observations.find(
+    (observation) => observation.sourceIndex === hit.sourceIndex
+  );
+  return Object.freeze({ ...row, timeDelta: hit.domainDelta });
+}
+function segmentCovers(point, segment, strokeWidth) {
+  if (strokeWidth <= 0) return false;
+  const half = strokeWidth / 2;
+  return point.x >= Math.min(segment.x1, segment.x2) && point.x <= Math.max(segment.x1, segment.x2) && point.y >= segment.y - half && point.y <= segment.y + half;
+}
+function stemCovers(point, stem, strokeWidth) {
+  return segmentCovers(point, { x1: stem.x, x2: stem.x, y: 0 }, 0) || strokeWidth > 0 && point.x >= stem.x - strokeWidth / 2 && point.x <= stem.x + strokeWidth / 2 && point.y >= Math.min(stem.highY, stem.lowY) && point.y <= Math.max(stem.highY, stem.lowY);
+}
+function paintedOhlcBarAt(rendered, options) {
+  rendered.assertLive();
+  if (!Number.isFinite(options.rootPoint.x) || !Number.isFinite(options.rootPoint.y))
+    throw new RangeError("paintedOhlcBarAt rootPoint must be finite.");
+  const point = rendered.localAtRoot(options.rootPoint);
+  if (!point || !rendered.anchorInsideClips(point)) return void 0;
+  for (let index = rendered.marks.length - 1; index >= 0; index--) {
+    const mark = rendered.marks[index];
+    if (segmentCovers(point, mark.closeTickLocal, mark.strokeWidthLocal))
+      return Object.freeze({
+        ...rendered.observations[index],
+        part: "closeTick"
+      });
+    if (segmentCovers(point, mark.openTickLocal, mark.strokeWidthLocal))
+      return Object.freeze({
+        ...rendered.observations[index],
+        part: "openTick"
+      });
+    if (stemCovers(point, mark.stemLocal, mark.strokeWidthLocal))
+      return Object.freeze({
+        ...rendered.observations[index],
+        part: "stem"
+      });
+  }
+  return void 0;
+}
+export {
+  nearestRecordedOhlcBarX,
+  paintedOhlcBarAt,
+  useOhlcBarInspection
+};
+//# sourceMappingURL=ohlc-bar.js.map

package/dist/features/viz/inspection/ohlc-bar.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/ohlc-bar.ts"],
+  "sourcesContent": ["import type { OhlcBarSeriesProps } from \"../lib/ohlc-bar-series.js\";\nimport {\n  invertNumericPosition,\n  type NumericPositionScale,\n} from \"../lib/series-position.js\";\nimport type { ResolvedContinuousScale } from \"../lib/types.js\";\nimport { useRenderedRef } from \"./owned-ref.js\";\nimport { nearestRecordedX } from \"./queries.js\";\nimport type {\n  NumericRenderedSeries,\n  RenderedSeriesPoint,\n} from \"./query-types.js\";\n\n/** One original OHLC record and its values and geometry as evaluated during paint.\n * @see {@link OhlcBarRenderedSeries}\n */\nexport interface OhlcBarObservation<D> {\n  /** Caller-owned original record. */\n  readonly datum: D;\n  /** Original source index, including skipped rows. */\n  readonly sourceIndex: number;\n  /** Evaluated UTC-millisecond timestamp. */\n  readonly time: number;\n  /** Evaluated opening value. */\n  readonly open: number;\n  /** Evaluated high value. */\n  readonly high: number;\n  /** Evaluated low value. */\n  readonly low: number;\n  /** Evaluated closing value. */\n  readonly close: number;\n  /** Closing endpoint in series-local coordinates. */ readonly anchorLocal: Readonly<RenderedSeriesPoint>;\n  /** Closing endpoint in root-logical coordinates. */ readonly anchorRoot: Readonly<RenderedSeriesPoint>;\n  /** High/low segment before world transforms. */ readonly stemLocal: Readonly<{\n    /** Horizontal center. */ x: number;\n    /** Mapped high endpoint. */ highY: number;\n    /** Mapped low endpoint. */ lowY: number;\n  }>;\n  /** Left-facing opening segment before world transforms. */ readonly openTickLocal: Readonly<{\n    /** Left endpoint. */ x1: number;\n    /** Center endpoint. */ x2: number;\n    /** Mapped opening ordinate. */ y: number;\n  }>;\n  /** Right-facing closing segment before world transforms. */ readonly closeTickLocal: Readonly<{\n    /** Center endpoint. */ x1: number;\n    /** Right endpoint. */ x2: number;\n    /** Mapped closing ordinate. */ y: number;\n  }>;\n}\n/** A nearest-time OHLC candidate with committed clip eligibility.\n * @see {@link nearestRecordedOhlcBarX}\n */\nexport interface OhlcBarInspectionCandidate<D> extends OhlcBarObservation<D> {\n  /** @returns Whether the close anchor lies inside every committed clip. */\n  anchorInsideClips(): boolean;\n}\n/** Original OHLC selected by nearest timestamp.\n * @see {@link nearestRecordedOhlcBarX}\n */\nexport interface NearestOhlcBarHit<D> extends OhlcBarObservation<D> {\n  /** Absolute UTC-millisecond distance from the requested timestamp. */\n  readonly timeDelta: number;\n}\n/** An actual painted OHLC stroke segment covering a root-logical point.\n * @see {@link paintedOhlcBarAt}\n */\nexport interface PaintedOhlcBarHit<D> extends OhlcBarObservation<D> {\n  /** Last painted matching segment. */\n  readonly part: \"stem\" | \"openTick\" | \"closeTick\";\n}\n/** @internal Local OHLC paint capture. */\nexport interface CapturedOhlcBarMark<D> extends Omit<\n  OhlcBarObservation<D>,\n  \"anchorRoot\"\n> {\n  readonly strokeWidthLocal: number;\n}\n/** Borrowed committed OHLC generation.\n * @see {@link OhlcBarInspectionRef}\n */\nexport interface OhlcBarRenderedSeries<D> {\n  /** Captured original observations in source order. */\n  readonly observations: readonly OhlcBarObservation<D>[];\n  /** Throws after replacement or disposal. */\n  assertLive(): void;\n  /** Inverts a root-logical point to a timestamp.\n   * @param pointRoot - Root-logical point.\n   * @returns Timestamp, or undefined for a singular transform.\n   */\n  timeAtRoot(pointRoot: Readonly<RenderedSeriesPoint>): number | undefined;\n  /** Tests a local point against every committed clip.\n   * @param pointLocal - Series-local point.\n   * @returns Whether every committed clip contains it.\n   */\n  anchorInsideClips(pointLocal: Readonly<RenderedSeriesPoint>): boolean;\n  /** @internal */ readonly marks: readonly CapturedOhlcBarMark<D>[];\n  /** @internal */ readonly numeric: NumericRenderedSeries<D>;\n  /** @internal Converts a root-logical point to local geometry.\n   * @param point - Root-logical coordinate.\n   * @returns Local coordinate, or undefined for a singular transform.\n   */ localAtRoot(\n    point: Readonly<RenderedSeriesPoint>,\n  ): Readonly<RenderedSeriesPoint> | undefined;\n}\n/** Mount-owned optional OHLC bar receiver.\n * @see {@link useOhlcBarInspection}\n */\nexport interface OhlcBarInspectionRef<D> {\n  /** @returns Current borrowed generation, or undefined before paint and after disposal. */\n  rendered(): OhlcBarRenderedSeries<D> | undefined;\n  /** @internal Records completed local paint without querying.\n   * @param input - Captured marks and committed mappings.\n   */ capture(input: {\n    /** Local marks in source order. */\n    marks: readonly CapturedOhlcBarMark<D>[];\n    /** Committed horizontal mapping. */\n    xScale: NumericPositionScale;\n    /** Committed price mapping. */\n    yScale: ResolvedContinuousScale;\n  }): void;\n}\n\n/** Creates a stable OHLC-bar inspection ref without reading data or subscribing.\n * @param _inputs - Inputs retained only to infer the original datum type.\n * @returns A ref for exactly one OhlcBarSeries inspection prop.\n * @see {@link OhlcBarInspectionRef}\n */\nexport function useOhlcBarInspection<D>(\n  _inputs: Pick<\n    OhlcBarSeriesProps<D>,\n    \"data\" | \"time\" | \"open\" | \"high\" | \"low\" | \"close\"\n  >,\n): OhlcBarInspectionRef<D> {\n  return useRenderedRef<\n    {\n      marks: readonly CapturedOhlcBarMark<D>[];\n      xScale: NumericPositionScale;\n      yScale: ResolvedContinuousScale;\n    },\n    OhlcBarRenderedSeries<D>\n  >(\"ohlcBarInspection\", (candidate, geometry) => {\n    const observations = Object.freeze(\n      candidate.marks.map((mark) =>\n        Object.freeze({\n          datum: mark.datum,\n          sourceIndex: mark.sourceIndex,\n          time: mark.time,\n          open: mark.open,\n          high: mark.high,\n          low: mark.low,\n          close: mark.close,\n          anchorLocal: mark.anchorLocal,\n          anchorRoot: geometry.rootAtLocal(mark.anchorLocal),\n          stemLocal: mark.stemLocal,\n          openTickLocal: mark.openTickLocal,\n          closeTickLocal: mark.closeTickLocal,\n        }),\n      ),\n    );\n    const numeric: NumericRenderedSeries<D> = Object.freeze({\n      observations: Object.freeze(\n        observations.map((row) =>\n          Object.freeze({\n            ...row,\n            domainX: row.time,\n            domainY: row.close,\n            run: 0,\n          }),\n        ),\n      ),\n      assertLive: geometry.assertLive,\n      domainXAtRoot(point: Readonly<RenderedSeriesPoint>) {\n        const local = geometry.localAtRoot(point);\n        return local\n          ? invertNumericPosition(candidate.xScale, local.x)\n          : undefined;\n      },\n      anchorInsideClips: geometry.anchorInsideClips,\n      anchorAtDomain(point: Readonly<{ domainX: number; domainY: number }>) {\n        geometry.assertLive();\n        const anchorLocal = Object.freeze({\n          x: candidate.xScale.map(point.domainX),\n          y: candidate.yScale.map(point.domainY),\n        });\n        return Object.freeze({\n          anchorLocal,\n          anchorRoot: geometry.rootAtLocal(anchorLocal),\n        });\n      },\n    });\n    return Object.freeze({\n      observations,\n      marks: Object.freeze(candidate.marks.slice()),\n      numeric,\n      assertLive: geometry.assertLive,\n      localAtRoot: geometry.localAtRoot,\n      anchorInsideClips: geometry.anchorInsideClips,\n      timeAtRoot: numeric.domainXAtRoot,\n    });\n  });\n}\n\n/** Selects captured original OHLC by nearest timestamp, retaining source-order ties.\n * @param rendered - Borrowed committed OHLC generation.\n * @param options - Timestamp and optional pure candidate filter.\n * @returns First source-order match on a tie, or undefined when none qualifies.\n * @see {@link NearestOhlcBarHit}\n */\nexport function nearestRecordedOhlcBarX<D>(\n  rendered: OhlcBarRenderedSeries<D>,\n  options: {\n    time: number;\n    filter?: (observation: OhlcBarInspectionCandidate<D>) => boolean;\n  },\n): NearestOhlcBarHit<D> | undefined {\n  const hit = nearestRecordedX(rendered.numeric, {\n    domainX: options.time,\n    filter: options.filter\n      ? (candidate) =>\n          options.filter!(\n            candidate as typeof candidate & OhlcBarInspectionCandidate<D>,\n          )\n      : undefined,\n  });\n  if (!hit) return undefined;\n  const row = rendered.observations.find(\n    (observation) => observation.sourceIndex === hit.sourceIndex,\n  )!;\n  return Object.freeze({ ...row, timeDelta: hit.domainDelta });\n}\n\nfunction segmentCovers(\n  point: Readonly<RenderedSeriesPoint>,\n  segment: Readonly<{ x1: number; x2: number; y: number }>,\n  strokeWidth: number,\n): boolean {\n  if (strokeWidth <= 0) return false;\n  const half = strokeWidth / 2;\n  return (\n    point.x >= Math.min(segment.x1, segment.x2) &&\n    point.x <= Math.max(segment.x1, segment.x2) &&\n    point.y >= segment.y - half &&\n    point.y <= segment.y + half\n  );\n}\nfunction stemCovers(\n  point: Readonly<RenderedSeriesPoint>,\n  stem: Readonly<{ x: number; highY: number; lowY: number }>,\n  strokeWidth: number,\n): boolean {\n  return (\n    segmentCovers(point, { x1: stem.x, x2: stem.x, y: 0 }, 0) ||\n    (strokeWidth > 0 &&\n      point.x >= stem.x - strokeWidth / 2 &&\n      point.x <= stem.x + strokeWidth / 2 &&\n      point.y >= Math.min(stem.highY, stem.lowY) &&\n      point.y <= Math.max(stem.highY, stem.lowY))\n  );\n}\n/** Finds the last-painted OHLC segment covering a root-logical point.\n * @param rendered - Borrowed committed OHLC generation.\n * @param options - Root-logical point; clips and singular transforms produce no result.\n * @returns Captured OHLC record and painted segment, or undefined for gaps.\n * @see {@link PaintedOhlcBarHit}\n */\nexport function paintedOhlcBarAt<D>(\n  rendered: OhlcBarRenderedSeries<D>,\n  options: { rootPoint: Readonly<RenderedSeriesPoint> },\n): PaintedOhlcBarHit<D> | undefined {\n  rendered.assertLive();\n  if (\n    !Number.isFinite(options.rootPoint.x) ||\n    !Number.isFinite(options.rootPoint.y)\n  )\n    throw new RangeError(\"paintedOhlcBarAt rootPoint must be finite.\");\n  const point = rendered.localAtRoot(options.rootPoint);\n  if (!point || !rendered.anchorInsideClips(point)) return undefined;\n  for (let index = rendered.marks.length - 1; index >= 0; index--) {\n    const mark = rendered.marks[index]!;\n    if (segmentCovers(point, mark.closeTickLocal, mark.strokeWidthLocal))\n      return Object.freeze({\n        ...rendered.observations[index]!,\n        part: \"closeTick\" as const,\n      });\n    if (segmentCovers(point, mark.openTickLocal, mark.strokeWidthLocal))\n      return Object.freeze({\n        ...rendered.observations[index]!,\n        part: \"openTick\" as const,\n      });\n    if (stemCovers(point, mark.stemLocal, mark.strokeWidthLocal))\n      return Object.freeze({\n        ...rendered.observations[index]!,\n        part: \"stem\" as const,\n      });\n  }\n  return undefined;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/viz/inspection/owned-ref.d.ts

@@ -0,0 +1,16 @@
+type Point = Readonly<{
+    x: number;
+    y: number;
+}>;
+interface Geometry {
+    assertLive(): void;
+    localAtRoot(point: Point): Point | undefined;
+    rootAtLocal(point: Point): Point;
+    anchorInsideClips(point: Point): boolean;
+}
+/** Shared private mount/generation ownership; no signal reads or query algorithms. */
+export declare function useRenderedRef<C, R>(kind: string, build: (candidate: C, geometry: Geometry) => R): Readonly<{
+    capture(input: C): void;
+    rendered(): R | undefined;
+}>;
+export {};

package/dist/features/viz/inspection/owned-ref.js

@@ -0,0 +1,99 @@
+import {
+  captureSeriesInspectionFrame,
+  useInternalHookSlot
+} from "@pibbl/core/internal";
+function useRenderedRef(kind, build) {
+  return useInternalHookSlot(kind, (teardowns) => {
+    let closed = false, revision = 0, generation = -1;
+    let receiver, candidate, current;
+    let frame;
+    teardowns.add(() => {
+      closed = true;
+      candidate = void 0;
+      current = void 0;
+      frame = void 0;
+      receiver = void 0;
+    });
+    return Object.freeze({
+      capture(input) {
+        if (closed) throw new Error("Inspection ref has been disposed.");
+        const next = captureSeriesInspectionFrame();
+        next.onFinish((success) => {
+          if (!success || closed || !next.alive()) return;
+          if (receiver && receiver !== next.receiver)
+            throw new Error(
+              "One inspection ref can bind only one mounted series."
+            );
+          if (!receiver) {
+            receiver = next.receiver;
+            next.onDispose(() => {
+              if (receiver !== next.receiver) return;
+              candidate = void 0;
+              current = void 0;
+              frame = void 0;
+              receiver = void 0;
+              revision++;
+            });
+          }
+          candidate = input;
+          frame = next;
+          revision++;
+          current = void 0;
+        });
+      },
+      rendered() {
+        if (closed || candidate === void 0 || !frame?.alive())
+          return void 0;
+        if (current && generation === frame.generation()) return current;
+        const captured = frame.resolve();
+        if (!captured) return void 0;
+        if (current && generation === captured.generation) return current;
+        generation = captured.generation;
+        const stamp = revision, committedGeneration = generation;
+        const transform = captured.transform, inverse = transform.inverse();
+        const ctx = captured.canvas.getContext("2d");
+        const assertLive = () => {
+          if (closed || revision !== stamp || !frame?.alive() || frame.generation() !== committedGeneration)
+            throw new Error(
+              "Rendered series is stale or disposed; obtain the current generation with rendered()."
+            );
+        };
+        const rootAtLocal = (point) => {
+          const root = transform.transformPoint(new DOMPoint(point.x, point.y));
+          return Object.freeze({ x: root.x, y: root.y });
+        };
+        current = build(candidate, {
+          assertLive,
+          rootAtLocal,
+          localAtRoot(point) {
+            assertLive();
+            const local = inverse.transformPoint(
+              new DOMPoint(point.x, point.y)
+            );
+            return Number.isFinite(local.x) && Number.isFinite(local.y) ? Object.freeze({ x: local.x, y: local.y }) : void 0;
+          },
+          anchorInsideClips(point) {
+            assertLive();
+            const root = rootAtLocal(point);
+            ctx.save();
+            try {
+              for (const clip of captured.clips) {
+                ctx.setTransform(clip.transform);
+                if (!ctx.isPointInPath(clip.path, root.x, root.y, clip.fillRule))
+                  return false;
+              }
+              return true;
+            } finally {
+              ctx.restore();
+            }
+          }
+        });
+        return current;
+      }
+    });
+  }).value;
+}
+export {
+  useRenderedRef
+};
+//# sourceMappingURL=owned-ref.js.map

package/dist/features/viz/inspection/owned-ref.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/owned-ref.ts"],
+  "sourcesContent": ["import {\n  captureSeriesInspectionFrame,\n  useInternalHookSlot,\n} from \"@pibbl/core/internal\";\ntype Point = Readonly<{ x: number; y: number }>;\ninterface Geometry {\n  assertLive(): void;\n  localAtRoot(point: Point): Point | undefined;\n  rootAtLocal(point: Point): Point;\n  anchorInsideClips(point: Point): boolean;\n}\n\n/** Shared private mount/generation ownership; no signal reads or query algorithms. */\nexport function useRenderedRef<C, R>(\n  kind: string,\n  build: (candidate: C, geometry: Geometry) => R,\n) {\n  return useInternalHookSlot(kind, (teardowns) => {\n    let closed = false,\n      revision = 0,\n      generation = -1;\n    let receiver: object | undefined,\n      candidate: C | undefined,\n      current: R | undefined;\n    let frame: ReturnType<typeof captureSeriesInspectionFrame> | undefined;\n    teardowns.add(() => {\n      closed = true;\n      candidate = undefined;\n      current = undefined;\n      frame = undefined;\n      receiver = undefined;\n    });\n    return Object.freeze({\n      capture(input: C) {\n        if (closed) throw new Error(\"Inspection ref has been disposed.\");\n        const next = captureSeriesInspectionFrame();\n        next.onFinish((success) => {\n          if (!success || closed || !next.alive()) return;\n          // Receiver removal is settled before successful render completion.\n          // Check here so a keyed replacement can adopt the surviving hook.\n          if (receiver && receiver !== next.receiver)\n            throw new Error(\n              \"One inspection ref can bind only one mounted series.\",\n            );\n          if (!receiver) {\n            receiver = next.receiver;\n            next.onDispose(() => {\n              if (receiver !== next.receiver) return;\n              candidate = undefined;\n              current = undefined;\n              frame = undefined;\n              receiver = undefined;\n              revision++;\n            });\n          }\n          candidate = input;\n          frame = next;\n          revision++;\n          current = undefined;\n        });\n      },\n      rendered(): R | undefined {\n        if (closed || candidate === undefined || !frame?.alive())\n          return undefined;\n        if (current && generation === frame.generation()) return current;\n        const captured = frame.resolve();\n        if (!captured) return undefined;\n        if (current && generation === captured.generation) return current;\n        generation = captured.generation;\n        const stamp = revision,\n          committedGeneration = generation;\n        const transform = captured.transform,\n          inverse = transform.inverse();\n        const ctx = captured.canvas.getContext(\"2d\")!;\n        const assertLive = () => {\n          if (\n            closed ||\n            revision !== stamp ||\n            !frame?.alive() ||\n            frame.generation() !== committedGeneration\n          )\n            throw new Error(\n              \"Rendered series is stale or disposed; obtain the current generation with rendered().\",\n            );\n        };\n        const rootAtLocal = (point: Point): Point => {\n          const root = transform.transformPoint(new DOMPoint(point.x, point.y));\n          return Object.freeze({ x: root.x, y: root.y });\n        };\n        current = build(candidate, {\n          assertLive,\n          rootAtLocal,\n          localAtRoot(point) {\n            assertLive();\n            const local = inverse.transformPoint(\n              new DOMPoint(point.x, point.y),\n            );\n            return Number.isFinite(local.x) && Number.isFinite(local.y)\n              ? Object.freeze({ x: local.x, y: local.y })\n              : undefined;\n          },\n          anchorInsideClips(point) {\n            assertLive();\n            const root = rootAtLocal(point);\n            ctx.save();\n            try {\n              for (const clip of captured.clips) {\n                ctx.setTransform(clip.transform);\n                if (\n                  !ctx.isPointInPath(clip.path, root.x, root.y, clip.fillRule)\n                )\n                  return false;\n              }\n              return true;\n            } finally {\n              ctx.restore();\n            }\n          },\n        });\n        return current;\n      },\n    });\n  }).value;\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAUA,SAAS,eACd,MACA,OACA;AACA,SAAO,oBAAoB,MAAM,CAAC,cAAc;AAC9C,QAAI,SAAS,OACX,WAAW,GACX,aAAa;AACf,QAAI,UACF,WACA;AACF,QAAI;AACJ,cAAU,IAAI,MAAM;AAClB,eAAS;AACT,kBAAY;AACZ,gBAAU;AACV,cAAQ;AACR,iBAAW;AAAA,IACb,CAAC;AACD,WAAO,OAAO,OAAO;AAAA,MACnB,QAAQ,OAAU;AAChB,YAAI,OAAQ,OAAM,IAAI,MAAM,mCAAmC;AAC/D,cAAM,OAAO,6BAA6B;AAC1C,aAAK,SAAS,CAAC,YAAY;AACzB,cAAI,CAAC,WAAW,UAAU,CAAC,KAAK,MAAM,EAAG;AAGzC,cAAI,YAAY,aAAa,KAAK;AAChC,kBAAM,IAAI;AAAA,cACR;AAAA,YACF;AACF,cAAI,CAAC,UAAU;AACb,uBAAW,KAAK;AAChB,iBAAK,UAAU,MAAM;AACnB,kBAAI,aAAa,KAAK,SAAU;AAChC,0BAAY;AACZ,wBAAU;AACV,sBAAQ;AACR,yBAAW;AACX;AAAA,YACF,CAAC;AAAA,UACH;AACA,sBAAY;AACZ,kBAAQ;AACR;AACA,oBAAU;AAAA,QACZ,CAAC;AAAA,MACH;AAAA,MACA,WAA0B;AACxB,YAAI,UAAU,cAAc,UAAa,CAAC,OAAO,MAAM;AACrD,iBAAO;AACT,YAAI,WAAW,eAAe,MAAM,WAAW,EAAG,QAAO;AACzD,cAAM,WAAW,MAAM,QAAQ;AAC/B,YAAI,CAAC,SAAU,QAAO;AACtB,YAAI,WAAW,eAAe,SAAS,WAAY,QAAO;AAC1D,qBAAa,SAAS;AACtB,cAAM,QAAQ,UACZ,sBAAsB;AACxB,cAAM,YAAY,SAAS,WACzB,UAAU,UAAU,QAAQ;AAC9B,cAAM,MAAM,SAAS,OAAO,WAAW,IAAI;AAC3C,cAAM,aAAa,MAAM;AACvB,cACE,UACA,aAAa,SACb,CAAC,OAAO,MAAM,KACd,MAAM,WAAW,MAAM;AAEvB,kBAAM,IAAI;AAAA,cACR;AAAA,YACF;AAAA,QACJ;AACA,cAAM,cAAc,CAAC,UAAwB;AAC3C,gBAAM,OAAO,UAAU,eAAe,IAAI,SAAS,MAAM,GAAG,MAAM,CAAC,CAAC;AACpE,iBAAO,OAAO,OAAO,EAAE,GAAG,KAAK,GAAG,GAAG,KAAK,EAAE,CAAC;AAAA,QAC/C;AACA,kBAAU,MAAM,WAAW;AAAA,UACzB;AAAA,UACA;AAAA,UACA,YAAY,OAAO;AACjB,uBAAW;AACX,kBAAM,QAAQ,QAAQ;AAAA,cACpB,IAAI,SAAS,MAAM,GAAG,MAAM,CAAC;AAAA,YAC/B;AACA,mBAAO,OAAO,SAAS,MAAM,CAAC,KAAK,OAAO,SAAS,MAAM,CAAC,IACtD,OAAO,OAAO,EAAE,GAAG,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,IACxC;AAAA,UACN;AAAA,UACA,kBAAkB,OAAO;AACvB,uBAAW;AACX,kBAAM,OAAO,YAAY,KAAK;AAC9B,gBAAI,KAAK;AACT,gBAAI;AACF,yBAAW,QAAQ,SAAS,OAAO;AACjC,oBAAI,aAAa,KAAK,SAAS;AAC/B,oBACE,CAAC,IAAI,cAAc,KAAK,MAAM,KAAK,GAAG,KAAK,GAAG,KAAK,QAAQ;AAE3D,yBAAO;AAAA,cACX;AACA,qBAAO;AAAA,YACT,UAAE;AACA,kBAAI,QAAQ;AAAA,YACd;AAAA,UACF;AAAA,QACF,CAAC;AACD,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AAAA,EACH,CAAC,EAAE;AACL;",
+  "names": []
+}

package/dist/features/viz/inspection/painted-point.d.ts

@@ -0,0 +1,22 @@
+import type { PointRenderedSeries } from "./capture-types.js";
+import type { RecordedNumericHit, RenderedSeriesPoint } from "./query-types.js";
+/** The original record and local geometry of a discrete circle/ring covering a query point.
+ * @see {@link RecordedNumericHit}
+ */
+export interface PaintedPointHit<D> extends RecordedNumericHit<D> {
+    /** Circle radius before world transforms, in local logical units. */
+    readonly radiusLocal: number;
+    /** Painted stroke width before world transforms, in local logical units. */
+    readonly strokeWidthLocal: number;
+}
+/**
+ * Selects the last-painted circle/ring covering a root-logical position in this series.
+ * This is geometric fill/stroke coverage, not alpha readback or a Pibbl event target.
+ * @param rendered - Borrowed point geometry from the last successful paint.
+ * @param options - Explicit root-logical query point; CSS/device pixels are unsupported.
+ * @returns Original datum/index and captured geometry, or undefined for clips, holes, omissions or singular transforms.
+ * @see {@link PaintedPointHit}
+ */
+export declare function paintedPointAt<D>(rendered: PointRenderedSeries<D>, options: {
+    rootPoint: Readonly<RenderedSeriesPoint>;
+}): PaintedPointHit<D> | undefined;

package/dist/features/viz/inspection/painted-point.js

@@ -0,0 +1,29 @@
+function paintedPointAt(rendered, options) {
+  rendered.assertLive();
+  const { x, y } = options.rootPoint;
+  if (!Number.isFinite(x) || !Number.isFinite(y))
+    throw new RangeError("paintedPointAt rootPoint must be finite.");
+  const local = rendered.localAtRoot(options.rootPoint);
+  if (!local || !rendered.anchorInsideClips(local)) return void 0;
+  for (let index = rendered.marks.length - 1; index >= 0; index--) {
+    const mark = rendered.marks[index];
+    const radius = mark.radiusLocal ?? 0, stroke = mark.strokeWidthLocal ?? 0;
+    if (radius === 0 || !mark.fill && stroke === 0) continue;
+    const distance = Math.hypot(
+      local.x - mark.anchorLocal.x,
+      local.y - mark.anchorLocal.y
+    );
+    if (distance > radius + stroke / 2 || !mark.fill && distance < Math.max(0, radius - stroke / 2))
+      continue;
+    return Object.freeze({
+      ...rendered.observations[index],
+      radiusLocal: radius,
+      strokeWidthLocal: stroke
+    });
+  }
+  return void 0;
+}
+export {
+  paintedPointAt
+};
+//# sourceMappingURL=painted-point.js.map

package/dist/features/viz/inspection/painted-point.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/painted-point.ts"],
+  "sourcesContent": ["import type { PointRenderedSeries } from \"./capture-types.js\";\nimport type { RecordedNumericHit, RenderedSeriesPoint } from \"./query-types.js\";\n\n/** The original record and local geometry of a discrete circle/ring covering a query point.\n * @see {@link RecordedNumericHit}\n */\nexport interface PaintedPointHit<D> extends RecordedNumericHit<D> {\n  /** Circle radius before world transforms, in local logical units. */\n  readonly radiusLocal: number;\n  /** Painted stroke width before world transforms, in local logical units. */\n  readonly strokeWidthLocal: number;\n}\n\n/**\n * Selects the last-painted circle/ring covering a root-logical position in this series.\n * This is geometric fill/stroke coverage, not alpha readback or a Pibbl event target.\n * @param rendered - Borrowed point geometry from the last successful paint.\n * @param options - Explicit root-logical query point; CSS/device pixels are unsupported.\n * @returns Original datum/index and captured geometry, or undefined for clips, holes, omissions or singular transforms.\n * @see {@link PaintedPointHit}\n */\nexport function paintedPointAt<D>(\n  rendered: PointRenderedSeries<D>,\n  options: { rootPoint: Readonly<RenderedSeriesPoint> },\n): PaintedPointHit<D> | undefined {\n  rendered.assertLive();\n  const { x, y } = options.rootPoint;\n  if (!Number.isFinite(x) || !Number.isFinite(y))\n    throw new RangeError(\"paintedPointAt rootPoint must be finite.\");\n  const local = rendered.localAtRoot(options.rootPoint);\n  if (!local || !rendered.anchorInsideClips(local)) return undefined;\n  for (let index = rendered.marks.length - 1; index >= 0; index--) {\n    const mark = rendered.marks[index];\n    const radius = mark.radiusLocal ?? 0,\n      stroke = mark.strokeWidthLocal ?? 0;\n    if (radius === 0 || (!mark.fill && stroke === 0)) continue;\n    const distance = Math.hypot(\n      local.x - mark.anchorLocal.x,\n      local.y - mark.anchorLocal.y,\n    );\n    if (\n      distance > radius + stroke / 2 ||\n      (!mark.fill && distance < Math.max(0, radius - stroke / 2))\n    )\n      continue;\n    return Object.freeze({\n      ...rendered.observations[index],\n      radiusLocal: radius,\n      strokeWidthLocal: stroke,\n    });\n  }\n  return undefined;\n}\n"],
+  "mappings": "AAqBO,SAAS,eACd,UACA,SACgC;AAChC,WAAS,WAAW;AACpB,QAAM,EAAE,GAAG,EAAE,IAAI,QAAQ;AACzB,MAAI,CAAC,OAAO,SAAS,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC;AAC3C,UAAM,IAAI,WAAW,0CAA0C;AACjE,QAAM,QAAQ,SAAS,YAAY,QAAQ,SAAS;AACpD,MAAI,CAAC,SAAS,CAAC,SAAS,kBAAkB,KAAK,EAAG,QAAO;AACzD,WAAS,QAAQ,SAAS,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS;AAC/D,UAAM,OAAO,SAAS,MAAM,KAAK;AACjC,UAAM,SAAS,KAAK,eAAe,GACjC,SAAS,KAAK,oBAAoB;AACpC,QAAI,WAAW,KAAM,CAAC,KAAK,QAAQ,WAAW,EAAI;AAClD,UAAM,WAAW,KAAK;AAAA,MACpB,MAAM,IAAI,KAAK,YAAY;AAAA,MAC3B,MAAM,IAAI,KAAK,YAAY;AAAA,IAC7B;AACA,QACE,WAAW,SAAS,SAAS,KAC5B,CAAC,KAAK,QAAQ,WAAW,KAAK,IAAI,GAAG,SAAS,SAAS,CAAC;AAEzD;AACF,WAAO,OAAO,OAAO;AAAA,MACnB,GAAG,SAAS,aAAa,KAAK;AAAA,MAC9B,aAAa;AAAA,MACb,kBAAkB;AAAA,IACpB,CAAC;AAAA,EACH;AACA,SAAO;AACT;",
+  "names": []
+}