@hlang-tech/editor-ui 0.3.0 → 0.5.0

package/lib/index.d.mts

@@ -1,5 +1,5 @@
-import { NodeKind, EditorNode, PortDescriptor, EditorCore, NodeId, Diagnostic, ParamValue, NodeDescriptor, ParamBag, Endpoint, IConnectionValidator, Point, IExecutionHandle } from '@hlang-tech/editor-core';
-import { CSSProperties, ReactNode, ReactElement, RefObject } from 'react';
+import { NodeKind, EditorNode, PortDescriptor, EditorCore, NodeId, Diagnostic, ParamValue, NodeDescriptor, ParamBag, Endpoint, IConnectionValidator, Point as Point$1, IExecutionHandle, INodeDeliveryEvent, INodeErrorEvent, INodeEndedEvent, INodeFinishedEvent, INodeDroppedEvent, EdgeId, EditorEdge, EdgeBounds } from '@hlang-tech/editor-core';
+import { CSSProperties, ReactNode, ReactElement, RefObject, UIEvent } from 'react';
 import { NodeProps, EdgeProps, NodeTypes, EdgeTypes, OnConnectStartParams } from '@xyflow/react';
 import { HlangRFNode, HlangRFEdge } from '@hlang-tech/editor-react';
 
@@ -159,7 +159,7 @@ declare function NodeBodySlot({ children }: NodeBodySlotProps): ReactElement | n
 
 /**
  * The signature edge: a connection rendered as a living stream. A base bezier
- * conduit plus a silver overlay that marches from output (O) to input (I) —
+ * conduit (or, from a node back into itself, a loop routed around the node) plus a silver overlay that marches from output (O) to input (I) —
  * exactly what an hlang RxJS port does; a cold spark lights it while flowing.
  *
  * When the SOURCE node carries a semantic `role` param (e.g. Character,
@@ -170,6 +170,48 @@ declare function NodeBodySlot({ children }: NodeBodySlotProps): ReactElement | n
 
 declare function FlowEdge(props: EdgeProps<HlangRFEdge>): ReactElement;
 
+/**
+ * The route of an edge from a node back into the same node: a Transform fed
+ * by its own output (iteration). A curve between two handles on opposite
+ * sides of one node would cut across it; instead the edge leaves the output
+ * to the right, runs under the node and comes up on the left into the input,
+ * with rounded corners, as node editors route an edge that goes backwards
+ * (n8n's back edges). Pure geometry, so the edge component only draws it.
+ */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface SelfLoopInput {
+    /** The output handle (on the node's right side) and the input handle (on its left). */
+    readonly source: Point;
+    readonly target: Point;
+    /** The node, in the same coordinates. */
+    readonly node: Rect;
+    /** How far the route keeps from the node. Default `SELF_LOOP_CLEARANCE`. */
+    readonly clearance?: number;
+    /** The corner radius, reduced where a segment is too short. Default `SELF_LOOP_RADIUS`. */
+    readonly radius?: number;
+}
+interface SelfLoop {
+    /** SVG path data. */
+    readonly path: string;
+    /** Where a label sits: the middle of the run under the node. */
+    readonly labelX: number;
+    readonly labelY: number;
+}
+/** The design system's distance between a self-loop and its node, in flow units. */
+declare const SELF_LOOP_CLEARANCE = 28;
+/** The design system's corner radius for a self-loop, in flow units. */
+declare const SELF_LOOP_RADIUS = 16;
+declare function selfLoopPath(input: SelfLoopInput): SelfLoop;
+
 /**
  * One-line React Flow wiring: `createHlangFlowTypes()` returns the `nodeTypes`
  * and `edgeTypes` maps to spread onto `<ReactFlow>`, binding hlang's R/T/W node
@@ -188,11 +230,84 @@ interface HlangFlowTypes {
 /** Build the React Flow node/edge type maps for the hlang editor. */
 declare function createHlangFlowTypes(): HlangFlowTypes;
 
