semiotic 3.7.5 → 3.8.1

package/dist/components/stream/types.d.ts

@@ -4,26 +4,19 @@ import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { HatchFill } from "../charts/shared/hatchFill";
 import type { CoercibleNumber } from "./accessorUtils";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
+import type { GlyphDef } from "./glyphDef";
+import type { SceneRenderMode } from "./sceneRenderBackendTypes";
+import type { StreamSemanticInteractionProps } from "./streamSemanticTypes";
+import type { XYFrameAxisConfig } from "./xyFrameAxisTypes";
+export type { SceneRenderBackend, SceneRenderMode } from "./sceneRenderBackendTypes";
+export type { ThemeSemanticColors } from "./streamThemeTypes";
+export type { AxisTickFormat, AxisTickFormatter, XYFrameAxisConfig } from "./xyFrameAxisTypes";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
-export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
-export interface ThemeSemanticColors {
-    primary?: string;
-    secondary?: string;
-    success?: string;
-    danger?: string;
-    warning?: string;
-    error?: string;
-    info?: string;
-    text?: string;
-    textSecondary?: string;
-    border?: string;
-    grid?: string;
-    surface?: string;
-}
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
     /** Exponential: half-life in buffer positions (default: bufferSize/2) */
@@ -104,8 +97,14 @@ export interface Style {
     strokeWidth?: number;
     strokeDasharray?: string;
     strokeLinecap?: "butt" | "round" | "square";
-    /** Fill color or CanvasPattern (e.g. from createHatchPattern) */
-    fill?: string | CanvasPattern;
+    /**
+     * Fill for the mark. One of:
+     *  - a color string (or CSS var)
+     *  - a {@link HatchFill} descriptor (declarative hatch — resolves to a
+     *    CanvasPattern on canvas and an SVG `<pattern>` on the SSR/overlay path)
+     *  - a `CanvasPattern` (e.g. a hand-built `createHatchPattern` — canvas only)
+     */
+    fill?: string | HatchFill | CanvasPattern;
     fillOpacity?: number;
     opacity?: number;
     /** For icon/isotype bars: an image to stamp instead of filling */
@@ -117,7 +116,19 @@ export interface Style {
     /** Internal geo line flag: fade line ends at projection clipping edges. */
     _edgeFade?: boolean;
 }
-export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | SymbolSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
+/**
+ * Optional semantic payload carried beside render geometry. `accessibleDatum`
+ * preserves the full row; `tableFields` lets a recipe expose a curated,
+ * user-facing table projection without reducing the scene datum itself.
+ */
+export interface SceneAccessibilityMetadata {
+    accessibleDatum?: SceneDatum | Datum[];
+    accessibility?: {
+        label?: string;
+        tableFields?: SceneDatum | Datum[];
+    };
+}
+export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | SymbolSceneNode | GlyphSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
     value: number;
     color: string;
@@ -132,6 +143,8 @@ export interface LineSceneNode {
     colorThresholds?: LineColorThreshold[];
     style: Style;
     datum: SeriesDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     /** Horizontal gradient for the line stroke */
     strokeGradient?: {
@@ -163,6 +176,8 @@ export interface AreaSceneNode {
     bottomPath: [number, number][];
     style: Style;
     datum: SeriesDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     /** Clip the area to this rect (in plot-relative pixels). Used by horizon
      *  charts to band a single series into N slices. */
@@ -223,6 +238,8 @@ export interface PointSceneNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional unique identifier for point-anchored annotations */
     pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active) */
@@ -262,6 +279,64 @@ export interface SymbolSceneNode {
     rotation?: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
+    /** Optional unique identifier for point-anchored annotations. */
+    pointId?: string;
+    /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active). */
+    _pulseIntensity?: number;
+    /** Pulse glow color. */
+    _pulseColor?: string;
+    /** Pulse glow radius in px. */
+    _pulseGlowRadius?: number;
+    /** Animation target fields (set during transitions). */
+    _targetX?: number;
+    _targetY?: number;
+    _targetR?: number;
+    _targetOpacity?: number;
+    /** Per-datum decay opacity (set by PipelineStore.applyDecay). */
+    _decayOpacity?: number;
+    /** Stable identity key for transition tracking. */
+    _transitionKey?: string;
+}
+/**
+ * Glyph node — the composite-pictogram channel. Where `symbol` stamps one
+ * `d3-shape` path, `glyph` stamps a small multi-part vector pictogram (a
+ * `GlyphDef`: an ISOTYPE server sign, a factory, a worker) with per-node
+ * `color`/`accent` paints resolved against the definition's role tokens, and
+ * an optional partial fill (`fraction`/`fractionStart`) for unit-chart final
+ * signs — pair with the `unitize` recipe. Painted on canvas and in SVG/SSR
+ * via the shared `glyphDef` helpers, hit-tested and keyboard-navigated by its
+ * drawn bounds, and transition-tracked like a point. Uses `x`/`y` in XY,
+ * ordinal, and geo scenes (the network variant uses `cx`/`cy`).
+ */
+export interface GlyphSceneNode {
+    type: "glyph";
+    x: number;
+    y: number;
+    /** Rendered height in px — width follows the definition's viewBox aspect. */
+    size: number;
+    /** The multi-part pictogram definition to stamp. */
+    glyph: GlyphDef;
+    /** Primary paint for parts declaring `"color"`. Falls back to `style.fill`. */
+    color?: string;
+    /** Accent paint for parts declaring `"accent"`. */
+    accent?: string;
+    /** Partial fill 0–1 — how much of the sign is painted. @default 1 */
+    fraction?: number;
+    /** Where the partial fill begins, 0–1 (range boundary signs). @default 0 */
+    fractionStart?: number;
+    /** Partial-fill axis: horizontal fills left→right, vertical bottom→up. @default "horizontal" */
+    fractionDirection?: "horizontal" | "vertical";
+    /** Ghost paint drawn at full extent beneath a partial fill so the whole
+     *  sign stays countable (the ISOTYPE partial-symbol convention). */
+    ghostColor?: string;
+    /** Rotation in radians about (x, y). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional unique identifier for point-anchored annotations. */
     pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active). */
@@ -320,6 +395,8 @@ export interface RectSceneNode {
     };
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -342,6 +419,8 @@ export interface HeatcellSceneNode {
     h: number;
     fill: string;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional style object (used for decay/transition opacity on heatmap cells) */
     style?: Style;
     /** Numeric cell value (for canvas text rendering when showValues is enabled) */
@@ -379,6 +458,8 @@ export interface CandlestickSceneNode {
     /** Range/dumbbell mode — no body, endpoint dots instead */
     isRange?: boolean;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional style object (used during transition opacity animations) */
     style?: Style;
     _pulseIntensity?: number;
@@ -431,6 +512,30 @@ export interface StreamScales {
     x: ScaleLinear<number, number>;
     y: ScaleLinear<number, number>;
 }
+/**
+ * Context handed to a `foregroundGraphics` / `backgroundGraphics` callback. The
+ * function form receives the frame's **resolved scales** alongside `size` +
+ * `margin`, so bespoke SVG overlays anchor to the same scales the chart drew
+ * (instead of re-deriving them from extents by hand and risking drift). `scales`
+ * is `null` before the first layout pass — fall back to your own mapping then.
+ * This is the HOC analogue of what custom layouts get via `ctx.scales`.
+ *
+ * Generic over the scale shape: XY frames pass {@link StreamScales} (`{x, y}`),
+ * the ordinal frame passes its `{o, r, projection}` scales.
+ */
+export interface FrameGraphicsContext<S = StreamScales> {
+    size: number[];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: S | null;
+}
+/** A foreground/background graphics value: static SVG, or a function of the
+ *  frame's geometry + resolved scales. */
+export type FrameGraphicsProp<S = StreamScales> = ReactNode | ((ctx: FrameGraphicsContext<S>) => ReactNode);
 export interface StreamLayout {
     width: number;
     height: number;
@@ -471,52 +576,7 @@ export interface BandConfig<T = Datum> {
      */
     interactive?: boolean;
 }
-/**
- * Per-axis configuration object for an XY frame's `axes: []` array.
- * Distinct from `AxisConfig` exported from the HOC layer (which is the
- * chart-level `xLabel` / `yLabel` / `xFormat` / `yFormat` bundle) —
- * this type describes one axis at a time and is what
- * `frameProps.axes[i]` consumes.
- *
- * Re-exported under the legacy name `AxisConfig` from `SVGOverlay.tsx`
- * for backwards-compatibility with internal callers; new code should
- * import this name directly.
- */
-export interface XYFrameAxisConfig {
-    orient: "left" | "right" | "top" | "bottom";
-    label?: string;
-    ticks?: number;
-    /** Per-axis tick label formatter. ReactNode return is supported and
-     *  renders inside a `<foreignObject>`. */
-    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
-    baseline?: boolean | "under";
-    jaggedBase?: boolean;
-    /** Explicit tick values. When provided, bypasses both d3's "nice"
-     *  generator and `axisExtent: "exact"` — the caller has hand-picked
-     *  the positions. Pixel-distance filtering downstream still drops
-     *  overlapping labels. Mirrors the ordinal frame's `rTickValues`. */
-    tickValues?: Array<number | Date>;
-    /** Grid line stroke style: `"dashed"` (6,4), `"dotted"` (2,4), or a
-     *  custom strokeDasharray string. Applied to grid lines extending
-     *  from ticks across the chart area. */
-    gridStyle?: "dashed" | "dotted" | string;
-    /** Always include the domain max as a tick, even if d3 omits it. */
-    includeMax?: boolean;
-    /** Auto-rotate labels 45° when horizontal spacing is too tight. */
-    autoRotate?: boolean;
-    /** Highlight ticks at time boundaries (new month, year, etc.) with
-     *  semibold text. `true` auto-detects Date boundaries. A function
-     *  receives (value, index) and returns true for landmark ticks. */
-    landmarkTicks?: boolean | ((value: any, index: number) => boolean);
-    /** Tick label anchoring strategy:
-     *  - `"middle"` (default): all tick labels centered on the tick mark
-     *  - `"edges"`: first tick label anchors to start, last to end,
-     *    middles stay centered. Pairs naturally with `axisExtent: "exact"`
-     *    — pins the domain to the data min/max AND keeps the extreme
-     *    labels from overflowing the plot. */
-    tickAnchor?: "middle" | "edges";
-}
-export interface StreamXYFrameProps<T = Datum> {
+export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteractionProps<HoverData> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
     data?: T[];
@@ -526,6 +586,12 @@ export interface StreamXYFrameProps<T = Datum> {
     chunkSize?: number;
     xAccessor?: string | ((d: T) => CoercibleNumber);
     yAccessor?: string | ((d: T) => CoercibleNumber);
+    /**
+     * Force domain/scene re-derivation when a stable function accessor's
+     * external semantics changed without receiving a new function identity.
+     * Prefer changing the accessor reference where possible.
+     */
+    accessorRevision?: number;
     colorAccessor?: string | ((d: T) => string);
     sizeAccessor?: string | ((d: T) => CoercibleNumber);
     /** Categorical accessor → glyph shape (scatter/bubble). */
@@ -541,22 +607,25 @@ export interface StreamXYFrameProps<T = Datum> {
      * - "zero" (default): standard stack from y=0
      * - "wiggle": Byron–Wattenberg streamgraph offset (minimizes wiggle)
      * - "silhouette": center the stack symmetrically around y=0
+     * - "diverging": positives stack above 0, negatives below 0 (signed values)
      *
      * Mutually exclusive with `normalize`: when `normalize` is `true`, the
      * stack is forced to a `"zero"` baseline (any other value is ignored)
      * because normalization assumes a fixed `[0, 1]` y-domain.
      */
-    baseline?: "zero" | "wiggle" | "silhouette";
+    baseline?: "zero" | "wiggle" | "silhouette" | "diverging";
     /**
      * Stack order — controls which series sits at the top, middle, or bottom.
      * - "key" (default): alphabetical by group key
+     * - "input": first-seen group order within the current data
+     *   buffer/window; streaming eviction can change this order
      * - "insideOut": largest-total series in the middle, smaller alternating
      *   above/below. Combined with `baseline: "wiggle"` or `"silhouette"`,
      *   produces the canonical streamgraph look where a "central anchor"
      *   layer sits across y=0 and other layers stack outward.
      * - "asc" / "desc": by total ascending / descending
      */
-    stackOrder?: "key" | "insideOut" | "asc" | "desc";
+    stackOrder?: "key" | "input" | "insideOut" | "asc" | "desc";
     /**
      * Accessor returning a symmetric uncertainty offset per datum.
      * When set, an uncertainty band is drawn ± this offset from the line.
@@ -621,7 +690,7 @@ export interface StreamXYFrameProps<T = Datum> {
     windowSize?: number;
     timeAccessor?: string | ((d: T) => number);
     xScaleType?: "linear" | "log" | "time";
-    yScaleType?: "linear" | "log";
+    yScaleType?: "linear" | "log" | "symlog";
     xExtent?: [number | undefined, number | undefined] | [number];
     yExtent?: [number | undefined, number | undefined] | [number];
     extentPadding?: number;
@@ -641,6 +710,8 @@ export interface StreamXYFrameProps<T = Datum> {
     };
     className?: string;
     background?: string;
+    /** Optional scene paint backend. Exact scene geometry remains interactive. */
+    renderMode?: SceneRenderMode<SceneNode>;
     lineStyle?: LineStyle | ((d: T, group?: string) => Style);
     pointStyle?: (d: T) => Style & {
         r?: number;
@@ -650,7 +721,7 @@ export interface StreamXYFrameProps<T = Datum> {
     waterfallStyle?: WaterfallStyle;
     swarmStyle?: SwarmStyle;
     barColors?: Record<string, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     showAxes?: boolean;
     /**
      * Per-axis config array. See `XYFrameAxisConfig` for the full set of
@@ -675,8 +746,6 @@ export interface StreamXYFrameProps<T = Datum> {
     tickFormatValue?: (value: number) => string;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
-    customHoverBehavior?: (d: HoverData | null) => void;
-    customClickBehavior?: (d: HoverData | null) => void;
     enableHover?: boolean;
     /** Max pixel distance for hover/click hit testing. Default 30. */
     hoverRadius?: number;
@@ -724,9 +793,9 @@ export interface StreamXYFrameProps<T = Datum> {
     /** Fires when the current legend category domain changes after scene rebuilds. */
     onCategoriesChange?: (categories: string[]) => void;
     /** SVG elements rendered behind the canvas (in pixel space) */
-    backgroundGraphics?: ReactNode;
+    backgroundGraphics?: FrameGraphicsProp;
     /** SVG elements rendered on top of everything (in SVG overlay) */
-    foregroundGraphics?: ReactNode;
+    foregroundGraphics?: FrameGraphicsProp;
     /** Canvas renderers executed before the chart-type renderers (e.g. connecting lines under points) */
     canvasPreRenderers?: CanvasRendererFn[];
     /** SVG pre-renderers for SSR — SVG equivalent of canvasPreRenderers, rendered under data marks */
@@ -745,6 +814,18 @@ export interface StreamXYFrameProps<T = Datum> {
     animate?: AnimateProp;
     /** Frame-level data liveness indicator */
     staleness?: StalenessConfig;
+    /** Optional rAF seam for deterministic host scheduling. */
+    frameScheduler?: import("./useFrame").FrameScheduler;
+    /** Monotonic wall-clock seam for deterministic replay, tests, or evidence capture. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Injectable random source for frame-local stochastic work. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed. Ignored when `random` is supplied. */
+    seed?: number;
+    /** Freeze logical animation time and cancel queued work while paused. */
+    paused?: boolean;
+    /** Freeze logical animation time while the page is hidden. Defaults to true for XY frames. */
+    suspendWhenHidden?: boolean;
     /** Marginal distribution plots in axis margins (histogram, violin, ridgeline, boxplot) */
     marginalGraphics?: MarginalGraphicsConfig;
     /** Aggregation mode for streaming heatmap (count, sum, mean) */
@@ -772,6 +853,9 @@ export interface StreamXYFrameProps<T = Datum> {
      *  returns SceneNode[] + optional overlays. See `semiotic/recipes` for
      *  reference layouts (waffle, calendar, horizon). */
     customLayout?: import("./customLayout").CustomLayout;
+    /** Called when `customLayout` throws. See `getLayoutFailure()` for the
+     * latest structured failure diagnostic. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to LayoutContext.config.
      *  Typed as `object` so caller-defined interfaces (without an index
      *  signature) flow through without casts; layouts narrow via their
@@ -796,6 +880,15 @@ export interface StreamXYFrameHandle<T = Datum> {
         x: [number, number];
         y: [number, number];
     } | null;
+    /** The most recent custom layout result (nodes/overlays as returned by the
+     *  `customLayout` function) — host readback so pages that need the computed
+     *  placement don't re-run the layout. Null before the first layout or when
+     *  no custom layout is configured. A failed retry retains the prior good
+     *  result; inspect `getLayoutFailure()` to distinguish that recovery. */
+    getCustomLayout(): import("./customLayout").LayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by the next successful
+     * layout, by removing the custom layout, or by `clear()`. */
+    getLayoutFailure(): import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
 }
 export type CanvasRendererFn = (ctx: CanvasRenderingContext2D, nodes: SceneNode[], scales: StreamScales, layout: StreamLayout) => void;
 /** SVG equivalent of CanvasRendererFn — returns React elements for SSR/SVG rendering */

package/dist/components/stream/useCanvasFrameHost.d.ts

@@ -0,0 +1,71 @@
+import * as React from "react";
+import type { DependencyList, MutableRefObject, ReactNode, RefObject } from "react";
+import type { FrameMargin, UseFrameResult } from "./useFrame";
+export interface CanvasFrameHostRuntime {
+    readonly isActive: boolean;
+    subscribe(listener: () => void): () => void;
+}
+export interface CanvasFrameHostStore {
+    cancelIntroAnimation?: () => void;
+}
+export interface UseCanvasFrameHostInput<TStore extends object> {
+    /** The family-owned store only needs the shared hydration escape hatch. */
+    storeRef: RefObject<TStore | null>;
+    /** The family-owned retained-scene repaint flag. */
+    dirtyRef: MutableRefObject<boolean>;
+    /** Stable render closure and scheduler callbacks supplied by `useFrame`. */
+    renderFnRef: MutableRefObject<() => void>;
+    scheduleRender: () => void;
+    cancelRender: () => void;
+    /** Logical pause/visibility runtime supplied by `useFrame`. */
+    frameRuntime: CanvasFrameHostRuntime;
+    /**
+     * Opt out only when a family-specific lifecycle adapter must synchronize
+     * pause/visibility with an external runtime such as a worker. The default
+     * host policy owns ordinary canvas-frame runtime transitions.
+     */
+    manageFrameRuntime?: boolean;
+    hydrated: boolean;
+    wasHydratingFromSSR: boolean;
+    /** Family-specific teardown such as clearing a streaming data adapter. */
+    cleanup?: () => void;
+    /**
+     * Some adapters synchronously paint their initial retained scene through a
+     * family-specific execution policy. They can skip the otherwise useful
+     * mount-time invalidation while retaining dependency-change invalidation.
+     */
+    skipInitialCanvasPaintInvalidation?: boolean;
+    /**
+     * Values that require a data-canvas repaint. Keep this list family-owned:
+     * it expresses paint semantics without teaching the host chart props or
+     * layout rules. Its length must remain stable for one host instance.
+     */
+    canvasPaintDependencies: DependencyList;
+}
+export interface CanvasFrameHostResult {
+    /** Base retained-scene data layer. */
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    /** Optional family use for hover/crosshair/highlight canvas content. */
+    interactionCanvasRef: RefObject<HTMLCanvasElement | null>;
+}
+type FrameCanvasHost = Pick<UseFrameResult, "renderFnRef" | "scheduleRender" | "cancelRender" | "frameRuntime">;
+type FrameCanvasHostInput<TStore extends object> = Omit<UseCanvasFrameHostInput<TStore>, "renderFnRef" | "scheduleRender" | "cancelRender" | "frameRuntime">;
+/**
+ * Installs common canvas-host lifecycle without absorbing family render work.
+ */
+export declare function useCanvasFrameHost<TStore extends object>(input: UseCanvasFrameHostInput<TStore>): CanvasFrameHostResult;
+/** Bind a family-owned store to the common scheduling runtime from useFrame. */
+export declare function useFrameCanvasHost<TStore extends object>(frame: FrameCanvasHost, input: FrameCanvasHostInput<TStore>): CanvasFrameHostResult;
+export interface CanvasFrameBackgroundProps {
+    children: ReactNode;
+    size: readonly [number, number];
+    margin: FrameMargin;
+    /** Preserve a family's existing SVG overflow behavior when it needs it. */
+    overflowVisible?: boolean;
+}
+/**
+ * The shared SVG background layer. Its coordinate translation is common;
+ * resolving graphics and choosing their contents remain family-specific.
+ */
+export declare function CanvasFrameBackground({ children, size, margin, overflowVisible, }: CanvasFrameBackgroundProps): React.ReactNode;
+export {};

package/dist/components/stream/useFrame.d.ts

@@ -6,6 +6,16 @@ import { resolveAnimateConfig } from "./pipelineTransitionUtils";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { TransitionConfig } from "./types";
 import type { HoverPointerCoords } from "./hoverUtils";
+import { FrameRuntime, type FrameClock, type FrameRandom } from "./FrameRuntime";
+/**
+ * The small scheduling surface `useFrame` needs. Keeping this separate from
+ * the browser global gives hook tests a deterministic, handle-agnostic seam
+ * without coupling the frame lifecycle to a broader scheduler abstraction.
+ */
+export interface FrameScheduler {
+    requestAnimationFrame(callback: FrameRequestCallback): number;
+    cancelAnimationFrame(handle: number): void;
+}
 /**
  * Frame-supplied margin defaults. Each Stream Frame has its own — XY's
  * differs from Ordinal's, Network has both a default and a CENTERED variant
@@ -40,6 +50,16 @@ export interface UseFrameInput {
     userMargin: Partial<FrameMargin> | undefined;
     /** Frame's family-default margin. Shallow-merged with `userMargin`. */
     marginDefault: FrameMargin;
+    /**
+     * Visual title rendered by the frame's SVG chrome. A title reserves a small
+     * top strip before plot geometry is calculated so compact caller margins do
+     * not place marks directly beneath the title.
+     */
+    title?: ReactNode;
+    /** Optional legend; a top-positioned legend reserves its first row. */
+    legend?: unknown;
+    /** Legend placement used for shared top-chrome clearance. */
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /** Frame's `foregroundGraphics` prop. */
     foregroundGraphics?: FrameGraphicsProp;
     /** Frame's `backgroundGraphics` prop. */
@@ -48,6 +68,22 @@ export interface UseFrameInput {
     animate?: AnimateProp;
     /** Frame's `transition` prop (legacy / explicit form). */
     transitionProp?: TransitionConfig;
+    /**
+     * Optional rAF seam for deterministic frame tests or an embedding runtime.
+     * It owns both render scheduling and pointer-move coalescing. Omit it to
+     * use the browser's `requestAnimationFrame` / `cancelAnimationFrame`.
+     */
+    frameScheduler?: FrameScheduler;
+    /** Monotonic wall-clock seam used by the frame runtime. */
+    clock?: FrameClock;
+    /** Injectable random seam. A serializable `seed` takes effect when omitted. */
+    random?: FrameRandom;
+    /** Serializable deterministic random seed for frame-local stochastic work. */
+    seed?: number;
+    /** Freeze logical frame time while paused. Opt-in so existing frame families retain their policy. */
+    paused?: boolean;
+    /** Freeze logical frame time while the document is hidden. Opt-in per frame family. */
+    suspendWhenHidden?: boolean;
     /**
      * Frame's `dirtyRef` (the flag that forces a full canvas redraw on the
      * next paint). When provided, useFrame installs a theme-change effect
@@ -94,12 +130,17 @@ export interface UseFrameResult {
     introEnabled: boolean;
     /** Stable id for the AccessibleDataTable region (hash-suffixed). */
     tableId: string;
-    /** Token of the pending rAF, or 0 if none. */
-    rafRef: React.MutableRefObject<number>;
+    /** Shared logical clock, pause/visibility policy, and RNG seam for this host. */
+    frameRuntime: FrameRuntime;
+    /** Token of the pending rAF, or `null` if none. `0` is a valid token. */
+    rafRef: React.MutableRefObject<number | null>;
     /** Frame assigns its render closure here. */
     renderFnRef: React.MutableRefObject<() => void>;
     /** Queue a render on the next animation frame. Coalesces. */
     scheduleRender: () => void;
+    /** Cancel a queued render, if any. Direct/hydration paints use this before
+     * taking over so a stale rAF cannot race a synchronous frame. */
+    cancelRender: () => void;
     /** Frame assigns its hover handler closure here. */
     hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords) => void>;
     /** Frame assigns its pointer-leave closure here. */
@@ -109,6 +150,7 @@ export interface UseFrameResult {
     onPointerMove: (e: {
         clientX: number;
         clientY: number;
+        pointerType?: string;
     }) => void;
     /** Stable callback to attach to canvas's onPointerLeave (or onMouseLeave).
      *  Cancels any pending hover rAF and invokes hoverLeaveRef. */

package/dist/components/stream/useHydration.d.ts

@@ -79,6 +79,12 @@ export interface HydrationLifecycleOptions {
      * would produce.
      */
     renderFnRef: MutableRefObject<() => void>;
+    /**
+     * Optional shared-scheduler cancellation. A hydration paint is synchronous,
+     * so it must take ownership from any queued render before invoking the
+     * frame closure.
+     */
+    cancelRender?: () => void;
     /**
      * Optional unmount cleanup. Frame-specific work the hook can't
      * generalize — e.g. clearing the streaming `DataSourceAdapter`

package/dist/components/stream/useLegendCategoryEmission.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import { type CategoryDomainAccessor } from "./categoryDomain";
+/** Keep legend-category callbacks stable while reading the latest frame props. */
+export declare function useLegendCategoryEmission<TStore extends object, TDatum extends Datum = Datum>(storeRef: RefObject<TStore | null>, accessor: CategoryDomainAccessor<TDatum> | undefined, onChange: ((categories: string[]) => void) | undefined, readData: (store: TStore) => TDatum[]): () => void;

package/dist/components/stream/useSemanticFrameInteractions.d.ts

@@ -0,0 +1,22 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type SemanticClickBehavior, type SemanticHoverBehavior, type SemanticInteractionContext } from "../charts/shared/semanticInteractions";
+import type { OnObservationCallback } from "../store/ObservationStore";
+interface HoverLike {
+    data?: Datum | null;
+    x?: number;
+    y?: number;
+}
+interface SemanticFrameInteractionOptions<Hover extends HoverLike> {
+    customHoverBehavior?: SemanticHoverBehavior<Hover>;
+    customClickBehavior?: SemanticClickBehavior<Hover>;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType: string;
+}
+/** Add semantic observations around the legacy Stream Frame callbacks. */
+export declare function useSemanticFrameInteractions<Hover extends HoverLike>({ customHoverBehavior: customHoverBehaviorProp, customClickBehavior: customClickBehaviorProp, onObservation, chartId, chartType }: SemanticFrameInteractionOptions<Hover>): {
+    customHoverBehavior: (hover: Hover | null, context?: SemanticInteractionContext) => void;
+    customClickBehavior: (hover: Hover | null, context?: SemanticInteractionContext) => void;
+    hasClickBehavior: boolean;
+};
+export {};

package/dist/components/stream/useUpdateResultSnapshot.d.ts

@@ -0,0 +1,7 @@
+import type { UpdateResult, UpdateResultStore } from "./pipelineUpdateContract";
+/**
+ * Read an additive pipeline update snapshot through React's external-store
+ * contract. Store mutation and frame scheduling remain imperative; consumers
+ * can use this only for React-owned inspection or diagnostics.
+ */
+export declare function useUpdateResultSnapshot(store: UpdateResultStore): UpdateResult;

package/dist/components/stream/workerModuleUrl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve a packaged module-worker asset from either published module format.
+ *
+ * tsup's CommonJS transform replaces `import.meta` with an object whose `url`
+ * field is absent. The fallback deliberately uses the real CommonJS module
+ * filename so `new Worker()` still points at the sibling asset shipped in the
+ * tarball. ESM callers retain their literal `new URL(..., import.meta.url)`
+ * expression so browser bundlers can discover and emit the worker asset.
+ */
+export declare function commonJsWorkerModuleUrl(assetName: string): URL;

package/dist/components/stream/xyAnnotationAnchors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Harvest annotation anchors from an XY scene graph.
+ * Every mark with a `pointId` becomes a `{ pointId, x, y, r }` record so
+ * `{ pointId }` annotations resolve regardless of mark type.
+ */
+import type { SceneNode } from "./types";
+export type AnnotationAnchor = {
+    pointId?: string;
+    x: number;
+    y: number;
+    r: number;
+};
+export declare function collectAnnotationAnchors(scene: SceneNode[] | undefined): AnnotationAnchor[] | undefined;

package/dist/components/stream/xyCanvasRenderers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Chart-type → canvas renderer dispatch for StreamXYFrame.
+ * Order matters: earlier renderers paint underneath later ones.
+ */
+import type { StreamChartType } from "./types";
+import type { StreamRendererFn } from "./renderers/types";
+export declare const XY_CANVAS_RENDERERS: Record<StreamChartType, StreamRendererFn[]>;

package/dist/components/stream/xyCrosshair.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Canvas crosshair + line-highlight paint helpers for StreamXYFrame.
+ * Pure drawing — no React / store dependency.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { HoverData, HoverAnnotationConfig, SceneNode } from "./types";
+import type { FrameThemeColors } from "./frameThemeColors";
+export declare function drawCrosshair(ctx: CanvasRenderingContext2D, hover: HoverData, width: number, height: number, config: HoverAnnotationConfig, hoveredNode: SceneNode | null, theme: FrameThemeColors): void;
+export declare function drawLineHighlight(ctx: CanvasRenderingContext2D, scene: SceneNode[], hoveredNode: SceneNode | null, highlightConfig: {
+    style?: Datum | ((d: Datum) => Datum);
+}, theme: FrameThemeColors): void;