semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,33 @@
+/** Structural scene node accepted from any frame family. */
+export type AccessibleSceneNode = {
+    type?: unknown;
+    datum?: unknown;
+    accessibleDatum?: unknown;
+    accessibility?: unknown;
+    group?: unknown;
+    value?: unknown;
+    category?: unknown;
+    label?: unknown;
+    name?: unknown;
+    properties?: unknown;
+    tableFields?: unknown;
+    x?: unknown;
+    y?: unknown;
+    w?: unknown;
+    h?: unknown;
+    path?: unknown;
+    topPath?: unknown;
+    openY?: unknown;
+    closeY?: unknown;
+    highY?: unknown;
+    lowY?: unknown;
+};
+export interface DataRow {
+    label: string;
+    values: Record<string, string | number>;
+}
+/**
+ * Extract user-facing table rows from scene nodes. Geometry is ignored; rich
+ * accessibleDatum/tableFields metadata takes precedence over the render datum.
+ */
+export declare function extractAllRows(scene: AccessibleSceneNode[]): DataRow[];

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

@@ -1,18 +1,31 @@
 /**
- * Compare two accessor specs for equivalence.
- * - Same reference: always equivalent (`===`)
- * - String accessors: exact string match
- * - Function accessors: `.toString()` comparison (catches inline arrow functions
- *   like `d => d.value` that are recreated on every render but have identical source)
- * - Mismatched types or undefined vs defined: not equivalent
+ * Compare two accessor specs for equivalence, using **identity** semantics.
+ * - String accessors: compared by value (`"value" === "value"`).
+ * - Function accessors: compared by reference. Two distinct function objects are
+ *   NOT equivalent, even when their source text matches.
+ * - Mismatched types or `undefined` vs defined: not equivalent.
  *
- * **Known limitation**: `.toString()` compares source text, not closure bindings.
- * Two functions with identical source but different captured variables will appear
- * equivalent. For closures that depend on changing values, use `useCallback` with
- * the variable in the dependency array so the reference changes when behavior changes.
+ * **Why identity, not source text.** A previous implementation compared
+ * `a.toString() === b.toString()` to treat re-created inline arrows
+ * (`d => d.value`) as equivalent across renders. That was a correctness bug:
+ * `.toString()` compares source text, not captured variables, so two closures
+ * with identical source but different bindings — `makeAccessor(1)` vs
+ * `makeAccessor(10)` — compared equal, and the store retained a stale
+ * domain/scene against a genuinely different accessor. Identity comparison also
+ * matches how the frames already decide a config changed
+ * (`useStableShallow` compares function props by identity), so the store no
+ * longer second-guesses a change the frame already detected.
+ *
+ * **Consumer contract.** Passing a *new* function accessor (a fresh inline
+ * arrow every render) now triggers a rebuild, because the library can no longer
+ * prove the new closure is semantically identical. Use a string accessor
+ * (always referentially stable) or memoize the function with `useCallback`. For
+ * the rare case where a stable function's captured semantics change *without*
+ * its identity changing, bump the pipeline config's `accessorRevision` to force
+ * re-derivation.
  */
-export declare function accessorsEquivalent(a: string | ((...args: any[]) => any) | undefined, b: string | ((...args: any[]) => any) | undefined): boolean;
+export declare function accessorsEquivalent<TDatum, TResult>(a: string | ((datum: TDatum, index?: number) => TResult) | undefined, b: string | ((datum: TDatum, index?: number) => TResult) | undefined): boolean;
 export type CoercibleNumber = number | Date | string;
 export declare function resolveAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => CoercibleNumber) | undefined, fallback: string): (d: T) => number;
-export declare function resolveRawAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => unknown) | undefined, fallback: string): (d: T) => unknown;
+export declare function resolveRawAccessor<T extends Record<string, unknown>, TResult>(accessor: string | ((d: T) => TResult) | undefined, fallback: string): (d: T) => TResult;
 export declare function resolveStringAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => string) | undefined, fallback?: string): ((d: T) => string) | undefined;

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