+/**
+ * The size rules of the editor's resizable footer (its console): how tall it
+ * may be, and how the keyboard and a double click change it. Pure, so the
+ * pointer and keyboard handling in `useFooterResize` stays a thin layer.
+ */
+/** How far one arrow key press moves the footer edge, in pixels; Shift moves four times as far. */
+declare const FOOTER_KEY_STEP = 16;
+interface FooterBounds {
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * The heights the footer may take in an editor with `available` pixels below
+ * its toolbar: at least `minHeight` (its header alone, collapsed), and at most
+ * what leaves the canvas `minCanvasHeight`.
+ */
+declare function footerBounds(options: {
+    readonly available: number;
+    readonly minHeight: number;
+    readonly minCanvasHeight: number;
+}): FooterBounds;
+/** `height` held within `bounds`, in whole pixels. */
+declare function clampFooter(height: number, bounds: FooterBounds): number;
+/** The height after pressing `key` on the footer edge, or `undefined` for a key that does nothing. */
+declare function resizeByKey(height: number, key: string, shift: boolean, bounds: FooterBounds): number | undefined;
+/** The footer's height and the height to return to when it is opened again. */
+interface FooterSize {
+    readonly height: number;
+    readonly restore: number;
+}
+/** Collapses an open footer (remembering its height), or opens a collapsed one to that height. */
+declare function toggleCollapsed(size: FooterSize, bounds: FooterBounds): FooterSize;
+
+/**
+ * `useFooterResize` — the state of a footer whose top edge the user drags, or
+ * moves with the keyboard, to make it taller or shorter. It takes only what it
+ * reads (a pointer's `clientY`, a key), so `FooterResizer` adapts the browser's
+ * events to it and the behavior is testable without a browser.
+ *
+ * The height the user asked for is kept apart from the height shown: when the
+ * editor gets shorter the footer shrinks to fit, and when it grows back the
+ * footer returns to the asked-for height.
+ */
+
+/** How a resizable footer behaves. */
+interface FooterResizeOptions {
+    /** Its height when the editor opens, in pixels. */
+    readonly defaultHeight: number;
+    /** Its height when collapsed: its own header, so it can always be grabbed and opened again. */
+    readonly minHeight: number;
+    /** The height the canvas always keeps. Default `DEFAULT_MIN_CANVAS_HEIGHT`. */
+    readonly minCanvasHeight?: number;
+}
+/** The canvas height a footer never takes away, unless a host sets another. */
+declare const DEFAULT_MIN_CANVAS_HEIGHT = 160;
+interface FooterResize {
+    /** The height to render. */
+    readonly height: number;
+    readonly bounds: FooterBounds;
+    readonly dragging: boolean;
+    /** Tells the hook how many pixels the toolbar leaves for the canvas and the footer. */
+    readonly measure: (available: number) => void;
+    readonly startDrag: (clientY: number) => void;
+    readonly drag: (clientY: number) => void;
+    readonly endDrag: () => void;
+    /** Applies a key pressed on the edge; returns whether the key resized the footer. */
+    readonly keyDown: (key: string, shift: boolean) => boolean;
+    /** Collapses the footer, or opens it again to the height it had. */
+    readonly toggle: () => void;
+}
+declare function useFooterResize(options: FooterResizeOptions): FooterResize;
+
 /**
  * `EditorShell` — composes the editor's regions (top toolbar, left panel,
- * center canvas, right inspector) as a CSS grid. It holds NO graph logic; a
- * host slots children into named regions. Left/right panels are collapsible via
- * UI-only props (collapse state is presentation, never part of the graph).
+ * center canvas, right inspector, footer). It holds NO graph logic; a host
+ * slots children into named regions. Left/right panels are collapsible via
+ * UI-only props, and the footer can be made resizable (presentation state,
+ * never part of the graph).
  */
 
 interface EditorShellProps {
@@ -206,10 +321,36 @@ interface EditorShellProps {
     readonly canvas: ReactNode;
     /** Optional footer region (e.g. an output/console strip). */
     readonly footer?: ReactNode;
+    /**
+     * Makes the footer resizable: its top edge can be dragged, moved with the
+     * keyboard, and double-clicked to collapse it. Without it the footer takes
+     * its content's height.
+     */
+    readonly footerResize?: FooterResizeOptions & {
+        /** The accessible name of the footer's resize handle. Default "Resize the panel". */
+        readonly label?: string;
+    };
     readonly leftCollapsed?: boolean;
     readonly rightCollapsed?: boolean;
 }
-declare function EditorShell({ toolbar, left, right, canvas, footer, leftCollapsed, rightCollapsed, }: EditorShellProps): ReactElement;
+declare function EditorShell({ toolbar, left, right, canvas, footer, footerResize, leftCollapsed, rightCollapsed, }: EditorShellProps): ReactElement;
+
+/**
+ * `FooterResizer` — the grab handle on a resizable footer's top edge. Drag it
+ * with a mouse, a finger or a pen; with focus, the arrow keys move it (Shift
+ * for larger steps), Home and End go to the smallest and largest heights, and
+ * Enter or a double click collapses the footer and opens it again. It is a
+ * focusable ARIA `separator` that reports the footer's height.
+ */
+
+interface FooterResizerProps {
+    readonly resize: FooterResize;
+    /** The id of the footer the handle resizes. */
+    readonly controls: string;
+    /** Its accessible name. */
+    readonly label: string;
+}
+declare function FooterResizer({ resize, controls, label }: FooterResizerProps): ReactElement;
 
 /**
  * The top toolbar: a thin glass bar with a brand wordmark on the left and an
@@ -255,6 +396,21 @@ declare function ToolbarGhostButton({ children, onClick, title, }: {
     readonly title?: string;
 }): ReactElement;
 
+/**
+ * `ReadOnlyBadge` — says, in the toolbar, that the graph can be looked at
+ * and run but not changed (the editor core is read-only; see editor-core's
+ * `IEditorModeService`). The host says why in `title`. In a narrow toolbar it
+ * keeps only its lock; the label stays its accessible name.
+ */
+
+interface ReadOnlyBadgeProps {
+    /** The badge's text. */
+    readonly label?: string;
+    /** Why the editor is read-only, shown as its tooltip. */
+    readonly title?: string;
+}
+declare function ReadOnlyBadge({ label, title }: ReadOnlyBadgeProps): ReactElement;
+
 /**
  * `ToolCluster` — the centred group of canvas tools in the top bar (nover-style):
  * a row of icon buttons with optional separators, in the black/silver glass
@@ -297,6 +453,10 @@ declare function CanvasChrome({ background }: CanvasChromeProps): ReactElement;
  * glass language. It replaces React Flow's default corner Controls + MiniMap
  * with one calm, centred dock.
  *
+ * A read-only dock (`readOnly`) keeps only the view controls (zoom, fit):
+ * undo, redo, the pointer modes and add-node all change the graph or exist
+ * to edit it.
+ *
  * Presentation only: it renders buttons and the current zoom %, and calls back
  * to the host for every action. It holds no React Flow or graph state — the host
  * wires the callbacks to `useReactFlow()` (zoom/fit) and the node search (add).
@@ -320,8 +480,10 @@ interface CanvasDockProps {
     readonly onRedo: () => void;
     readonly canUndo: boolean;
     readonly canRedo: boolean;
+    /** Show the view controls only: the graph cannot be edited. */
+    readonly readOnly?: boolean;
 }
-declare function CanvasDock({ zoom, onZoomIn, onZoomOut, onFitView, onAdd, mode, onModeChange, onUndo, onRedo, canUndo, canRedo, }: CanvasDockProps): ReactElement;
+declare function CanvasDock({ zoom, onZoomIn, onZoomOut, onFitView, onAdd, mode, onModeChange, onUndo, onRedo, canUndo, canRedo, readOnly, }: CanvasDockProps): ReactElement;
 
 /**
  * `EmptyState` — a quiet, centered hint shown over an empty canvas. Purely
@@ -339,6 +501,7 @@ declare function EmptyState({ title, hint, }: EmptyStateProps): ReactElement;
  * `InspectorPanel` — the right-hand property inspector. It follows selection:
  * with exactly one node selected it shows that node's identity plus a
  * schema-driven parameter form (edits commit undoable UpdateParamsCommands);
+ * with exactly one connection selected, the connection and its back-pressure;
  * otherwise it shows an empty/summary state. This is the unified control center
  * (nover.studio's model) over hlang's headless core.
  */
@@ -387,6 +550,59 @@ interface PreviewPanelProps {
 }
 declare function PreviewPanel({ imageUrl, title, status }: PreviewPanelProps): ReactElement;
 
+/**
+ * `PanelHead` and `PanelAction` — the header row of a docked panel (the
+ * console, the run log): what the panel is, a short status, and its actions.
+ *
+ * The header responds to its own width, not the window's (a container query,
+ * as VS Code's and DevTools' panel toolbars do): when it is narrow the actions
+ * drop their labels and keep their icons, and then the status gives way. A
+ * label that is not shown is still the button's accessible name, and its
+ * tooltip.
+ */
+
+interface PanelHeadProps {
+    /** What the panel is: its title, or the host's tabs. */
+    readonly leading: ReactNode;
+    /** A short status after it, e.g. a count; the first thing to go when the panel is narrow. */
+    readonly meta?: ReactNode;
+    /** The panel's actions, usually `PanelAction`s. */
+    readonly children?: ReactNode;
+}
+declare function PanelHead({ leading, meta, children }: PanelHeadProps): ReactElement;
+interface PanelActionProps {
+    readonly icon: ReactNode;
+    /** The action's name: shown when there is room, and always its accessible name. */
+    readonly label: string;
+    readonly onClick: () => void;
+    /** For a toggle: whether it is on. Leave out for a plain action. */
+    readonly pressed?: boolean;
+    readonly disabled?: boolean;
+    /** The tooltip; the label by default. */
+    readonly title?: string;
+}
+declare function PanelAction({ icon, label, onClick, pressed, disabled, title }: PanelActionProps): ReactElement;
+
+/**
+ * Per-type node icons. A small registry mapping a node `code` to a crisp
+ * line-glyph (1.5px stroke, currentColor), with a kind fallback (R/T/W). Used
+ * by the outline tree and the node chrome so every node reads by its ROLE, not
+ * a generic letter — the difference between a tool and a spreadsheet.
+ *
+ * Icons are inline SVG (not emoji) for a premium, monochrome, scalable look;
+ * they inherit `color` so callers tint them by kind or silver.
+ */
+
+interface IconProps {
+    readonly size?: number;
+}
+/** Funnel — show only what involves the selection. */
+declare function FilterIcon({ size }: IconProps): ReactElement;
+/** Arrow onto a line — keep the newest entry in view. */
+declare function FollowIcon({ size }: IconProps): ReactElement;
+/** Circle with a stroke through it — clear the log (DevTools' glyph). */
+declare function ClearIcon({ size }: IconProps): ReactElement;
+
 /**
  * `RailTabs` — the segmented tab strip at the top of a side rail (Outline /
  * Insert / Assets, nover-style), in the black/silver glass language. Purely
@@ -517,8 +733,10 @@ interface ParamFormProps {
     readonly fields: readonly ParamField[];
     /** Commit a single field's new value (undoable, handled by the caller). */
     readonly onCommit: (key: string, value: ParamValue) => void;
+    /** Disables every field, e.g. in a read-only editor. */
+    readonly disabled?: boolean;
 }
-declare function ParamForm({ fields, onCommit }: ParamFormProps): ReactElement;
+declare function ParamForm({ fields, onCommit, disabled }: ParamFormProps): ReactElement;
 
 /**
  * `useNodeParams` — reactively read a node's params and commit edits through the
@@ -641,9 +859,9 @@ declare function connectableCandidates(query: string, descriptors: readonly Node
 /** Where and how the palette is currently open. */
 interface NodeSearchState {
     /** Screen-space anchor for rendering the floating panel. */
-    readonly screen: Point;
+    readonly screen: Point$1;
     /** Flow-space position where the created node will be placed. */
-    readonly flow: Point;
+    readonly flow: Point$1;
     /** Set when opened by releasing a dangling connection. */
     readonly pending?: PendingConnection;
 }
@@ -652,9 +870,9 @@ interface NodeSearchController {
     /** Current open state, or `undefined` when closed. */
     readonly state: NodeSearchState | undefined;
     /** Open the palette to create a free-standing node. */
-    openBlank(screen: Point, flow: Point): void;
+    openBlank(screen: Point$1, flow: Point$1): void;
     /** Open the palette to complete a released connection. */
-    openFromConnection(screen: Point, flow: Point, pending: PendingConnection): void;
+    openFromConnection(screen: Point$1, flow: Point$1, pending: PendingConnection): void;
     /** Close the palette without creating anything. */
     close(): void;
     /**
@@ -703,6 +921,9 @@ declare function NodeSearch({ controller }: NodeSearchProps): ReactElement | nul
  *     only for the pane, never for nodes/edges/handles) rather than a raw DOM
  *     double-click, so this never reaches into React Flow's internal markup.
  *
+ * A read-only editor (`core.mode.readOnly`) opens nothing: the palette only
+ * adds nodes, which a read-only graph refuses.
+ *
  * Screen→flow coordinate conversion uses the React Flow instance, so created
  * nodes land under the pointer regardless of pan/zoom. This hook must be used
  * within a `ReactFlowProvider` (React Flow's own requirement for `useReactFlow`).
@@ -779,14 +1000,14 @@ declare function useEditorHotkeys(core: EditorCore, options?: EditorHotkeysOptio
 /** Where the menu is open and which node it targets. */
 interface NodeContextMenuState {
     /** Screen-space anchor (the click point). */
-    readonly screen: Point;
+    readonly screen: Point$1;
     /** The node the menu acts on. */
     readonly nodeId: NodeId;
 }
 interface NodeContextMenuController {
     readonly state: NodeContextMenuState | undefined;
     /** Open the menu for a node at a screen point. */
-    openForNode(screen: Point, nodeId: NodeId): void;
+    openForNode(screen: Point$1, nodeId: NodeId): void;
     close(): void;
 }
 declare function useNodeContextMenu(): NodeContextMenuController;
@@ -824,15 +1045,19 @@ declare function NodeContextMenu({ controller, items }: NodeContextMenuProps): R
  * `NodeInteractionContext` — optional per-node interaction wiring supplied by the
  * host (diagnostics to badge, rename to commit). Node chrome reads it to render a
  * diagnostic badge and to support inline rename, but degrades gracefully to a
- * plain, read-only node when no provider is present — so editor-ui stays usable
+ * plain node that cannot be renamed when no provider is present, or when the
+ * host leaves `rename` out (a read-only editor) — so editor-ui stays usable
  * without the full editor wiring.
  */
 
 interface NodeInteraction {
     /** The most severe diagnostic on a node, or undefined. */
     diagnosticFor(id: NodeId): Diagnostic | undefined;
-    /** Commit a rename (host routes it through the command service). */
-    rename(id: NodeId, name: string): void;
+    /**
+     * Commit a rename (host routes it through the command service). Without it,
+     * a node's name cannot be edited in place.
+     */
+    readonly rename?: (id: NodeId, name: string) => void;
 }
 interface NodeInteractionProviderProps {
     readonly value: NodeInteraction;
@@ -897,27 +1122,43 @@ declare function useToast(): ToastApi;
  *     frame however many signals arrived in it.
  */
 /** Live state of a node during execution. */
-type NodeLiveState = 'idle' | 'active' | 'error';
-type Listener = () => void;
-/** Minimal edge shape the store needs to map a source-port pulse to edges. */
+type NodeLiveState = 'idle' | 'active' | 'error' | 'finished';
+type Listener$1 = () => void;
+/**
+ * Minimal edge shape the store needs to map a signal to edges. With its
+ * target, a delivery lights exactly the edge that carried it.
+ */
 interface EdgeIndexEntry {
     readonly id: string;
     readonly sourceNodeId: string;
     readonly sourcePortId: string;
+    readonly targetNodeId?: string;
+    readonly targetPortId?: string;
     readonly isError: boolean;
 }
+/** A message delivered on one connection: its source ran and sent it, its target ran to handle it. */
+interface DeliverySignal {
+    readonly sourceNodeId: string;
+    readonly sourcePortId: string;
+    readonly targetNodeId: string;
+    readonly targetPortId: string;
+}
 /** Injected clock + scheduler so the store is deterministic and testable. */
 interface LiveSignalStoreDeps {
     now(): number;
     schedule(cb: () => void): number;
     cancel(handle: number): void;
 }
+/** The browser's clock and frame scheduler, with fallbacks outside a browser. */
+declare const defaultLiveDeps: LiveSignalStoreDeps;
 declare class LiveSignalStore {
     private readonly deps;
     /** nodeId -> last-active timestamp. */
     private readonly nodeActiveAt;
     /** nodeId set that errored during this run. */
     private readonly erroredNodes;
+    /** nodeId set that finished during this run (RFC 0001). */
+    private readonly finishedNodes;
     /** edgeId -> last-flowing timestamp. */
     private readonly edgeFlowAt;
     /** Per-id listeners. */
@@ -928,21 +1169,42 @@ declare class LiveSignalStore {
     private readonly lastEdgeFlowing;
     /** Edges sourced by a given (nodeId@portId), for pulse -> edge mapping. */
     private edgesBySourcePort;
+    /** Edges by the connection they carry (source port -> target port). */
+    private edgesByConnection;
+    /** How many messages each node has handled or sent, and each edge carried, this run. */
+    private readonly nodePulse;
+    private readonly edgePulse;
+    /** The pulse counts last notified, so a new message notifies even while the state stays active. */
+    private readonly lastNodePulse;
+    private readonly lastEdgePulse;
     private rafHandle;
     private running;
     constructor(deps?: LiveSignalStoreDeps);
     /** Provide the current edge index (call whenever edges change). */
     setEdgeIndex(edges: readonly EdgeIndexEntry[]): void;
+    /**
+     * Record a message delivered on a connection, when it happens: its source
+     * and its target each pulse once (each ran), and so does the edge that
+     * carried it, and only that edge. Subscribers are notified on the next
+     * frame, once however many messages arrived in it.
+     */
+    markDelivery(signal: DeliverySignal): void;
+    /** How many messages a node has handled or sent this run; it changes each time the node runs. */
+    getNodePulse(nodeId: string): number;
+    /** How many messages an edge has carried this run. */
+    getEdgePulse(edgeId: string): number;
     /** Record a node emitting on an output port (drives node + edge activity). */
     markActivity(nodeId: string, portId: string): void;
+    /** Record a node finishing (RFC 0001): shown once its last flash has faded. */
+    markFinished(nodeId: string): void;
     /** Record a node erroring (sticky for the run). */
     markError(nodeId: string): void;
     /** Clear all live state (on stop/teardown) and notify everyone. */
     reset(): void;
     /** Subscribe to a single node's live state. */
-    subscribeNode(nodeId: string, listener: Listener): () => void;
+    subscribeNode(nodeId: string, listener: Listener$1): () => void;
     /** Subscribe to a single edge's flowing state. */
-    subscribeEdge(edgeId: string, listener: Listener): () => void;
+    subscribeEdge(edgeId: string, listener: Listener$1): () => void;
     /** Current live state of a node. */
     getNodeState(nodeId: string): NodeLiveState;
     /** Whether an edge is currently flowing. */
@@ -1000,8 +1262,288 @@ declare function LiveSignalProvider({ store, children }: LiveSignalProviderProps
 declare function useLiveSignalStore(): LiveSignalStore | null;
 /** Subscribe to a single node's live state. Idle when no store is present. */
 declare function useNodeLiveState(nodeId: string): NodeLiveState;
+/** How many messages a node has handled or sent this run; it changes each time the node runs. */
+declare function useNodePulse(nodeId: string): number;
+/** How many messages an edge has carried this run. */
+declare function useEdgePulse(edgeId: string): number;
 /** Subscribe to a single edge's flowing state. False when no store is present. */
 declare function useEdgeFlowing(edgeId: string): boolean;
 
-export { AssetGrid, AssetNodeChrome, CanvasChrome, CanvasDock, Cheatsheet, DiagnosticBadge, EditorShell, EditorUIThemeProvider, EmptyState, FlowEdge, HlangNode, InspectorPanel, KIND_ROLE, KIND_TOKEN, LiveSignalProvider, LiveSignalStore, NodeBodySlot, NodeChrome, NodeContextMenu, NodeInteractionProvider, NodeSearch, OutlineTree, ParamForm, PillNodeChrome, PortRow, PositionPanel, PreviewPanel, RailTabs, RunButton, SignalBar, TOKEN_NAMES, ToastProvider, ToolCluster, Toolbar, ToolbarGhostButton, ToolbarStat, UndoRedo, connectableCandidates, createHlangFlowTypes, createTheme, deriveParamSchema, descriptorCandidates, fuzzyRank, fuzzyScore, isEditableTarget, searchNodes, tokenVar, useEdgeFlowing, useEditorHotkeys, useLiveSignalStore, useLiveSignals, useNodeContextMenu, useNodeInteraction, useNodeLiveState, useNodeParams, useNodeSearch, useNodeSearchTriggers, useToast };
-export type { AssetGridProps, AssetItem, AssetNodeChromeProps, CanvasChromeProps, CanvasDockProps, CanvasMode, CheatsheetProps, ConnectableResult, ConnectionEnd, ContextMenuItem, DiagnosticBadgeProps, EdgeIndexEntry, EditorHotkeysOptions, EditorShellProps, EditorUIThemeProviderProps, EmptyStateProps, FuzzyCandidate, FuzzyMatch, FuzzyResult, HlangFlowTypes, InspectorPanelProps, LiveSignalProviderProps, LiveSignalStoreDeps, NodeBodySlotProps, NodeCandidate, NodeChromeProps, NodeContextMenuController, NodeContextMenuProps, NodeContextMenuState, NodeInteraction, NodeInteractionProviderProps, NodeLiveState, NodeParamsHandle, NodeSearchController, NodeSearchProps, NodeSearchResult, NodeSearchResultView, NodeSearchState, NodeSearchTriggerOptions, NodeSearchTriggers, OutlineTreeProps, ParamField, ParamFieldBase, ParamFormProps, PendingConnection, PillNodeChromeProps, PointerPosition, PortRowProps, PositionPanelProps, PreviewPanelProps, RailTab, RailTabsProps, RunButtonProps, ShortcutGroup, ShortcutRow, ThemeOverride, ToastApi, ToastProviderProps, TokenName, ToolClusterProps, ToolItem, ToolbarProps, TouchPositions, UndoRedoProps };
+/**
+ * `RunTrace` — what a running graph did: a bounded log of every delivery and
+ * error, and per-node statistics (messages in and out, errors, time spent,
+ * the latest values). It is fed from an execution handle's `onDelivery` and
+ * `onError` (see `useRunTrace`) and read by the run log and the inspector.
+ *
+ * Like `LiveSignalStore`, it records synchronously and notifies at most once
+ * per frame, so a flow delivering thousands of messages a second costs one
+ * render per frame. The log is a ring buffer: memory stays bounded however
+ * long the run, while the statistics keep counting everything.
+ */
+
+/** How many log entries a trace keeps unless told otherwise. */
+declare const RUN_LOG_CAPACITY = 500;
+/** A message delivered on a connection. `at` is milliseconds since the run started. */
+interface RunDeliveryEntry {
+    readonly kind: 'delivery';
+    readonly seq: number;
+    readonly at: number;
+    readonly sourceNodeId: string;
+    readonly sourcePortId: string;
+    readonly targetNodeId: string;
+    readonly targetPortId: string;
+    readonly message: unknown;
+    /** How long the receiving node's handlers took, in milliseconds. */
+    readonly duration: number;
+}
+/** A node error. `at` is milliseconds since the run started. */
+interface RunErrorEntry {
+    readonly kind: 'error';
+    readonly seq: number;
+    readonly at: number;
+    readonly nodeId: string;
+    readonly error: unknown;
+}
+/** An input that ended (RFC 0001): every connection into it closed and its messages done. */
+interface RunEndedEntry {
+    readonly kind: 'ended';
+    readonly seq: number;
+    readonly at: number;
+    readonly nodeId: string;
+    readonly portId: string;
+}
+/** A node that finished (RFC 0001): its inputs ended and its outputs closed. */
+interface RunFinishedEntry {
+    readonly kind: 'finished';
+    readonly seq: number;
+    readonly at: number;
+    readonly nodeId: string;
+}
+/** A message a full `drop-oldest` connection dropped (RFC 0001). */
+interface RunDroppedEntry {
+    readonly kind: 'dropped';
+    readonly seq: number;
+    readonly at: number;
+    readonly sourceNodeId: string;
+    readonly sourcePortId: string;
+    readonly targetNodeId: string;
+    readonly targetPortId: string;
+    readonly message: unknown;
+}
+type RunLogEntry = RunDeliveryEntry | RunErrorEntry | RunEndedEntry | RunFinishedEntry | RunDroppedEntry;
+/** One node's activity during the run. */
+interface NodeRunSummary {
+    readonly received: number;
+    readonly sent: number;
+    readonly errors: number;
+    /** Time spent handling what it received, in milliseconds: in total and the longest once. */
+    readonly totalMs: number;
+    readonly maxMs: number;
+    readonly lastReceived: unknown;
+    readonly lastSent: unknown;
+    /** Messages a full `drop-oldest` connection into this node dropped. */
+    readonly dropped: number;
+    /** Whether the node has finished: its inputs ended and its outputs closed. */
+    readonly finished: boolean;
+}
+interface RunTraceOptions {
+    /** How many log entries to keep. Default `RUN_LOG_CAPACITY`. */
+    readonly capacity?: number;
+    /** Clock and frame scheduler; injected in tests. */
+    readonly deps?: LiveSignalStoreDeps;
+}
+type Listener = () => void;
+declare class RunTrace {
+    private readonly capacity;
+    private readonly deps;
+    /** The log as a ring: `ring[(head + i) % capacity]` is the i-th oldest entry. */
+    private readonly ring;
+    private head;
+    private droppedCount;
+    private seq;
+    private startedAt;
+    private readonly stats;
+    private readonly listeners;
+    /** Bumped by every change; the entries cache follows it. */
+    private revision;
+    /** Bumped once per notified frame; what subscribers compare. */
+    private version;
+    private frame;
+    /** The entries as an array, rebuilt only after a change. */
+    private entriesCache;
+    private entriesRevision;
+    constructor(options?: RunTraceOptions);
+    /** Begins a run: clears everything and times entries from now. */
+    start(): void;
+    /** Forgets the log and the statistics. */
+    clear(): void;
+    recordDelivery(event: INodeDeliveryEvent): void;
+    recordError(event: INodeErrorEvent): void;
+    recordEnded(event: INodeEndedEvent): void;
+    recordFinished(event: INodeFinishedEvent): void;
+    recordDropped(event: INodeDroppedEvent): void;
+    /** The log, oldest first. The same array is returned until something changes. */
+    entries(): readonly RunLogEntry[];
+    /** A node's statistics, or `undefined` when it has done nothing this run. */
+    statsOf(nodeId: string): NodeRunSummary | undefined;
+    /** How many entries the log has let go of to stay within its capacity. */
+    get dropped(): number;
+    /** Changes once per notified frame; a snapshot for `useSyncExternalStore`. */
+    getVersion(): number;
+    subscribe(listener: Listener): () => void;
+    private append;
+    private nextSeq;
+    private elapsed;
+    private statsFor;
+    /** Schedules one notification for the next frame, however many changes come before it. */
+    private changed;
+}
+/** Whether `entry` concerns `nodeId`: either end of a delivery, or the node of an error. */
+declare function involves(entry: RunLogEntry, nodeId: string): boolean;
+
+/**
+ * React glue for `RunTrace`. A host provides one trace for the editor; the run
+ * log and the inspector read it through `useRunTraceVersion`, which changes at
+ * most once per frame, so a busy flow costs one render per frame.
+ */
+
+interface RunTraceProviderProps {
+    readonly trace: RunTrace;
+    readonly children: ReactNode;
+}
+declare function RunTraceProvider({ trace, children }: RunTraceProviderProps): ReactElement;
+/** The trace, or `null` when there is no provider (run views stay hidden). */
+declare function useRunTraceStore(): RunTrace | null;
+/** Re-renders the caller when the trace changes; returns its version (0 without a trace). */
+declare function useRunTraceVersion(trace: RunTrace | null): number;
+
+/**
+ * `useRunTrace` — feeds a run's deliveries and errors into a `RunTrace`. Each
+ * new handle starts a new run in the trace; when the handle goes away (the
+ * run stopped) the trace keeps what it recorded, so the log can still be read.
+ * A handle that cannot trace (no `onDelivery`) still feeds its errors.
+ */
+
+declare function useRunTrace(trace: RunTrace, handle: IExecutionHandle | undefined): void;
+
+/**
+ * `useFollowScroll` — a scrolling list that stays on its newest entry, as a
+ * terminal does. While following, every render scrolls it to the bottom. When
+ * the reader scrolls back to read, following stops so the view holds still;
+ * scrolling back to the bottom (or `setFollow(true)`) resumes it.
+ */
+
+/** Within this many pixels of the bottom, the list counts as at the bottom. */
+declare const FOLLOW_SLACK_PX = 24;
+interface FollowScroll<T extends HTMLElement> {
+    /** Attach to the scrolling element. */
+    readonly ref: RefObject<T | null>;
+    /** Attach as the scrolling element's `onScroll`. */
+    readonly onScroll: (event: UIEvent<T>) => void;
+    readonly follow: boolean;
+    readonly setFollow: (follow: boolean) => void;
+}
+declare function useFollowScroll<T extends HTMLElement>(): FollowScroll<T>;
+
+/**
+ * `RunLog` — the editor's live console. Every message the running graph
+ * delivers, and every node error, as it happens: when (since the run
+ * started), from which node and port to which, a preview of the value, and
+ * how long the receiving node took. Choosing a row selects its node, and the
+ * log can follow the selection. It reads the `RunTrace` from
+ * `<RunTraceProvider>` and renders nothing without one.
+ */
+
+interface RunLogProps {
+    readonly core: EditorCore;
+    /** Also called when a row is chosen, after its node is selected (e.g. to bring it into view). */
+    readonly onSelectNode?: (nodeId: string) => void;
+    /** The log's name, shown at the start of its header and used as its accessible name. */
+    readonly title?: string;
+    /** Shown at the start of the header in place of the title, e.g. the host's tabs. */
+    readonly leading?: ReactNode;
+}
+declare function RunLog({ core, onSelectNode, title, leading }: RunLogProps): ReactElement | null;
+
+/**
+ * `NodeRunStats` — what one node did in the current run: messages in and out,
+ * errors, the average and longest time it spent on a message, and the latest
+ * values. Shown in the inspector when the host provides a `RunTrace`.
+ */
+
+declare function NodeRunStats({ nodeId }: {
+    readonly nodeId: string;
+}): ReactElement | null;
+
+/**
+ * `ConnectionInspector` — the inspector for one selected connection: where it
+ * runs from and to, and its back-pressure (RFC 0001): whether it is bounded,
+ * its capacity, and whether a full connection drops its oldest message.
+ * Changes are undoable commands.
+ */
+
+declare function ConnectionInspector({ core, edgeId }: {
+    readonly core: EditorCore;
+    readonly edgeId: EdgeId;
+}): ReactElement | null;
+
+/**
+ * `useEdgeBounds` — one connection and its bounds (RFC 0001), kept current
+ * as commands change it, with a setter that commits an undoable
+ * `SetEdgeBoundsCommand`.
+ */
+
+interface EdgeBoundsHandle {
+    /** The edge, or undefined if it no longer exists. */
+    readonly edge: EditorEdge | undefined;
+    /** Bound the connection, or unbound it, as one undoable step. */
+    readonly setBounds: (bounds: EdgeBounds) => void;
+}
+declare function useEdgeBounds(core: EditorCore, edgeId: EdgeId | undefined): EdgeBoundsHandle;
+
+/**
+ * A connection's bounds (RFC 0001) as the editor shows and edits them: the
+ * fields of the inspector's Connection section, the bounds a change to one of
+ * them makes, and the label a bounded edge carries.
+ */
+
+/** The capacity a connection gets when it is first bounded: JavaFBP's production default. */
+declare const DEFAULT_EDGE_CAPACITY = 10;
+/** The inspector's fields for a connection with `bounds`. */
+declare function boundsFields(bounds: EdgeBounds): ParamField[];
+/** The bounds after the inspector's field `key` is set to `value`. */
+declare function nextBounds(bounds: EdgeBounds, key: string, value: ParamValue): EdgeBounds;
+/** A bounded edge's label, in FBP notation: `[4]`; `undefined` when unbounded. */
+declare function capacityLabel(bounds: EdgeBounds): string | undefined;
+
+/**
+ * `previewValue` — a short, single-line text for any value a node sends, for
+ * the run log and the inspector. Messages are `unknown`: they can be huge,
+ * cyclic, class instances, or objects whose getters throw, so the preview
+ * never throws, never prints a function's source, and is cut to a limit.
+ */
+/** The longest preview, in characters, unless a caller asks for another. */
+declare const PREVIEW_LENGTH = 120;
+/** A single-line preview of `value`, at most `maxLength` characters. */
+declare function previewValue(value: unknown, maxLength?: number): string;
+
+/** Short, aligned text for the times the run views show. */
+/** How long a delivery took: `<0.01 ms`, `0.12 ms`, `4.6 ms`, `42 ms`, `1.52 s`. */
+declare function formatDuration(ms: number): string;
+/** When something happened, in seconds since the run started: `0.013s`. */
+declare function formatElapsed(ms: number): string;
+
+/**
+ * `LivePulse` — one flash on a node each time it runs during a live run. The
+ * pulse count from the live store keys the element, so every new count
+ * mounts a fresh element and its CSS animation plays once: the node flashes
+ * exactly as often as it actually ran (per frame at most). Place it as the
+ * first child of a node's rounded, positioned root.
+ */
+
+declare function LivePulse({ nodeId }: {
+    readonly nodeId: string;
+}): ReactElement | null;
+
+export { AssetGrid, AssetNodeChrome, CanvasChrome, CanvasDock, Cheatsheet, ClearIcon, ConnectionInspector, DEFAULT_EDGE_CAPACITY, DEFAULT_MIN_CANVAS_HEIGHT, DiagnosticBadge, EditorShell, EditorUIThemeProvider, EmptyState, FOLLOW_SLACK_PX, FOOTER_KEY_STEP, FilterIcon, FlowEdge, FollowIcon, FooterResizer, HlangNode, InspectorPanel, KIND_ROLE, KIND_TOKEN, LivePulse, LiveSignalProvider, LiveSignalStore, NodeBodySlot, NodeChrome, NodeContextMenu, NodeInteractionProvider, NodeRunStats, NodeSearch, OutlineTree, PREVIEW_LENGTH, PanelAction, PanelHead, ParamForm, PillNodeChrome, PortRow, PositionPanel, PreviewPanel, RUN_LOG_CAPACITY, RailTabs, ReadOnlyBadge, RunButton, RunLog, RunTrace, RunTraceProvider, SELF_LOOP_CLEARANCE, SELF_LOOP_RADIUS, SignalBar, TOKEN_NAMES, ToastProvider, ToolCluster, Toolbar, ToolbarGhostButton, ToolbarStat, UndoRedo, boundsFields, capacityLabel, clampFooter, connectableCandidates, createHlangFlowTypes, createTheme, defaultLiveDeps, deriveParamSchema, descriptorCandidates, footerBounds, formatDuration, formatElapsed, fuzzyRank, fuzzyScore, involves, isEditableTarget, nextBounds, previewValue, resizeByKey, searchNodes, selfLoopPath, toggleCollapsed, tokenVar, useEdgeBounds, useEdgeFlowing, useEdgePulse, useEditorHotkeys, useFollowScroll, useFooterResize, useLiveSignalStore, useLiveSignals, useNodeContextMenu, useNodeInteraction, useNodeLiveState, useNodeParams, useNodePulse, useNodeSearch, useNodeSearchTriggers, useRunTrace, useRunTraceStore, useRunTraceVersion, useToast };
+export type { AssetGridProps, AssetItem, AssetNodeChromeProps, CanvasChromeProps, CanvasDockProps, CanvasMode, CheatsheetProps, ConnectableResult, ConnectionEnd, ContextMenuItem, DeliverySignal, DiagnosticBadgeProps, EdgeBoundsHandle, EdgeIndexEntry, EditorHotkeysOptions, EditorShellProps, EditorUIThemeProviderProps, EmptyStateProps, FollowScroll, FooterBounds, FooterResize, FooterResizeOptions, FooterResizerProps, FooterSize, FuzzyCandidate, FuzzyMatch, FuzzyResult, HlangFlowTypes, InspectorPanelProps, LiveSignalProviderProps, LiveSignalStoreDeps, NodeBodySlotProps, NodeCandidate, NodeChromeProps, NodeContextMenuController, NodeContextMenuProps, NodeContextMenuState, NodeInteraction, NodeInteractionProviderProps, NodeLiveState, NodeParamsHandle, NodeRunSummary, NodeSearchController, NodeSearchProps, NodeSearchResult, NodeSearchResultView, NodeSearchState, NodeSearchTriggerOptions, NodeSearchTriggers, OutlineTreeProps, PanelActionProps, PanelHeadProps, ParamField, ParamFieldBase, ParamFormProps, PendingConnection, PillNodeChromeProps, PointerPosition, PortRowProps, PositionPanelProps, PreviewPanelProps, RailTab, RailTabsProps, ReadOnlyBadgeProps, RunButtonProps, RunDeliveryEntry, RunErrorEntry, RunLogEntry, RunLogProps, RunTraceOptions, RunTraceProviderProps, SelfLoop, SelfLoopInput, ShortcutGroup, ShortcutRow, ThemeOverride, ToastApi, ToastProviderProps, TokenName, ToolClusterProps, ToolItem, ToolbarProps, TouchPositions, UndoRedoProps };