Rendered series inspection

Read as Markdown

Import from @pibbl/core/viz/inspection. Rendering-only applications can omit this entry. Pass an optional inspection ref to one mounted series:

import { signal, type PibblLogicalMouseEvent } from "@pibbl/core";
import {
  PointSeries,
  defineSeries,
  linearInterpolation,
} from "@pibbl/core/viz";
import {
  anchorInsideClips,
  lastSourceObservation,
  nearestRecordedX,
  sampleRecordedX,
  usePointInspection,
  withInspection,
} from "@pibbl/core/viz/inspection";

function InspectedPoints() {
  const series = defineSeries({
    data: [{ time: 0, price: 10 }],
    x: "time",
    y: "price",
  });
  const inspection = usePointInspection(series);
  return (
    <PointSeries
      {...series}
      xScale="time"
      yScale="price"
      inspection={inspection}
    />
  );
}

useNumericInspection(series) captures numeric line/point observations. usePointInspection(series) also exposes point circle/ring geometry. useBarInspection(inputs) captures value, range and grouped categorical bars. Descriptors supply datum inference; hooks do not read data, subscribe to signals, build indexes or run queries. The renderer records values it already evaluated. Numeric capture requires continuous numeric scales; categorical point/line inspection is not currently supported. Category/group identity in bars remains its original string or number.

Standalone queries

function QueryNearest() {
  const series = defineSeries({
    data: [{ time: 0, price: 10 }],
    x: "time",
    y: "price",
  });
  const inspection = usePointInspection(series);
  const rendered = inspection.rendered();
  if (rendered) {
    const hit = nearestRecordedX(rendered, { domainX: 8 });
    console.log(hit?.datum, hit?.sourceIndex, hit?.domainY);
  }
  return <PointSeries {...series} xScale="time" yScale="price" inspection={inspection} />;
}

nearestRecordedX selects by absolute horizontal domain distance, returning domainDelta. nearestRecordedPoint accepts rootPoint and returns Euclidean rootDistance. Equal distances choose the first source observation. Limits are inclusive (maxDomainDelta, maxRootDistance); a missing requested domain x, empty data or no qualifying row returns undefined. Invalid finite-coordinate or negative-limit inputs throw actionable errors. These selections are not event targets and do not require marks to cover the query point.

Results preserve the original typed datum, zero-based sourceIndex, captured domainX/domainY, anchorLocal and anchorRoot. Domain units follow the scales, such as UTC milliseconds. Local anchors are series-local logical Canvas units; root anchors/distances use root-logical Canvas units, not CSS/device pixels. rendered.domainXAtRoot(rootPoint) uses the captured inverse transform and scale. A singular transform yields undefined for inversion and painted lookup.

No filter means all finite observations accepted by the renderer’s defined predicate participate, including offscreen anchors. An optional pure filter(candidate) additionally restricts that request:

function QueryVisibleNearest() {
  const series = defineSeries({
    data: [{ time: 0, price: 10 }],
    x: "time",
    y: "price",
  });
  const inspection = usePointInspection(series);
  const rendered = inspection.rendered();
  if (rendered)
    nearestRecordedX(rendered, {
      domainX: 8,
      filter: anchorInsideClips,
    });
  return <PointSeries {...series} xScale="time" yScale="price" inspection={inspection} />;
}

anchorInsideClips tests the observation anchor against every committed clip and Layer bound. It does not test scene-wide occlusion. Custom filters receive the original datum/index, captured values/anchors and an anchorInsideClips() method; false removes that row from consideration. Filters cannot restore undefined rows and do not change what is rendered.

Explicit interpolation

function QueryInterpolatedSample() {
  const series = defineSeries({
    data: [{ time: 0, price: 10 }],
    x: "time",
    y: "price",
  });
  const inspection = usePointInspection(series);
  const rendered = inspection.rendered();
  if (rendered)
    sampleRecordedX(rendered, {
      domainX: 8,
      interpolation: linearInterpolation(),
      resolveDuplicate: lastSourceObservation,
    });
  return <PointSeries {...series} xScale="time" yScale="price" inspection={inspection} />;
}

sampleRecordedX returns kind: "exact" with an original record, or kind: "interpolated" with both original observations (including source indices), fraction, domain values and mapped local/root anchors. An estimate has no invented datum. Input x must be nondecreasing within each valid run. Missing/excluded rows and filter rejections split runs; interpolation never bridges them or extrapolates. maxDomainGap rejects larger intervals. Duplicate x rejects by default. An optional resolveDuplicate(first, next) must return one of those supplied observations; firstSourceObservation and lastSourceObservation are ordinary imported resolver functions. Interpolation and resolver callbacks must be pure, synchronous and return valid values.

