@erd-studio/renderer 0.1.0

package/dist/types/hooks/useColumnReorder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useColumnReorder — drag-to-reorder state machine for column lists.
+ *
+ * Uses imperative mouse events (matching the existing useLongPressDrag pattern).
+ * Returns drag state, handle props for each row, and the optimistic display order.
+ *
+ * Works in both DetailPanel (ColumnRowEditor rows) and ModelNode (ColumnRow rows)
+ * by accepting configurable CSS selectors for the container and row elements.
+ */
+interface Column {
+    name: string;
+}
+interface UseColumnReorderOptions<T extends Column> {
+    /** Source-of-truth columns from the extension. */
+    columns: T[];
+    /** Called on drop with the final ordered column names. */
+    onReorder: (orderedNames: string[]) => void;
+    /** CSS selector for the scrollable list container (walked up from the handle). */
+    containerSelector?: string;
+    /** CSS selector for individual row elements within the container. */
+    rowSelector?: string;
+}
+interface UseColumnReorderReturn<T extends Column> {
+    /** Columns in display order (same as input — reorder applied on drop). */
+    orderedColumns: T[];
+    /** Index of the row currently being dragged, or null. */
+    dragIndex: number | null;
+    /** Current insertion point index, or null. */
+    dropIndex: number | null;
+    /** Props to spread onto the drag handle element for a given row index. */
+    getDragHandleProps: (index: number) => {
+        onMouseDown: (e: React.MouseEvent) => void;
+    };
+}
+export declare function useColumnReorder<T extends Column>({ columns, onReorder, containerSelector, rowSelector, }: UseColumnReorderOptions<T>): UseColumnReorderReturn<T>;
+export {};

package/dist/types/hooks/useFocusWithinRow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * useFocusWithinRow — hook for tracking focus within a container element.
+ *
+ * Uses requestAnimationFrame instead of setTimeout to reliably detect
+ * when focus leaves a row container. This eliminates flicker issues
+ * when switching between fields (e.g., name input → data type dropdown).
+ */
+export interface UseFocusWithinRowResult {
+    /** Whether focus is currently within the row container. */
+    isFocusWithin: boolean;
+    /** Props to spread on the row container element. */
+    rowProps: {
+        onFocus: (e: React.FocusEvent) => void;
+        onBlur: (e: React.FocusEvent) => void;
+    };
+}
+/**
+ * Hook for tracking focus within a row container.
+ *
+ * @param onFocusLeave - Callback fired when focus leaves the row entirely.
+ *                       Use this to trigger auto-save or validation.
+ */
+export declare function useFocusWithinRow(onFocusLeave?: () => void): UseFocusWithinRowResult;

package/dist/types/hooks/useLongPressDrag.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Custom hook for detecting long-press (press and hold) gestures.
+ *
+ * Used for initiating drag-to-create-relationship interactions. After the
+ * specified delay, `onLongPressStart` fires to indicate a drag has begun.
+ * The consumer is responsible for tracking mouse position and handling the
+ * drop via global event listeners.
+ */
+export interface UseLongPressDragOptions {
+    /** Delay in ms before long-press is triggered. Default: 220ms */
+    delay?: number;
+    /** Called when long-press threshold is reached */
+    onLongPressStart?: () => void;
+    /** Called when press is cancelled (mouseup before delay, or mouse leaves) */
+    onCancel?: () => void;
+}
+export interface UseLongPressDragReturn {
+    /** Whether the press timer is active (for visual feedback like pulsing) */
+    isPressing: boolean;
+    /** Whether long-press completed and drag is active */
+    isDragging: boolean;
+    /** Call this to end the drag state (e.g., after drop) */
+    endDrag: () => void;
+    /** Event handlers to spread onto the pressable element */
+    handlers: {
+        onMouseDown: (e: React.MouseEvent) => void;
+        onMouseUp: () => void;
+        onMouseLeave: () => void;
+    };
+}
+export declare function useLongPressDrag(options?: UseLongPressDragOptions): UseLongPressDragReturn;

