semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,128 @@
+import * as React from "react";
+import type { FrameGraphicsProp } from "../../stream/useFrame";
+import type { 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 ChartModeResult } from "../shared/hooks";
+export type PhysicsHocFrameProps<TOmitted extends keyof StreamPhysicsFrameProps = never> = Partial<Omit<StreamPhysicsFrameProps, "initialSpawns" | "initialSpawnPacing" | "size" | TOmitted>>;
+/**
+ * Chrome / AI / annotation contracts HOCs forward to StreamPhysicsFrame.
+ * Compose with `BaseChartProps` on every physics HOC.
+ */
+export type PhysicsSharedChartProps = {
+    annotations?: StreamPhysicsFrameProps["annotations"];
+    autoPlaceAnnotations?: StreamPhysicsFrameProps["autoPlaceAnnotations"];
+    background?: StreamPhysicsFrameProps["background"];
+    legend?: StreamPhysicsFrameProps["legend"];
+    legendPosition?: StreamPhysicsFrameProps["legendPosition"];
+    legendLayout?: StreamPhysicsFrameProps["legendLayout"];
+    svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+};
+/** Galton / pile sampling mode (orthogonal to ChartMode display modes). */
+export type PhysicsSimulationMode = "sample" | "mechanical";
+/**
+ * Split ChartMode (`primary`/`context`/`sparkline`/`mobile`) from the
+ * Galton/pile `sample`/`mechanical` simulation mode. Accepts legacy
+ * `mode="mechanical"` as simulationMode for back-compat.
+ */
+export declare function resolvePhysicsModes(options: {
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+}): {
+    chartMode: ChartMode | undefined;
+    simulationMode: PhysicsSimulationMode;
+};
+/** Physics fills its box; only compact ChartModes get non-zero chrome padding. */
+export declare function physicsMarginForMode(compactMode: boolean, mode?: ChartMode): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export declare function resolvePhysicsChartSize(size: [number, number] | undefined, width: number | undefined, height: number | undefined, fallback: [number, number]): [number, number];
+export type PhysicsChartModeProps = {
+    width?: number;
+    height?: number;
+    title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    /** Frame-level hover; HOCs may pass via tooltip or frameProps. */
+    enableHover?: boolean;
+    mobileInteraction?: BaseChartProps["mobileInteraction"];
+    mobileSemantics?: BaseChartProps["mobileSemantics"];
+    responsiveRules?: BaseChartProps["responsiveRules"];
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+    size?: [number, number];
+    showProjection?: boolean;
+    showChrome?: boolean;
+    tooltip?: TooltipProp;
+    className?: string;
+};
+export interface PhysicsChartModeResult {
+    chartMode: ChartMode | undefined;
+    simulationMode: PhysicsSimulationMode;
+    resolved: ChartModeResult;
+    chartSize: [number, number];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    showProjection: boolean;
+    showChrome: boolean;
+    enableHover: boolean;
+    title: string | undefined;
+    description: string | undefined;
+    summary: string | undefined;
+    accessibleTable: boolean | undefined;
+    className: string | undefined;
+    compactMode: boolean;
+    mobileInteraction: ChartModeResult["mobileInteraction"];
+    mobileSemantics: ChartModeResult["mobileSemantics"];
+}
+/**
+ * ChartMode + size + compact chrome defaults for every physics HOC.
+ * Primary physics sizes stay family-specific (`primaryFallback`); mode only
+ * overrides when width/height/size are unset.
+ */
+export declare function usePhysicsChartMode(props: PhysicsChartModeProps, primaryFallback: [number, number], options?: {
+    hasSimulationMode?: boolean;
+}): PhysicsChartModeResult;
+export declare function renderPhysicsChartState<TDatum extends Datum>(options: {
+    data?: TDatum[] | null;
+    emptyContent?: BaseChartProps["emptyContent"];
+    loading?: BaseChartProps["loading"];
+    loadingContent?: BaseChartProps["loadingContent"];
+    size: [number, number];
+}): React.ReactElement | null;
+export declare function renderPhysicsFrame(componentName: string, size: [number, number], children: React.ReactNode): React.ReactElement;
+export declare function composePhysicsFrameGraphics(first: FrameGraphicsProp | undefined, second: FrameGraphicsProp | undefined): FrameGraphicsProp | undefined;
+export declare function resolvePhysicsTooltipProps(tooltip: TooltipProp | undefined, frameProps?: Partial<StreamPhysicsFrameProps>): Pick<StreamPhysicsFrameProps, "enableHover" | "tooltipContent">;
+/**
+ * HOC → StreamPhysicsFrame shared Semiotic contracts: a11y, observation,
+ * click, chrome (title/legend/annotations), primitive styling, emphasis.
+ * Prefer HOC props; frameProps fill gaps.
+ */
+export declare function resolvePhysicsFrameSharedProps(props: Pick<BaseChartProps, "accessibleTable" | "chartId" | "className" | "color" | "description" | "emphasis" | "hoverRadius" | "onClick" | "onObservation" | "opacity" | "stroke" | "strokeWidth" | "summary" | "title"> & {
+    annotations?: StreamPhysicsFrameProps["annotations"];
+    autoPlaceAnnotations?: StreamPhysicsFrameProps["autoPlaceAnnotations"];
+    background?: StreamPhysicsFrameProps["background"];
+    legend?: StreamPhysicsFrameProps["legend"];
+    legendPosition?: StreamPhysicsFrameProps["legendPosition"];
+    legendLayout?: StreamPhysicsFrameProps["legendLayout"];
+    svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+}, frameProps: Partial<StreamPhysicsFrameProps> | undefined, semanticItems?: PhysicsSemanticItem[], modeExtras?: {
+    chartMode?: ChartMode;
+    className?: string;
+    title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    enableHover?: boolean;
+    margin?: StreamPhysicsFrameProps["margin"];
+}): Partial<StreamPhysicsFrameProps>;
+export type { TooltipProp };

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

