semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,46 @@
+/**
+ * Pure style / color-map resolution helpers for PipelineStore.
+ * Accept a small context object so the store methods stay thin wrappers.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { PipelineConfig } from "./pipelineConfig";
+import type { Style } from "./types";
+export interface PipelineColorMapCache {
+    key: string;
+    map: Map<string, string>;
+    version: number;
+}
+export interface PipelineGroupDataCache {
+    version: number;
+    group: ((d: Datum) => string) | undefined;
+    data: Datum[];
+    result: {
+        key: string;
+        data: Datum[];
+    }[];
+}
+export declare function groupPipelineData(data: Datum[], getGroup: ((d: Datum) => string) | undefined, ingestVersion: number, cache: PipelineGroupDataCache | null): {
+    result: {
+        key: string;
+        data: Datum[];
+    }[];
+    cache: PipelineGroupDataCache;
+};
+export declare function resolvePipelineColorMap(data: Datum[], getColor: ((d: Datum) => string) | undefined, config: Pick<PipelineConfig, "colorScheme" | "themeCategorical">, ingestVersion: number, cache: PipelineColorMapCache | null): {
+    map: Map<string, string>;
+    cache: PipelineColorMapCache;
+};
+export declare function resolvePipelineGroupColor(options: {
+    group: string;
+    colorMapCache: PipelineColorMapCache | null;
+    groupColorMap: Map<string, string>;
+    groupColorCounter: number;
+    groupColorMapCap: number;
+    config: Pick<PipelineConfig, "colorScheme" | "themeCategorical">;
+}): {
+    color: string | null;
+    groupColorCounter: number;
+};
+export declare function resolvePipelineLineStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveGroupColor: (group: string) => string | null): Style;
+export declare function resolvePipelineAreaStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveGroupColor: (group: string) => string | null): Style;
+export declare function resolvePipelineBoundsStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveLineStyle: (group: string, sampleDatum?: Datum) => Style): Style;

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

@@ -11,6 +11,7 @@
  * Consumed by: PipelineStore.computeScene (after decay/pulse)
  */
 import type { SceneNode, TransitionConfig } from "./types";
+import type { GlyphDef } from "./glyphDef";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
 export type PrevPosition = {
@@ -24,6 +25,7 @@ export type PrevPosition = {
     closeY?: number;
     highY?: number;
     lowY?: number;
+    glyph?: GlyphDef;
 };
 export type PrevPath = {
     topPath?: [number, number][];
@@ -63,7 +65,7 @@ export interface TransitionState {
  * Detects entering nodes (new, no prev match) and exiting nodes (prev, no new match).
  * Mutates scene and exitNodes in place. Returns updated state.
  */
-export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): TransitionState;
+export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>, startTime?: number): TransitionState;
 /**
  * Advance the transition animation. Returns true if still animating.
  * Mutates scene nodes in place.

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

@@ -0,0 +1,69 @@
+/**
+ * Pure update contract for the stream-pipeline migration pilot.
+ *
+ * Stores still expose their established boolean/void mutation APIs. This
+ * module gives a host an additive, inspectable result path without coupling it
+ * to React, canvas, timers, or a particular chart family.
+ */
+/** Reasons a host may need to recompute or repaint part of a chart. */
+export declare const INVALIDATION_KINDS: readonly ["data", "domain", "layout", "scene-geometry", "scene-style", "data-paint", "interaction-paint", "overlay", "accessibility", "evidence"];
+export type Invalidation = (typeof INVALIDATION_KINDS)[number];
+/**
+ * Describes the operation that produced an update without retaining raw data
+ * or user callbacks in a diagnostic/result object.
+ */
+export interface ChangeSet {
+    readonly kind: "initialize" | "ingest" | "replace" | "remove" | "update" | "clear" | "config" | "restyle" | "enqueue" | "tick" | "settle" | "restore" | "constraint" | "impulse" | "pause" | "visibility";
+    readonly keys?: readonly string[];
+    readonly count?: number;
+}
+/**
+ * Monotonic revision counters. A host can consume only the counters relevant
+ * to its work (for example a canvas data layer observes `dataPaint`, while an
+ * accessibility tree observes `accessibility`).
+ */
+export interface RevisionSet {
+    readonly data: number;
+    readonly domain: number;
+    readonly layout: number;
+    readonly sceneGeometry: number;
+    readonly sceneStyle: number;
+    readonly dataPaint: number;
+    readonly interactionPaint: number;
+    readonly overlay: number;
+    readonly accessibility: number;
+    readonly evidence: number;
+}
+/** The additive result exposed by the XY PipelineStore reference path. */
+export interface UpdateResult {
+    readonly changeSet: ChangeSet;
+    readonly changed: ReadonlySet<Invalidation>;
+    readonly revisions: RevisionSet;
+}
+export declare function createRevisionSet(): RevisionSet;
+/** Return a fresh revision snapshot with exactly the invalidated counters bumped. */
+export declare function advanceRevisions(previous: RevisionSet, invalidations: Iterable<Invalidation>): RevisionSet;
+/**
+ * Build an immutable-by-convention update record from a change description.
+ * The Set is copied so later mutation of the caller's iterable cannot alter
+ * the revision decision that was recorded.
+ */
+export declare function createUpdateResult(changeSet: ChangeSet, invalidations: Iterable<Invalidation>, previousRevisions: RevisionSet): UpdateResult;
+/**
+ * Small retained-state helper for stores adopting the result contract. It
+ * keeps revision bookkeeping out of family-specific data/layout code while
+ * preserving each store's existing mutation API.
+ */
+export type UpdateResultListener = () => void;
+export interface UpdateResultStore {
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: UpdateResultListener): () => void;
+}
+export declare class UpdateResultTracker {
+    private revisions;
+    private latest;
+    private listeners;
+    get last(): UpdateResult;
+    subscribe(listener: UpdateResultListener): () => void;
+    record(changeSet: ChangeSet, invalidations: Iterable<Invalidation>): UpdateResult;
+}

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

