semiotic 3.8.0 → 3.8.1

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

@@ -65,7 +65,7 @@ export interface TransitionState {
  * Detects entering nodes (new, no prev match) and exiting nodes (prev, no new match).
  * Mutates scene and exitNodes in place. Returns updated state.
  */
-export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): TransitionState;
+export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>, startTime?: number): TransitionState;
 /**
  * Advance the transition animation. Returns true if still animating.
  * Mutates scene nodes in place.

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

@@ -54,9 +54,16 @@ export declare function createUpdateResult(changeSet: ChangeSet, invalidations:
  * keeps revision bookkeeping out of family-specific data/layout code while
  * preserving each store's existing mutation API.
  */
+export type UpdateResultListener = () => void;
+export interface UpdateResultStore {
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: UpdateResultListener): () => void;
+}
 export declare class UpdateResultTracker {
     private revisions;
     private latest;
+    private listeners;
     get last(): UpdateResult;
+    subscribe(listener: UpdateResultListener): () => void;
     record(changeSet: ChangeSet, invalidations: Iterable<Invalidation>): UpdateResult;
 }

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

@@ -0,0 +1,21 @@
+import type { UpdateResult } from "./pipelineUpdateContract";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+export type { UpdateResult } from "./pipelineUpdateContract";
+/** Shared additive update-result read and subscription surface for stream stores. */
+export interface PipelineUpdateResultSource {
+    readonly last: UpdateResult;
+    subscribe(listener: () => void): () => void;
+}
+/** Public lifecycle surface installed on each stream store prototype. */
+export interface UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    markStylePaintPending(): void;
+    consumeStylePaintPending(): boolean;
+}
+/** Adds the shared lifecycle methods without imposing a base-class constructor. */
+export declare function attachUpdateResultStore(target: {
+    prototype: object;
+}): void;

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

@@ -0,0 +1,27 @@
+import * as React from "react";
+import type { SceneRenderBackend, SceneRenderMode, Style } from "./types";
+type SceneLike = {
+    type?: string;
+    datum?: unknown;
+    style?: Style;
+};
+/** Resolve a whole-scene or per-datum renderer. The legacy `sketchy` token
+ * stays on the existing built-in rendering path. */
+export declare function resolveSceneRenderBackend<Node extends SceneLike>(renderMode: SceneRenderMode<Node> | undefined, node: Node): SceneRenderBackend<Node> | undefined;
+/** Paint nodes in scene order, delegating unsupported runs to the built-in renderer. */
+export declare function paintSceneWithBackend<Node extends SceneLike>(args: {
+    context: CanvasRenderingContext2D;
+    nodes: Node[];
+    renderMode: SceneRenderMode<Node> | undefined;
+    pixelRatio: number;
+    paintBuiltIn: (nodes: Node[]) => void;
+}): void;
+/** Try a backend for SSR/static SVG, then invoke the existing converter. */
+export declare function renderSceneWithBackend<Node extends SceneLike>(args: {
+    node: Node;
+    index: number;
+    renderMode: SceneRenderMode<Node> | undefined;
+    fallback: () => React.ReactNode;
+}): React.ReactNode;
+export declare function resetRenderBackendWarningsForTests(): void;
+export {};

package/dist/components/stream/renderers/canvasRenderHelpers.d.ts

@@ -16,6 +16,7 @@
  * mechanical bits that recur regardless of the shape being painted.
  */
 import type { CurveType } from "../types";
+import { type HatchFill } from "../../charts/shared/hatchFill";
 import type { CurveFactory } from "d3-shape";
 /**
  * Structural shapes for the gradient configs the helpers accept. Kept
@@ -61,7 +62,20 @@ export declare function resolveCurveFactory(curve: CurveType | undefined): Curve
  * `(typeof X === "string" ? resolveCSSColor(ctx, X) : X) || fallback`,
  * repeated once per renderer per fill/stroke site.
  */
-export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+/**
+ * Narrow a possibly-`HatchFill` `style.fill` to the `string | CanvasPattern`
+ * a canvas `fillStyle` accepts, for the direct-assign sites that don't
+ * otherwise route through {@link resolveCanvasFill}. Returns `undefined` for a
+ * nullish (or unresolvable) fill so callers can apply their own fallback with
+ * `?? "…"`.
+ *
+ * Delegates to {@link resolveCanvasFill} so behavior stays consistent: string
+ * fills (including `var(--…)`) resolve through `resolveCSSColor` — a raw CSS
+ * variable written straight to `fillStyle` would silently paint black — and a
+ * `HatchFill` resolves to its `CanvasPattern` (or its resolved background).
+ */
+export declare function coerceCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined): string | CanvasPattern | undefined;
 /**
  * Build a linear gradient from a `FillGradient` config. Returns `null`
  * when the gradient cannot be constructed (fewer than two valid color

package/dist/components/stream/renderers/geoCanvasRenderer.d.ts

@@ -1,4 +1,5 @@
-import type { GeoSceneNode } from "../geoTypes";
+import type { GeoScales, GeoSceneNode } from "../geoTypes";
+import type { StreamLayout } from "../types";
 /**
  * Canvas renderer for GeoAreaSceneNode — projected geographic polygons.
  * Uses Path2D for GPU-accelerated rendering of complex geo paths.
@@ -6,4 +7,4 @@ import type { GeoSceneNode } from "../geoTypes";
  * Points and lines in a geo frame are rendered by the existing
  * pointCanvasRenderer and lineCanvasRenderer respectively.
  */