Lazy ordinary handlers

function ClickSelection() {
  const series = defineSeries({
    data: [{ time: 0, price: 10 }],
    x: "time",
    y: "price",
  });
  const inspection = usePointInspection(series);
  const selection = signal<{ time: number; price: number } | null>(null);
  const onClick = withInspection<PibblLogicalMouseEvent>((event, context) => {
    const rendered = context.rendered(inspection);
    if (!rendered) return;
    const rootPoint = { x: event.x, y: event.y };
    const hit = context.request(nearestRecordedX, rendered, {
      domainX: rendered.domainXAtRoot(rootPoint),
    });
    selection.set(hit?.datum ?? null);
  });
  return (
    <PointSeries
      {...series}
      xScale="time"
      yScale="price"
      inspection={inspection}
      onClick={onClick}
    />
  );
}

The event is unchanged. The second argument expires when the synchronous handler returns; promise-returning handlers/queries are unsupported. Contexts pin the selected generation and memoize per logical dispatch, rendered identity, query function identity and equal argument values, including undefined results. Plain options and logical points compare by value; filter/interpolation/resolver functions compare by identity. Reuse callback functions for repeatable requests. Arguments do not accept arbitrary cyclic/class/array payloads. No query executes without a request, and caches release at dispatch completion.

For empty-space selection attach the adapter to a plot ancestor and put a transparent Rectangle behind the marks. Root conversion uses the inspected series’ transform, not the ancestor handler’s. Click/tap use ordinary events; keyboard handlers supply an explicit domain value or root point. They never invent a pointer. No additional hover subscription or render is necessary.

Painted discrete marks

paintedPointAt(rendered, { rootPoint }) selects the last-painted circle/ring covering the point. It returns the original observation plus local radius and stroke width; hollow centers and zero-radius marks have no match. paintedBarAt(rendered, { rootPoint }) selects the last-painted rectangle and returns original datum/index, category/group, valueStart/valueEnd (including baseline for ordinary bars), and boundsLocal.

These linear reverse-order lookups respect actual geometric fill/stroke, transforms, arbitrary clips and Layer bounds. They do not read pixels, resolve scene-wide occlusion or change the logical event target. Transparent paint follows Pibbl’s existing geometric targeting convention; filters do not expand lookup geometry. Explicit inspection can query decorative pointerEvents="none" paint.

Line segments, filled areas and interval bands have no universal original datum at every painted position. Their painted-datum operation is deliberately unsupported. Custom PlotSeries marks already receive datum/index in render; attach a handler to authored geometry. PieLayout/PieSlice already supply original datum/index/key, values, angles and radii; close over that slice rather than search again. Area/band observation queries preserving baseline/both bounds are pending their dedicated authoring checkpoint.

Ownership and cost

rendered() returns undefined before first successful paint/after unmount or disposal. A rendered series is borrowed from one committed visual generation; stale/disposed queries throw. Signal writes schedule a later render and do not replace captured values during dispatch. Results may be retained: geometry and calculated values are read-only, while original datum/neighbor references remain caller-owned and are not deeply frozen. Replace records through signals rather than mutating them in place to keep original data and painted values aligned.

Optional capture retains O(n) row metadata. Queries use O(n) scans; interpolation also uses O(n) temporary run storage. There is no sorting, speculative spatial index, global series registry, per-row event object or additional scheduler. Existing closestX, closestPoint, interpolateX and HoverData retain their current-data/local-coordinate contracts; they are not silently converted to committed-render inspection.

Current coverage

Family	Supported observation contract	Painted identity
LineSeries	Finite numeric x/y, original record/index, contiguous runs	Unsupported on continuous segments/curves
PointSeries	Finite numeric x/y; defined gaps and zero-radius observations preserved	Circle/ring fill and stroke, reverse source order
BarSeries	Original category/group, baseline or range endpoints, local rectangle bounds	Value/range/grouped rectangles, both orientations
AreaSeries	Baseline-preserving inspection pending a dedicated design	Unsupported on continuous fill
IntervalBandSeries	Both-bounds inspection pending a dedicated design	Unsupported on continuous fill
PlotSeries	Existing render callback supplies original record/index/key	Close over the record in an authored mark handler
PieLayout/PieSlice	Existing slice supplies record/index/key/value/fraction/angles/radii	Close over the slice in an authored wedge handler
Candles/volume	Pending financial batch; will share this ownership foundation	Dedicated geometry contracts pending

Every supported captured family uses the same successful-root generation, transformed/clipped coordinates, dispatch memoization, signal-update and disposal rules. A clean cached Layer reuses evaluated data while a changed ancestor transform or clip produces a new borrowed root generation. One ref supports one live series receiver; a keyed replacement may adopt the same surviving hook. Failed rendering follows core teardown semantics: the inspection ref releases its metadata and retained borrowed generations reject queries.