@@ -0,0 +1,21 @@
+import type { UpdateResult } from "./pipelineUpdateContract";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+export type { UpdateResult } from "./pipelineUpdateContract";
+/** Shared additive update-result read and subscription surface for stream stores. */
+export interface PipelineUpdateResultSource {
+    readonly last: UpdateResult;
+    subscribe(listener: () => void): () => void;
+}
+/** Public lifecycle surface installed on each stream store prototype. */
+export interface UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    markStylePaintPending(): void;
+    consumeStylePaintPending(): boolean;
+}
+/** Adds the shared lifecycle methods without imposing a base-class constructor. */
+export declare function attachUpdateResultStore(target: {
+    prototype: object;
+}): void;

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

@@ -0,0 +1,22 @@
+/** Minimal surface shared by stream frames for idle pulse repainting. */
+export interface PulseRefreshStore {
+    lastCustomLayoutFailure?: {
+        preservedLastGoodScene?: boolean;
+    } | null;
+    hasActivePulsesAt(now: number): boolean;
+    refreshPulse(now: number): boolean;
+}
+export interface IdlePulseRefresh {
+    /** Whether the data canvas needs a style-only repaint this frame. */
+    changed: boolean;
+    /** Keep one subsequent frame so an expired glow can be cleared. */
+    pending: boolean;
+}
+/**
+ * Advance pulse styling without triggering a layout rebuild. A failed custom
+ * layout deliberately retains its last good scene, which must remain
+ * immutable until the layout owner recovers.
+ */
+export declare function refreshIdlePulse(store: PulseRefreshStore, now: number, sceneRecomputed: boolean, pendingRef: {
+    current: boolean;
+}): IdlePulseRefresh;

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

@@ -0,0 +1,27 @@
+import * as React from "react";
+import type { SceneRenderBackend, SceneRenderMode, Style } from "./types";
+type SceneLike = {
+    type?: string;
+    datum?: unknown;
+    style?: Style;
+};
+/** Resolve a whole-scene or per-datum renderer. The legacy `sketchy` token
+ * stays on the existing built-in rendering path. */
+export declare function resolveSceneRenderBackend<Node extends SceneLike>(renderMode: SceneRenderMode<Node> | undefined, node: Node): SceneRenderBackend<Node> | undefined;
+/** Paint nodes in scene order, delegating unsupported runs to the built-in renderer. */
+export declare function paintSceneWithBackend<Node extends SceneLike>(args: {
+    context: CanvasRenderingContext2D;
+    nodes: Node[];
+    renderMode: SceneRenderMode<Node> | undefined;
+    pixelRatio: number;
+    paintBuiltIn: (nodes: Node[]) => void;
+}): void;
+/** Try a backend for SSR/static SVG, then invoke the existing converter. */
+export declare function renderSceneWithBackend<Node extends SceneLike>(args: {
+    node: Node;
+    index: number;
+    renderMode: SceneRenderMode<Node> | undefined;
+    fallback: () => React.ReactNode;
+}): React.ReactNode;
+export declare function resetRenderBackendWarningsForTests(): void;
+export {};

package/dist/components/stream/renderers/canvasRenderHelpers.d.ts

@@ -16,6 +16,7 @@
  * mechanical bits that recur regardless of the shape being painted.
  */
 import type { CurveType } from "../types";
