# Interfaces A–T

Import these from `@grafloria/renderer`.

## Interfaces

### `AddWaypointResult`

Result of adding a waypoint

```ts
interface AddWaypointResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `newPoints` | `Point[]` |  |  |
| `waypointIndex` | `number` |  |  |
| `segmentIndex` | `number` |  |  |

### `AlignmentGuide`

A single alignment snapline. `position` is the aligned coordinate.

```ts
interface AlignmentGuide
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'vertical' \| 'horizontal'` |  |  |
| `position` | `number` |  | World x (vertical guide) or world y (horizontal guide). |
| `from` | `number` |  | Extent of the drawn line along the other axis. |
| `to` | `number` |  |  |
| `kind` | `'edge' \| 'center'` |  |  |

### `Announcement`

```ts
interface Announcement
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `string` |  |  |
| `politeness` | `'polite' \| 'assertive'` |  | `assertive` interrupts the screen reader (errors); default polite. |
| `seq` | `number` |  | Monotonic counter — hosts re-announce only when this changes. |

### `ControlPoint`

Control point information

```ts
interface ControlPoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `point` | `Point` |  | Position of the control point |
| `segmentIndex` | `number` |  | Index of the segment this control point belongs to |
| `type` | `'control1' \| 'control2'` |  | Type of control point (control1 or control2) |
| `anchor` | `Point` |  | Anchor point (from/to) that this control point affects |

### `ControlPointHitResult`

Result of hit testing a control point

```ts
interface ControlPointHitResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `segmentIndex` | `number` |  | Index of the segment |
| `controlType` | `'control1' \| 'control2'` |  | Type of control point |
| `point` | `Point` |  | Position of the control point |
| `anchor` | `Point` |  | Anchor point |

### `DrawToolOptions`

```ts
interface DrawToolOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `string` |  |  |
| `width?` | `number` |  |  |
| `opacity?` | `number` |  | Highlighter ink is translucent. |
| `simplifyEpsilon?` | `number` |  | Douglas-Peucker tolerance at commit. Omit to use the model's tuned default. |
| `label?` | `string` |  | An author label for the committed ink — makes it a NAMED annotation in the a11y tree. |
| `active?` | `boolean` |  |  |

### `EraserToolOptions`

```ts
interface EraserToolOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `radius?` | `number` |  | Extra hit radius in world units around the eraser path. Default 8. |
| `active?` | `boolean` |  |  |

### `FocusRing`

What the host draws as the visible focus ring.

```ts
interface FocusRing
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `FocusTargetType` |  |  |
| `id` | `string` |  |  |
| `bounds?` | `Rectangle` |  | Nodes: the padded world box. |
| `rotation?` | `number` |  |  |
| `points?` | `Point[]` |  | Links: the routed polyline. |
| `label` | `string` |  | The accessible name announced for this target. |

### `FocusTarget`

```ts
interface FocusTarget
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `FocusTargetType` |  |  |
| `id` | `string` |  |  |

### `Highlighter`

```ts
interface Highlighter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable key for the host's keyed list. |
| `kind` | `HighlighterKind` |  |  |
| `entity` | `'node' \| 'link'` |  |  |
| `entityId` | `string` |  |  |
| `bounds?` | `Rectangle` |  | Node highlighters: the padded world box to outline. |
| `rotation?` | `number` |  | Node highlighters: rotation (deg) about the box centre. |
| `points?` | `Point[]` |  | Link highlighters: the routed polyline to trace. |
| `severity?` | `'error' \| 'warning'` |  |  |
| `message?` | `string` |  | Validation message (also the accessible description). |
| `className` | `string` |  | Suggested CSS class, so a host can theme without re-deriving the kind. |

### `HighlighterConfig`

```ts
interface HighlighterConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `hoverPadding` | `number` |  | World padding around a node's box, per kind. |
| `selectionPadding` | `number` |  |  |
| `validationPadding` | `number` |  |  |
| `showHover` | `boolean` |  |  |
| `showSelection` | `boolean` |  |  |
| `showValidation` | `boolean` |  |  |
| `showConnectTargets` | `boolean` |  |  |

### `InkOverlayOptions`

```ts
interface InkOverlayOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement` |  | The mounted diagram's root (`.grafloria-diagram-root`). |
| `viewport` | `ViewportController` |  |  |

### `InkPreviewStyle`

How a preview should look while it is being drawn.

```ts
interface InkPreviewStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` |  |  |
| `width` | `number` |  |  |
| `opacity?` | `number` |  |  |
| `dashed?` | `boolean` |  | Dashed outline, for the rectangle tool's rubber-band. |

### `KeyboardConnectState`

The keyboard-connect state machine.