@@ -9,14 +9,14 @@
  * `StreamOrdinalFrame` (and any future frame with the same need)
  * can share the same plumbing rather than re-implementing it.
  */
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 export interface ResolvedAnnotationAccessor {
     /** String key the annotation context will read on each datum. */
     key: string | undefined;
     /** Accessor function when the user supplied one (synthetic key
      *  gets baked from this); `null` when the user supplied a string
      *  or nothing. */
-    fn: ((d: Datum) => any) | null;
+    fn: ((d: Datum) => DatumValue) | null;
 }
 /**
  * Resolve an accessor pair to the (key, fn) shape the annotation

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

@@ -0,0 +1,25 @@
+import * as React from "react";
+export type BrushKeyboardAction = {
+    type: "nudge";
+    direction: "left" | "right" | "up" | "down";
+    resize: boolean;
+} | {
+    type: "clear";
+};
+export interface BrushAccessibilityOptions {
+    label?: string;
+    description?: string;
+    onAction?: (action: BrushKeyboardAction) => void;
+}
+/** Shared ARIA and keyboard vocabulary for frame-owned D3 brushes. */
+export declare function useBrushAccessibility({ label, description, onAction, }?: BrushAccessibilityOptions): {
+    description: string;
+    descriptionId: string;
+    svgProps: {
+        role: string;
+        tabIndex: number;
+        "aria-label": string;
+        "aria-describedby": string;
+        onKeyDown: (event: React.KeyboardEvent<SVGSVGElement>) => void;
+    };
+};

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

@@ -0,0 +1,24 @@
+export interface PaintCanvasBackgroundOptions {
+    /** Explicit chart background color (or CSS var). */
+    background?: string;
+    /**
+     * When true, skip the fill so an SVG backgroundGraphics layer shows through.
+     * Equivalent to frames' `backgroundGraphics` prop being set.
+     */
+    hasBackgroundGraphics?: boolean;
+    /**
+     * Theme fallback when `background` is unset (e.g. `--semiotic-bg`).
+     * Empty / transparent values are ignored.
+     */
+    themeBackground?: string;
+    /** Fill origin (plot-local or canvas-local depending on frame transform). */
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+}
+/**
+ * Paint an opaque chart background when appropriate.
+ * Returns true if a fill was applied.
+ */
+export declare function paintCanvasBackground(ctx: CanvasRenderingContext2D, options: PaintCanvasBackgroundOptions): boolean;

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

