@erd-studio/renderer 0.1.4 → 0.4.0

package/dist/types/ErdCanvas.d.ts

@@ -1,9 +1,13 @@
 /**
  * ErdCanvas — the diagram as a self-contained, read-only React component.
  *
- * Renders a `DisplayDomain` the way the VS Code extension's canvas shows a
+ * Renders a `DisplaySubjectArea` the way the VS Code extension's canvas shows a
  * read-only domain: model nodes, FK edges, annotations, the minimap, the
- * detail panel a click on a model opens, and the legend. There are no editing
+ * detail panel a click on a model opens, the legend (only the entries the
+ * stage shown can draw) and, beside its button, the table and relationship
+ * counts. Closing the detail panel keeps the table selected, its
+ * relationships lit; a click on the empty canvas, or Escape, clears the
+ * selection. There are no editing
  * affordances (the canvas runs in viewer mode) and nothing is ever sent
  * anywhere.
  *
@@ -18,14 +22,23 @@
  * `onLayoutModifiedChange` reports whether the layout differs from the
  * domain's, and `resetLayout()` (through a ref) puts everything back.
  *
+ * Resting the pointer on a table previews what it connects to (the rest of
+ * the diagram fades) and the relationship lines of the hovered or clicked
+ * table carry moving direction arrows (`useHoverFocus`). Both are local,
+ * ephemeral presentation: nothing is posted and no prop is needed.
+ *
+ * Relationship lines are routed around the tables in one of two styles,
+ * `lineStyle` `curved` (the default) or `hops`; the reader cannot change it.
+ *
  * Derived from the extension webview's `EditorCanvas` (`webview/App.tsx`),
  * keeping its React Flow configuration.
  */
 import { type CSSProperties } from 'react';
-import type { DisplayDomain } from '@erd-studio/core';
+import type { DisplaySubjectArea } from '@erd-studio/core';
+import { type LineStyle } from './lib/edgeRouting/lineStyle.js';
 export interface ErdCanvasProps {
     /** The domain to render. It is shown read-only whatever its `readOnly` flag says. */
-    domain: DisplayDomain;
+    domain: DisplaySubjectArea;
     /** Let readers drag model and annotation nodes. Moves are never saved. Default false. */
     nodesDraggable?: boolean;
     /**
@@ -36,6 +49,21 @@ export interface ErdCanvasProps {
     onLayoutModifiedChange?: (modified: boolean) => void;
     /** Called once, when the first nodes have been measured and fitted into view. */
     onReady?: () => void;
+    /**
+     * Draw the diagram of a project with no dbt project: no stage colours on
+     * tables, lines or the selection ring (the layer badge carries the colour)
+     * and no Physical, ghost or comparison entries in the legend. Default
+     * false: the stage colours, as before.
+     */
+    logicalOnly?: boolean;
+    /**
+     * How relationship lines are drawn. Both route the lines around the tables:
+     * `curved` (the default) with soft curves, a halo where two lines cross and
+     * a faint dashed "x-ray" where a line has to pass under a table; `hops`
+     * with square corners and a small hop where two lines cross. Anything else
+     * reads as `curved`.
+     */
+    lineStyle?: LineStyle;
     className?: string;
     style?: CSSProperties;
 }
@@ -50,5 +78,5 @@ export interface ErdCanvasHandle {
  * model's columns, each column's data type). Objects with nothing missing are
  * reused as they are.
  */
-export declare function toRenderableDomain(domain: DisplayDomain): DisplayDomain;
+export declare function toRenderableSubjectArea(domain: DisplaySubjectArea): DisplaySubjectArea;
 export declare const ErdCanvas: import("react").ForwardRefExoticComponent<ErdCanvasProps & import("react").RefAttributes<ErdCanvasHandle>>;

package/dist/types/canvas/CanvasBackdrop.d.ts

@@ -1,6 +1,7 @@
 /**
- * The canvas backdrop: the dotted background and the minimap. Render it as a
- * child of `<ReactFlow>`.
+ * The canvas backdrop: the dotted background, the minimap and the line
+ * routing (`EdgeRouter`, the x-ray `EdgeOverlay`, `LayerLineColour`). Render
+ * it as a child of `<ReactFlow>`.
  */
 /** Minimap fill for annotation nodes, keyed by annotation colour. */
 export declare const ANNOTATION_MINIMAP_COLORS: Record<string, string>;