```ts
interface KeyboardConnectState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `phase` | `'source' \| 'target'` |  |  |
| `sourceNodeId` | `string` |  |  |
| `sourcePortId` | `string` |  |  |
| `targetNodeId?` | `string` |  |  |
| `targetPortId?` | `string` |  |  |
| `valid` | `boolean` |  | True when the current source/target pair is a legal link. |

### `KeyboardNavConfig`

```ts
interface KeyboardNavConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nudgeStep` | `number` |  | Fine nudge step, world units (arrow key). |
| `coarseNudgeStep` | `number` |  | Coarse nudge step, world units (Shift + arrow). |
| `wrapFocus` | `boolean` |  | Focus wraps around at the ends of the order. |
| `focusRingPadding` | `number` |  | World padding of the focus ring around a node's box. |

### `LinkPartHit`

Part-aware link hit result: a link plus WHICH sub-part of it was hit
(body / label / endpoint / arrow) and local info (label index, or the 0-1
position `t` along the path for body hits). Downstream edge features
(inline label editing, endpoint reconnection, edge toolbar) key off `part`.

```ts
interface LinkPartHit
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  |  |
| `part` | `LinkPart` |  |  |
| `labelIndex?` | `number` |  |  |
| `t?` | `number` |  |  |

### `PathHitResult`

Result of hit testing a path segment

```ts
interface PathHitResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `segmentIndex` | `number` |  |  |
| `insertPosition` | `Point` |  |  |
| `insertIndex` | `number` |  |  |
| `distance` | `number` |  |  |

### `Point`

Point in 2D space

```ts
interface Point
```

**Properties**

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

### `PortHit`

A port the magnet found, with its owner.

```ts
interface PortHit
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `port` | `PortModel` |  |  |
| `node` | `NodeModel` |  |  |
| `position` | `Point` |  | World position of the port. |
| `distance` | `number` |  |  |

### `ProximityCandidate`

A proximity-connect candidate: link `source` → `target` if the user drops here.

```ts
interface ProximityCandidate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sourcePort` | `PortModel` |  |  |
| `targetPort` | `PortModel` |  |  |
| `sourceNodeId` | `string` |  |  |
| `targetNodeId` | `string` |  |  |
| `distance` | `number` |  |  |

### `RectangleToolOptions`

```ts
interface RectangleToolOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth?` | `number` |  |  |
| `minSize?` | `number` |  | Below this size (world px) the drag is treated as a mis-click and no node is made. |
| `label?` | `string` |  |  |
| `active?` | `boolean` |  |  |

### `ResizeOptions`

```ts
interface ResizeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minWidth?` | `number` |  |  |
| `minHeight?` | `number` |  |  |
| `maxWidth?` | `number` |  | Upper bound on the dragged size, clamped DURING the gesture. Default ∞. |
| `maxHeight?` | `number` |  |  |
| `keepAspect?` | `boolean` |  | Preserve the starting aspect ratio (corner handles only). |
| `aspect?` | `number` |  | Explicit width÷height ratio to lock to (corner handles only). Set by a per-node aspect lock; overrides the start ratio and implies keepAspect. |

### `SelectionToolLayer`

Everything the host needs to draw the tool layer for the current selection.

```ts
interface SelectionToolLayer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bounds` | `Rectangle \| null` |  | World bbox of the selection; null when nothing is selected. |
| `rotation` | `number` |  | Rotation (deg) of the single selected node; 0 otherwise. |
| `center` | `Point \| null` |  | World centre the bounds rotate about (the frame outline follows it). |
| `nodeIds` | `string[]` |  |  |
| `linkIds` | `string[]` |  |  |
| `handles` | `ToolHandle[]` |  |  |

### `SelectionToolsConfig`