+import { type HatchFill } from "../../charts/shared/hatchFill";
 import type { CurveFactory } from "d3-shape";
 /**
  * Structural shapes for the gradient configs the helpers accept. Kept
@@ -61,7 +62,20 @@ export declare function resolveCurveFactory(curve: CurveType | undefined): Curve
  * `(typeof X === "string" ? resolveCSSColor(ctx, X) : X) || fallback`,
  * repeated once per renderer per fill/stroke site.
  */
-export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+/**
+ * Narrow a possibly-`HatchFill` `style.fill` to the `string | CanvasPattern`
+ * a canvas `fillStyle` accepts, for the direct-assign sites that don't
+ * otherwise route through {@link resolveCanvasFill}. Returns `undefined` for a
+ * nullish (or unresolvable) fill so callers can apply their own fallback with
+ * `?? "…"`.
+ *
+ * Delegates to {@link resolveCanvasFill} so behavior stays consistent: string
+ * fills (including `var(--…)`) resolve through `resolveCSSColor` — a raw CSS
+ * variable written straight to `fillStyle` would silently paint black — and a
+ * `HatchFill` resolves to its `CanvasPattern` (or its resolved background).
+ */
+export declare function coerceCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined): string | CanvasPattern | undefined;
 /**
  * Build a linear gradient from a `FillGradient` config. Returns `null`
  * when the gradient cannot be constructed (fewer than two valid color

package/dist/components/stream/renderers/geoCanvasRenderer.d.ts

@@ -1,4 +1,5 @@
-import type { GeoSceneNode } from "../geoTypes";
+import type { GeoScales, GeoSceneNode } from "../geoTypes";
+import type { StreamLayout } from "../types";
 /**
  * Canvas renderer for GeoAreaSceneNode — projected geographic polygons.
  * Uses Path2D for GPU-accelerated rendering of complex geo paths.
@@ -6,4 +7,4 @@ import type { GeoSceneNode } from "../geoTypes";
  * Points and lines in a geo frame are rendered by the existing
  * pointCanvasRenderer and lineCanvasRenderer respectively.
  */
-export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: any, _layout: any): void;
+export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: GeoScales, _layout: StreamLayout): void;

package/dist/components/stream/renderers/glyphCanvasRenderer.d.ts

@@ -0,0 +1,6 @@
+import type { NetworkSceneNode } from "../networkTypes";
+import type { StreamRendererFn } from "./types";
+/** XY / ordinal / geo painter (x/y-positioned glyph nodes). */
+export declare const glyphCanvasRenderer: StreamRendererFn;
+/** Network painter (cx/cy-positioned glyph nodes). */
+export declare function networkGlyphRenderer(ctx: CanvasRenderingContext2D, nodes: NetworkSceneNode[]): void;

package/dist/components/stream/renderers/networkParticleRenderer.d.ts

@@ -8,4 +8,4 @@ export declare function renderNetworkParticles(ctx: CanvasRenderingContext2D, po
 /**
  * Spawn particles for all edges proportional to their value.
  */
-export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle): void;
+export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle, random?: () => number): void;

package/dist/components/stream/renderers/resolveCSSColor.d.ts

