semiotic 3.8.5 → 3.8.7

package/dist/components/charts/physics/{PhysicalFlowChart.d.ts → PacketFlowChart.d.ts}

@@ -4,8 +4,8 @@ import type { StyleRule } from "../shared/styleRules";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type PhysicalFlowCoordinateMode, type PhysicalFlowPathConstraint, type PhysicalFlowRawPath } from "./physicsChartUtils";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
-export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PacketFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     nodes?: TNode[];
     links?: TLink[];
     edges?: TLink[];
@@ -37,15 +37,22 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
     styleRules?: StyleRule[];
     seed?: number;
     tooltip?: TooltipProp;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     paused?: boolean;
     frameProps?: PhysicsHocFrameProps<"config">;
 }
+/** @deprecated Renamed to {@link PacketFlowChartProps} in 3.9.0. */
+export type PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> = PacketFlowChartProps<TNode, TLink>;
 /**
  * Physics-backed flow chart that sends packet bodies along authored routes while retaining a static throughput layer.
  *
  * @example
  * ```tsx
- * <PhysicalFlowChart
+ * <PacketFlowChart
  *   nodes={[{ id: "in", x: 0.1, y: 0.5 }, { id: "out", x: 0.9, y: 0.5 }]}
  *   links={[{ source: "in", target: "out", value: 40 }]}
  *   coordinateMode="normalized"
@@ -54,7 +61,7 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
  *
  * @example
  * ```tsx
- * <PhysicalFlowChart
+ * <PacketFlowChart
  *   nodes={ports}
  *   edges={routes}
  *   pathAccessor="path"
@@ -63,8 +70,17 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
  * />
  * ```
  */