API details from source

useNumericInspection

Owns optional numeric capture without reading signals or executing queries.

useNumericInspection: <D>(_series: HoverSeries<D>) => NumericInspectionRef<D>

Parameters

_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.

usePointInspection

Owns optional circle/ring capture for one PointSeries; O(n) retained geometry when enabled.

usePointInspection: <D>(_series: HoverSeries<D>) => PointInspectionRef<D>

Parameters

_series — Typed descriptor used for datum inference; not observed or registered.

Returns

A stable point inspection ref. Rendered records are borrowed until replacement/disposal.

withInspection

Adapts an ordinary handler to lazy typed inspection without changing its event.

withInspection: <E extends PibblEvent>(handler: (event: E, context: InspectionContext) => void) => (event: E) => void

Related API: withInspection, PibblEvent, InspectionContext.

Parameters

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.

paintedPointAt

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.

paintedPointAt: <D>(rendered: PointRenderedSeries<D>, options: { rootPoint: Readonly<RenderedSeriesPoint>; }) => PaintedPointHit<D> | undefined

Parameters

rendered — Borrowed point geometry from the last successful paint.
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.

useBarInspection

Owns opt-in capture for ordinary, range or grouped categorical bars.

useBarInspection: <D>(_inputs: Pick<BarSeriesProps<D>, "data" | "category">) => BarInspectionRef<D>

Parameters

_inputs — Bar inputs used for datum inference; no data is read or subscribed here.

Returns

A stable ref to pass to one BarSeries inspection prop; captured endpoints share one fixed contract.

paintedBarAt

Finds the last-painted bar covering a root-logical point in this explicit series.

paintedBarAt: <D>(rendered: BarRenderedSeries<D>, options: { rootPoint: Readonly<RenderedSeriesPoint>; }) => PaintedBarHit<D> | undefined

Parameters

rendered — Borrowed committed categorical bar values and rectangle geometry.
options — Root-logical query point; respects every clip, fill/stroke and source order.

Returns

Original record, category/group, endpoints and local bounds, or undefined for gaps and singular transforms.

BarInspectionRef

Mount-owned optional categorical-bar capture.

interface BarInspectionRef<D>

Related API: BarInspectionRef.

Properties and methods

rendered

rendered: () => BarRenderedSeries<D> | undefined

Related API: BarRenderedSeries.

Returns the last successful generation.

Returns

Borrowed bar geometry or undefined before paint/after disposal.

View source — packages/core/src/features/viz/inspection/bar.ts:61

capture

capture: (input: readonly CapturedBarMark<D>[]) => void

Parameters

input — Source-ordered captured rectangle marks.

View source — packages/core/src/features/viz/inspection/bar.ts:65

BarRenderedSeries

A borrowed committed categorical bar generation; contains no numeric category mapping.

interface BarRenderedSeries<D>

Related API: BarRenderedSeries.

Properties and methods

marks

readonly marks: readonly CapturedBarMark<D>[]

Original records and geometry in source paint order.

View source — packages/core/src/features/viz/inspection/bar.ts:38

assertLive

assertLive: () => void

Throws after replacement or disposal.

View source — packages/core/src/features/viz/inspection/bar.ts:40

localAtRoot

localAtRoot: (point: Readonly<RenderedSeriesPoint>) => Readonly<RenderedSeriesPoint> | undefined

Related API: RenderedSeriesPoint.

Converts root logical units into this generation’s local geometry.

Parameters

point — Root-logical Canvas point.

Returns

Local point or undefined for a singular transform.

View source — packages/core/src/features/viz/inspection/bar.ts:45

anchorInsideClips

anchorInsideClips: (point: Readonly<RenderedSeriesPoint>) => boolean

Related API: anchorInsideClips, RenderedSeriesPoint.

Tests a local point against every committed clip/layer bound.

Parameters

point — Local-logical Canvas point.

Returns

Whether the point is inside every clip and layer bound.

View source — packages/core/src/features/viz/inspection/bar.ts:52

PaintedBarHit

Original range/value/grouped bar with its captured endpoints and local paint bounds.

interface PaintedBarHit<D>

Related API: PaintedBarHit.

Properties and methods

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/bar.ts:12

sourceIndex

readonly sourceIndex: number

Original zero-based source position.

View source — packages/core/src/features/viz/inspection/bar.ts:14

PaintedPointHit

The original record and local geometry of a discrete circle/ring covering a query point.

interface PaintedPointHit<D> extends RecordedNumericHit<D>