package/dist/types/host/canvasEnvironment.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The canvas's link to whatever page embeds it.
+ *
+ * Canvas components never talk to their host directly. Edits made on the
+ * canvas (renaming a column, moving an annotation, …) are posted as
+ * `CanvasEditMessage`s to the `CanvasHost` supplied by the nearest
+ * `CanvasEnvironmentProvider`. The VS Code extension supplies a host that
+ * forwards them to the extension; without a provider, messages go nowhere.
+ *
+ * The environment also carries the `viewer` flag, which read-only embeddings
+ * set to present the canvas without its editing affordances.
+ */
+import { type ReactNode } from 'react';
+import type { CanvasEditMessage } from '@erd-studio/core';
+/** Receives the edits made on the canvas. */
+export interface CanvasHost {
+    postMessage(message: CanvasEditMessage): void;
+}
+export interface CanvasEnvironment {
+    host: CanvasHost;
+    /** Read-only viewer presentation (no editing affordances). */
+    viewer: boolean;
+}
+/** A host that drops every message. */
+export declare const NOOP_CANVAS_HOST: CanvasHost;
+export declare function CanvasEnvironmentProvider({ host, viewer, children, }: {
+    host?: CanvasHost;
+    viewer?: boolean;
+    children: ReactNode;
+}): JSX.Element;
+/** The host edits are posted to (a no-op host outside any provider). */
+export declare function useCanvasHost(): CanvasHost;
+/** A stable function that posts an edit to the host. */
+export declare function useSend(): (message: CanvasEditMessage) => void;
+/** Whether the canvas is in read-only viewer mode (false outside any provider). */
+export declare function useIsViewer(): boolean;

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { ErdCanvas, type ErdCanvasProps, type ErdCanvasHandle } from './ErdCanvas.js';
+export { transformDomain, pickHandleSides, type TransformResult, type TransformOptions, type NodeRect, type NodeDimensions, } from './lib/graphTransformer.js';
+export { repickHandleSides, nodeRect } from './lib/dragHandleSides.js';
+export type { DisplayDomain, DisplayModel, DisplayColumn, DisplayRelationship, PhysicalColumnSource, PhysicalProvenance, Annotation, AnnotationColor, Cardinality, Layer, ModelRole, NodePosition, Rationale, Stage, ViewConfig, LayerConfig, } from '@erd-studio/core';
+export type { ModelFlowNode, ModelNodeData, FkFlowEdge, FkEdgeData, AnnotationFlowNode, AnnotationFlowEdge, ColumnDisplay, } from './types/graph.js';

package/dist/types/lib/annotationColors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared annotation colour constants.
+ *
+ * Used by AnnotationNode (inline toolbar) and ContextMenu (right-click menu)
+ * to render identical colour swatch rows from a single source of truth.
+ */
+import type { AnnotationColor } from '@erd-studio/core';
+export interface AnnotationColorOption {
+    value: AnnotationColor;
+    label: string;
+    swatch: string;
+}
+export declare const ANNOTATION_COLORS: AnnotationColorOption[];

package/dist/types/lib/badgeLabels.d.ts