+export declare const PacketFlowChart: {
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PacketFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+/**
+ * @deprecated Renamed to {@link PacketFlowChart} in 3.9.0. Sends discrete packets along authored routes; "Physical" named the substrate and told a reader nothing about the reading protocol.
+ * The alias stays exported indefinitely for existing imports; new code and
+ * every registry (schema, capabilities, MCP, server configs) use `PacketFlowChart`.
+ */
 export declare const PhysicalFlowChart: {
-    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PhysicalFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PacketFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-export default PhysicalFlowChart;
+export default PacketFlowChart;

package/dist/components/charts/physics/PhysicsCustomChart.d.ts

@@ -62,7 +62,7 @@ export interface PhysicsCustomLayoutResult {
 }
 export type PhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomLayoutResult;
 export type PhysicsCustomSpawnDatumResult = PhysicsDatumSpawnResult | PhysicsQueuedSpawn | PhysicsQueuedSpawn[];
-export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     layout: PhysicsCustomLayout<TDatum, TConfig>;
     /**

package/dist/components/charts/physics/ProcessFlowChart.d.ts

@@ -1,12 +1,12 @@
 import * as React from "react";
-import { type PhysicsBodySelection, type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import { type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
 import { type CapacityQueueSnapshot } from "../../stream/physics/PhysicsControllers";
 import { type ProcessChromeOptions } from "../../recipes/processChrome";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type ProcessFlowProjectionMetadata, type ProcessFlowStageDef } from "./physicsChartUtils";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
 export type { ProcessFlowStageDef, ProcessFlowProjectionMetadata };
 export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
@@ -35,6 +35,11 @@ export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omi
     springDamping?: number;
     tooltip?: TooltipProp;
     paused?: boolean;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
     /**
      * When true (default), stages with `capacity` install live FIFO queue
@@ -43,8 +48,6 @@ export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omi
     liveCapacity?: boolean;
     /** Live capacity metrics callback (queue depth, processed count per region). */
     onCapacityChange?: (stats: CapacityQueueSnapshot[]) => void;
-    /** Shared selection (process body restyle without relayout). */
-    selection?: PhysicsBodySelection | null;
     /**
      * Soft body budget: caps live bodies via pipeline bodyLimit (evict oldest).
      * Use for infinite/long streams with sediment-style history in the readout.

package/dist/components/charts/physics/{PhysicalFlowChart.capability.d.ts → UnitPileChart.capability.d.ts}

@@ -1,2 +1,2 @@
 import type { ChartCapability } from "../../ai/chartCapabilityTypes";
-export declare const PhysicalFlowChartCapability: ChartCapability;
+export declare const UnitPileChartCapability: ChartCapability;

package/dist/components/charts/physics/{PhysicsPileChart.d.ts → UnitPileChart.d.ts}

@@ -3,8 +3,8 @@ import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor, ChartMode } from "../shared/types";
 import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
-export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+export interface UnitPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -30,15 +30,22 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
     showProjection?: boolean;
     sediment?: boolean;
     tooltip?: TooltipProp;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     paused?: boolean;
     frameProps?: PhysicsHocFrameProps<"config">;
 }
+/** @deprecated Renamed to {@link UnitPileChartProps} in 3.9.0. */
+export type PhysicsPileChartProps<TDatum extends Datum = Datum> = UnitPileChartProps<TDatum>;
 /**
  * Physics-backed unit pile chart that converts category values into repeated bodies and a readable settled projection.
  *
  * @example
  * ```tsx
- * <PhysicsPileChart
+ * <UnitPileChart
  *   data={[{ category: "A", value: 12 }, { category: "B", value: 8 }]}
  *   categoryAccessor="category"
  *   valueAccessor="value"
@@ -48,7 +55,7 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
  *
  * @example
  * ```tsx
- * <PhysicsPileChart
+ * <UnitPileChart
  *   mode="mechanical"
  *   mechanicalCategories={["North", "South", "West"]}
  *   mechanicalCount={90}
@@ -56,5 +63,11 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
  * />
  * ```
  */
-export declare const PhysicsPileChart: React.ForwardRefExoticComponent<PhysicsPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
-export default PhysicsPileChart;
+export declare const UnitPileChart: React.ForwardRefExoticComponent<UnitPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+/**
+ * @deprecated Renamed to {@link UnitPileChart} in 3.9.0. Unitizes category values into countable bodies; the substrate is an implementation detail, not the reading.
+ * The alias stays exported indefinitely for existing imports; new code and
+ * every registry (schema, capabilities, MCP, server configs) use `UnitPileChart`.
+ */
+export declare const PhysicsPileChart: React.ForwardRefExoticComponent<UnitPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default UnitPileChart;

package/dist/components/charts/physics/crucibleChartProps.d.ts

@@ -32,7 +32,7 @@ export type CrucibleSnapshotAt = number | {
     progress?: number;
 };
 export type CrucibleColorBy<TDatum extends Datum = Datum> = "category" | "status" | "outlet" | "product" | ChartAccessor<TDatum, string>;
-export interface CrucibleChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "onClick">, PhysicsSharedChartProps {
+export interface CrucibleChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "onClick" | "selection">, PhysicsSharedChartProps {
     /** Controlled, bounded source charge. CrucibleChart has no live push API. */
     data: TDatum[];
     /** Ordered furnace program. Every phase must have a unique id and duration. */

package/dist/components/charts/physics/crucibleChartUtils.d.ts

@@ -0,0 +1,9 @@
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleColorBy, CrucibleControls } from "./crucibleChartProps";
+import type { CrucibleComponentState, CrucibleRunState } from "./crucibleTypes";
+export declare function numericCrucibleSeed(seed: number | string | undefined): number;
+export declare function boundedCruciblePlaybackRate(value: unknown): number;
+export declare function resolveCrucibleControls(controls: boolean | CrucibleControls | undefined): Required<CrucibleControls>;
+export declare function crucibleColorKey<TDatum extends Datum>(component: CrucibleComponentState<TDatum>, colorBy: CrucibleColorBy<TDatum>, index: number): string;
+export declare function crucibleColorForKey(key: string): string;
+export declare function crucibleStateSummary<TDatum extends Datum>(state: CrucibleRunState<TDatum>, amountLabel?: string): string;

package/dist/components/charts/physics/gauntletChartProps.d.ts

@@ -9,7 +9,7 @@ import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { PhysicsProcessBodyGroup } from "./physicsProcessPrimitives";
 import type { PhysicsHocFrameProps, PhysicsRerunMS, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
 import type { GauntletEvent, GauntletGate, GauntletLayout, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyDefinition } from "./gauntletTypes";
-export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     idAccessor?: ChartAccessor<TDatum, string>;
@@ -43,6 +43,11 @@ export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<B
         positiveProperties: Map<string, GauntletPropertyDefinition>;
     }) => string;
     paused?: boolean;
+    /**
+     * Deterministic seed, matching every other physics HOC. An explicit
+     * `frameProps.config.kernel.seed` still wins so existing snapshots hold.
+     */
+    seed?: number;
     /**
      * Replay the full compound simulation this many milliseconds after it
      * settles. Omit or pass `null` for a single run; `0` replays on the next

package/dist/components/charts/physics/gauntletTerminal.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Gauntlet terminal state — the end of the authored tape, computed without
+ * running the simulation.
+ *
+ * ## Why this exists
+ *
+ * Every event-tape physics chart owes the same contract: **its end state must be
+ * computable from the authored inputs alone.** If the outcome only exists as the
+ * residue of a simulation, then reduced motion, SSR, snapshot export, and
+ * `describeChart` cannot state it, and the chart is a movie rather than a
+ * reading. `CrucibleChart` satisfies this by compiling `terminalState` /
+ * `terminalSpawns`; `ChainReactionChart` satisfies it by deriving task state from
+ * the data at `currentTime`. Gauntlet had no such function — this is it.
+ *
+ * The fold below mirrors the live `runGauntletTick` state path exactly (same
+ * `applyGauntletEffect` / `recordGauntletEvent` / viability / final-outcome
+ * order), so the pure answer and the simulated answer agree. Terminal means the
+ * tape has fully run: every authored event is due, including capacity-gated
+ * ones, because at terminal every gate visit has been processed.
+ *
+ * ## The one thing this cannot predict
+ *
+ * `GauntletChart` has a **second outcome source that is not in the tape**: with
+ * `crashDetection` enabled (the default), a core whose simulated trajectory
+ * touches the crash line is killed and its outcome is overridden to
+ * `"bad_design_crash"`. That is a genuine physics-derived finding, and no pure
+ * function can compute it — it depends on the trajectory.
+ *
+ * So this resolver returns the **authored-tape terminal state**. It equals the
+ * simulated settled state whenever the run does not crash (notably with
+ * `crashDetection={false}`, where the tape is the whole story). When crash
+ * detection is armed, treat the pure result as "the outcome the plan earns on
+ * paper" and the simulated `killed` / `crashX` fields as the physical override.
+ * Charts that need a fully authored reading should disable crash detection.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { GauntletEvent, GauntletLayout, GauntletProjectState, GauntletPropertyDefinition, GauntletViabilityFn } from "./gauntletTypes";
+export interface GauntletTerminalOptions<TDatum extends Datum = Datum> {
+    /** Initial project states, as `createInitialState` produces them. */
+    projects: readonly GauntletProjectState<TDatum>[];
+    /** Authored tape, or the per-project function form. */
+    events?: readonly GauntletEvent[] | ((project: GauntletProjectState<TDatum>, layout: GauntletLayout) => readonly GauntletEvent[]);
+    layout: GauntletLayout;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    viability?: GauntletViabilityFn<TDatum>;
+    outcome?: (project: GauntletProjectState<TDatum>, context: {
+        layout: GauntletLayout;
+        negativeProperties: Map<string, GauntletPropertyDefinition>;
+        positiveProperties: Map<string, GauntletPropertyDefinition>;
+    }) => string;
+}
+/**
+ * Fold one project's whole authored tape into its terminal state.
+ *
+ * Pure: no store, no kernel, no clock. Given the same inputs it returns the
+ * same state, which is what makes it usable for SSR and snapshot export.
+ */
+export declare function resolveGauntletTerminalState<TDatum extends Datum = Datum>(project: GauntletProjectState<TDatum>, options: GauntletTerminalOptions<TDatum>): GauntletProjectState<TDatum>;
+/** Terminal state for every project in a run. */
+export declare function resolveGauntletTerminalStates<TDatum extends Datum = Datum>(options: GauntletTerminalOptions<TDatum>): GauntletProjectState<TDatum>[];

package/dist/components/charts/physics/packetFlowSemantics.d.ts

@@ -0,0 +1,6 @@
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicalFlowProjectionMetadata } from "./physicsChartUtils";
+export declare function formatPhysicalFlowThroughput(value: number): string;
+export declare function physicalFlowPathD(points: PhysicalFlowProjectionMetadata["links"][number]["path"]): string;
+/** Build keyboard/reader targets from the authored throughput routes. */
+export declare function physicalFlowSemanticItems(metadata: PhysicalFlowProjectionMetadata | undefined): PhysicsSemanticItem[];

