# Interfaces A–H

Import these from `@grafloria/engine`.

## Interfaces

### `ApplyLayoutConfig`

Configuration for applying a layout

```ts
interface ApplyLayoutConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `adapter` | `'dagre' \| 'elk' \| LayoutAdapter` |  | Layout adapter to use (name or instance) |
| `options?` | `Partial<LayoutOptions>` |  | Layout-specific options |
| `animate?` | `boolean` |  | Whether to animate to new positions |
| `animationDuration?` | `number` |  | Animation duration in milliseconds |
| `fit?` | `boolean` |  | Whether to fit viewport after layout |
| `canvasDimensions?` | `{ width: number; height: number }` |  | Canvas dimensions for viewport fitting |
| `onProgress?` | `(progress: number) => void` |  | Progress callback for long-running layouts |

### `AutoLayoutResult`

Also has every member of `LayoutResult`, listed on its own entry.

```ts
interface AutoLayoutResult extends LayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selection` | `LayoutSelectionReport` |  | Why this layout, and what the alternatives scored. |

### `Boundary`

Boundary definition for constraining node movement

```ts
interface Boundary
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minX?` | `number` |  | Minimum X coordinate (inclusive) |
| `maxX?` | `number` |  | Maximum X coordinate (inclusive) |
| `minY?` | `number` |  | Minimum Y coordinate (inclusive) |
| `maxY?` | `number` |  | Maximum Y coordinate (inclusive) |

### `BundledEdgePath`

Bundled edge path with control points

```ts
interface BundledEdgePath
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `edgeId` | `string` |  | Edge ID |
| `controlPoints` | `Point2D[]` |  | Control points for smooth curve |
| `bundleId?` | `string` |  | Bundle ID this edge belongs to |
| `strength` | `number` |  | Bundling strength applied (0-1) |

### `CandidateScore`

Every number behind one candidate's verdict.

```ts
interface CandidateScore
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `options` | `UnifiedLayoutOptions` |  |  |
| `score` | `number` |  | Final weighted score, 0-100. |
| `quality` | `LayoutQualityResult` |  | The classic metrics (crossings, overlap, symmetry, …). |
| `portRespect` | `number` |  | Requirement 1: do edges leave in the direction their port faces? 0-100. |
| `labelClearance` | `number` |  | Requirement 2: do edge labels stay off the nodes? 0-100. |
| `bends` | `number \| undefined` |  | Total bends across the engine's routes; undefined if it reported none. |
| `area` | `number` |  | Bounding-box area in px². |
| `error?` | `string` |  | Failed to run — kept in the report rather than hidden. |

### `CircularLayoutOptions`

Also has every member of `UnifiedLayoutOptions`, `LayoutOptions`, `LayoutRunOptions`, listed on their own entries.

```ts
interface CircularLayoutOptions extends UnifiedLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `radius?` | `number` |  | Force a radius. By default it is derived so nodes never overlap. |

### `CommunityLayoutOptions`

Also has every member of `LayoutOptions`, listed on its own entry.

Community detection layout options

```ts
interface CommunityLayoutOptions extends LayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm?` | `'louvain' \| 'label-propagation'` |  | Community detection algorithm (default: 'louvain') |
| `resolution?` | `number` |  | Resolution parameter for community detection (default: 1.0) |
| `separateCommunities?` | `boolean` |  | Separate communities visually (default: true) |
| `communitySpacing?` | `number` |  | Spacing between communities (default: 200) |
| `communityLayout?` | `'circular' \| 'grid' \| 'force'` |  | Layout algorithm for communities (default: 'circular') |
| `innerLayout?` | `'force' \| 'circular'` |  | Layout algorithm within communities (default: 'force') |
| `forceOptions?` | `{ iterations?: number; repulsion?: number; attraction?: number; }` |  | Force layout options for inner layout |

### `CompoundLayoutOptions`

