@pibbl/core 0.0.2 → 0.0.3-alpha.109.1

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

@@ -0,0 +1,49 @@
+import { useRenderedRef } from "./owned-ref.js";
+function useBarInspection(_inputs) {
+  return useRenderedRef(
+    "barSeriesInspection",
+    (marks, geometry) => Object.freeze({
+      marks: Object.freeze(marks.slice()),
+      assertLive: geometry.assertLive,
+      localAtRoot: geometry.localAtRoot,
+      anchorInsideClips: geometry.anchorInsideClips
+    })
+  );
+}
+function paintedBarAt(rendered, options) {
+  rendered.assertLive();
+  if (!Number.isFinite(options.rootPoint.x) || !Number.isFinite(options.rootPoint.y))
+    throw new RangeError("paintedBarAt 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], b = mark.boundsLocal, half = mark.strokeWidthLocal / 2;
+    const inside = point.x >= b.x && point.x <= b.x + b.width && point.y >= b.y && point.y <= b.y + b.height;
+    const outline = half > 0 && point.x >= b.x - half && point.x <= b.x + b.width + half && point.y >= b.y - half && point.y <= b.y + b.height + half && !(point.x > b.x + half && point.x < b.x + b.width - half && point.y > b.y + half && point.y < b.y + b.height - half);
+    if (!(mark.fill && inside || outline)) continue;
+    const {
+      datum,
+      sourceIndex,
+      category,
+      group,
+      valueStart,
+      valueEnd,
+      boundsLocal
+    } = mark;
+    return Object.freeze({
+      datum,
+      sourceIndex,
+      category,
+      group,
+      valueStart,
+      valueEnd,
+      boundsLocal
+    });
+  }
+  return void 0;
+}
+export {
+  paintedBarAt,
+  useBarInspection
+};
+//# sourceMappingURL=bar.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/bar.ts"],
+  "sourcesContent": ["import type { LayoutBox } from \"@pibbl/core\";\nimport type { BarSeriesProps } from \"../lib/bar-series.js\";\nimport type { BandCategory } from \"../lib/types.js\";\nimport type { RenderedSeriesPoint } from \"./query-types.js\";\nimport { useRenderedRef } from \"./owned-ref.js\";\n\n/** Original range/value/grouped bar with its captured endpoints and local paint bounds.\n * @see {@link BarRenderedSeries}\n */\nexport interface PaintedBarHit<D> {\n  /** Caller-owned original record. */\n  readonly datum: D;\n  /** Original zero-based source position. */\n  readonly sourceIndex: number;\n  /** Original discrete category, without numeric coercion. */\n  readonly category: BandCategory;\n  /** Original subgroup when grouping is enabled. */\n  readonly group: BandCategory | undefined;\n  /** Data-space starting endpoint, including an ordinary bar's baseline. */\n  readonly valueStart: number;\n  /** Data-space ending endpoint. */\n  readonly valueEnd: number;\n  /** Logical rectangle bounds before world transforms. */\n  readonly boundsLocal: Readonly<LayoutBox>;\n}\n/** @internal Captured rectangle paint flags used only for geometric lookup. */\nexport interface CapturedBarMark<D> extends PaintedBarHit<D> {\n  /** Whether this rectangle paints its interior. */\n  readonly fill: boolean;\n  /** Painted stroke width in local logical units. */\n  readonly strokeWidthLocal: number;\n}\n/** A borrowed committed categorical bar generation; contains no numeric category mapping.\n * @see {@link PaintedBarHit}\n */\nexport interface BarRenderedSeries<D> {\n  /** Original records and geometry in source paint order. */\n  readonly marks: readonly CapturedBarMark<D>[];\n  /** Throws after replacement or disposal. */\n  assertLive(): void;\n  /** Converts root logical units into this generation's local geometry.\n   * @param point - Root-logical Canvas point.\n   * @returns Local point or undefined for a singular transform.\n   */\n  localAtRoot(\n    point: Readonly<RenderedSeriesPoint>,\n  ): Readonly<RenderedSeriesPoint> | undefined;\n  /** Tests a local point against every committed clip/layer bound.\n   * @param point - Local-logical Canvas point.\n   * @returns Whether the point is inside every clip and layer bound.\n   */\n  anchorInsideClips(point: Readonly<RenderedSeriesPoint>): boolean;\n}\n/** Mount-owned optional categorical-bar capture.\n * @see {@link BarRenderedSeries}\n */\nexport interface BarInspectionRef<D> {\n  /** Returns the last successful generation.\n   * @returns Borrowed bar geometry or undefined before paint/after disposal.\n   */\n  rendered(): BarRenderedSeries<D> | undefined;\n  /** @internal Records candidate values and paint geometry without executing a search.\n   * @param input - Source-ordered captured rectangle marks.\n   */\n  capture(input: readonly CapturedBarMark<D>[]): void;\n}\n\n/**\n * Owns opt-in capture for ordinary, range or grouped categorical bars.\n * @param _inputs - Bar inputs used for datum inference; no data is read or subscribed here.\n * @returns A stable ref to pass to one BarSeries inspection prop; captured endpoints share one fixed contract.\n * @see {@link BarInspectionRef}\n */\nexport function useBarInspection<D>(\n  _inputs: Pick<BarSeriesProps<D>, \"data\" | \"category\">,\n): BarInspectionRef<D> {\n  return useRenderedRef<readonly CapturedBarMark<D>[], BarRenderedSeries<D>>(\n    \"barSeriesInspection\",\n    (marks, geometry) =>\n      Object.freeze({\n        marks: Object.freeze(marks.slice()),\n        assertLive: geometry.assertLive,\n        localAtRoot: geometry.localAtRoot,\n        anchorInsideClips: geometry.anchorInsideClips,\n      }),\n  );\n}\n\n/**\n * Finds the last-painted bar covering a root-logical point in this explicit series.\n * @param rendered - Borrowed committed categorical bar values and rectangle geometry.\n * @param options - Root-logical query point; respects every clip, fill/stroke and source order.\n * @returns Original record, category/group, endpoints and local bounds, or undefined for gaps and singular transforms.\n * @see {@link PaintedBarHit}\n */\nexport function paintedBarAt<D>(\n  rendered: BarRenderedSeries<D>,\n  options: { rootPoint: Readonly<RenderedSeriesPoint> },\n): PaintedBarHit<D> | undefined {\n  rendered.assertLive();\n  if (\n    !Number.isFinite(options.rootPoint.x) ||\n    !Number.isFinite(options.rootPoint.y)\n  )\n    throw new RangeError(\"paintedBarAt 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      b = mark.boundsLocal,\n      half = mark.strokeWidthLocal / 2;\n    const inside =\n      point.x >= b.x &&\n      point.x <= b.x + b.width &&\n      point.y >= b.y &&\n      point.y <= b.y + b.height;\n    const outline =\n      half > 0 &&\n      point.x >= b.x - half &&\n      point.x <= b.x + b.width + half &&\n      point.y >= b.y - half &&\n      point.y <= b.y + b.height + half &&\n      !(\n        point.x > b.x + half &&\n        point.x < b.x + b.width - half &&\n        point.y > b.y + half &&\n        point.y < b.y + b.height - half\n      );\n    if (!((mark.fill && inside) || outline)) continue;\n    const {\n      datum,\n      sourceIndex,\n      category,\n      group,\n      valueStart,\n      valueEnd,\n      boundsLocal,\n    } = mark;\n    return Object.freeze({\n      datum,\n      sourceIndex,\n      category,\n      group,\n      valueStart,\n      valueEnd,\n      boundsLocal,\n    });\n  }\n  return undefined;\n}\n"],
+  "mappings": "AAIA,SAAS,sBAAsB;AAqExB,SAAS,iBACd,SACqB;AACrB,SAAO;AAAA,IACL;AAAA,IACA,CAAC,OAAO,aACN,OAAO,OAAO;AAAA,MACZ,OAAO,OAAO,OAAO,MAAM,MAAM,CAAC;AAAA,MAClC,YAAY,SAAS;AAAA,MACrB,aAAa,SAAS;AAAA,MACtB,mBAAmB,SAAS;AAAA,IAC9B,CAAC;AAAA,EACL;AACF;AASO,SAAS,aACd,UACA,SAC8B;AAC9B,WAAS,WAAW;AACpB,MACE,CAAC,OAAO,SAAS,QAAQ,UAAU,CAAC,KACpC,CAAC,OAAO,SAAS,QAAQ,UAAU,CAAC;AAEpC,UAAM,IAAI,WAAW,wCAAwC;AAC/D,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,GAC/B,IAAI,KAAK,aACT,OAAO,KAAK,mBAAmB;AACjC,UAAM,SACJ,MAAM,KAAK,EAAE,KACb,MAAM,KAAK,EAAE,IAAI,EAAE,SACnB,MAAM,KAAK,EAAE,KACb,MAAM,KAAK,EAAE,IAAI,EAAE;AACrB,UAAM,UACJ,OAAO,KACP,MAAM,KAAK,EAAE,IAAI,QACjB,MAAM,KAAK,EAAE,IAAI,EAAE,QAAQ,QAC3B,MAAM,KAAK,EAAE,IAAI,QACjB,MAAM,KAAK,EAAE,IAAI,EAAE,SAAS,QAC5B,EACE,MAAM,IAAI,EAAE,IAAI,QAChB,MAAM,IAAI,EAAE,IAAI,EAAE,QAAQ,QAC1B,MAAM,IAAI,EAAE,IAAI,QAChB,MAAM,IAAI,EAAE,IAAI,EAAE,SAAS;AAE/B,QAAI,EAAG,KAAK,QAAQ,UAAW,SAAU;AACzC,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,IAAI;AACJ,WAAO,OAAO,OAAO;AAAA,MACnB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/features/viz/inspection/candle.d.ts