@@ -21,6 +21,12 @@ export declare function resolveCSSColor(ctx: CanvasRenderingContext2D, value: st
  * invalidation is global because theme changes are global.
  */
 export declare function clearCSSColorCache(_canvas?: HTMLCanvasElement): void;
+/**
+ * Monotonic version bumped by theme changes and `clearCSSColorCache`.
+ * Frames can cache derived theme color objects keyed by this value so
+ * paint loops avoid `getComputedStyle` on every rAF.
+ */
+export declare function getCSSColorCacheVersion(): number;
 /**
  * Test-only: reset all cache state, including disconnecting any installed
  * observer/matchMedia listeners. Required for test isolation — without it,

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { Style } from "./types";
+/**
+ * Optional paint backend for pre-computed scene nodes. A backend may change
+ * how a mark looks, but it must not mutate the scene node: original geometry
+ * remains authoritative for interaction, focus, transitions, and accessibility.
+ */
+export interface SceneRenderBackend<Node = unknown> {
+    readonly id: string;
+    cacheKey(node: Node, style: Style): string;
+    drawCanvas(args: {
+        context: CanvasRenderingContext2D;
+        node: Node;
+        style: Style;
+        pixelRatio: number;
+    }): boolean;
+    renderStaticSVG(args: {
+        node: Node;
+        style: Style;
+        key: string;
+    }): ReactNode | null;
+}
+/** A backend can cover the whole scene or be selected per datum. */
+export type SceneRenderDatum<Node> = Node extends {
+    datum?: infer NodeDatum;
+} ? Exclude<NodeDatum, undefined> | null : Datum | null;
+export type SceneRenderMode<Node = unknown> = "sketchy" | SceneRenderBackend<Node> | ((datum: SceneRenderDatum<Node>, node: Node) => "sketchy" | SceneRenderBackend<Node> | undefined);

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

@@ -0,0 +1,45 @@
+import type { RevisionSet, UpdateResult, UpdateResultStore } from "./pipelineUpdateContract";
+export type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
+export interface SceneRevisionCheck {
+    revisions: SceneRevisionSet;
+    signature: string;
+    sawSignals: boolean;
+    wasUnconsumed: boolean;
+    warnUnconsumed: boolean;
+}
+interface SceneRevisionStore extends UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+}
+/** Development-only consumption and duplicate-compute diagnostics for a scene host. */
+export declare class SceneRevisionDiagnostics {
+    private readonly hostName;
+    constructor(hostName?: string);
+    private lastConsumed;
+    private lastObserved;
+    private lastDuplicateWarning;
+    private lastUnconsumedWarning;
+    /**
+     * Accept a React external-store observation without participating in frame
+     * scheduling or paint. The imperative result passed to beforeCompute remains
+     * authoritative; retaining the high-water mark only protects development
+     * diagnostics when React observes an update between frame passes.
+     */
+    observeUpdateResult(updateResult: UpdateResult): void;
+    beforeCompute(updateResult: UpdateResult, isTransitioning: boolean): SceneRevisionCheck;
+    afterCompute(check: SceneRevisionCheck, computedScene: boolean, dimsChanged: boolean): void;
+}
+/** Keep a frame's development-only revision tracker stable across renders. */
+export declare function useSceneRevisionDiagnostics(hostName: string): import("react").RefObject<SceneRevisionDiagnostics>;
+/** Wrap an unconditional scene build with the common revision accounting. */
+export declare function runSceneBuild(diagnostics: SceneRevisionDiagnostics, store: SceneRevisionStore, build: () => void, isTransitioning?: boolean, dimsChanged?: boolean): void;
+/**
+ * Observes external-store revisions without putting diagnostics on a React
+ * render path. Stores can record non-invalidating operational results during
+ * host effects, so a useSyncExternalStore subscription here could feed those
+ * diagnostics back into the host's render cycle.
+ */
+export declare const SceneRevisionDiagnosticsObserver: import("react").MemoExoticComponent<({ store, diagnostics }: {
+    store: UpdateResultStore;
+    diagnostics: SceneRevisionDiagnostics;
+}) => null>;
+export {};

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

@@ -0,0 +1,16 @@
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+/** Interaction props shared by all Stream Frame families. */
+export interface StreamSemanticInteractionProps<Hover> {
+    customHoverBehavior?: SemanticHoverBehavior<Hover>;
+    customClickBehavior?: SemanticClickBehavior<Hover>;
+    /** Structured interaction observations, including semantic focus/activate. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier included in observation events. */
+    chartId?: string;
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+}

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

@@ -0,0 +1,37 @@
+import { type MutableRefObject } from "react";
+/**
+ * Push the memoized pipeline config into the scene store and repaint.
+ *
+ * `config` is memoized upstream (the frames' `stablePipelineConfig`), so this
+ * fires only on a real config change, never per render. Marks the scene dirty
+ * and repaints because style callbacks (pointStyle, areaStyle, …) carried in
+ * the config may have changed even when geometry did not.
+ */
+export declare function useConfigSync<C>(storeRef: MutableRefObject<{
+    updateConfig(config: C): void;
+} | null>, config: C, dirtyRef: MutableRefObject<boolean>, scheduleRender: () => void): void;
+/**
+ * Bridge a custom layout's resolved selection (`layoutSelection`) into the
+ * scene store and repaint.
+ *
+ * `layoutSelection` has no single home in a store: the custom-chart HOCs
+ * assemble it in React by merging local component state (hover-highlight,
+ * legend interaction) with the cross-chart selection store
+ * (`effectiveSelectionHook = hover ?? legend ?? activeSelection`). React owns
+ * that blended value.
+ *
+ * Kept OFF the rebuild path: when the layout returned a `restyle` callback a
+ * selection change re-applies styles to the existing scene and repaints (no
+ * relayout, no quadtree rebuild); otherwise it marks the scene dirty so a
+ * rebuild lets `ctx.selection` reach the layout. Either way the overlay subtree
+ * re-renders against the new selection via `CustomLayoutSelectionProvider`.
+ *
+ * The `lastSelectionRef` guard makes the write fire only on a real selection
+ * change (the HOCs already memoize `layoutSelection` on its `isActive`/
+ * `predicate` identity), never per render.
+ */
+export declare function useLayoutSelectionSync<S>(storeRef: MutableRefObject<{
+    setLayoutSelection(selection: S | null): void;
+    hasCustomRestyle: boolean;
+    restyleScene(selection: S | null): void;
+} | null>, layoutSelection: S | null | undefined, dirtyRef: MutableRefObject<boolean>, scheduleRender: () => void): void;

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