```ts
interface CompoundLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultAlgorithm?` | `CompoundAlgorithm` |  | Default algorithm for groups without an explicit / 'inherit' choice. |
| `adapters?` | `Record<string, LayoutAdapter \| undefined>` |  | Injected adapters used as black boxes, keyed by name. Unknown → grid. |
| `defaultPadding?` | `number` |  | Fallback padding for groups without their own padding. |
| `gridGap?` | `number` |  | Gap between units in the built-in grid. |
| `layoutTopLevel?` | `boolean` |  | Also arrange the top level (root groups + ungrouped nodes). Default false. |
| `layoutOptions?` | `UnifiedLayoutOptions` |  | Base options in the ONE unified vocabulary (direction / nodeSpacing / rankSpacing / seed), translated per level into whatever that level's engine calls them. Per-group `layoutOptions` are merged OVER these. |
| `groupOverrides?` | `Record<string, Partial<GroupInfo>>` |  | Per-group overrides keyed by group id — honors the GroupInfo contract for callers that don't want to store config on the GroupModel. Merged over the group's own `subgraphLayout`. |

### `CompoundLayoutResult`

```ts
interface CompoundLayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `laidOut` | `string[]` |  | Groups laid out, in the order processed (deepest first). |
| `skipped` | `string[]` |  | Groups skipped: fixed, collapsed, or inside a collapsed container. |
| `collapsed` | `string[]` |  | Groups skipped specifically because they are collapsed (a leaf, not a container). |
| `groupBounds` | `Map<string, Rect>` |  | group id → final outer bounds. |
| `nodePositions` | `Map<string, { x: number; y: number }>` |  | Final node positions — the LayoutResult contract, so the registry can commit. |
| `bounds` | `Rect` |  | Bounding box of everything laid out. |

### `DagreLayoutOptions`

Also has every member of `LayoutOptions`, listed on its own entry.

Dagre-specific layout options

```ts
interface DagreLayoutOptions extends LayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `rankdir` | `'TB' \| 'BT' \| 'LR' \| 'RL'` |  | Layout direction |
| `align?` | `'UL' \| 'UR' \| 'DL' \| 'DR'` |  | Alignment for rank nodes |
| `nodesep` | `number` |  | Separation between adjacent nodes on the same rank (pixels) |
| `edgesep` | `number` |  | Separation between adjacent edges (pixels) |
| `ranksep` | `number` |  | Separation between ranks (pixels) |
| `marginx` | `number` |  | Horizontal margin (pixels) |
| `marginy` | `number` |  | Vertical margin (pixels) |
| `acyclicer?` | `'greedy' \| undefined` |  | Acyclic strategy for breaking cycles |
| `ranker` | `'network-simplex' \| 'tight-tree' \| 'longest-path'` |  | Algorithm for assigning ranks to nodes |
| `deepRankThreshold?` | `number` |  | DEEP-GRAPH FAST PATH — rank-count threshold (default 300). |

### `DiagramLayoutEvent`

Layout event data

```ts
interface DiagramLayoutEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `LayoutEventType` |  |  |
| `algorithmType` | `LayoutAlgorithmType` |  |  |
| `data?` | `any` |  |  |

### `EdgeBundlingOptions`

Configuration for edge bundling

```ts
interface EdgeBundlingOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  | Enable edge bundling |
| `strategy?` | `EdgeBundlingStrategy` |  | Bundling strategy to use |
| `strength?` | `number` |  | Bundling strength (0 = no bundling, 1 = maximum bundling) |
| `controlPoints?` | `number` |  | Number of control points per edge |
| `smoothness?` | `number` |  | Smoothness of bundled curves (0-1) |
| `iterations?` | `number` |  | Number of iterations for force-directed bundling |
| `springConstant?` | `number` |  | Spring constant for force-directed bundling |
| `compatibilityThreshold?` | `number` |  | Compatibility threshold (0-1) for bundling edges together |
| `respectGroups?` | `boolean` |  | Whether to bundle only edges in same group |
| `minEdgeLength?` | `number` |  | Minimum edge length for bundling |

### `EdgeBundlingResult`

Result of edge bundling computation

```ts
interface EdgeBundlingResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bundledPaths` | `Map<string, BundledEdgePath>` |  | Map of edge ID to bundled path |
| `bundleCount` | `number` |  | Number of bundles created |
| `bundledEdges` | `string[]` |  | Edges that were bundled |
| `unbundledEdges` | `string[]` |  | Edges that were not bundled |
| `strategy` | `EdgeBundlingStrategy` |  | Strategy used |
| `strength` | `number` |  | Actual strength applied |

### `EdgeInfo`

Edge information for bundling

```ts
interface EdgeInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Edge unique identifier |
| `sourceNodeId` | `string` |  | Source node ID |
| `targetNodeId` | `string` |  | Target node ID |
| `sourcePortId?` | `string` |  | Source port ID (optional) |
| `targetPortId?` | `string` |  | Target port ID (optional) |
| `weight?` | `number` |  | Edge weight/importance |
| `group?` | `string` |  | Group identifier for related edges |

### `ForceDirectedOptions`

Force-directed layout options (for future implementation)

```ts
interface ForceDirectedOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `iterations?` | `number` |  | Number of simulation iterations (default: 100) |
| `repulsionStrength?` | `number` |  | Strength of repulsive force between nodes (default: 5000) |
| `attractionStrength?` | `number` |  | Strength of attraction between connected nodes (default: 0.01) |
| `damping?` | `number` |  | Velocity damping factor (0-1, default: 0.9) |
| `temperature?` | `number` |  | Initial temperature for simulation (default: 100) |
| `coolingFactor?` | `number` |  | Cooling factor per iteration (default: 0.95) |
| `minDistance?` | `number` |  | Minimum distance between nodes (default: 50) |
| `maxDistance?` | `number` |  | Maximum distance for force calculation (default: 500) |
| `centerGravity?` | `number` |  | Center gravity strength (pulls towards center, default: 0.1) |
| `pinExistingNodes?` | `boolean` |  | Pin existing nodes (don't move them) |

### `ForceLayoutOptions`

Also has every member of `LayoutOptions`, listed on its own entry.

Force-directed layout options

```ts
interface ForceLayoutOptions extends LayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `repulsion?` | `number` |  | Repulsion strength between nodes (default: 100) |
| `attraction?` | `number` |  | Attraction strength along edges (default: 0.2) |
| `gravity?` | `number` |  | Gravity pulling nodes to center (default: 0.1) |
| `temperature?` | `number` |  | Initial temperature (default: 100) |
| `cooling?` | `number` |  | Cooling factor per iteration (default: 0.95) |
| `iterations?` | `number` |  | Number of iterations (default: 300) |
| `threshold?` | `number` |  | Minimum movement to continue (default: 0.1) |
| `useBarnesHut?` | `boolean` |  | Use Barnes-Hut approximation for large graphs (default: true) |
| `theta?` | `number` |  | Barnes-Hut theta parameter (default: 0.9) |
| `linkDistance?` | `number` |  | Edge length (default: 100) |
| `randomize?` | `boolean` |  | Randomize initial positions (default: true) |
| `removeOverlaps?` | `boolean` |  | The engine-wide "give me the algorithm's raw output" escape hatch (see UnifiedLayoutOptions in layout-registry.ts). `false` skips the adapter's snapshot-time residual-overlap cleanup too, so what comes back is literally the simulation state — same meaning as everywhere else. |

### `GraphComponent`

One connected component: its nodes, and the links that live entirely inside it.

```ts
interface GraphComponent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `NodeModel[]` |  |  |
| `links` | `LinkModel[]` |  |  |

### `GraphShape`

What kind of graph is this? Used to pick which candidates are worth RUNNING
(a bake-off over five algorithms on a 5,000-node graph is not free) — never to
pick the winner. The winner is always decided by measurement.

```ts
interface GraphShape
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeCount` | `number` |  |  |
| `linkCount` | `number` |  |  |
| `density` | `number` |  | links / max-possible-links. |
| `isTree` | `boolean` |  | No cycles, and every node has at most one parent. |
| `isDAG` | `boolean` |  | Directed, acyclic. |
| `components` | `number` |  | Number of connected components. |
| `hasDeclaredPorts` | `boolean` |  | Any node carries author-declared ports. |
| `hasEdgeLabels` | `boolean` |  | Any link carries a label. |

### `GridLayoutOptions`

Grid layout options

```ts
interface GridLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number \| 'auto'` |  | Number of columns (auto-calculated if not specified) |
| `startPosition?` | `Point` |  | Starting position |
| `horizontalSpacing?` | `number` |  | Horizontal spacing between nodes |
| `verticalSpacing?` | `number` |  | Vertical spacing between nodes |
| `nodeSize?` | `Size` |  | Node size for calculations (uses actual size if not specified) |
| `alignment?` | `'start' \| 'center' \| 'end'` |  | Alignment within grid cells |
| `direction?` | `'row' \| 'column'` |  | Direction of grid filling |

### `GridLayoutPortfolioOptions`

Also has every member of `UnifiedLayoutOptions`, `LayoutOptions`, `LayoutRunOptions`, listed on their own entries.

```ts
interface GridLayoutPortfolioOptions extends UnifiedLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Columns in the grid. Defaults to ceil(sqrt(n)) — a roughly square block. |

### `GroupInfo`

Group/container information for layout

```ts
interface GroupInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique group identifier |
| `parentId?` | `string` |  | Parent group ID (if nested) |
| `memberNodeIds` | `string[]` |  | Node IDs that belong to this group |
| `childGroupIds?` | `string[]` |  | Child group IDs (if this group contains other groups) |
| `padding?` | `{ top?: number; right?: number; bottom?: number; left?: number; }` |  | Padding inside the group container |
| `minSize?` | `{ width: number; height: number; }` |  | Minimum size for the group |
| `maxSize?` | `{ width: number; height: number; }` |  | Maximum size for the group |
| `fixed?` | `boolean` |  | Fixed position (group doesn't move during layout) |
| `fixedSize?` | `boolean` |  | Fixed size (group size doesn't change to fit content) |
| `layoutAlgorithm?` | `'dagre' \| 'elk' \| 'inherit'` |  | Layout algorithm to use for this group's contents |
| `layoutOptions?` | `any` |  | Layout options specific to this group |
| `collapsed?` | `boolean` |  | Whether this group should collapse its members visually |

### `HierarchicalOptions`

Hierarchical layout options (for future implementation)

```ts
interface HierarchicalOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `'TB' \| 'BT' \| 'LR' \| 'RL'` |  | Direction of hierarchy |
| `nodeSpacing?` | `number` |  | Spacing between nodes in same rank |
| `rankSpacing?` | `number` |  | Spacing between ranks/levels |
| `rankAlgorithm?` | `'longest-path' \| 'coffman-graham'` |  | Algorithm for rank assignment |
| `minimizeCrossings?` | `boolean` |  | Whether to minimize edge crossings |
| `preserveMentalMap?` | `boolean` |  | Preserve mental map when re-layouting |

### `HostLayoutResult`

Also has every member of `LayoutResult`, listed on its own entry.

```ts
interface HostLayoutResult extends LayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm` | `string` |  |  |
| `nodePositions` | `Map<string, { x: number; y: number }>` |  | Map of node IDs to their new positions |
| `bounds` | `{ x: number; y: number; width: number; height: number }` |  | Bounding box of the laid-out graph |
| `partial` | `boolean` |  | True when this is a best-so-far answer rather than a finished one. |
| `reason?` | `LayoutStopReason` |  |  |
| `iteration` | `number` |  |  |
| `totalIterations` | `number` |  |  |

### `HybridOptions`

Hybrid layout options

```ts
interface HybridOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fallbackAlgorithm?` | `'grid' \| 'force-directed' \| 'hierarchical'` |  | Fallback algorithm if pattern detection fails or confidence is low |
| `enableAutoSwitch?` | `boolean` |  | Enable automatic algorithm switching based on pattern detection (default: true) |
| `analysisThreshold?` | `number` |  | Confidence threshold for pattern detection (0-1, default: 0.7) If confidence is below this, fallback algorithm is used |
| `gridOptions?` | `GridLayoutOptions` |  | Options for each sub-algorithm |
| `forceDirectedOptions?` | `ForceDirectedOptions` |  |  |
| `hierarchicalOptions?` | `HierarchicalOptions` |  |  |