Related API: PaintedPointHit, RecordedNumericHit.

Properties and methods

radiusLocal

readonly radiusLocal: number

Circle radius before world transforms, in local logical units.

View source — packages/core/src/features/viz/inspection/painted-point.ts:9

strokeWidthLocal

readonly strokeWidthLocal: number

Painted stroke width before world transforms, in local logical units.

View source — packages/core/src/features/viz/inspection/painted-point.ts:11

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

InspectionContext

Lazy synchronous inspection; expires when its handler returns.

interface InspectionContext

Related API: InspectionContext.

Properties and methods

rendered

rendered: <S>(ref: InspectionRef<S>) => S | undefined

Related API: InspectionRef.

Pins one receiver’s committed generation for this logical dispatch.

Parameters

ref — Explicit ref identifying the mounted receiver.

Returns

Borrowed generation or undefined before paint/after disposal.

View source — packages/core/src/features/viz/inspection/handler.ts:25

request

request: <S, A, R>(query: (rendered: S, options: A) => R, rendered: S, options: A) => R

Executes only on demand and memoizes equal requests, including no result. Options contain plain scalar fields, function identities and logical points.

Parameters

query — Pure synchronous query with a stable result contract.
rendered — Committed generation pinned for this request.
options — Named query parameters; functions compare by identity.

Returns

Query result, including undefined, reused for equal requests in dispatch.

View source — packages/core/src/features/viz/inspection/handler.ts:34

InspectionRef

A mount-owned source of borrowed committed render records.

interface InspectionRef<S>

Related API: InspectionRef.

Properties and methods

rendered

rendered: () => S | undefined

Returns the current committed record.

Returns

Borrowed record or undefined before paint/after disposal.

View source — packages/core/src/features/viz/inspection/handler.ts:14

NumericInspectionRef

Optional renderer sink and mount-owned access to the last successful paint.

interface NumericInspectionRef<D>

Related API: NumericInspectionRef.

Properties and methods

rendered

rendered: () => NumericRenderedSeries<D> | undefined

Related API: NumericRenderedSeries.

Returns borrowed rendered values.

Returns

Current committed generation, or undefined before paint/after disposal.

View source — packages/core/src/features/viz/inspection/capture-types.ts:45

capture

capture: (input: NumericSeriesCapture<D>) => void

Parameters

input — Values evaluated by the receiver in source order.

View source — packages/core/src/features/viz/inspection/capture-types.ts:49

PointInspectionRef

Mount-owned point capture; queries are imported independently.

interface PointInspectionRef<D> extends NumericInspectionRef<D>

Properties and methods

rendered

rendered: () => PointRenderedSeries<D> | undefined

Related API: PointRenderedSeries.

Returns borrowed point geometry.

Returns

Current point generation, or undefined before paint/after disposal.

View source — packages/core/src/features/viz/inspection/capture-types.ts:74

capture

capture: (input: NumericSeriesCapture<D>) => void

Parameters

input — Values evaluated by the receiver in source order.

View source — packages/core/src/features/viz/inspection/capture-types.ts:49

PointRenderedSeries

Rendered numeric points with committed circle/ring geometry.

interface PointRenderedSeries<D> extends NumericRenderedSeries<D>

Properties and methods

observations

readonly observations: readonly NumericRenderedObservation<D>[]

Related API: NumericRenderedObservation.

Evaluated observations in source order for this committed generation.

View source — packages/core/src/features/viz/inspection/query-types.ts:63

assertLive

assertLive: () => void

Asserts that this generation can still be inspected synchronously.

View source — packages/core/src/features/viz/inspection/query-types.ts:65

marks

readonly marks: readonly CapturedNumericObservation<D>[]

View source — packages/core/src/features/viz/inspection/capture-types.ts:57

localAtRoot

localAtRoot: (point: Readonly<RenderedSeriesPoint>) => Readonly<RenderedSeriesPoint> | undefined

Related API: RenderedSeriesPoint.

Parameters

point — Root-logical Canvas coordinates.

Returns

Local coordinates, or undefined for a singular transform.

View source — packages/core/src/features/viz/inspection/capture-types.ts:62

domainXAtRoot

domainXAtRoot: (point: Readonly<RenderedSeriesPoint>) => number | undefined

Related API: RenderedSeriesPoint.

Converts a root-logical point to a numeric horizontal domain value, or reports that the committed transform cannot invert that point.

Parameters

point — Root-logical position to invert.

Returns

The numeric horizontal domain value, or undefined when unavailable.

View source — packages/core/src/features/viz/inspection/query-types.ts:72

anchorAtDomain

anchorAtDomain: (point: Readonly<{ domainX: number; domainY: number; }>) => NumericRenderedAnchors