@@ -0,0 +1,41 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartLayout } from "./physicsChartShared";
+export interface PhysicsPileMechanicalSampleOptions {
+    categories?: readonly string[];
+    count?: number;
+    idPrefix?: string;
+    seed?: number;
+    unitValue?: number;
+}
+export interface PhysicsPileOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    categoryAccessor: ChartAccessor<TDatum, string>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    unitValue: number;
+    ballRadius: number;
+    seed: number;
+    size: [number, number];
+}
+export declare function generatePhysicsPileMechanicalSamples(options?: PhysicsPileMechanicalSampleOptions): Datum[];
+export interface PileTubeGeometry {
+    laneWidth: number;
+    tubeWidth: number;
+    ballDiameter: number;
+    perRow: number;
+    centerX: (index: number) => number;
+    pileHeight: (count: number) => number;
+}
+/**
+ * Column geometry shared by the pile builder and its projection overlay so the
+ * ghost bar's height is exactly the fill target the stacked units rise to reach.
+ * Units drop into a narrow tube (a few balls wide) so their count reads as
+ * height — a bar chart assembled from falling units, not a spreading heap.
+ */
+export declare function pileTubeGeometry(plot: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, categoryCount: number, ballRadius: number): PileTubeGeometry;
+export declare function buildPhysicsPile<TDatum extends Datum>(options: PhysicsPileOptions<TDatum>): PhysicsChartLayout;

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