@@ -0,0 +1,156 @@
+import type { LayoutBox } from "@pibbl/core";
+import type { CandlestickSeriesProps } from "../lib/candlestick-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 candle with its evaluated OHLC values and committed local geometry.
+ * @see {@link CandleRenderedSeries}
+ */
+export interface CandleObservation<D> {
+    /** Caller-owned original record. */
+    readonly datum: D;
+    /** Original source index, including skipped records. */
+    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 logical units. */
+    readonly anchorLocal: Readonly<RenderedSeriesPoint>;
+    /** Closing endpoint in root-logical units. */
+    readonly anchorRoot: Readonly<RenderedSeriesPoint>;
+    /** Body rectangle before world transforms. */
+    readonly bodyBoundsLocal: Readonly<LayoutBox>;
+    /** Wick center and endpoints before world transforms. */
+    readonly wickLocal: Readonly<{
+        /** Horizontal wick center in series-local logical units. */
+        x: number;
+        /** Mapped low endpoint in series-local logical units. */
+        lowY: number;
+        /** Mapped high endpoint in series-local logical units. */
+        highY: number;
+    }>;
+}
+/** A candle candidate whose closing endpoint can be tested against committed clips.
+ * @see {@link CandleObservation}
+ */
+export interface CandleInspectionCandidate<D> extends CandleObservation<D> {
+    /**
+     * @returns Whether the close anchor lies inside every committed clip.
+     */
+    anchorInsideClips(): boolean;
+}
+/** Candle selected by nearest timestamp.
+ * @see {@link nearestRecordedCandleX}
+ */
+export interface NearestCandleHit<D> extends CandleObservation<D> {
+    /** Absolute UTC-millisecond distance from the requested timestamp. */
+    readonly timeDelta: number;
+}
+/** Candle part whose actual painted geometry covers a root-logical query point.
+ * @see {@link paintedCandleAt}
+ */
+export interface PaintedCandleHit<D> extends CandleObservation<D> {
+    /** Part selected in source paint order: body paints after wick. */
+    readonly part: "body" | "wick";
+}
+/** @internal Local candle geometry and paint flags committed by CandlestickSeries. */
+export interface CapturedCandleMark<D> extends Omit<CandleObservation<D>, "anchorRoot"> {
+    /** Whether the body paints an interior. */
+    readonly bodyFill: boolean;
+    /** Local body outline width, zero when its outline is not painted. */
+    readonly bodyStrokeWidthLocal: number;
+    /** Local wick stroke width, zero when its wick is not painted. */
+    readonly wickStrokeWidthLocal: number;
+}
+/** Borrowed committed candle generation.
+ * @see {@link CandleInspectionRef}
+ */
+export interface CandleRenderedSeries<D> {
+    /** Captured original records, values, and geometry in source order. */
+    readonly observations: readonly CandleObservation<D>[];
+    /** Throws after replacement or disposal. */
+    assertLive(): void;
+    /**
+     * Selects the supplied/nearest timestamp at a root-logical coordinate.
+     * @param pointRoot - Root-logical point to invert through the committed transform.
+     * @returns UTC milliseconds, or undefined for singular transforms or empty mappings.
+     */
+    timeAtRoot(pointRoot: Readonly<RenderedSeriesPoint>): number | undefined;
+    /**
+     * Tests local geometry against each committed clip.
+     * @param pointLocal - Series-local logical point.
+     * @returns Whether every committed clip contains the point.
+     */
+    anchorInsideClips(pointLocal: Readonly<RenderedSeriesPoint>): boolean;
+    /** @internal Captured paint flags in source paint order. */
+    readonly marks: readonly CapturedCandleMark<D>[];
+    /** @internal Numeric-query view based on close endpoints. */
+    readonly numeric: NumericRenderedSeries<D>;
+    /**
+     * @internal Converts root-logical points to local geometry.
+     * @param point - Root-logical point to convert.
+     * @returns Series-local point, or undefined when the transform is singular.
+     */
+    localAtRoot(point: Readonly<RenderedSeriesPoint>): Readonly<RenderedSeriesPoint> | undefined;
+}
+/** Mount-owned optional candle capture.
+ * @see {@link useCandleInspection}
+ */
+export interface CandleInspectionRef<D> {
+    /**
+     * @returns The current borrowed generation, or undefined before paint and after disposal.
+     */
+    rendered(): CandleRenderedSeries<D> | undefined;
+    /**
+     * @internal Records a completed CandlestickSeries paint without executing queries.
+     * @param input - Source-ordered marks and the committed numeric mappings.
+     */
+    capture(input: {
+        /** Source-ordered local marks and paint flags. */
+        marks: readonly CapturedCandleMark<D>[];
+        /** Committed numeric or trading-time horizontal mapping. */
+        xScale: NumericPositionScale;
+        /** Committed continuous vertical mapping. */
+        yScale: ResolvedContinuousScale;
+    }): void;
+}
+/**
+ * Creates a stable optional candle receiver without reading data or subscribing.
+ *
+ * @param _inputs - Inputs retained only to infer the original datum type.
+ * @returns A ref for exactly one CandlestickSeries inspection prop.
+ * @see {@link CandleInspectionRef}
+ */
+export declare function useCandleInspection<D>(_inputs: Pick<CandlestickSeriesProps<D>, "data" | "time" | "open" | "high" | "low" | "close">): CandleInspectionRef<D>;
+/**
+ * Selects a captured candle nearest to a requested UTC timestamp.
+ *
+ * @param rendered - Borrowed committed candle generation.
+ * @param options - Timestamp and optional pure candidate filter.
+ * @returns The first source-order candle on a tie, or undefined when none qualifies.
+ * @see {@link NearestCandleHit}
+ */
+export declare function nearestRecordedCandleX<D>(rendered: CandleRenderedSeries<D>, options: {
+    time: number;
+    filter?: (observation: CandleInspectionCandidate<D>) => boolean;
+}): NearestCandleHit<D> | undefined;
+/**
+ * Finds the last-painted candle body or wick covering a root-logical point.
+ *
+ * Body coverage is tested before wick coverage because a candle paints its body after its wick.
+ *
+ * @param rendered - Borrowed committed candle generation.
+ * @param options - Root-logical point; clips and singular transforms produce no result.
+ * @returns Captured candle and painted part, or undefined for gaps and unpainted geometry.
+ * @see {@link PaintedCandleHit}
+ */
+export declare function paintedCandleAt<D>(rendered: CandleRenderedSeries<D>, options: {
+    rootPoint: Readonly<RenderedSeriesPoint>;
+}): PaintedCandleHit<D> | undefined;

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