Related API: NumericRenderedAnchors.

Maps numeric domain values to the committed local and root-logical anchors.

Parameters

point — Numeric domain values to map.
point.domainX — Horizontal numeric domain value.
point.domainY — Vertical numeric domain value.

Returns

Both committed logical anchors for the requested domain point.

View source — packages/core/src/features/viz/inspection/query-types.ts:80

anchorInsideClips

anchorInsideClips: (pointLocal: Readonly<RenderedSeriesPoint>) => boolean

Related API: anchorInsideClips, RenderedSeriesPoint.

Returns whether a local point lies within the committed clip stack.

Parameters

pointLocal — Series-local logical position to test.

Returns

Whether every committed clip contains the point.

View source — packages/core/src/features/viz/inspection/query-types.ts:93

nearestRecordedX

Finds the recorded observation nearest to a numeric horizontal domain value in O(n) time.

Ties retain source order. Distance is measured in domain units, while both returned anchors retain their explicitly named local and root-logical units.

nearestRecordedX: <D>(rendered: NumericRenderedSeries<D>, options: NearestRecordedXOptions<D>) => NearestRecordedXHit<D> | undefined

Parameters

rendered — Committed rendered-series generation to inspect synchronously.
options — Domain position, optional limit, and observation filter.

Returns

The selected recorded observation, or undefined when none qualifies.

nearestRecordedPoint

Finds the recorded observation nearest to a root-logical point in O(n) time.

Ties retain source order. This query measures distance in root-logical units so it remains meaningful under nonuniform series transforms.

nearestRecordedPoint: <D>(rendered: NumericRenderedSeries<D>, options: NearestRecordedPointOptions<D>) => NearestRecordedPointHit<D> | undefined

Parameters

rendered — Committed rendered-series generation to inspect synchronously.
options — Root position, optional limit, and observation filter.

Returns

The selected recorded observation, or undefined when none qualifies.

sampleRecordedX

Returns an exact recorded observation or a caller-defined interpolation between records.

It never bridges separate rendered runs, filtered observations, or an interval larger than maxDomainGap. Duplicate x values reject by default and require an explicit resolveDuplicate function. Estimated results retain their two source observations and map explicit local/root anchors through the committed generation. This is O(n) in captured observations and the result is borrowed until the rendered generation is replaced or disposed.

sampleRecordedX: <D>(rendered: NumericRenderedSeries<D>, options: SampleRecordedXOptions<D>) => RecordedXSample<D> | undefined

Parameters

rendered — Committed rendered-series generation to inspect synchronously.
options — Domain position, interpolation, duplicate policy, and filter.

Returns

An exact record, an explicitly interpolated estimate, or undefined.

firstSourceObservation

Retains the first source observation at a duplicate domain coordinate.

firstSourceObservation: <D>(first: NumericRenderedObservation<D>, _next: NumericRenderedObservation<D>) => NumericRenderedObservation<D>

Parameters

first — First selected observation at this domain coordinate.
_next — Later observation at the same domain coordinate.

Returns

The earliest source observation.

lastSourceObservation

Replaces a source observation with the next one at a duplicate domain coordinate.

lastSourceObservation: <D>(_first: NumericRenderedObservation<D>, next: NumericRenderedObservation<D>) => NumericRenderedObservation<D>

Parameters

_first — Earlier selected observation at this domain coordinate.
next — Later observation at the same domain coordinate.

Returns

The latest source observation.

anchorInsideClips

Returns whether a filter candidate’s anchor lies inside the committed clip stack.

Pass this function as a query filter when visibility at the anchor is required. Queries otherwise examine all eligible rendered observations.

anchorInsideClips: <D>(candidate: InspectionCandidate<D>) => boolean

Related API: anchorInsideClips, InspectionCandidate.

Parameters

candidate — Candidate whose committed local anchor should be clip-tested.

Returns

Whether the candidate anchor lies within every committed clip.

NumericRenderedSeries

A committed numeric rendering available for synchronous inspection.

Instances are supplied by the matching inspection ref; applications do not create them. They are valid only for the synchronous inspection context that supplied them. assertLive throws after that context, after a replacement generation, or after disposal.

interface NumericRenderedSeries<D>

Related API: NumericRenderedSeries.

Properties and methods

observations

readonly observations: readonly NumericRenderedObservation<D>[]

Related API: NumericRenderedObservation.

Evaluated observations in source order for this committed generation.

View source — packages/core/src/features/viz/inspection/query-types.ts:63

assertLive

assertLive: () => void

Asserts that this generation can still be inspected synchronously.

View source — packages/core/src/features/viz/inspection/query-types.ts:65

domainXAtRoot

