semiotic 3.7.3 → 3.7.5

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

@@ -0,0 +1,105 @@
+/** The Kafka Streams window taxonomy. */
+export type WindowType = "tumbling" | "hopping" | "session";
+/** Which statistic the aggregated series carries as its primary value. */
+export type AggregateStat = "mean" | "sum" | "min" | "max" | "count";
+/** Envelope drawn around the aggregated series. */
+export type AggregateBand = "stddev" | "minmax" | "none";
+export interface WindowAccumulatorConfig {
+    /** Window kind. Defaults to `"tumbling"`. */
+    window?: WindowType;
+    /**
+     * Window width in **milliseconds** (already parsed from any duration
+     * string by the caller). For session windows this is unused; pass
+     * `gap` instead.
+     */
+    size: number;
+    /**
+     * Advance between consecutive hopping windows, in ms. Only meaningful
+     * for `window: "hopping"`; must satisfy `0 < hop ≤ size`. Defaults to
+     * `size`, which makes hopping degenerate to tumbling.
+     */
+    hop?: number;
+    /**
+     * Inactivity gap in ms that closes a session. Only meaningful for
+     * `window: "session"`. Two events within `gap` of each other (in
+     * event-time) share a session; an event bridging two sessions merges
+     * them.
+     */
+    gap?: number;
+    /**
+     * Keep at most this many most-recent windows; older windows are
+     * pruned on push. Bounds memory for an unbounded stream. Defaults to
+     * unbounded (`Infinity`).
+     */
+    retain?: number;
+}
+/** A closed or still-filling aggregation window. */
+export interface AggregatedWindow {
+    /** Inclusive window start (event-time ms). */
+    start: number;
+    /** Exclusive window end (event-time ms). */
+    end: number;
+    /** Number of events in the window. */
+    count: number;
+    mean: number;
+    sum: number;
+    min: number;
+    max: number;
+    /** Population standard deviation. */
+    stddev: number;
+    /**
+     * `true` while the window may still receive events — the trailing,
+     * still-filling window(s) up to the latest watermark. Render these
+     * distinctly (the partial-bin convention) so a viewer doesn't read a
+     * half-filled aggregate as final.
+     */
+    partial: boolean;
+}
+/**
+ * Accumulates event-time windowed statistics. Stateful and mutable —
+ * one instance per streaming series. Pure with respect to event order.
+ */
+export declare class WindowAccumulator {
+    private readonly type;
+    private readonly size;
+    private readonly hop;
+    private readonly gap;
+    private readonly retain;
+    private windows;
+    private sessions;
+    private latest;
+    constructor(config: WindowAccumulatorConfig);
+    /** Incorporate one event. Non-finite time/value are ignored. */
+    push(time: number, value: number): void;
+    private pushFixed;
+    private bump;
+    private pushSession;
+    private prune;
+    /**
+     * Snapshot the current windows as aggregated rows, sorted by start.
+     * For tumbling/hopping a window is `partial` while the watermark has
+     * not yet passed its end; for session windows the most recent session
+     * is `partial` while within `gap` of the watermark.
+     */
+    emit(): AggregatedWindow[];
+    private emitFixed;
+    private emitSessions;
+    private row;
+    /** Number of live windows (or sessions). */
+    get windowCount(): number;
+    /** The watermark — largest event-time seen, or `-Infinity` if empty. */
+    get watermark(): number;
+    clear(): void;
+}
+/**
+ * Pull the primary value for a stat off an aggregated window. `count`
+ * reads the event count; the rest read the matching `RunningStats`
+ * field.
+ */
+export declare function statValue(w: AggregatedWindow, stat: AggregateStat): number;
+/**
+ * Compute the [lower, upper] band bounds for an aggregated window.
+ * `stddev` draws `value ± k·σ` around the chosen stat; `minmax` draws
+ * the observed range. Returns `null` for `none`.
+ */
+export declare function bandBounds(w: AggregatedWindow, band: AggregateBand, stat: AggregateStat, sigma?: number): [number, number] | null;

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

@@ -0,0 +1,12 @@
+/**
+ * Parse a window duration to milliseconds.
+ *
+ * - A finite number is returned as-is (already milliseconds).
+ * - A string is parsed as one or more `<number><unit>` terms summed
+ *   together: `"1m"`, `"500ms"`, `"1m30s"`.
+ *
+ * Returns `null` for unparseable input (empty string, unknown unit,
+ * non-positive result, non-finite number) so callers can fall back to
+ * a default rather than silently bucketing on a zero-width window.
+ */
+export declare function parseWindowDuration(spec: number | string): number | null;

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