package/dist/components/charts/physics/physicsHocUtils.d.ts

@@ -1,9 +1,9 @@
 import * as React from "react";
 import type { FrameGraphicsProp } from "../../stream/useFrame";
-import type { PhysicsSemanticItem, StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsBodySelection, PhysicsSemanticItem, StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { Datum } from "../shared/datumTypes";
-import type { BaseChartProps, ChartMode } from "../shared/types";
+import type { BaseChartProps, ChartMode, LinkedHoverProp, SelectionConfig } from "../shared/types";
 import { type ChartModeResult } from "../shared/hooks";
 export type PhysicsHocFrameProps<TOmitted extends keyof StreamPhysicsFrameProps = never> = Partial<Omit<StreamPhysicsFrameProps, "initialSpawns" | "initialSpawnPacing" | "size" | TOmitted>>;
 /**
@@ -18,7 +18,48 @@ export type PhysicsSharedChartProps = {
     legendPosition?: StreamPhysicsFrameProps["legendPosition"];
     legendLayout?: StreamPhysicsFrameProps["legendLayout"];
     svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+    /**
+     * Shared selection. Pass a `{ name }` config to join the selection store
+     * (cross-highlight inside `LinkedCharts`), or a resolved
+     * `{ isActive, predicate }` body predicate directly.
+     */
+    selection?: PhysicsChartSelection;
+    /** Emit hover into the shared selection store for cross-chart highlighting. */
+    linkedHover?: LinkedHoverProp;
 };
