Layout — interfaces l–t

reference

10 min readUpdated 2026-10-05

Interfaces L–T

Import these from @grafloria/engine.

Interfaces

`LayoutRun`

An in-flight, pre-emptible layout computation.

Pure and synchronous by construction: no DOM, no clock, no Math.random().

ts
interface LayoutRun

Properties

Name	Type	Default	Description
`iteration`	`number`		Iterations completed so far.
`totalIterations`	`number`		Iterations this run would do if left alone — the denominator for progress.

Members

step(): boolean — Advance exactly one iteration.
snapshot(): LayoutResult — The best answer so far. Must be safe to call at ANY point — before the first step (returns the input positions), midway (returns the partial simulation), or after the last (returns the final layout).

`LayoutRunOptions`

Caller-side options that must NEVER cross the wire (they are not clonable).

ts
interface LayoutRunOptions

Properties

Name	Type	Description
`signal?`	`AbortSignal`	Cancel the run. Cooperative: takes effect within one slice.
`onProgress?`	`(progress: LayoutProgress) => void`	Streaming progress. Called on the caller's thread.
`timeBudgetMs?`	`number`	Give up after this long and return the best-so-far, flagged partial.
`sliceMs?`	`number`	Compute-between-yields, ms. Lower = promper cancellation, more overhead.
`stopAfterIteration?`	`number`	Deterministic pre-emption after N iterations. See LayoutRequestRun.

`LayoutSelectionReport`

What the auto-selector chose, and WHY. Returned on the layout result, so the reasoning is available to a UI, a log line or a test — never hidden.

ts
interface LayoutSelectionReport

Properties

Name	Type	Description
`chosen`	`string`	The candidate that won (its id, e.g. 'elk:layered ').
`algorithm`	`string`	The registered algorithm behind it.
`reason`	`string`	One sentence a human can read.
`shape`	`GraphShape`	What we worked out about the graph before choosing.
`candidates`	`CandidateScore[]`	Every candidate, scored, best first. Losers included on purpose.

`LayoutServePort`

The port surface the SERVER side needs — a worker's self satisfies it.

ts
interface LayoutServePort

Properties

Name	Type	Default	Description
`onmessage`	`((ev: { data: LayoutRequest }) => void) \| null`

Members

postMessage(msg: LayoutResponse): void

`LayoutSnapshot`

Snapshot of node positions at a point in time

ts
interface LayoutSnapshot

Properties

Name	Type	Description
`id`	`string`	Unique identifier for this snapshot
`timestamp`	`number`	Timestamp when snapshot was created
`positions`	`Map<string, { x: number; y: number }>`	Node positions
`description?`	`string`	Optional description
`algorithm?`	`string`	Layout algorithm used
`options?`	`any`	Layout options used

`NodeConstraint`

Constraint definition for a single node

ts
interface NodeConstraint

Properties

Name	Type	Description
`nodeId`	`string`	ID of the node this constraint applies to
`type`	`ConstraintType`	Type of constraint
`position?`	`Position`	Fixed position for 'pin' constraint The node will be locked to this exact position
`value?`	`number`	Fixed value for 'fix-x' or 'fix-y' constraints - For 'fix-x': The X coordinate is locked to this value, Y can vary - For 'fix-y': The Y coordinate is locked to this value, X can vary
`boundary?`	`Boundary`	Boundary limits for 'boundary' constraint The node position will be clamped within these bounds
`priority?`	`number`	Priority of this constraint (higher = more important) Used when constraints conflict (default: 0)

`OverlapRemovalOptions`

ts
interface OverlapRemovalOptions

Properties

Name	Type	Default	Description
`spacing?`	`number`		Gap to open up between two boxes that were overlapping.

`PackBox`

A box to pack, plus the id used to break ties deterministically.

ts
interface PackBox

Properties

Name	Type	Default	Description
`id`	`string`
`width`	`number`
`height`	`number`

`PackingOptions`

ts
interface PackingOptions

Properties

Name	Type	Default	Description
`spacing?`	`number`		Gap between packed components. Defaults to the layout's `nodeSpacing`.
`aspectRatio?`	`number`		Target width/height of the packed result. 1.6 ≈ a landscape screen.

`PlacementOptions`

Options for calculating node placement

ts
interface PlacementOptions

Properties

Name	Type	Description
`node`	`NodeModel`	The node to place
`viewport`	`Rectangle`	Current viewport dimensions
`existingNodes`	`NodeModel[]`	Existing nodes in the diagram
`preferredPosition?`	`Point`	Preferred position (optional hint)
`respectManualPositions?`	`boolean`	Whether to respect manual positions of existing nodes
`spacing?`	`number`	Spacing between nodes
`padding?`	`number`	Padding from viewport edges

`PlacementResult`

Result of placement calculation

ts
interface PlacementResult

Properties