domainXAtRoot: (point: Readonly<RenderedSeriesPoint>) => number | undefined

Related API: RenderedSeriesPoint.

Converts a root-logical point to a numeric horizontal domain value, or reports that the committed transform cannot invert that point.

Parameters

point — Root-logical position to invert.

Returns

The numeric horizontal domain value, or undefined when unavailable.

View source — packages/core/src/features/viz/inspection/query-types.ts:72

anchorAtDomain

anchorAtDomain: (point: Readonly<{ domainX: number; domainY: number; }>) => NumericRenderedAnchors

Related API: NumericRenderedAnchors.

Maps numeric domain values to the committed local and root-logical anchors.

Parameters

point — Numeric domain values to map.
point.domainX — Horizontal numeric domain value.
point.domainY — Vertical numeric domain value.

Returns

Both committed logical anchors for the requested domain point.

View source — packages/core/src/features/viz/inspection/query-types.ts:80

anchorInsideClips

anchorInsideClips: (pointLocal: Readonly<RenderedSeriesPoint>) => boolean

Related API: anchorInsideClips, RenderedSeriesPoint.

Returns whether a local point lies within the committed clip stack.

Parameters

pointLocal — Series-local logical position to test.

Returns

Whether every committed clip contains the point.

View source — packages/core/src/features/viz/inspection/query-types.ts:93

NumericRenderedObservation

One numeric observation evaluated for a committed rendered-series generation.

anchorLocal belongs to the series’ local logical coordinate system and anchorRoot belongs to the root-logical coordinate system used by Pibbl events. run separates observations that the rendered mark does not join.

interface NumericRenderedObservation<D>

Related API: NumericRenderedObservation.

Properties and methods

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

RecordedNumericHit

A recorded observation selected by a numeric inspection query.

interface RecordedNumericHit<D> extends NumericRenderedObservation<D>

Properties and methods

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

NearestRecordedXHit

A recorded observation selected by horizontal-domain proximity.

interface NearestRecordedXHit<D> extends RecordedNumericHit<D>

Related API: NearestRecordedXHit, RecordedNumericHit.

Properties and methods

domainDelta

readonly domainDelta: number

Absolute difference from the requested horizontal domain value.

View source — packages/core/src/features/viz/inspection/query-types.ts:131

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

NearestRecordedPointHit

A recorded observation selected by root-logical geometric proximity.

interface NearestRecordedPointHit<D> extends RecordedNumericHit<D>

Properties and methods

rootDistance

readonly rootDistance: number

Euclidean distance from the requested root-logical point.

View source — packages/core/src/features/viz/inspection/query-types.ts:141

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

RecordedXSample

An exact recorded sample or an explicit estimate between recorded observations.

Full type declaration

type RecordedXSample<D> = | (RecordedNumericHit<D> & {
      /** Identifies a value selected directly from one recorded observation. */
      readonly kind: "exact";
    })
  | Readonly<{
      /** Identifies a value computed between two recorded observations. */
      kind: "interpolated";
      /** Requested horizontal numeric domain value. */
      domainX: number;
      /** Numeric domain value returned by the caller's interpolation function. */
      domainY: number;
      /** Interpolated anchor in committed series-local logical coordinates. */
      anchorLocal: Readonly<RenderedSeriesPoint>;
      /** Interpolated anchor in committed root-logical coordinates. */
      anchorRoot: Readonly<RenderedSeriesPoint>;
      /** Observation immediately before the sampled position in its rendered run. */
      before: NumericRenderedObservation<D>;
      /** Observation immediately after the sampled position in its rendered run. */
      after: NumericRenderedObservation<D>;
      /** Fraction of the interval from `before` through `after`. */
      fraction: number;
    }>

Properties and methods

kind

kind: "exact" | "interpolated"

Identifies a value computed between two recorded observations. Identifies a value selected directly from one recorded observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:185

domainX

domainX: number

Requested horizontal numeric domain value. Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:187

domainY

domainY: number

Numeric domain value returned by the caller’s interpolation function. Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:189

anchorLocal

anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

Interpolated anchor in committed series-local logical coordinates. The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:191

anchorRoot

anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

Interpolated anchor in committed root-logical coordinates. The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:193

NumericRenderedFilter

Selects observations eligible for one inspection request.

type NumericRenderedFilter<D> = (
  observation: InspectionCandidate<D>,
) => boolean

Parameters

observation — Candidate containing the original observation and optional clip test.

Returns

Whether the candidate participates in this request.

NumericDuplicateResolver

Chooses one source observation when several observations in one rendered run have the same horizontal domain value.

type NumericDuplicateResolver<D> = (
  first: NumericRenderedObservation<D>,
  next: NumericRenderedObservation<D>,
) => NumericRenderedObservation<D>