-export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: any, _layout: any): void;
+export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: GeoScales, _layout: StreamLayout): void;

package/dist/components/stream/renderers/networkParticleRenderer.d.ts

@@ -8,4 +8,4 @@ export declare function renderNetworkParticles(ctx: CanvasRenderingContext2D, po
 /**
  * Spawn particles for all edges proportional to their value.
  */
-export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle): void;
+export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle, random?: () => number): void;

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { Style } from "./types";
+/**
+ * Optional paint backend for pre-computed scene nodes. A backend may change
+ * how a mark looks, but it must not mutate the scene node: original geometry
+ * remains authoritative for interaction, focus, transitions, and accessibility.
+ */
+export interface SceneRenderBackend<Node = unknown> {
+    readonly id: string;
+    cacheKey(node: Node, style: Style): string;
+    drawCanvas(args: {
+        context: CanvasRenderingContext2D;
+        node: Node;
+        style: Style;
+        pixelRatio: number;
+    }): boolean;
+    renderStaticSVG(args: {
+        node: Node;
+        style: Style;
+        key: string;
+    }): ReactNode | null;
+}
+/** A backend can cover the whole scene or be selected per datum. */
+export type SceneRenderDatum<Node> = Node extends {
+    datum?: infer NodeDatum;
+} ? Exclude<NodeDatum, undefined> | null : Datum | null;
+export type SceneRenderMode<Node = unknown> = "sketchy" | SceneRenderBackend<Node> | ((datum: SceneRenderDatum<Node>, node: Node) => "sketchy" | SceneRenderBackend<Node> | undefined);

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

@@ -1,18 +1,45 @@
-import type { RevisionSet, UpdateResult } from "./pipelineUpdateContract";
-type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
-interface SceneRevisionCheck {
+import type { RevisionSet, UpdateResult, UpdateResultStore } from "./pipelineUpdateContract";
+export type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
+export interface SceneRevisionCheck {
     revisions: SceneRevisionSet;
     signature: string;
     sawSignals: boolean;
     wasUnconsumed: boolean;
     warnUnconsumed: boolean;
 }
-/** Development-only consumption and duplicate-compute diagnostics for an XY scene host. */
+interface SceneRevisionStore extends UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+}
+/** Development-only consumption and duplicate-compute diagnostics for a scene host. */
 export declare class SceneRevisionDiagnostics {
+    private readonly hostName;
+    constructor(hostName?: string);
     private lastConsumed;
+    private lastObserved;
     private lastDuplicateWarning;
     private lastUnconsumedWarning;
+    /**
+     * Accept a React external-store observation without participating in frame
+     * scheduling or paint. The imperative result passed to beforeCompute remains
+     * authoritative; retaining the high-water mark only protects development
+     * diagnostics when React observes an update between frame passes.
+     */
+    observeUpdateResult(updateResult: UpdateResult): void;
     beforeCompute(updateResult: UpdateResult, isTransitioning: boolean): SceneRevisionCheck;
     afterCompute(check: SceneRevisionCheck, computedScene: boolean, dimsChanged: boolean): void;
 }
+/** Keep a frame's development-only revision tracker stable across renders. */
+export declare function useSceneRevisionDiagnostics(hostName: string): import("react").RefObject<SceneRevisionDiagnostics>;
+/** Wrap an unconditional scene build with the common revision accounting. */
+export declare function runSceneBuild(diagnostics: SceneRevisionDiagnostics, store: SceneRevisionStore, build: () => void, isTransitioning?: boolean, dimsChanged?: boolean): void;
+/**
+ * Observes external-store revisions without putting diagnostics on a React
+ * render path. Stores can record non-invalidating operational results during
+ * host effects, so a useSyncExternalStore subscription here could feed those
+ * diagnostics back into the host's render cycle.
+ */
+export declare const SceneRevisionDiagnosticsObserver: import("react").MemoExoticComponent<({ store, diagnostics }: {
+    store: UpdateResultStore;
+    diagnostics: SceneRevisionDiagnostics;
+}) => null>;
 export {};

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

@@ -0,0 +1,16 @@
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+/** Interaction props shared by all Stream Frame families. */
+export interface StreamSemanticInteractionProps<Hover> {
+    customHoverBehavior?: SemanticHoverBehavior<Hover>;
+    customClickBehavior?: SemanticClickBehavior<Hover>;
+    /** Structured interaction observations, including semantic focus/activate. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier included in observation events. */
+    chartId?: string;
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+}

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