Name	Type	Description
`position`	`Point`	Calculated position for the node
`success`	`boolean`	Whether placement was successful
`metadata?`	`{ /** * Grid position (for grid layouts) / gridPosition?: { row: number; column: number }; /* * Pattern detected (for hybrid layouts) / detectedPattern?: 'grid' \| 'tree' \| 'freeform'; /* * Reason for placement choice / reason?: string; /* * Number of attempts made (for iterative placement) / attempt?: number; /* * Allow additional metadata properties */ [key: string]: any; }`	Metadata about the placement decision

`Point2D`

Point in 2D space

ts
interface Point2D

Properties

Name	Type	Default	Description
`x`	`number`
`y`	`number`

`PortAwareLayoutOptions`

Configuration for port-aware layout

ts
interface PortAwareLayoutOptions

Properties

Name	Type	Description
`enabled`	`boolean`	Enable port-aware layout
`ports?`	`PortInfo[]`	Port information for all ports in the diagram
`autoAssignSides?`	`boolean`	Automatic port side assignment based on node connections
`autoOrderPorts?`	`boolean`	Automatic port ordering to minimize crossings
`inputSide?`	`PortSide`	Prefer inputs on specific side
`outputSide?`	`PortSide`	Prefer outputs on specific side
`portSpacing?`	`number`	Minimum spacing between ports (in pixels)
`usePortPositions?`	`boolean`	Whether to consider port positions in edge routing
`orderingStrategy?`	`'minimize-crossings' \| 'connection-based' \| 'group-based' \| 'manual'`	Strategy for port ordering
`nodeSidePreferences?`	`{ [nodeId: string]: { inputs?: PortSide; outputs?: PortSide; }; }`	Node-specific port side preferences
`portOrdering?`	`{ [nodeId: string]: string[]; // Ordered list of port IDs for this node }`	Per-port ordering constraints

`PortAwareLayoutResult`

Result of port-aware layout computation

ts
interface PortAwareLayoutResult

Properties

Name	Type	Description
`portAssignments`	`Map<string, PortSide>`	Final port assignments (port ID -> side)
`portOrdering`	`Map<string, string[]>`	Final port ordering (node ID -> ordered port IDs)
`portPositions`	`Map<string, { x: number; y: number; side: PortSide }>`	Calculated port positions (port ID -> {x, y} relative to node)
`edgeCrossings`	`number`	Number of edge crossings
`wasOptimized`	`boolean`	Whether port positions were optimized
`autoAssignedPorts`	`string[]`	Ports that were automatically assigned sides
`autoOrderedPorts`	`string[]`	Ports that were automatically ordered

`PortInfo`

Information about a port for layout purposes

ts
interface PortInfo

Properties

Name	Type	Description
`id`	`string`	Port unique identifier
`nodeId`	`string`	Node this port belongs to
`preferredSide?`	`PortSide`	Preferred side of the node
`direction?`	`PortFlowDirection`	Port direction
`offset?`	`number`	Position along the side (0-1, where 0 is top/left, 1 is bottom/right)
`fixed?`	`boolean`	Fixed position (prevents automatic ordering)
`priority?`	`number`	Priority for ordering (higher = more important)
`group?`	`string`	Group identifier for related ports

`PortRespectResult`

ts
interface PortRespectResult

Properties

Name	Type	Description
`violations`	`number`	Links whose endpoint travels AGAINST the side its port faces.
`judged`	`number`	Links that could be judged (both ends resolvable, both nodes placed).
`score`	`number`	100 = every port-constrained edge leaves in the direction its port faces.
`violatingLinks`	`string[]`	Which links violated, for the report.

`Position`

Position definition for pinned nodes

ts
interface Position

Properties

Name	Type	Default	Description
`x`	`number`
`y`	`number`

`QualityAssessmentOptions`

Options for quality assessment

ts
interface QualityAssessmentOptions

Properties

Name	Type	Description
`includeSuggestions?`	`boolean`	Whether to include detailed suggestions
`customWeights?`	`{ edgeCrossings?: number; nodeOverlap?: number; edgeLength?: number; nodeDistribution?: number; symmetry?: number; aspectRatio?: number; }`	Custom metric weights (overrides defaults)
`canvasDimensions?`	`{ width: number; height: number; }`	Canvas dimensions for aspect ratio calculation

`QualityMetric`

Individual quality metric

ts
interface QualityMetric

Properties

Name	Type	Description
`name`	`string`	Metric name
`score`	`number`	Score (0-100, higher is better)
`weight`	`number`	Weight of this metric in overall score
`description`	`string`	Description of what this measures
`suggestions?`	`string[]`	Suggestions for improvement

`RadialLayoutOptions`

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

ts
interface RadialLayoutOptions extends UnifiedLayoutOptions

Properties

Name	Type	Default	Description
`rootId?`	`string`		Centre of the rings. Defaults to a source node, else the hub. See pickRoot.

`RegisteredLayout`

