@hlang-tech/editor-ui 0.0.0-stage → 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,971 @@
+import { NodeKind, EditorNode, PortDescriptor, EditorCore, NodeId, Diagnostic, ParamValue, NodeDescriptor, ParamBag, Endpoint, IConnectionValidator, Point, IExecutionHandle } from '@hlang-tech/editor-core';
+import { CSSProperties, ReactNode, ReactElement, MouseEvent } from 'react';
+import { NodeProps, EdgeProps, NodeTypes, EdgeTypes, OnConnectStart, OnConnectEnd } from '@xyflow/react';
+import { HlangRFNode, HlangRFEdge } from '@hlang-tech/editor-react';
+
+/**
+ * Typed accessors for the design tokens. This module only NAMES the CSS custom
+ * properties declared in `tokens.css` — it never duplicates their values, so
+ * there is a single source of truth. Components reference tokens through here
+ * (e.g. `KIND_TOKEN[node.kind]`) instead of hardcoding hex values.
+ */
+
+/** The full set of token custom-property names (without the leading `--`). */
+declare const TOKEN_NAMES: readonly ["hl-void", "hl-void-2", "hl-surface", "hl-surface-2", "hl-line", "hl-line-strong", "hl-silver", "hl-silver-hi", "hl-silver-lo", "hl-spark", "hl-r", "hl-t", "hl-w", "hl-error", "hl-ink", "hl-ink-2", "hl-ink-3", "hl-font-ui", "hl-font-mono", "hl-r-sm", "hl-r-md", "hl-r-lg", "hl-r-pill", "hl-shadow-node", "hl-shadow-glass", "hl-glow-silver", "hl-ease"];
+/** A token name (without `--`), e.g. `'hl-silver'`. */
+type TokenName = (typeof TOKEN_NAMES)[number];
+/** `var(--<name>)` reference string for a token. */
+declare function tokenVar(name: TokenName): string;
+/** Maps a node kind to its color-temperature token reference. */
+declare const KIND_TOKEN: Record<NodeKind, string>;
+/** Human-readable role label per node kind (used in node headers). */
+declare const KIND_ROLE: Record<NodeKind, string>;
+
+/**
+ * Theming: a host overrides any subset of tokens by producing a CSS-variable
+ * style object with `createTheme(...)` and applying it (via
+ * `EditorUIThemeProvider` or directly on a wrapper element). Zero-runtime and
+ * SSR-safe — it is just inline custom properties.
+ */
+
+/**
+ * A partial override map from token name to CSS value. Values may be
+ * `undefined` (treated as "not overridden") so callers can pass conditional
+ * overrides without pre-filtering.
+ */
+type ThemeOverride = Partial<Record<TokenName, string | undefined>>;
+/**
+ * Build a style object that overrides the given tokens as inline custom
+ * properties. Apply it to a wrapping element to re-theme everything beneath.
+ *
+ * ```ts
+ * <div style={createTheme({ 'hl-silver': '#d8dce4' })}> … </div>
+ * ```
+ */
+declare function createTheme(overrides: ThemeOverride): CSSProperties;
+
+/**
+ * `EditorUIThemeProvider` — applies a token override to its subtree by wrapping
+ * children in an element carrying the inline custom properties from
+ * `createTheme`. Import `@hlang-tech/editor-ui/tokens.css` once at the app root
+ * for the base tokens; use this provider only to override.
+ */
+
+interface EditorUIThemeProviderProps {
+    readonly theme?: ThemeOverride;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly children: ReactNode;
+}
+declare function EditorUIThemeProvider({ theme, className, style, children, }: EditorUIThemeProviderProps): ReactElement;
+
+/**
+ * The R/T/W node component. A near-monochrome glass card whose personality
+ * comes from a thin kind-tinted signal bar and glowing ports; body content is
+ * an extension point (empty for generic nodes). Ports are laid out in two
+ * columns — inputs (I) left, outputs (O) right — each Handle anchored to its
+ * own row so the `@node/error` port never drifts. W nodes render no error port
+ * because their descriptor has none.
+ */
+
+/** Presentational node chrome, decoupled from React Flow for easy testing. */
+interface NodeChromeProps {
+    readonly node: EditorNode;
+    readonly selected?: boolean;
+    readonly body?: ReactNode;
+}
+declare function NodeChrome({ node, selected, body }: NodeChromeProps): ReactElement;
+/**
+ * The React Flow node component. Reads everything from `data.editorNode`, then
+ * DISPATCHES to the right dressing — all in editor-ui, with no change to the
+ * runtime (every case is just a node with ports):
+ *   - an image asset (params.imageUrl)  → {@link AssetNodeChrome} (framed photo)
+ *   - anything else                      → {@link PillNodeChrome} (nover capsule)
+ * The verbose port-board {@link NodeChrome} stays available as a future
+ * "expanded" view.
+ */
+declare function HlangNode({ data, selected }: NodeProps<HlangRFNode>): ReactElement;
+
+/**
+ * `AssetNode` — a source node dressed as a real image asset.
+ *
+ * Architecturally this is just an R node: to the runtime it has output ports and
+ * emits its image (its `params.imageUrl`). editor-ui is free to DRESS it as a
+ * framed photograph — a frosted-glass card whose hero is the image itself — with
+ * no change to the input/output contract. This is the layering: the bottom is an
+ * input→output DAG; this layer decides what the node looks like.
+ *
+ * Ports are reused verbatim (PortRow → React Flow Handle), so wiring behaves
+ * exactly like any other node; the output handle rides the image's right edge.
+ */
+
+interface AssetNodeChromeProps {
+    readonly node: EditorNode;
+    readonly selected?: boolean;
+}
+declare function AssetNodeChrome({ node, selected }: AssetNodeChromeProps): ReactElement;
+
+/**
+ * `PillNode` — the default dressing for a non-asset node: a nover-style capsule.
+ *
+ * To the runtime this is still an ordinary R/T/W node with ports; editor-ui just
+ * dresses it as a rounded pill — a kind-tinted domain dot, the name, and a
+ * status dot — with the ports HIDDEN at rest and revealed on hover/selection.
+ * The picture, not the plumbing. The verbose port-board (`NodeChrome`) remains
+ * available as an "expanded" view for later.
+ *
+ * Ports reuse `PortRow` (so wiring is identical); the pill styles the handles
+ * to ride its left/right edges as small silver dots.
+ */
+
+interface PillNodeChromeProps {
+    readonly node: EditorNode;
+    readonly selected?: boolean;
+}
+declare function PillNodeChrome({ node, selected }: PillNodeChromeProps): ReactElement;
+
+/**
+ * The thin, kind-tinted bar across the top of a node — the node's kind
+ * expressed with restraint (no large color fills). Reads `--hl-kind` set by the
+ * node's kind class.
+ */
+
+declare function SignalBar(): ReactElement;
+
+/**
+ * A single port row: a React Flow `Handle` anchored to this row (so it centers
+ * on its own label, never drifting) plus the port's mono label. Renders the
+ * live/value distinction (filled vs hollow handle) and the error hue.
+ */
+
+interface PortRowProps {
+    readonly port: PortDescriptor;
+}
+declare function PortRow({ port }: PortRowProps): ReactElement;
+
+/**
+ * The node-body extension point. In M-UI-1 this renders nothing (generic nodes
+ * stay clean R/T/W cards). M-UI-5 wires it to the NodeBodyRegistry so a host
+ * application can render custom content — image/video previews, inline
+ * widgets — per node `code`/`kind` without editor-ui knowing anything about it.
+ */
+
+interface NodeBodySlotProps {
+    readonly node: EditorNode;
+    /** Custom body content, resolved by the host/registry. Empty renders nothing. */
+    readonly children?: ReactNode;
+}
+declare function NodeBodySlot({ children }: NodeBodySlotProps): ReactElement | null;
+
+/**
+ * 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) —
+ * 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,
+ * Background), a small glass label pill rides the edge midpoint — naming what
+ * the connection carries, the way nover labels its wires. The role is read from
+ * the source node's params (no change to editor-react's edge data).
+ */
+
+declare function FlowEdge(props: EdgeProps<HlangRFEdge>): ReactElement;
+
+/**
+ * One-line React Flow wiring: `createHlangFlowTypes()` returns the `nodeTypes`
+ * and `edgeTypes` maps to spread onto `<ReactFlow>`, binding hlang's R/T/W node
+ * kinds to `HlangNode` and the default edge to the flowing `FlowEdge`.
+ *
+ * ```tsx
+ * const { nodeTypes, edgeTypes } = createHlangFlowTypes();
+ * <ReactFlow nodeTypes={nodeTypes} edgeTypes={edgeTypes} {...useHlangFlow(core)} />
+ * ```
+ */
+
+interface HlangFlowTypes {
+    readonly nodeTypes: NodeTypes;
+    readonly edgeTypes: EdgeTypes;
+}
+/** Build the React Flow node/edge type maps for the hlang editor. */
+declare function createHlangFlowTypes(): HlangFlowTypes;
+
+/**
+ * `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).
+ */
+
+interface EditorShellProps {
+    /** Top toolbar region. */
+    readonly toolbar?: ReactNode;
+    /** Left region (node palette / outline). */
+    readonly left?: ReactNode;
+    /** Right region (inspector). */
+    readonly right?: ReactNode;
+    /** Center region — required; the host renders <ReactFlow> + <CanvasChrome>. */
+    readonly canvas: ReactNode;
+    /** Optional footer region (e.g. an output/console strip). */
+    readonly footer?: ReactNode;
+    readonly leftCollapsed?: boolean;
+    readonly rightCollapsed?: boolean;
+}
+declare function EditorShell({ toolbar, left, right, canvas, footer, leftCollapsed, rightCollapsed, }: EditorShellProps): ReactElement;
+
+/**
+ * The top toolbar: a thin glass bar with a brand wordmark on the left and an
+ * action cluster on the right. `Toolbar` is the presentational container;
+ * `UndoRedo` and `RunButton` are the standard actions wired to editor-core via
+ * editor-react hooks. Hosts may pass extra actions through `actions`.
+ */
+
+interface ToolbarProps {
+    /** Brand/title shown on the left. Defaults to a generic wordmark. */
+    readonly title?: ReactNode;
+    /** Centre slot — a tool cluster (add/frame/view), absolutely centred. */
+    readonly center?: ReactNode;
+    /** Action nodes rendered on the right (e.g. <UndoRedo/>, <RunButton/>). */
+    readonly actions?: ReactNode;
+}
+declare function Toolbar({ title, center, actions }: ToolbarProps): ReactElement;
+interface UndoRedoProps {
+    readonly core: EditorCore;
+}
+declare function UndoRedo({ core }: UndoRedoProps): ReactElement;
+interface RunButtonProps {
+    /**
+     * Invoked when clicked. This is a toggle: when `running` is true the button
+     * shows a Stop affordance, and the host is expected to stop the execution.
+     */
+    readonly onRun: () => void;
+    /** Whether an execution is currently in progress. */
+    readonly running?: boolean;
+    readonly runLabel?: string;
+    readonly stopLabel?: string;
+}
+declare function RunButton({ onRun, running, runLabel, stopLabel, }: RunButtonProps): ReactElement;
+/** A compact read-only stat pill (e.g. a node/vertex count) for the top bar. */
+declare function ToolbarStat({ label, value }: {
+    readonly label?: string;
+    readonly value: ReactNode;
+}): ReactElement;
+/** A secondary ghost button for the top bar (e.g. Invite). Presentational. */
+declare function ToolbarGhostButton({ children, onClick, title, }: {
+    readonly children: ReactNode;
+    readonly onClick?: () => void;
+    readonly title?: string;
+}): 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
+ * language. Purely presentational: the host supplies the items and their
+ * actions. Kept generic (no business/media concepts) so it stays an editor-ui
+ * primitive — a "frame", "add", or "view" tool is just an item with an icon.
+ */
+
+interface ToolItem {
+    readonly id: string;
+    readonly icon: ReactNode;
+    readonly title: string;
+    readonly onClick?: () => void;
+    readonly active?: boolean;
+    readonly disabled?: boolean;
+    /** Draw a thin divider before this item. */
+    readonly separatorBefore?: boolean;
+}
+interface ToolClusterProps {
+    readonly items: readonly ToolItem[];
+}
+declare function ToolCluster({ items }: ToolClusterProps): ReactElement;
+
+/**
+ * `CanvasChrome` — themed React Flow canvas furniture. Now just the dotted
+ * background: React Flow's default MiniMap and Controls are intentionally NOT
+ * rendered — a creation studio replaces them with our own centred `CanvasDock`
+ * (pan/zoom/add) so the canvas isn't cluttered with a stock topology-editor
+ * toolbar. Rendered as children of <ReactFlow>.
+ */
+
+interface CanvasChromeProps {
+    readonly background?: boolean;
+}
+declare function CanvasChrome({ background }: CanvasChromeProps): ReactElement;
+
+/**
+ * `CanvasDock` — the centred, bottom-of-canvas floating toolbar of a creation
+ * studio: pointer/pan mode, add-node, and zoom controls, in the black/silver
+ * glass language. It replaces React Flow's default corner Controls + MiniMap
+ * with one calm, centred dock.
+ *
+ * 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).
+ */
+
+/** Interaction mode the canvas is in — left-drag selects, or left-drag pans. */
+type CanvasMode = 'select' | 'pan';
+interface CanvasDockProps {
+    /** Current zoom as a fraction (1 = 100%). */
+    readonly zoom: number;
+    readonly onZoomIn: () => void;
+    readonly onZoomOut: () => void;
+    readonly onFitView: () => void;
+    /** Open the node search to add a node. */
+    readonly onAdd: () => void;
+    /** Current interaction mode + setter (left-drag selects vs pans). */
+    readonly mode: CanvasMode;
+    readonly onModeChange: (mode: CanvasMode) => void;
+    /** Undo/redo — colocated with the canvas tools rather than the top bar. */
+    readonly onUndo: () => void;
+    readonly onRedo: () => void;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+}
+declare function CanvasDock({ zoom, onZoomIn, onZoomOut, onFitView, onAdd, mode, onModeChange, onUndo, onRedo, canUndo, canRedo, }: CanvasDockProps): ReactElement;
+
+/**
+ * `EmptyState` — a quiet, centered hint shown over an empty canvas. Purely
+ * presentational; the host decides when to render it (e.g. when the graph has
+ * no nodes). Non-interactive so it never blocks canvas gestures.
+ */
+
+interface EmptyStateProps {
+    readonly title?: ReactNode;
+    readonly hint?: ReactNode;
+}
+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);
+ * otherwise it shows an empty/summary state. This is the unified control center
+ * (nover.studio's model) over hlang's headless core.
+ */
+
+interface InspectorPanelProps {
+    readonly core: EditorCore;
+    /** Shown when no single node is selected. */
+    readonly emptyState?: ReactNode;
+}
+declare function InspectorPanel({ core, emptyState }: InspectorPanelProps): ReactElement;
+
+/**
+ * `OutlineTree` — the left-rail outline: a two-level GROUPING, not a tree.
+ *
+ * hlang's graph is a DAG (R/T/W nodes, O->I edges, T<->T feedback allowed), so
+ * there is no parent/child hierarchy to render. Instead we group by weakly-
+ * connected component (`GraphTopology.components()`): each component is one
+ * expandable "Flow N" container, and its member nodes are listed FLAT — they are
+ * peers. The real relationships between nodes (edges, fan-in/out) are shown on
+ * the canvas, never faked here as nesting. So: the outline expresses BELONGING
+ * (which Flow a node is in); the canvas expresses DATA FLOW.
+ *
+ * Rows carry per-type icons, a diagnostic marker, hover-revealed visible/lock
+ * controls, and a solid silver highlight when selected. Clicking a node selects
+ * and focuses it. Visibility/lock are per-node view state via `useViewState`.
+ */
+
+interface OutlineTreeProps {
+    readonly core: EditorCore;
+    readonly onFocus?: (id: NodeId) => void;
+}
+declare function OutlineTree({ core, onFocus }: OutlineTreeProps): ReactElement;
+
+/**
+ * `PreviewPanel` — a framed preview of a result image. Generic: the host passes
+ * an image URL + title (and optional status), and it renders a glass-framed
+ * hero card. In the creator flow this is the "output" of the graph — the render
+ * — completing the素材→intent→result narrative. editor-ui only draws it; what
+ * the image IS (a render, a still, a mock) is the host's business.
+ */
+
+interface PreviewPanelProps {
+    readonly imageUrl?: string;
+    readonly title?: string;
+    readonly status?: string;
+}
+declare function PreviewPanel({ imageUrl, title, status }: PreviewPanelProps): 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
+ * presentational and generic: the host supplies the tab ids/labels and owns the
+ * active state, so this is an editor-ui primitive with no coupling to what the
+ * tabs contain.
+ */
+
+interface RailTab {
+    readonly id: string;
+    readonly label: string;
+}
+interface RailTabsProps {
+    readonly tabs: readonly RailTab[];
+    readonly active: string;
+    readonly onChange: (id: string) => void;
+}
+declare function RailTabs({ tabs, active, onChange }: RailTabsProps): ReactElement;
+
+/**
+ * `AssetGrid` — a thumbnail grid of render results / source images (the nover
+ * "Renders" / "Assets" panel). Purely presentational: the host supplies image
+ * URLs; clicking one calls back. editor-ui stays generic — an "asset" here is
+ * just an image with an id, no media/model business concept.
+ */
+
+interface AssetItem {
+    readonly id: string;
+    readonly url: string;
+    readonly label?: string;
+}
+interface AssetGridProps {
+    readonly items: readonly AssetItem[];
+    readonly onSelect?: (id: string) => void;
+    /** Shown when there are no assets yet. */
+    readonly emptyHint?: string;
+}
+declare function AssetGrid({ items, onSelect, emptyHint }: AssetGridProps): ReactElement;
+
+/**
+ * `PositionPanel` — the "Position" section of the inspector (nover-style): a
+ * 3×2 align cluster, the selected node's X/Y, and a Pin toggle. Generic geometry
+ * only — alignment/coordinates carry no media/model concept, so this belongs in
+ * editor-ui. All moves go through the command service (undoable) via `useRename`-
+ * style command execution; nothing mutates the model directly.
+ *
+ * With a single selected node it shows and edits that node's position. With
+ * multiple, the align actions distribute them against their common bounding box.
+ */
+
+interface PositionPanelProps {
+    readonly core: EditorCore;
+    /**
+     * Optional LIVE position reader (canvas coords) for a node. A drag commits to
+     * the model only on drag-stop, so to show X/Y updating DURING a drag the host
+     * supplies the canvas's in-flight position (e.g. React Flow's node.position).
+     * When omitted, the committed model position is shown. Keeping this a callback
+     * means editor-ui never imports React Flow — the binding stays in the host.
+     */
+    readonly livePosition?: (id: string) => {
+        x: number;
+        y: number;
+    } | undefined;
+}
+declare function PositionPanel({ core, livePosition }: PositionPanelProps): ReactElement;
+
+/**
+ * `DiagnosticBadge` — a single edit-time diagnostic marker (error/warning icon +
+ * tooltip), shared by the node chrome and the outline so the severity→icon and
+ * severity→class mapping lives in ONE place. `variant` only sets the wrapper
+ * class prefix so each host can size/position it via its own CSS.
+ */
+
+interface DiagnosticBadgeProps {
+    readonly diagnostic: Diagnostic;
+    /** Class-prefix so hosts style it in context (e.g. 'hl-pill-diag'). */
+    readonly variant: string;
+    readonly size?: number;
+}
+declare function DiagnosticBadge({ diagnostic, variant, size }: DiagnosticBadgeProps): ReactElement;
+
+/**
+ * Schema-driven property editing. A node's editable parameters are derived into
+ * a strongly-typed `ParamField[]` (zero `any`), which the inspector renders as
+ * form controls. Field types are inferred from each default value's runtime
+ * type — the only metadata a `NodeDescriptor` carries today (`defaultParams`).
+ */
+
+/** Common fields on every derived form field. */
+interface ParamFieldBase {
+    readonly key: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+/** A discriminated union of the built-in form field types (zero `any`). */
+type ParamField = (ParamFieldBase & {
+    readonly type: 'text';
+    readonly value: string;
+}) | (ParamFieldBase & {
+    readonly type: 'textarea';
+    readonly value: string;
+}) | (ParamFieldBase & {
+    readonly type: 'number';
+    readonly value: number;
+}) | (ParamFieldBase & {
+    readonly type: 'toggle';
+    readonly value: boolean;
+}) | (ParamFieldBase & {
+    readonly type: 'custom';
+    readonly fieldType: string;
+    readonly value: ParamValue;
+});
+/**
+ * Derive the ordered form schema for a node. Keys come from the descriptor's
+ * `defaultParams` (the canonical param set); current values come from the live
+ * node, falling back to the default.
+ */
+declare function deriveParamSchema(descriptor: NodeDescriptor, node: EditorNode): readonly ParamField[];
+
+/**
+ * `ParamForm` — renders a derived `ParamField[]` as compact, pro-tool form
+ * controls. Text/number inputs commit on blur or Enter (not per keystroke, so
+ * one edit is one undo entry); toggles commit immediately. `custom` fields are
+ * a placeholder until the ParamFieldRegistry lands (M-UI-5).
+ */
+
+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;
+}
+declare function ParamForm({ fields, onCommit }: ParamFormProps): ReactElement;
+
+/**
+ * `useNodeParams` — reactively read a node's params and commit edits through the
+ * command service (so every change is undoable). Re-reads on the `nodeChanged`
+ * event via a version counter (the same pattern editor-react's selectors use).
+ */
+
+interface NodeParamsHandle {
+    /** The node, or undefined if it no longer exists. */
+    readonly node: EditorNode | undefined;
+    /** Set a single param, committing an undoable UpdateParamsCommand. */
+    setParam(key: string, value: ParamValue): void;
+    /** Replace the whole param bag, committing an undoable UpdateParamsCommand. */
+    setParams(next: ParamBag): void;
+}
+declare function useNodeParams(core: EditorCore, nodeId: NodeId | undefined): NodeParamsHandle;
+
+/**
+ * Small, dependency-free fuzzy matcher for the node search palette. Pure
+ * functions — the only logic in editor-ui that carries its own unit tests
+ * (behavior, not pixels). Ranks candidates by subsequence match quality:
+ * contiguous and word-boundary matches score higher, earlier matches score
+ * higher, shorter targets break ties.
+ */
+/** A scored match with the matched character positions (for highlighting). */
+interface FuzzyMatch {
+    readonly score: number;
+    readonly positions: readonly number[];
+}
+/**
+ * Score `query` against `target` as a case-insensitive subsequence match.
+ * Returns `null` when `target` does not contain `query` as a subsequence.
+ * An empty query matches everything with score 0 (stable, no reordering).
+ */
+declare function fuzzyScore(query: string, target: string): FuzzyMatch | null;
+/** A candidate to rank, carrying an opaque payload of type `T`. */
+interface FuzzyCandidate<T> {
+    readonly text: string;
+    readonly value: T;
+}
+/** A ranked result: the candidate plus its match. */
+interface FuzzyResult<T> {
+    readonly value: T;
+    readonly text: string;
+    readonly match: FuzzyMatch;
+}
+/**
+ * Rank candidates against a query, best first. Non-matching candidates are
+ * dropped. With an empty query, candidates are returned in their original order.
+ */
+declare function fuzzyRank<T>(query: string, candidates: readonly FuzzyCandidate<T>[]): readonly FuzzyResult<T>[];
+
+/**
+ * Pure model behind the node-search palette. No React, no DOM.
+ *
+ * Two responsibilities:
+ *   1. Turn the design-time registry into fuzzy-searchable candidates and rank
+ *      them against a query (`descriptorCandidates` + `searchNodes`).
+ *   2. When the palette is opened by releasing a dangling connection into empty
+ *      space, offer ONLY nodes that can legally complete that connection, and
+ *      remember which port on each closes it (`connectableCandidates`). The
+ *      legality decision is delegated to the core `IConnectionValidator` — this
+ *      module never re-encodes hlang's connection rules.
+ */
+
+/** A registry descriptor made searchable, keyed by its display name. */
+type NodeCandidate = FuzzyCandidate<NodeDescriptor>;
+/** A ranked search result carrying the matched descriptor. */
+type NodeSearchResult = FuzzyResult<NodeDescriptor>;
+/** Build fuzzy candidates from registry descriptors (display-name keyed). */
+declare function descriptorCandidates(descriptors: readonly NodeDescriptor[]): readonly NodeCandidate[];
+/** Rank descriptors against `query`, best first (empty query keeps order). */
+declare function searchNodes(query: string, descriptors: readonly NodeDescriptor[]): readonly NodeSearchResult[];
+/**
+ * A connection left dangling in empty space. `fromEndpoint` is the port the
+ * user dragged from and `fromPort` its resolved descriptor; `direction` says
+ * whether that endpoint is the connection's source (an output, needing a
+ * target) or its target (an input, needing a source). The palette will create a
+ * node and wire the missing side.
+ */
+interface PendingConnection {
+    readonly fromEndpoint: Endpoint;
+    /** Descriptor of the port the drag started from (resolved from the model). */
+    readonly fromPort: PortDescriptor;
+    readonly direction: 'from-source' | 'from-target';
+}
+/**
+ * A search result augmented with the specific port on the candidate node that
+ * would complete a pending connection.
+ */
+interface ConnectableResult {
+    readonly candidate: NodeSearchResult;
+    /** The port id on the (future) new node that closes the connection. */
+    readonly connectPortId: string;
+}
+/**
+ * Filter and rank descriptors to those that can legally complete `pending`,
+ * annotating each with the completing port. Legality is decided by the core
+ * validator's model-free `canLink` (direction + DTO): for a dangling source we
+ * ask canLink(danglingSource, candidatePort); for a dangling target we ask
+ * canLink(candidatePort, danglingTarget). No graph model is consulted, because
+ * the candidate node does not exist yet — legality here is purely a property of
+ * the two ports.
+ */
+declare function connectableCandidates(query: string, descriptors: readonly NodeDescriptor[], pending: PendingConnection, validator: IConnectionValidator): readonly ConnectableResult[];
+
+/**
+ * `useNodeSearch` — palette state + commit logic for creating nodes by search.
+ *
+ * The palette can open in two modes:
+ *   - blank: create a free-standing node at a point (canvas double-click, `/`).
+ *   - from a released connection: create a node AND wire the dangling link to a
+ *     compatible port on it, as ONE undoable step.
+ *
+ * All mutation goes through the core command service; connection legality and
+ * edge ids come from the core (validator + id generator). This hook holds no
+ * graph rules of its own.
+ */
+
+/** Where and how the palette is currently open. */
+interface NodeSearchState {
+    /** Screen-space anchor for rendering the floating panel. */
+    readonly screen: Point;
+    /** Flow-space position where the created node will be placed. */
+    readonly flow: Point;
+    /** Set when opened by releasing a dangling connection. */
+    readonly pending?: PendingConnection;
+}
+/** The palette controller returned by the hook. */
+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;
+    /** Open the palette to complete a released connection. */
+    openFromConnection(screen: Point, flow: Point, pending: PendingConnection): void;
+    /** Close the palette without creating anything. */
+    close(): void;
+    /**
+     * Rank registry descriptors for the current query and open mode. In blank
+     * mode every node is offered; in connection mode only nodes that can legally
+     * complete the pending link are offered.
+     */
+    results(query: string): readonly NodeSearchResultView[];
+    /** Create the chosen node (and wire the pending link, if any), then close. */
+    commit(result: NodeSearchResultView): void;
+}
+/**
+ * A ranked result as the palette renders it: the fuzzy match plus, in
+ * connection mode, the port on the new node that completes the link.
+ */
+interface NodeSearchResultView {
+    readonly result: NodeSearchResult;
+    /** Present only in connection mode. */
+    readonly connectPortId?: string;
+}
+declare function useNodeSearch(core: EditorCore): NodeSearchController;
+
+/**
+ * `NodeSearch` — the floating command palette for creating nodes by fuzzy
+ * search. Rendered when the controller is open; anchored at the trigger point.
+ *
+ * Presentation only: it owns the query string, keyboard navigation, and match
+ * highlighting, and delegates ranking + creation to the `NodeSearchController`.
+ * Deep-space glass panel, electric-blue accent, kind-tinted result chips.
+ */
+
+interface NodeSearchProps {
+    readonly controller: NodeSearchController;
+}
+declare function NodeSearch({ controller }: NodeSearchProps): ReactElement | null;
+
+/**
+ * `useNodeSearchTriggers` — bridge React Flow gestures to the node-search
+ * palette. Returns handlers to spread onto `<ReactFlow>`:
+ *
+ *   - `onConnectStart` / `onConnectEnd`: when a link is dragged from a port and
+ *     released into empty space (not onto a handle), open the palette pre-filtered
+ *     to nodes that can complete that connection.
+ *   - `onPaneClick`: two clicks on the empty pane within `doubleClickMs` open a
+ *     blank palette. We use React Flow's first-class `onPaneClick` (which fires
+ *     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.
+ *
+ * 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`).
+ */
+
+/** Options for the trigger hook (injectable clock keeps it deterministic). */
+interface NodeSearchTriggerOptions {
+    /** Double-click detection window in ms. Defaults to 350. */
+    readonly doubleClickMs?: number;
+    /** Monotonic clock in ms. Defaults to `performance.now`. */
+    readonly now?: () => number;
+}
+/** Handlers to spread onto the `<ReactFlow>` element. */
+interface NodeSearchTriggers {
+    readonly onConnectStart: OnConnectStart;
+    readonly onConnectEnd: OnConnectEnd;
+    /** Attach to `<ReactFlow onPaneClick>`; a rapid second click opens the palette. */
+    onPaneClick(event: MouseEvent): void;
+}
+declare function useNodeSearchTriggers(core: EditorCore, search: NodeSearchController, options?: NodeSearchTriggerOptions): NodeSearchTriggers;
+
+/**
+ * `useEditorHotkeys` — global keyboard shortcuts for the editor canvas:
+ *
+ *   ⌘/Ctrl+Z         undo       ⌘/Ctrl+Shift+Z, ⌘/Ctrl+Y  redo
+ *   ⌘/Ctrl+C  copy   ⌘/Ctrl+V  paste   ⌘/Ctrl+X  cut   ⌘/Ctrl+D  duplicate
+ *   Delete / Backspace  delete
+ *
+ * Clipboard actions run through `useClipboard`; undo/redo drive the history
+ * service. Every action is a proper command, so it is itself undoable. The
+ * listener is on `window` but SUPPRESSED while a text input / textarea /
+ * contenteditable is focused, so typing never triggers a canvas action.
+ */
+
+/** True when focus is in an editable field, where shortcuts must NOT fire. */
+declare function isEditableTarget(target: EventTarget | null): boolean;
+declare function useEditorHotkeys(core: EditorCore): void;
+
+/**
+ * `useNodeContextMenu` — controller for the right-click node menu. Holds only
+ * where the menu is open and which node it targets; the menu ITEMS (labels,
+ * shortcuts, actions) are assembled by the consumer from clipboard/view-state
+ * actions, so this hook carries no graph rules.
+ */
+
+/** Where the menu is open and which node it targets. */
+interface NodeContextMenuState {
+    /** Screen-space anchor (the click point). */
+    readonly screen: Point;
+    /** 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;
+    close(): void;
+}
+declare function useNodeContextMenu(): NodeContextMenuController;
+
+/**
+ * `NodeContextMenu` — the right-click menu for a node. A black/silver glass
+ * panel matching the command palette's material and dismissal, listing actions
+ * the consumer supplies (duplicate/copy/cut/paste/delete/hide/lock). Presentation
+ * only: each item carries its own `onSelect`; this component owns positioning,
+ * keyboard navigation, and dismissal.
+ */
+
+/** One menu row. A separator is a bare `{ separator: true }`. */
+interface ContextMenuItem {
+    readonly id: string;
+    readonly label: string;
+    /** Optional keyboard-shortcut hint shown right-aligned (e.g. "⌘D"). */
+    readonly shortcut?: string;
+    /** Optional leading glyph. */
+    readonly icon?: ReactNode;
+    /** Destructive styling (e.g. Delete). */
+    readonly danger?: boolean;
+    /** Disabled rows are shown dim and are not selectable. */
+    readonly disabled?: boolean;
+    readonly onSelect: () => void;
+}
+interface NodeContextMenuProps {
+    readonly controller: NodeContextMenuController;
+    /** Build the items for the targeted node id (recomputed on open). */
+    readonly items: (nodeId: string) => readonly ContextMenuItem[];
+}
+declare function NodeContextMenu({ controller, items }: NodeContextMenuProps): ReactElement | null;
+
+/**
+ * `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
+ * 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;
+}
+interface NodeInteractionProviderProps {
+    readonly value: NodeInteraction;
+    readonly children: ReactNode;
+}
+declare function NodeInteractionProvider({ value, children, }: NodeInteractionProviderProps): ReactElement;
+declare function useNodeInteraction(): NodeInteraction;
+
+/**
+ * `Cheatsheet` — a keyboard-shortcut reference in the black/silver glass
+ * language. Toggled by the host (typically the `?` key). Presentation only: it
+ * takes an `open` flag and an `onClose`, and renders a grouped list of the
+ * editor's shortcuts so they are discoverable, not memorized.
+ */
+
+interface ShortcutRow {
+    readonly keys: string;
+    readonly label: string;
+}
+interface ShortcutGroup {
+    readonly title: string;
+    readonly rows: readonly ShortcutRow[];
+}
+interface CheatsheetProps {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    /** Groups to display; a sensible default set is used when omitted. */
+    readonly groups?: readonly ShortcutGroup[];
+}
+declare function Cheatsheet({ open, onClose, groups }: CheatsheetProps): ReactElement | null;
+
+/**
+ * `ToastProvider` / `useToast` — lightweight transient notifications in the
+ * black/silver glass language. A host wraps the app once; any component calls
+ * `useToast().show('Copied 3 nodes')` for a brief confirmation. Presentation
+ * only: it holds a small queue that auto-dismisses.
+ */
+
+interface ToastApi {
+    show(message: string): void;
+}
+interface ToastProviderProps {
+    readonly children: ReactNode;
+    /** Auto-dismiss delay in ms (default 2200). */
+    readonly duration?: number;
+}
+declare function ToastProvider({ children, duration }: ToastProviderProps): ReactElement;
+declare function useToast(): ToastApi;
+
+/**
+ * `LiveSignalStore` — the source of truth for a running graph's live visual
+ * state. It ingests activity/error signals, decays activity over a short
+ * window, and lets node/edge components subscribe to THEIR OWN id only.
+ *
+ * Design rationale (industrial-grade, no tricks):
+ *   - No global DOM scanning and no dependency on React Flow's private CSS
+ *     classes. Components read their state by id through `useSyncExternalStore`,
+ *     so only the components whose state actually flips re-render.
+ *   - Edge "flowing" state is computed from an injected edge index, not by
+ *     reaching into another layer's model at paint time.
+ *   - A single rAF loop advances decay and notifies only changed ids.
+ */
+/** 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. */
+interface EdgeIndexEntry {
+    readonly id: string;
+    readonly sourceNodeId: string;
+    readonly sourcePortId: string;
+    readonly isError: boolean;
+}
+/** Injected clock + scheduler so the store is deterministic and testable. */
+interface LiveSignalStoreDeps {
+    now(): number;
+    schedule(cb: () => void): number;
+    cancel(handle: number): void;
+}
+declare class LiveSignalStore {
+    private readonly deps;
+    /** nodeId -> last-active timestamp. */
+    private readonly nodeActiveAt;
+    /** nodeId set that errored during this run. */
+    private readonly erroredNodes;
+    /** edgeId -> last-flowing timestamp. */
+    private readonly edgeFlowAt;
+    /** Per-id listeners. */
+    private readonly nodeListeners;
+    private readonly edgeListeners;
+    /** Snapshot of last-emitted state per id, so we only notify on real change. */
+    private readonly lastNodeState;
+    private readonly lastEdgeFlowing;
+    /** Edges sourced by a given (nodeId@portId), for pulse -> edge mapping. */
+    private edgesBySourcePort;
+    private rafHandle;
+    private running;
+    constructor(deps?: LiveSignalStoreDeps);
+    /** Provide the current edge index (call whenever edges change). */
+    setEdgeIndex(edges: readonly EdgeIndexEntry[]): void;
+    /** Record a node emitting on an output port (drives node + edge activity). */
+    markActivity(nodeId: string, portId: 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;
+    /** Subscribe to a single edge's flowing state. */
+    subscribeEdge(edgeId: string, listener: Listener): () => void;
+    /** Current live state of a node. */
+    getNodeState(nodeId: string): NodeLiveState;
+    /** Whether an edge is currently flowing. */
+    isEdgeFlowing(edgeId: string): boolean;
+    private subscribe;
+    private ensureLoop;
+    private stopLoop;
+    /**
+     * Recompute every subscribed id's state, notify only those that changed, and
+     * report whether anything is still within its active window (so the loop can
+     * stop when the graph goes quiet).
+     */
+    private flushNotifications;
+}
+
+/**
+ * `useLiveSignals` — feed a running flow's activity/error signals into the
+ * LiveSignalStore, which node/edge components subscribe to by id. No global DOM
+ * access and no dependency on React Flow's private structure: the store is the
+ * single source of truth and components read their own state (see
+ * `LiveSignalContext`). Must be used within a `<LiveSignalProvider>`.
+ */
+
+/**
+ * Drive live visuals from an execution handle. Pass the handle returned by
+ * `core.execution.run(...)`; pass `undefined` to clear. Keeps the store's edge
+ * index in sync with the model so a source-port pulse lights the right edges.
+ *
+ * The store is taken from `<LiveSignalProvider>` context; pass `explicitStore`
+ * when the feeding component sits at or above the provider (so it and the
+ * subscribing components share one store).
+ */
+declare function useLiveSignals(core: EditorCore, handle: IExecutionHandle | undefined, explicitStore?: LiveSignalStore): void;
+
+/**
+ * React glue for the LiveSignalStore. A single store instance is provided via
+ * context; node/edge components subscribe to their own id through
+ * `useNodeLiveState` / `useEdgeFlowing` (each returns a primitive, so only the
+ * components whose state actually flips re-render — no global DOM scanning).
+ */
+
+interface LiveSignalProviderProps {
+    /** Optional external store; a fresh one is created if omitted. */
+    readonly store?: LiveSignalStore;
+    readonly children: ReactNode;
+}
+declare function LiveSignalProvider({ store, children }: LiveSignalProviderProps): ReactElement;
+/** Access the live store, or `null` when there is no provider (visuals off). */
+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;
+/** Subscribe to a single edge's flowing state. False when no store is present. */
+declare function useEdgeFlowing(edgeId: string): boolean;
+
+export { AssetGrid, type AssetGridProps, type AssetItem, AssetNodeChrome, type AssetNodeChromeProps, CanvasChrome, type CanvasChromeProps, CanvasDock, type CanvasDockProps, type CanvasMode, Cheatsheet, type CheatsheetProps, type ConnectableResult, type ContextMenuItem, DiagnosticBadge, type DiagnosticBadgeProps, type EdgeIndexEntry, EditorShell, type EditorShellProps, EditorUIThemeProvider, type EditorUIThemeProviderProps, EmptyState, type EmptyStateProps, FlowEdge, type FuzzyCandidate, type FuzzyMatch, type FuzzyResult, type HlangFlowTypes, HlangNode, InspectorPanel, type InspectorPanelProps, KIND_ROLE, KIND_TOKEN, LiveSignalProvider, type LiveSignalProviderProps, LiveSignalStore, type LiveSignalStoreDeps, NodeBodySlot, type NodeBodySlotProps, type NodeCandidate, NodeChrome, type NodeChromeProps, NodeContextMenu, type NodeContextMenuController, type NodeContextMenuProps, type NodeContextMenuState, type NodeInteraction, NodeInteractionProvider, type NodeInteractionProviderProps, type NodeLiveState, type NodeParamsHandle, NodeSearch, type NodeSearchController, type NodeSearchProps, type NodeSearchResult, type NodeSearchResultView, type NodeSearchState, type NodeSearchTriggerOptions, type NodeSearchTriggers, OutlineTree, type OutlineTreeProps, type ParamField, type ParamFieldBase, ParamForm, type ParamFormProps, type PendingConnection, PillNodeChrome, type PillNodeChromeProps, PortRow, type PortRowProps, PositionPanel, type PositionPanelProps, PreviewPanel, type PreviewPanelProps, type RailTab, RailTabs, type RailTabsProps, RunButton, type RunButtonProps, type ShortcutGroup, type ShortcutRow, SignalBar, TOKEN_NAMES, type ThemeOverride, type ToastApi, ToastProvider, type ToastProviderProps, type TokenName, ToolCluster, type ToolClusterProps, type ToolItem, Toolbar, ToolbarGhostButton, type ToolbarProps, ToolbarStat, UndoRedo, type UndoRedoProps, connectableCandidates, createHlangFlowTypes, createTheme, deriveParamSchema, descriptorCandidates, fuzzyRank, fuzzyScore, isEditableTarget, searchNodes, tokenVar, useEdgeFlowing, useEditorHotkeys, useLiveSignalStore, useLiveSignals, useNodeContextMenu, useNodeInteraction, useNodeLiveState, useNodeParams, useNodeSearch, useNodeSearchTriggers, useToast };