@@ -0,0 +1,38 @@
+import type { PhysicsColliderBodyFilter, PhysicsColliderSpec, PhysicsColliderShape } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsSemanticItem, StreamPhysicsRegionEffect, StreamPhysicsRegionKind } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+export interface PhysicsProcessStage {
+    id: string;
+    label?: string;
+    description?: string;
+    kind?: StreamPhysicsRegionKind | string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface PhysicsProcessBodyGroup<TDatum extends Datum = Datum> {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    bodyIds?: readonly string[];
+    datum?: TDatum;
+    state?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export interface PhysicsProcessBoundaryOptions {
+    id?: string;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    friction?: number;
+    restitution?: number;
+    thickness?: number;
+}
+export declare function physicsProcessBoundaryColliders(shape: PhysicsColliderShape, options?: PhysicsProcessBoundaryOptions): PhysicsColliderSpec[];
+export declare function physicsProcessRegionSemanticItem(region: StreamPhysicsRegionEffect): PhysicsSemanticItem | null;
+export declare function physicsProcessStageSemanticItems(stages: readonly PhysicsProcessStage[]): PhysicsSemanticItem[];
+export declare function physicsProcessGroupSemanticItems<TDatum extends Datum>(groups: readonly PhysicsProcessBodyGroup<TDatum>[]): PhysicsSemanticItem[];

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

@@ -0,0 +1,97 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsTypes";
+import { groupCompletionRows, type BodyGroupSpec, type ProcessVolumeLayout } from "../../recipes/processPhysics";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface ProcessFlowStageDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /** Relative width share along the route. */
+    share?: number;
+    /**
+     * Continuous forward force while bodies overlap the stage.
+     * Number form is `{ x: force, y: 0 }`.
+     */
+    force?: number | {
+        x?: number;
+        y?: number;
+    };
+    damping?: number;
+    /**
+     * Capacitated processing stand-in: throughput metadata + force/damping.
+     * Full queue DES is ProcessFlow controller territory later.
+     */
+    capacity?: {
+        unitsPerSecond: number;
+        /** Datum field used as work-units (stamped into attributes only for now). */
+        unitAccessor?: string;
+    };
+    /**
+     * Raise drag with a pressure scalar (or occupancy when provided at build time).
+     */
+    pressure?: boolean | {
+        pressure?: number;
+        occupancy?: number;
+        baseDamping?: number;
+        dampingPerUnit?: number;
+        energyPerUnit?: number;
+    };
+    /** Rework / bounce portal toward another stage id. */
+    portal?: {
+        targetStageId: string;
+        force?: {
+            x?: number;
+            y?: number;
+        };
+    };
+    /** Absorbing sink (completion / merge). */
+    absorb?: boolean;
+    kind?: StreamPhysicsRegionEffect["kind"];
+}
+export interface ProcessFlowPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    stages: readonly ProcessFlowStageDef[];
+    size: [number, number];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    stageAccessor?: ChartAccessor<TDatum, string>;
+    groupBy?: ChartAccessor<TDatum, string>;
+    groupLabelAccessor?: ChartAccessor<TDatum, string>;
+    workAccessor?: ChartAccessor<TDatum, number>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    ballRadius?: number;
+    seed?: number;
+    /** Horizontal process lane (default). */
+    route?: "horizontal";
+    groupCompletion?: "allAbsorbed" | "none";
+    /** Optional column x for feature/group anchors (plot-relative fraction 0–1). */
+    groupAnchorAlong?: number;
+    springStiffness?: number;
+    springDamping?: number;
+    gravityX?: number;
+    gravityY?: number;
+    settle?: boolean;
+}
+export interface ProcessFlowProjectionMetadata {
+    kind: "process-flow";
+    plot: PhysicsChartArea["plot"];
+    volume: ProcessVolumeLayout;
+    stages: Array<{
+        id: string;
+        label: string;
+        x: number;
+        width: number;
+        count: number;
+        capacity?: number;
+        absorb?: boolean;
+        portalTarget?: string;
+    }>;
+    groups: BodyGroupSpec[];
+    groupCompletion: ReturnType<typeof groupCompletionRows>;
+    regionEffects: StreamPhysicsRegionEffect[];
+}
+/**
+ * Build a capacitated multi-body process lane: stage regions, optional feature
+ * body-groups, springs toward stage centers, and a settled stage-count projection.
+ */
+export declare function buildProcessFlowPhysics<TDatum extends Datum>(options: ProcessFlowPhysicsOptions<TDatum>): PhysicsChartLayout;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -3,14 +3,22 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Time interval for binning */
     binSize: number;
     /** Chart dimensions as [width, height] */

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -3,15 +3,23 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 import { type AggregateConfig } from "./aggregate";
 import { type EventTimeConfig } from "./eventTime";
 export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -1,15 +1,23 @@
 import * as React from "react";