package/dist/types/canvas/EdgeRouting.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Line routing on the canvas. Render all three as children of `<ReactFlow>`
+ * (CanvasBackdrop does), in the editor and in the viewer alike: none of them
+ * posts to a host or shows an editing affordance.
+ *
+ * - `EdgeRouter` routes every FK line in one pass whenever a card moves, is
+ *   measured, or the line style changes, and puts the result in the canvas
+ *   store (`edgeRoutes`). `FkEdge` reads its own route from there. Each
+ *   canvas has its own routing engine (router memory and performance guard).
+ * - `EdgeOverlay` draws what has to sit above the cards: the x-ray stretches
+ *   of a line that passes under a table (the `curved` style).
+ * - `LayerLineColour` hands the diagram's layer colour to the CSS, which a
+ *   logical-only canvas lights the focused lines with (EdgeRouting.css).
+ */
+import './EdgeRouting.css';
+/**
+ * The diagram's own layer colour, as `--diagram-layer-color` on the React
+ * Flow root, so a logical-only canvas can light its focused lines with it
+ * (EdgeRouting.css). Cleared when the diagram has no layer colour: the lines
+ * then stay neutral grey.
+ */
+export declare function LayerLineColour(): null;
+/**
+ * Routes every FK line once per frame in which a card moved, was measured or
+ * the line style changed (and, for hops, when the zoom moves a quarter of a
+ * doubling: hops are sized for it). The engine is this canvas's own, and
+ * decides whether and where to route (see `createEdgeRoutingEngine`): a small
+ * diagram routes here, on the main thread; a larger one in the canvas's
+ * worker, whose answer arrives later through `onUpdate`; a slow diagram holds
+ * its routes while a card is dragged and routes again when the drag ends
+ * (`dragKey` changes back to empty).
+ */
+export declare function EdgeRouter(): null;
+/**
+ * The x-ray: every routed line that passes under a card is drawn again ABOVE
+ * the cards, as a fine dashed ghost in the line's own colour, with a portal
+ * ring where it dives under a border and where it comes back out. Only the
+ * `curved` line style computes tunnels; with `hops` this draws nothing.
+ *
+ * The ghost is the line's own `d` (so it sits exactly on the hidden line
+ * whatever the corner or crossing style) under two clips: the card boxes, and
+ * the boxes of the line's tunnels (`windows`). The second clip keeps out what
+ * `computeTunnels` deliberately dropped: a line's hook inside its own two
+ * nearly touching cards, or a rounded corner grazing a card.
+ *
+ * A line whose end stub sits inside another card (the two cards closer than
+ * 20 px) would leave its ghost dangling mid-card; a short `lead` carries it on
+ * to the anchor on its own card, so the reader sees where it plugs in.
+ *
+ * Calm by default, loud on demand: at rest the ghost is faint and the portals
+ * carry the message ("this line goes under here"); the lines of the hovered
+ * or selected table, or the selected line (`flowFocus` / `hoverFocus`), get a
+ * bright ghost; lines faded by a selection or by the hover preview fade their
+ * ghost almost away. Pointer-events none, no host posts: viewer-safe.
+ */
+export declare function EdgeOverlay(): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/canvas/useCanvasGraph.d.ts

@@ -4,17 +4,23 @@
  *
  *   - The transform effect rebuilds every node and edge when the domain (or
  *     the discrepancy overlay) changes, preserving measured sizes, the
- *     current selection and valid edge selections.
+ *     current selection and valid edge selections, and keeps the existing
+ *     object for every node and edge that came out the same
+ *     (`reuseUnchanged`), so a drag re-renders only what moved.
  *   - The overlay effect updates only the `dimmed` / `isExpanded` flags when
  *     selection, search or column expansion changes.
  *   - The handlers open the detail panel on a model click, select annotations,
  *     highlight an FK edge's columns and clear selection on a pane click.
  *
+ * Hover preview and the moving relationship arrows are `useHoverFocus`, a
+ * separate hook: it needs React Flow's store, and this one must keep working
+ * without a `ReactFlowProvider`. Hover never comes through the overlay pass.
+ *
  * Must run inside a `CanvasStoreProvider`.
  */
 import type { OnSelectionChangeFunc } from '@xyflow/react';
 import type { DiscrepancyReport } from '@erd-studio/core';