@@ -0,0 +1,120 @@
+import {
+  invertNumericPosition
+} from "../lib/series-position.js";
+import { nearestRecordedX } from "./queries.js";
+import { useRenderedRef } from "./owned-ref.js";
+function useCandleInspection(_inputs) {
+  return useRenderedRef("candleInspection", (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),
+          bodyBoundsLocal: mark.bodyBoundsLocal,
+          wickLocal: mark.wickLocal
+        })
+      )
+    );
+    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 nearestRecordedCandleX(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 rectangleCovers(point, bounds, fill, strokeWidth) {
+  const half = strokeWidth / 2;
+  const inside = point.x >= bounds.x && point.x <= bounds.x + bounds.width && point.y >= bounds.y && point.y <= bounds.y + bounds.height;
+  const outline = half > 0 && point.x >= bounds.x - half && point.x <= bounds.x + bounds.width + half && point.y >= bounds.y - half && point.y <= bounds.y + bounds.height + half && !(point.x > bounds.x + half && point.x < bounds.x + bounds.width - half && point.y > bounds.y + half && point.y < bounds.y + bounds.height - half);
+  return fill && inside || outline;
+}
+function wickCovers(point, wick, strokeWidth) {
+  if (strokeWidth <= 0 || wick.lowY === wick.highY) return false;
+  const half = strokeWidth / 2;
+  return point.x >= wick.x - half && point.x <= wick.x + half && point.y >= Math.min(wick.lowY, wick.highY) && point.y <= Math.max(wick.lowY, wick.highY);
+}
+function paintedCandleAt(rendered, options) {
+  rendered.assertLive();
+  if (!Number.isFinite(options.rootPoint.x) || !Number.isFinite(options.rootPoint.y))
+    throw new RangeError("paintedCandleAt 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 (rectangleCovers(
+      point,
+      mark.bodyBoundsLocal,
+      mark.bodyFill,
+      mark.bodyStrokeWidthLocal
+    ))
+      return Object.freeze({
+        ...rendered.observations[index],
+        part: "body"
+      });
+    if (wickCovers(point, mark.wickLocal, mark.wickStrokeWidthLocal))
+      return Object.freeze({
+        ...rendered.observations[index],
+        part: "wick"
+      });
+  }
+  return void 0;
+}
+export {
+  nearestRecordedCandleX,
+  paintedCandleAt,
+  useCandleInspection
+};
+//# sourceMappingURL=candle.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/candle.ts"],
+  "sourcesContent": ["import type { LayoutBox } from \"@pibbl/core\";\nimport type { CandlestickSeriesProps } from \"../lib/candlestick-series.js\";\nimport {\n  invertNumericPosition,\n  type NumericPositionScale,\n} from \"../lib/series-position.js\";\nimport type { ResolvedContinuousScale } from \"../lib/types.js\";\nimport type {\n  NumericRenderedSeries,\n  RenderedSeriesPoint,\n} from \"./query-types.js\";\nimport { nearestRecordedX } from \"./queries.js\";\nimport { useRenderedRef } from \"./owned-ref.js\";\n\n/** One original candle with its evaluated OHLC values and committed local geometry.\n * @see {@link CandleRenderedSeries}\n */\nexport interface CandleObservation<D> {\n  /** Caller-owned original record. */\n  readonly datum: D;\n  /** Original source index, including skipped records. */\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 logical units. */\n  readonly anchorLocal: Readonly<RenderedSeriesPoint>;\n  /** Closing endpoint in root-logical units. */\n  readonly anchorRoot: Readonly<RenderedSeriesPoint>;\n  /** Body rectangle before world transforms. */\n  readonly bodyBoundsLocal: Readonly<LayoutBox>;\n  /** Wick center and endpoints before world transforms. */\n  readonly wickLocal: Readonly<{\n    /** Horizontal wick center in series-local logical units. */\n    x: number;\n    /** Mapped low endpoint in series-local logical units. */\n    lowY: number;\n    /** Mapped high endpoint in series-local logical units. */\n    highY: number;\n  }>;\n}\n\n/** A candle candidate whose closing endpoint can be tested against committed clips.\n * @see {@link CandleObservation}\n */\nexport interface CandleInspectionCandidate<D> extends CandleObservation<D> {\n  /**\n   * @returns Whether the close anchor lies inside every committed clip.\n   */\n  anchorInsideClips(): boolean;\n}\n\n/** Candle selected by nearest timestamp.\n * @see {@link nearestRecordedCandleX}\n */\nexport interface NearestCandleHit<D> extends CandleObservation<D> {\n  /** Absolute UTC-millisecond distance from the requested timestamp. */\n  readonly timeDelta: number;\n}\n\n/** Candle part whose actual painted geometry covers a root-logical query point.\n * @see {@link paintedCandleAt}\n */\nexport interface PaintedCandleHit<D> extends CandleObservation<D> {\n  /** Part selected in source paint order: body paints after wick. */\n  readonly part: \"body\" | \"wick\";\n}\n\n/** @internal Local candle geometry and paint flags committed by CandlestickSeries. */\nexport interface CapturedCandleMark<D> extends Omit<\n  CandleObservation<D>,\n  \"anchorRoot\"\n> {\n  /** Whether the body paints an interior. */\n  readonly bodyFill: boolean;\n  /** Local body outline width, zero when its outline is not painted. */\n  readonly bodyStrokeWidthLocal: number;\n  /** Local wick stroke width, zero when its wick is not painted. */\n  readonly wickStrokeWidthLocal: number;\n}\n\n/** Borrowed committed candle generation.\n * @see {@link CandleInspectionRef}\n */\nexport interface CandleRenderedSeries<D> {\n  /** Captured original records, values, and geometry in source order. */\n  readonly observations: readonly CandleObservation<D>[];\n  /** Throws after replacement or disposal. */\n  assertLive(): void;\n  /**\n   * Selects the supplied/nearest timestamp at a root-logical coordinate.\n   * @param pointRoot - Root-logical point to invert through the committed transform.\n   * @returns UTC milliseconds, or undefined for singular transforms or empty mappings.\n   */\n  timeAtRoot(pointRoot: Readonly<RenderedSeriesPoint>): number | undefined;\n  /**\n   * Tests local geometry against each committed clip.\n   * @param pointLocal - Series-local logical point.\n   * @returns Whether every committed clip contains the point.\n   */\n  anchorInsideClips(pointLocal: Readonly<RenderedSeriesPoint>): boolean;\n  /** @internal Captured paint flags in source paint order. */\n  readonly marks: readonly CapturedCandleMark<D>[];\n  /** @internal Numeric-query view based on close endpoints. */\n  readonly numeric: NumericRenderedSeries<D>;\n  /**\n   * @internal Converts root-logical points to local geometry.\n   * @param point - Root-logical point to convert.\n   * @returns Series-local point, or undefined when the transform is singular.\n   */\n  localAtRoot(\n    point: Readonly<RenderedSeriesPoint>,\n  ): Readonly<RenderedSeriesPoint> | undefined;\n}\n\n/** Mount-owned optional candle capture.\n * @see {@link useCandleInspection}\n */\nexport interface CandleInspectionRef<D> {\n  /**\n   * @returns The current borrowed generation, or undefined before paint and after disposal.\n   */\n  rendered(): CandleRenderedSeries<D> | undefined;\n  /**\n   * @internal Records a completed CandlestickSeries paint without executing queries.\n   * @param input - Source-ordered marks and the committed numeric mappings.\n   */\n  capture(input: {\n    /** Source-ordered local marks and paint flags. */\n    marks: readonly CapturedCandleMark<D>[];\n    /** Committed numeric or trading-time horizontal mapping. */\n    xScale: NumericPositionScale;\n    /** Committed continuous vertical mapping. */\n    yScale: ResolvedContinuousScale;\n  }): void;\n}\n\n/**\n * Creates a stable optional candle receiver without reading data or subscribing.\n *\n * @param _inputs - Inputs retained only to infer the original datum type.\n * @returns A ref for exactly one CandlestickSeries inspection prop.\n * @see {@link CandleInspectionRef}\n */\nexport function useCandleInspection<D>(\n  _inputs: Pick<\n    CandlestickSeriesProps<D>,\n    \"data\" | \"time\" | \"open\" | \"high\" | \"low\" | \"close\"\n  >,\n): CandleInspectionRef<D> {\n  return useRenderedRef<\n    {\n      marks: readonly CapturedCandleMark<D>[];\n      xScale: NumericPositionScale;\n      yScale: ResolvedContinuousScale;\n    },\n    CandleRenderedSeries<D>\n  >(\"candleInspection\", (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          bodyBoundsLocal: mark.bodyBoundsLocal,\n          wickLocal: mark.wickLocal,\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/**\n * Selects a captured candle nearest to a requested UTC timestamp.\n *\n * @param rendered - Borrowed committed candle generation.\n * @param options - Timestamp and optional pure candidate filter.\n * @returns The first source-order candle on a tie, or undefined when none qualifies.\n * @see {@link NearestCandleHit}\n */\nexport function nearestRecordedCandleX<D>(\n  rendered: CandleRenderedSeries<D>,\n  options: {\n    time: number;\n    filter?: (observation: CandleInspectionCandidate<D>) => boolean;\n  },\n): NearestCandleHit<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 & CandleInspectionCandidate<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 rectangleCovers(\n  point: Readonly<RenderedSeriesPoint>,\n  bounds: Readonly<LayoutBox>,\n  fill: boolean,\n  strokeWidth: number,\n): boolean {\n  const half = strokeWidth / 2;\n  const inside =\n    point.x >= bounds.x &&\n    point.x <= bounds.x + bounds.width &&\n    point.y >= bounds.y &&\n    point.y <= bounds.y + bounds.height;\n  const outline =\n    half > 0 &&\n    point.x >= bounds.x - half &&\n    point.x <= bounds.x + bounds.width + half &&\n    point.y >= bounds.y - half &&\n    point.y <= bounds.y + bounds.height + half &&\n    !(\n      point.x > bounds.x + half &&\n      point.x < bounds.x + bounds.width - half &&\n      point.y > bounds.y + half &&\n      point.y < bounds.y + bounds.height - half\n    );\n  return (fill && inside) || outline;\n}\n\nfunction wickCovers(\n  point: Readonly<RenderedSeriesPoint>,\n  wick: Readonly<{ x: number; lowY: number; highY: number }>,\n  strokeWidth: number,\n): boolean {\n  if (strokeWidth <= 0 || wick.lowY === wick.highY) return false;\n  const half = strokeWidth / 2;\n  return (\n    point.x >= wick.x - half &&\n    point.x <= wick.x + half &&\n    point.y >= Math.min(wick.lowY, wick.highY) &&\n    point.y <= Math.max(wick.lowY, wick.highY)\n  );\n}\n\n/**\n * Finds the last-painted candle body or wick covering a root-logical point.\n *\n * Body coverage is tested before wick coverage because a candle paints its body after its wick.\n *\n * @param rendered - Borrowed committed candle generation.\n * @param options - Root-logical point; clips and singular transforms produce no result.\n * @returns Captured candle and painted part, or undefined for gaps and unpainted geometry.\n * @see {@link PaintedCandleHit}\n */\nexport function paintedCandleAt<D>(\n  rendered: CandleRenderedSeries<D>,\n  options: { rootPoint: Readonly<RenderedSeriesPoint> },\n): PaintedCandleHit<D> | undefined {\n  rendered.assertLive();\n  if (\n    !Number.isFinite(options.rootPoint.x) ||\n    !Number.isFinite(options.rootPoint.y)\n  )\n    throw new RangeError(\"paintedCandleAt 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 (\n      rectangleCovers(\n        point,\n        mark.bodyBoundsLocal,\n        mark.bodyFill,\n        mark.bodyStrokeWidthLocal,\n      )\n    )\n      return Object.freeze({\n        ...rendered.observations[index]!,\n        part: \"body\" as const,\n      });\n    if (wickCovers(point, mark.wickLocal, mark.wickStrokeWidthLocal))\n      return Object.freeze({\n        ...rendered.observations[index]!,\n        part: \"wick\" as const,\n      });\n  }\n  return undefined;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/viz/inspection/capture-types.d.ts

@@ -0,0 +1,65 @@
+import type { NumericRenderedSeries, RenderedSeriesPoint } from "./query-types.js";
+/** Values evaluated by a numeric series, before applying its world transform. */
+export interface CapturedNumericObservation<D> {
+    /** Original caller-owned record. */
+    readonly datum: D;
+    /** Original zero-based source position, including skipped rows. */
+    readonly sourceIndex: number;
+    /** Horizontal data-space value. */
+    readonly domainX: number;
+    /** Vertical data-space value. */
+    readonly domainY: number;
+    /** Local logical anchor before world transforms. */
+    readonly anchorLocal: Readonly<RenderedSeriesPoint>;
+    /** Contiguous valid run identity; interpolation cannot cross runs. */
+    readonly run: number;
+    /** Optional local circle radius captured for discrete point geometry. */
+    readonly radiusLocal?: number;
+    /** Whether the mark has geometric fill coverage. */
+    readonly fill?: boolean;
+    /** Local painted stroke width, zero when absent. */
+    readonly strokeWidthLocal?: number;
+}
+/** Structural capture input used by renderers; no query is executed by capture. */
+export interface NumericSeriesCapture<D> {
+    /** Evaluated values and geometry owned by this candidate generation. */
+    readonly observations: readonly CapturedNumericObservation<D>[];
+    /** Captured numeric x mapping and inversion. */
+    readonly xScale: import("../lib/series-position.js").NumericPositionScale;
+    /** Captured numeric y mapping for explicit interpolation anchors. */
+    readonly yScale: import("../lib/series-position.js").NumericPositionScale;
+}
+/** Optional renderer sink and mount-owned access to the last successful paint.
+ * @see {@link NumericRenderedSeries}
+ */
+export interface NumericInspectionRef<D> {
+    /** Returns borrowed rendered values.
+     * @returns Current committed generation, or undefined before paint/after disposal.
+     */
+    rendered(): NumericRenderedSeries<D> | undefined;
+    /** @internal Records a candidate; publishes only after successful root rendering.
+     * @param input - Values evaluated by the receiver in source order.
+     */
+    capture(input: NumericSeriesCapture<D>): void;
+}
+/** Rendered numeric points with committed circle/ring geometry.
+ * @see {@link NumericRenderedSeries}
+ */
+export interface PointRenderedSeries<D> extends NumericRenderedSeries<D> {
+    /** @internal Borrowed geometry corresponding to observations in source order. */
+    readonly marks: readonly CapturedNumericObservation<D>[];
+    /** @internal Maps a root-logical point to this committed local frame.
+     * @param point - Root-logical Canvas coordinates.
+     * @returns Local coordinates, or undefined for a singular transform.
+     */
+    localAtRoot(point: Readonly<RenderedSeriesPoint>): Readonly<RenderedSeriesPoint> | undefined;
+}
+/** Mount-owned point capture; queries are imported independently.
+ * @see {@link PointRenderedSeries}
+ */
+export interface PointInspectionRef<D> extends NumericInspectionRef<D> {
+    /** Returns borrowed point geometry.
+     * @returns Current point generation, or undefined before paint/after disposal.
+     */
+    rendered(): PointRenderedSeries<D> | undefined;
+}

package/dist/features/viz/inspection/capture.d.ts

@@ -0,0 +1,16 @@
+import type { HoverSeries } from "../lib/hover-types.js";
+import type { NumericInspectionRef, PointInspectionRef } from "./capture-types.js";
+/**
+ * Owns optional numeric capture without reading signals or executing queries.
+ * @param _series - Typed descriptor used for datum inference; not observed or registered.
+ * @returns A stable mount-owned capture ref; pass it to one numeric series' inspection prop.
+ * @see {@link NumericInspectionRef}
+ */
+export declare function useNumericInspection<D>(_series: HoverSeries<D>): NumericInspectionRef<D>;
+/**
+ * Owns optional circle/ring capture for one PointSeries; O(n) retained geometry when enabled.
+ * @param _series - Typed descriptor used for datum inference; not observed or registered.
+ * @returns A stable point inspection ref. Rendered records are borrowed until replacement/disposal.
+ * @see {@link PointInspectionRef}
+ */
+export declare function usePointInspection<D>(_series: HoverSeries<D>): PointInspectionRef<D>;

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

@@ -0,0 +1,49 @@
+import { invertNumericPosition } from "../lib/series-position.js";
+import { useRenderedRef } from "./owned-ref.js";
+function useCapture() {
+  return useRenderedRef(
+    "numericSeriesInspection",
+    (candidate, geometry) => {
+      const rows = candidate.observations.map(
+        (row) => Object.freeze({
+          ...row,
+          anchorLocal: Object.freeze({ ...row.anchorLocal }),
+          anchorRoot: geometry.rootAtLocal(row.anchorLocal)
+        })
+      );
+      return Object.freeze({
+        observations: Object.freeze(rows),
+        marks: Object.freeze(candidate.observations.slice()),
+        assertLive: geometry.assertLive,
+        localAtRoot: geometry.localAtRoot,
+        anchorInsideClips: geometry.anchorInsideClips,
+        domainXAtRoot(point) {
+          const local = geometry.localAtRoot(point);
+          return local ? invertNumericPosition(candidate.xScale, local.x) : void 0;
+        },
+        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)
+          });
+        }
+      });
+    }
+  );
+}
+function useNumericInspection(_series) {
+  return useCapture();
+}
+function usePointInspection(_series) {
+  return useCapture();
+}
+export {
+  useNumericInspection,
+  usePointInspection
+};
+//# sourceMappingURL=capture.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/inspection/capture.ts"],
+  "sourcesContent": ["import { invertNumericPosition } from \"../lib/series-position.js\";\nimport { useRenderedRef } from \"./owned-ref.js\";\nimport type { HoverSeries } from \"../lib/hover-types.js\";\nimport type {\n  NumericSeriesCapture,\n  NumericInspectionRef,\n  PointInspectionRef,\n  PointRenderedSeries,\n} from \"./capture-types.js\";\n\nfunction useCapture<D>(): PointInspectionRef<D> {\n  return useRenderedRef<NumericSeriesCapture<D>, PointRenderedSeries<D>>(\n    \"numericSeriesInspection\",\n    (candidate, geometry) => {\n      const rows = candidate.observations.map((row) =>\n        Object.freeze({\n          ...row,\n          anchorLocal: Object.freeze({ ...row.anchorLocal }),\n          anchorRoot: geometry.rootAtLocal(row.anchorLocal),\n        }),\n      );\n      return Object.freeze({\n        observations: Object.freeze(rows),\n        marks: Object.freeze(candidate.observations.slice()),\n        assertLive: geometry.assertLive,\n        localAtRoot: geometry.localAtRoot,\n        anchorInsideClips: geometry.anchorInsideClips,\n        domainXAtRoot(point: Readonly<{ x: number; y: number }>) {\n          const local = geometry.localAtRoot(point);\n          return local\n            ? invertNumericPosition(candidate.xScale, local.x)\n            : undefined;\n        },\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    },\n  );\n}\n\n/**\n * Owns optional numeric capture without reading signals or executing queries.\n * @param _series - Typed descriptor used for datum inference; not observed or registered.\n * @returns A stable mount-owned capture ref; pass it to one numeric series' inspection prop.\n * @see {@link NumericInspectionRef}\n */\nexport function useNumericInspection<D>(\n  _series: HoverSeries<D>,\n): NumericInspectionRef<D> {\n  return useCapture<D>();\n}\n\n/**\n * Owns optional circle/ring capture for one PointSeries; O(n) retained geometry when enabled.\n * @param _series - Typed descriptor used for datum inference; not observed or registered.\n * @returns A stable point inspection ref. Rendered records are borrowed until replacement/disposal.\n * @see {@link PointInspectionRef}\n */\nexport function usePointInspection<D>(\n  _series: HoverSeries<D>,\n): PointInspectionRef<D> {\n  return useCapture<D>();\n}\n"],
+  "mappings": "AAAA,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAS/B,SAAS,aAAuC;AAC9C,SAAO;AAAA,IACL;AAAA,IACA,CAAC,WAAW,aAAa;AACvB,YAAM,OAAO,UAAU,aAAa;AAAA,QAAI,CAAC,QACvC,OAAO,OAAO;AAAA,UACZ,GAAG;AAAA,UACH,aAAa,OAAO,OAAO,EAAE,GAAG,IAAI,YAAY,CAAC;AAAA,UACjD,YAAY,SAAS,YAAY,IAAI,WAAW;AAAA,QAClD,CAAC;AAAA,MACH;AACA,aAAO,OAAO,OAAO;AAAA,QACnB,cAAc,OAAO,OAAO,IAAI;AAAA,QAChC,OAAO,OAAO,OAAO,UAAU,aAAa,MAAM,CAAC;AAAA,QACnD,YAAY,SAAS;AAAA,QACrB,aAAa,SAAS;AAAA,QACtB,mBAAmB,SAAS;AAAA,QAC5B,cAAc,OAA2C;AACvD,gBAAM,QAAQ,SAAS,YAAY,KAAK;AACxC,iBAAO,QACH,sBAAsB,UAAU,QAAQ,MAAM,CAAC,IAC/C;AAAA,QACN;AAAA,QACA,eAAe,OAAuD;AACpE,mBAAS,WAAW;AACpB,gBAAM,cAAc,OAAO,OAAO;AAAA,YAChC,GAAG,UAAU,OAAO,IAAI,MAAM,OAAO;AAAA,YACrC,GAAG,UAAU,OAAO,IAAI,MAAM,OAAO;AAAA,UACvC,CAAC;AACD,iBAAO,OAAO,OAAO;AAAA,YACnB;AAAA,YACA,YAAY,SAAS,YAAY,WAAW;AAAA,UAC9C,CAAC;AAAA,QACH;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAQO,SAAS,qBACd,SACyB;AACzB,SAAO,WAAc;AACvB;AAQO,SAAS,mBACd,SACuB;AACvB,SAAO,WAAc;AACvB;",
+  "names": []
+}