Parameters

first — Observation selected so far at this domain value.
next — Later source observation at the same domain value.

Returns

Either first or next.

NumericDomainInterpolation

Computes a numeric vertical sample between two recorded domain values.

type NumericDomainInterpolation = (
  beforeDomainY: number,
  afterDomainY: number,
  fraction: number,
) => number

Related API: NumericDomainInterpolation.

Parameters

beforeDomainY — Numeric vertical value before the sample.
afterDomainY — Numeric vertical value after the sample.
fraction — Distance from before to after, from zero through one.

Returns

The estimated numeric vertical domain value.

RenderedSeriesPoint

A point in a named logical coordinate system.

interface RenderedSeriesPoint

Related API: RenderedSeriesPoint.

Properties and methods

readonly x: number

Horizontal logical coordinate.

View source — packages/core/src/features/viz/inspection/query-types.ts:8

readonly y: number

Vertical logical coordinate.

View source — packages/core/src/features/viz/inspection/query-types.ts:10

RenderedSeries

A committed numeric rendering available for synchronous inspection.

interface RenderedSeries<D>

Related API: RenderedSeries.

Properties and methods

observations

readonly observations: readonly NumericRenderedObservation<D>[]

Related API: NumericRenderedObservation.

Evaluated observations in source order for this committed generation.

View source — packages/core/src/features/viz/inspection/query-types.ts:63

assertLive

assertLive: () => void

Asserts that this generation can still be inspected synchronously.

View source — packages/core/src/features/viz/inspection/query-types.ts:65

domainXAtRoot

domainXAtRoot: (point: Readonly<RenderedSeriesPoint>) => number | undefined

Related API: RenderedSeriesPoint.

Converts a root-logical point to a numeric horizontal domain value, or reports that the committed transform cannot invert that point.

Parameters

point — Root-logical position to invert.

Returns

The numeric horizontal domain value, or undefined when unavailable.

View source — packages/core/src/features/viz/inspection/query-types.ts:72

anchorAtDomain

anchorAtDomain: (point: Readonly<{ domainX: number; domainY: number; }>) => NumericRenderedAnchors

Related API: NumericRenderedAnchors.

Maps numeric domain values to the committed local and root-logical anchors.

Parameters

point — Numeric domain values to map.
point.domainX — Horizontal numeric domain value.
point.domainY — Vertical numeric domain value.

Returns

Both committed logical anchors for the requested domain point.

View source — packages/core/src/features/viz/inspection/query-types.ts:80

anchorInsideClips

anchorInsideClips: (pointLocal: Readonly<RenderedSeriesPoint>) => boolean

Related API: anchorInsideClips, RenderedSeriesPoint.

Returns whether a local point lies within the committed clip stack.

Parameters

pointLocal — Series-local logical position to test.

Returns

Whether every committed clip contains the point.

View source — packages/core/src/features/viz/inspection/query-types.ts:93

InspectionCandidate

An observation that can be explicitly filtered by committed clipping.

interface InspectionCandidate<D> extends NumericRenderedObservation<D>

Properties and methods

anchorInsideClips

anchorInsideClips: () => boolean

Related API: anchorInsideClips.

Returns

Whether this observation’s anchor lies within the committed clips.

View source — packages/core/src/features/viz/inspection/query-types.ts:103

datum

readonly datum: D

Caller-owned original record.

View source — packages/core/src/features/viz/inspection/query-types.ts:24

sourceIndex

readonly sourceIndex: number

Original zero-based index in the caller’s source array.

View source — packages/core/src/features/viz/inspection/query-types.ts:26

domainX

readonly domainX: number

Evaluated horizontal value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:28

domainY

readonly domainY: number

Evaluated vertical value in the series’ numeric domain.

View source — packages/core/src/features/viz/inspection/query-types.ts:30

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in series-local logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:32

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

The observation anchor in root-logical coordinates.

View source — packages/core/src/features/viz/inspection/query-types.ts:34

run

readonly run: number

Identifier of the contiguous rendered run containing this observation.

View source — packages/core/src/features/viz/inspection/query-types.ts:36

NumericRenderedAnchors

The two logical anchors of a numeric domain position.

interface NumericRenderedAnchors

Related API: NumericRenderedAnchors.

Properties and methods

anchorLocal

readonly anchorLocal: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

Anchor in the series-local logical coordinate system.

View source — packages/core/src/features/viz/inspection/query-types.ts:46

anchorRoot

readonly anchorRoot: Readonly<RenderedSeriesPoint>

Related API: RenderedSeriesPoint.

Anchor in the root-logical coordinate system.