@@ -0,0 +1,14 @@
+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;
+}

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

@@ -0,0 +1,10 @@
+export declare function resolveHorizontalTickAnchor(mode: "middle" | "edges" | undefined, isLeftmost: boolean, isRightmost: boolean): "start" | "middle" | "end";
+export declare function resolveVerticalTickBaseline(mode: "middle" | "edges" | undefined, isTopmost: boolean, isBottommost: boolean): "hanging" | "middle" | "auto";
+export declare function tickPixelExtent(ticks: Array<{
+    pixel: number;
+}>): {
+    min: number | null;
+    max: number | null;
+};
+export declare function resolveGridDash(style: "dashed" | "dotted" | string | undefined): string | undefined;
+export declare function jaggedBaselinePath(orient: "left" | "right" | "top" | "bottom", width: number, height: number): string;

package/dist/components/stream/test-utils/frameScheduler.d.ts

@@ -0,0 +1,12 @@
+import type { FrameScheduler } from "../useFrame";
+/**
+ * Deterministic rAF scheduler for frame tests. It deliberately permits zero
+ * as the first handle so tests cannot rely on truthiness for pending work.
+ */
+export declare function createFrameScheduler(firstHandle?: number): {
+    scheduler: FrameScheduler;
+    requestedHandles: number[];
+    cancelledHandles: number[];
+    readonly pendingCount: number;
+    flush(timestamp?: number): void;
+};

package/dist/components/stream/test-utils/revisionConsumption.d.ts

@@ -0,0 +1,13 @@
+import { SceneRevisionDiagnostics, type SceneRevisionCheck } from "../sceneRevisionDiagnostics";
+import type { UpdateResult } from "../pipelineUpdateContract";
+export interface UnconsumedSceneRevisionProbe {
+    diagnostics: SceneRevisionDiagnostics;
+    initial: SceneRevisionCheck;
+    later: SceneRevisionCheck;
+}
+/**
+ * Assert the contract that a later style/state result cannot conceal scene
+ * work that a host has not consumed. Callers finish the probe with
+ * `diagnostics.afterCompute(probe.later, false, false)` and assert its warning.
+ */
+export declare function assertUnconsumedSceneRevisionSurvivesLaterUpdate(initialResult: UpdateResult, laterResult: UpdateResult, hostName?: string): UnconsumedSceneRevisionProbe;

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

@@ -0,0 +1,31 @@
+/**
+ * Shared title clearance for StreamFrame plot areas.
+ *
+ * Stream titles live in the outer SVG chrome while marks are translated into
+ * the plot margin. Reserving this strip before layout keeps titles from
+ * touching or overlapping the first row of marks when consumers supply a
+ * compact top margin.
+ */
+export interface TitleMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Enough room for the standard 14px title plus a visible gap to the plot. */
+export declare const MIN_TITLE_TOP_MARGIN = 36;
+/** One horizontal legend row plus its inset when no title is present. */
+export declare const MIN_TOP_LEGEND_MARGIN = 34;
+/** The standard title strip plus one horizontal legend row and plot gap. */
+export declare const MIN_TITLE_TOP_LEGEND_MARGIN = 58;
+/** Baseline that leaves a calm outer-edge inset for the standard title face. */
+export declare const TITLE_BASELINE = 22;
+/** Static SVG and GIF output only render text titles in their SVG chrome. */
+export declare function hasTextTitle(title: unknown): title is string;
+/**
+ * Reserve the shared top chrome before any frame calculates plot geometry.
+ * A raw StreamFrame can supply both a compact margin and a top legend, so the
+ * legend's first row needs its own minimum rather than relying on HOC margins.
+ */
+export declare function reserveFrameChromeMargin<T extends TitleMargin>(margin: T, hasTitle: boolean, hasTopLegend?: boolean): T;
+export declare function reserveTitleMargin<T extends TitleMargin>(margin: T, title: unknown): T;

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

@@ -4,27 +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) */
@@ -105,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 */
@@ -578,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[];
@@ -757,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;
@@ -791,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;
@@ -861,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) */

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,7 @@ 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
@@ -49,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. */
@@ -63,6 +74,16 @@ export interface UseFrameInput {
      * 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
@@ -109,6 +130,8 @@ export interface UseFrameResult {
     introEnabled: boolean;
     /** Stable id for the AccessibleDataTable region (hash-suffixed). */
     tableId: string;
+    /** 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. */

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

@@ -1,5 +1,5 @@
-import { type MutableRefObject, type RefObject } from "react";
-import type { PipelineStore } from "./PipelineStore";
+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(storeRef: RefObject<PipelineStore | null>, accessorRef: MutableRefObject<CategoryDomainAccessor | undefined>, onChangeRef: MutableRefObject<((categories: string[]) => void) | undefined>, previousRef: MutableRefObject<string[]>): () => void;
+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;