@@ -0,0 +1,63 @@
+/**
+ * badgeLabels — the abbreviations and symbols the canvas stamps on nodes and
+ * columns, and the prose that decodes them.
+ *
+ * These live here rather than in ModelNode because the Legend explains exactly
+ * this vocabulary. Two copies of "WH means the warehouse catalog" is two things
+ * to keep in step, and the legend is precisely the copy nobody edits when the
+ * node changes. Both ends import these maps, so a new source or a renamed chip
+ * shows up in the legend for free.
+ *
+ * Pure data — no vscode, no DOM.
+ */
+import type { PhysicalColumnSource } from '@erd-studio/core';
+/**
+ * Header chip text for each physical column source. Three letters, because the
+ * chip shares a fixed-height header row with the name and the schema badge —
+ * the sentence-length explanation lives in the chip's title and in the
+ * DetailPanel's "Columns from" row.
+ */
+export declare const SOURCE_LABEL: Record<PhysicalColumnSource, string>;
+/** How each source is named in prose (chip tooltip). */
+export declare const SOURCE_PHRASE: Record<PhysicalColumnSource, string>;
+/**
+ * The order the legend lists the sources in: most authoritative first, which is
+ * also the order `provenance.columns` arrives in.
+ */
+export declare const SOURCE_ORDER: PhysicalColumnSource[];
+/** One line per source for the legend, saying what having that chip means. */
+export declare const SOURCE_LEGEND_DESC: Record<PhysicalColumnSource, string>;
+/** Unicode circled numbers for SCD type badges. */
+export declare const SCD_BADGE: Record<number, string>;
+/**
+ * What each SCD badge is claiming, for the badge's title. A bare "SCD Type 2"
+ * only re-reads the number back to someone who is hovering precisely because
+ * the number meant nothing to them.
+ */
+export declare const SCD_TITLE: Record<number, string>;
+/** Symbols for additive type badges. */
+export declare const ADDITIVE_BADGE: Record<string, string>;
+/** The same courtesy for the additive symbols. */
+export declare const ADDITIVE_TITLE: Record<string, string>;
+/**
+ * What a coloured or dashed edge is claiming during a comparison. The colours
+ * alone carry this today, which is unreadable to anyone who has not just read
+ * the legend — and invisible to anyone who cannot tell amber from red.
+ */
+export declare const DISCREPANCY_PHRASE: Record<'extra' | 'missing' | 'cardinality-mismatch', string>;
+/** The fields of an edge that its hover text is built from. */
+export interface EdgeHoverInput {
+    fromModel: string;
+    fromColumn: string;
+    toModel: string;
+    toColumn: string;
+    cardinality: string;
+    discrepancyStatus?: 'extra' | 'missing' | 'cardinality-mismatch';
+}
+/**
+ * Hover text for a relationship line: which columns it joins, its cardinality,
+ * and — during a comparison — what its colour is saying. The `*` / `1` glyphs
+ * are `pointer-events: none` so the line itself is the only part of an edge
+ * that can carry this.
+ */
+export declare function edgeHoverText(edge: EdgeHoverInput): string;

package/dist/types/lib/cardinalityUtils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cardinality utility functions.
+ *
+ * Pure helpers for working with FK relationship cardinality values.
+ */
+import type { Cardinality } from '@erd-studio/core';
+/**
+ * Returns the inverse cardinality (source/target sides swapped).
+ *
+ * many-to-one  ↔  one-to-many
+ * one-to-one   →  one-to-one   (symmetric, no-op)
+ * many-to-many →  many-to-many (symmetric, no-op)
+ */
+export declare function swapCardinality(c: Cardinality): Cardinality;

package/dist/types/lib/dataTypeColors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Data-type colour mapping for column type text.
+ *
+ * Hand-picked colours for the 8 preset SQL types; deterministic
+ * hash-derived colours for any custom / unknown type.
+ *
+ * Colours are HSL strings with moderate saturation and lightness tuned
+ * for readability on both dark and light VS Code themes.
+ */
+/**
+ * Returns an HSL colour string for a given SQL data type.
+ * Preset types get a hand-picked colour; everything else gets a
+ * deterministic hash-derived colour.
+ */
+export declare function getDataTypeColor(dataType: string): string;

package/dist/types/lib/dragHandleSides.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Handle sides for edges after nodes are moved on the canvas.
+ *
+ * `transformDomain` chooses the handle side at each end of an edge from the
+ * saved positions: `pickHandleSides` compares the two node rectangles, and a
+ * self-referencing relationship always uses the top (source) and right
+ * (target) handles. A canvas that lets nodes be dragged without rebuilding the
+ * domain has to make that choice again for the edges on the dragged nodes, or
+ * those edges stay attached to the side that faced the old position.
+ *
+ * The rectangles follow `transformDomain` too: a node's size is its measured
+ * size when React Flow has one, otherwise the model-node estimate from
+ * `resolveNodeDimensions`, or an annotation's own (or default) size.
+ */
+import { type NodeRect } from './graphTransformer.js';
+import type { GraphNode, GraphEdge } from './nodeOverlays.js';
+/** The rectangle `pickHandleSides` compares for `node`: its position and size. */
+export declare function nodeRect(node: GraphNode): NodeRect;
+/**
+ * Recompute the handles of the edges attached to any node in `movedIds`.
+ *
+ * Only edges whose handles actually change are replaced; every other entry is
+ * the original edge. If none change, `edges` is returned as is, which lets a
+ * caller compare by reference and skip a store update. Edges with an endpoint
+ * missing from `nodes` are left as they are.
+ */
+export declare function repickHandleSides(nodes: ReadonlyArray<GraphNode>, edges: GraphEdge[], movedIds: ReadonlySet<string>): GraphEdge[];