+/**
+ * What a physics HOC's `selection` prop accepts.
+ *
+ * `SelectionConfig` (`{ name }`) joins the shared selection store, so physics
+ * bodies cross-highlight inside `LinkedCharts` like every other family.
+ * `PhysicsBodySelection` (`{ isActive, predicate }`) stays available as the
+ * direct escape hatch for hosts that resolve a body predicate themselves.
+ */
+export type PhysicsChartSelection = SelectionConfig | PhysicsBodySelection | null;
+export interface PhysicsSelectionOptions {
+    selection?: PhysicsChartSelection;
+    linkedHover?: LinkedHoverProp;
+    colorBy?: unknown;
+    chartType: string;
+    chartId?: string;
+    onObservation?: BaseChartProps["onObservation"];
+    onClick?: BaseChartProps["onClick"];
+    onBodyHover?: StreamPhysicsFrameProps["onBodyHover"];
+    fallbackFields?: string[];
+    unwrapSourceDatum?: boolean;
+}
+export interface PhysicsSelectionResult {
+    selection: PhysicsBodySelection | null;
+    onBodyHover?: StreamPhysicsFrameProps["onBodyHover"];
+}
+/**
+ * Wire a physics HOC into the shared selection store.
+ *
+ * The store resolves a predicate over *data*, while the frame wants a predicate
+ * over *bodies*, so the resolved predicate is lifted through `body.datum`.
+ * Bodies with no datum (walls, pegs, chrome) never match a data selection.
+ */
+export declare function usePhysicsSelection(options: PhysicsSelectionOptions): PhysicsSelectionResult;
 /** Galton / pile sampling mode (orthogonal to ChartMode display modes). */
 export type PhysicsSimulationMode = "sample" | "mechanical";
 /** Delay between a settled physics run and a fresh seeded replay. */
