@mettascript/grapher 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,815 @@
+import { Atom, MeTTa } from '@mettascript/hyperon';
+
+/** A node's role in the s-expression:
+ *  - `symbol`: a named atom. With children it is `(name child...)`; without, a bare symbol/variable/value.
+ *  - `list`: a headless expression `(child...)`.
+ *  - `dot`: a build-time passthrough (a single child composes to that child). */
+type NodeKind = "symbol" | "list" | "dot";
+/** One node: its identity, its text, its role, and its position on the canvas. */
+interface GraphNode {
+    id: string;
+    name: string;
+    kind: NodeKind;
+    x: number;
+    y: number;
+}
+/** A cycle-guarded DAG of {@link GraphNode}s with parent/child edges. */
+declare class Graph {
+    readonly nodes: Map<string, GraphNode>;
+    private readonly childIds;
+    private readonly parentIds;
+    /** Add a node. An explicit `id` is preserved (for loading); otherwise a fresh one is minted. Defaults:
+     *  kind `symbol`, position `(0, 0)`. */
+    add(spec: {
+        name: string;
+        kind?: NodeKind;
+        x?: number;
+        y?: number;
+        id?: string;
+    }): GraphNode;
+    /** Remove a node and every edge touching it. */
+    remove(id: string): void;
+    /** Move a node to a new position. */
+    move(id: string, x: number, y: number): void;
+    /** This node's child ids, in insertion order. */
+    childrenOf(id: string): string[];
+    /** This node's parent ids, in insertion order. */
+    parentsOf(id: string): string[];
+    /** Whether `parent -> child` would be a legal edge: not a self-loop, a duplicate, an unknown node, or a
+     *  cycle (the parent already sitting below the child). Lets the editor reject a drag before committing it. */
+    canConnect(parentId: string, childId: string): boolean;
+    /** Connect `parent` to `child`. Returns false and does nothing when the edge would be illegal (see
+     *  {@link canConnect}). */
+    connect(parentId: string, childId: string): boolean;
+    /** Remove the `parent -> child` edge if present. */
+    disconnect(parentId: string, childId: string): void;
+    /** Children of `id` in screen order: by x, ties (within {@link X_EPSILON}) broken by y. This is how
+     *  argument order is read off the canvas. */
+    sortedChildren(id: string): GraphNode[];
+    /** The roots (parentless nodes) reachable by walking up from `id`. A parentless node is its own head. */
+    findHeads(id: string): GraphNode[];
+    /** Every root in the graph (nodes with no parents). */
+    heads(): GraphNode[];
+    /** A deep copy: same node ids, positions, and edges. */
+    clone(): Graph;
+    /** Can `from` reach `to` by following child edges downward? */
+    private reaches;
+}
+
+/** A pan offset and a scale. Screen = world * scale + pan. */
+interface Viewport {
+    panX: number;
+    panY: number;
+    scale: number;
+}
+/** The identity viewport (no pan, unit scale). */
+declare function initialViewport(): Viewport;
+/** Screen point to world point. */
+declare function toWorld(v: Viewport, sx: number, sy: number): {
+    x: number;
+    y: number;
+};
+/** World point to screen point. */
+declare function toScreen(v: Viewport, wx: number, wy: number): {
+    x: number;
+    y: number;
+};
+/** Pan by a screen-space delta. */
+declare function pan(v: Viewport, dx: number, dy: number): Viewport;
+/** Scale by `factor` while keeping the world point under screen `(sx, sy)` fixed (zoom toward cursor). */
+declare function zoomAt(v: Viewport, sx: number, sy: number, factor: number): Viewport;
+
+/** A per-node evaluation label to show beneath it. */
+interface NodeLabel {
+    text: string;
+    error: boolean;
+}
+/** A per-node overlay from a MeTTa `&grapher` directive: a fill color, a highlight ring, a label, and a size
+ *  scale (1 = default). */
+interface NodeViz {
+    color?: string;
+    highlight?: boolean;
+    label?: string;
+    sizeScale?: number;
+}
+/** Everything the renderer needs for one frame. */
+interface RenderState {
+    graph: Graph;
+    viewport: Viewport;
+    selection: ReadonlySet<string>;
+    labels: ReadonlyMap<string, NodeLabel>;
+    primaryId: string | null;
+    viz: ReadonlyMap<string, NodeViz>;
+}
+/** Renders a graph into an <svg> and keeps a handle to the viewport group for pan and zoom. */
+declare class Renderer {
+    readonly svg: SVGSVGElement;
+    private readonly viewportG;
+    private readonly haloG;
+    private readonly edgesG;
+    private readonly mergeG;
+    private readonly nodesG;
+    private tracePrev;
+    private traceRaf;
+    private traceDuration;
+    private bg;
+    constructor(container: HTMLElement);
+    /** Set the canvas background. The redex glow re-reads it, so its contrast stays right under any theme. */
+    setBackground(bg: string): void;
+    /** Set how long a step's morph takes (ms), so playback speed slows the animation, not just the pauses. */
+    setTraceDuration(ms: number): void;
+    /** Redraw the whole frame. */
+    render(state: RenderState): void;
+    /** Forget the last playthrough frame, so the next one starts without gliding from a stale step. */
+    clearTrace(): void;
+    /** Show one reduction step. With `animate` and a previous step, shared subterms arc from their old place
+     *  to their new one, the parts that appear or vanish fade, and the viewport eases, the way a math
+     *  animation morphs one expression into the next. Otherwise it paints at once. */
+    showTrace(state: RenderState, animate: boolean): void;
+    /** Paint an interpolated frame between two steps. The interpolation itself is pure ({@link
+     *  interpolateTrace}); this just draws the result. */
+    private paintTrace;
+    /** Faint dashed links between the occurrences of each variable within a rule. */
+    private varNet;
+    private edges;
+    private nodeGroups;
+}
+
+/** The state and operations the controller drives. The host (the editor) owns everything persistent. */
+interface ControllerHost {
+    svg: SVGSVGElement;
+    container: HTMLElement;
+    graph: Graph;
+    viewport: Viewport;
+    selection: Set<string>;
+    primaryId: string | null;
+    /** Left-drag on empty canvas pans instead of rubber-band selecting. Host configuration, fixed for the
+     *  host's lifetime, unlike {@link isTracing} which changes as a playthrough runs. */
+    readonly panOnLeftDrag: boolean;
+    render(): void;
+    changed(): void;
+    evaluate(nodeId: string): void;
+    completions(prefix: string): string[];
+    isTracing(): boolean;
+}
+/** Attaches to the host's svg on construction; call {@link destroy} to detach. */
+declare class Controller {
+    private readonly host;
+    private mode;
+    private lastScreen;
+    private connectFrom;
+    private rubberStart;
+    private spaceHeld;
+    private clip;
+    private readonly overlay;
+    private input;
+    private menu;
+    private createAt;
+    private highlight;
+    private readonly onDown;
+    private readonly onMove;
+    private readonly onUp;
+    private readonly onWheel;
+    private readonly onDblClick;
+    private readonly onKeyDown;
+    private readonly onKeyUp;
+    private readonly onContext;
+    constructor(host: ControllerHost);
+    /** Detach every listener and remove transient UI. */
+    destroy(): void;
+    private screenOf;
+    private worldOf;
+    private nodeIdAt;
+    private pointerDown;
+    private pointerMove;
+    private pointerUp;
+    private wheel;
+    private dblClick;
+    private selectOnly;
+    private toggle;
+    private clearSelection;
+    private selectInRubber;
+    private drawRubber;
+    private drawConnectLine;
+    private toScreen;
+    private keyDown;
+    private keyUp;
+    private copy;
+    private paste;
+    private openInput;
+    private inputKey;
+    private commit;
+    private updateMenu;
+    private renderMenu;
+    private closeInput;
+}
+
+/** A serialized graph: every node with its position, and every `[parent, child]` edge in order. */
+interface GraphJson {
+    nodes: GraphNode[];
+    edges: [string, string][];
+}
+/** Snapshot a graph to JSON. */
+declare function toJson(graph: Graph): GraphJson;
+/** Rebuild a graph from JSON, preserving ids, positions, and edge order. */
+declare function fromJson(json: GraphJson): Graph;
+/** Render a graph as MeTTa source, one head per line. */
+declare function toSource(graph: Graph): string;
+/** Parse MeTTa source into a laid-out graph. */
+declare function fromSource(src: string): Graph;
+
+/** One self-contained SVG animation frame and its display time. */
+interface SvgFrame {
+    svg: string;
+    delay: number;
+}
+/** SVG frames with one fixed output size and background. */
+interface SvgAnimation {
+    frames: SvgFrame[];
+    width: number;
+    height: number;
+    background: string;
+}
+/** Convert one SVG frame to width * height * 4 RGBA bytes. */
+type SvgRasterizer = (svg: string, width: number, height: number, background: string) => Promise<Uint8Array | Uint8ClampedArray>;
+/** Encode SVG frames with a caller-supplied rasterizer and gifenc-compatible encoder. */
+declare function encodeSvgAnimation(animation: SvgAnimation, rasterize: SvgRasterizer, lib: GifEncoderLib, maxColors?: number): Promise<Uint8Array>;
+
+/** The colors of the block view. */
+interface BlockPalette {
+    canvas: string;
+    bkgColor: string;
+    backgroundBlockColor: string;
+    outlineBlockColor: string;
+    formColor: string;
+    identifierColor: string;
+    literalColor: string;
+    stringColor: string;
+    operatorColor: string;
+    spacerefColor: string;
+    atColor: string;
+    holeFill: string;
+    holeSide: string;
+    holeText: string;
+    selectedColor: string;
+    selectedAtomColor: string;
+}
+/** Colors and sizes for one render, all in pixels. */
+interface BlockSettings extends BlockPalette {
+    fontSize: number;
+    /** Advance width of one monospace character; measured by the renderer. */
+    unitWidth: number;
+    /** Row height; a glyph is centered within it. */
+    unitHeight: number;
+    /** Block corner radius. */
+    radius: number;
+    /** Atom and hole backing radius (smaller than the block radius). */
+    radiusAdj: number;
+    /** Below this many characters of children, a block stays on one line even if it is a stacking form. */
+    cutoff: number;
+}
+/** The site's own syntax palette (GitHub dark), so a block program matches the code blocks around it:
+ *  variables and space-refs orange, numbers blue, strings light blue, control operators red, at-atoms
+ *  purple, everything else the neutral light text. Nesting is shown by two dark surfaces and a lighter
+ *  outline, on the same dark canvas as the node graph. */
+declare const SITE_PALETTE: BlockPalette;
+/** A plain teal scheme. */
+declare const TEAL_PALETTE: BlockPalette;
+/** The character-count cutoff below which a stacking form stays on one line. */
+declare const CUTOFF = 14;
+/** Build settings from a font size, the measured monospace advance, and a palette (the site's by
+ *  default). */
+declare function makeSettings(fontSize: number, unitWidth: number, palette?: BlockPalette): BlockSettings;
+
+/** One vertex of a pulled-point polygon: the point, plus the incoming (l) and outgoing (r) Bezier pulls
+ *  and angles (degrees). */
+interface PulledPoint {
+    lpull: number;
+    langle: number;
+    x: number;
+    y: number;
+    rpull: number;
+    rangle: number;
+}
+/** A row of a backing profile: `x` is the edge (right edge for the right profile, left edge for the left)
+ *  and `h` is the row height. */
+interface ProfileRow {
+    x: number;
+    h: number;
+}
+/** Build an SVG path from a closed loop of pulled points: one cubic Bezier per edge, wrapping the last
+ *  point back to the first. */
+declare function pulledPointsToPath(points: readonly PulledPoint[]): string;
+/** A rounded rectangle path. */
+declare function roundedRectPath(width: number, height: number, r: number): string;
+/** A rounded backing path from its right and left row profiles. */
+declare function roundedBackingPath(rightProfile: readonly ProfileRow[], leftProfile: readonly ProfileRow[], r: number, headerException: boolean): string;
+
+/** A leaf glyph. */
+interface AtomBox {
+    kind: "atom";
+    path: number[];
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    depth: number;
+    text: string;
+    color: string;
+}
+/** A variable, drawn as a hole with its name inside. */
+interface HoleBox {
+    kind: "hole";
+    path: number[];
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    depth: number;
+    text: string;
+}
+/** A block: a form drawn as a backing with its head glyph and child boxes inside. */
+interface ExprBox {
+    kind: "expr";
+    path: number[];
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    depth: number;
+    orient: "h" | "v";
+    fill: string;
+    outline: string;
+    headerException: boolean;
+    children: BlockBox[];
+    rightProfile: ProfileRow[];
+    leftProfile: ProfileRow[];
+}
+type BlockBox = AtomBox | HoleBox | ExprBox;
+/** Lay out one atom as a block tree rooted at the origin. */
+declare function layoutAtom(atom: Atom, s: BlockSettings, path?: number[]): BlockBox;
+/** Lay out a whole program: one block per head, stacked down the canvas with a gap between them. Each
+ *  head keeps its index as its root path so a reduction can be spliced back into the right head. */
+declare function placeProgram(atoms: readonly Atom[], s: BlockSettings): BlockBox[];
+
+/** The slice of the `gifenc` module this needs. Pass `await import("gifenc")` (or `import * as`) here. */
+interface GifEncoderLib {
+    GIFEncoder: () => {
+        writeFrame: (index: Uint8Array, width: number, height: number, opts: {
+            palette: number[][];
+            delay: number;
+        }) => void;
+        finish: () => void;
+        bytes: () => Uint8Array;
+    };
+    quantize: (rgba: Uint8Array | Uint8ClampedArray, maxColors: number) => number[][];
+    applyPalette: (rgba: Uint8Array | Uint8ClampedArray, palette: number[][]) => Uint8Array;
+}
+/** How to render the GIF. */
+interface GifOptions {
+    /** Output width in pixels (height follows the aspect ratio). Default 720. */
+    width?: number;
+    /** Morph frames per reduction step. Default `morphMs / stepMs`, reduced to keep under `maxFrames`. */
+    framesPerStep?: number;
+    /** Cap on the total number of frames. Default 180. */
+    maxFrames?: number;
+    /** Milliseconds to hold each settled state. Default 260. */
+    holdMs?: number;
+    /** Milliseconds per morph frame. Default 40. */
+    stepMs?: number;
+    /** Milliseconds one step's morph spans, the live view's trace duration. Sets the default frame count
+     *  per step so the export glides exactly like the screen; an explicit `framesPerStep` wins. The editor
+     *  export methods fill this in with their current trace duration. Default 550 (`DEFAULT_TRACE_MS`). */
+    morphMs?: number;
+    /** Canvas background color. Used by the graph GIF, which has no block palette to take it from. */
+    background?: string;
+}
+/** Encode a sequence of reduction states into an animated GIF, morphing between them. Each state is a
+ *  frontier (one or more terms), so a nondeterministic step shows every branch. */
+declare function reductionGif(states: readonly Atom[][], s: BlockSettings, lib: GifEncoderLib, opts?: GifOptions): Promise<Blob>;
+
+/** A per-node visual overlay set by MeTTa directives in the `&grapher` space. */
+interface VizOverlay {
+    color?: string;
+    highlight?: boolean;
+    label?: string;
+    sizeScale?: number;
+}
+/** Options for {@link MeTTaGrapher}: bring your own engine (to share a space) and an initial program. */
+interface GrapherOptions {
+    metta?: MeTTa;
+    source?: string;
+    /** Left-drag on empty canvas pans instead of rubber-band selecting. For a host that gives the canvas its
+     *  own panel rather than embedding it in a scrolling article, where panning is the gesture a reader
+     *  reaches for first. Shift-drag still rubber-bands, so box-select stays available. Off by default. */
+    panOnLeftDrag?: boolean;
+}
+/** A visual MeTTa editor mounted in a DOM element. */
+declare class MeTTaGrapher implements ControllerHost {
+    readonly container: HTMLElement;
+    readonly metta: MeTTa;
+    /** Whether a left-drag on empty canvas pans (part of {@link ControllerHost}). */
+    readonly panOnLeftDrag: boolean;
+    graph: Graph;
+    viewport: Viewport;
+    readonly selection: Set<string>;
+    primaryId: string | null;
+    readonly labels: Map<string, NodeLabel>;
+    /** Per-node overlays (color, highlight, label) driven by MeTTa directives in the `&grapher` space. */
+    readonly viz: Map<string, VizOverlay>;
+    private readonly vizFocus;
+    private vizBound;
+    /** The `&grapher` directives from the last loaded source, kept so `toSource` can round-trip them under a
+     *  comment even though they are not drawn as nodes. */
+    private vizDirectives;
+    private readonly renderer;
+    private readonly controller;
+    private readonly changeCbs;
+    private readonly sharedSpace;
+    private program;
+    private programDirty;
+    private trace;
+    private traceIndex;
+    private traceGraph;
+    /** Which view is showing: the node graph, or the nested-block ("block") view. */
+    viewMode: "graph" | "block";
+    private readonly block;
+    /** The rendered SVG element (part of {@link ControllerHost}). */
+    get svg(): SVGSVGElement;
+    constructor(container: HTMLElement, opts?: GrapherOptions);
+    /** The space to evaluate against. A provided engine is used as-is (a shared, persistent space);
+     *  otherwise the whole canvas is loaded into a fresh space so its rules and facts are active, rebuilt
+     *  lazily when the graph has changed. */
+    private evalSpace;
+    /** Redraw from the current state. During a playthrough the reduction graph is shown, without the
+     *  editing selection or evaluation labels. */
+    render(): void;
+    /** The render state for a playthrough step: the reduction graph, without editing chrome. */
+    private traceState;
+    /** Notify onChange subscribers that the graph changed. */
+    changed(): void;
+    /** Completion candidates for the node-creation input, including the program's own defined symbols. */
+    completions(prefix: string): string[];
+    /** Evaluate every head the node belongs to and label each with its result. */
+    evaluate(nodeId: string): void;
+    /** Evaluate every head in the graph. */
+    evaluateAll(): void;
+    /** Read the `&grapher` space's directives and turn them into per-node overlays and a focus set. */
+    private applyViz;
+    private mergeViz;
+    /** Apply one `(shade-by FUNC)` / `(size-by FUNC)` mapper: value each node by evaluating `(FUNC node)`, then
+     *  normalize the values across the graph and colour or size the nodes that produced a number. */
+    private applyMapper;
+    /** The nodes a directive target names: by node name, else by the atom the node composes to. Nodes that
+     *  are part of a `&grapher` directive expression are skipped, so `(color (fact 5) red)` colors the query
+     *  node and not the `(fact 5)` written inside the directive itself. */
+    private matchNodes;
+    /** Every node inside a head that operates on `&grapher` (`(add-atom &grapher …)` and friends): the
+     *  directives' own plumbing, which should not be matched or colored. */
+    private directiveNodeIds;
+    /** Frame the focused nodes (graph view), if any directive asked to focus. */
+    private focusViz;
+    /** Evaluate one head and store its result label, unless the head is inert: a definition `(= ...)` or any
+     *  atom that reduces to itself (a fact, a type declaration). Only genuine queries get a label. */
+    private labelHead;
+    /** Load a graph from JSON. */
+    load(json: GraphJson): void;
+    /** Load a graph by parsing MeTTa source. A top-level `(style ...)` block, and any explicit `(add-atom
+     *  &grapher ...)`, are the stylesheet, not content: their directives are run into the isolated `&grapher`
+     *  space, kept out of the drawn graph, and their overlays painted onto the content. */
+    loadSource(src: string): void;
+    /** Load a program from atoms (for example built with the eDSL), laid out as tidy trees. */
+    loadAtoms(atoms: readonly Atom[]): void;
+    /** Recolor the block view with a different palette. */
+    setBlockPalette(palette: BlockPalette): void;
+    /** Snapshot the graph to JSON. */
+    save(): GraphJson;
+    /** Render the graph as MeTTa source. */
+    toSource(): string;
+    /** Compose the graph's heads into atoms. */
+    atoms(): Atom[];
+    /** Re-run the tidy tree layout, frame the result, and redraw. */
+    tidy(): void;
+    /** Zoom around the canvas center by `factor` (above 1 zooms in, below 1 zooms out). Works in both views. */
+    zoomBy(factor: number): void;
+    /** Pan the view by a screen-space delta (for on-screen pan controls). Works in both views. */
+    panBy(dx: number, dy: number): void;
+    /** Frame the whole program: reset the block view's zoom/pan, or fit the graph. */
+    fitView(padding?: number): void;
+    /** The viewport that frames `graph` in the container, or null when it has no nodes. */
+    private fitViewportFor;
+    /** Start a step-by-step reduction playthrough of a head (the given node, or the current query target).
+     *  While tracing, the canvas shows each reduction state; step with {@link traceForward} /
+     *  {@link traceBack} and leave with {@link stopTrace}. */
+    playTrace(nodeId?: string): void;
+    /** The live morph span, mirrored here so the GIF exporters pace their frames off what the screen plays. */
+    private traceMs;
+    /** How long each step's morph takes (ms). Lower it to speed the animation up, raise it to slow it down so
+     *  the reduction is easy to follow. The GIF exporters default to the same span. */
+    setTraceDuration(ms: number): void;
+    /** Advance the playthrough by one reduction. */
+    traceForward(): void;
+    /** Step the playthrough back one reduction. */
+    traceBack(): void;
+    /** Jump the playthrough back to the first state, to replay it from the start. */
+    traceRestart(): void;
+    /** Leave the playthrough and return to the editable graph (or interactive blocks). */
+    stopTrace(): void;
+    /** Whether a playthrough is active (part of {@link ControllerHost}, which pauses editing while true). */
+    isTracing(): boolean;
+    /** The current playthrough position (0-based step and total states), or null when not tracing. */
+    traceInfo(): {
+        index: number;
+        total: number;
+    } | null;
+    /** A snapshot of the whole view state for the host UI. The editor is the single source of truth: the
+     *  host reads this (and subscribes with {@link onViewChange}) instead of tracking which view is showing
+     *  or whether a playthrough is active on its own, so the two can never disagree. */
+    uiState(): {
+        viewMode: "graph" | "block";
+        tracing: {
+            index: number;
+            total: number;
+        } | null;
+        blockCanBack: boolean;
+    };
+    private showTraceStep;
+    /** Switch between the node-graph view and the nested-block view. */
+    setViewMode(mode: "graph" | "block"): void;
+    /** Reduce the block view's selected term one step in place. */
+    blockReduce(): boolean;
+    /** Step the block view back to before its last in-place reduction. */
+    blockBack(): boolean;
+    /** Whether the block view can step back. */
+    blockCanStepBack(): boolean;
+    /** The block view's program as source, reflecting its edits and reductions. */
+    blockSource(): string;
+    /** The reduction states to animate for a GIF: the active playthrough's if one is running, else those
+     *  computed for the last query. Null when there is nothing (no target, or fewer than two states). */
+    private traceStates;
+    /** Encode the current query's reduction as an animated GIF of the block view, using a caller-supplied
+     *  encoder (gifenc) so the package carries no GIF dependency. The morph pacing defaults to the live
+     *  trace duration, so the GIF plays what the screen plays. Returns null when there is no reduction. */
+    exportReductionGif(lib: GifEncoderLib, opts?: GifOptions): Promise<Blob | null>;
+    /** Encode the current reduction as a GIF of the node-graph view alone (companion to the block GIF; stack
+     *  the two to show both). Paced like the live view. Returns null when there is nothing to animate. */
+    exportGraphReductionGif(lib: GifEncoderLib, opts?: GifOptions): Promise<Blob | null>;
+    /** Export the current reduction as one GIF that plays it in the graph and the block views side by side.
+     *  Paced like the live view. Returns null when there is nothing to animate. */
+    exportSideBySideGif(lib: GifEncoderLib, opts?: GifOptions): Promise<Blob | null>;
+    private readonly blockCbs;
+    /** Subscribe to block-view changes (an edit or reduction); returns an unsubscribe function. */
+    onBlockChange(cb: () => void): () => void;
+    private notifyBlock;
+    private readonly viewCbs;
+    /** Subscribe to view-state changes: a view switch or any playthrough transition. The host reads
+     *  {@link uiState} in the callback. Returns an unsubscribe function. */
+    onViewChange(cb: () => void): () => void;
+    private notifyView;
+    /** The head to trace: the selected node's head, else the last query head (not a `=`/`:` definition). */
+    private traceTarget;
+    /** Subscribe to graph changes; returns an unsubscribe function. */
+    onChange(cb: (graph: Graph) => void): () => void;
+    /** Detach listeners and remove the SVG. */
+    destroy(): void;
+    private afterLoad;
+}
+
+/** The space the editor watches for directives. */
+declare const VIZ_SPACE = "&grapher";
+/** A parsed directive read from the grapher space. */
+interface VizDirective {
+    kind: "color" | "highlight" | "focus" | "label" | "size" | "shade";
+    /** The term (or symbol) the directive points at. */
+    target: Atom;
+    /** A color for `color`, or the text for `label`. */
+    arg?: Atom;
+    /** The number for `size` (a relative scale) and `shade` (a value mapped to a heat color). */
+    value?: number;
+}
+/** A data-driven style rule from `(shade-by FUNC)` or `(size-by FUNC)`: colour or size every node by
+ *  evaluating `(FUNC node)` and normalizing the results across the graph, the way a Cytoscape stylesheet maps
+ *  a data field to a visual property. */
+interface VizMapper {
+    property: "shade" | "size";
+    /** The function applied to each node, e.g. `energy` in `(shade-by energy)`. */
+    func: Atom;
+}
+/** Everything the editor reads from `&grapher`: the per-node directives, the data-driven mappers, and the
+ *  global settings that target nothing (the canvas background). */
+interface VizResult {
+    directives: VizDirective[];
+    /** Data-driven mappers from `(shade-by FUNC)` / `(size-by FUNC)`, applied to every node. */
+    mappers: VizMapper[];
+    /** The canvas background from `(background COLOR)`, or null to keep the default. */
+    background: string | null;
+}
+/** Bind the isolated `&grapher` space in `space` (as a fresh, empty space). Call once per space: binding
+ *  it again would replace it with a new empty one, dropping any directives already added. */
+declare function bindVizSpace(space: MeTTa): void;
+/** Read what is currently in `&grapher`, each atom verbatim (unevaluated): the per-node directives and the
+ *  global background. Empty when the space is unbound or empty. */
+declare function readViz(space: MeTTa): VizResult;
+/** A CSS color from a name (`red`, `blue`, …) or a hex string; falls back to yellow. */
+declare function colorOf(atom: Atom): string;
+/** The text of a label atom: a string without its quotes, or the atom's rendering. */
+declare function textOf(atom: Atom): string;
+
+/** A built-in palette name, or a custom palette. */
+type PaletteChoice = "site" | "teal" | BlockPalette;
+/** A fluent handle over a mounted {@link MeTTaGrapher}. Building steps return the handle; `source`, `gif`,
+ *  and `destroy` end the chain. The full instance is on `.grapher`. */
+interface Grapher {
+    readonly grapher: MeTTaGrapher;
+    /** Replace the program from MeTTa source. */
+    load(source: string): Grapher;
+    /** Replace the program from atoms (for example built with the eDSL). */
+    atoms(atoms: readonly Atom[]): Grapher;
+    /** Show the node graph. */
+    graph(): Grapher;
+    /** Show the nested blocks. */
+    blocks(): Grapher;
+    /** Recolor the blocks (a built-in name or a custom palette). */
+    palette(palette: PaletteChoice): Grapher;
+    /** Lay the program out and frame it. */
+    fit(): Grapher;
+    /** Evaluate every query and label the result. */
+    evaluate(): Grapher;
+    /** Initialize the last query's reduction trace at its first state. */
+    play(): Grapher;
+    /** The current program as source, reflecting edits and reductions. */
+    source(): string;
+    /** Encode the reduction as an animated GIF, using a caller-supplied encoder (gifenc). */
+    gif(encoder: GifEncoderLib, opts?: GifOptions): Promise<Blob | null>;
+    /** Detach listeners and remove the editor. */
+    destroy(): void;
+}
+/** Mount the visualizer on an element (or a CSS selector) and return a fluent handle. */
+declare function grapher(target: string | HTMLElement, opts?: GrapherOptions): Grapher;
+
+/** Compose the atom rooted at one node, or null if the node is unknown or contributes nothing. */
+declare function composeAtom(graph: Graph, nodeId: string): Atom | null;
+/** Compose one atom per head (a parentless node), children in screen order. Dot nodes that contribute
+ *  nothing are dropped. */
+declare function graphToAtoms(graph: Graph): Atom[];
+/** Build nodes and edges from atoms, then lay them out as tidy trees. Adds to `graph` if given. */
+declare function atomToGraph(atoms: Atom[], graph?: Graph): Graph;
+
+/** Parse MeTTa source into its top-level atoms. */
+declare function parseProgram(src: string): Atom[];
+/** Parse a single-token source string into one atom, or `undefined` if it is not exactly one atom. */
+declare function parseLeaf(token: string): Atom | undefined;
+
+/** Assign `x` and `y` to every node so the graph reads as tidy top-down trees. Mutates the graph. */
+declare function layout(graph: Graph, opts?: {
+    originX?: number;
+    originY?: number;
+    scaleOf?: (node: GraphNode) => number;
+}): void;
+
+/** Load the whole graph into a space so its own rules and facts are active when a head is evaluated. Adds
+ *  every head atom to `metta`'s space and returns it; a fresh engine is created when none is given. This is
+ *  what makes evaluating a query like `(fact 5)` reduce through a `(= (fact $n) ...)` rule drawn on the
+ *  same canvas. */
+declare function loadProgram(graph: Graph, metta?: MeTTa): MeTTa;
+/** The outcome of evaluating a head: the result atoms, a short label for display, and whether any result
+ *  is an error (or evaluation threw). */
+interface EvalResult {
+    atoms: Atom[];
+    label: string;
+    error: boolean;
+}
+/** Evaluate the head at `headId`, catching a thrown error as a failed result. */
+declare function evaluateHead(graph: Graph, headId: string, metta: MeTTa): EvalResult;
+/** Like {@link evaluateHead}, awaiting async grounded operations reached during evaluation. */
+declare function evaluateHeadAsync(graph: Graph, headId: string, metta: MeTTa): Promise<EvalResult>;
+
+type LazyCache = Map<string, Set<number>>;
+/** One reduction step of the whole expression: reduce the leftmost eager argument that can reduce (fanning
+ *  out if that argument is nondeterministic), else reduce the whole atom. Returns every successor, or null
+ *  at a normal form. */
+declare function reduceStep(atom: Atom, metta: MeTTa, cache?: LazyCache): Atom[] | null;
+/** The full sequence of frontiers from `atom` to its normal form(s). The first frontier is `[atom]`; each
+ *  next frontier reduces every still-reducing term one step, so nondeterministic branches all advance
+ *  together and every result is shown. Capped at `maxSteps` deep and {@link MAX_WIDTH} wide. */
+declare function reduceTrace(atom: Atom, metta: MeTTa, maxSteps?: number): Atom[][];
+
+/** Pairs of node ids to connect: for each variable name within a head, a chain through its occurrences in
+ *  screen order. Names appearing once are omitted. */
+declare function variableLinks(graph: Graph): Array<[string, string]>;
+
+/** Ranked completion candidates for `prefix`, drawn from the space and the stdlib. Empty prefix yields
+ *  nothing. Ties break toward shorter, then alphabetical, names. */
+declare function completionsFor(prefix: string, metta: MeTTa, limit?: number): string[];
+
+/** A token category, matching the highlighter's classes, plus `control` for the branching forms so the
+ *  graph can shape and color them like a flowchart decision, and `boolean` for the constants True/False. */
+type NodeRole = "variable" | "number" | "string" | "boolean" | "operator" | "control" | "spaceref" | "at" | "paren" | "symbol";
+/** The fill and text color of a node. */
+interface NodeColor {
+    fill: string;
+    text: string;
+}
+/** Classify a symbol name into a highlighter token category. */
+declare function roleOf(name: string): NodeRole;
+/** The color of a node. List nodes are the paren green; dot nodes a neutral; symbol nodes are colored by
+ *  {@link roleOf}. */
+declare function colorFor(node: GraphNode): NodeColor;
+
+/** Node box height in world units. */
+declare const NODE_H = 22;
+/** The text drawn inside a node: `( )` for a list, a dot for a passthrough, otherwise the name rendered as
+ *  its math glyph (`*` as ×, `->` as →, …). */
+declare function displayText(node: GraphNode): string;
+/** A node's box width, from its display text. */
+declare function nodeWidth(node: GraphNode): number;
+
+/** A block view mounted in a container, sharing the engine with the rest of the editor. */
+declare class BlockView {
+    private readonly renderer;
+    private readonly getSpace;
+    private palette;
+    private settings;
+    private atoms;
+    private boxes;
+    private selectedPath;
+    private editing;
+    private readonlyMode;
+    private readonly history;
+    private readonly onChange;
+    constructor(container: HTMLElement, getSpace: () => MeTTa, onChange?: () => void);
+    private ensureSettings;
+    /** Recolor the view with a different palette. */
+    setPalette(palette: BlockPalette): void;
+    /** Load a program to edit and reduce interactively. */
+    setAtoms(atoms: readonly Atom[]): void;
+    /** Zoom the view in (factor > 1) or out (factor < 1). */
+    zoomBy(factor: number): void;
+    /** Pan the view by a screen-space delta. */
+    panBy(dx: number, dy: number): void;
+    /** Reset zoom/pan so the whole program is framed again. */
+    fitView(): void;
+    /** Frame the given atoms without interaction (used for a step-through playthrough). */
+    showReadonly(atoms: readonly Atom[]): void;
+    render(animate?: boolean): void;
+    /** The current program as source, reflecting any edits and reductions. */
+    sourceText(): string;
+    /** Encode a sequence of reduction states as an animated GIF, using a caller-supplied encoder (gifenc),
+     *  so the package needs no GIF dependency of its own. */
+    exportGif(states: readonly Atom[][], lib: GifEncoderLib, opts?: GifOptions): Promise<Blob>;
+    /** Encode a reduction as one GIF that plays it in both the graph and the block views side by side. Shares
+     *  the block layout settings so the two panels agree on the canvas color and fonts. */
+    exportSideBySideGif(states: readonly Atom[][], lib: GifEncoderLib, opts?: GifOptions): Promise<Blob>;
+    show(): void;
+    hide(): void;
+    destroy(): void;
+    private pathFromEvent;
+    /** The leaf text at `path`, or null when the term is a form (not editable as text). */
+    private leafText;
+    private lastPath;
+    private lastClickTime;
+    private readonly onPointerDown;
+    /** Begin editing the selected leaf. When `replace` is set the buffer starts empty (typing replaces the
+     *  term); otherwise it starts from the current text (typing extends it). */
+    private startEdit;
+    /** Commit the edit: re-parse the buffer into an atom and splice it back into the program. */
+    private commitEdit;
+    private cancelEdit;
+    /** Reduce the selected term one step in place. Returns whether anything changed. */
+    reduceSelected(): boolean;
+    /** Step back to the program before the last reduction or edit. */
+    back(): boolean;
+    canStepBack(): boolean;
+    private readonly onKeyDown;
+    private onEditKey;
+    /** Every box path in preorder (a term before its children). */
+    private preorder;
+    /** Move the cursor: right and left step through the tree in preorder, down enters the first child, up
+     *  returns to the parent. */
+    private navigate;
+}
+
+/** Encode a reduction (its list of states, each a frontier of atoms) into one GIF showing the graph and the
+ *  block views side by side, morphing between states together. `s` supplies the block layout and the shared
+ *  canvas color. Returns an `image/gif` Blob. */
+declare function sideBySideReductionGif(states: readonly Atom[][], s: BlockSettings, lib: GifEncoderLib, opts?: GifOptions): Promise<Blob>;
+/** The graph and block views in one SVG animation, suitable for browser or Node rasterization. */
+declare function sideBySideReductionSvgs(states: readonly Atom[][], opts?: GifOptions, s?: BlockSettings): SvgAnimation;
+/** One rendered graph frame: a self-contained SVG string and how long to hold it (ms). */
+type GraphFrame = SvgFrame;
+/** The node-graph view of a reduction as a sequence of SVG frames over a fixed-size, action-following
+ *  viewport. Pure (no DOM), so it runs in Node as well as the browser: {@link graphReductionGif} rasterizes
+ *  these with browser Canvas, while the Node entry uses Sharp. */
+declare function graphReductionSvgs(states: readonly Atom[][], opts?: GifOptions): SvgAnimation;
+/** Encode a reduction as a GIF of the node-graph view alone, morphing between states. Companion to {@link
+ *  reductionGif} (the block view); stack the two to show a reduction both ways. Rasterizes the frames from
+ *  {@link graphReductionSvgs} with a canvas. */
+declare function graphReductionGif(states: readonly Atom[][], lib: GifEncoderLib, opts?: GifOptions): Promise<Blob>;
+/** The nested-block view of a reduction as a sequence of SVG frames over a fixed view box (the union of every
+ *  state's bounds). Pure (no DOM), the block-view companion to {@link graphReductionSvgs}: place the two next
+ *  to each other to show a reduction both ways. Rasterize with a canvas ({@link reductionGif}) or an external
+ *  tool. Uses default block settings (site palette, monospace unit width); pass `background` to override the
+ *  canvas color. */
+declare function blockReductionSvgs(states: readonly Atom[][], opts?: GifOptions): SvgAnimation;
+
+export { type BlockBox, type BlockPalette, type BlockSettings, BlockView, CUTOFF, Controller, type ControllerHost, type EvalResult, type GifEncoderLib, type GifOptions, Graph, type GraphFrame, type GraphJson, type GraphNode, type Grapher, type GrapherOptions, MeTTaGrapher, NODE_H, type NodeColor, type NodeKind, type NodeLabel, type NodeRole, type PaletteChoice, type ProfileRow, type PulledPoint, type RenderState, Renderer, SITE_PALETTE, type SvgAnimation, type SvgFrame, type SvgRasterizer, TEAL_PALETTE, VIZ_SPACE, type Viewport, type VizDirective, type VizOverlay, type VizResult, atomToGraph, bindVizSpace, blockReductionSvgs, colorFor, colorOf, completionsFor, composeAtom, displayText, encodeSvgAnimation, evaluateHead, evaluateHeadAsync, fromJson, fromSource, graphReductionGif, graphReductionSvgs, graphToAtoms, grapher, initialViewport, layout, layoutAtom, loadProgram, makeSettings, nodeWidth, pan, parseLeaf, parseProgram, placeProgram, pulledPointsToPath, readViz, reduceStep, reduceTrace, reductionGif, roleOf, roundedBackingPath, roundedRectPath, sideBySideReductionGif, sideBySideReductionSvgs, textOf, toJson, toScreen, toSource, toWorld, variableLinks, zoomAt };