semiotic 3.7.5 → 3.8.1

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

@@ -1,12 +1,19 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, ThemeSemanticColors } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { MarginType } from "../types/marginType";
+import type { GeoCustomLayout } from "./geoCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -41,6 +48,8 @@ export interface GeoAreaSceneNode {
     screenArea: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     interactive?: boolean;
     /** Lazily-cached Path2D parsed from pathData (avoids re-parsing on every hit test) */
@@ -54,33 +63,42 @@ export interface GeoLineSceneNode {
     path: [number, number][];
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
 }
-/** Union of all scene node types that GeoFrame produces */
-export type GeoSceneNode = GeoAreaSceneNode | PointSceneNode | GeoLineSceneNode;
+/** Union of all scene node types that GeoFrame produces. `GlyphSceneNode`
+ *  joins for custom geo layouts — projected pictograms standing on the map. */
+export type GeoSceneNode = GeoAreaSceneNode | PointSceneNode | GlyphSceneNode | GeoLineSceneNode;
 export interface GeoScales {
     projection: GeoProjection;
-    geoPath: GeoPath<any, GeoPermissibleObjects>;
+    geoPath: GeoPath<void, GeoPermissibleObjects>;
     projectedPoint: (lon: number, lat: number) => [number, number] | null;
     invertedPoint: (px: number, py: number) => [number, number] | null;
 }
 export interface GeoPipelineConfig {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
+     * @default 0
+     */
+    fitPadding?: number | null;
     xAccessor?: string | ((d: Datum) => number);
     yAccessor?: string | ((d: Datum) => number);
     lineDataAccessor?: string | ((d: Datum) => Datum[]);
     lineType?: "geo" | "line";
     /** Flow rendering style: "basic" (straight/great-circle), "offset" (bidirectional offset), "arc" (curved arcs) @default "basic" */
     flowStyle?: "basic" | "offset" | "arc";
-    areaStyle?: Style | ((d: Datum) => Style);
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     lineStyle?: Style | ((d: Datum, group?: string) => Style);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Theme-resolved semantic role colors — default fallback before hardcoded hex. See `ThemeSemanticColors` in ./types. */
     themeSemantic?: ThemeSemanticColors;
     /** Theme sequential scheme name — fallback for ChoroplethMap when colorScheme is not set. */
@@ -89,6 +107,10 @@ export interface GeoPipelineConfig {
     themeDiverging?: string;
     graticule?: boolean | GraticuleConfig;
     projectionTransform?: DistanceCartogramConfig;
+    /** Maximum retained points and lines after the store enters streaming mode. @default 500 */
+    windowSize?: number;
+    /** Logical clock used for Geo pulse and transition work. */
+    clock?: import("./FrameRuntime").FrameClock;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
@@ -99,15 +121,37 @@ export interface GeoPipelineConfig {
     pointIdAccessor?: string | ((d: Datum) => string);
     /** ID accessor on line data — required for `removeLine` by id. */
     lineIdAccessor?: string | ((d: Datum) => string);
+    customLayout?: GeoCustomLayout;
+    layoutConfig?: object;
+    layoutMargin?: MarginType;
+    layoutSelection?: CustomLayoutSelection | null;
+    /** Receives structured information if `customLayout` throws. */
+    onLayoutError?: (diagnostic: CustomLayoutFailureDiagnostic) => void;
+    themeCategorical?: string[];
 }
 export interface StreamGeoFrameProps<T = Datum> {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
-    fitPadding?: number;
+    /**
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
+     * @default 0
+     */
+    fitPadding?: number | null;
     areas?: GeoJSON.Feature[];
     points?: T[];
     lines?: T[];
+    /** Replace built-in area/line/point scene construction with a custom layout. */
+    customLayout?: GeoCustomLayout;
+    /** User configuration threaded to `GeoLayoutContext.config`. */
+    layoutConfig?: object;
+    /** Shared-selection projection supplied by `GeoCustomChart`. */
+    layoutSelection?: CustomLayoutSelection | null;
+    /** Receives structured information if `customLayout` throws. The prior
+     *  successful scene remains visible when one is available. */
+    onLayoutError?: (diagnostic: CustomLayoutFailureDiagnostic) => void;
     xAccessor?: string | ((d: T) => number);
     yAccessor?: string | ((d: T) => number);
     lineDataAccessor?: string | ((d: T) => Datum[]);
@@ -155,12 +199,16 @@ export interface StreamGeoFrameProps<T = Datum> {
     className?: string;
     background?: string;
     runtimeMode?: "bounded" | "streaming";
-    areaStyle?: Style | ((d: Datum) => Style);
+    /** Maximum retained points and lines after imperative streaming begins. @default 500 */
+    windowSize?: number;
+    /** Optional scene paint backend. Exact projected geometry remains interactive. */
+    renderMode?: SceneRenderMode<GeoSceneNode>;
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     lineStyle?: Style | ((d: Datum, group?: string) => Style);
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Categorical color field. For ChoroplethMap reads from area `properties`
      * (or top-level fallback); for ProportionalSymbolMap reads from each point.
@@ -173,9 +221,23 @@ export interface StreamGeoFrameProps<T = Datum> {
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
-    customClickBehavior?: (d: HoverData | null) => void;
-    customHoverBehavior?: (d: HoverData | null) => void;
+    /**
+     * Allow chart-local tooltips to extend beyond the frame bounds.
+     * Useful when a non-portal tooltip should overlap adjacent chart chrome.
+     * @default false
+     */
+    allowTooltipOverflow?: boolean;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    /** 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;
     annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     decay?: DecayConfig;
     pulse?: PulseConfig;
@@ -185,6 +247,18 @@ export interface StreamGeoFrameProps<T = Datum> {
      *  Set `{ intro: false }` to disable the intro animation. */
     animate?: AnimateProp;
     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 Geo frames. */
+    suspendWhenHidden?: boolean;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
@@ -230,7 +304,7 @@ export interface StreamGeoFrameHandle {
     getLines(): Datum[];
     clear(): void;
     getProjection(): GeoProjection | null;
-    getGeoPath(): GeoPath<any, GeoPermissibleObjects> | null;
+    getGeoPath(): GeoPath<void, GeoPermissibleObjects> | null;
     /** Get cartogram layout info (center position, max cost, radius) */
     getCartogramLayout(): {
         cx: number;
@@ -244,4 +318,12 @@ export interface StreamGeoFrameHandle {
     resetZoom(): void;
     /** Get current data points */
     getData(): Datum[];
+    /** The most recent custom layout result — 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 recovery. */
+    getCustomLayout(): import("./geoCustomLayout").GeoLayoutResult | null;
+    /** The most recent custom-layout failure, or null after a successful retry,
+     *  clear, or explicit removal of `customLayout`. */
+    getLayoutFailure(): CustomLayoutFailureDiagnostic | null;
 }

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

@@ -0,0 +1,98 @@
+/**
+ * Glyph definitions — the composite-pictogram sibling of `symbolPath.ts`.
+ *
+ * A `symbol` scene node is one path; a `glyph` scene node is a small
+ * multi-part vector pictogram (an ISOTYPE sign: a server cabinet with accent
+ * vents, a factory with windows) defined once in definition space and stamped
+ * per datum with per-node color, accent, size, and partial fill. The same
+ * `GlyphDef` renders identically on canvas (`drawGlyphParts`), in SVG/SSR
+ * (`SceneToSVG`), and in any React chrome the host draws, because everything
+ * reads these helpers.
+ *
+ * Paint roles, not colors: parts declare `fill: "color" | "accent"` (or a
+ * literal CSS color) and the node supplies the actual paints — one definition
+ * serves every category/status recoloring, exactly how classic pictogram
+ * plates reused one cut in many inks.
+ */
+/** One drawable part of a glyph, in definition coordinates. */
+export interface GlyphPart {
+    /** SVG path data in definition (viewBox) coordinates. */
+    d: string;
+    /**
+     * Fill paint: `"color"` (the node's primary paint), `"accent"` (the node's
+     * accent paint), `"none"`, or a literal CSS color. @default "color"
+     */
+    fill?: "color" | "accent" | "none" | (string & {});
+    /** Stroke paint, same tokens as `fill`. @default "none" */
+    stroke?: "color" | "accent" | "none" | (string & {});
+    /** Stroke width in definition units — scales with the glyph. */
+    strokeWidth?: number;
+    /** Part opacity, multiplied into the node's opacity. */
+    opacity?: number;
+    strokeLinecap?: "butt" | "round" | "square";
+    strokeLinejoin?: "miter" | "round" | "bevel";
+}
+/** A reusable multi-part pictogram definition. */
+export interface GlyphDef {
+    /** Definition-space box `[width, height]` the parts are drawn in. @default [40, 40] */
+    viewBox?: [number, number];
+    /**
+     * Which point of the viewBox lands on the node's `(x, y)`, as fractions.
+     * `[0.5, 0.5]` centers the glyph (the default); `[0.5, 1]` anchors its feet
+     * — the "standing on a baseline/terrain" pictogram convention.
+     */
+    anchor?: [number, number];
+    parts: GlyphPart[];
+}
+export declare const DEFAULT_GLYPH_VIEWBOX: [number, number];
+export declare const DEFAULT_GLYPH_ANCHOR: [number, number];
+/** Resolved placement of a glyph node: scale plus the top-left corner offset
+ *  from the node's (x, y), honoring the definition's anchor. */
+export interface GlyphPlacement {
+    width: number;
+    height: number;
+    scale: number;
+    /** Add to the node's x to get the drawn top-left corner. */
+    offsetX: number;
+    /** Add to the node's y to get the drawn top-left corner. */
+    offsetY: number;
+}
+/** Size is the rendered **height** in px; width follows the viewBox aspect.
+ *  (Pictogram sizing is a height, unlike the d3-symbol area convention.) */
+export declare function glyphPlacement(def: GlyphDef, size: number): GlyphPlacement;
+/** Radius from the node's (x, y) that bounds the drawn glyph — used for hit
+ *  testing and keyboard-navigation focus geometry. */
+export declare function glyphExtent(def: GlyphDef, size: number): number;
+/**
+ * Resolve a part's paint token against the node's paints. Returns `undefined`
+ * for `"none"`/absent so callers can skip the fill/stroke entirely.
+ */
+export declare function resolveGlyphPaint(token: string | undefined, color: string | undefined, accent: string | undefined, fallback?: string): string | undefined;
+export declare function getGlyphPath2D(d: string): Path2D | null;
+/** The shared fraction geometry for partial glyph fills: the clip rect in
+ *  definition space covering `[fractionStart, fraction]` of the glyph. */
+export declare function glyphFractionClipRect(def: GlyphDef, fraction: number, fractionStart?: number, direction?: "horizontal" | "vertical"): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+/** Hit/focus geometry of a glyph node: the drawn bounds' center offset from
+ *  the node's (x, y) plus its half-extents — shared by the four hit testers
+ *  and the keyboard-nav extractors so pointer and focus agree exactly. */
+export declare function glyphHitGeometry(def: GlyphDef, size: number): {
+    centerDx: number;
+    centerDy: number;
+    halfWidth: number;
+    halfHeight: number;
+    radius: number;
+};
+/**
+ * Paint a glyph's parts onto a canvas context. The caller has already
+ * translated/scaled into definition space (via {@link glyphPlacement}) and
+ * set global alpha; this draws parts with the node's paints. `paintOverride`
+ * paints every part in one flat color — the ghost-silhouette pass under a
+ * partial fill. `resolvePaint` maps a computed paint through the renderer's
+ * CSS-var resolution before it hits the canvas.
+ */
+export declare function drawGlyphParts(ctx: CanvasRenderingContext2D, def: GlyphDef, color: string | undefined, accent: string | undefined, paintOverride?: string, resolvePaint?: (paint: string) => string): void;

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

@@ -0,0 +1,170 @@
+import type { PointSceneNode, RectSceneNode, SceneDatum } from "./types";
+import type { GeoAreaSceneNode } from "./geoTypes";
+import type { NetworkCircleNode, NetworkRectNode } from "./networkTypes";
+/** Default hit/keyboard-focus radius (px) — larger than a typical glyph so the
+ *  target is easy to hit by pointer and to land on by keyboard (Fitts's law). */
+export declare const DEFAULT_HIT_RADIUS = 8;
+export interface HitTargetPointProps {
+    /** Plot-relative x of the mark's center. */
+    x: number;
+    /** Plot-relative y of the mark's center. */
+    y: number;
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Stable identity. Set as the node's `pointId` (annotation anchor + nav-tree
+     *  leaf match) *and* its transition key, so the mark keeps identity across
+     *  re-layouts. Strongly recommended for interactive/animated custom charts. */
+    id?: string | number;
+    /** Hit + keyboard-focus radius in px. @default {@link DEFAULT_HIT_RADIUS} */
+    r?: number;
+}
+/**
+ * A transparent, hit-testable **point** node for a custom XY or ordinal layout
+ * whose visible marks live in `overlays`. Inherits keyboard navigation, the
+ * focus ring, annotation anchoring (by `id` → `pointId`), tooltip/`onObservation`
+ * emission, and transition identity. See the module overview for the full
+ * contract.
+ *
+ * @example
+ * ```ts
+ * nodes: ctx.data.map((row) => {
+ *   const { x, y } = polarToXY(angle(row.day), radius(row.value))
+ *   return hitTargetPoint({ x, y, datum: row, id: `day-${row.day}` })
+ * })
+ * ```
+ */
+export declare function hitTargetPoint(props: HitTargetPointProps): PointSceneNode;
+/**
+ * A transparent, hit-testable point node for a custom **geo** layout whose
+ * visible marks (sprites, icons, forts) live in `overlays`. Project a lon/lat
+ * with `ctx.scales.projectedPoint(lon, lat)` first, then pass the resulting
+ * `x` / `y`. Functionally identical to {@link hitTargetPoint} — geo scenes use
+ * the same `PointSceneNode` — but named for discoverability: it makes
+ * overlay-drawn geographic marks keyboard-navigable, focus-ringed, and
+ * annotation-anchorable, exactly as {@link networkHitTarget} does for networks.
+ *
+ * @example
+ * ```ts
+ * // inside a GeoCustomChart layout
+ * nodes: pois.map((p) => {
+ *   const [x, y] = ctx.scales.projectedPoint(p.lon, p.lat)!
+ *   return geoHitTarget({ x, y, datum: p, id: p.id })
+ * })
+ * ```
+ */
+export declare function geoHitTarget(props: HitTargetPointProps): PointSceneNode;
+export interface GeoAreaHitTargetProps {
+    /** SVG path string in plot-relative screen coordinates. */
+    pathData: string;
+    /** Screen-space centroid for tooltip and focus positioning. */
+    centroid: [number, number];
+    /** Screen-space bounds as [[x0, y0], [x1, y1]]. */
+    bounds: [[number, number], [number, number]];
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Optional series/category key for grouped selection + legend interaction. */
+    group?: string;
+    /** Screen-space area in px^2. Defaults to the bounding-box area. */
+    screenArea?: number;
+}
+/**
+ * A transparent, hit-testable **area** node for a custom geo layout whose
+ * visible polygons live in `overlays`. Use this when the semantic mark is not
+ * point-like: isometric tiles, schematic regions, hex/cell maps, contour bands,
+ * or any hand-built path that should retain GeoFrame hover, keyboard focus,
+ * tooltips, accessible rows, and shape-aware canvas hit testing.
+ *
+ * @example
+ * ```ts
+ * return geoAreaHitTarget({
+ *   pathData: diamondPath(x, y, tileWidth, tileHeight),
+ *   centroid: [x, y],
+ *   bounds: [[x - tileWidth / 2, y - tileHeight / 2], [x + tileWidth / 2, y + tileHeight / 2]],
+ *   screenArea: (tileWidth * tileHeight) / 2,
+ *   datum: tile,
+ *   group: tile.kind,
+ * })
+ * ```
+ */
+export declare function geoAreaHitTarget(props: GeoAreaHitTargetProps): GeoAreaSceneNode;
+export interface HitTargetRectProps {
+    /** Plot-relative x of the rect's top-left corner. */
+    x: number;
+    /** Plot-relative y of the rect's top-left corner. */
+    y: number;
+    /** Rect width in px. */
+    width: number;
+    /** Rect height in px. */
+    height: number;
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Stable identity — used as the transition key, and as `group` for shared
+     *  selection. (Rect nodes anchor annotations by their center via the
+     *  point-anchor harvest only on network; for XY/ordinal pair a rect hit area
+     *  with {@link hitTargetPoint} if you need annotation anchoring.) */
+    id?: string | number;
+    /** Optional series/category key for grouped selection + legend interaction. */
+    group?: string;
+}
+/**
+ * A transparent, hit-testable **rect** node for a custom XY or ordinal layout —
+ * the rectangular sibling of {@link hitTargetPoint}, for marks that read as a
+ * box (a bar, an interval lane segment, a labelled card). Same free interaction:
+ * keyboard nav, focus ring, tooltip/`onObservation`, transition identity.
+ */
+export declare function hitTargetRect(props: HitTargetRectProps): RectSceneNode;
+export interface NetworkHitTargetCircleProps {
+    /** Plot-relative x of the mark's center. */
+    x: number;
+    /** Plot-relative y of the mark's center. */
+    y: number;
+    /** The raw user datum (the object you passed in `nodes`, typically `node.data`). */
+    datum: SceneDatum;
+    /** Stable identity — set as the node `id`, which is how a `pointId`-anchored
+     *  annotation resolves to this mark and how shared selection keys it. */
+    id?: string | number;
+    /** Hit + keyboard-focus radius in px. @default {@link DEFAULT_HIT_RADIUS} */
+    r?: number;
+    /** Optional accessible label override for the node. */
+    label?: string;
+}
+export interface NetworkHitTargetRectProps {
+    /** Plot-relative x of the rect's top-left corner. */
+    x: number;
+    /** Plot-relative y of the rect's top-left corner. */
+    y: number;
+    /** Rect width in px. */
+    width: number;
+    /** Rect height in px. */
+    height: number;
+    /** The raw user datum (the object you passed in `nodes`, typically `node.data`). */
+    datum: SceneDatum;
+    /** Stable identity — set as the node `id` for annotation anchoring + selection. */
+    id?: string | number;
+    /** Optional accessible label override for the node. */
+    label?: string;
+}
+/**
+ * A transparent, hit-testable node for a custom **network** layout. Pass `width`
+ * + `height` for a rect (a labelled box / card), or omit them for a circle of
+ * radius `r`. Every network scene node is harvested as an annotation anchor, so
+ * `id` resolves a `{ pointId: id }` annotation to this mark. Inherits the same
+ * keyboard nav, focus ring, tooltip/`onObservation`, and shared-selection
+ * threading the built-in network charts get.
+ *
+ * @example
+ * ```ts
+ * sceneNodes: positioned.map((node) =>
+ *   networkHitTarget({
+ *     x: node.x - node.width / 2,
+ *     y: node.y - node.height / 2,
+ *     width: node.width,
+ *     height: node.height,
+ *     datum: node,
+ *     id: node.id,
+ *   })
+ * )
+ * ```
+ */
+export declare function networkHitTarget(props: NetworkHitTargetRectProps): NetworkRectNode;
+export declare function networkHitTarget(props: NetworkHitTargetCircleProps): NetworkCircleNode;

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

@@ -27,11 +27,11 @@ export declare function getHitRadius(nodeRadius: number | undefined, maxDistance
  * Convert a value to a Date if possible. Returns null for non-date values.
  * Treats numbers > 1e9 as millisecond timestamps.
  */
-export declare function toDate(value: any): Date | null;
+export declare function toDate(value: Date | number | string | null | undefined): Date | null;
 /**
  * Detect whether a tick marks a time boundary (new month or year) compared to the previous tick.
  */
-export declare function isTimeLandmark(value: any, prevValue: any): boolean;
+export declare function isTimeLandmark(value: Date | number | string | null | undefined, prevValue: Date | number | string | null | undefined): boolean;
 /**
  * Normalize an angle to the [0, 2π) range.
  */

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

@@ -7,6 +7,8 @@
  * property flattening that are handled at the call site.
  */
 import type { HoverData } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export type RawHoverDatum = Datum | Datum[] | null;
 /**
  * Minimal shape a Stream Frame's internal hover handler needs from a pointer
  * event. React.MouseEvent satisfies this structurally, as does the plain
@@ -18,8 +20,11 @@ import type { HoverData } from "../realtime/types";
 export interface HoverPointerCoords {
     clientX: number;
     clientY: number;
+    pointerType?: string;
 }
-export declare function normalizeHoverDatum(rawDatum: any): any;
+export declare const TOUCH_HIT_RADIUS = 24;
+export declare function getPointerHitRadius(baseRadius: number, pointerType?: string): number;
+export declare function normalizeHoverDatum(rawDatum: RawHoverDatum): Datum | null;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * The raw datum is preserved as `hover.data` for tooltip / callback
@@ -27,4 +32,4 @@ export declare function normalizeHoverDatum(rawDatum: any): any;
  * relevant to a specific frame family — `category`, `stats`,
  * `nodeOrEdge`, `xValue`, etc. — is layered in via `extra`.
  */
-export declare function buildHoverData(rawDatum: any, x: number, y: number, extra?: Partial<HoverData>): HoverData;
+export declare function buildHoverData(rawDatum: RawHoverDatum, x: number, y: number, extra?: Partial<HoverData>): HoverData;

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

@@ -20,11 +20,14 @@ export interface NavPoint {
     y: number;
     datum: Datum | null;
     /** Shape hint for focus ring rendering */
-    shape?: "circle" | "rect" | "wedge";
+    shape?: "circle" | "rect" | "wedge" | "geoarea";
     /** Width of rect-shaped elements (bars, sankey nodes) */
     w?: number;
     /** Height of rect-shaped elements */
     h?: number;
+    /** SVG path (plot-relative) for a geoarea focus ring — the shape is
+     *  outlined instead of drawing a circle at the centroid. */
+    pathData?: string;
     /** Group identifier for graph navigation (series name, category, node id) */
     group?: string;
     /** Index in NavGraph.flat — set by buildNavGraph for O(1) lookup */

package/dist/components/stream/layouts/forceLayoutPlugin.d.ts

@@ -1,2 +1,10 @@
-import type { NetworkLayoutPlugin } from "../networkTypes";
+import type { NetworkLayoutPlugin, RealtimeNode } from "../networkTypes";
+import type { Datum } from "../../charts/shared/datumTypes";
 export declare const forceLayoutPlugin: NetworkLayoutPlugin;
+/**
+ * Build a function that returns a node radius. If `nodeSize` is a number,
+ * use it directly. If it is a string accessor, look up `node.data[nodeSize]`
+ * and scale the result to `nodeSizeRange`. If it is a function, call it.
+ * Falls back to a default radius of 8.
+ */
+export declare function resolveNodeSizeFn(nodeSize: number | string | ((d: Datum) => number) | undefined, nodeSizeRange: [number, number] | undefined, allNodes: RealtimeNode[]): (node: RealtimeNode) => number;

package/dist/components/stream/layouts/forceLayoutWorkerClient.d.ts

@@ -0,0 +1,58 @@
+import type { GraphEdge, GraphNode, Point } from "../../recipes/networkAnalysis";
+import type { ForceLayoutOptions } from "../../recipes/forceLayout";
+import type { NetworkPipelineConfig, RealtimeEdge, RealtimeNode } from "../networkTypes";
+export type ForceLayoutExecution = "auto" | "worker" | "sync";
+export interface NormalizedForceWorkerRequest {
+    kind: "normalized";
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    options: Omit<ForceLayoutOptions, "nodeRadius">;
+    nodeRadii?: Record<string, number>;
+}
+export interface FrameForceWorkerRequest {
+    kind: "frame";
+    nodes: RealtimeNode[];
+    edges: RealtimeEdge[];
+    config: {
+        chartType: "force";
+        iterations?: number;
+        forceStrength?: number;
+        seed?: number;
+    };
+    size: [number, number];
+}
+export type ForceWorkerRequest = NormalizedForceWorkerRequest | FrameForceWorkerRequest;
+export interface ForceWorkerResponse {
+    positions: Record<string, Point>;
+}
+export declare const DEFAULT_FORCE_WORKER_THRESHOLD = 40000;
+export declare function shouldUseForceWorker(execution: ForceLayoutExecution, nodeCount: number, edgeCount: number, iterations: number, threshold?: number): boolean;
+export declare function canUseForceWorker(): boolean;
+export declare function createForceLayoutWorker(): Worker;
+export declare function createFrameForceWorkerRequest(nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], previousPositions?: Map<string, {
+    x: number;
+    y: number;
+}> | null): FrameForceWorkerRequest;
+/**
+ * Long-lived force-layout worker session. Mirrors PhysicsWorkerSession:
+ * one Worker is reused across layouts so module parse + startup cost is
+ * paid once per page, not once per graph re-layout.
+ */
+export declare class ForceLayoutWorkerSession {
+    private nextRequestId;
+    private pending;
+    private worker;
+    private dead;
+    constructor(worker?: Worker);
+    get isDead(): boolean;
+    request(request: ForceWorkerRequest, signal?: AbortSignal): Promise<ForceWorkerResponse>;
+    terminate(): void;
+    private rejectAll;
+}
+/** Test helper: drop the shared session so the next call creates a fresh Worker. */
+export declare function _resetSharedForceLayoutSessionForTest(): void;
+/**
+ * Run a force layout on a reused worker session.
+ * Prefer this over constructing a new Worker per layout.
+ */
+export declare function runForceLayoutWorker(request: ForceWorkerRequest, signal?: AbortSignal): Promise<ForceWorkerResponse>;

package/dist/components/stream/layouts/hierarchyUtils.d.ts

@@ -20,7 +20,7 @@ export declare function parseColor(color: string): [number, number, number];
  * Uses perceived luminance (ITU-R BT.601).
  */
 export declare function contrastTextColor(bgColor: string): string;
-export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => any[]) | undefined): ((d: Datum) => any[]) | undefined;
-export declare function resolveNodeId(d: any, config: NetworkPipelineConfig, index: number): string;
+export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => Datum[]) | undefined): ((d: Datum) => Datum[]) | undefined;
+export declare function resolveNodeId(d: Datum, config: NetworkPipelineConfig, index: number): string;
 export declare function resolveLabelFn(nodeLabel: string | ((d: Datum) => string) | undefined): ((d: Datum) => string) | null;
 export declare function resolveDefaultNodeSize(nodeSize: number | string | ((d: Datum) => number) | undefined): number;

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

@@ -0,0 +1,10 @@
+import type { BezierCache, RealtimeEdge, RealtimeNode } from "./networkTypes";
+/** Default cubic control-point curvature (fraction of span). */
+export declare const NETWORK_EDGE_CURVATURE = 0.5;
+export declare function buildStandardBezier(edge: RealtimeEdge, sourceNode: RealtimeNode, targetNode: RealtimeNode, curvature?: number): BezierCache;
+export declare function buildCircularBezier(edge: RealtimeEdge, curvature?: number): BezierCache;
+/**
+ * Resolve source/target RealtimeNodes and attach the edge's bezier cache.
+ * Returns false if endpoints cannot be resolved.
+ */
+export declare function updateEdgeBezier(edge: RealtimeEdge, nodes: Map<string, RealtimeNode>, curvature?: number): boolean;