@@ -128,6 +169,8 @@ export declare function resolvePhysicsFrameSharedProps(props: Pick<BaseChartProp
     legendLayout?: StreamPhysicsFrameProps["legendLayout"];
     svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
 }, frameProps: Partial<StreamPhysicsFrameProps> | undefined, semanticItems?: PhysicsSemanticItem[], modeExtras?: {
+    /** Resolved body predicate from {@link usePhysicsSelection}. */
+    selection?: PhysicsBodySelection | null;
     chartMode?: ChartMode;
     className?: string;
     title?: string;

package/dist/components/charts/shared/auditAccessibilityStyles.d.ts

@@ -0,0 +1,9 @@
+import type { Datum } from "./datumTypes";
+/**
+ * Statically detect the serializable HatchFill form styleRules can carry.
+ * Function-valued rule styles may also return hatches at runtime, but the
+ * config-only audit cannot inspect those honestly.
+ */
+export declare function hasDeclaredHatchFill(props: Datum): boolean;
+/** True only when every declared hex color belongs to the safe palette. */
+export declare function usesCvdSafePalette(colorScheme: unknown): boolean;

package/dist/components/charts/shared/chartSpecCore.d.ts

@@ -1,12 +1,10 @@
 /**
- * Single source of truth for per-chart prop specifications.
- *
- * Three downstream consumers used to maintain their own per-chart entries:
+ * Single source of truth for per-chart prop specifications consumed by:
  *   - `ai/schema.json`                                    (LLM tool definitions)
  *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
  *   - `ai/componentMetadata.cjs`                          (category buckets)
  *
- * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * `validationMap.generated.ts` and `ai/schema.json` are generated from
  * this registry — run `npm run docs:chart-specs:schema` to refresh both after
  * editing a spec. `componentMetadata.cjs` is still
  * hand-edited but gated for parity by the registry: `check:chart-specs` (run

package/dist/components/charts/shared/gaugeGradient.d.ts

@@ -1,16 +1,12 @@
 import type { Datum } from "./datumTypes";
+import type { ColorGradientInput, GradientConfig, GradientStop } from "./gradient";
 export interface GaugeThresholdLike {
     value: number;
     color: string;
     label?: string;
 }
-export interface GaugeGradientStop {
-    offset: number;
-    color: string;
-}
-export interface GaugeGradientFill {
-    colorStops: GaugeGradientStop[];
-}
+export type GaugeGradientStop = GradientStop;
+export type GaugeGradientFill = ColorGradientInput;
 export interface GaugeArcDatum extends Datum {
     category: string;
     value: number;
@@ -48,7 +44,7 @@ interface BuildGaugeArcModelOptions {
     backgroundColor: string;
     fillZones: boolean;
     showScaleLabels: boolean;
-    gradientFill?: GaugeGradientFill;
+    gradientFill?: GradientConfig;
     gradientSteps?: number;
 }
 /**

package/dist/components/charts/shared/gradient.d.ts

@@ -0,0 +1,35 @@
+export interface GradientStop {
+    /** Position along the gradient, clamped to 0–1. */
+    offset: number;
+    /** Stop color. Omit to inherit the mark's resolved color. */
+    color?: string;
+    /** Stop opacity, clamped to 0–1. */
+    opacity?: number;
+}
+export interface GradientConfig {
+    stops: GradientStop[];
+}
+interface ColorStopsConfig {
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+}
+interface OpacityEndpointsConfig {
+    topOpacity?: number;
+    bottomOpacity?: number;
+}
+export interface SemanticGradientStopInput {
+    at: number;
+    color: string;
+    opacity?: number;
+}
+export type GradientInput = GradientConfig | boolean | ColorStopsConfig | OpacityEndpointsConfig;
+export type ColorGradientInput = GradientConfig | ColorStopsConfig;
+export type SemanticGradientInput = GradientConfig | SemanticGradientStopInput[];
+export declare const DEFAULT_GRADIENT: GradientConfig;
+export declare function normalizeGradient(input: GradientInput | null | undefined, defaultGradient?: GradientConfig): GradientConfig | undefined;
+export declare function normalizeColorGradient(input: ColorGradientInput | null | undefined): GradientConfig | undefined;
+export declare function normalizeSemanticGradient(input: SemanticGradientInput | null | undefined): GradientConfig | undefined;
+export declare function reverseGradient(gradient: GradientConfig): GradientConfig;
+export {};