@@ -0,0 +1,14 @@
+export interface ThemeSemanticColors {
+    primary?: string;
+    secondary?: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+    text?: string;
+    textSecondary?: string;
+    border?: string;
+    grid?: string;
+    surface?: string;
+}

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

@@ -0,0 +1,10 @@
+export declare function resolveHorizontalTickAnchor(mode: "middle" | "edges" | undefined, isLeftmost: boolean, isRightmost: boolean): "start" | "middle" | "end";
+export declare function resolveVerticalTickBaseline(mode: "middle" | "edges" | undefined, isTopmost: boolean, isBottommost: boolean): "hanging" | "middle" | "auto";
+export declare function tickPixelExtent(ticks: Array<{
+    pixel: number;
+}>): {
+    min: number | null;
+    max: number | null;
+};
+export declare function resolveGridDash(style: "dashed" | "dotted" | string | undefined): string | undefined;
+export declare function jaggedBaselinePath(orient: "left" | "right" | "top" | "bottom", width: number, height: number): string;

package/dist/components/stream/test-utils/frameScheduler.d.ts

@@ -0,0 +1,12 @@
+import type { FrameScheduler } from "../useFrame";
+/**
+ * Deterministic rAF scheduler for frame tests. It deliberately permits zero
+ * as the first handle so tests cannot rely on truthiness for pending work.
+ */
+export declare function createFrameScheduler(firstHandle?: number): {
+    scheduler: FrameScheduler;
+    requestedHandles: number[];
+    cancelledHandles: number[];
+    readonly pendingCount: number;
+    flush(timestamp?: number): void;
+};

package/dist/components/stream/test-utils/revisionConsumption.d.ts

@@ -0,0 +1,13 @@
+import { SceneRevisionDiagnostics, type SceneRevisionCheck } from "../sceneRevisionDiagnostics";
+import type { UpdateResult } from "../pipelineUpdateContract";
+export interface UnconsumedSceneRevisionProbe {
+    diagnostics: SceneRevisionDiagnostics;
+    initial: SceneRevisionCheck;
+    later: SceneRevisionCheck;
+}
+/**
+ * Assert the contract that a later style/state result cannot conceal scene
+ * work that a host has not consumed. Callers finish the probe with
+ * `diagnostics.afterCompute(probe.later, false, false)` and assert its warning.
+ */
+export declare function assertUnconsumedSceneRevisionSurvivesLaterUpdate(initialResult: UpdateResult, laterResult: UpdateResult, hostName?: string): UnconsumedSceneRevisionProbe;

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

@@ -0,0 +1,31 @@
+/**
+ * Shared title clearance for StreamFrame plot areas.
+ *
+ * Stream titles live in the outer SVG chrome while marks are translated into
+ * the plot margin. Reserving this strip before layout keeps titles from
+ * touching or overlapping the first row of marks when consumers supply a
+ * compact top margin.
+ */
+export interface TitleMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Enough room for the standard 14px title plus a visible gap to the plot. */
+export declare const MIN_TITLE_TOP_MARGIN = 36;
+/** One horizontal legend row plus its inset when no title is present. */
+export declare const MIN_TOP_LEGEND_MARGIN = 34;
+/** The standard title strip plus one horizontal legend row and plot gap. */
+export declare const MIN_TITLE_TOP_LEGEND_MARGIN = 58;
+/** Baseline that leaves a calm outer-edge inset for the standard title face. */
+export declare const TITLE_BASELINE = 22;
+/** Static SVG and GIF output only render text titles in their SVG chrome. */
+export declare function hasTextTitle(title: unknown): title is string;
+/**
+ * Reserve the shared top chrome before any frame calculates plot geometry.
+ * A raw StreamFrame can supply both a compact margin and a top legend, so the
+ * legend's first row needs its own minimum rather than relying on HOC margins.
+ */
+export declare function reserveFrameChromeMargin<T extends TitleMargin>(margin: T, hasTitle: boolean, hasTopLegend?: boolean): T;
+export declare function reserveTitleMargin<T extends TitleMargin>(margin: T, title: unknown): T;