package/dist/features/viz/inspection/handler.d.ts

@@ -0,0 +1,36 @@
+import type { PibblEvent } from "@pibbl/core";
+/** A mount-owned source of borrowed committed render records.
+ * @see {@link InspectionContext}
+ */
+export interface InspectionRef<S> {
+    /** Returns the current committed record.
+     * @returns Borrowed record or undefined before paint/after disposal.
+     */
+    rendered(): S | undefined;
+}
+/** Lazy synchronous inspection; expires when its handler returns.
+ * @see {@link InspectionRef}
+ */
+export interface InspectionContext {
+    /** Pins one receiver's committed generation for this logical dispatch.
+     * @param ref - Explicit ref identifying the mounted receiver.
+     * @returns Borrowed generation or undefined before paint/after disposal.
+     */
+    rendered<S>(ref: InspectionRef<S>): S | undefined;
+    /**
+     * Executes only on demand and memoizes equal requests, including no result.
+     * Options contain plain scalar fields, function identities and logical points.
+     * @param query - Pure synchronous query with a stable result contract.
+     * @param rendered - Committed generation pinned for this request.
+     * @param options - Named query parameters; functions compare by identity.
+     * @returns Query result, including undefined, reused for equal requests in dispatch.
+     */
+    request<S, A, R>(query: (rendered: S, options: A) => R, rendered: S, options: A): R;
+}
+/**
+ * Adapts an ordinary handler to lazy typed inspection without changing its event.
+ * @param handler - Synchronous callback receiving the unchanged event and an expiring context.
+ * @returns An ordinary event handler. Searches occur only on request; memo state releases at dispatch end.
+ * @see {@link InspectionContext}
+ */
+export declare function withInspection<E extends PibblEvent>(handler: (event: E, context: InspectionContext) => void): (event: E) => void;