package/dist/types/lib/edgeDistribution.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Edge distribution — calculates evenly-spaced connection points along node sides.
+ *
+ * When multiple edges connect to the same side of a node, they would normally
+ * all connect at the center point, causing visual overlap. This module provides
+ * functions to distribute those connection points evenly along the side.
+ *
+ * The algorithm:
+ *   1. Group edges by (nodeId, side) — ALL edges on a side, regardless of
+ *      direction (incoming/outgoing). This prevents overlap between source
+ *      and target edges that would otherwise be centered independently.
+ *   2. For each edge, find its index in the sorted group (consistent ordering)
+ *   3. Calculate offset from center: evenly divide the side length
+ *   4. Apply offset perpendicular to the edge direction
+ */
+import type { Edge } from '@xyflow/react';
+/** Default node width when measured dimensions not available. */
+export declare const DEFAULT_NODE_WIDTH = 280;
+/** Default node height when measured dimensions not available. */
+export declare const DEFAULT_NODE_HEIGHT = 200;
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+export interface EdgeOffset {
+    x: number;
+    y: number;
+}
+/** Map of node IDs to their positions. */
+export type NodePositionMap = Map<string, {
+    x: number;
+    y: number;
+}>;
+/**
+ * Get all edge IDs that connect to a specific node side in a specific direction.
+ *
+ * @param edges — all edges in the graph
+ * @param nodeId — the node to check connections for
+ * @param side — which side of the node (top/right/bottom/left)
+ * @param isSource — true to find edges where this node is the source,
+ *                   false for edges where this node is the target
+ * @returns Sorted array of edge IDs for consistent ordering
+ */
+export declare function getEdgesForSide(edges: Edge[], nodeId: string, side: Side, isSource: boolean): string[];
+/**
+ * Get all edge IDs that connect to a specific node side, regardless of direction.
+ *
+ * This includes both edges where the node is the source (outgoing) AND edges
+ * where it's the target (incoming). Used for distribution to prevent overlap
+ * between incoming and outgoing edges on the same side.
+ *
+ * When nodePositions is provided, edges are sorted by the position of their
+ * connected node (the node at the OTHER end of the edge):
+ *   - For left/right sides: sort by Y position (top to bottom)
+ *   - For top/bottom sides: sort by X position (left to right)
+ *
+ * This sorting minimizes edge crossings by aligning connection points with
+ * the visual flow of the connected nodes.
+ *
+ * @param edges — all edges in the graph
+ * @param nodeId — the node to check connections for
+ * @param side — which side of the node (top/right/bottom/left)
+ * @param nodePositions — optional map of node positions for spatial sorting
+ * @returns Sorted array of edge IDs for consistent ordering
+ */
+export declare function getAllEdgesForSide(edges: Edge[], nodeId: string, side: Side, nodePositions?: NodePositionMap): string[];
+/**
+ * All edges that connect to `nodeId` on `side`, in either direction.
+ *
+ * Returns a cached array (do not mutate) — identity is stable for a given
+ * `edges` array, so it is safe to use as a memo dependency.
+ */
+export declare function getEdgesOnSide(edges: Edge[], nodeId: string, side: Side): readonly Edge[];
+/**
+ * Sort a side group into its final connection order and return edge IDs.
+ *
+ * When `nodePositions` is provided, edges are ordered by the position of the
+ * node at the OTHER end (Y for left/right sides, X for top/bottom) so
+ * connection points follow the visual flow and edges do not cross.
+ * Falls back to alphabetical ID order when positions are unavailable.
+ */
+export declare function sortEdgesForSide(edgesForSide: readonly Edge[], nodeId: string, side: Side, nodePositions?: NodePositionMap): string[];
+/**
+ * Parse the side from a handle ID.
+ *
+ * Handle IDs follow the format "node-{side}-{src|tgt}".
+ * Returns undefined if the handle ID doesn't match the expected format.
+ */
+export declare function parseSideFromHandle(handleId: string | null | undefined): Side | undefined;
+/** Node dimensions from React Flow's internal node measurement. */
+interface MeasuredDimensions {
+    width?: number;
+    height?: number;
+}
+/**
+ * Get the length of a node side in pixels.
+ *
+ * For horizontal sides (top/bottom), returns the node width.
+ * For vertical sides (left/right), returns the node height.
+ * Falls back to default dimensions if the node hasn't been measured yet.
+ *
+ * @param side — which side of the node
+ * @param measured — the node's measured dimensions (may be undefined)
+ * @returns Side length in pixels
+ */
+export declare function getSideLength(side: Side, measured: MeasuredDimensions | undefined): number;
+/**
+ * Calculate the offset for a connection point along a node side.
+ *
+ * Distributes connection points evenly along the side. For example, with
+ * 3 edges connecting to a 280px wide side:
+ *   - spacing = 280 / 4 = 70px
+ *   - positions: 70px, 140px, 210px (from left edge)
+ *   - offsets from center (140px): -70px, 0px, +70px
+ *
+ * @param edgeIndex — this edge's position in the group (0-based)
+ * @param groupSize — total number of edges connecting to this side
+ * @param sideLength — width or height of the side in pixels
+ * @param side — which side (determines offset axis)
+ * @returns Offset in pixels from the center of the side
+ */
+export declare function calculateDistributionOffset(edgeIndex: number, groupSize: number, sideLength: number, side: Side): EdgeOffset;
+/**
+ * Calculate the full offset for an edge's connection point.
+ *
+ * This is the main entry point — combines grouping and offset calculation.
+ * Groups ALL edges on a side together (both incoming and outgoing) to prevent
+ * overlap between source and target edges.
+ *
+ * When nodePositions is provided, edges are sorted by their connected node's
+ * position to minimize visual crossings.
+ *
+ * @param edgeId — the edge to calculate offset for
+ * @param nodeId — the node this edge connects to
+ * @param side — which side of the node
+ * @param isSource — true if calculating source offset, false for target (kept for API compatibility)
+ * @param allEdges — all edges in the graph
+ * @param sideLength — width (for top/bottom) or height (for left/right) of the node
+ * @param nodePositions — optional map of node positions for spatial sorting
+ * @returns Offset in pixels from the center of the side
+ */
+export declare function calculateEdgeOffset(edgeId: string, nodeId: string, side: Side, _isSource: boolean, allEdges: Edge[], sideLength: number, nodePositions?: NodePositionMap): EdgeOffset;
+/**
+ * Same as `calculateEdgeOffset` but for a pre-grouped side (see
+ * `getEdgesOnSide`), avoiding a scan of the full edge array per call.
+ */
+export declare function calculateEdgeOffsetInGroup(edgeId: string, nodeId: string, side: Side, edgesOnSide: readonly Edge[], sideLength: number, nodePositions?: NodePositionMap): EdgeOffset;
+/**
+ * Build a compact, value-comparable key of the given nodes' positions.
+ *
+ * React Flow mutates its `nodeLookup` Map in place (`adoptUserNodes` clears
+ * and refills it), so the Map identity never changes and cannot be used as a
+ * memo dependency. Subscribing to this string instead re-renders exactly when
+ * one of the listed nodes moves.
+ */
+export declare function buildPositionsKey(nodeLookup: ReadonlyMap<string, {
+    position?: {
+        x: number;
+        y: number;
+    };
+    internals?: {
+        positionAbsolute?: {
+            x: number;
+            y: number;
+        };
+    };
+}>, nodeIds: readonly string[]): string;
+export {};