package/dist/components/charts/shared/hatchFill.d.ts

@@ -1,15 +1,8 @@
 /**
- * Declarative hatch-fill descriptor — a single value that renders as a
- * diagonal-line pattern on BOTH rendering backends.
+ * Declarative hatch-fill descriptor that renders as a diagonal-line pattern
+ * on both rendering backends.
  *
- * The library historically had two disjoint hatch primitives: a canvas
- * `createHatchPattern` (→ `CanvasPattern`) and an SVG `<pattern>` builder
- * (`hatchFill` recipe / `createSVGHatchPattern`). A caller had to know
- * which medium they were painting into and hand-produce the right thing —
- * which is why a `CanvasPattern` returned from a `pieceStyle` silently
- * collapses to a solid color in SSR (`svgFill` drops non-string fills).
- *
- * `HatchFill` closes that gap: it is a plain, serializable descriptor that
+ * `HatchFill` is a plain, serializable descriptor that
  * can be set directly as `style.fill`. The canvas renderer resolves it to a
  * `CanvasPattern` (`resolveHatchCanvasPattern`); the SVG serializer resolves
  * it to a `<pattern>` def + `url(#id)` (`hatchPatternDef` / `hatchFillId`).

package/dist/components/charts/shared/hooks.d.ts

@@ -2,9 +2,7 @@ export { DEFAULT_COLOR } from "./colorUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, ResolvedMobileInteractionConfig } from "./types";
-import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
-import type { LegendValue } from "../../types/legendTypes";
 import type { Datum } from "./datumTypes";
 import type { ChartModeInput, ChartModeResult } from "./chartMode";
 export { DISABLED_MOBILE_INTERACTION, MOBILE_INTERACTION_DEFAULTS, MOBILE_INTERACTION_MIN_HIT_RADIUS, MOBILE_INTERACTION_TARGET_SIZE, isChartMode, resolveChartMode, resolveMobileInteraction, } from "./chartMode";
@@ -96,54 +94,8 @@ export declare function getCrosshairProps(linkedHover: unknown, crosshairSourceI
     linkedCrosshairName: string;
     linkedCrosshairSourceId: string;
 } | undefined;
-/**
- * Hook to create a legend and compute margins with legend-aware adjustment.
- * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
- * expansion pattern that every chart with color encoding repeats.
- */
-export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, }: {
-    data: Array<Datum>;
-    colorBy: Accessor<string> | undefined;
-    colorScale: ((v: string) => string) | undefined;
-    showLegend: boolean | undefined;
-    legendPosition?: LegendPosition;
-    userMargin: PartialMargin | undefined;
-    defaults?: MarginType;
-    categories?: string[];
-    /** Caller legend composed after the chart's inferred categorical groups. */
-    additionalLegend?: LegendValue;
-}): {
-    legend: LegendValue | undefined;
-    margin: MarginType;
-    legendPosition: LegendPosition;
-};
-export type LegendInteractionMode = "highlight" | "isolate" | "none";
-export interface LegendInteractionState {
-    highlightedCategory: string | null;
-    isolatedCategories: Set<string>;
-    onLegendHover: (item: {
-        label: string;
-    } | null) => void;
-    onLegendClick: (item: {
-        label: string;
-    }) => void;
-    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
-    legendSelectionHook: {
-        isActive: boolean;
-        predicate: (d: Datum) => boolean;
-    } | null;
-}
-/**
- * Hook managing legend highlight/isolate interaction.
- * - "highlight": hover over a legend item produces a selection hook that
- *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
- *   dim opacity resolves in this order: per-chart
- *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
- *   `DEFAULT_SELECTION_OPACITY` fallback.
- * - "isolate": click toggles category visibility; click all to reset
- */
-export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;
+export { useChartLegendAndMargin, useLegendInteraction, } from "./useChartLegend";
+export type { LegendPosition, LegendInteractionMode, LegendInteractionState, } from "./useChartLegend";
 /**
  * React-facing alias for {@link resolveChartMode}. Mode resolution is kept
  * pure so non-React renderers (notably semiotic/server) consume the exact same

package/dist/components/charts/shared/knownChartComponents.d.ts

@@ -5,5 +5,5 @@
  * This compact registry is intentionally separate from validation metadata:
  * config serialization only needs chart-name membership.
  */