View source — packages/core/src/features/viz/inspection/query-types.ts:48

NearestRecordedXOptions

Options for nearestRecordedX.

interface NearestRecordedXOptions<D>

Related API: NearestRecordedXOptions.

View source — packages/core/src/features/viz/inspection/queries.ts:103

Properties and methods

domainX

readonly domainX: number | undefined

Numeric horizontal domain value to inspect, or undefined for no request.

View source — packages/core/src/features/viz/inspection/queries.ts:105

maxDomainDelta (optional)

readonly maxDomainDelta?: number | undefined

Maximum accepted absolute horizontal-domain delta.

View source — packages/core/src/features/viz/inspection/queries.ts:107

filter (optional)

readonly filter?: NumericRenderedFilter<D> | undefined

Related API: NumericRenderedFilter.

Further restricts committed observations for this request.

View source — packages/core/src/features/viz/inspection/queries.ts:109

NearestRecordedPointOptions

Options for nearestRecordedPoint.

interface NearestRecordedPointOptions<D>

Related API: NearestRecordedPointOptions.

View source — packages/core/src/features/viz/inspection/queries.ts:153

Properties and methods

rootPoint

readonly rootPoint: Readonly<RenderedSeriesPoint> | undefined

Related API: RenderedSeriesPoint.

Root-logical point to inspect, or undefined for no request.

View source — packages/core/src/features/viz/inspection/queries.ts:155

maxRootDistance (optional)

readonly maxRootDistance?: number | undefined

Maximum accepted Euclidean root-logical distance.

View source — packages/core/src/features/viz/inspection/queries.ts:157

filter (optional)

readonly filter?: NumericRenderedFilter<D> | undefined

Related API: NumericRenderedFilter.

Further restricts committed observations for this request.

View source — packages/core/src/features/viz/inspection/queries.ts:159

SampleRecordedXOptions

Options for sampleRecordedX.

interface SampleRecordedXOptions<D>

Related API: SampleRecordedXOptions.

View source — packages/core/src/features/viz/inspection/queries.ts:206

Properties and methods

domainX

readonly domainX: number | undefined

Numeric horizontal domain value to sample, or undefined for no request.

View source — packages/core/src/features/viz/inspection/queries.ts:208

interpolation

readonly interpolation: NumericDomainInterpolation

Related API: NumericDomainInterpolation.

Computes the estimated numeric domain value between two recorded values.

View source — packages/core/src/features/viz/inspection/queries.ts:210

resolveDuplicate (optional)

readonly resolveDuplicate?: NumericDuplicateResolver<D> | undefined

Related API: NumericDuplicateResolver.

Explicitly chooses one observation from each duplicate-domain group.

View source — packages/core/src/features/viz/inspection/queries.ts:212

maxDomainGap (optional)

readonly maxDomainGap?: number | undefined

Maximum domain interval that may be interpolated across.

View source — packages/core/src/features/viz/inspection/queries.ts:214

filter (optional)

readonly filter?: NumericRenderedFilter<D> | undefined

Related API: NumericRenderedFilter.

Further restricts committed observations for this request.

View source — packages/core/src/features/viz/inspection/queries.ts:216

Implementation guidance for agents

Read the Data visualization companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Recorded numeric inspection: Query the committed observations from numeric and point series with explicit units and interpolation. Plain source
Painted mark lookup: Keep painted point and bar hit testing separate from nearest recorded-data selection. Plain source
Lazy event inspection: Request a typed query only inside an ordinary event handler and reuse an equal request within its dispatch. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision dd39ce2. ALPHA — NOT FOR PRODUCTION USE.

Rendered series inspection

Standalone queries

Explicit interpolation

Lazy ordinary handlers

Painted discrete marks

Ownership and cost

Current coverage

API details from source

useNumericInspection

Parameters

Returns

See also

usePointInspection

Parameters

Returns

See also

withInspection

Parameters

Returns

See also

paintedPointAt

Parameters

Returns

See also

useBarInspection

Parameters

Returns

See also

paintedBarAt

Parameters

Returns

See also

BarInspectionRef

See also

Properties and methods

Returns

Parameters

BarRenderedSeries

See also

Properties and methods

Parameters

Returns

Parameters

Returns

PaintedBarHit

See also

Properties and methods

PaintedPointHit

See also

Properties and methods

InspectionContext

See also

Properties and methods

Parameters

Returns

Parameters

Returns

InspectionRef

See also

Properties and methods

Returns

NumericInspectionRef

See also

Properties and methods

Returns

Parameters

PointInspectionRef

See also

Properties and methods

Returns

Parameters

PointRenderedSeries

See also

Properties and methods

Parameters

Returns

Parameters

Returns

Parameters

Returns