package/dist/types/lib/graphTransformer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Graph transformer — converts a DisplayDomain into React Flow nodes and edges.
+ *
+ * This is a pure function with no side effects, making it easy to unit test.
+ * It handles:
+ *   1. Mapping each DisplayModel → ModelFlowNode (with position + columns)
+ *   2. Mapping each DisplayRelationship → FkFlowEdge (with handle side selection)
+ *   3. Selecting optimal handle sides based on relative node positions
+ *   4. Injecting discrepancy data and ghost nodes/edges when a comparison report is active
+ */
+import type { DisplayDomain } from '@erd-studio/core';
+import type { DiscrepancyReport } from '@erd-studio/core';
+import type { ModelFlowNode, FkFlowEdge, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
+export interface TransformResult {
+    nodes: (ModelFlowNode | AnnotationFlowNode)[];
+    edges: (FkFlowEdge | AnnotationFlowEdge)[];
+}
+/** Width/height of a rendered node, in canvas pixels. */
+export interface NodeDimensions {
+    width: number;
+    height: number;
+}
+/** Optional parameters for discrepancy overlay rendering. */
+export interface TransformOptions {
+    /** Active cross-stage discrepancy report (e.g., physical vs logical). */
+    discrepancyReport?: DiscrepancyReport;
+    /**
+     * Measured node sizes (keyed by node id) from the current React Flow state.
+     * Used to pick edge handle sides from node centres rather than top-left
+     * corners. Nodes without an entry fall back to an estimate.
+     */
+    nodeDimensions?: ReadonlyMap<string, NodeDimensions>;
+    /** Column expansion state per model — sharpens the height estimate fallback. */
+    isExpanded?: (modelName: string) => boolean;
+}
+type Side = 'top' | 'right' | 'bottom' | 'left';
+/** A node's top-left position plus its rendered size. */
+export interface NodeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Choose which side of each node to connect, minimising visual bends.
+ *
+ * Compares the relative position of the source and target node *centres*
+ * and picks the axis (horizontal or vertical) with the greater distance.
+ * On that axis, the source connects on the side facing the target and vice
+ * versa. Centres (not top-left corners) matter because a tall node next to a
+ * short one would otherwise route its edge out of the wrong side.
+ */
+export declare function pickHandleSides(source: NodeRect, target: NodeRect): {
+    sourceSide: Side;
+    targetSide: Side;
+};
+/**
+ * Convert a DisplayDomain into React Flow nodes and edges.
+ *
+ * @param domain — the display domain from extension host
+ * @param options — optional discrepancy report and ghost positions
+ * @returns nodes and edges ready for React Flow's `<ReactFlow>` component
+ */
+export declare function transformDomain(domain: DisplayDomain, options?: TransformOptions): TransformResult;
+export {};

package/dist/types/lib/nodeOverlays.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Node/edge overlays — ephemeral per-node presentation state layered on top
+ * of the graph produced by `transformDomain`:
+ *
+ *   - `dimmed`: search-miss or not-connected-to-selection dimming (F402)
+ *   - `isExpanded` / `onToggleExpansion`: column expansion (F405)
+ *
+ * `applyNodeOverlays` is a pure function that preserves object identity for
+ * every node/edge whose overlay values did not change, so React Flow's
+ * `adoptUserNodes` short-circuits on unchanged nodes and memoised
+ * `ModelNode` / `FkEdge` components skip re-rendering. When nothing changed
+ * at all, the *same arrays* are returned so callers can skip `setNodes`.
+ *
+ * This lets selection / search / expansion changes avoid re-running the full
+ * domain transform (which would also drop `measured` and force React Flow to
+ * re-measure every node).
+ */
+import type { ModelFlowNode, FkFlowEdge, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
+export type GraphNode = ModelFlowNode | AnnotationFlowNode;
+export type GraphEdge = FkFlowEdge | AnnotationFlowEdge;
+export interface OverlayState {
+    /** Currently selected model (drives connected-node dimming). */
+    selectedNode: string | null;
+    /** Currently selected FK edge id (drives endpoint dimming). */
+    selectedEdge: string | null;
+    /** Raw search query; blank means no search dimming. */
+    searchQuery: string;
+    /** Column expansion lookup per model. */
+    isExpanded: (modelName: string) => boolean;
+    /** Stable toggle callback injected into node data. */
+    toggleExpansion: (modelName: string) => void;
+}
+/**
+ * Apply dimming + expansion overlays to nodes and edges.
+ *
+ * Returns the input arrays untouched (same reference) when no element changed.
+ */
+export declare function applyNodeOverlays(nodes: GraphNode[], edges: GraphEdge[], state: OverlayState): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};

package/dist/types/lib/nodeSizing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Model node size estimation (matches ModelNode CSS).
+ *
+ * The width and height a model node will render at, estimated from its
+ * content, for code that needs node sizes before React Flow has measured the
+ * DOM: edge handle placement in the graph transformer and the extension's ELK
+ * auto-layout, which imports these from `@erd-studio/renderer/sizing`.
+ *
+ * Kept free of elkjs and React Flow runtime imports so it can be loaded on its
+ * own.
+ */
+import type { ModelFlowNode, ModelNodeData } from '../types/graph.js';
+/** Default width — used as fallback by edgeDistribution.ts. */
+export declare const NODE_WIDTH = 280;
+/**
+ * Estimate a node's rendered height from the number of column rows actually
+ * drawn (see `countVisibleColumnRows`) and whether a grain subtitle is shown.
+ */
+export declare function estimateNodeHeight(rowCount: number, hasGrain: boolean): number;
+/**
+ * Number of rows ModelNode actually renders in its columns section.
+ *
+ * Mirrors the rendering rules in `ModelNode.tsx`:
+ *   - stub models show only PK/NK columns
+ *   - collapsed nodes show at most `COLLAPSED_COLUMN_LIMIT` columns plus a
+ *     "...and N more" button row
+ *   - expanded nodes with more than the limit also render a "Show less" row
+ *
+ * Using the full column count (the old behaviour) over-reserved
+ * `(columns - 5) * rowHeight` per node on auto-collapsed domains (≥30 models).
+ */
+export declare function countVisibleColumnRows(data: Pick<ModelNodeData, 'columns' | 'isStub' | 'isExpanded'>): number;
+/**
+ * Best-known size for a model node: React Flow's measured DOM size when
+ * available, otherwise an estimate from the rows that will be rendered.
+ */
+export declare function resolveNodeDimensions(node: Pick<ModelFlowNode, 'data' | 'measured'>): {
+    width: number;
+    height: number;
+};
+/**
+ * Estimate the pixel width a node needs to display its content without
+ * truncation. Examines the header and each column row, returning the
+ * widest value clamped to [MIN_NODE_WIDTH, MAX_NODE_WIDTH].
+ *
+ * A safety margin is added before clamping so ELK always reserves
+ * slightly more space than the minimum estimate, preventing overlap
+ * when font rendering or badge widths differ from the approximation.
+ */
+export declare function estimateNodeWidth(data: Pick<ModelNodeData, 'modelName' | 'columns' | 'provenance'>): number;

package/dist/types/lib/stageColors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stage colour constants.
+ *
+ * Fixed colour scheme for the two design stages.
+ *
+ * CSS classes use `var(--stage-*)` custom properties defined in theme.css.
+ * This module provides raw hex values for contexts that cannot use CSS
+ * variables (e.g., React Flow MiniMap `nodeColor` callback).
+ */
+/** Hex border colours keyed by stage name (or 'ghost' for missing nodes). */
+export declare const STAGE_HEX: Record<string, string>;
+/**
+ * Return the hex border colour for a node given its stage and ghost state.
+ * Used by MiniMap's `nodeColor` callback which needs raw colour values.
+ */
+export declare function stageNodeColor(stage: string, isGhost?: boolean): string;

package/dist/types/sizing.d.ts

@@ -0,0 +1 @@
+export { NODE_WIDTH, estimateNodeHeight, countVisibleColumnRows, resolveNodeDimensions, estimateNodeWidth, } from './lib/nodeSizing.js';