semiotic 3.8.3 → 3.8.4

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

@@ -7,7 +7,7 @@ import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineSto
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { PhysicsProcessBodyGroup } from "./physicsProcessPrimitives";
-import type { PhysicsHocFrameProps, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
+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 {
     data?: TDatum[];
@@ -43,6 +43,12 @@ export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<B
         positiveProperties: Map<string, GauntletPropertyDefinition>;
     }) => string;
     paused?: boolean;
+    /**
+     * Replay the full compound simulation this many milliseconds after it
+     * settles. Omit or pass `null` for a single run; `0` replays on the next
+     * timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     projectPlacement?: (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout) => Partial<GauntletProjectPlacement>;
     showChrome?: boolean;
     /**

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

@@ -12,9 +12,10 @@ export declare function defaultGauntletTooltipContent(hover: PhysicsHoverData):
 export declare function drawGauntletBody(ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style): void;
 export declare function resolveCanvasColor(ctx: CanvasRenderingContext2D, value: Style[keyof Style] | undefined, fallback: string): string;
 export declare function drawTethers(ctx: CanvasRenderingContext2D, bodies: PhysicsBodyState[]): void;
-export declare function GauntletChrome({ layout, states }: {
+export declare function GauntletChrome({ layout, states, compact }: {
     layout: GauntletLayout;
     states: readonly GauntletProjectState[];
+    compact?: boolean;
 }): React.JSX.Element;
 export declare function gauntletSemanticItem(body: PhysicsBodyState): false | {
     label: string;

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

@@ -10,7 +10,7 @@ export { CORE_KIND, POSITIVE_KIND, NEGATIVE_KIND } from "./gauntletTypes";
 export type { GauntletAccessors, GauntletBodyDatum, GauntletCoreBodyFn, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectPlacementFn, GauntletProjectState, GauntletPropertyDefinition, GauntletPropertyForceContext, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions, GauntletViabilityFn } from "./gauntletTypes";
 export declare const DEFAULT_WIDTH = 900;
 export declare const DEFAULT_HEIGHT = 520;
-export declare function gauntletWallColliders(layout: Pick<GauntletLayout, "width" | "floorY">): NonNullable<PhysicsPipelineConfig["colliders"]>;
+export declare function gauntletWallColliders(layout: Pick<GauntletLayout, "width" | "floorY"> & Partial<Pick<GauntletLayout, "height">>): NonNullable<PhysicsPipelineConfig["colliders"]>;
 export declare function readAccessor<TDatum extends Datum, TValue>(datum: TDatum, index: number, accessor: ChartAccessor<TDatum, TValue> | undefined, fallback: TValue): TValue;
 export declare function propertyLabel(property: GauntletPropertyDefinition | undefined): string;
 export declare function projectCoreId(projectId: string): string;
@@ -23,19 +23,34 @@ export declare const GAUNTLET_WALL: {
     readonly rightInset: 30;
     readonly thickness: 8;
 };
+type GauntletWallLayout = Pick<GauntletLayout, "width" | "floorY"> & Partial<Pick<GauntletLayout, "height">>;
+/** Scale the authored gauntlet corridor into context and sparkline boxes. */
+export declare function resolveGauntletWall(layout: GauntletWallLayout): {
+    readonly left: 28;
+    readonly top: 76;
+    readonly rightInset: 30;
+    readonly thickness: 8;
+} | {
+    left: number;
+    top: number;
+    rightInset: number;
+    thickness: number;
+};
+/** Scale default body/orbit geometry while preserving authored full-size values. */
+export declare function gauntletSpatialScale(layout: GauntletWallLayout): number;
 /**
  * Keep body centers inside the playable gauntlet corridor so satellite
  * property particles never spawn or settle outside the left/right walls
  * (the "stuck on the left" regression for Homes on Main Street).
  */
-export declare function clampGauntletPoint(x: number, y: number, radius: number, layout: Pick<GauntletLayout, "width" | "floorY">): {
+export declare function clampGauntletPoint(x: number, y: number, radius: number, layout: GauntletWallLayout): {
     x: number;
     y: number;
 };
 export declare function buildLayout(size: [number, number], gates: readonly GauntletGate[] | undefined, crashOffset: number): GauntletLayout;
 export declare function defaultPlacement(layout: GauntletLayout): Required<GauntletProjectPlacement>;
 export declare function resolvePlacement<TDatum extends Datum>(project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, projectPlacement: GauntletProjectPlacementFn<TDatum> | undefined): Required<GauntletProjectPlacement>;
-export declare function featureSlot(ids: readonly string[], id: string): {
+export declare function featureSlot(ids: readonly string[], id: string, spatialScale?: number): {
     angle: number;
     index: number;
     radius: number;
@@ -68,4 +83,4 @@ export declare function buildGauntletPhysics<TDatum extends Datum = Datum>(optio
     initialSpawns: PhysicsQueuedSpawn[];
     layout: GauntletLayout;
 };
-export declare function buildNegativeSpawn<TDatum extends Datum>(project: GauntletProjectState<TDatum>, property: GauntletPropertyDefinition, index: number, x: number, y: number, layout: Pick<GauntletLayout, "width" | "floorY">, spawnAt?: number): PhysicsQueuedSpawn;
+export declare function buildNegativeSpawn<TDatum extends Datum>(project: GauntletProjectState<TDatum>, property: GauntletPropertyDefinition, index: number, x: number, y: number, layout: GauntletWallLayout, spawnAt?: number): PhysicsQueuedSpawn;

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

@@ -34,7 +34,10 @@ export declare function spawnBodiesForGauntletEffect<TDatum extends Datum>(optio
         color?: string;
         durationMs?: number;
         radius?: number;
+        scale?: number;
     }) => unknown;
+    /** Uniform pop-burst scale (see StreamPhysicsPopOptions.scale). */
+    popScale?: number;
 }): void;
 export declare function projectRouteTarget<TDatum extends Datum>(elapsed: number, project: GauntletProjectState<TDatum>, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>, events: readonly GauntletEvent[], gateById: Map<string, GauntletLayout["gates"][number]>, terminalBehavior: "outcome" | "hold-last"): {
     x: number;

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

@@ -21,6 +21,18 @@ export type PhysicsSharedChartProps = {
 };
 /** 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. */
+export type PhysicsRerunMS = number | null;
+/**
+ * Add an optional settle -> delay -> remount loop to a physics HOC.
+ *
+ * Remounting is intentional: it replays the chart's deterministic seed,
+ * initial bodies, and spawn pacing instead of trying to reverse a live store.
+ */
+export declare function usePhysicsRerun(config: StreamPhysicsFrameProps["config"], rerunMS: PhysicsRerunMS | undefined, paused: boolean | undefined, onRerun?: () => void): {
+    config: StreamPhysicsFrameProps["config"];
+    rerunKey: number;
+};
 /**
  * Split ChartMode (`primary`/`context`/`sparkline`/`mobile`) from the
  * Galton/pile `sample`/`mechanical` simulation mode. Accepts legacy

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

@@ -36,6 +36,8 @@ export interface ChartModeInput {
     responsiveRules?: ResponsiveRule[];
 }
 export interface ChartModeResult {
+    /** Effective mode after responsive rules have been applied. */
+    mode: ChartMode;
     width: number;
     height: number;
     showAxes: boolean;
@@ -65,3 +67,9 @@ export declare function resolveChartMode(mode: ChartMode | undefined, userProps:
     width?: number;
     height?: number;
 }): ChartModeResult;
+/**
+ * Axis-free charts keep their established 10px regular-mode inset while
+ * adopting the shared context/sparkline margins. Reading `resolved` here is
+ * important: responsive rules may have changed the effective chart mode.
+ */
+export declare function resolveAxisFreeMarginDefaults(resolved: Pick<ChartModeResult, "compactMode" | "marginDefaults">): ChartModeResult["marginDefaults"];

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

@@ -32,7 +32,7 @@
  *     schema.json (and MCP responses) but are dropped from validationMap
  *     (which only reads `type` and `enum`).
  */
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function" | "null";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime" | "physics" | "value";
 /**
@@ -157,7 +157,7 @@ export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
 export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
 export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
 export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
-export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline", "mobile"];
 /**
  * Compose a chart's full prop set (bags + ownProps) in deterministic order.
  * ownProps wins on key collision so a chart can override a shared default.

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

@@ -12,6 +12,7 @@
  * />
  * ```
  */
+import type { HatchFill } from "./hatchFill";
 export interface HatchPatternOptions {
     /** Background color of the pattern tile */
     background?: string;
@@ -27,9 +28,13 @@ export interface HatchPatternOptions {
 /**
  * Create a repeating diagonal-line hatch pattern for canvas fills.
  *
- * Must be called in a browser environment (needs canvas). Returns null
- * in server/test environments where canvas is unavailable.
+ * In a browser (canvas available) returns a `CanvasPattern`. In server/test
+ * environments — where canvas is unavailable — returns the equivalent
+ * serializable {@link HatchFill} descriptor instead of `null`, so the same
+ * `pieceStyle`/`nodeStyle` renders a hatch through the SVG path rather than
+ * collapsing to the solid fallback. Use {@link isHatchFill} to distinguish the
+ * two forms; both are valid as a `style.fill`.
  */
 export declare function createHatchPattern(options?: HatchPatternOptions, 
 /** Optional target canvas to create the pattern on (for correct DPR scaling) */
-targetCtx?: CanvasRenderingContext2D): CanvasPattern | null;
+targetCtx?: CanvasRenderingContext2D): CanvasPattern | HatchFill | null;

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

@@ -0,0 +1,55 @@
+/**
+ * Pure LineChart series-feature prep for the SSR / renderChart path.
+ *
+ * Mirrors the client HOC orchestration of:
+ *   - `useSeriesFeatures` (forecast / anomaly via `buildForecast`)
+ *   - gapStrategy (break / interpolate / zero)
+ *   - directLabel endpoint annotations
+ *   - segment-aware lineStyle (createSegmentLineStyle)
+ *
+ * Client uses lazy dynamic import + React state for these; SSR can call
+ * the pure statisticalOverlays entry points synchronously.
+ */
+import type { Datum } from "./datumTypes";
+import { type AnomalyConfig, type ForecastConfig } from "./statisticalOverlays";
+export interface LineSeriesSsrInput {
+    data: unknown;
+    xAccessor?: string | ((d: Datum) => unknown);
+    yAccessor?: string | ((d: Datum) => unknown);
+    lineBy?: string | ((d: Datum) => unknown);
+    colorBy?: string | ((d: Datum) => unknown);
+    colorScheme?: unknown;
+    color?: string;
+    forecast?: ForecastConfig;
+    anomaly?: AnomalyConfig;
+    gapStrategy?: "break" | "interpolate" | "zero";
+    directLabel?: boolean | {
+        position?: "start" | "end";
+        fontSize?: number;
+    };
+    /** Existing annotations to merge with statistical + direct-label ones. */
+    annotations?: Datum[];
+    themeCategorical?: string[];
+    /** Base lineStyle from buildLineStyle — wrapped with segment styling when forecast is set. */
+    baseLineStyle?: (d: Datum, group?: string) => Datum;
+}
+export interface LineSeriesSsrResult {
+    data: Datum[];
+    xAccessor: string | ((d: Datum) => unknown);
+    yAccessor: string | ((d: Datum) => unknown);
+    groupAccessor: string | ((d: Datum) => unknown) | undefined;
+    colorAccessor: string | ((d: Datum) => unknown) | undefined;
+    annotations: Datum[];
+    lineStyle?: (d: Datum, group?: string) => Datum;
+    yExtent?: [number, number];
+    /** Extra right/left margin for direct labels. */
+    marginExtra?: {
+        left?: number;
+        right?: number;
+    };
+}
+/**
+ * Prepare LineChart props for static SSR: forecast/anomaly data + annotations,
+ * gap handling, direct labels, segment lineStyle.
+ */
+export declare function prepareLineSeriesForSsr(input: LineSeriesSsrInput): LineSeriesSsrResult;

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

@@ -43,7 +43,7 @@ export type LinkedBrushProp = string | {
     yField?: string;
 };
 /**
- * Chart display mode — controls default chrome, size, and interaction.
+ * Chart display mode — controls default decoration, size, and interaction.
  * User-provided props always override mode defaults.
  */
 export type ChartMode = "primary" | "context" | "sparkline" | "mobile";
@@ -98,7 +98,7 @@ export interface ResolvedMobileInteractionConfig {
  * Base props shared across all chart components
  */
 export interface BaseChartProps {
-    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    /** Display mode: "primary" (full decoration), "context" (compact), "sparkline" (inline), or "mobile" (touch-first) */
     mode?: ChartMode;
     /** Chart width in pixels. Default: 600 */
     width?: number;

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

@@ -5,7 +5,7 @@ export interface ValidationResult {
     valid: boolean;
     errors: string[];
 }
-export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function" | "null";
 export interface PropDef {
     type: PropType | PropType[];
     enum?: readonly string[];

package/dist/components/charts/xy/AreaChart.d.ts

@@ -14,6 +14,16 @@ export interface SemanticGradientStop {
     /** Optional opacity applied to this stop. */
     opacity?: number;
 }
+/**
+ * Convert value-anchored `semanticGradient` stops (`{ at, color }` on the value
+ * scale, 0–100) into the frame's `gradientFill.colorStops` (offset 0 = top).
+ * Exported so the server (`renderChart`) config resolves it identically to this
+ * HOC — otherwise SSR silently drops `semanticGradient` and paints a flat area.
+ */
+export declare function semanticGradientToColorStops(stops: SemanticGradientStop[]): Array<{
+    offset: number;
+    color: string;
+}>;
 /**
  * AreaChart component props
  */

package/dist/components/charts/xy/minimapBrushOverlay.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { StreamScales } from "../../stream/types";
+export interface MinimapBrushOverlayProps {
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: StreamScales | null;
+    brushDirection: "x" | "y";
+    extent: [number, number] | null;
+    onBrush: (extent: [number, number] | null) => void;
+}
+export declare function MinimapBrushOverlay({ width, height, margin, scales, brushDirection, extent, onBrush, }: MinimapBrushOverlayProps): React.JSX.Element;

package/dist/components/charts/xy/minimapBrushOverlayLazy.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import type { MinimapBrushOverlayProps } from "./minimapBrushOverlay";
+/** Renders nothing until d3-brush module resolves, then mounts the brush. */
+export declare function MinimapBrushOverlayLazy(props: MinimapBrushOverlayProps): React.JSX.Element | null;

package/dist/components/charts/xy/scatterplotMatrixBrushOverlay.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+import type { StreamXYFrameHandle } from "../../stream/types";
+export interface ScatterplotMatrixBrushOverlayProps {
+    frameRef: React.RefObject<StreamXYFrameHandle | null>;
+    cellSize: number;
+    onBrush: (extent: [number, number][] | null) => void;
+}
+export declare function ScatterplotMatrixBrushOverlay({ frameRef, cellSize, onBrush, }: ScatterplotMatrixBrushOverlayProps): React.JSX.Element;

package/dist/components/charts/xy/scatterplotMatrixBrushOverlayLazy.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+import type { ScatterplotMatrixBrushOverlayProps } from "./scatterplotMatrixBrushOverlay";
+export declare function ScatterplotMatrixBrushOverlayLazy(props: ScatterplotMatrixBrushOverlayProps): React.JSX.Element | null;

package/dist/components/realtime/types.d.ts

@@ -191,6 +191,11 @@ export interface RealtimeFrameHandle {
     remove(id: string | string[]): Datum[];
     /** Update data by ID in place. Requires an ID accessor. Returns previous values. */
     update(id: string | string[], updater: (d: Datum) => Datum): Datum[];
+    /**
+     * Ordinal-only bounded ingest: replace the buffer while preserving category
+     * order and enter/move/exit transitions. XY/network/geo typically omit this.
+     */
+    replace?(data: Datum[]): void;
     clear(): void;
     getData(): Datum[];
     /** Returns the frame's resolved scales, or null if unavailable.

package/dist/components/recipes/gridObservatory.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Pure grid-operations helpers for multi-series power observatories.
+ *
+ * These turn balancing-authority hourly rows into the chart-ready series used by
+ * StackedAreaChart, DifferenceChart, BigNumber, styleRules factories, and
+ * provenanced event annotations. They are domain math — not a React kit — so
+ * agents and pages can share the same pipeline.
+ *
+ * Honesty: {@link reserveMarginPct} is a **readability proxy** from public
+ * demand / net-generation (+ optional interchange) series. It is *not* an ISO
+ * contingency-reserve product. Label it as such in UI and `describeChart` copy.
+ */
+import type { StyleRule } from "../charts/shared/styleRules";
+import type { HatchFill } from "../charts/shared/hatchFill";
+/** Stable fuel keys used across regions when present. */
+export declare const GRID_FUEL_KEYS: readonly ["naturalGas", "coal", "nuclear", "hydro", "wind", "solar", "other"];
+export type GridFuelKey = (typeof GRID_FUEL_KEYS)[number];
+/** Human labels for fuel keys (legend / tooltips). */
+export declare const GRID_FUEL_LABELS: Record<GridFuelKey, string>;
+/**
+ * One hour (or finest grain) in one balancing authority.
+ * Compatible with the strategy schema in docs/strategy/examples-thegrid.md.
+ */
+export type GridHour = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw?: number;
+    netGenMw: number;
+    interchangeMw?: number;
+    fuels: Partial<Record<GridFuelKey, number>>;
+};
+export type ReserveSnapshot = {
+    t: number;
+    ba: string;
+    /** Rough operational headroom proxy — never claim ISO-grade contingency reserve. */
+    reserveMarginPct: number;
+    netLoadMw: number;
+    demandMw: number;
+    netGenMw: number;
+};
+export type ReserveLevels = {
+    /** Margin below this % is "tight" / danger. Default 5. */
+    tight?: number;
+    /** Margin below this % is "watch" / warning. Default 12. */
+    watch?: number;
+    /** Margin at or above this % is comfortable / success. Default 20. */
+    comfortable?: number;
+};
+export type FuelStackRow = {
+    t: number;
+    fuel: GridFuelKey;
+    fuelLabel: string;
+    mw: number;
+    ba: string;
+};
+export type DemandForecastRow = {
+    t: number;
+    a: number;
+    b: number;
+    demandMw: number;
+    forecastMw: number;
+    errorMw: number;
+    ba: string;
+};
+export type OperatingPointSummary = {
+    t: number;
+    ba: string;
+    demandMw: number;
+    forecastMw: number | null;
+    forecastErrorMw: number | null;
+    netGenMw: number;
+    reserveMarginPct: number;
+    topFuel: GridFuelKey | null;
+    topFuelShare: number;
+    topFuelMw: number;
+    fuelShares: Partial<Record<GridFuelKey, number>>;
+};
+export type GridEventWindow = {
+    id: string;
+    /** Inclusive start epoch ms. */
+    start: number;
+    /** Inclusive end epoch ms. */
+    end: number;
+    label: string;
+    /** Optional longer note for callouts. */
+    note?: string;
+    /** "heat-wave" | "outage" | "demand-spike" | open string. */
+    kind?: string;
+    /** ISO 8601 duration or ms; default "P7D". */
+    ttlHint?: string | number;
+    y?: number;
+    /** Data y for y-threshold style notes. */
+    value?: number;
+};
+/**
+ * Stackable long-form fuel series for StackedAreaChart (`areaBy: "fuel"`).
+ * Zero / missing fuels are omitted so empty keys do not invent area layers.
+ */
+export declare function stackFuelSeries(hours: readonly GridHour[], options?: {
+    fuels?: readonly GridFuelKey[];
+    includeZero?: boolean;
+}): FuelStackRow[];
+/**
+ * DifferenceChart rows: series A = demand, series B = forecast.
+ * Hours without a finite forecast are skipped.
+ */
+export declare function demandForecastRows(hours: readonly GridHour[]): DemandForecastRow[];
+/**
+ * Readability proxy for operational headroom.
+ *
+ * ```
+ * reserveMarginPct = ((supply - demand) / demand) * 100
+ * supply = capacityOrNetGen + max(0, -interchange)  // imports add supply
+ * ```
+ *
+ * When demand is 0, returns 0. Negative values mean demand exceeds supply.
+ *
+ * **Not** ISO contingency reserve (spinning + non-spinning + regulation).
+ * Document that distinction wherever this number is shown.
+ */
+export declare function reserveMarginPct(input: {
+    demand: number;
+    capacityOrNetGen: number;
+    interchange?: number;
+}): number;
+/** Per-hour reserve snapshots derived from {@link GridHour} rows. */
+export declare function reserveSeries(hours: readonly GridHour[]): ReserveSnapshot[];
+/**
+ * Declarative `styleRules` for marks whose primary value is reserve margin %.
+ * Hatch on the tight band so color is not the only encoding.
+ *
+ * Works on BarChart / DotPlot (ordinal) and LineChart / Scatterplot when the
+ * mark value (or `field: "reserveMarginPct"`) is the margin percent.
+ */
+export declare function thresholdBandsForReserve(levels?: ReserveLevels, options?: {
+    field?: string;
+    /** Override hatch for the tight band. */
+    tightHatch?: HatchFill;
+    tightFill?: string;
+    watchFill?: string;
+    comfortableFill?: string;
+}): StyleRule[];
+/**
+ * Annotation band descriptors for reserve threshold strips (y-band style).
+ * Pair with chart `annotations` — not the same object as styleRules.
+ */
+export declare function reserveAnnotationBands(levels?: ReserveLevels): Array<{
+    type: "band";
+    y0: number;
+    y1: number;
+    label: string;
+    color: string;
+    fillOpacity: number;
+    emphasis: "secondary";
+}>;
+/** Summarize the operating point at `now` (or the last hour ≤ now). */
+export declare function summarizeOperatingPoint(hours: readonly GridHour[], now?: number): OperatingPointSummary | null;
+/**
+ * Convert authored event windows into annotation objects with provenance + lifecycle
+ * fields suitable for `applyAnnotationLifecycle`.
+ *
+ * Returns plain annotation dicts (not React nodes). Callers may pass the array to
+ * chart `annotations` after lifecycle treatment.
+ */
+export declare function gridEventAnnotations(events: readonly GridEventWindow[], options?: {
+    now?: number;
+    author?: string;
+    source?: string;
+}): Array<Record<string, unknown>>;
+/** Pick the top N tightest-margin hours for a ranked risk strip. */
+export declare function tightestHours(reserves: readonly ReserveSnapshot[], n?: number): ReserveSnapshot[];
+/** Format MW with locale grouping; returns "—" for non-finite. */
+export declare function formatMw(value: number, digits?: number): string;
+/** Format reserve margin percent with sign awareness. */
+export declare function formatReservePct(value: number, digits?: number): string;

package/dist/components/recipes/recipeChrome.d.ts

@@ -44,6 +44,30 @@ export declare function boundsOf(points: ReadonlyArray<{
     width: number;
     height: number;
 } | null;
+/** Axis-aligned box with a top-left origin (chip, card, scene rect). */
+export interface HullBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type HullPadding = number | {
+    x?: number;
+    y?: number;
+};
+/**
+ * Axis-aligned hull of discrete mark boxes, with optional padding. Use this when
+ * marks are chips/cards with known extents (not just points): the result fully
+ * surrounds the marks so a stroke drawn *after* the marks reads as a true
+ * enclosure (fill under, stroke over). Returns null for an empty set.
+ *
+ * @example
+ * ```ts
+ * const hull = hullFromBoxes(chips, { x: 12, y: 10 })
+ * // overlays: fill rect (under) then marks then stroke-only rect (over)
+ * ```
+ */
+export declare function hullFromBoxes(boxes: ReadonlyArray<HullBox>, padding?: HullPadding): HullBox | null;
 export interface BandLabelProps {
     text: string;
     x: number;