@@ -21,6 +21,9 @@ export interface CanvasMargin {
  */
 export declare function prepareCanvas(canvas: HTMLCanvasElement, size: [number, number], margin: CanvasMargin, dpr: number): CanvasRenderingContext2D | null;
 /**
- * Get the current devicePixelRatio, defaulting to 1 in non-browser environments.
+ * Get the effective canvas devicePixelRatio, defaulting to 1 in non-browser
+ * environments. Mobile/coarse-pointer screens are capped at 2x to avoid
+ * allocating very large backing stores on high-density phones; desktop stays
+ * crisper but still caps pathological DPR values at 3x.
  */
 export declare function getDevicePixelRatio(): number;

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

@@ -0,0 +1,33 @@
+/**
+ * Structured failure information emitted when a custom layout throws.
+ *
+ * Custom layouts run inside imperative stores so an exception cannot reach a
+ * React error boundary. Keep this deliberately small and serializable enough
+ * for an app's error UI, telemetry, or an imperative frame-handle readback.
+ */
+export type CustomLayoutFamily = "xy" | "ordinal" | "geo" | "network";
+export type CustomLayoutFailureRecovery = "preserved-last-good-scene" | "empty-scene";
+export interface CustomLayoutFailureDiagnostic {
+    /** Stable machine-readable failure code. */
+    code: "CUSTOM_LAYOUT_ERROR";
+    severity: "error";
+    phase: "layout";
+    /** Frame family whose layout callback threw. */
+    component: CustomLayoutFamily;
+    /** The callback surface that threw. */
+    source: "customLayout" | "customNetworkLayout";
+    /** Human-readable summary suitable for a non-blocking error UI. */
+    message: string;
+    /** A safe, serializable summary of the thrown value. */
+    error: {
+        name: string;
+        message: string;
+    };
+    /** Whether a prior custom-layout scene remained visible. */
+    recovery: CustomLayoutFailureRecovery;
+    /** Convenience mirror of `recovery` for simple caller branching. */
+    preservedLastGoodScene: boolean;
+    /** Store revision at which the failed layout attempt occurred. */
+    affectedRevision: number;
+}
+export declare function createCustomLayoutFailureDiagnostic(component: CustomLayoutFamily, error: unknown, preservedLastGoodScene: boolean, affectedRevision: number): CustomLayoutFailureDiagnostic;

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

@@ -7,11 +7,15 @@ import { schemeCategory10 } from "../charts/shared/colorPalettes";
  * call this helper.
  *
  * Precedence:
- *   1. Explicit `colorScheme` array — used as-is.
- *   2. Named scheme string (e.g. "tableau10") — looked up in
+ *   1. Object map `{ key: color }` — its values become the palette (so
+ *      `theme.categorical` reflects the map). Pair with `buildResolveColor`,
+ *      which returns the *exact* mapped color per key; this palette only
+ *      feeds unmapped keys and `theme.categorical`.
+ *   2. Explicit `colorScheme` array — used as-is.
+ *   3. Named scheme string (e.g. "tableau10") — looked up in
  *      `COLOR_SCHEMES`. Unknown names fall through.
- *   3. Theme categorical (when non-empty).
- *   4. The provided fallback palette.
+ *   4. Theme categorical (when non-empty).
+ *   5. The provided fallback palette.
  *
  * @param colorScheme   `colorScheme` from the chart's pipeline config
  * @param themeCategorical  `themeCategorical` from theme resolution
@@ -19,11 +23,17 @@ import { schemeCategory10 } from "../charts/shared/colorPalettes";
  *                      Network passes `schemeCategory10`; ordinal passes
  *                      `STREAMING_PALETTE`. Caller's choice.
  */
-export declare function resolveCustomLayoutPalette(colorScheme: string | string[] | undefined, themeCategorical: string[] | undefined, fallback: readonly string[]): readonly string[];
+export declare function resolveCustomLayoutPalette(colorScheme: string | string[] | Record<string, string> | undefined, themeCategorical: string[] | undefined, fallback: readonly string[]): readonly string[];
 /**
- * Build a stable hash → palette index resolver. Used by the network and
- * ordinal customLayout contexts so the same key always returns the same
- * color for the lifetime of the closure.
+ * Build a stable key → color resolver. Used by the network and ordinal
+ * customLayout contexts so the same key always returns the same color for
+ * the lifetime of the closure.
+ *
+ * When `colorScheme` is an object map `{ key: color }`, a key present in the
+ * map resolves to its *exact* color (the documented "exact per-category
+ * colors" contract); keys absent from the map hash into `palette` as usual.
+ * Non-object `colorScheme` values are ignored here — pass the already-resolved
+ * `palette` from `resolveCustomLayoutPalette` for those.
  */
-export declare function buildResolveColor(palette: readonly string[]): (key: string) => string;
+export declare function buildResolveColor(palette: readonly string[], colorScheme?: string | string[] | Record<string, string>): (key: string) => string;
 export { schemeCategory10, STREAMING_PALETTE };

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

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+import type { FrameGraphicsContext, FrameGraphicsProp } from "./types";
+/** Resolve a static or scale-aware SVG graphics layer for a frame family. */
+export declare function resolveFrameGraphics<S>(graphics: FrameGraphicsProp<S> | undefined, size: number[], margin: FrameGraphicsContext<S>["margin"], scales: S | null): ReactNode;

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

@@ -0,0 +1,45 @@
+import type { Dispatch, KeyboardEvent, SetStateAction } from "react";
+import type { HoverData } from "../realtime/types";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { PipelineStore } from "./PipelineStore";
+import type { OrdinalPipelineStore } from "./OrdinalPipelineStore";
+import type { GeoPipelineStore } from "./GeoPipelineStore";
+import type { SceneNode } from "./types";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { GeoSceneNode } from "./geoTypes";
+import { type NavPoint } from "./keyboardNav";
+type RefValue<Value> = {
+    current: Value;
+};
+type SetHoverPoint = Dispatch<SetStateAction<HoverData | null>>;
+type FocusedNavPoint = Pick<NavPoint, "shape" | "w" | "h" | "pathData">;
+interface KeyboardInteractionParams<Store, Node = unknown> {
+    storeRef: RefValue<Store | null>;
+    hoverRef: RefValue<HoverData | null>;
+    hoveredNodeRef?: RefValue<Node | null>;
+    setHoverPoint: SetHoverPoint;
+    customHoverBehavior: SemanticHoverBehavior<HoverData>;
+    customClickBehavior: SemanticClickBehavior<HoverData>;
+    scheduleRender: () => void;
+}
+export declare function useXYKeyboardNavigation(params: KeyboardInteractionParams<PipelineStore, SceneNode>): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+interface OrdinalKeyboardParams extends KeyboardInteractionParams<OrdinalPipelineStore, OrdinalSceneNode> {
+    chartType: string;
+    oAccessor: unknown;
+    rAccessor: unknown;
+}
+export declare function useOrdinalKeyboardNavigation({ chartType, oAccessor, rAccessor, ...params }: OrdinalKeyboardParams): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+export declare function useGeoKeyboardNavigation({ storeRef, hoverRef, hoveredNodeRef, setHoverPoint, customHoverBehavior, customClickBehavior, scheduleRender }: KeyboardInteractionParams<GeoPipelineStore, GeoSceneNode>): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+export {};

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

@@ -0,0 +1,24 @@
+export interface FrameThemeColors {
+    axisStroke: string;
+    tickText: string;
+    crosshair: string;
+    hoverFill: string;
+    hoverStroke: string;
+    pointRing: string;
+    /** Primary accent — crosshair / highlight fallback when datum has no color. */
+    primary: string;
+    /** Chart background from `--semiotic-bg` / surface tokens (may be empty). */
+    background: string;
+}
+export declare const LIGHT_FRAME_THEME: FrameThemeColors;
+/**
+ * Append a 2-char hex alpha to an existing CSS color.
+ * Expands 3-char hex; converts rgb() to rgba(); passes other forms through.
+ */
+export declare function withAlpha(color: string, alphaHex: string): string;
+export declare function resolveFrameThemeColors(el: HTMLElement | null): FrameThemeColors;
+/** Version-keyed cache for a frame instance's theme colors. */
+export declare function createFrameThemeColorCache(): {
+    resolve(el: HTMLElement | null): FrameThemeColors;
+    invalidate(): void;
+};

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

@@ -0,0 +1,14 @@
+/**
+ * Harvest annotation anchors from a geo scene graph.
+ * Point marks pass through; glyph marks contribute drawn-bounds center + radius
+ * so `{ pointId }` annotations resolve against pictograms too.
+ */
+import type { GeoSceneNode } from "./geoTypes";
+import type { SceneNode } from "./types";
+export type GeoAnnotationAnchor = {
+    pointId?: string;
+    x: number;
+    y: number;
+    r: number;
+};
+export declare function collectGeoAnnotationAnchors(scene: (GeoSceneNode | SceneNode)[] | undefined): GeoAnnotationAnchor[] | undefined;

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

@@ -0,0 +1,17 @@
+/**
+ * Distance-cartogram projection of geo point scene nodes.
+ * Mutates point/line positions in place; returns layout metadata for overlays.
+ */
+import type { DistanceCartogramConfig, GeoSceneNode } from "./geoTypes";
+import type { StreamLayout } from "./types";
+export type GeoCartogramLayout = {
+    cx: number;
+    cy: number;
+    maxCost: number;
+    availableRadius: number;
+};
+/**
+ * Apply a distance cartogram transform to the scene.
+ * Returns layout info when applied, or null when skipped.
+ */
+export declare function applyDistanceCartogram(scene: GeoSceneNode[], transform: DistanceCartogramConfig, layout: StreamLayout, areasLength: number): GeoCartogramLayout | null;

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

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { MarginType } from "../types/marginType";
+import type { GeoScales, GeoSceneNode } from "./geoTypes";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import type { Style, ThemeSemanticColors } from "./types";
+/**
+ * Custom-layout escape hatch for `StreamGeoFrame`.
+ *
+ * The frame resolves and fits the geographic projection before invoking the
+ * layout. The layout may use those geographic scales, replace the built-in
+ * geometry entirely, or combine both approaches while continuing to emit the
+ * GeoFrame scene primitives (`geoarea`, `point`, and `line`).
+ */
+export type GeoCustomLayout<C extends object = Record<string, unknown>> = (ctx: GeoLayoutContext<C>) => GeoLayoutResult;
+export interface GeoLayoutContext<C extends object = Record<string, unknown>> {
+    /** Geographic areas supplied to the frame. */
+    areas: GeoJSON.Feature[];
+    /** Buffered point data supplied through props or the push API. */
+    points: Datum[];
+    /** Line/flow records supplied to the frame. */
+    lines: Datum[];
+    /** Frame-fitted projection helpers. */
+    scales: GeoScales;
+    /** Plot-local geometry. Scene-node coordinates are relative to this plot. */
+    dimensions: {
+        width: number;
+        height: number;
+        margin: MarginType;
+        plot: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** Theme-resolved semantic and categorical colors. */
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    /** Resolve a stable categorical color from the active palette. */
+    resolveColor: (key: string) => string;
+    /** User configuration threaded through `layoutConfig`. */
+    config: C;
+    /** Shared-selection projection, when the chart participates in one. */
+    selection?: CustomLayoutSelection | null;
+}
+export interface GeoLayoutResult {
+    /** Geo scene nodes rendered on canvas and serialized for SSR. */
+    nodes?: GeoSceneNode[];
+    /** SVG graphics composited above the canvas. */
+    overlays?: ReactNode;
+    /**
+     * Selection-only style updates that do not require rebuilding geometry.
+     * Patches are merged onto the node's original emitted style.
+     */
+    restyle?: (node: GeoSceneNode, selection: CustomLayoutSelection | null) => Partial<Style> | void;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Default geo hover tooltip for StreamGeoFrame.
+ * Uses shared `defaultTooltipStyle` for theme CSS-var consistency.
+ */
+import * as React from "react";
+import type { HoverData } from "../realtime/types";
+type GeoTooltipData = HoverData | null;
+declare function DefaultGeoTooltip({ data }: {
+    data: GeoTooltipData;
+}): React.JSX.Element | null;
+export { DefaultGeoTooltip };

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

@@ -0,0 +1,34 @@
+/**
+ * Small StreamGeoFrame helpers: particle conservation defaults, zoom chrome,
+ * projection name resolution, and hit-canvas context acquisition.
+ */
+import type * as React from "react";
+import type { Selection } from "d3-selection";
+import type { ZoomTransform } from "d3-zoom";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { ProjectionName, ProjectionProp } from "./geoTypes";
+export declare const DEFAULT_GEO_MARGIN: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export declare const DEFAULT_GEO_HOVER_RADIUS = 30;
+export declare function shouldConserveGeoParticles(): boolean;
+export declare function defaultGeoParticleMaxPerLine(): number;
+export declare function defaultGeoParticleSpawnRate(): number;
+export declare const zoomButtonStyle: React.CSSProperties;
+export type GeoFeatureLike = Datum & {
+    properties?: Datum;
+    geometry?: unknown;
+    data?: Datum;
+};
+export type HitCanvas = HTMLCanvasElement | OffscreenCanvas;
+export type HitCanvasContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+export type GeoZoomSelection = Selection<HTMLDivElement, unknown, null, undefined>;
+export interface GeoZoomControlBehavior {
+    scaleBy(selection: GeoZoomSelection, factor: number): void;
+    transform(selection: GeoZoomSelection, transform: ZoomTransform | Pick<ZoomTransform, "k">): void;
+}
+export declare function resolveProjectionName(projection: ProjectionProp): ProjectionName | null;
+export declare function ensureHitCanvasContext(canvas: HitCanvas | null): HitCanvasContext | null;

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

@@ -0,0 +1,46 @@
+/**
+ * Pure geo pipeline helpers — projection resolution, accessors, themed defaults,
+ * anti-meridian path splitting, and flow-style arc/offset builders.
+ * Extracted from GeoPipelineStore so the store class stays orchestration-only.
+ */
+import type { GeoProjection } from "d3-geo";
+import type { GeoPipelineConfig, ProjectionProp } from "./geoTypes";
+import type { Style } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
+export declare function resolveProjection(prop: ProjectionProp | undefined): GeoProjection;
+export declare function makeGeoNumericAccessor(acc: string | ((d: Datum) => number) | undefined, fallback: string): (d: Datum) => number;
+export declare function makeLineDataAccessor(acc: string | ((d: Datum) => Datum[]) | undefined): (d: Datum) => Datum[];
+export declare function resolveGeoStyle<TDatum extends object>(styleProp: Style | ((d: TDatum) => Style) | undefined, datum: TDatum, defaults: Style): Style;
+export declare function themedDefaultArea(config: GeoPipelineConfig): Style;
+export declare function themedDefaultPoint(config: GeoPipelineConfig): Style & {
+    r?: number;
+};
+export declare function themedDefaultLine(config: GeoPipelineConfig): Style;
+/**
+ * Detect screen-space jumps in a projected path that indicate the line
+ * has wrapped around the edge of the projection (anti-meridian crossing).
+ * Split the path at those jumps and return an array of continuous segments.
+ *
+ * A jump is detected when consecutive screen-space points are further apart
+ * than `threshold` pixels (default: half the viewport width).
+ */
+export declare function splitAntiMeridianPath(screenPath: [number, number][], viewportWidth: number): [number, number][][];
+/**
+ * Build a quadratic arc path between two screen-space points.
+ * The arc bulges perpendicular to the straight line (right of the
+ * direction of travel in screen coords), with height proportional to distance.
+ */
+export declare function buildArcPath(start: [number, number], end: [number, number], segments?: number): [number, number][];
+/**
+ * Build an offset version of a densified geo screen path.
+ * Shifts each point along its local normal so the great-circle curvature
+ * is preserved while visually separating overlapping flows.
+ */
+export declare function buildOffsetGeoPath(screenPath: [number, number][], strokeWidth: number): [number, number][];
+/**
+ * Build an offset path — shift a straight line perpendicular to its direction.
+ * All flows are offset to their left by half their stroke width plus padding.
+ * Bidirectional pairs (A->B and B->A) naturally separate because their
+ * left-hand normals point to opposite sides.
+ */
+export declare function buildOffsetPath(start: [number, number], end: [number, number], _flow: Datum, _allFlows: Datum[], strokeWidth: number): [number, number][];

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

@@ -0,0 +1,34 @@
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/** Whether a config patch must re-derive its retained Geo data resources. */
+export type GeoRetainedDataEffect = "preserve" | "rebuild";
+export interface GeoConfigPatchDependency {
+    readonly retainedData: GeoRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Geo's key-level config-patch dependency table. `windowSize` is a retained
+ * resource rebuild: its `data` revision is added only when an active stream
+ * actually resizes, so a bounded config-only patch is never reported as an
+ * ingest.
+ */
+export declare const GEO_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, GeoConfigPatchDependency>>;
+export interface GeoConfigPatchClassification {
+    readonly retainedData: GeoRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyGeoConfigPatch(keys: readonly string[]): GeoConfigPatchClassification;
+type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
+/** Result bookkeeping and explicit config-patch dependency policy for Geo. */
+export declare class GeoPipelineUpdateResults {
+    private tracker;
+    get last(): UpdateResult;
+    subscribe(listener: () => void): () => void;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[], options?: {
+        retainedDataChanged?: boolean;
+    }): UpdateResult;
+}
+export {};

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

@@ -0,0 +1,16 @@
+import type { GeoPath, GeoPermissibleObjects, GeoProjection } from "d3-geo";
+import type { GeoPipelineConfig, GeoSceneNode } from "./geoTypes";
+import type { StreamLayout } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
+interface GeoSceneBuildInput {
+    config: GeoPipelineConfig;
+    projection: GeoProjection;
+    path: GeoPath<void, GeoPermissibleObjects>;
+    areas: GeoJSON.Feature[];
+    points: Datum[];
+    lines: Datum[];
+    layout: StreamLayout;
+}
+/** Builds the built-in geo scene independently of store-owned custom layout state. */
+export declare function buildBuiltInGeoScene({ config, projection, path, areas, points, lines, layout }: GeoSceneBuildInput): GeoSceneNode[];
+export {};