-import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
+import type { ArrowOfTime, WindowMode, Style, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -43,6 +51,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     timeExtent?: [number, number];
     /** Fixed value domain */
     valueExtent?: [number, number];
+    /** Value-axis scale. "symlog" supports signed values while compressing large magnitudes. */
+    yScaleType?: "linear" | "log" | "symlog";
     /** Extent padding factor */
     extentPadding?: number;
     /** Category accessor for color-coding dots */
@@ -59,6 +69,10 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     stroke?: string;
     /** Dot stroke width */
     strokeWidth?: number;
+    /** Per-datum dot style. Returned values override the top-level dot primitives and category color. */
+    pointStyle?: (datum: TDatum) => Style & {
+        r?: number;
+    };
     /** Show canvas-drawn axes */
     showAxes?: boolean;
     /** Background fill color */

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

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

@@ -0,0 +1,88 @@
+/**
+ * `<AnnotationLabel>` — the single, shared renderer for the text label of a
+ * region-bounding annotation (threshold lines, bands, enclosures, category
+ * highlights) across every frame and the server SSR path.
+ *
+ * Two problems it solves:
+ *   1. **Legibility.** A label sitting over dense marks needs a backdrop to
+ *      stay readable. Historically the region rules hand-rolled a
+ *      `paint-order: stroke` white "halo" inline — and only some of them, and
+ *      the client and server disagreed (client `y-threshold` had a halo, the
+ *      server's didn't). This component makes the halo a first-class,
+ *      consistent option and adds a genuine semitransparent **box** backdrop
+ *      (the rounded panel behind a label like "Fast-scaling · 10").
+ *   2. **Duplication.** Client (`annotationRules.tsx`) and server
+ *      (`staticAnnotations.tsx`) both emit label `<text>`; routing both through
+ *      one component removes the drift.
+ *
+ * `background` is the knob:
+ *   - `"halo"` / `true` — a stroke halo (default for region annotations; matches
+ *      the legacy look byte-for-byte when `haloColor`/`haloWidth` are unset)
+ *   - `"box"` — a filled, optionally-semitransparent rounded rect behind the text
+ *   - `"none"` / `false` — plain text
+ *   - a config object — fine-grained control over either treatment
+ *
+ * The box's geometry is derived from an *estimated* text width (SVG can't
+ * measure text without a live DOM, and the server path has none), which is
+ * accurate enough for a padded backdrop and identical on both backends.
+ */
+import * as React from "react";
+export interface AnnotationLabelBackgroundConfig {
+    /** Backdrop treatment. @default "halo" */
+    type?: "halo" | "box";
+    /**
+     * Backdrop paint. For `"halo"` it is the outline color (defaults to the
+     * plot background so the halo "erases" marks under the text). For `"box"`
+     * it is the panel fill.
+     * @default "var(--semiotic-bg, #ffffff)"
+     */
+    fill?: string;
+    /** Box fill opacity (box mode only). @default 0.85 */
+    opacity?: number;
+    /** Box inner padding in px — number (uniform) or `{x,y}`. @default {x:6,y:3} */
+    padding?: number | {
+        x: number;
+        y: number;
+    };
+    /** Box corner radius in px. @default 3 */
+    radius?: number;
+    /** Box border color (box mode only). */
+    stroke?: string;
+    /** Box border width in px. @default 0 */
+    strokeWidth?: number;
+    /** Halo stroke width in px (halo mode only). @default 3 */
+    haloWidth?: number;
+}
+export type AnnotationLabelBackground = boolean | "halo" | "box" | "none" | AnnotationLabelBackgroundConfig;
+export interface AnnotationLabelProps {
+    x: number;
+    y: number;
+    text: string | number;
+    /** Text color. */
+    fill: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    fontFamily?: string;
+    textAnchor?: "start" | "middle" | "end";
+    dominantBaseline?: React.SVGAttributes<SVGTextElement>["dominantBaseline"];
+    /**
+     * Backdrop treatment. Defaults to `"halo"` (the legacy region-label look).
+     * Pass `"box"` for a semitransparent panel, `"none"` for plain text, or a
+     * config object for fine control.
+     */
+    background?: AnnotationLabelBackground;
+    className?: string;
+}
+/**
+ * Rough width of a rendered label. SVG offers no synchronous text metrics
+ * (and the server has no DOM at all), so we estimate from character count.
+ * ~0.6em per glyph is a reasonable average for the sans-serif UI faces this
+ * library ships; the box carries padding, so a small error is invisible.
+ */
+export declare function estimateLabelWidth(text: string | number, fontSize: number): number;
+/**
+ * Render an annotation's text label with an optional legibility backdrop.
+ * Emits a bare `<text>` (halo/none) or a `<g>` with a backing `<rect>` + text
+ * (box). Safe on both the client SVG overlay and the server static SVG path.
+ */
+export declare function AnnotationLabel(props: AnnotationLabelProps): React.ReactElement;

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

@@ -0,0 +1,35 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
+import type { OnObservationCallback, ObservationInputType } from "../../store/ObservationStore";
+export type ChartAnnotation = Datum;
+export interface AnnotationActivationEvent {
+    annotation: ChartAnnotation;
+    annotationId?: string;
+    chartId?: string;
+    inputType: ObservationInputType;
+}
+export type OnAnnotationActivateCallback = (event: AnnotationActivationEvent) => void;
+export interface AnnotationActivationOptions {
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
+}
+/** Route annotation activation to both a direct callback and the observation store. */
+export declare function useAnnotationActivationOptions(options: AnnotationActivationOptions): AnnotationActivationOptions;
+/**
+ * Resolve a durable annotation identity without ever falling back to array
+ * position. Provenance stable IDs are accepted for agent-authored notes.
+ */
+export declare function annotationStableId(annotation: ChartAnnotation): string | undefined;
+/**
+ * Event props for a widget's existing HTML boundary. Capture phase observes
+ * arbitrary descendant controls without replacing their behavior or adding a
+ * nested interactive element.
+ */
+export declare function annotationActivationProps(annotation: ChartAnnotation, options?: AnnotationActivationOptions): React.HTMLAttributes<HTMLDivElement> & {
+    "data-semiotic-annotation-id"?: string;
+    "data-semiotic-annotation-widget": "";
+};
+/** True when a bubbled frame click originated inside a widget annotation. */
+export declare function isAnnotationActivationTarget(target: EventTarget | null): boolean;

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

@@ -0,0 +1,5 @@
+export declare const TOP_LABEL_BASELINE = 16;
+/** Keep a horizontal-threshold label inside the plot when its rule is near the top. */
+export declare function thresholdLabelY(y: number, height: number): number;
+/** Place a horizontal-band label just inside its visible top edge. */
+export declare function bandLabelY(y0: number, y1: number): number;

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
 import type { Datum } from "./datumTypes";
+import { type AnnotationActivationOptions } from "./annotationActivation";
 export { applyAnnotationEmphasis, type AnnotationRenderPair } from "./annotationHierarchy";
 type AnnotationRule = (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
 /**
@@ -17,4 +18,4 @@ type AnnotationRule = (annotation: Datum, index: number, context: AnnotationCont
  * through to the default rule, preserving the existing override contract.
  */
 export declare function renderAnnotationPass(annotations: ReadonlyArray<Datum>, defaultRule: AnnotationRule, userRule: AnnotationRule | undefined, context: AnnotationContext): React.ReactNode[];
-export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;
+export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network", activation?: AnnotationActivationOptions): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;