What a registered layout engine must be able to do.

ts
interface RegisteredLayout

Properties

Name	Type	Description
`name`	`string`
`adapter?`	`LayoutAdapter`	The underlying node/link algorithm, when the engine has one.
`handlesContainers?`	`boolean`	The layout arranges CONTAINERS itself — zones are part of its composition (the architecture layout puts regions on a grid and sizes their frames), so `engine.layout()` must not hand it to the nested-container path, which lays out one container at a time with some other engine.

Members

apply(diagram: DiagramModel, options: UnifiedLayoutOptions): Promise<LayoutResult>

`ScalePlan`

A structural engine choice made without running a bake-off.

ts
interface ScalePlan

Properties

Name	Type	Default	Description
`candidates`	`LayoutCandidate[]`		Candidates to try, best-first; the first that runs wins.
`why`	`string`		The structural fact the pick rests on — goes into the report verbatim.

`ServeLayoutDeps`

ts
interface ServeLayoutDeps

Properties

Name	Type	Default	Description
`resolve?`	`(name: string) => LayoutAdapter \| undefined`		Name → algorithm. Injected, because the INLINE host resolves against the engine's live registry (so a host-registered custom layout still works), while a real worker resolves against whatever its own bundle registered — a function cannot be posted across a thread boundary, so an extension layout registered at runtime is inline-only, by physics rather than choice.
`now?`	`() => number`		The clock. Injected so tests can stop it lying.

`SpectralLayoutOptions`

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

Spectral layout options

ts
interface SpectralLayoutOptions extends LayoutOptions

Properties

Name	Type	Description
`normalized?`	`boolean`	Use normalized Laplacian (default: true)
`dimensions?`	`number`	Number of dimensions to compute (default: 2)
`scale?`	`number`	Scale factor for positions (default: 500)
`center?`	`boolean`	Center the layout (default: true)
`convergenceThreshold?`	`number`	Power iteration convergence threshold (default: 1e-6)
`maxIterations?`	`number`	Maximum power iterations (default: 1000)

`SteppableLayoutAdapter`

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

A layout adapter that can be driven a step at a time.

Optional: isSteppable() is a type guard, and the host degrades gracefully for adapters that are not.

ts
interface SteppableLayoutAdapter extends LayoutAdapter

Members

createRun( nodes: NodeModel[], links: LinkModel[], options?: Partial<LayoutOptions> ): LayoutRun

`SubgraphLayoutOptions`

Configuration for subgraph layout

ts
interface SubgraphLayoutOptions

Properties

Name	Type	Description
`enabled`	`boolean`	Enable subgraph/group layout
`groups?`	`GroupInfo[]`	Group information for all groups in the diagram
`targetGroups?`	`string[]`	Specific group IDs to layout (if undefined, layout all)
`recursive?`	`boolean`	Whether to recursively layout nested groups
`defaultPadding?`	`number`	Default padding for groups without explicit padding
`boundaryHandling?`	`'strict' \| 'flexible' \| 'none'`	How to handle group boundaries
`layoutTopLevel?`	`boolean`	Whether to layout the top-level (non-grouped) nodes
`groupPositioning?`	`'compact' \| 'spacious' \| 'grid' \| 'manual'`	Strategy for positioning groups relative to each other
`groupSpacing?`	`number`	Spacing between groups
`autoResize?`	`boolean`	Whether to automatically resize groups to fit content
`maintainAspectRatio?`	`boolean`	Whether to maintain aspect ratio when resizing groups
`interGroupLinks?`	`'route-around' \| 'direct' \| 'hidden'`	How to handle links between groups

`SubgraphLayoutResult`

Result of subgraph layout computation

ts
interface SubgraphLayoutResult

Properties

Name	Type	Description
`nodePositions`	`Map<string, { x: number; y: number; groupId?: string }>`	Node positions within their groups (node ID -> position)
`groupPositions`	`Map<string, { x: number; y: number }>`	Group positions (group ID -> position)
`groupSizes`	`Map<string, { width: number; height: number }>`	Computed group sizes (group ID -> size)
`laidOutGroups`	`string[]`	Groups that were laid out
`skippedGroups`	`string[]`	Groups that were skipped (fixed, collapsed, etc.)
`bounds`	`{ x: number; y: number; width: number; height: number }`	Overall bounds
`wasRecursive`	`boolean`	Whether groups were recursively laid out

`TreeLayoutOptions`

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

ts
interface TreeLayoutOptions extends UnifiedLayoutOptions

Properties

Name	Type	Default	Description
`rootId?`	`string`		Root of the tree. Defaults to a source node (in-degree 0), else the hub.
`branchDirections?`	`Record<string, FlowDirection>`		Per-branch direction: the subtree rooted at this node flows this way instead of the tree's `direction`. A mind map is `{ 'child-a': 'LR', 'child-b': 'RL' }`.

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →