semiotic 3.8.4 → 3.8.5

package/dist/components/semiotic-utils-core.d.ts

@@ -20,6 +20,9 @@ export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver
 export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate, } from "./charts/shared/styleRules";
 export { validateProps } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
+export { auditData, formatDataAudit, profileNumericFields, toDataAuditNotifications, } from "./data/auditData";
+export type { AuditDataOptions, CheckedNumericContract, DataAuditChartNotification, DataAuditDiagnosis, DataAuditNotificationOptions, DataAuditResult, NumericFieldProfile, ProfileNumericFieldsOptions, } from "./data/auditData";
+export type { NumericAggregateContract, NumericContracts, NumericFieldContract, NumericFieldRole, NumericRequirement, } from "./data/numericContracts";
 export { auditAccessibility, formatAccessibilityAudit, accessibilityCaveats } from "./charts/shared/auditAccessibility";
 export { auditMobileVisualization, formatMobileVisualizationAudit, mobileVisualizationCaveats } from "./charts/shared/auditMobileVisualization";
 export { responsiveRuleMatches, resolveResponsiveRules } from "./charts/shared/responsiveRules";

package/dist/components/semiotic.d.ts

@@ -72,7 +72,7 @@ export { intentManifestFromRecipe, summarizeIntentManifest } from "./ai/intentMa
 export type { IntentManifest, IntentManifestFromRecipeOptions } from "./ai/intentManifest";
 export { useNavigationSync } from "./ai/useNavigationSync";
 export type { UseNavigationSyncOptions, UseNavigationSyncResult } from "./ai/useNavigationSync";
-export type { ChartContainerProps, ChartContainerHandle, ChartContainerMobileOptions, ChartNotification, ChartNotificationLevel, } from "./ChartContainer";
+export type { ChartContainerProps, ChartContainerHandle, ChartContainerDataAudit, ChartContainerDataAuditOptions, ChartContainerMobileOptions, ChartNotification, ChartNotificationLevel, } from "./ChartContainer";
 export type { MobileChartChip, MobileChartContainerProps, MobileChartDetailMode, } from "./MobileChartContainer";
 export type { MobileStandardBrushControls, MobileStandardControlKind, MobileStandardControlLegendItem, MobileStandardControlRequest, MobileStandardControlsMode, MobileStandardControlsProps, MobileStandardLegendControls, MobileStandardZoomControls, UseMobileRangeControlsOptions, UseMobileRangeControlsResult, } from "./MobileStandardControls";
 export type { MobileVisualizationContract } from "./charts/shared/auditMobileVisualization";

package/dist/components/server/renderEvidence.d.ts

@@ -47,6 +47,26 @@ export interface RenderEvidence {
     ariaLabel: string;
     /** Stable warning codes (EMPTY_SCENE, NO_SCALES). */
     warnings: string[];
+    /**
+     * The resolved margin Semiotic actually used — after auto-reservation for a
+     * legend, a title, or any other chrome that grows a side beyond the caller's
+     * input. This is ground truth for reconstructing the plot rectangle by
+     * hand (e.g. a caller hand-drawing an SSR overlay); it is exactly what the
+     * emitted SVG's `data-area` group is translated by.
+     */
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** The plot rectangle after resolving `margin` against the outer `width`/`height`. */
+    plot?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
 }
 /**
  * Internal mutable slot threaded through the frame renderers. Only
@@ -85,6 +105,13 @@ interface BuildEvidenceInput {
     edgeCount?: number;
     legendItems?: number;
     extraWarnings?: string[];
+    /** The resolved margin (after auto-reservation) the caller's frame used. */
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
 }
 /** Assemble evidence from a computed scene. Component name is stamped later
  *  by `renderChartWithEvidence`, which knows the HOC-level name. */

package/dist/components/server/serverChartConfigs.d.ts

@@ -52,6 +52,7 @@ export declare const CHART_CONFIGS: {
     CollisionSwarmChart: ChartConfig;
     ProcessFlowChart: ChartConfig;
     GauntletChart: ChartConfig;
+    CrucibleChart: ChartConfig;
     PhysicalFlowChart: ChartConfig;
     PhysicsCustomChart: ChartConfig;
 };

package/dist/components/server/serverChartConfigsPhysics.d.ts

@@ -5,5 +5,14 @@ export declare const physicsPileChart: ChartConfig;
 export declare const collisionSwarmChart: ChartConfig;
 export declare const processFlowChart: ChartConfig;
 export declare const gauntletChart: ChartConfig;
+/**
+ * Static CrucibleChart renders the same deterministic ledger used by the
+ * client HOC. A replay request settles at the terminal state for SSR (the
+ * client also hydrates from that reduced-motion snapshot); snapshot mode is
+ * the one deliberate way to request an authored intermediate instant.
+ * `paused`, `playbackRate`, and `rerunMS` govern wall-clock replay only and
+ * therefore cannot alter this static semantic state.
+ */
+export declare const crucibleChart: ChartConfig;
 export declare const physicalFlowChart: ChartConfig;
 export declare const physicsCustomChart: ChartConfig;

package/dist/components/server/staticAnnotations.d.ts

@@ -7,6 +7,7 @@ import type { Datum, DatumValue } from "../charts/shared/datumTypes";
  */
 import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
+import type { AnnotationContext } from "../realtime/types";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 interface AnnotationScales {
     x?: AnnotationScale;
@@ -46,6 +47,17 @@ export interface StaticAnnotationConfig {
     yAccessor?: string;
     /** Ordinal projection — determines whether r maps to x or y */
     projection?: "vertical" | "horizontal" | "radial";
+    /**
+     * Custom SVG annotation renderer — same contract as the client
+     * `svgAnnotationRules` frame prop. When present, each annotation is
+     * offered to this rule first; returning `null`/`undefined` falls through
+     * to the built-in static type handlers. Without this, custom middle-
+     * marker / bulb overlays (and any other non-built-in annotation type)
+     * silently vanished from `renderChart` SVG.
+     */
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode;
+    /** Chart data forwarded into the AnnotationContext for custom rules. */
+    annotationData?: Datum[];
 }
 /**
  * Render annotations as static SVG elements.

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

@@ -52,6 +52,7 @@ export declare class GeoPipelineStore implements UpdateResultStore {
         cy: number;
         maxCost: number;
         availableRadius: number;
+        layout?: "radial" | "strip";
     } | null;
     private areas;
     private pointData;

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

@@ -3,6 +3,7 @@ import type { OnObservationCallback } from "../store/ObservationStore";
 import { type OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 import * as React from "react";
 import type { ReactNode } from "react";
+import type { AnnotationContext } from "../realtime/types";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 interface GeoSVGOverlayProps {
@@ -45,6 +46,12 @@ interface GeoSVGOverlayProps {
     chartId?: string;
     chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
+    /**
+     * Custom SVG annotation renderer. Same contract as XY/ordinal
+     * `svgAnnotationRules`. Runs after geographic `coordinates` are projected
+     * to pixel `x`/`y`, so rules can use the shared pixel-scale context.
+     */
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     pointNodes?: {
         pointId?: string;
         x: number;

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

@@ -1,6 +1,11 @@
 /**
  * Distance-cartogram projection of geo point scene nodes.
  * Mutates point/line positions in place; returns layout metadata for overlays.
+ *
+ * Two encodings:
+ * - `radial` (default): pixel distance from center ∝ cost; bearing from geography
+ * - `strip`: 1D Langren-style cost axis — x ∝ cost, y collapsed to a baseline
+ *   (sparkline-friendly; no map chrome)
  */
 import type { DistanceCartogramConfig, GeoSceneNode } from "./geoTypes";
 import type { StreamLayout } from "./types";
@@ -9,6 +14,8 @@ export type GeoCartogramLayout = {
     cy: number;
     maxCost: number;
     availableRadius: number;
+    /** Active layout encoding — overlays branch on this. */
+    layout: "radial" | "strip";
 };
 /**
  * Apply a distance cartogram transform to the scene.

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

@@ -3,7 +3,7 @@ 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, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
-import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
+import type { AnnotationContext, HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
@@ -35,6 +35,12 @@ export interface DistanceCartogramConfig {
     costAccessor: string | ((d: Datum) => number);
     strength?: number;
     lineMode?: "straight" | "fractional";
+    /**
+     * Layout encoding for cost-from-center:
+     * - `"radial"` (default): polar cartogram — distance ∝ cost, bearing from geography
+     * - `"strip"`: 1D Langren-style number line — x ∝ cost, y collapsed (sparkline)
+     */
+    layout?: "radial" | "strip";
 }
 export interface GeoAreaSceneNode {
     type: "geoarea";
@@ -239,6 +245,14 @@ export interface StreamGeoFrameProps<T = Datum> {
     /** Observe activation of widget annotations without replacing widget behavior. */
     onAnnotationActivate?: OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
+    /**
+     * Custom SVG annotation renderer — same contract as XY/ordinal
+     * `svgAnnotationRules`. Called before the built-in geo annotation rules;
+     * return `null`/`undefined` to fall through. Geo pre-projects
+     * `coordinates: [lon, lat]` to pixel `x`/`y` before this runs so a single
+     * rule body works on canvas CSR and `renderChart` SSR.
+     */
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
@@ -305,12 +319,13 @@ export interface StreamGeoFrameHandle {
     clear(): void;
     getProjection(): GeoProjection | null;
     getGeoPath(): GeoPath<void, GeoPermissibleObjects> | null;
-    /** Get cartogram layout info (center position, max cost, radius) */
+    /** Get cartogram layout info (center position, max cost, radius / strip length) */
     getCartogramLayout(): {
         cx: number;
         cy: number;
         maxCost: number;
         availableRadius: number;
+        layout?: "radial" | "strip";
     } | null;
     /** Get current zoom level (1 = default) */
     getZoom(): number;

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

@@ -4,7 +4,11 @@ import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
 import type { NetworkLayoutResult } from "./networkCustomLayout";
 /** Imperative API exposed by `StreamNetworkFrame` refs. */
 export interface StreamNetworkFrameHandle {
+    /** Ingest one edge immediately and coalesce its expensive layout with other
+     * pushes at the next animation frame. Geometry getters commit first. */
     push(edge: EdgePush): void;
+    /** Ingest and lay out an explicit edge batch synchronously, absorbing any
+     * layout pending from prior single-edge pushes. */
     pushMany(edges: EdgePush[]): void;
     /** Remove a node by ID. Also removes connected edges. */
     removeNode(id: string): boolean;

package/dist/components/stream/physics/PhysicsSettledSVG.d.ts

@@ -1,3 +1,7 @@
+import * as React from "react";
+import type { Style } from "../types";
+import type { FrameGraphicsProp, FrameMargin } from "../useFrame";
+import type { PhysicsBodyState } from "./PhysicsKernel";
 import type { PhysicsSettledEvidence } from "./PhysicsEvidence";
 import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
 import { type PhysicsSettledScene, type PhysicsSettledSceneOptions } from "./PhysicsSettledScene";
@@ -7,8 +11,12 @@ export interface PhysicsSettledSVGOptions extends PhysicsSettledSceneOptions {
     title?: string;
     description?: string;
     background?: string;
+    backgroundGraphics?: FrameGraphicsProp;
     className?: string;
+    foregroundGraphics?: FrameGraphicsProp;
     idPrefix?: string;
+    margin?: Partial<FrameMargin>;
+    renderBodySVG?: (body: PhysicsBodyState, style: Style, index: number, idPrefix: string) => React.ReactNode | undefined;
 }
 export interface PhysicsSettledSVGRender {
     svg: string;

package/dist/components/useChartContainerDataAudit.d.ts

@@ -0,0 +1,7 @@
+import type { ChartNotification } from "./ChartContainer";
+import type { ChartConfig } from "./export/chartConfig";
+import type { ChartContainerDataAudit } from "./chartContainerDataAudit";
+type AuditableChartConfig = Pick<ChartConfig, "component" | "props">;
+/** Load the opt-in numeric evaluator only when a container asks for it. */
+export declare function useChartContainerDataAudit(chartConfig: AuditableChartConfig | undefined, dataAudit: ChartContainerDataAudit | undefined): ChartNotification[];
+export {};