-export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "CrucibleChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "BumpChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "UnitPileChart", "CollisionSwarmChart", "GauntletChart", "CrucibleChart", "ProcessFlowChart", "PacketFlowChart", "ChainReactionChart", "BigNumber"];
 export declare function isKnownChartComponent(componentName: string): boolean;

package/dist/components/charts/shared/streamPropsHelpers.d.ts

@@ -18,8 +18,7 @@ import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
  * and the user's tooltip body reads only fields it knows about.
  *
  * Typing the helper's return at the wider `HoverData` shape lets either
- * source flow through without a cast at the call site, matching the
- * inline form HOCs used before this refactor.
+ * source flow through without a cast at the call site.
  */
 type FrameTooltipContent = (d: HoverData) => ReactNode;
 /**

package/dist/components/charts/shared/useChartLegend.d.ts

@@ -0,0 +1,65 @@
+import type { Accessor } from "./types";
+import type { MarginType, PartialMargin } from "../../types/marginType";
+import type { LegendLayout, LegendValue } from "../../types/legendTypes";
+import { type AxisChromeInput } from "../../legendLayout";
+import type { Datum } from "./datumTypes";
+/**
+ * Hook to create a legend and compute margins with legend-aware adjustment.
+ * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
+ * expansion pattern that every chart with color encoding repeats.
+ */
+export type LegendPosition = "right" | "left" | "top" | "bottom";
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, chartWidth, legendLayout, hasTitle, axisChrome, }: {
+    data: Array<Datum>;
+    colorBy: Accessor<string> | undefined;
+    colorScale: ((v: string) => string) | undefined;
+    showLegend: boolean | undefined;
+    legendPosition?: LegendPosition;
+    userMargin: PartialMargin | undefined;
+    defaults?: MarginType;
+    categories?: string[];
+    /** Caller legend composed after the chart's inferred categorical groups. */
+    additionalLegend?: LegendValue;
+    /** Total chart width, used to estimate wrapping for top/bottom legends. */
+    chartWidth?: number;
+    /** Legend metrics shared with the renderer. */
+    legendLayout?: LegendLayout;
+    /** Reserve the chart-title band above a top legend. */
+    hasTitle?: boolean;
+    /**
+     * Axis chrome on the legend's side. A top/bottom legend is placed outside
+     * this band, so the reserved margin has to include it or the legend lands
+     * past the canvas edge.
+     */
+    axisChrome?: AxisChromeInput;
+}): {
+    legend: LegendValue | undefined;
+    margin: MarginType;
+    legendPosition: LegendPosition;
+};
+export type LegendInteractionMode = "highlight" | "isolate" | "none";
+export interface LegendInteractionState {
+    highlightedCategory: string | null;
+    isolatedCategories: Set<string>;
+    onLegendHover: (item: {
+        label: string;
+    } | null) => void;
+    onLegendClick: (item: {
+        label: string;
+    }) => void;
+    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
+    legendSelectionHook: {
+        isActive: boolean;
+        predicate: (d: Datum) => boolean;
+    } | null;
+}
+/**
+ * Hook managing legend highlight/isolate interaction.
+ * - "highlight": hover over a legend item produces a selection hook that
+ *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
+ *   dim opacity resolves in this order: per-chart
+ *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
+ *   `DEFAULT_SELECTION_OPACITY` fallback.
+ * - "isolate": click toggles category visibility; click all to reset
+ */
+export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;