@@ -0,0 +1,31 @@
+export interface CustomTooltipEntry {
+    key: string;
+    label: string;
+    value: unknown;
+    formatted: string;
+}
+export interface CustomTooltipEntryOptions {
+    /** Maximum number of rows to return. @default 8 */
+    maxEntries?: number;
+    /** Extra keys to omit in addition to underscore-prefixed internals. */
+    excludeKeys?: readonly string[] | Set<string>;
+    /** Include underscore-prefixed keys. @default false */
+    includeInternal?: boolean;
+    /** Include null, undefined, and empty-string values. @default false */
+    includeEmpty?: boolean;
+    /** Optional display labels by key. */
+    labels?: Record<string, string> | ((key: string) => string);
+    /** Optional value formatter. */
+    valueFormat?: (value: unknown, key: string, datum: Record<string, unknown>) => string;
+}
+/**
+ * Extract the user-facing datum from Semiotic hover/observation payloads.
+ *
+ * Custom charts can surface hover payloads as `hover.datum`,
+ * `hover.datum.data`, `hover.data`, or `hover.data.data` depending on the
+ * frame family and scene node type. This helper normalizes those shapes and
+ * drops internal/function fields so tooltips do not render empty chrome.
+ */
+export declare function extractTooltipDatum(payload: unknown): Record<string, unknown> | null;
+export declare function buildTooltipEntries(payload: unknown, options?: CustomTooltipEntryOptions): CustomTooltipEntry[];
+export declare function formatTooltipValue(value: unknown): string;

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

@@ -0,0 +1,207 @@
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { CustomLayout, LayoutContext } from "../stream/customLayout";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { Style } from "../stream/types";
+import type { BezierPoint } from "../stream/networkTypes";
+export type GofishGlyphMark = {
+    kind: "rect";
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    style?: Style;
+    datum?: Datum;
+    group?: string;
+    interactive?: boolean;
+    rx?: number;
+    /** Clip this mark to an SVG path (pixel coords) — e.g. a fill to a silhouette. */
+    clipPath?: string;
+} | {
+    kind: "image";
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    href: string;
+    /** @default "none" — stretch to the box; "xMidYMid meet" to letterbox. */
+    preserveAspectRatio?: string;
+    opacity?: number;
+    /** Clip the image to an SVG path (pixel coords). */
+    clipPath?: string;
+} | {
+    kind: "circle";
+    id: string;
+    cx: number;
+    cy: number;
+    r: number;
+    style?: Style;
+    datum?: Datum;
+    group?: string;
+    interactive?: boolean;
+} | {
+    kind: "area";
+    id: string;
+    topPath: [number, number][];
+    bottomPath: [number, number][];
+    style?: Style;
+    datum?: Datum[];
+    group?: string;
+} | {
+    kind: "path";
+    id: string;
+    d: string;
+    style?: Style;
+    datum?: Datum;
+    group?: string;
+    clipPath?: string;
+} | {
+    kind: "line";
+    id: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    style?: Style;
+} | {
+    kind: "text";
+    id: string;
+    x: number;
+    y: number;
+    text: ReactNode;
+    style?: Style;
+    fontSize?: number;
+    fontWeight?: number | string;
+    textAnchor?: "start" | "middle" | "end";
+    dominantBaseline?: React.SVGProps<SVGTextElement>["dominantBaseline"];
+    transform?: string;
+};
+export interface GofishGlyphLayer {
+    marks: GofishGlyphMark[];
+    overlays?: ReactNode;
+}
+export interface HitRectForGlyphOptions {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    datum?: Datum;
+    group?: string;
+    style?: Style;
+    rx?: number;
+}
+export type GofishGlyphSolver<C extends object> = (ctx: LayoutContext<C>) => GofishGlyphLayer;
+export declare function hitRectForGlyph(options: HitRectForGlyphOptions): GofishGlyphMark;
+export declare function overlayGroup(children: ReactNode, className?: string): ReactNode;
+/**
+ * Compile a small GoFish-style mark vocabulary to a Semiotic custom layout.
+ *
+ * Rects, circles, and areas become normal scene nodes when interactive is not
+ * false, so Semiotic owns hit testing, transitions, decay, SSR evidence, and
+ * tooltips. Rich glyph chrome such as petal paths, labels, bottle silhouettes,
+ * and arrows is rendered as pointer-events-none SVG overlay content.
+ */
+export declare function createGofishGlyphLayout<C extends object>(solve: GofishGlyphSolver<C>): CustomLayout<C>;
+export interface GofishFlowerConfig {
+    lakeAccessor?: string | ((d: Datum) => string);
+    speciesAccessor?: string | ((d: Datum) => string);
+    countAccessor?: string | ((d: Datum) => number);
+    xAccessor?: string | ((d: Datum) => number);
+    flowerRadius?: number;
+    stemWidth?: number;
+}
+export interface GofishBottleConfig {
+    categoryAccessor?: string | ((d: Datum) => string);
+    amountAccessor?: string | ((d: Datum) => number);
+    bottleWidth?: number;
+    bottleHeight?: number;
+}
+export interface GofishPolarRibbonConfig {
+    lakeAccessor?: string | ((d: Datum) => string);
+    speciesAccessor?: string | ((d: Datum) => string);
+    countAccessor?: string | ((d: Datum) => number);
+    innerRadius?: number;
+    outerRadius?: number;
+}
+export interface GofishTitanicCircleTreemapConfig {
+    classAccessor?: string | ((d: Datum) => string | number);
+    survivedAccessor?: string | ((d: Datum) => string | number | boolean);
+    fareAccessor?: string | ((d: Datum) => number);
+    padding?: number;
+}
+export interface PythonTutorPointer {
+    pointer: number;
+}
+export interface PythonTutorBinding {
+    name: string;
+    value: string | PythonTutorPointer;
+}
+export interface PythonTutorTuple {
+    values: Array<string | PythonTutorPointer>;
+}
+export interface PythonTutorDiagram {
+    stack: PythonTutorBinding[];
+    heap: PythonTutorTuple[];
+    heapArrangement: Array<Array<number | null>>;
+}
+export interface GofishPythonTutorConfig {
+    diagram?: PythonTutorDiagram;
+    cellWidth?: number;
+    cellHeight?: number;
+    heapGap?: number;
+}
+export interface PythonTutorMemoryGraph {
+    nodes: Datum[];
+    edges: Datum[];
+}
+export declare function buildPythonTutorMemoryGraph(diagram: PythonTutorDiagram): PythonTutorMemoryGraph;
+export declare const gofishFlowerLayout: CustomLayout<GofishFlowerConfig>;
+export declare const gofishBottleFillLayout: CustomLayout<GofishBottleConfig>;
+export declare const gofishPolarRibbonLayout: CustomLayout<GofishPolarRibbonConfig>;
+export declare const gofishTitanicCircleTreemapLayout: CustomLayout<GofishTitanicCircleTreemapConfig>;
+export declare const gofishPythonTutorLayout: CustomLayout<GofishPythonTutorConfig>;
+export declare const gofishPythonTutorNetworkLayout: NetworkCustomLayout<GofishPythonTutorConfig>;
+export declare function pointerCurve(start: [number, number], end: [number, number]): {
+    d: string;
+    points: [BezierPoint, BezierPoint, BezierPoint, BezierPoint];
+};
+interface TreemapStripRegion<T> {
+    id: string;
+    rows: T[];
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface PackedCircle<T> {
+    row: T;
+    index: number;
+    x: number;
+    y: number;
+    r: number;
+}
+export declare function layoutTreemapStrip<T>(entries: Array<{
+    id: string;
+    rows: T[];
+    value: number;
+    heightValue?: number;
+}>, bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, gap: number): Array<TreemapStripRegion<T>>;
+export declare function packCirclesInRect<T>(rows: T[], region: TreemapStripRegion<T>, value: (row: T) => number, gap: number): Array<PackedCircle<T>>;
+export declare function datumFromFields(fields: Record<string, unknown>): Datum;
+export declare function stableGlyphId(value: string): string;
+export declare function polarPoint(cx: number, cy: number, r: number, angle: number): [number, number];
+export declare function petalPath(cx: number, cy: number, innerR: number, outerR: number, start: number, end: number): string;
+export declare function polarBandPath(cx: number, cy: number, innerR: number, outerR: number, start: number, end: number): string;
+export declare function smoothClosedPath(points: [number, number][]): string;
+export declare function bottlePath(x: number, y: number, w: number, h: number): string;
+export {};

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

@@ -0,0 +1,23 @@
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+export interface GofishBobaConfig {
+    /** Category — one cup per distinct value. @default "name" */
+    categoryAccessor?: string | ((d: Datum) => string);
+    /** Tea volume (cm³). @default field "teaVolume" → 450 */
+    teaVolumeAccessor?: string | ((d: Datum) => number);
+    /** Tapioca-pearl volume (cm³); pearl count derived from it. @default field "bobaVolume" → 110 */
+    bobaVolumeAccessor?: string | ((d: Datum) => number);
+    /** Ice volume (cm³); cube count derived from it. @default field "iceVolume" → 135 */
+    iceVolumeAccessor?: string | ((d: Datum) => number);
+    /** Cup height (cm). @default field "cupHeight" → 15.5 */
+    cupHeightAccessor?: string | ((d: Datum) => number);
+    /** Cup top radius (cm). @default field "cupTopRadius" → 4.75 */
+    cupTopRadiusAccessor?: string | ((d: Datum) => number);
+    /** Cup bottom radius (cm). @default field "cupBottomRadius" → 3.75 */
+    cupBottomRadiusAccessor?: string | ((d: Datum) => number);
+    /** Pearl radius (cm). @default field "bobaRadius" → 0.6 */
+    bobaRadiusAccessor?: string | ((d: Datum) => number);
+    /** Fraction of each band the cup glyph may occupy. @default 0.82 */
+    cupWidthRatio?: number;
+}
+export declare const gofishBobaLayout: OrdinalCustomLayout<GofishBobaConfig>;

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

@@ -0,0 +1,169 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { CustomLayout } from "../stream/customLayout";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { GofishLambda } from "./gofishLambdas";
+/**
+ * Experimental GoFish Frontend IR → Semiotic custom-layout adapter.
+ *
+ * This is the GoFish analogue of `fromVegaLite`. Where `fromVegaLite` maps a
+ * Vega-Lite spec onto a built-in HOC component + props, `unstable_fromGofishIR` maps a
+ * GoFish *Frontend IR* document (the JSON artifact GoFish's `to_ir` /
+ * serialization frontend emits — see the `gofish-ir` package) onto Semiotic's
+ * custom-layout surface.
+ *
+ * Unlike a recognizer, this *interprets* the spec: `unstable_fromGofishIR` picks a
+ * frame family, then hands the IR to `interpretGofishIR` (see
+ * `gofishInterpreter.ts`), which walks `data → operators → mark` and executes
+ * `group`/`spread`/`stack`/`scatter`/`treemap`/`layer`, the `polar`/`unit`
+ * coordinate transforms, mark channels through scales, and `connect`/`ref`/
+ * `arrow` relations. The two sanctioned non-grammar paths — `derive` and
+ * `mark-fn` — resolve through the lambda registry. Any spec built from the
+ * supported grammar renders; it is not limited to known archetypes.
+ *
+ * Frame family (hybrid): `arrow`/pointer specs → network; the boba volume
+ * signature → ordinal (Semiotic owns the category axis, the interpreter owns
+ * the within-cup composition); everything else → XY. The Python Tutor memory
+ * diagram is a genuinely bespoke diagram beyond the grammar, so it stays a
+ * chart-level escape hatch rendered by `gofishPythonTutorNetworkLayout`.
+ *
+ * Scope: GoFish Frontend IR v0. This is a PR-preview adapter named
+ * `unstable-gofish-ir-adapter`, not a release API commitment. Constructs outside the interpreter's
+ * allocation model (`table`, `cut`, `mask`, free-form `.constrain`, …) record
+ * a warning and fall back rather than silently mis-rendering.
+ */
+export declare const EXPERIMENTAL_GOFISH_ADAPTER_NAME = "unstable-gofish-ir-adapter";
+/** Explicit field-accessor channel form, emitted by `field(name)`. */
+export interface GofishFieldAccessor {
+    type: "field";
+    name: string;
+    measure?: string;
+}
+/** A data-driven channel value, emitted by `datum(v)` / `v(...)`. */
+export interface GofishDatumValue {
+    type: "datum";
+    datum?: unknown;
+    offset?: number;
+    [key: string]: unknown;
+}
+/** The right-hand side of a mark or operator channel (`h: …`, `fill: …`). */
+export type GofishChannelValue = string | number | boolean | null | GofishFieldAccessor | GofishDatumValue | {
+    __gofish_lambda: string;
+};
+export interface GofishOperatorIR {
+    type: string;
+    by?: string;
+    dir?: "x" | "y";
+    x?: GofishChannelValue;
+    y?: GofishChannelValue;
+    spacing?: number | [number, number];
+    [key: string]: unknown;
+}
+export interface GofishMarkIR {
+    type: string;
+    __combinator?: true;
+    children?: GofishMarkIR[];
+    source?: GofishMarkIR;
+    options?: Record<string, unknown>;
+    origin?: {
+        name?: string;
+    };
+    name?: string;
+    [key: string]: unknown;
+}
+export interface GofishChartIR {
+    type: "chart";
+    data?: GofishDataIR | null;
+    operators?: GofishOperatorIR[];
+    mark: GofishMarkIR;
+    options?: Record<string, unknown>;
+    connect?: GofishMarkIR;
+    name?: string;
+}
+export interface GofishLayerIR {
+    type: "layer";
+    charts: GofishChartIR[];
+    options?: Record<string, unknown>;
+}
+export interface GofishRawMarkIR {
+    type: "raw-mark";
+    mark: GofishMarkIR;
+    options?: Record<string, unknown>;
+}
+export type GofishDataIR = {
+    type: "inline";
+    rows: Array<Record<string, unknown>>;
+} | {
+    type: "select";
+    layer: string;
+    mode?: "one" | "all";
+} | {
+    type: "external";
+    id?: string;
+};
+export type GofishRootIR = GofishChartIR | GofishLayerIR | GofishRawMarkIR;
+export interface GofishIRDocument {
+    irVersion: number;
+    ir: string;
+    $schema?: string;
+    root: GofishRootIR;
+}
+export type GofishChartFamily = "xy" | "network" | "ordinal";
+export type GofishRecipeName = 
+/** XY / ordinal charts are produced by the IR interpreter, not a named recipe. */
+"gofishInterpreter"
+/** The Python Tutor memory diagram is a bespoke network glyph (chart-level escape hatch). */
+ | "gofishPythonTutorNetworkLayout";
+/**
+ * The translated chart, spreadable into `XYCustomChart` / `NetworkCustomChart`.
+ * Mirrors `fromVegaLite`'s `{ component, props, warnings }` for the
+ * custom-layout surface.
+ */
+export interface GofishChartConfig {
+    family: GofishChartFamily;
+    /** Which `gofish.tsx` recipe the IR resolved to. */
+    recipe: GofishRecipeName;
+    /** Layout function to pass as `layout` on `XYCustomChart` — null otherwise. */
+    layout: CustomLayout<Record<string, unknown>> | null;
+    /** Layout function to pass as `layout` on `NetworkCustomChart` — null otherwise. */
+    networkLayout: NetworkCustomLayout<Record<string, unknown>> | null;
+    /** Layout function to pass as `layout` on `OrdinalCustomChart` — null otherwise. */
+    ordinalLayout: OrdinalCustomLayout<Record<string, unknown>> | null;
+    /** Accessor config derived from the IR; pass as `layoutConfig`. */
+    layoutConfig: Record<string, unknown>;
+    /** Category accessor for ordinal charts (the frame builds the o-scale from it). */
+    categoryAccessor?: string;
+    /** Value accessor for ordinal charts (the frame builds the r-scale from it). */
+    valueAccessor?: string;
+    /** Inline data to seed the chart (`data` / `pushMany`). Empty for network. */
+    data: Datum[];
+    /** Node/edge graph for `NetworkCustomChart` (memory diagram only). */
+    graph: {
+        nodes: Datum[];
+        edges: Datum[];
+    } | null;
+    irVersion: number;
+    warnings?: string[];
+}
+export interface FromGofishIROptions {
+    /** Force a frame family instead of inferring it. */
+    family?: GofishChartFamily;
+    /** Per-call `derive`/`mark-fn` lambda overrides (merged over the registry). */
+    lambdas?: Record<string, GofishLambda>;
+}
+/**
+ * Translate a GoFish Frontend IR document into a Semiotic custom-layout config
+ * by *interpreting* the spec.
+ *
+ * @example
+ * ```tsx
+ * import { unstable_fromGofishIR } from "semiotic/experimental"
+ * import { XYCustomChart } from "semiotic/xy"
+ *
+ * const cfg = unstable_fromGofishIR(flowerIR)
+ * <XYCustomChart data={cfg.data} layout={cfg.layout} />
+ * ```
+ */
+export declare function unstable_fromGofishIR(doc: GofishIRDocument, options?: FromGofishIROptions): GofishChartConfig;
+/** @deprecated Internal compatibility alias for the temporary GoFish PR preview. */
+export declare const fromGofishIR: typeof unstable_fromGofishIR;

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

@@ -0,0 +1,89 @@
+import type { GofishIRDocument } from "./gofishIR";
+/** The Python Tutor heap/stack snapshot, inlined as a single IR data row. */
+export declare const pythonTutorDiagramRow: {
+    kind: string;
+    stack: ({
+        name: string;
+        value: {
+            pointer: number;
+        };
+    } | {
+        name: string;
+        value: string;
+    })[];
+    heap: {
+        values: (string | {
+            pointer: number;
+        })[];
+    }[];
+    heapArrangement: (number | null)[][];
+};
+/**
+ * Deterministic Titanic passenger sample (no RNG), mirroring the docs page so
+ * the IR document is self-contained. Kept modest per class so the inline rows
+ * stay reasonable to ship and display.
+ */
+export declare function buildTitanicSampleRows(): Array<Record<string, unknown>>;
+/**
+ * A meadow: one green stem per lake (a `scatter` placing each lake's bar at its
+ * x), topped by a polar fan of species petals. Single-chart form so the
+ * interpreter renders it directly: `scatter(by:lake)` → per lake a `layer` of
+ * a stem `rect` (height = summed catch) and a `polar` `stack` of `petal`s
+ * around the angle axis.
+ */
+export declare const flowerIR: GofishIRDocument;
+/**
+ * A row of pictorial bottles, one per category, each filled to its `amount`
+ * percentage. Grammar-first with one `derive`: `bottleGeometry` emits the
+ * per-bottle normalized geometry under `_b`; the marks render it with the
+ * reusable `image` + clip primitives — an `image` of the bottle silhouette, a
+ * green fill `rect` clipped to that silhouette, a fill line, a percentage
+ * label, a category label, and a transparent hit rect carrying the datum.
+ */
+export declare const bottleIR: GofishIRDocument;
+/**
+ * Stacked species bars laid out radially per lake (polar coord), with one
+ * cross-lake ribbon per species connecting the matching segments.
+ */
+export declare const polarRibbonIR: GofishIRDocument;
+/**
+ * A bar chart that's treemap-filled and circle-filled: a `spread` lays one
+ * equal-width bar per passenger class whose HEIGHT encodes the class's total
+ * fare (`sizeBy`), and that bar rectangle becomes a squarified `treemap` of its
+ * passengers — every fare-sized cell rendered as an inscribed circle coloured
+ * by survival.
+ */
+export declare const titanicCircleTreemapIR: GofishIRDocument;
+/**
+ * A Python Tutor runtime memory diagram: a global frame of variable bindings
+ * whose pointers arrow into a heap of linked tuples. Encoded as a `layer` of a
+ * `spread` (frame + heap) plus `arrow` connectors over `ref`s; the snapshot
+ * itself travels as a single inline data row consumed by the network recipe.
+ */
+export declare const pythonMemoryIR: GofishIRDocument;
+/**
+ * A boba-shop menu: four bubble-tea drinks spread along the category axis, each
+ * fully data-driven. Per drink, the tea + tapioca + ice volumes (plus the
+ * cup-size parameters) add up to a total volume that determines the drink
+ * height; the pearls stack at the bottom and the ice floats at the surface — so
+ * "Extra Boba" grows a taller pearl bed, "Light Ice" reads as mostly tea, and
+ * "Mega" is a bigger cup of everything.
+ *
+ * Grammar-first, per the "follow the spec as far as it can" rule: the cup, tea,
+ * straw, and lid are real `polygon`/`line` marks and the pearls/ice are real
+ * `circle`/`rect` marks. The one genuinely non-grammar step — the
+ * frustum-volume → drink-height solve and tapioca/ice packing — lives in a
+ * single `derive` lambda (`bobaGeometry`) that emits each cup's geometry the
+ * marks read (`_g.*`) plus a shared `_g.box` aspect for the `uniform` unit fit,
+ * so the cups sit on one shelf with aligned straws. Derived from Krist
+ * Wongsuphasawat's "Boba Science" notebook. Routed to the ordinal frame.
+ */
+export declare const bobaIR: GofishIRDocument;
+export interface GofishIRExample {
+    key: "flower" | "bottle" | "polar" | "titanic" | "python" | "boba";
+    label: string;
+    doc: GofishIRDocument;
+    source: string;
+}
+/** All five examples, in gallery order. */
+export declare const gofishIRExamples: readonly GofishIRExample[];