semiotic 3.3.0 → 3.4.0

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

@@ -2,7 +2,8 @@ import type { ReactNode } from "react";
 import type { OnObservationCallback } from "../store/ObservationStore";
 import type { HoverData, AnnotationContext } from "../realtime/types";
 import type { LegendGroup } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, StalenessConfig } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -52,6 +53,8 @@ export interface RealtimeEdge {
     _targetY0?: number;
     _targetY1?: number;
     _targetSankeyWidth?: number;
+    /** Set during intro animation to allow edge interpolation from width 0 */
+    _introFromZero?: boolean;
     direction?: string;
     circular?: boolean;
     circularPathData?: any;
@@ -168,13 +171,16 @@ export interface NetworkRectNode {
     _pulseGlowRadius?: number;
 }
 /** Arc node — used by chord */
+/** Arc node — used by chord. Angles in canvas convention (0 = 3 o'clock). */
 export interface NetworkArcNode {
     type: "arc";
     cx: number;
     cy: number;
     innerR: number;
     outerR: number;
+    /** Start angle in radians, canvas convention (0 = 3 o'clock, positive = clockwise) */
     startAngle: number;
+    /** End angle in radians, canvas convention */
     endAngle: number;
     style: Style;
     datum: any;
@@ -205,6 +211,9 @@ export interface NetworkBezierEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    /** Lazily-built Path2D for hit testing; invalidated when pathD changes. */
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Ribbon edge — used by chord */
 export interface NetworkRibbonEdge {
@@ -214,6 +223,8 @@ export interface NetworkRibbonEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 /** Curved edge — used by tree, cluster */
 export interface NetworkCurvedEdge {
@@ -223,6 +234,8 @@ export interface NetworkCurvedEdge {
     datum: any;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _cachedPath2D?: Path2D;
+    _cachedPath2DSource?: string;
 }
 export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
@@ -290,8 +303,10 @@ export interface NetworkPipelineConfig {
     sourceAccessor?: string | ((d: any) => string);
     targetAccessor?: string | ((d: any) => string);
     valueAccessor?: string | ((d: any) => number);
+    /** Edge ID accessor for removeEdge(edgeId) — enables single-ID edge removal */
+    edgeIdAccessor?: string | ((d: any) => string);
     childrenAccessor?: string | ((d: any) => any[]);
-    hierarchySum?: (d: any) => number;
+    hierarchySum?: string | ((d: any) => number);
     orientation?: "horizontal" | "vertical";
     nodeAlign?: "justify" | "left" | "right" | "center";
     nodePaddingRatio?: number;
@@ -323,6 +338,9 @@ export interface NetworkPipelineConfig {
     nodeSizeRange?: [number, number];
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Whether to animate elements on first render (nodes scale up, edges fade in) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     /** Ring arrangement mode: "flat" (all children in one ring), "solar" (one per ring),
@@ -370,8 +388,10 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     sourceAccessor?: string | ((d: T) => string);
     targetAccessor?: string | ((d: T) => string);
     valueAccessor?: string | ((d: T) => number);
+    /** Edge ID accessor for removeEdge(edgeId) single-ID removal */
+    edgeIdAccessor?: string | ((d: any) => string);
     childrenAccessor?: string | ((d: T) => T[]);
-    hierarchySum?: (d: T) => number;
+    hierarchySum?: string | ((d: T) => number);
     orientation?: "horizontal" | "vertical";
     nodeAlign?: "justify" | "left" | "right" | "center";
     nodePaddingRatio?: number;
@@ -413,24 +433,9 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     className?: string;
     background?: string;
     enableHover?: boolean;
-    tooltipContent?: (d: {
-        type: "node" | "edge";
-        data: any;
-        x: number;
-        y: number;
-    }) => ReactNode;
-    customHoverBehavior?: (d: {
-        type: "node" | "edge";
-        data: any;
-        x: number;
-        y: number;
-    } | null) => void;
-    customClickBehavior?: (d: {
-        type: "node" | "edge";
-        data: any;
-        x: number;
-        y: number;
-    } | null) => void;
+    tooltipContent?: (d: HoverData) => ReactNode;
+    customHoverBehavior?: (d: HoverData | null) => void;
+    customClickBehavior?: (d: HoverData | null) => void;
     /** Observation callback — emits hover/click events to the ObservationStore and this callback */
     onObservation?: OnObservationCallback;
     /** Chart instance identifier for observation filtering */
@@ -455,6 +460,11 @@ export interface StreamNetworkFrameProps<T = Record<string, any>> {
     backgroundGraphics?: ReactNode;
     decay?: DecayConfig;
     pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     thresholds?: ThresholdAlertConfig;
     orbitMode?: "flat" | "solar" | "atomic" | number[];
@@ -477,8 +487,8 @@ export interface StreamNetworkFrameHandle {
     pushMany(edges: EdgePush[]): void;
     /** Remove a node by ID. Also removes connected edges. */
     removeNode(id: string): boolean;
-    /** Remove all edges between source and target node IDs. */
-    removeEdge(sourceId: string, targetId: string): boolean;
+    /** Remove edges by source+target, or by edge ID when edgeIdAccessor is configured. */
+    removeEdge(sourceIdOrEdgeId: string, targetId?: string): boolean;
     /** Update a node's data by ID. Returns previous data. */
     updateNode(id: string, updater: (data: Record<string, any>) => Record<string, any>): Record<string, any> | null;
     /** Update all edges between source+target. Returns array of previous data. */

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

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig } from "./types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup } from "../types/legendTypes";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane";
 export interface OrdinalScales {
@@ -15,8 +16,12 @@ export interface WedgeSceneNode {
     cy: number;
     innerRadius: number;
     outerRadius: number;
+    /** Start angle in radians, canvas convention (0 = 3 o'clock, positive = clockwise) */
     startAngle: number;
+    /** End angle in radians, canvas convention */
     endAngle: number;
+    /** Corner radius for rounded wedge arcs (d3-shape arc.cornerRadius) */
+    cornerRadius?: number;
     style: Style;
     datum: any;
     category?: string;
@@ -24,6 +29,8 @@ export interface WedgeSceneNode {
     _pulseColor?: string;
     _pulseGlowRadius?: number;
     _targetOpacity?: number;
+    _targetStartAngle?: number;
+    _targetEndAngle?: number;
     _transitionKey?: string;
 }
 export interface BoxplotSceneNode {
@@ -149,21 +156,27 @@ export interface OrdinalPipelineConfig {
     windowMode: WindowMode;
     extentPadding: number;
     projection: "vertical" | "horizontal" | "radial";
-    oAccessor?: string | ((d: any) => string);
-    rAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
+    categoryAccessor?: string | ((d: any) => string);
+    valueAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
     colorAccessor?: string | ((d: any) => string);
     stackBy?: string | ((d: any) => string);
     groupBy?: string | ((d: any) => string);
-    multiAxis?: boolean;
     timeAccessor?: string | ((d: any) => number);
-    valueAccessor?: string | ((d: any) => number);
-    categoryAccessor?: string | ((d: any) => string);
+    /** @deprecated Use categoryAccessor */
+    oAccessor?: string | ((d: any) => string);
+    /** @deprecated Use valueAccessor */
+    rAccessor?: string | ((d: any) => number) | Array<string | ((d: any) => number)>;
+    multiAxis?: boolean;
     rExtent?: [number?, number?];
     oExtent?: string[];
     barPadding?: number;
+    /** Rounded top corner radius for bar charts. Only the end away from the baseline is rounded. For stacked bars, only the topmost segment gets rounded. */
+    roundedTop?: number;
     /** When true, adds padding below the 0 baseline. When false (default), bars are flush with the axis line. */
     baselinePadding?: boolean;
     innerRadius?: number;
+    /** Corner radius for rounded wedge arcs (pie/donut) */
+    cornerRadius?: number;
     normalize?: boolean;
     startAngle?: number;
     /** Total arc sweep in degrees (default 360 = full circle). Used by GaugeChart for partial arcs. */
@@ -174,34 +187,41 @@ export interface OrdinalPipelineConfig {
     amplitude?: number;
     connectorOpacity?: number;
     showLabels?: boolean;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     connectorAccessor?: string | ((d: any) => string);
     connectorStyle?: Style | ((d: any) => Style);
     dynamicColumnWidth?: string | ((data: any[]) => number);
     pieceStyle?: (d: any, category?: string) => Style;
     summaryStyle?: (d: any, category?: string) => Style;
     colorScheme?: string | string[];
+    themeCategorical?: string[];
     barColors?: Record<string, string>;
     /** ID accessor for remove() — extracts a unique identifier from each datum */
     dataIdAccessor?: string | ((d: any) => string);
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
 }
 export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     chartType: OrdinalChartType;
     runtimeMode?: "bounded" | "streaming";
     data?: T[];
-    oAccessor?: string | ((d: T) => string);
-    rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    /** Category field — the ordinal dimension (replaces oAccessor) */
+    categoryAccessor?: string | ((d: T) => string);
+    /** Value field — the quantitative dimension (replaces rAccessor). Can be array for multiAxis. */
+    valueAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
     colorAccessor?: string | ((d: T) => string);
     stackBy?: string | ((d: T) => string);
     groupBy?: string | ((d: T) => string);
-    multiAxis?: boolean;
     timeAccessor?: string | ((d: T) => number);
-    valueAccessor?: string | ((d: T) => number);
-    categoryAccessor?: string | ((d: T) => string);
+    /** @deprecated Use categoryAccessor instead */
+    oAccessor?: string | ((d: T) => string);
+    /** @deprecated Use valueAccessor instead */
+    rAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
+    multiAxis?: boolean;
     projection?: "vertical" | "horizontal" | "radial";
     size?: [number, number];
     responsiveWidth?: boolean;
@@ -213,8 +233,10 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
         left?: number;
     };
     barPadding?: number;
+    roundedTop?: number;
     baselinePadding?: boolean;
     innerRadius?: number;
+    cornerRadius?: number;
     normalize?: boolean;
     startAngle?: number;
     sweepAngle?: number;
@@ -228,7 +250,7 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     rExtent?: [number?, number?];
     oExtent?: string[];
     extentPadding?: number;
-    oSort?: ((a: any, b: any) => number) | boolean | "asc" | "desc";
+    oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
     arrowOfTime?: ArrowOfTime;
     windowMode?: WindowMode;
     windowSize?: number;
@@ -246,9 +268,21 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     barColors?: Record<string, string>;
     showAxes?: boolean;
     showCategoryTicks?: boolean;
+    /** Category axis label */
+    categoryLabel?: string;
+    /** Value axis label */
+    valueLabel?: string;
+    /** Category tick formatter */
+    categoryFormat?: (d: string, index?: number) => string | ReactNode;
+    /** Value tick formatter */
+    valueFormat?: (d: number | string) => string;
+    /** @deprecated Use categoryLabel */
     oLabel?: string;
+    /** @deprecated Use valueLabel */
     rLabel?: string;
+    /** @deprecated Use categoryFormat */
     oFormat?: (d: string, index?: number) => string | ReactNode;
+    /** @deprecated Use valueFormat */
     rFormat?: (d: number | string) => string;
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
@@ -288,6 +322,10 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
@@ -299,6 +337,19 @@ export interface StreamOrdinalFrameProps<T = Record<string, any>> {
 export interface StreamOrdinalFrameHandle<T = Record<string, any>> {
     push(datum: T): void;
     pushMany(data: T[]): void;
+    /** Replace all data. Unlike `clear() + pushMany()`, `replace()` preserves
+     *  the previous scene's position snapshot so data-change transitions fire.
+     *  Use when you need to swap in a full new dataset (e.g. re-aggregated
+     *  values from streaming input) and want the bars/points/etc. to animate
+     *  between the old and new positions.
+     *
+     *  Note: for datasets within the DataSourceAdapter chunk threshold (the
+     *  common case for aggregator HOCs like LikertChart) the replacement
+     *  lands in a single changeset. Larger datasets fall through to the
+     *  progressive-chunked path used by the `data` prop — the first chunk
+     *  resets + seeds the buffer, subsequent chunks append on successive
+     *  animation frames, so replacement is not instantaneous for large N. */
+    replace(data: T[]): void;
     /** Remove data items by ID. Requires dataIdAccessor. */
     remove(id: string | string[]): T[];
     /** Update data items by ID in place. Requires dataIdAccessor. Returns previous values. */

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

@@ -1,11 +1,12 @@
 /**
- * Decay encoding for XY pipeline scene nodes.
+ * Shared decay encoding utilities for all pipeline stores.
  *
- * Applies age-based opacity fade to scene nodes — linear, exponential, or step.
- * Per-vertex decay for line/area nodes, uniform for discrete nodes (point, rect, etc.).
+ * `computeDecayOpacity()` — core algorithm used by all four pipeline stores
+ * (XY, Ordinal, Network, Geo) to compute age-based opacity.
  *
- * Dependencies: types (SceneNode, DecayConfig)
- * Consumed by: PipelineStore.computeScene (after scene build, before transitions)
+ * `applyDecay()` — XY-specific application that handles per-vertex decay
+ * for line/area nodes. Other stores call `computeDecayOpacity()` directly
+ * with their own node iteration logic.
  */
 import type { SceneNode, DecayConfig } from "./types";
 /**

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

@@ -40,3 +40,24 @@ export declare function lerp(from: number, to: number, t: number): number;
  * Get the current timestamp in a way that works both in browser and Node.
  */
 export declare function now(): number;
+/** The animate prop type accepted by all HOCs and Stream Frames.
+ *  Single source of truth — re-exported by types.ts, ordinalTypes.ts, networkTypes.ts, geoTypes.ts. */
+export type AnimateProp = boolean | {
+    duration?: number;
+    easing?: "linear" | "ease-out";
+    intro?: boolean;
+};
+/**
+ * Resolve the declarative `animate` prop into a concrete TransitionConfig.
+ * Used by all 4 Stream Frames. `animate` takes precedence over `transitionProp`.
+ */
+export declare function resolveAnimateConfig(animate: AnimateProp | undefined, transitionProp: {
+    duration?: number;
+    easing?: "ease-out" | "linear";
+} | undefined): {
+    transition: {
+        duration?: number;
+        easing?: "ease-out" | "linear";
+    } | undefined;
+    introEnabled: boolean;
+};

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

@@ -0,0 +1,22 @@
+import type { Quadtree } from "d3-quadtree";
+export interface QuadtreeHit<T> {
+    node: T;
+    distance: number;
+}
+/**
+ * Find the closest point whose own hit radius contains the cursor.
+ *
+ * Uses `quadtree.visit()` to enumerate every candidate within the widened
+ * search radius (maxDistance extended by the largest point radius in the
+ * scene). `quadtree.find()` alone is insufficient because it returns the
+ * nearest candidate by center-to-center distance — a farther point with a
+ * much larger visual radius can still be a valid hit that `find()` would
+ * hide.
+ *
+ * `T` must expose `x`, `y`, and `r` — the standard `PointSceneNode` shape.
+ */
+export declare function findHitPointInQuadtree<T extends {
+    x: number;
+    y: number;
+    r: number;
+}>(qt: Quadtree<T>, px: number, py: number, maxDistance: number, maxPointRadius: number): QuadtreeHit<T> | null;

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

@@ -5,13 +5,30 @@
  * reads the computed value from the canvas element. Otherwise returns
  * the input unchanged.
  *
- * Per-canvas cache avoids repeated getComputedStyle calls within a single
- * paint cycle. The cache is cleared on theme changes via clearCSSColorCache(),
- * which each Stream Frame calls in its theme-change useEffect.
+ * Per-canvas cache avoids repeated `getComputedStyle` calls. Cached entries
+ * are tagged with a global version counter that's bumped whenever a theme
+ * change is detected — either through `clearCSSColorCache()` (called by
+ * Stream Frames on `currentTheme` change) or via the global observer below
+ * (catches external class toggles on `<html>` and `prefers-color-scheme`
+ * media-query changes that bypass React).
  */
 export declare function resolveCSSColor(ctx: CanvasRenderingContext2D, value: string | undefined): string | undefined;
 /**
- * Clear the per-canvas CSS variable cache. Called by Stream Frames
- * when the theme changes so the next paint reads fresh computed values.
+ * Invalidate the CSS variable cache. Stream Frames call this from their
+ * `currentTheme` `useEffect` so the next paint reads fresh computed values.
+ *
+ * The `canvas` argument is accepted for backward compatibility but ignored —
+ * invalidation is global because theme changes are global.
+ */
+export declare function clearCSSColorCache(_canvas?: HTMLCanvasElement): void;
+/**
+ * Test-only: reset all cache state, including disconnecting any installed
+ * observer/matchMedia listeners. Required for test isolation — without it,
+ * observers accumulate across files and bump `currentVersion` more than once
+ * per real DOM mutation.
+ *
+ * `currentVersion` is *incremented* (not reset to zero) so any WeakMap entries
+ * that survive from a previous test can't accidentally be re-validated by a
+ * version collision.
  */
-export declare function clearCSSColorCache(canvas: HTMLCanvasElement): void;
+export declare function _resetCSSColorCacheForTest(): void;

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
+import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
@@ -107,6 +108,8 @@ export interface LineSceneNode {
     _prevPath?: [number, number][];
     /** Target path coordinates for interpolation during transitions */
     _targetPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals line from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface AreaSceneNode {
     type: "area";
@@ -156,6 +159,8 @@ export interface AreaSceneNode {
     _prevBottomPath?: [number, number][];
     /** Target bottom path coordinates for interpolation during transitions */
     _targetBottomPath?: [number, number][];
+    /** Intro clip fraction (0→1): reveals area from left to right via canvas clip */
+    _introClipFraction?: number;
 }
 export interface PointSceneNode {
     type: "point";
@@ -187,6 +192,10 @@ export interface RectSceneNode {
     y: number;
     w: number;
     h: number;
+    /** Rounded corner radius on the end away from the baseline */
+    roundedTop?: number;
+    /** Which edge to round: "top"/"bottom" (vertical), "right"/"left" (horizontal) */
+    roundedEdge?: "top" | "bottom" | "right" | "left";
     style: Style;
     datum: any;
     group?: string;
@@ -274,6 +283,15 @@ export interface Changeset<T = Record<string, any>> {
     bounded: boolean;
     /** Hint: total dataset size when progressively chunking bounded data */
     totalSize?: number;
+    /** When true on a bounded changeset, the store replaces the buffer
+     *  contents but does NOT clear its category insertion-order memory
+     *  and marks itself as having received streaming-sourced data. Used
+     *  by aggregator HOCs (LikertChart, future density/bin charts) that
+     *  re-derive their full dataset from streaming input on every push —
+     *  the user perceives it as a stream even though the transport is
+     *  a wholesale replacement. Without this, re-aggregation would wipe
+     *  the category order and categories would shuffle on every tick. */
+    preserveCategoryOrder?: boolean;
 }
 /**
  * Note: when xScaleType="time", the x scale is a d3.scaleTime at runtime
@@ -463,6 +481,10 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     pulse?: PulseConfig;
     /** Smooth position transitions on data change */
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     /** Frame-level data liveness indicator */
     staleness?: StalenessConfig;
     /** Marginal distribution plots in axis margins (histogram, violin, ridgeline, boxplot) */

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

@@ -0,0 +1,122 @@
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { SemioticTheme } from "../store/ThemeStore";
+import { useResponsiveSize } from "./useResponsiveSize";
+import { resolveAnimateConfig } from "./pipelineTransitionUtils";
+import type { AnimateProp } from "./pipelineTransitionUtils";
+import type { TransitionConfig } from "./types";
+import type { HoverPointerCoords } from "./hoverUtils";
+/**
+ * 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
+ * for radial chart types. The hook accepts the resolved default and
+ * shallow-merges user margin on top.
+ */
+export interface FrameMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Foreground/background graphics can be a ReactNode (rendered as-is) or a
+ * function that receives the current `{ size, margin }` and returns one.
+ * The function form lets users place chrome relative to the chart area.
+ */
+export type FrameGraphicsProp = ReactNode | ((ctx: {
+    size: number[];
+    margin: FrameMargin;
+}) => ReactNode);
+export interface UseFrameInput {
+    /** Resolved size `[width, height]`. Each frame defaults its `size` prop
+     *  before calling, so this is never undefined. */
+    sizeProp: [number, number];
+    /** Frame's `responsiveWidth` prop. */
+    responsiveWidth: boolean | undefined;
+    /** Frame's `responsiveHeight` prop. */
+    responsiveHeight: boolean | undefined;
+    /** Frame's user-supplied margin (always partial — each side optional).
+     *  Matches the `margin?:` prop type on every Stream Frame. */
+    userMargin: Partial<FrameMargin> | undefined;
+    /** Frame's family-default margin. Shallow-merged with `userMargin`. */
+    marginDefault: FrameMargin;
+    /** Frame's `foregroundGraphics` prop. */
+    foregroundGraphics?: FrameGraphicsProp;
+    /** Frame's `backgroundGraphics` prop. */
+    backgroundGraphics?: FrameGraphicsProp;
+    /** Frame's `animate` prop. */
+    animate?: AnimateProp;
+    /** Frame's `transition` prop (legacy / explicit form). */
+    transitionProp?: TransitionConfig;
+    /**
+     * Frame's `dirtyRef` (the flag that forces a full canvas redraw on the
+     * next paint). When provided, useFrame installs a theme-change effect
+     * that bumps it to `true`, clears the CSS-var cache, and queues a
+     * render — the pattern that all four frames duplicated.
+     *
+     * Optional because this is a Tier B add-on; before the migration the
+     * frames installed this themselves. The hook keeps the input optional
+     * so a frame can opt in independently, but in practice all four pass
+     * it.
+     *
+     * `dirtyRef` is owned by the frame (not the hook) because its initial
+     * value differs — only `StreamXYFrame` inits to `false`; Ordinal,
+     * Network, and Geo all init to `true` (load-bearing for first-paint
+     * timing on those three).
+     */
+    themeDirtyRef?: React.MutableRefObject<boolean>;
+}
+export interface UseFrameResult {
+    /** Reduced-motion preference at last render (for re-render gating). */
+    reducedMotion: boolean;
+    /** Reduced-motion ref-mirror so render closures see the latest value
+     *  without depending on it. */
+    reducedMotionRef: React.MutableRefObject<boolean>;
+    /** Ref to attach to the responsive container. */
+    responsiveRef: ReturnType<typeof useResponsiveSize>[0];
+    /** Resolved size `[width, height]` accounting for `responsiveWidth/Height`. */
+    size: [number, number];
+    /** Effective margin (`marginDefault` ⊕ `userMargin`). */
+    margin: FrameMargin;
+    /** `size[0] - margin.left - margin.right`. */
+    adjustedWidth: number;
+    /** `size[1] - margin.top - margin.bottom`. */
+    adjustedHeight: number;
+    /** Resolved foreground (function-or-node, evaluated). */
+    resolvedForeground: ReactNode;
+    /** Resolved background (function-or-node, evaluated). */
+    resolvedBackground: ReactNode;
+    /** Current theme from the ThemeStore — re-renders on theme change. */
+    currentTheme: SemioticTheme;
+    /** Resolved transition config from `animate`/`transition` props. */
+    transition: ReturnType<typeof resolveAnimateConfig>["transition"];
+    /** Whether the intro animation should run on first render. */
+    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>;
+    /** Frame assigns its render closure here. */
+    renderFnRef: React.MutableRefObject<() => void>;
+    /** Queue a render on the next animation frame. Coalesces. */
+    scheduleRender: () => void;
+    /** Frame assigns its hover handler closure here. */
+    hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords) => void>;
+    /** Frame assigns its pointer-leave closure here. */
+    hoverLeaveRef: React.MutableRefObject<() => void>;
+    /** Stable callback to attach to canvas's onPointerMove (or onMouseMove).
+     *  Captures the coords and queues a single rAF to drain into hoverHandlerRef. */
+    onPointerMove: (e: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Stable callback to attach to canvas's onPointerLeave (or onMouseLeave).
+     *  Cancels any pending hover rAF and invokes hoverLeaveRef. */
+    onPointerLeave: () => void;
+}
+/**
+ * Bundles the universally-shared setup boilerplate that opens every
+ * Stream Frame. See `FRAME_COMPOSITION_LOG.md` for which concerns are
+ * inside this hook vs. left frame-specific.
+ */
+export declare function useFrame(input: UseFrameInput): UseFrameResult;