-import type { ModelFlowNode, FkFlowEdge, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
+import type { TableFlowNode, FkFlowEdge, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
 export interface UseCanvasGraphOptions {
     /** Whether the cross-stage discrepancy overlay is shown. */
     discrepancyVisible?: boolean;
@@ -24,12 +30,12 @@ export interface UseCanvasGraphOptions {
      * Called with the rebuilt nodes and edges each time the transform effect
      * runs, just before they are written to the store.
      */
-    onTransformed?: (nodes: (ModelFlowNode | AnnotationFlowNode)[], edges: (FkFlowEdge | AnnotationFlowEdge)[]) => void;
+    onTransformed?: (nodes: (TableFlowNode | AnnotationFlowNode)[], edges: (FkFlowEdge | AnnotationFlowEdge)[]) => void;
 }
 export interface UseCanvasGraphResult {
-    nodes: (ModelFlowNode | AnnotationFlowNode)[];
+    nodes: (TableFlowNode | AnnotationFlowNode)[];
     edges: (FkFlowEdge | AnnotationFlowEdge)[];
-    onNodeClick: (event: React.MouseEvent, node: ModelFlowNode | AnnotationFlowNode) => void;
+    onNodeClick: (event: React.MouseEvent, node: TableFlowNode | AnnotationFlowNode) => void;
     onEdgeClick: (event: React.MouseEvent, edge: FkFlowEdge | AnnotationFlowEdge) => void;
     onPaneClick: () => void;
     onSelectionChange: OnSelectionChangeFunc;

package/dist/types/canvas/useHoverFocus.d.ts

@@ -0,0 +1,64 @@
+/**
+ * useHoverFocus — hover a table to preview what it connects to, and keep the
+ * moving relationship arrows on the right lines.
+ *
+ * Rest the pointer on a table and, after a short hover-intent delay, it and
+ * its related tables stay bright while everything else fades, as a click
+ * does. Move away and the diagram, or whatever was clicked, comes back.
+ *
+ * Precedence:
+ *   1. Hover previews: while `hoverFocus` is set, the hovered neighbourhood is
+ *      bright and everything else is faded, over click and search dimming.
+ *   2. Leaving restores: hover never touches `data.dimmed`, so the click and
+ *      search state reappears exactly as it was.
+ *   3. The clicked table stays findable at half opacity while a hover fades it.
+ *   4. Arrows follow `flowFocus = hoverFocus ?? focus(clicked table | line)`.
+ *      A click selection's arrows settle (stand still, still pointing the
+ *      way) after `SELECTION_FLOW_SETTLE_MS`, so a table left selected does
+ *      not keep the canvas animating; a hover's arrows move while it lasts.
+ *   5. The hover preview lights only the hovered table's own lines, not the
+ *      lines between its neighbours (`ownLinesOnly`); a click keeps both.
+ *
+ * Render path: hover never rewrites the nodes or edges arrays (every
+ * `setEdges` re-renders every `FkEdge`). The store holds `CanvasFocus` sets,
+ * `flowClassName` on the React Flow root fades everything in CSS, and each
+ * table and line reads its own part with an O(1) selector that returns a
+ * primitive, so only the tables and lines whose part changed re-render.
+ *
+ * Ephemeral: `hoverFocus` / `flowFocus` are never persisted, posted to the
+ * host or written to a file, and there is no message type. The preview is not
+ * an editing affordance, so it works the same in viewer mode and on the
+ * read-only Physical tab (any future viewer gate: `viewer ? … : <upstream>`).
+ *
+ * Suppressed (checked at event time): any mouse button held, a pane drag or
+ * box selection, a viewport move (pan, wheel zoom, inertia), a column drag
+ * to create a relationship, an annotation link drag, an open context menu, a
+ * device without a fine hover pointer. The column and annotation drags and
+ * the context menu also clear a hover at once, so a drop target is never
+ * faded. A node drag freezes the focus until it stops; grabbing a table other
+ * than the hovered one moves the focus to it first, and dropping a table the
+ * focus is not on previews it (the pointer is still resting there).
+ *
+ * Lives apart from `useCanvasGraph` because it needs React Flow's store; both
+ * hosts call it inside their `ReactFlowProvider`. `useOnViewportChange` takes
+ * React Flow's single `onViewportChangeStart/End` slot: no host uses it.
+ */
+import { type NodeMouseHandler, type EdgeMouseHandler, type OnNodeDrag } from '@xyflow/react';
+import type { GraphNode, GraphEdge } from '../lib/nodeOverlays.js';
+export interface HoverFocusHandlers {
+    onNodeMouseEnter: NodeMouseHandler<GraphNode>;
+    onNodeMouseLeave: NodeMouseHandler<GraphNode>;
+    onEdgeMouseEnter: EdgeMouseHandler<GraphEdge>;
+    onEdgeMouseLeave: EdgeMouseHandler<GraphEdge>;
+    onNodeDragStart: OnNodeDrag<GraphNode>;
+    onNodeDragStop: OnNodeDrag<GraphNode>;
+}
+export interface UseHoverFocusResult {
+    /** Spread onto `<ReactFlow>`. Stable across renders. */
+    hoverHandlers: HoverFocusHandlers;
+    /** `className` for `<ReactFlow>`: `erd-flow`, plus `erd-flow--hover-focus` while a hover preview is on. */
+    flowClassName: string;
+}
+/** A click selection's arrows move this long, then stand still. */
+export declare const SELECTION_FLOW_SETTLE_MS = 6000;
+export declare function useHoverFocus(): UseHoverFocusResult;

package/dist/types/components/DetailPanel/AliasEditor.d.ts

@@ -1,5 +1,5 @@
 /**
- * AliasEditor — the "Table name" row of the detail panel's metadata.
+ * AliasEditor — the "Warehouse name" row of the detail panel's metadata.
  *
  * A model's name is its identity; its alias is the table dbt builds it as.
  * Setting one is how two layers can each have a `date` table: the models are
@@ -8,12 +8,26 @@
  * Read mode shows the table name (the model name, dimmed, when there is no
  * alias). Edit mode is a single input: Enter saves, Escape cancels, and an
  * empty value clears the alias.
+ *
+ * Without a dbt project (`dbtWording` false) the tooltip and hint say the
+ * same thing without naming dbt. The viewer always passes false: a page
+ * outside VS Code cannot know whether the project uses dbt.
  */
 interface AliasEditorProps {
     modelName: string;
     alias?: string;
     /** Physical stage and the viewer: show the value, offer no edit. */
     readOnly: boolean;
+    /**
+     * Name dbt in the tooltip and hint (default). False in a folder with no
+     * dbt project, where the alias is just the table's name in the warehouse,
+     * and always in the viewer.
+     */
+    dbtWording?: boolean;
 }
-export declare function AliasEditor({ modelName, alias, readOnly }: AliasEditorProps): import("react/jsx-runtime").JSX.Element;
+/** The edit-mode hint under the input. */
+export declare function aliasHint(dbtWording: boolean): string;
+/** The read-mode tooltip on the value. */
+export declare function aliasTitle(modelName: string, alias: string | undefined, dbtWording: boolean): string;
+export declare function AliasEditor({ modelName, alias, readOnly, dbtWording }: AliasEditorProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/components/DetailPanel/ColumnEditor.d.ts

@@ -5,8 +5,10 @@
  * Supports adding new columns and inline editing.
  * Uses ColumnRowEditor for consistent column row rendering.
  */
-import type { DisplayColumn } from '@erd-studio/core';
-import type { ModelRole } from '@erd-studio/core';
+import { type FieldsTable } from './FieldsSection.js';
+import type { DisplayColumn, FieldList } from '@erd-studio/core';
+import type { TableRole } from '@erd-studio/core';
+import type { ColumnFieldVisibility } from '../common/ColumnRowEditor.js';
 import './ColumnEditor.css';
 export interface ColumnEditorProps {
     modelName: string;
@@ -14,6 +16,20 @@ export interface ColumnEditorProps {
     /** Whether this model/stage is read-only. */
     readOnly?: boolean;
     /** Parent model's role — passed to column rows for conditional SCD/additive dropdowns. */
-    modelRole?: ModelRole;
+    modelRole?: TableRole;
+    /** The project's field list (`DisplaySubjectArea.fields`); the starting set when absent. */
+    fields?: FieldList;
+    /** No dbt project: the column Fields show no "from dbt" badge. */
+    logicalOnly?: boolean;
 }
-export declare function ColumnEditor({ modelName, columns, readOnly, modelRole }: ColumnEditorProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Which of a column's typed fields its row shows: those the field list
+ * names (and that suit the table's role), and any with a value.
+ */
+export declare function columnFieldVisibility(column: DisplayColumn, table: FieldsTable, list: FieldList): ColumnFieldVisibility;
+/**
+ * A read-only row (the viewer, the physical stage) shows only the typed
+ * fields that have a value: an empty, disabled "Not set" dropdown says nothing.
+ */
+export declare function valueOnlyFieldVisibility(column: DisplayColumn): ColumnFieldVisibility;
+export declare function ColumnEditor({ modelName, columns, readOnly, modelRole, fields, logicalOnly }: ColumnEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/DetailPanel/DescriptionEditor.d.ts

@@ -6,7 +6,7 @@
  * 2. Read — shows description text with pencil edit button on hover
  * 3. Edit — textarea with Save/Cancel buttons
  *
- * Follows the same pattern as GrainEditor.tsx.
+ * Follows the same add / read / edit pattern as the text fields in FieldsSection.tsx.
  */
 interface DescriptionEditorProps {
     modelName: string;

package/dist/types/components/DetailPanel/DetailPanel.d.ts

@@ -2,9 +2,38 @@
  * DetailPanel — floating detail view for the selected model.
  *
  * Displays at top-right when a node is clicked. Shows:
- * - Model metadata (name, schema, description)
+ * - Model metadata (its file, when the editing host says, then name, schema, description)
  * - Editable column list
- * - Incoming and outgoing FK relationships
+ * - Incoming and outgoing FK relationships, then (editing host only) the
+ *   relationships to tables not on this diagram, each with "+ Add"
+ * - "Modelling detail (optional)": the table's Fields (its context fields,
+ *   from the project's field list), folded until one of them has a value
+ *
+ * The viewer (`useIsViewer`) never has the host's context and keeps the
+ * layout it always had, in the old order, with the Fields where the role,
+ * grain, meta and rationale sections were: a section folded to its heading
+ * and count until the reader opens it (it sits above Columns, so a few long
+ * rationale values would push the columns and relationships out of a short
+ * embedded canvas), and remembered from table to table. Its close button hides the
+ * panel but keeps the table selected (its relationships stay lit; a click on
+ * the table opens the panel again, and the empty canvas or Escape clears it),
+ * its relationship rows wrap instead of cutting names off, and it is never
+ * taller than the canvas it floats over.
  */
+import { type FieldsTable } from './FieldsSection.js';
+import type { DisplayRelationship, FieldList } from '@erd-studio/core';
 import './DetailPanel.css';
+/**
+ * The detail panel's "Remove from Diagram" question. A table's relationships
+ * go with it only when the diagram file holds them itself (a YAML/JSON
+ * domain's own list); in the Table Library (every DBML diagram) they stay.
+ * `inDiagramFile` is absent from an older core: then every relationship the
+ * table draws is counted, the old warning.
+ */
+export declare function removeConfirmText(tableName: string, relationshipsInDiagramFile: boolean | undefined, outgoing: readonly Pick<DisplayRelationship, 'inDiagramFile'>[], incoming: readonly Pick<DisplayRelationship, 'inDiagramFile'>[]): string;
+/**
+ * Whether any of the table's fields has a value, so "Modelling detail" opens
+ * by itself. Import DBML's bookkeeping (`meta.dbml`) is not a field.
+ */
+export declare function hasModellingDetail(model: FieldsTable, list?: FieldList): boolean;
 export declare function DetailPanel(): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/DetailPanel/FieldsSection.d.ts

@@ -0,0 +1,68 @@
+/**
+ * FieldsSection — a table's (or a column's) context fields in the Detail panel.
+ *
+ * The rows come from core's resolver (`resolveTableFields` /
+ * `resolveColumnFields`) over the project's field list
+ * (`DisplaySubjectArea.fields`, else core's `STARTING_FIELD_LIST`), so the
+ * canvas, the CLI and the assistant agree on what a table records. A field's
+ * value stays where it always lived (its *home*), and each edit is posted as
+ * the message that home has always used:
+ *
+ * - `rationale` → `updateModelRationale` with one key (`''` clears it)
+ * - `meta` → `updateMeta` (set one key; a clear removes the key)
+ * - `grain` → `updateModelGrain` (`''` clears it)
+ * - `role` → `updateModelRole` (`null` clears it)
+ *
+ * A column's section lists only the fields kept in the column's `meta`; its
+ * natural key, SCD type and additivity stay in `ColumnRowEditor`.
+ *
+ * Three presentations, gated `viewer ? … : (readOnly ? … : <editor>)`:
+ * the viewer and a read-only stage (physical) show the rows that have a
+ * value, labels and values only (two columns: muted label, wrapped value),
+ * and post nothing; in the viewer a table's section is a fold, its heading a
+ * button with the count, closed unless `open` says otherwise. The editor shows the list
+ * in order (empty fields with their guidance), retired fields with a badge,
+ * values the list does not name under "Not in your list", and "+ Add field".
+ */
+import type { DisplayColumn, DisplayTable, FieldList, FieldRow, Meta, MetaValue } from '@erd-studio/core';
+import './FieldsSection.css';
+/** The table properties the resolver reads. */
+export type FieldsTable = Pick<DisplayTable, 'modelRole' | 'grain' | 'meta' | 'rationale'>;
+/** The column properties the resolver reads. */
+export type FieldsColumn = Pick<DisplayColumn, 'name' | 'meta' | 'isNaturalKey' | 'scdType' | 'additiveType'>;
+/** The label of Import DBML's bookkeeping row (`meta.dbml`). */
+export declare const DBML_IMPORT_ROW_LABEL = "Kept from DBML import";
+/** Whether a row holds a value a reader would see: anything except no value or blank text. */
+export declare function rowHasValue(row: FieldRow): boolean;
+/** The `meta.dbml` entry Import DBML keeps, or undefined. */
+export declare function dbmlImportValue(owner: {
+    meta?: Meta;
+} | undefined): MetaValue | undefined;
+/** The rows a section draws: a column's section keeps only the fields held in its `meta`. */
+export declare function fieldRows(table: FieldsTable, column: FieldsColumn | undefined, list: FieldList): FieldRow[];
+/**
+ * Whether a table's read-only Fields section has anything to show: a field
+ * with a value, or the "Kept from DBML import" row.
+ */
+export declare function tableFieldsShown(table: FieldsTable, list?: FieldList): boolean;
+export interface FieldsSectionProps {
+    modelName: string;
+    /** The table (for a column's section: the column's table, whose role decides which fields suit it). */
+    table: FieldsTable;
+    /** Show this column's fields instead of the table's (a compact section). */
+    column?: FieldsColumn;
+    /** The project's field list (`DisplaySubjectArea.fields`); the starting set when absent. */
+    fields?: FieldList;
+    /** A read-only stage (physical): values only, as the viewer shows them. */
+    readOnly?: boolean;
+    /** No dbt project: no "from dbt" badge. */
+    logicalOnly?: boolean;
+    /**
+     * Viewer only, a table's section: whether its fold is open. Without it the
+     * section keeps its own state, starting closed.
+     */
+    open?: boolean;
+    /** Viewer only: called when the reader opens or closes the fold. */
+    onOpenChange?: (open: boolean) => void;
+}
+export declare function FieldsSection({ modelName, table, column, fields, readOnly, logicalOnly, open, onOpenChange }: FieldsSectionProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/Graph/ColumnTooltip.d.ts

@@ -2,7 +2,7 @@
  * ColumnTooltip — hover tooltip showing column details on the canvas.
  *
  * Renders via a React Portal to document.body so it is never clipped by
- * the ModelNode's `overflow: hidden`. Positioned with `position: fixed`
+ * the TableNode's `overflow: hidden`. Positioned with `position: fixed`
  * using the anchor element's bounding rect. Automatically flips below
  * the row if there isn't enough space above.
  *

package/dist/types/components/Graph/EdgeFlow.d.ts

@@ -0,0 +1,55 @@
+/**
+ * EdgeFlow — the moving direction glyphs drawn along a relationship line.
+ *
+ * Chevrons run from the `1` end to the `*` end; a many-to-many has two lanes
+ * running opposite ways; a one-to-one has two dots meeting in the middle
+ * (`lib/edgeFlow.ts` has the rule and the recipes). Each glyph is an SVG
+ * `<animateMotion>` along the line's own path:
+ *
+ *   - `path={d}`, never `<mpath href>`: edge ids repeat when two canvases
+ *     share a page, so an id reference could follow the other canvas's line.
+ *   - `calcMode="linear"`: the default (`paced`) ignores `keyPoints`.
+ *   - Each glyph is keyed on its recipe, so a change of direction or a switch
+ *     between moving and still mounts fresh SMIL elements.
+ *   - With the OS reduce-motion setting on, too many lines flowing, or a
+ *     settled click selection, every glyph is still: a plain
+ *     `translate() rotate()` at a point off the bends (`stillPositions`),
+ *     with no SMIL at all, so it follows a swapped or re-routed line and
+ *     costs nothing per frame.
+ *
+ * `EdgeFlow` is the canvas version: it draws nothing below `MIN_FLOW_ZOOM`
+ * and scales the glyphs up as the canvas zooms out, so they stay legible.
+ * `EdgeFlowGlyphs` always draws (the Legend, which is not zoomed). Neither
+ * takes pointer events nor is read out by assistive technology: the line's
+ * own `<title>` says what the relationship is.
+ */
+import { type FlowMode } from '../../lib/edgeFlow.js';
+import './FkEdge.css';
+/** A filled, notched arrowhead, 8 × 9, pointing along +x (the direction of travel). */
+export declare const CHEVRON_D = "M -4,-4.5 L 4,0 L -4,4.5 L -1.75,0 Z";
+export interface EdgeFlowProps {
+    /** The line's path data, exactly as drawn. */
+    d: string;
+    mode: FlowMode;
+    /** Path length in flow pixels when `d` cannot be measured; otherwise unused. */
+    length?: number;
+    /** False: stand still (too many lines flowing, or a settled selection). */
+    animate: boolean;
+    /** Colour key: a stage (`logical`, `physical`, `ghost`) or `discrepancy-<status>`. */
+    statusKey: string;
+    /** Glyph size factor (1 = 8 flow px). `EdgeFlow` sets it from the zoom. */
+    glyphScale?: number;
+}
+declare function EdgeFlowGlyphsComponent({ d, mode, length, animate, statusKey, glyphScale }: EdgeFlowProps): import("react/jsx-runtime").JSX.Element;
+/** The glyphs at any zoom (for the Legend). */
+export declare const EdgeFlowGlyphs: import("react").MemoExoticComponent<typeof EdgeFlowGlyphsComponent>;
+/**
+ * The glyph scale for a zoom: 0 below `MIN_FLOW_ZOOM` (draw nothing), else
+ * 1 / zoom rounded up to a quarter and clamped to 1..`MAX_GLYPH_SCALE`, so a
+ * glyph stays about 8 screen px or more and the value changes rarely.
+ */
+export declare function glyphScaleForZoom(zoom: number): number;
+declare function EdgeFlowComponent(props: EdgeFlowProps): import("react/jsx-runtime").JSX.Element | null;
+/** The glyphs on the canvas: nothing below `MIN_FLOW_ZOOM`, larger when zoomed out. */
+export declare const EdgeFlow: import("react").MemoExoticComponent<typeof EdgeFlowComponent>;
+export {};

package/dist/types/components/Graph/EdgeLabels.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where an edge's HTML labels go: React Flow's label layer
+ * (`.react-flow__edgelabel-renderer`), portalled into exactly as
+ * `<EdgeLabelRenderer>` does, but found once per canvas.
+ *
+ * `<EdgeLabelRenderer>` finds the layer with a store selector that runs
+ * `domNode.querySelector(...)`, so every edge re-searches the canvas DOM on
+ * every React Flow store update. On a 2,000-table diagram that was 2,743
+ * searches through ~100,000 elements several times a drag frame: about 45% of
+ * the time a drag took. Here the selector is a WeakMap lookup.
+ */
+import type { ReactNode } from 'react';
+/** The canvas's label layer, looked up once per canvas root (again only if it left the DOM). */
+export declare function labelLayerOf(root: Element | null | undefined): HTMLElement | null;
+/** Renders `children` in the canvas's label layer (nothing until the layer exists). */
+export declare function EdgeLabels({ children }: {
+    children: ReactNode;
+}): import("react").ReactPortal | null;

package/dist/types/components/Graph/FkEdge.d.ts

@@ -1,7 +1,9 @@
 /**
  * FkEdge — custom React Flow edge for displaying FK relationships.
  *
- * Renders a smooth-step path with Power BI-style cardinality labels:
+ * Draws its route from the one-pass line router (`EdgeRouter`, in the canvas
+ * store's `edgeRoutes`) when it has one, else a smooth-step path, with Power
+ * BI-style cardinality labels:
  * `*` for "many" and `1` for "one", positioned near each endpoint.
  * Built relationships are blue; design relationships are orange.
  * All edges use a solid line style.
@@ -12,6 +14,11 @@
  * Edges connect to node-level handles (top/right/bottom/left) rather
  * than column-specific handles, choosing the side that creates the
  * least bends.
+ *
+ * Edges of the hovered or selected table carry moving arrows from the 1 end
+ * to the * end; one-to-one shows two dots meeting (`EdgeFlow`). While a hover
+ * preview is active, the hovered table's lines are marked lit so the root
+ * `erd-flow--hover-focus` class can fade every other line (`useHoverFocus`).
  */
 import { type EdgeProps } from '@xyflow/react';
 import type { FkFlowEdge } from '../../types/graph.js';

package/dist/types/components/Graph/ModelNode.d.ts

@@ -1,5 +1,5 @@
 /**
- * ModelNode — custom React Flow node for displaying a semantic model card.
+ * TableNode — custom React Flow node for displaying a semantic model card.
  *
  * Shows model name with a layer badge, a list of columns with PK/FK
  * indicators and data types, and a footer with the total column count.
@@ -14,8 +14,8 @@
  *   3. Release to open the relationship dialog with prefilled data
  */
 import { type NodeProps } from '@xyflow/react';
-import type { ModelFlowNode } from '../../types/graph.js';
+import type { TableFlowNode } from '../../types/graph.js';
 import './ModelNode.css';
-declare function ModelNodeComponent({ data, selected }: NodeProps<ModelFlowNode>): import("react/jsx-runtime").JSX.Element;
-export declare const ModelNode: import("react").MemoExoticComponent<typeof ModelNodeComponent>;
+declare function TableNodeComponent({ id, data, selected }: NodeProps<TableFlowNode>): import("react/jsx-runtime").JSX.Element;
+export declare const TableNode: import("react").MemoExoticComponent<typeof TableNodeComponent>;
 export {};

package/dist/types/components/Legend/Legend.d.ts

@@ -1,11 +1,42 @@
 /**
  * Legend — collapsible panel explaining the visual language of the graph.
  *
- * Shows stage colours, relationship types, cardinality notation, the node
- * header badges (schema abbreviation and physical provenance chips) and the
- * column badges. The badge vocabulary is imported from lib/badgeLabels so the
- * legend cannot fall out of step with what ModelNode actually renders. Positioned in the bottom-left corner, collapsible
+ * Shows stage colours, relationship types, cardinality notation (and the
+ * moving direction arrows a hovered or clicked table's lines carry), the node
+ * header badges (the layer badge, the schema prefix and physical provenance
+ * chips) and the column badges. Without a dbt project (`logicalOnly`) the
+ * Physical, ghost, provenance and comparison entries are left out, and in a
+ * single-layer project the layer badge, which the canvas does not draw. The
+ * viewer (`useIsViewer`) shows only what can appear on the one read-only stage
+ * it draws (`legendEntries`): a logical diagram has no Physical, ghost,
+ * provenance or line-colour entries, a physical one no Logical entry, and
+ * neither has the comparison entries (the viewer never compares stages). It
+ * never names dbt: a page outside VS Code cannot know whether the project
+ * uses it. The badge vocabulary is imported from lib/badgeLabels so the
+ * legend cannot fall out of step with what TableNode actually renders. Positioned in the bottom-left corner, collapsible
  * to a `?` icon button.
  */
 import './Legend.css';
+/** Which optional groups of entries the legend shows. */
+export interface LegendEntries {
+    /** The Logical stage card. */
+    logicalStage: boolean;
+    /** The Physical stage card, both ghosts and the provenance chips. */
+    physical: boolean;
+    /** "Line colour follows the stage": a logical and a physical line. */
+    lineColours: boolean;
+    /** "Comparing Stages": the discrepancy colours and lines. */
+    comparison: boolean;
+}
+/**
+ * The legend's optional entries. The editor shows every one (without a dbt
+ * project, `logicalOnly`, none of the physical or comparison ones). The viewer
+ * draws one stage, read-only, and never a comparison, so it shows only that
+ * stage's entries.
+ */
+export declare function legendEntries(options: {
+    viewer: boolean;
+    logicalOnly: boolean;
+    stage: string | undefined;
+}): LegendEntries;
 export declare function Legend(): import("react/jsx-runtime").JSX.Element;