```ts
interface SelectionToolsConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `handleSize` | `number` |  | Side of a square resize handle, in SCREEN px. |
| `rotateHandleOffset` | `number` |  | Distance from the selection's top edge to the rotate handle, SCREEN px. |
| `haloGap` | `number` |  | Gap between the selection box and the halo column, SCREEN px. |
| `haloButtonSize` | `number` |  | Diameter of a halo button, SCREEN px. |
| `showHalo` | `boolean` |  | Show the Halo context toolbar. |
| `showResizeHandles` | `boolean` |  | Show the 8 resize handles (single-node selection only). |
| `showRotateHandle` | `boolean` |  | Show the rotate handle (single-node selection, `behavior.rotatable`). |
| `showRemoveButton` | `boolean` |  | Show the ✕ remove button. |
| `showLinkTools` | `boolean` |  | Show link endpoint / vertex tools for a selected link. |
| `minWidth` | `number` |  | Smallest width/height a resize may produce, WORLD units. |
| `minHeight` | `number` |  |  |
| `rotationSnapDegrees` | `number` |  | Rotation snap while a modifier is held, in degrees. |
| `resolveNodeToolbar?` | `ToolbarResolver` |  | Per-TYPE toolbar policy. Layered on top of each node's own `metadata.toolbar`; lets a host decide which tools a node type exposes without touching per-node data. Omit for "every tool, every node". |

### `SnapConfig`

Framework-agnostic and pure w.r.t. the geometry it is handed: `computeSnap`
takes the moving box + the boxes it may align to and returns the corrected box
PLUS the guides a host should draw. Nothing here renders, and nothing mutates
the model — except the explicit port-highlight helper, which sets the same
`isHighlighted` / `isValidTarget` flags the renderer already draws for
connection dragging.

Everything is measured in WORLD units. Hosts that want a constant on-screen
feel pass `snapThreshold: px / zoom` (see `DiagramCanvasComponent`).

```ts
interface SnapConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  | Master switch for alignment snaplines + equal spacing. |
| `snapToGrid` | `boolean` |  | Quantise the box to a grid (applied when no alignment guide claims an axis). |
| `gridSize` | `number` |  |  |
| `snapThreshold` | `number` |  | Distance (world units) within which an alignment candidate snaps. |
| `equalSpacing` | `boolean` |  | Emit equal-spacing guides (Figma/GoJS-style distribution hints). |
| `keepInBounds` | `Rectangle \| null` |  | World rectangle the moving box must stay inside (null = unbounded). |
| `snapToPortRadius` | `number` |  | Magnetic port radius — the engine's `snapToPortRadius` lives here. |
| `proximityConnectRadius` | `number` |  | Drop-a-node-near-a-port auto-link radius (React-Flow proximity connect). |

### `SnapResult`

```ts
interface SnapResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `box` | `Rectangle` |  | The corrected box (grid / alignment / spacing / bounds applied). |
| `dx` | `number` |  | Correction applied to the input box. |
| `dy` | `number` |  |  |
| `guides` | `AlignmentGuide[]` |  |  |
| `spacing` | `SpacingGuide[]` |  |  |

### `SpacingGuide`

An equal-spacing hint: two or more equal gaps, each with a distance label.

```ts
interface SpacingGuide
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` |  |  |
| `gap` | `number` |  | The equal gap, in world units. |
| `label` | `string` |  | Human label the host draws at the segment's midpoint (e.g. "40"). |
| `segments` | `Array<{ x1: number; y1: number; x2: number; y2: number }>` |  | The measured gaps, as segments to draw. |

### `StrokeEditToolOptions`

```ts
interface StrokeEditToolOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tolerance?` | `number` |  | Extra hit radius in world units around the ink. Default 6 — finger-friendly. |
| `highlightColor?` | `string` |  | Highlight colour for the selected stroke's ghost. |
| `active?` | `boolean` |  |  |

### `TextEditSession`

```ts
interface TextEditSession
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `target` | `TextEditTarget` |  |  |
| `value` | `string` |  | The text the editor opens with. |
| `bounds` | `Rectangle` |  | World rectangle the editor should cover. |
| `center` | `Point` |  | World point the editor centres on (labels have no box of their own). |
| `multiline` | `boolean` |  | Node labels wrap; link labels are single-line. |

### `TextEditTarget`

```ts
interface TextEditTarget
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `TextEditTargetType` |  |  |
| `nodeId?` | `string` |  | Node being edited (`type: 'node'`). |
| `linkId?` | `string` |  | Link owning the label (`type: 'link-label'`). |
| `labelIndex?` | `number` |  | Which label on that link. Links carry TWO label dialects: the positioned `labels[]` collection, and the DISPLAY label every spec input writes (`edges: [{label}]` → `metadata.label`, painted at the path midpoint). |

### `ToolModifierState`

Modifier snapshot a host forwards from its pointer events.

```ts
interface ToolModifierState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shift?` | `boolean` |  |  |
| `alt?` | `boolean` |  |  |
| `ctrl?` | `boolean` |  |  |
| `meta?` | `boolean` |  |  |

### `TouchGestureHost`

Everything the gesture controller needs from its host (keeps it DI-free).

```ts
interface TouchGestureHost
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `ViewportController` |  |  |
| `interaction` | `InteractionController` |  |  |

**Members**

- `getEngine(): DiagramEngine | null`
- `getRect(): CanvasRect`
- `requestRender(): void`
- `emit(event: string, payload: unknown): void`
- `isReadonly(): boolean` — Live read — read-only can be toggled while the canvas is mounted.

### `TouchGestureOptions`

```ts
interface TouchGestureOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enablePan?` | `boolean` |  |  |
| `enableZoom?` | `boolean` |  |  |
| `longPressMs?` | `number` |  | ms a finger must rest before it becomes a context-menu gesture. Default 500. |
| `moveTolerancePx?` | `number` |  | CSS px of travel that cancels a long-press / promotes a tap to a drag. Default 10. |
| `tapMaxMs?` | `number` |  | Max ms for a press+release to count as a tap. Default 300. |