semiotic 3.7.4 → 3.8.0

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/customLayoutSelection.d.ts

@@ -0,0 +1,52 @@
+import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * The shared-selection state projected to a custom layout — both into the layout
+ * context (`ctx.selection`) and, via {@link useCustomLayoutSelection}, into the
+ * layout's React `overlays` subtree.
+ *
+ * `isActive` is `false` when no selection clause is present (treat every mark as
+ * selected). `predicate(datum)` returns `true` when the raw datum matches the
+ * active selection.
+ */
+export interface CustomLayoutSelection {
+    isActive: boolean;
+    predicate: (datum: Datum) => boolean;
+}
+/**
+ * Provided by the Stream Frames around a custom layout's `overlays`. The value
+ * is the chart's resolved selection; it updates on hover/selection change
+ * **without** the frame re-running the layout — so an overlay that subscribes
+ * via {@link useCustomLayoutSelection} restyles itself while sceneNodes, the
+ * canvas paint, and the quadtree stay untouched.
+ */
+export declare function CustomLayoutSelectionProvider({ value, children, }: {
+    value: CustomLayoutSelection | null;
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Read the chart's resolved selection from inside a custom layout's `overlays`.
+ *
+ * Subscribing components re-render on selection/hover change **without a
+ * relayout** — the frame swaps only the context value, never rebuilding the
+ * scene. This is the read side of the styling channel; pair it with the
+ * `restyle` callback on the layout result to dim/highlight **canvas** marks
+ * without re-positioning.
+ *
+ * Returns an inactive selection (`isActive: false`, predicate always `true`)
+ * when called outside a custom chart, so overlays render fully-lit by default.
+ *
+ * @example
+ * ```tsx
+ * function ClusterLabel({ datum, x, y }) {
+ *   const { isActive, predicate } = useCustomLayoutSelection()
+ *   const dim = isActive && !predicate(datum)
+ *   return <text x={x} y={y} opacity={dim ? 0.15 : 1}>{datum.label}</text>
+ * }
+ * ```
+ */
+export declare function useCustomLayoutSelection(): CustomLayoutSelection;
+/** Wrap a custom layout's overlay node in the selection provider (no-op for a
+ *  null node, so an empty overlay layer stays empty rather than becoming a
+ *  provider element). Used by the Stream Frames. */
+export declare function wrapWithCustomLayoutSelection(node: React.ReactNode, selection: CustomLayoutSelection | null): React.ReactNode;

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) => any[]) | undefined): (d: Datum) => any[];
+export declare function resolveGeoStyle(styleProp: Style | ((d: Datum) => Style) | undefined, datum: any, 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: any, _allFlows: any[], strokeWidth: number): [number, number][];

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

@@ -1,12 +1,16 @@
 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 } 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";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -41,6 +45,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,10 +60,13 @@ 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>;
@@ -67,7 +76,12 @@ export interface GeoScales {
 export interface GeoPipelineConfig {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
-    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    /**
+     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
+     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
+     * almost always a pixel mistake and collapses the projection off-canvas.
+     * @default 0
+     */
     fitPadding?: number;
     xAccessor?: string | ((d: Datum) => number);
     yAccessor?: string | ((d: Datum) => number);
@@ -80,7 +94,7 @@ export interface GeoPipelineConfig {
         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. */
@@ -99,15 +113,36 @@ 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 */
+    /**
+     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
+     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
+     * almost always a pixel mistake and collapses the projection off-canvas.
+     * @default 0
+     */
     fitPadding?: number;
     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[]);
@@ -160,7 +195,7 @@ export interface StreamGeoFrameProps<T = Datum> {
         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,6 +208,12 @@ export interface StreamGeoFrameProps<T = Datum> {
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
+    /**
+     * 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?: (d: HoverData | null) => void;
     customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Datum[];
@@ -244,4 +285,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;