# Grafloria · GPT-6 Luna

<!-- source: javascript-quick-start.md -->

# JavaScript quick start

Mount a sized, interactive diagram in plain JavaScript with either [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) or the `<grafloria-flow>` custom element.

Grafloria has one headless model underneath its framework bindings; the element and `render()` give you two ways to mount that same diagram in a browser.

## Prerequisites

- A browser project that runs JavaScript modules and can resolve npm packages (the steps below use Vite).
- `@grafloria/element` 0.4.83, with peer dependencies `@grafloria/engine` `^0.3.16` and `@grafloria/renderer` `^0.4.15`.

## Install

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
npm install --save-dev vite
```

Add a `dev` script that runs Vite, or start the local server with `npx vite` from your project directory.

## 1. Mount with `render()`

Use `render()` when you want the live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) returned to your JavaScript code. It takes the diagram data first and then a sized target element.

Create `index.html` with a real height for the canvas:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Grafloria flow</title>
    <style>
      html, body { margin: 0; height: 100%; }
      #canvas { width: 100%; height: 80vh; }
    </style>
  </head>
  <body>
    <div id="canvas"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
```

In `src/main.js`, pass a spec containing two nodes and an edge:

```js
import { render } from '@grafloria/element';

const canvas = document.getElementById('canvas');
if (!(canvas instanceof HTMLElement)) {
  throw new Error('Canvas element not found');
}
canvas.style.height = '80vh';
const diagram = render({
  nodes: [
    { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Ingest' } },
    { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Publish' } },
  ],
  edges: [{ id: 'ingest-to-publish', source: 'ingest', target: 'publish' }],
}, canvas);
```

![Look at the canvas immediately after `render()` mounts the diagram.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7f794eb07613b0168e61389e4b23a2f0.png)

The canvas shows **Ingest** connected to **Publish**. You can drag nodes, connect them, pan, and zoom; `diagram` is the returned instance for further operations. The spec is diagram data, not Mermaid text.

## 2. Or mount the custom element

Choose `<grafloria-flow>` when HTML attributes are the natural place to provide the diagram. Import the package from your JavaScript module to register the element, then put JSON arrays in its `nodes` and `edges` attributes.

Use this `index.html` instead of the `render()` version above. The element fills its own box, so give the element a resolved height:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Grafloria flow</title>
    <style>
      html, body { margin: 0; height: 100%; }
      grafloria-flow { display: block; width: 100%; height: 80vh; }
    </style>
  </head>
  <body>
    <grafloria-flow
      nodes='[{"id":"extract","position":{"x":60,"y":80},"label":"Extract"},{"id":"load","position":{"x":300,"y":80},"label":"Load"}]'
      edges='[{"id":"extract-to-load","source":"extract","target":"load"}]'>
    </grafloria-flow>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
```

Use the exported [`GrafloriaFlowElement`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#grafloriaflowelement) class to narrow the queried element to the custom-element API. Importing the package registers the default tag.

```js
import { GrafloriaFlowElement } from '@grafloria/element';

const element = document.querySelector('grafloria-flow');
const flow = element instanceof GrafloriaFlowElement
  ? element
  : new GrafloriaFlowElement();
if (!(element instanceof GrafloriaFlowElement)) {
  flow.style.width = '100%';
  flow.style.height = '80vh';
  flow.nodes = [
    { id: 'extract', position: { x: 60, y: 80 }, label: 'Extract' },
    { id: 'load', position: { x: 300, y: 80 }, label: 'Load' },
  ];
  flow.edges = [{ id: 'extract-to-load', source: 'extract', target: 'load' }];
  document.body.append(flow);
}
flow.fitView();
```

![Look at the element's canvas immediately after it mounts the diagram.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/42b3472cdef8fbf1c92b4def8af7528a.png)

The element shows **Extract** connected to **Load**, and `flow.fitView()` frames the diagram in the element. Its `nodes` and `edges` values are JSON strings in HTML; for rich JavaScript objects, set the element's `nodes` and `edges` properties instead. The element exposes its instance through `diagram` when you need the instance API.

## What you have

Both entry points mount an interactive diagram with a visible edge in a container with a real height. `render()` returns the instance directly; the custom element gives you HTML attributes and DOM events, and disposes its diagram when disconnected.

## Where next

- The [`<grafloria-flow>` reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#grafloriaflowelement) documents the element class and its API.
- [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the model, document, and command concepts behind the bindings.
- [Open the JavaScript starter in StackBlitz](https://stackblitz.com/github/grafloria/grafloria/tree/main/starters/javascript?file=src/main.js) to run the `render()` sample, or browse the [live demo gallery](https://grafloria.com/demos/).

<!-- source: react-quick-start.md -->

# React quick start

Build a working diagram in React, connect sibling UI to its live instance, and render kit diagrams and comment threads.

One headless model drives every framework binding: the React components are framework-specific skins over the same diagram engine.

## Prerequisites

Use a browser-based React app with React and React DOM 17, 18, or 19. The `@grafloria/react` 0.10.6 package declares peers `@grafloria/engine` `^0.3.0`, `@grafloria/renderer` `^0.4.16`, and `@grafloria/element` `^0.4.3`.

Install the binding and its peers:

```bash
npm install @grafloria/react @grafloria/engine @grafloria/renderer @grafloria/element react react-dom
```

## 1. Mount a flow

Use [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow) for an interactive node-and-edge canvas. The starter data uses [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec); `defaultNodes` and `defaultEdges` seed an uncontrolled diagram, which the instance owns after mount.

```tsx
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Ingest' } },
  { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Publish' } },
];

const edges: EdgeSpec[] = [{ id: 'e1', source: 'ingest', target: 'publish' }];

export default function App() {
  return (
    <div style={{ height: '100vh' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} plugins />
    </div>
  );
}
```

![The Ingest and Publish nodes appear connected in the mounted canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/34a9b527931125821d2696da3475dd6f.png)

The mounted canvas shows Ingest connected to Publish, with the minimap, zoom and fit controls, and background supplied by `plugins`. Give the wrapper a resolved height; the canvas fills its parent.

## 2. Keep controlled data in React state

When application UI owns the graph, [`useNodesState`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#usenodesstate) and [`useEdgesState`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#useedgesstate) provide state plus a separate callback for changes coming back from the canvas. Keep both callback connections: without `onNodesChange`, for example, a node drag can be overwritten by stale controlled state on the next render.

```tsx
import { GrafloriaFlow, useEdgesState, useNodesState } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const initialNodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, label: 'Ingest' },
  { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, label: 'Publish' },
];

const initialEdges: EdgeSpec[] = [{ id: 'e1', source: 'ingest', target: 'publish' }];

export default function ControlledFlow() {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, , onEdgesChange] = useEdgesState(initialEdges);

  return (
    <div style={{ height: 440, display: 'flex', flexDirection: 'column' }}>
      <button
        onClick={() => setNodes((all) => [
          ...all,
          { id: `step-${all.length}`, position: { x: 220, y: 240 }, label: 'New step' },
        ])}
      >
        Add node
      </button>
      <GrafloriaFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        style={{ flex: 1, minHeight: 0 }}
      />
    </div>
  );
}
```

![The controlled canvas shows its Add node button and the connected Ingest and Publish nodes.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/5a92ce8cf362520f0a721000cc676145.png)

The button adds a node to React state, and dragging or deleting nodes and edges sends the resulting models back through the third tuple values. The second tuple value updates React's specs; it is not the canvas change callback.

## 3. Reach the canvas from sibling UI

Wrap a toolbar and canvas in [`GrafloriaProvider`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaprovider) when the toolbar is outside the flow subtree. [`useGrafloria`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#usegrafloria) returns the live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance), or `null` until the flow mounts. The toolbar below calls `fitView()` on that instance.

For live readouts, [`useSelection`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#useselection) returns the current selection as state, [`useOnSelectionChange`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#useonselectionchange) runs a callback when it changes, and [`useViewport`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#useviewport) returns the camera state. [`useGrafloriaStore`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#usegrafloriastore) exposes the nearest store itself; use it when you need the store rather than only its instance.

```tsx
import { useState } from 'react';
import {
  GrafloriaFlow,
  GrafloriaProvider,
  useGrafloria,
  useGrafloriaStore,
  useOnSelectionChange,
  useSelection,
  useViewport,
} from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'draft', position: { x: 40, y: 80 }, label: 'Draft' },
  { id: 'review', position: { x: 280, y: 80 }, label: 'Review' },
];

const edges: EdgeSpec[] = [{ id: 'e1', source: 'draft', target: 'review' }];

function Toolbar() {
  const instance = useGrafloria();

  return (
    <button disabled={!instance} onClick={() => instance?.fitView()}>
      Fit diagram
    </button>
  );
}

function CanvasReadout() {
  const store = useGrafloriaStore();
  const instance = useGrafloria();
  const { nodes: selectedNodes } = useSelection();
  const { zoom } = useViewport();
  const [selectionEvents, setSelectionEvents] = useState(0);

  useOnSelectionChange(() => setSelectionEvents((count) => count + 1));

  const storeConnected = instance !== null && store?.get() === instance;

  return (
    <output>
      {storeConnected ? 'Canvas connected' : 'Waiting for canvas'} ·{' '}
      {selectedNodes.length} selected · {Math.round(zoom * 100)}% zoom ·{' '}
      {selectionEvents} selection changes
    </output>
  );
}

export default function App() {
  return (
    <GrafloriaProvider>
      <div style={{ height: 440, display: 'flex', flexDirection: 'column' }}>
        <Toolbar />
        <CanvasReadout />
        <GrafloriaFlow
          defaultNodes={nodes}
          defaultEdges={edges}
          style={{ flex: 1, minHeight: 0 }}
        />
      </div>
    </GrafloriaProvider>
  );
}
```

![Fit diagram and the selection and zoom readout sit above the connected canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/54c417ee83972c441008ab984cf63d95.png)

The toolbar is a sibling of the canvas, and Fit diagram frames its nodes when clicked. The readout shows the selected-node count and zoom; selecting a node updates the count and selection-change total. A single flow can also publish its instance to its own children without a provider; use the provider for components outside that subtree.

## 4. Render a kit diagram

Use [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriadiagram) when you have a diagram spec rather than node and edge props. This example passes a JSON-encoded spec string; the mounted component renders a connected Ingest-to-Publish diagram.

```tsx
import { GrafloriaDiagram } from '@grafloria/react';

const spec = JSON.stringify({
  nodes: [
    { id: 'ingest', position: { x: 40, y: 80 }, data: { label: 'Ingest' } },
    { id: 'publish', position: { x: 280, y: 80 }, data: { label: 'Publish' } },
  ],
  edges: [{ id: 'e1', source: 'ingest', target: 'publish' }],
});

export default function KitDiagram() {
  return (
    <div style={{ height: 440 }}>
      <GrafloriaDiagram spec={spec} />
    </div>
  );
}
```

![The diagram shows Ingest connected to Publish.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/bbde5f4755399111d28401894d2b8718.png)

## 5. Add a comment panel

Set `comments` on the flow to enable its comment store, then pass that store to [`GrafloriaCommentPanel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriacommentpanel). [`CommentStore`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-comments-commentstore#commentstore) is available from the instance after mount; this example anchors a starter thread to the Review node.

```tsx
import { useState } from 'react';
import { GrafloriaCommentPanel, GrafloriaFlow } from '@grafloria/react';
import type { CommentStore } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'design', position: { x: 40, y: 100 }, size: { width: 150, height: 66 }, label: 'Design' },
  { id: 'review', position: { x: 260, y: 100 }, size: { width: 150, height: 66 }, label: 'Review' },
];

const edges: EdgeSpec[] = [{ id: 'e1', source: 'design', target: 'review' }];

export default function FlowWithComments() {
  const [store, setStore] = useState<CommentStore | null>(null);

  return (
    <div style={{ display: 'flex', height: 440 }}>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        comments
        style={{ flex: 1, minWidth: 0 }}
        onInit={(instance) => {
          const commentStore = instance.getCommentStore();
          if (commentStore) {
            commentStore.createThread(
              { kind: 'node', id: 'review' },
              'Can we tighten the review step?'
            );
            setStore(commentStore);
          }
        }}
      />
      {store && (
        <div style={{ width: 300, overflow: 'auto' }}>
          <GrafloriaCommentPanel store={store} />
        </div>
      )}
    </div>
  );
}
```

![A comment thread about the Review step appears beside the connected Design and Review nodes.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/68cebc7a53efbfdc4e74440f54bfb270.png)

The canvas renders Design and Review with their edge, and the panel appears beside it with a thread attached to Review. The panel follows the store passed at mount; this example keeps that store in React state until the component unmounts.

## What you have

You now have an interactive React canvas, controlled state that stays synchronized with edits, sibling UI that reaches the canvas instance, a generic kit-diagram host, and a comment panel bound to the canvas store.

## Where next

- [Every demo as a React component](https://grafloria.com/demos-react/) — see the live React examples.
- [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) — the model and engine ideas behind the bindings.
- [The instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow) — follow data between React and the live diagram.
- [Custom nodes in React](https://grafloria.com/learn/react-custom-nodes/) — render React components for node types.

<!-- source: vue-quick-start.md -->

# Vue quick start

Render a flow, connect sibling UI to its live instance, and mount the diagram and comments components in a Vue 3 app.

One headless model drives every framework binding, so you can learn the model once and use the same diagram behavior across frameworks.

## Prerequisites

Use Vue 3.4 or later; for the shared engine, renderer, and element package setup, see the [JavaScript quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/javascript-quick-start).

Install the binding and its peers:

```bash
npm install @grafloria/vue @grafloria/engine @grafloria/renderer @grafloria/element vue
```

## 1. Render a flow

In Vue, bind typed initial arrays to [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow) with `:default-nodes` and `:default-edges`; for the shared flow and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) overview, see the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start). Give the flow's parent a height because the canvas fills that parent.

Create `src/App.vue`:

```vue
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/vue';

const nodes: NodeSpec[] = [
  {
    id: 'ingest',
    position: { x: 60, y: 80 },
    size: { width: 180, height: 80 },
    data: { label: 'Ingest' },
  },
  {
    id: 'publish',
    position: { x: 380, y: 80 },
    size: { width: 180, height: 80 },
    data: { label: 'Publish' },
  },
];

const edges: EdgeSpec[] = [
  { id: 'ingest-to-publish', source: 'ingest', target: 'publish' },
];
</script>

<template>
  <div style="height: 480px">
    <GrafloriaFlow
      :default-nodes="nodes"
      :default-edges="edges"
      :plugins="true"
    />
  </div>
</template>
```

The mounted canvas shows Ingest connected to Publish, with the minimap, zoom/fit controls, and background grid enabled by `plugins`. For application-owned state, bind `v-model:nodes` and `v-model:edges` instead of using the `default…` props.

## 2. Reach the instance from a sibling

Place the sibling panel under [`GrafloriaProvider`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaprovider), and call [`useGrafloria`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#usegrafloria), [`useSelection`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#useselection), [`useViewport`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#useviewport), and [`useOnSelectionChange`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#useonselectionchange) in its Vue setup scope; the callback subscription ends with that scope. For the shared sibling-instance pattern, see the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start).

Create `src/App.vue` with a sibling inspector component declared in the same file. The child component calls the composables from its own setup scope, under the provider:

```vue
<script setup lang="ts">
import { defineComponent, h, ref } from 'vue';
import { GrafloriaFlow, GrafloriaProvider } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/vue';
import {
  useGrafloria,
  useOnSelectionChange,
  useSelection,
  useViewport,
} from '@grafloria/vue';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Ingest' } },
  { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, data: { label: 'Publish' } },
];

const edges: EdgeSpec[] = [
  { id: 'ingest-to-publish', source: 'ingest', target: 'publish' },
];

const InspectorPanel = defineComponent({
  setup() {
    const diagram = useGrafloria();
    const selection = useSelection();
    const viewport = useViewport();
    const latestChange = ref('No selection changes yet');

    useOnSelectionChange((change) => {
      latestChange.value = `${change.nodes.length} nodes, ${change.edges.length} edges`;
    });

    return () =>
      h('aside', { style: 'width: 220px; padding: 16px' }, [
        h('p', `${selection.value.nodes.length} nodes selected`),
        h('p', `Zoom: ${viewport.value.zoom.toFixed(2)}`),
        h('p', `Latest change: ${latestChange.value}`),
        h(
          'button',
          { type: 'button', onClick: () => diagram.value?.fitView() },
          'Fit diagram',
        ),
      ]);
  },
});
</script>

<template>
  <GrafloriaProvider>
    <div style="display: flex; height: 480px">
      <div style="flex: 1; min-width: 0">
        <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" />
      </div>
      <InspectorPanel />
    </div>
  </GrafloriaProvider>
</template>
```

## 3. Render a diagram spec

Use [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriadiagram) when you have a diagram spec instead of flow props. Its `spec` accepts a diagram spec object or a JSON string; this example uses a JSON string with nodes and edges.

Create `src/SpecDiagram.vue`:

```vue
<script setup lang="ts">
import { GrafloriaDiagram } from '@grafloria/vue';

const spec = JSON.stringify({
  nodes: [
    {
      id: 'draft',
      position: { x: 70, y: 90 },
      size: { width: 170, height: 70 },
      data: { label: 'Draft' },
    },
    {
      id: 'review',
      position: { x: 340, y: 90 },
      size: { width: 170, height: 70 },
      data: { label: 'Review' },
    },
  ],
  edges: [{ id: 'draft-to-review', source: 'draft', target: 'review' }],
});
</script>

<template>
  <div style="height: 400px">
    <GrafloriaDiagram :spec="spec" />
  </div>
</template>
```

The component mounts a diagram with Draft connected to Review. Changing the spec's value replaces the mounted diagram; an equal value does not trigger a replacement.

## 4. Add a comment panel

In Vue, capture the store in a nullable `shallowRef` from the flow's `@init` handler, then use `v-if` to mount [`GrafloriaCommentPanel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriacommentpanel) only when the store exists. For the shared flow comments and [`CommentStore`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-comments-commentstore#commentstore) pattern, see the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start).

Create `src/CommentsExample.vue`:

```vue
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaCommentPanel, GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/vue';
import type { CommentStore } from '@grafloria/engine';

const store = shallowRef<CommentStore | null>(null);

const nodes: NodeSpec[] = [
  { id: 'design', position: { x: 40, y: 100 }, size: { width: 150, height: 66 }, data: { label: 'Design' } },
  { id: 'review', position: { x: 260, y: 100 }, size: { width: 150, height: 66 }, data: { label: 'Review' } },
  { id: 'ship', position: { x: 480, y: 100 }, size: { width: 150, height: 66 }, data: { label: 'Ship' } },
];

const edges: EdgeSpec[] = [
  { id: 'design-to-review', source: 'design', target: 'review' },
  { id: 'review-to-ship', source: 'review', target: 'ship' },
];

function onInit(instance: DiagramInstance): void {
  const comments = instance.getCommentStore();
  if (!comments) return;

  const threadId = comments.createThread(
    { kind: 'node', id: 'review' },
    'Can we tighten the review checklist?',
  );
  comments.reply(threadId, 'I will update it before handoff.');
  store.value = comments;
}
</script>

<template>
  <div style="display: flex; height: 400px">
    <div style="flex: 1; min-width: 0">
      <GrafloriaFlow
        :default-nodes="nodes"
        :default-edges="edges"
        :comments="true"
        @init="onInit"
      />
    </div>
    <aside v-if="store" style="width: 300px; overflow: auto">
      <GrafloriaCommentPanel :store="store" />
    </aside>
  </div>
</template>
```

The initial view contains the Design → Review → Ship flow and a comment thread attached to Review. `getCommentStore()` returns `null` when comments are not enabled, so the panel renders only after the enabled flow supplies its store.

## What you have

You can mount a typed flow, read live instance state from a sibling component, render a JSON diagram spec, and attach the comments UI to a flow's comment store.

## Where to go next

- [State and data flow in Vue](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow) explains controlled and uncontrolled flow data and saving diagrams.
- [Lay out diagrams automatically](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams) covers layout choices.
- See the [live drag-and-undo demo](https://grafloria.com/demos-vue/#/interaction/drag-undo) and [live comments demo](https://grafloria.com/demos-vue/#/collab/comments).

<!-- source: angular-quick-start.md -->

# Angular quick start

Mount a working diagram in Angular, then choose the right host and integration components for diagrams, kits, toolbars, and property editing.

The same headless model drives every framework binding; Angular components provide the Angular-shaped way to mount and work with it.

## Prerequisites

Use Angular 18.1 through 22. The Angular package's peer dependencies include Angular common, core, forms, and platform-browser, Grafloria engine and renderer, RxJS, and Grafloria element.

Install the Angular binding and its peer packages in your Angular project:

```bash
npm install @grafloria/angular @angular/common @angular/core @angular/forms @angular/platform-browser @grafloria/engine @grafloria/renderer rxjs @grafloria/element
```

## 1. Mount a canvas

Use [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) for a flow editor backed by node and edge data. Its `nodes` and `edges` model bindings round-trip edits to the arrays. [`GrafloriaNodeDefDirective`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-core#graflorianodedefdirective) marks a template for nodes of a matching type. The sample includes real data, gives the canvas a height, and turns on the shipped minimap, zoom and fit controls, and background grid.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaNodeDefDirective } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaNodeDefDirective],
  template: `
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      [plugins]="true"
      style="display: block; height: 520px">
      <ng-template grafloriaNode="job" let-data="data">
        <article class="job-card">
          <strong>{{ data['title'] }}</strong>
          <span>{{ data['owner'] }}</span>
        </article>
      </ng-template>
    </grafloria-diagram-canvas>
  `,
  styles: [
    `.job-card {
      box-sizing: border-box;
      height: 100%;
      padding: 12px;
      border: 1px solid #94a3b8;
      border-radius: 8px;
      background: white;
      display: grid;
      align-content: center;
      gap: 6px;
    }`,
  ],
})
export class AppComponent {
  nodes: NodeSpec[] = [
    {
      id: 'extract',
      type: 'job',
      position: { x: 60, y: 90 },
      size: { width: 180, height: 84 },
      data: { title: 'Extract', owner: 'Data team' },
    },
    {
      id: 'publish',
      type: 'job',
      position: { x: 340, y: 90 },
      size: { width: 180, height: 84 },
      data: { title: 'Publish', owner: 'Platform team' },
    },
  ];

  edges: EdgeSpec[] = [
    { id: 'extract-publish', source: 'extract', target: 'publish' },
  ];
}
```

![The mounted canvas shows its graph and plugin controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4f8855216a97fbe6bf06adb21cf630d2.png)

The canvas shows two Angular-rendered job cards connected by an edge, plus its plugin controls and grid. A matching `grafloriaNode` template is the integration: the canvas routes nodes of that type through Angular's template rendering without a separate node registry.

## 2. Choose a kit host for a data-first diagram

Use [`GrafloriaDiagramComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes#grafloriadiagramcomponent) when a kit builds a complete diagram from a spec. Here `erDiagram` supplies the entity and relationship data, and `<grafloria-diagram>` mounts the resulting kit spec. The host also accepts UML and other kit specs through the same `spec` input.

```ts
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { erDiagram } from '@grafloria/element';

@Component({
  selector: 'app-entity-diagram',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: `
    <grafloria-diagram [spec]="spec" style="display: block; height: 520px" />
  `,
})
export class EntityDiagramComponent {
  spec = erDiagram({
    entities: [
      {
        id: 'CUSTOMER',
        name: 'Customer',
        position: { x: 60, y: 80 },
        columns: [
          { name: 'id', type: 'int', pk: true },
          { name: 'name', type: 'varchar' },
        ],
      },
      {
        id: 'ORDER',
        name: 'Order',
        position: { x: 360, y: 80 },
        columns: [
          { name: 'id', type: 'int', pk: true },
          { name: 'customer_id', type: 'int', fk: true },
        ],
      },
    ],
    relationships: [{ from: 'CUSTOMER', to: 'ORDER', label: 'places' }],
  });
}
```

![The kit host displays the entity-relationship diagram.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/b64d6e8109a966411112d436594df578.png)

The mounted kit renders two entity tables joined by a relationship. For a dashboard kit, [`GrafloriaDashboardComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-grafloriadashboardcomponent#grafloriadashboardcomponent) is the data-first host; its widget templates use [`GrafloriaWidgetDefDirective`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes#grafloriawidgetdefdirective).

## 3. Find the Angular integrations

These components connect the canvas to custom Angular UI or add editing controls around it. The canvas already mounts its link toolbar when a link is hovered or selected; use the component directly when you need to place that toolbar in your own host.

| Need | Component | What it provides |
|---|---|---|
| Render a node with Angular markup | `GrafloriaNodeDefDirective` | An `ng-template[grafloriaNode]` matched by node type. Its context exposes the live node and its `data` payload. |
| Make an HTML node element a connection endpoint | [`GrafloriaHandleDirective`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-core#grafloriahandledirective) | The `grafloriaHandle` attribute marks a source or target inside an HTML node; the parent node element needs a `data-node-id`. |
| Add contextual actions for a node | [`NodeToolbarComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-nodetoolbarcomponent#nodetoolbarcomponent) | A floating node toolbar positioned relative to the supplied node. Bind its node and engine. |
| Edit selected node properties | [`PropertyPanelComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-propertypanelcomponent#propertypanelcomponent) | A schema-driven property editor. Set its `selectedNodes` property on the component instance; the panel needs a property schema for the node type. Its default update mode applies valid changes immediately; deferred mode provides Save and Cancel actions. |

These are integrations around the canvas, not alternate diagram hosts. The canvas owns drawing and interaction; custom-node templates add Angular-rendered node content, while toolbars and the property panel provide companion UI. The following standalone examples show each companion component in a mounted Angular view.

### Add a node toolbar

Pass the selected live node and the canvas engine to the node toolbar. Set [`NodeToolbarConfig`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interfaces#nodetoolbarconfig) to keep the toolbar visible without requiring a selection. This sample uses a [`ToolbarAction`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interfaces#toolbaraction) to place an Inspect action beside the first node; selecting it writes that node's ID to the browser console.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent, NodeToolbarComponent } from '@grafloria/angular';
import type { NodeToolbarConfig, ToolbarAction } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-node-actions',
  standalone: true,
  imports: [DiagramCanvasComponent, NodeToolbarComponent],
  template: `
    <div #host style="position: relative; display: block; height: 360px">
      <grafloria-diagram-canvas
        #canvas
        [(nodes)]="nodes"
        [(edges)]="edges"
        style="display: block; height: 100%" />
      @if (canvas.activeEngine(); as engine) {
        @if (engine.getDiagram()?.getNode('job'); as node) {
          <grafloria-node-toolbar
            [node]="node"
            [engine]="engine"
            [canvasElement]="host"
            [viewport]="canvas.viewport()"
            [zoom]="canvas.zoom()"
            [config]="toolbarConfig"
            [actions]="actions" />
        }
      }
    </div>
  `,
})
export class NodeActionsComponent {
  nodes: NodeSpec[] = [
    { id: 'job', type: 'task', position: { x: 100, y: 110 }, size: { width: 180, height: 80 }, label: 'Review' },
    { id: 'next', position: { x: 360, y: 110 }, size: { width: 160, height: 72 }, label: 'Publish' },
  ];
  edges: EdgeSpec[] = [{ id: 'job-next', source: 'job', target: 'next' }];
  toolbarConfig: NodeToolbarConfig = { behavior: { hideOnMultiSelect: false } };
  actions: ToolbarAction[] = [
    { id: 'inspect', label: 'Inspect', onClick: node => console.info(node.id) },
  ];
}
```

![The Inspect toolbar is positioned beside the canvas node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9564d1e8d1f100054516841b1161cb13.png)

### Add a link toolbar

The canvas normally supplies link actions itself. Mount [`LinkToolbarComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-linktoolbarcomponent#linktoolbarcomponent) directly when you want a separate toolbar host; this example attaches an Inspect action described by [`LinkToolbarAction`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interfaces#linktoolbaraction) to the live link in a mounted canvas.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent, LinkToolbarComponent } from '@grafloria/angular';
import type { LinkToolbarAction } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-link-actions',
  standalone: true,
  imports: [DiagramCanvasComponent, LinkToolbarComponent],
  template: `
    <div #host style="position: relative; display: block; height: 360px">
      <grafloria-diagram-canvas
        #canvas
        [(nodes)]="nodes"
        [(edges)]="edges"
        style="display: block; height: 100%" />
      @if (canvas.activeEngine(); as engine) {
        @if (engine.getDiagram()?.getLink('flow'); as link) {
          <grafloria-link-toolbar
            [link]="link"
            [engine]="engine"
            [canvasElement]="host"
            [viewport]="canvas.viewport()"
            [zoom]="canvas.zoom()"
            [actions]="actions" />
        }
      }
    </div>
  `,
})
export class LinkActionsComponent {
  nodes: NodeSpec[] = [
    { id: 'start', position: { x: 70, y: 120 }, size: { width: 150, height: 70 }, label: 'Start' },
    { id: 'finish', position: { x: 350, y: 120 }, size: { width: 150, height: 70 }, label: 'Finish' },
  ];
  edges: EdgeSpec[] = [{ id: 'flow', source: 'start', target: 'finish' }];
  actions: LinkToolbarAction[] = [
    { id: 'inspect', label: 'Inspect link', onClick: context => console.info(context.link.id) },
  ];
}
```

![The Inspect link toolbar is attached to the rendered edge.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/416c74784a5214b786473dcc7d393caa.png)

The live link supplies the toolbar's position and its action context. The Inspect button logs the connected link's ID when clicked.

### Add a property panel

The property panel needs a schema for the selected node type. Register one with [`PropertyPanelService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-propertypanelservice#propertypanelservice) before displaying the panel; assign a [`PropertyDiagramNode`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services#propertydiagramnode) to the component instance's `selectedNodes` property and define its fields with [`PropertySchema`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-propertyschema#propertyschema). Its string editor changes the selected node's data immediately.

```ts
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { PropertyPanelComponent, PropertyPanelService } from '@grafloria/angular';
import type { PropertyDiagramNode } from '@grafloria/angular';
import type { PropertySchema } from '@grafloria/renderer';

@Component({
  selector: 'app-properties',
  standalone: true,
  imports: [PropertyPanelComponent],
  template: `
    <diagram-property-panel #panel
      [showHeader]="true"
      (propertyChanged)="onPropertyChanged($event.property, $event.value)" />
    <p>Current title: {{ selectedNodes.data['title'] }}</p>
  `,
})
export class PropertiesComponent implements AfterViewInit {
  panel = viewChild.required(PropertyPanelComponent);

  selectedNodes: PropertyDiagramNode = {
    id: 'job',
    type: 'quick-start-task',
    label: 'Review',
    data: { title: 'Review' },
  };

  constructor(propertyPanel: PropertyPanelService) {
    if (!propertyPanel.getSchema('quick-start-task')) {
      const schema: PropertySchema = {
        properties: [{ key: 'title', label: 'Title', editor: 'string' }],
      };
      propertyPanel.registerSchema('quick-start-task', schema);
    }
  }

  ngAfterViewInit(): void {
    this.panel().selectedNodes = this.selectedNodes;
  }

  onPropertyChanged(property: string, value: unknown): void {
    console.info(`${property}: ${String(value)}`);
  }
}
```

![The property panel displays the Title editor for the selected node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f0b6de9bbb9f4d02d96379303fa31d96.png)

The panel renders a Title editor for the selected node. Editing the field changes its `data.title` value, which the line below the panel reflects.

### Add an interaction settings panel

[`InteractionConfigPanelComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interactionconfigpanelcomponent#interactionconfigpanelcomponent) needs the live canvas engine. Guard the panel with Angular's `@if` so it mounts after the canvas provides that engine.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent, InteractionConfigPanelComponent } from '@grafloria/angular';
import type { NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-interaction-settings',
  standalone: true,
  imports: [DiagramCanvasComponent, InteractionConfigPanelComponent],
  template: `
    <grafloria-diagram-canvas #canvas [(nodes)]="nodes" style="display: block; height: 320px" />
    @if (canvas.activeEngine(); as engine) {
      <grafloria-interaction-config-panel
        [engine]="engine"
        [expanded]="true"
        (configChanged)="onConfigChanged($event)" />
    }
  `,
})
export class InteractionSettingsComponent {
  nodes: NodeSpec[] = [
    { id: 'task', position: { x: 80, y: 90 }, size: { width: 160, height: 72 }, label: 'Task' },
  ];

  onConfigChanged(config: object): void {
    console.info('Interaction settings changed', config);
  }
}
```

![The expanded interaction settings panel appears with the task canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7ec7324527d593d9d6ea80ef2e9b8a3e.png)

The expanded settings panel reads and updates interaction configuration on the same engine that drives the visible node.

### Show comment threads

[`GrafloriaCommentPanelComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes#grafloriacommentpanelcomponent) uses the comment store created by the canvas. This sample mounts the conversation panel beside a canvas with comments enabled.

```ts
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaCommentPanelComponent } from '@grafloria/angular';
import type { NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-comments',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaCommentPanelComponent],
  template: `
    <grafloria-diagram-canvas
      #canvas
      [nodes]="nodes"
      [comments]="true"
      style="display: block; height: 320px" />
    @if (canvas.getCommentStore(); as store) {
      <grafloria-comment-panel [store]="store" />
    }
  `,
})
export class CommentsComponent implements AfterViewInit {
  canvas = viewChild.required(DiagramCanvasComponent);

  nodes: NodeSpec[] = [
    { id: 'note', position: { x: 80, y: 90 }, size: { width: 160, height: 72 }, label: 'Discuss this step' },
  ];

  ngAfterViewInit(): void {
    this.canvas().getCommentStore()?.createThread(
      { kind: 'node', id: 'note' },
      'Should this step include an approval?'
    );
  }
}
```

![The comment panel lists the seeded thread beside the canvas node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/304a75914d88098827db6af459ef00f6.png)

The comment panel receives the canvas's live store and shows the seeded thread anchored to the node.

### Identify the lower-level canvas package

[`CanvasNgCanvasNgComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-canvas-ng#canvasngcanvasngcomponent) belongs to the separate `@grafloria/canvas-ng` package. It has no inputs or outputs and is not the diagram canvas above; this sample mounts that package's component as-is.

Install that optional package before using this sample:

```bash
npm install @grafloria/canvas-ng
```

```ts
import { Component } from '@angular/core';
import { CanvasNgCanvasNgComponent } from '@grafloria/canvas-ng';

@Component({
  selector: 'app-canvas-ng',
  standalone: true,
  imports: [CanvasNgCanvasNgComponent],
  template: `<lib-canvas-ng-canvas-ng style="display: block; min-height: 80px" />`,
})
export class CanvasNgExampleComponent {}
```

![The lower-level component displays its package placeholder text.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/77e55f992b60d4946070386c0692f80e.png)

This component renders its own package placeholder; use `DiagramCanvasComponent` to mount a Grafloria diagram.

## What you have

You can mount a controlled canvas with typed node and edge data, render custom nodes as Angular templates, and choose the generic kit host when a kit provides the diagram spec. The component map shows which separate integrations add node connections, contextual actions, and property editing.

## Where to go next

- [Create custom nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/create-custom-nodes) to build out template-rendered nodes.
- [Build ER and UML diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-er-and-uml-diagrams) for the data-first kit hosts.
- [Build dashboards](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-dashboards) for dashboard views and widget templates.
- Explore the [Angular tutorial](https://grafloria.com/learn/angular/) and the [Angular demo gallery](https://grafloria.com/demos-angular/) for live examples.

<!-- source: qwik-quick-start.md -->

# Qwik quick start

The Qwik binding combines a flow component with sibling hooks, a generic diagram host, and a comment panel.

One headless model drives every framework binding; the Qwik components expose that model in Qwik's resumable app structure.

## Prerequisites

Use Qwik 1.x; [@grafloria/qwik](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik) 0.10.6 also declares `@grafloria/element` `^0.4.3` as a peer. For the shared engine and renderer peer ranges, see [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start).

Install the binding and its peer packages:

```bash
npm install @grafloria/qwik @grafloria/engine @grafloria/renderer @builder.io/qwik @grafloria/element
```

## 1. Render a flow

For what the flow, node and edge specs, and default-data props do, see [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start). Here, [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow) uses `fitView` to frame the mounted flow.

## 2. Connect a sibling toolbar

Wrap the flow and its toolbar in [`GrafloriaProvider`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaprovider). The sibling calls [`useGrafloria`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#usegrafloria) for the live instance, and [`useSelection`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#useselection) and [`useViewport`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#useviewport) expose selection and camera state as reactive signals. Use [`useOnSelectionChange$`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#useonselectionchange) when a QRL handler needs each selection update; it receives a [`SelectionChange`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#selectionchange). The instance signal is `undefined` until the flow mounts.

This route combines the flow, sibling toolbar, comment panel, and generic spec host. The toolbar reads selection and viewport state; selecting a node also logs the selected node and edge counts. The comment panel waits for the flow's live instance, then receives its non-serializable comment store.

```tsx
import {
  $,
  component$,
  noSerialize,
  useSignal,
  useVisibleTask$,
  type NoSerialize,
} from '@builder.io/qwik';
import type { CommentStore } from '@grafloria/engine';
import {
  GrafloriaCommentPanel,
  GrafloriaDiagram,
  GrafloriaFlow,
  GrafloriaProvider,
  useGrafloria,
  useOnSelectionChange$,
  useSelection,
  useViewport,
  type EdgeSpec,
  type NodeSpec,
  type SelectionChange,
} from '@grafloria/qwik';

const nodes: NodeSpec[] = [
  { id: 'plan', position: { x: 60, y: 60 }, size: { width: 160, height: 64 }, label: 'Plan' },
  { id: 'build', position: { x: 300, y: 60 }, size: { width: 160, height: 64 }, label: 'Build' },
  { id: 'test', position: { x: 540, y: 60 }, size: { width: 160, height: 64 }, label: 'Test' },
];

const edges: EdgeSpec[] = [
  { id: 'e1', source: 'plan', target: 'build', sourceHandle: 'right', targetHandle: 'left' },
  { id: 'e2', source: 'build', target: 'test', sourceHandle: 'right', targetHandle: 'left' },
];

const spec = { nodes, edges };

const Toolbar = component$(() => {
  const instance = useGrafloria();
  const selection = useSelection();
  const viewport = useViewport();

  useOnSelectionChange$($((change: SelectionChange) => {
    console.info('Selection changed', change.nodes.length, change.edges.length);
  }));

  return (
    <aside style={{ gridColumn: '1 / -1' }}>
      <span>Flow {instance.value ? 'ready' : 'waiting'}</span>
      <span>Zoom {viewport.value.zoom.toFixed(2)}</span>
      <span>
        Selected {selection.value.nodes.length} node(s), {selection.value.edges.length} edge(s)
      </span>
    </aside>
  );
});

const CommentPanelHost = component$(() => {
  const instance = useGrafloria();
  const store = useSignal<NoSerialize<CommentStore>>();

  useVisibleTask$(({ track }) => {
    const diagram = track(() => instance.value);
    if (!diagram) return;
    const comments = diagram.getCommentStore();
    if (!comments) return;
    comments.createThread({ kind: 'node', id: 'plan' }, 'Confirm the handoff criteria.');
    store.value = noSerialize(comments);
  });

  return store.value ? <GrafloriaCommentPanel store={store.value} /> : null;
});

export default component$(() => (
  <GrafloriaProvider>
    <div style={{ display: 'grid', gridTemplateColumns: 'minmax(0, 2fr) minmax(260px, 1fr)', gridTemplateRows: 'auto 400px' }}>
      <Toolbar />
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        comments
        fitView
        style={{ height: '400px' }}
      />
      <CommentPanelHost />
    </div>
    <GrafloriaDiagram spec={spec} style={{ height: '400px' }} />
  </GrafloriaProvider>
));
```

## 3. Add an anchored comment panel

For the comment-store setup, see [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start). In Qwik, [`GrafloriaCommentPanel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriacommentpanel) appears after `useVisibleTask$` reads the live instance and keeps its store in a signal wrapped with `noSerialize()`.

## 4. Mount a spec with the generic diagram component

Use [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriadiagram) when your input is a diagram spec rather than the flow component's node and edge props. It accepts an object spec.

The object spec renders as a diagram in the component's container. A changed spec or options value replaces the mounted diagram and calls `onReady$` again; an equal spec value does not trigger a replacement.

## Where to go next

See the [live Qwik demos](https://grafloria.com/demos-qwik/) to run the binding's examples, including the provider-and-hooks and generic spec examples. Continue with [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the shared model and instance concepts, or [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows) to make diagrams interactive for end users.

<!-- source: how-grafloria-works.md -->

# How Grafloria works

Grafloria is one headless diagram model with framework bindings around it: the binding mounts the diagram, the instance connects its rendered canvas to its data and engine, and the renderer turns model intent into pixels.

## One headless model, every framework

Use the binding that fits your application. Each example mounts the same two-node flow; drag a node or connect nodes in the resulting canvas, regardless of framework.

### React

For a runnable React flow and its initial-data props, see the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start). The framework component mounts the shared model rather than a React-specific diagram model.

### Vue

For a runnable Vue flow and its initial-data props, see the [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start). Vue also mounts the shared model; the binding changes how you express the component, not the diagram's underlying model.

### Qwik

Qwik renders the component on the server and resumes it in the browser; follow the [Qwik quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/qwik-quick-start) for a runnable component setup.

### Angular

Angular uses [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) with two-way node and edge bindings. The canvas displays the same flow, and user edits update the bound arrays.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-root',
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      style="display: block; height: 400px" />
  `,
})
export class AppComponent {
  nodes: NodeSpec[] = [
    { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, label: 'Ingest' },
    { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, label: 'Publish' },
  ];
  edges: EdgeSpec[] = [{ id: 'flow', source: 'ingest', target: 'publish' }];
}
```

Each binding translates its convenient spec inputs into the same live model. The model is headless: it describes the diagram without depending on React, Vue, Qwik, Angular, or a DOM. That is why the same data and engine behavior make sense in each binding.

## Two layers, one truth

The diagram owns data; the engine owns behavior. A [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) is the renderer-level facade between them and the canvas.

```mermaid
flowchart LR
  Specs["Framework specs"] --> Model["DiagramModel: nodes, links, groups, viewport"]
  Engine["DiagramEngine: commands, history, layout, validation"] --> Model
  Model --> Instance["DiagramInstance: canvas and model facade"]
  Instance --> Pixels["Renderer: visible diagram"]
```

For plain JavaScript, [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) mounts a spec into a real, sized host and returns that same kind of instance. This complete browser example renders two boxes, fits them into view, and reads the live model's document:

```ts
import { render } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 60, y: 80 }, size: { width: 180, height: 80 }, label: 'Ingest' },
  { id: 'publish', position: { x: 380, y: 80 }, size: { width: 180, height: 80 }, label: 'Publish' },
];
const edges: EdgeSpec[] = [{ id: 'flow', source: 'ingest', target: 'publish' }];

const container = document.createElement('div');
container.style.height = '400px';
document.body.append(container);

const instance = render({ nodes, edges }, container);
instance.fitView();

const diagram = instance.getModel();
const engine = instance.getEngine();
const activeDiagram = engine.getDiagram();
if (activeDiagram === null) {
  throw new Error('The engine has no active diagram.');
}
const savedDocument = activeDiagram.serialize();
const savedJson = JSON.stringify(savedDocument);
```

The canvas shows the two labeled boxes and their edge. `getModel()` returns the live [`DiagramModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-diagrammodel#diagrammodel), where diagram data lives; `getEngine()` returns the [`DiagramEngine`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-engine#diagramengine), where behavior lives. `serialize()` produces the document object, and `JSON.stringify()` turns it into JSON text. Use the instance for canvas-facing work, the model for data queries, and the engine for behavior.

## The document is the API

The model serializes the diagram as one JSON document: it includes the schema version, diagram metadata and name, nodes, links, groups, and viewport. The same document shape is used for persistence and restoration, so data does not need a separate format for each framework. `savedDocument` in the example above is that document object; `savedJson` is its JSON representation.

## User edits are commands on one history stack

When a user drags, connects, deletes, or groups an item in the mounted canvas, Grafloria turns the gesture into a command on the engine's shared history stack. Try dragging either node in one of the mounted examples and pressing Ctrl+Z (or ⌘Z on macOS): the move is undone. The framework binding reflects the changed model back into application state. By contrast, adding initial specs or loading a document is setup, not a user edit to undo.

See [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) for commands and programmatic edits.

## The model stores intent, not pixels

Node specs provide identity, label, and geometry; an edge spec identifies its source and target. The renderer decides how to draw that intent. For example, an edge without pinned handles can use the side that faces its partner, so the connection adapts as nodes move instead of preserving a pixel path.

In the examples, `position` locates each node and `source`/`target` describe the edge. Grafloria computes and draws the connection on the canvas; the spec does not contain the rendered pixels. See [Diagram intent and rendering](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/diagram-intent-and-rendering) for geometry and routing.

## Where next

- [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document) — nodes, links, groups, and serialized data.
- [Instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow) — how specs and model changes move through the instance.
- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) — how gestures and programmatic edits enter history.
- [Diagram intent and rendering](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/diagram-intent-and-rendering) — how the renderer turns model geometry and connections into a visible diagram.
- [Live interaction demo](https://grafloria.com/demos/#interaction) — drag a node and try undo.

<!-- source: graph-model-and-document.md -->

# The graph model and document

A diagram is a model of nodes, ports, links, and groups; save that model as a document, then reconstruct it when you load the document.

## One diagram, two layers

The [`DiagramModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-diagrammodel#diagrammodel) holds diagram data: nodes, links, groups, and viewport state. The engine owns behavior such as commands, history, validation, and layout. Framework bindings accept convenient specs and turn them into live models; a rendered instance gives you access to the model behind its canvas.

The [`NodeModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-nodemodel#nodemodel) represents an item with an identity, type, geometry, data, and ports. A node starts with four bidirectional ports, one on each side. Add a [`PortModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-portmodel#portmodel) when a connection needs a specific direction, side, or other port-level configuration. Ports describe where a connection may attach and what constraints apply; they are not separate diagram nodes.

A [`LinkModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-linkmodel#linkmodel) connects source and target ports. Its path type records the geometry intent; the renderer draws and routes the line. A [`GroupModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-groupmodel#groupmodel) collects member entities into a container and can itself be nested in another group.

```mermaid
flowchart LR
  Diagram["DiagramModel"] --> Nodes["NodeModel"]
  Nodes --> Ports["PortModel"]
  Links["LinkModel"] --> Ports
  Diagram --> Links
  Diagram --> Groups["GroupModel"]
  Groups --> Nodes
```

## Mount a diagram and round-trip its document

Use [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) to mount the data spec and get a live instance. Read the model from that instance, serialize it with [`DiagramSerializer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization#diagramserializer), then pass the saved JSON to [`fromDocument`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#fromdocument) to reconstruct the model.

This browser example renders an order flow, serializes it, and reconstructs its model. Give the canvas a height so it has room to draw.

```html
<div id="original" style="height: 360px"></div>
```

```ts
import { DiagramSerializer } from '@grafloria/engine';
import { fromDocument, render } from '@grafloria/element';

const originalHost = document.getElementById('original')!;
originalHost.style.height = '360px';

const original = render(
  {
    nodes: [
      {
        id: 'intake',
        type: 'rect',
        position: { x: 40, y: 70 },
        size: { width: 130, height: 56 },
        label: 'Intake',
        data: { owner: 'Operations' },
      },
      {
        id: 'review',
        type: 'rect',
        position: { x: 250, y: 70 },
        size: { width: 130, height: 56 },
        label: 'Review',
        data: { owner: 'Finance' },
      },
    ],
    edges: [{ id: 'intake-review', source: 'intake', target: 'review' }],
    groups: [
      {
        id: 'approval',
        label: 'Approval',
        children: ['intake', 'review'],
        bounds: { x: 20, y: 30, width: 380, height: 150 },
      },
    ],
  },
  originalHost
);

const diagramModel = original.getModel();
const serializer = new DiagramSerializer();
const savedDocument = JSON.stringify(serializer.serializeEnvelope(diagramModel));
const restoredModel = fromDocument(savedDocument).model;
console.log('Restored node IDs:', restoredModel.getNodes().map((node) => node.id));
```

The canvas shows two labelled nodes joined by an edge inside the Approval group. The saved envelope contains the diagram model data, including nodes, links, groups, and viewport. `fromDocument()` accepts the JSON string and returns a loaded spec containing the restored model; the console lists its node IDs.

## What the document contains

Serialization gives persistence one diagram-level format rather than separate node, edge, and group files. The flat model serialization includes a schema version, identity and metadata, the diagram name, nodes, links, groups, and viewport; each node entry includes its serialized ports. Strokes and comments are included when present. `serializeEnvelope()` wraps the diagram data with portable document metadata. `deserialize()` accepts the envelope as well as the flat serializer form, while `fromDocument()` turns a saved document into a renderable spec.

The document preserves model data and connection intent, not functions or an application's runtime. A custom-node painter is code and must be supplied again when loading a diagram that needs it. The renderer remains responsible for drawing and routing from the restored model.

## Where to go next

- [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports) for port direction, positioning, and connection options.
- [Route and edit edges](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/route-and-edit-edges) for link geometry and routing.
- [Group nodes and containers](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/group-nodes-and-containers) for group membership and nesting.
- [Import and round-trip diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/import-and-round-trip-diagrams) for persistence and text formats.

<!-- source: instance-and-data-flow.md -->

# The instance and data flow

The live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance) connects your diagram specs to the rendered canvas: it reconciles application data into live models, coordinates model changes with the renderer, and exposes the engine for diagram behavior.

## One model, three responsibilities

The framework bindings are thin wrappers around one headless model. They accept [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec) data, create a live instance, and reflect model changes through their framework's data contract. The instance is the facade between the canvas, the data model, and the engine:

```mermaid
flowchart LR
  A["Application specs"] -->|"props or setNodes() / setEdges()"| I["DiagramInstance"]
  I -->|reconcile| M["DiagramModel: live nodes, links, groups"]
  M -->|invalidations and scheduled paint| R["Renderer: SVG and HTML layers"]
  M -->|model events| I
  I -->|callbacks, events, or two-way updates| A
  I -->|"getEngine()"| E["DiagramEngine: behavior"]
```

Think of the layers this way: specs are convenient application input; the live model is the diagram's data; the engine owns behavior such as commands and validation; and the renderer turns model intent into pixels. The instance joins those layers so the same model drives each framework binding.

## Mounting hands you the live instance

In browser JavaScript, [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) mounts a data spec and returns the instance for that canvas. This runnable example starts with one node. Clicking **Add node** reconciles a second node into the mounted diagram; the instance event listener reports the live model's node count.

```ts
import { render } from '@grafloria/element';
import type { NodeSpec } from '@grafloria/renderer';

const host = document.createElement('div');
host.style.cssText = 'width: 100%; height: 400px';
document.body.append(host);

const button = document.createElement('button');
button.textContent = 'Add node';
document.body.prepend(button);

const specs: NodeSpec[] = [
  { id: 'first', position: { x: 40, y: 60 }, label: 'First' },
];
let currentSpecs = specs;
const instance = render({ nodes: specs, edges: [] }, host);

instance.on('nodes:change', ({ nodes }) => {
  console.log(`Live nodes: ${nodes.length}`);
});

button.addEventListener('click', () => {
  const next: NodeSpec = {
    id: `node-${currentSpecs.length + 1}`,
    position: { x: 220, y: 60 },
    label: 'Second',
  };
  currentSpecs = [...currentSpecs, next];
  instance.setNodes(currentSpecs);
});
```

The canvas displays both labeled nodes after the click. `setNodes()` returns `void`; the event listener receives the updated live node models when the model's membership changes. Give the host a resolved height so the canvas has space to draw.

## Use the same flow through a framework

The wrappers mount that same model through their own component conventions. Their instance callback gives you the same `DiagramInstance`, while controlled inputs let application state own the specs. In the React, Vue, and Angular examples below, the **Add node** button shows the inbound update path.

### React

[`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow) accepts `defaultNodes` for an instance-owned graph. `onInit` captures the instance, and `onNodesChange` receives live node models when membership changes.

```tsx
import { useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance, NodeSpec } from '@grafloria/renderer';

const initialNodes: NodeSpec[] = [
  { id: 'first', position: { x: 40, y: 60 }, label: 'First' },
];

export function ReactFlowExample() {
  const instance = useRef<DiagramInstance | null>(null);
  const specs = useRef<NodeSpec[]>(initialNodes);

  function addNode() {
    const next: NodeSpec = {
      id: `node-${specs.current.length + 1}`,
      position: { x: 220, y: 60 },
      label: 'Second',
    };
    specs.current = [...specs.current, next];
    instance.current?.setNodes(specs.current);
  }

  return (
    <>
      <button onClick={addNode}>Add node</button>
      <div style={{ height: 400 }}>
        <GrafloriaFlow
          defaultNodes={initialNodes}
          onInit={(live) => { instance.current = live; }}
          onNodesChange={(nodes) => console.log(`Live nodes: ${nodes.length}`)}
        />
      </div>
    </>
  );
}
```

The click adds a node to the live model, and `onNodesChange` observes the membership update. In controlled React mode, pass `nodes` with `onNodesChange`; otherwise a later render can reconcile stale application state back into the canvas. See the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start) for the controlled ownership pattern.

### Vue

[`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow) emits `init` with the instance. This example uses the instance to update its live model; Vue's component does not declare an `onNodesChange` callback, so the code subscribes to the instance's `nodes:change` event.

```vue
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, NodeSpec } from '@grafloria/renderer';

const initialNodes: NodeSpec[] = [
  { id: 'first', position: { x: 40, y: 60 }, label: 'First' },
];
const specs = ref<NodeSpec[]>(initialNodes);
const instance = shallowRef<DiagramInstance | null>(null);

function onInit(live: DiagramInstance) {
  instance.value = live;
  live.on('nodes:change', ({ nodes }) => {
    console.log(`Live nodes: ${nodes.length}`);
  });
}

function addNode() {
  const next: NodeSpec = {
      id: 'second',
    position: { x: 220, y: 60 },
    label: 'Second',
  };
  specs.value = [...specs.value, next];
  instance.value?.setNodes(specs.value);
}
</script>

<template>
  <button @click="addNode">Add node</button>
  <div style="height: 400px">
    <GrafloriaFlow :default-nodes="initialNodes" @init="onInit" />
  </div>
</template>
```

The click adds the second node, and the `nodes:change` listener reports the live model's node count. For controlled Vue data, use `v-model:nodes`; the wrapper reconciles that prop into the model and emits updated specs when the controlled nodes change. See the [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start).

### Angular

Angular's [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) follows the same model flow through signal-based two-way bindings. Here the component instance remains behind its Angular component boundary: the host owns a typed spec array, and the binding reconciles it into the rendered diagram.

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-flow-example',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="addNode()">Add node</button>
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class FlowExampleComponent {
  nodes: NodeSpec[] = [
    { id: 'first', position: { x: 40, y: 60 }, label: 'First' },
  ];
  edges: EdgeSpec[] = [];

  addNode(): void {
    this.nodes = [
      ...this.nodes,
      { id: `node-${this.nodes.length + 1}`, position: { x: 220, y: 60 }, label: 'Second' },
    ];
  }
}
```

Clicking **Add node** updates the host array; `[(nodes)]` feeds it into the live model and writes canvas-side node changes back to the host. Angular also exposes `modelChange` for incremental model patches. See the [Angular quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/angular-quick-start).

## Reconciliation preserves the live diagram

`setNodes()` and `setEdges()` reconcile incoming specs rather than rebuilding the diagram. New ids add models, missing ids remove them, and ids that remain update their existing live objects. The renderer, selection, listeners, and mounted plugins stay attached to the same instance; the next scheduled paint reflects the model change.

That identity preservation matters when your app passes a changed array for a graph whose ids remain stable. It also means a same-id spec updates the live model rather than replacing the entire document. When importing a different document that reuses ids and must replace all current state, clear the existing specs before applying the new ones. The reconciliation details and import pattern are covered in [Add nodes from palettes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/add-nodes-from-palettes).

Model change events are not a frame-by-frame drag feed. Structural changes such as adding or removing nodes emit `nodes:change`; moving or editing a node schedules a repaint, while changes from an interaction are reflected at its commit points. The wrappers project data according to their contracts: React's callback receives live models, while Vue's controlled output provides specs. Treat those values as application synchronization, not as a full-document persistence format.

## Choose the layer for the task

Start with the instance for mounted-canvas work: `getModel()` reads live diagram data, `getEngine()` reaches engine behavior, and `setNodes()` / `setEdges()` reconcile input. Use the framework component's controlled binding when application state owns the graph. The instance itself does not provide undo; history lives on the engine. The [DiagramInstance reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance) maps the full surface, while [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) explains the engine's undoable edits.

See the live [React save-and-restore demo](https://grafloria.com/demos-react/#/interaction/save-and-restore), [Vue save-and-restore demo](https://grafloria.com/demos-vue/#/interaction/save-and-restore), and [Angular snapshot-and-restore demo](https://grafloria.com/demos-angular/#/interaction/save-and-restore) to watch model data travel through a mounted canvas.

<!-- source: command-history.md -->

# Command history and edits

An undoable [Command](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-classes-a-r#command) packages a diagram edit so the engine can execute it, undo it, and put it on the shared history stack.

The [DiagramInstance](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) exposes the mounted diagram's model and its engine. The [DiagramModel](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-diagrammodel#diagrammodel) owns the diagram data; the [DiagramEngine](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-engine#diagramengine) owns behavior, including command history. A user gesture goes through the command manager, while initial setup and loading can write to the model directly:

```mermaid
flowchart LR
  G["User gesture or user-directed edit"] --> C["CommandManager.execute(command)"]
  C --> H["Undo history"]
  H --> U["Undo / redo"]
  S["Setup or load"] --> M["DiagramModel operations"]
  M --> V["Diagram data, not an undo step"]
```

## Choose by intent

Use model operations to build or load the diagram: adding nodes directly to the model does not create a history entry. Use a command when your feature edits on the user's behalf, such as applying a toolbar action or suggestion; executing it records an undoable change.

This helper expects the instance from an already mounted diagram. It adds a starting node as setup, then adds a suggested node through the shipped [`AddNodeCommand`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-classes-a-r#addnodecommand). After it completes, the mounted diagram contains both boxes; the setup node is not an undo step, while the suggestion is.

```ts
import { AddNodeCommand, NodeModel } from '@grafloria/engine';
import type { DiagramInstance } from '@grafloria/renderer';

export async function prepareAndSuggest(instance: DiagramInstance): Promise<void> {
  const diagram = instance.getModel();
  const start = new NodeModel({
    id: 'start',
    type: 'basic',
    position: { x: 80, y: 80 },
    size: { width: 160, height: 80 },
  });
  diagram.addNode(start);

  const suggestion = new NodeModel({
    id: 'suggestion',
    type: 'basic',
    position: { x: 300, y: 80 },
    size: { width: 160, height: 80 },
  });
  await instance.getEngine().commandManager.execute(new AddNodeCommand(suggestion));
}
```

The command manager's `execute()` returns a promise, so await it before checking the diagram or updating controls. To undo that edit later, call `undo()` on `instance.getEngine()`; `DiagramInstance` itself has no `undo()` method. The starting node remains because `diagram.addNode()` did not enter history. To combine several related edits into one undo step, use the shipped [`BatchCommand`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-classes-a-r#batchcommand).

## Gestures use the same history

Dragging, connecting, deleting, pasting, and grouping are user edits, so their completed actions are represented as commands on the same history stack as a programmatic feature edit. A completed drag is one history step rather than one step per pointer-position update. Undo and redo apply those commands to the model, so the rendered diagram reflects the reverted or replayed state.

Try the [live interaction demo](https://grafloria.com/demos/#interaction): drag an item, then use the platform's undo shortcut to see the gesture revert.

## Related

- [Undo and redo edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/undo-and-redo) — wire history controls into your app.
- [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document) — learn what the commands change.
- [The instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow) — follow data between the mounted canvas and your application.

<!-- source: diagram-intent-and-rendering.md -->

# Diagram intent and rendering

A Grafloria spec records what nodes represent, where they belong, and how links relate them; the renderer computes link routes and paints the visible diagram.

## One model, two layers

The spec is the input vocabulary shared by Grafloria's framework bindings. Bindings reconcile specs into the live diagram model; the renderer reads that model to choose geometry and draw it. The [diagram instance](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance) is the facade to the mounted canvas, its data model, and its engine.

```mermaid
flowchart LR
  S["Node and edge specs"] --> M["Live diagram model"]
  M --> R["Renderer: route and paint"]
  R --> V["Visible diagram"]
  U["User edit"] --> M
```

For nodes, the spec describes geometry such as position and size along with a label and application data. For edges, `source` and `target` identify nodes; optional handles express endpoint intent. Omit handles to let the renderer select the port-facing side as nodes move, or name a handle to pin an endpoint. A `router` chooses the route, while `connector` controls how a routed polyline is drawn. `type` is the edge shape shorthand; when router and connector are omitted, they are derived from it.

The model stores intent rather than a drawing frozen into pixels. An obstacle-avoiding route, for example, is recalculated from the current node positions. A hand-edited route is different: explicit waypoints record the bends the renderer must preserve.

## Render a routed diagram

Use [the `render` function](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) when you want to mount a spec directly in a browser host. The sample's nodes place a wall between two endpoints, and its edge requests an orthogonal route with obstacle avoidance.

```html
<div id="app" style="width: 800px; height: 420px"></div>
```

```ts
import { render } from '@grafloria/element';
import type { RenderSpec } from '@grafloria/element';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'start', position: { x: 80, y: 150 }, size: { width: 130, height: 56 }, label: 'Start' },
  { id: 'wall', position: { x: 350, y: 90 }, size: { width: 140, height: 170 }, label: 'Obstacle' },
  { id: 'finish', position: { x: 650, y: 150 }, size: { width: 130, height: 56 }, label: 'Finish' },
];

const edges: EdgeSpec[] = [
  { id: 'path', source: 'start', target: 'finish', type: 'orthogonal', router: 'avoid' },
];

const spec: RenderSpec = { nodes, edges };
const container = document.getElementById('app')!;
container.style.width = '800px';
container.style.setProperty('height', '420px', 'important');
const instance: DiagramInstance = render(spec, container);
instance.fitView();
```

`fitView()` frames all three nodes in the mounted canvas. `router: 'avoid'` selects obstacle avoidance, and `type: 'orthogonal'` gives the routed path right-angle geometry. The endpoint handles are omitted, so the renderer uses the port-facing attachment behavior rather than pinning either end to a named side.

## The same intent in framework bindings

The framework component changes how you mount and size the canvas; the `NodeSpec` and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) data still describe the same graph. These examples use default data so the component owns the initial specs rather than receiving controlled state.

### Angular

```ts
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-diagram-intent',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div class="canvas">
      <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges" />
    </div>
  `,
  styles: [':host { display: block; } .canvas { height: 420px; }'],
})
export class DiagramIntentExampleComponent {
  nodes: NodeSpec[] = [
    { id: 'start', position: { x: 80, y: 150 }, size: { width: 130, height: 56 }, label: 'Start' },
    { id: 'wall', position: { x: 350, y: 90 }, size: { width: 140, height: 170 }, label: 'Obstacle' },
    { id: 'finish', position: { x: 650, y: 150 }, size: { width: 130, height: 56 }, label: 'Finish' },
  ];

  edges: EdgeSpec[] = [
    { id: 'path', source: 'start', target: 'finish', type: 'orthogonal', router: 'avoid' },
  ];
}
```

The Angular canvas starts from the same nodes and edge. Two-way bindings keep the component's edited node and edge arrays in the component fields.

## Keep the distinction clear

- Use node positions and sizes to describe box geometry; use edge endpoints and handles to describe connection intent.
- Choose a `router` for where a line travels and a `connector` for how its path is drawn. `type` is the shorthand shape setting, not a node position.
- Use `waypoints` when the bends themselves are part of the saved intent. Without manual waypoints, the route follows the current endpoints and routing rules.
- The spec passed to `render()` is an object (or its JSON), not a Mermaid-style text DSL. Use the text import API when your input is diagram text.

For a running view of an edge routed around a movable obstacle, see the [edge-routing demo](https://grafloria.com/demos/edges/edge-routing.html). For the broader model vocabulary, continue to [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document), then see [Route and edit edges](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/route-and-edit-edges) for user-edited bends.

<!-- source: build-runnable-workflows.md -->

# Build runnable workflows

Build a branching workflow diagram and run a browser-side path through it, showing the current, completed, and unselected steps and links.

Use this pattern when your application owns the workflow rules and execution. The canvas displays the workflow; your runner decides which branch to take and updates the visible data as each step runs. In this example the runner takes the approved branch.

## 1. Describe the steps and branches

Use [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec) for each step and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) for each connection. The graph below branches from `Check approval` to either `Deploy` or `Hold`; the runner takes the approved route through `Deploy` to `Finish`.

The bindings pass these specs to a live [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow) in Qwik, [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow) in React, and [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow) in Vue. Plain JavaScript mounts the same graph with [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render), and Angular uses [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent).

## 2. Mount the graph and run its selected path

Each example starts with the same five nodes and four links. Press **Run workflow**: the runner marks a node as running, waits, then marks it complete and advances along the selected links. The initial links leaving `Check approval` are labelled `approved` and `rejected`; the final view marks `Hold` and its link as not selected. Status is represented in the node labels and node/link styles, so the workflow rules and the status display remain application data. The JavaScript, React, and Vue samples reconcile these changes with `setNodes()` and `setEdges()` on the mounted [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance); Angular and Qwik bind updated data arrays.

The canvas fills its parent. Give the host a resolved height; without one, the canvas is blank.

Choose the install command for your framework; these are alternatives, not a single command sequence:

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
npm install @grafloria/react @grafloria/engine @grafloria/renderer react react-dom @grafloria/element
npm install @grafloria/vue @grafloria/engine @grafloria/renderer vue @grafloria/element
npm install @grafloria/qwik @grafloria/engine @grafloria/renderer @builder.io/qwik @grafloria/element
npm install @grafloria/angular @angular/common @angular/core @angular/forms @angular/platform-browser @grafloria/engine @grafloria/renderer rxjs @grafloria/element
```

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const nodes = [
  { id: 'trigger', position: { x: 40, y: 180 }, size: { width: 140, height: 60 }, label: 'Trigger' },
  { id: 'check', position: { x: 230, y: 180 }, size: { width: 160, height: 60 }, label: 'Check approval' },
  { id: 'deploy', position: { x: 460, y: 90 }, size: { width: 140, height: 60 }, label: 'Deploy' },
  { id: 'hold', position: { x: 460, y: 270 }, size: { width: 140, height: 60 }, label: 'Hold' },
  { id: 'finish', position: { x: 650, y: 90 }, size: { width: 140, height: 60 }, label: 'Finish' },
];
const edges = [
  { id: 'start', source: 'trigger', target: 'check' },
  { id: 'approved', source: 'check', target: 'deploy', label: 'approved' },
  { id: 'rejected', source: 'check', target: 'hold', label: 'rejected' },
  { id: 'finish-link', source: 'deploy', target: 'finish' },
];

const host = document.createElement('div');
host.style.height = '440px';
document.body.append(host);
const button = document.createElement('button');
button.textContent = 'Run workflow';
document.body.insertBefore(button, host);
const readout = document.createElement('p');
readout.textContent = 'Ready';
document.body.insertBefore(readout, host);
const instance = render({ nodes, edges }, host);
instance.fitView(30);

/**
 * @param {string | null} current
 * @param {string[]} completed
 * @param {string[]} skipped
 * @param {string | null} activeLink
 * @param {string[]} completedLinks
 * @param {string | null} skippedLink
 */
function paint(current, completed, skipped, activeLink, completedLinks, skippedLink) {
  instance.setNodes(nodes.map((node) => {
    const id = node.id ?? '';
    const state = id === current ? 'running'
      : completed.includes(id) ? 'completed'
      : skipped.includes(id) ? 'not selected' : 'ready';
    const fill = state === 'running' ? '#dbeafe'
      : state === 'completed' ? '#dcfce7'
      : state === 'not selected' ? '#f1f5f9' : '#ffffff';
    const stroke = state === 'running' ? '#2563eb'
      : state === 'completed' ? '#16a34a'
      : state === 'not selected' ? '#94a3b8' : '#64748b';
    return { ...node, label: `${node.label} · ${state}`, style: { fill, stroke, strokeWidth: 2 } };
  }));
  instance.setEdges(edges.map((edge) => {
    const id = edge.id ?? '';
    const state = id === activeLink ? 'running'
      : completedLinks.includes(id) ? 'completed'
      : id === skippedLink ? 'not selected' : '';
    const stroke = state === 'running' ? '#2563eb'
      : state === 'completed' ? '#16a34a'
      : state === 'not selected' ? '#94a3b8' : '#64748b';
    return { ...edge, label: state || edge.label, style: { stroke, strokeWidth: state === 'running' ? 4 : 2 } };
  }));
}

/** @param {number} ms */
const delay = (ms) => new Promise((resolve) => window.setTimeout(resolve, ms));
async function run() {
  const approved = true;
  const path = approved ? ['trigger', 'check', 'deploy', 'finish'] : ['trigger', 'check', 'hold'];
  const pathLinks = approved ? ['start', 'approved', 'finish-link'] : ['start', 'rejected'];
  const allNodeIds = nodes.map((node) => node.id ?? '');
  const allLinkIds = edges.map((edge) => edge.id ?? '');
  const completed = [];
  const completedLinks = [];

  for (let index = 0; index < path.length; index += 1) {
    const nodeId = path[index];
    if (nodeId === undefined) continue;
    const activeLink = pathLinks[index - 1] ?? null;
    paint(nodeId, completed, [], activeLink, completedLinks, null);
    readout.textContent = `Running: ${nodeId}`;
    await delay(500);
    completed.push(nodeId);
    if (activeLink) completedLinks.push(activeLink);
  }

  const skipped = allNodeIds.filter((id) => !path.includes(id));
  const skippedLink = allLinkIds.find((id) => !pathLinks.includes(id) && id !== 'finish-link') ?? null;
  paint(null, completed, skipped, null, completedLinks, skippedLink);
  readout.textContent = `Completed the ${approved ? 'approved' : 'rejected'} branch`;
}

button.addEventListener('click', () => { void run(); });
paint(null, [], [], null, [], null);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const NODES: NodeSpec[] = [
  { id: 'trigger', position: { x: 40, y: 180 }, size: { width: 140, height: 60 }, label: 'Trigger' },
  { id: 'check', position: { x: 230, y: 180 }, size: { width: 160, height: 60 }, label: 'Check approval' },
  { id: 'deploy', position: { x: 460, y: 90 }, size: { width: 140, height: 60 }, label: 'Deploy' },
  { id: 'hold', position: { x: 460, y: 270 }, size: { width: 140, height: 60 }, label: 'Hold' },
  { id: 'finish', position: { x: 650, y: 90 }, size: { width: 140, height: 60 }, label: 'Finish' },
];
const EDGES: EdgeSpec[] = [
  { id: 'start', source: 'trigger', target: 'check' },
  { id: 'approved', source: 'check', target: 'deploy', label: 'approved' },
  { id: 'rejected', source: 'check', target: 'hold', label: 'rejected' },
  { id: 'finish-link', source: 'deploy', target: 'finish' },
];

@Component({
  selector: 'app-workflow',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="run()">Run workflow</button>
    <p>{{ readout }}</p>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display: block; height: 440px" />
  `,
})
export class WorkflowComponent {
  nodes: NodeSpec[] = NODES;
  edges: EdgeSpec[] = EDGES;
  readout = 'Ready';

  private paint(current: string | null, completed: string[], skipped: string[], activeLink: string | null, completedLinks: string[], skippedLink: string | null): void {
    this.nodes = NODES.map((node) => {
      const id = node.id ?? '';
      const state = id === current ? 'running'
        : completed.includes(id) ? 'completed'
        : skipped.includes(id) ? 'not selected' : 'ready';
      const fill = state === 'running' ? '#dbeafe'
        : state === 'completed' ? '#dcfce7'
        : state === 'not selected' ? '#f1f5f9' : '#ffffff';
      const stroke = state === 'running' ? '#2563eb'
        : state === 'completed' ? '#16a34a'
        : state === 'not selected' ? '#94a3b8' : '#64748b';
      return { ...node, label: `${node.label ?? id} · ${state}`, style: { fill, stroke, strokeWidth: 2 } };
    });
    this.edges = EDGES.map((edge) => {
      const id = edge.id ?? '';
      const state = id === activeLink ? 'running'
        : completedLinks.includes(id) ? 'completed'
        : id === skippedLink ? 'not selected' : '';
      const stroke = state === 'running' ? '#2563eb'
        : state === 'completed' ? '#16a34a'
        : state === 'not selected' ? '#94a3b8' : '#64748b';
      return { ...edge, label: state || edge.label, style: { stroke, strokeWidth: state === 'running' ? 4 : 2 } };
    });
  }

  async run(): Promise<void> {
    const approved = true;
    const path = approved ? ['trigger', 'check', 'deploy', 'finish'] : ['trigger', 'check', 'hold'];
    const pathLinks = approved ? ['start', 'approved', 'finish-link'] : ['start', 'rejected'];
    const completed: string[] = [];
    const completedLinks: string[] = [];
    for (let index = 0; index < path.length; index += 1) {
      const nodeId = path[index];
      if (nodeId === undefined) continue;
      const activeLink = pathLinks[index - 1] ?? null;
      this.paint(nodeId, completed, [], activeLink, completedLinks, null);
      this.readout = `Running: ${nodeId}`;
      await new Promise<void>((resolve) => window.setTimeout(resolve, 500));
      completed.push(nodeId);
      if (activeLink) completedLinks.push(activeLink);
    }
    const skipped = NODES.map((node) => node.id ?? '').filter((id) => !path.includes(id));
    const skippedLink = EDGES.map((edge) => edge.id ?? '').find((id) => !pathLinks.includes(id) && id !== 'finish-link') ?? null;
    this.paint(null, completed, skipped, null, completedLinks, skippedLink);
    this.readout = `Completed the ${approved ? 'approved' : 'rejected'} branch`;
  }
}
```
```tsx title="Qwik"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const INITIAL_NODES: NodeSpec[] = [
  { id: 'trigger', position: { x: 40, y: 180 }, size: { width: 140, height: 60 }, label: 'Trigger' },
  { id: 'check', position: { x: 230, y: 180 }, size: { width: 160, height: 60 }, label: 'Check approval' },
  { id: 'deploy', position: { x: 460, y: 90 }, size: { width: 140, height: 60 }, label: 'Deploy' },
  { id: 'hold', position: { x: 460, y: 270 }, size: { width: 140, height: 60 }, label: 'Hold' },
  { id: 'finish', position: { x: 650, y: 90 }, size: { width: 140, height: 60 }, label: 'Finish' },
];
const INITIAL_EDGES: EdgeSpec[] = [
  { id: 'start', source: 'trigger', target: 'check' },
  { id: 'approved', source: 'check', target: 'deploy', label: 'approved' },
  { id: 'rejected', source: 'check', target: 'hold', label: 'rejected' },
  { id: 'finish-link', source: 'deploy', target: 'finish' },
];

export default component$(() => {
  const nodes = useSignal<NodeSpec[]>(INITIAL_NODES);
  const edges = useSignal<EdgeSpec[]>(INITIAL_EDGES);
  const readout = useSignal('Ready');

  return (
    <div>
      <button type="button" onClick$={async () => {
        const approved = true;
        const path = approved ? ['trigger', 'check', 'deploy', 'finish'] : ['trigger', 'check', 'hold'];
        const pathLinks = approved ? ['start', 'approved', 'finish-link'] : ['start', 'rejected'];
        const completed: string[] = [];
        const completedLinks: string[] = [];
        const paint = (current: string | null, skipped: string[], activeLink: string | null, skippedLink: string | null): void => {
          nodes.value = INITIAL_NODES.map((node) => {
            const id = node.id ?? '';
            const state = id === current ? 'running'
              : completed.includes(id) ? 'completed'
              : skipped.includes(id) ? 'not selected' : 'ready';
            const fill = state === 'running' ? '#dbeafe'
              : state === 'completed' ? '#dcfce7'
              : state === 'not selected' ? '#f1f5f9' : '#ffffff';
            const stroke = state === 'running' ? '#2563eb'
              : state === 'completed' ? '#16a34a'
              : state === 'not selected' ? '#94a3b8' : '#64748b';
            return { ...node, label: `${node.label ?? id} · ${state}`, style: { fill, stroke, strokeWidth: 2 } };
          });
          edges.value = INITIAL_EDGES.map((edge) => {
            const id = edge.id ?? '';
            const state = id === activeLink ? 'running'
              : completedLinks.includes(id) ? 'completed'
              : id === skippedLink ? 'not selected' : '';
            const stroke = state === 'running' ? '#2563eb'
              : state === 'completed' ? '#16a34a'
              : state === 'not selected' ? '#94a3b8' : '#64748b';
            return { ...edge, label: state || edge.label, style: { stroke, strokeWidth: state === 'running' ? 4 : 2 } };
          });
        };

        for (let index = 0; index < path.length; index += 1) {
          const nodeId = path[index];
          if (nodeId === undefined) continue;
          const activeLink = pathLinks[index - 1] ?? null;
          paint(nodeId, [], activeLink, null);
          readout.value = `Running: ${nodeId}`;
          await new Promise<void>((resolve) => setTimeout(resolve, 500));
          completed.push(nodeId);
          if (activeLink) completedLinks.push(activeLink);
          paint(null, [], null, null);
        }

        const skipped = INITIAL_NODES.map((node) => node.id ?? '').filter((id) => !path.includes(id));
        const skippedLink = INITIAL_EDGES.map((edge) => edge.id ?? '').find((id) => !pathLinks.includes(id) && id !== 'finish-link') ?? null;
        paint(null, skipped, null, skippedLink);
        readout.value = `Completed the ${approved ? 'approved' : 'rejected'} branch`;
      }}>Run workflow</button>
      <p>{readout.value}</p>
      <div style={{ height: '440px' }}>
        <GrafloriaFlow nodes={nodes.value} edges={edges.value} fitView readonly />
      </div>
    </div>
  );
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const NODES: NodeSpec[] = [
  { id: 'trigger', position: { x: 40, y: 180 }, size: { width: 140, height: 60 }, label: 'Trigger' },
  { id: 'check', position: { x: 230, y: 180 }, size: { width: 160, height: 60 }, label: 'Check approval' },
  { id: 'deploy', position: { x: 460, y: 90 }, size: { width: 140, height: 60 }, label: 'Deploy' },
  { id: 'hold', position: { x: 460, y: 270 }, size: { width: 140, height: 60 }, label: 'Hold' },
  { id: 'finish', position: { x: 650, y: 90 }, size: { width: 140, height: 60 }, label: 'Finish' },
];
const EDGES: EdgeSpec[] = [
  { id: 'start', source: 'trigger', target: 'check' },
  { id: 'approved', source: 'check', target: 'deploy', label: 'approved' },
  { id: 'rejected', source: 'check', target: 'hold', label: 'rejected' },
  { id: 'finish-link', source: 'deploy', target: 'finish' },
];

export function Workflow() {
  const instance = useRef<DiagramInstance | null>(null);
  const [readout, setReadout] = useState('Ready');

  async function run(): Promise<void> {
    const api = instance.current;
    if (!api) return;
    const approved = true;
    const path = approved ? ['trigger', 'check', 'deploy', 'finish'] : ['trigger', 'check', 'hold'];
    const pathLinks = approved ? ['start', 'approved', 'finish-link'] : ['start', 'rejected'];
    const completed: string[] = [];
    const completedLinks: string[] = [];
    const paint = (current: string | null, skipped: string[], activeLink: string | null, skippedLink: string | null): void => {
      api.setNodes(NODES.map((node) => {
        const id = node.id ?? '';
        const state = id === current ? 'running'
          : completed.includes(id) ? 'completed'
          : skipped.includes(id) ? 'not selected' : 'ready';
        const fill = state === 'running' ? '#dbeafe'
          : state === 'completed' ? '#dcfce7'
          : state === 'not selected' ? '#f1f5f9' : '#ffffff';
        const stroke = state === 'running' ? '#2563eb'
          : state === 'completed' ? '#16a34a'
          : state === 'not selected' ? '#94a3b8' : '#64748b';
        return { ...node, label: `${node.label ?? id} · ${state}`, style: { fill, stroke, strokeWidth: 2 } };
      }));
      api.setEdges(EDGES.map((edge) => {
        const id = edge.id ?? '';
        const state = id === activeLink ? 'running'
          : completedLinks.includes(id) ? 'completed'
          : id === skippedLink ? 'not selected' : '';
        const stroke = state === 'running' ? '#2563eb'
          : state === 'completed' ? '#16a34a'
          : state === 'not selected' ? '#94a3b8' : '#64748b';
        return { ...edge, label: state || edge.label, style: { stroke, strokeWidth: state === 'running' ? 4 : 2 } };
      }));
    };

    for (let index = 0; index < path.length; index += 1) {
      const nodeId = path[index];
      if (nodeId === undefined) continue;
      const activeLink = pathLinks[index - 1] ?? null;
      paint(nodeId, [], activeLink, null);
      setReadout(`Running: ${nodeId}`);
      await new Promise<void>((resolve) => window.setTimeout(resolve, 500));
      completed.push(nodeId);
      if (activeLink) completedLinks.push(activeLink);
      paint(null, [], null, null);
    }

    const skipped = NODES.map((node) => node.id ?? '').filter((id) => !path.includes(id));
    const skippedLink = EDGES.map((edge) => edge.id ?? '').find((id) => !pathLinks.includes(id) && id !== 'finish-link') ?? null;
    paint(null, skipped, null, skippedLink);
    setReadout(`Completed the ${approved ? 'approved' : 'rejected'} branch`);
  }

  return (
    <div>
      <button type="button" onClick={() => { void run(); }}>Run workflow</button>
      <p>{readout}</p>
      <div style={{ height: 440 }}>
        <GrafloriaFlow defaultNodes={NODES} defaultEdges={EDGES}
          onInit={(api) => { api.fitView(30); instance.current = api; }} />
      </div>
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'trigger', position: { x: 40, y: 180 }, size: { width: 140, height: 60 }, label: 'Trigger' },
  { id: 'check', position: { x: 230, y: 180 }, size: { width: 160, height: 60 }, label: 'Check approval' },
  { id: 'deploy', position: { x: 460, y: 90 }, size: { width: 140, height: 60 }, label: 'Deploy' },
  { id: 'hold', position: { x: 460, y: 270 }, size: { width: 140, height: 60 }, label: 'Hold' },
  { id: 'finish', position: { x: 650, y: 90 }, size: { width: 140, height: 60 }, label: 'Finish' },
];
const edges: EdgeSpec[] = [
  { id: 'start', source: 'trigger', target: 'check' },
  { id: 'approved', source: 'check', target: 'deploy', label: 'approved' },
  { id: 'rejected', source: 'check', target: 'hold', label: 'rejected' },
  { id: 'finish-link', source: 'deploy', target: 'finish' },
];
const instance = shallowRef<DiagramInstance | null>(null);
const readout = ref('Ready');

function paint(current: string | null, completed: string[], skipped: string[], activeLink: string | null, completedLinks: string[], skippedLink: string | null): void {
  instance.value?.setNodes(nodes.map((node) => {
    const id = node.id ?? '';
    const state = id === current ? 'running'
      : completed.includes(id) ? 'completed'
      : skipped.includes(id) ? 'not selected' : 'ready';
    const fill = state === 'running' ? '#dbeafe'
      : state === 'completed' ? '#dcfce7'
      : state === 'not selected' ? '#f1f5f9' : '#ffffff';
    const stroke = state === 'running' ? '#2563eb'
      : state === 'completed' ? '#16a34a'
      : state === 'not selected' ? '#94a3b8' : '#64748b';
    return { ...node, label: `${node.label ?? id} · ${state}`, style: { fill, stroke, strokeWidth: 2 } };
  }));
  instance.value?.setEdges(edges.map((edge) => {
    const id = edge.id ?? '';
    const state = id === activeLink ? 'running'
      : completedLinks.includes(id) ? 'completed'
      : id === skippedLink ? 'not selected' : '';
    const stroke = state === 'running' ? '#2563eb'
      : state === 'completed' ? '#16a34a'
      : state === 'not selected' ? '#94a3b8' : '#64748b';
    return { ...edge, label: state || edge.label, style: { stroke, strokeWidth: state === 'running' ? 4 : 2 } };
  }));
}

async function run(): Promise<void> {
  const approved = true;
  const path = approved ? ['trigger', 'check', 'deploy', 'finish'] : ['trigger', 'check', 'hold'];
  const pathLinks = approved ? ['start', 'approved', 'finish-link'] : ['start', 'rejected'];
  const completed: string[] = [];
  const completedLinks: string[] = [];
  for (let index = 0; index < path.length; index += 1) {
    const nodeId = path[index];
    if (nodeId === undefined) continue;
    const activeLink = pathLinks[index - 1] ?? null;
    paint(nodeId, completed, [], activeLink, completedLinks, null);
    readout.value = `Running: ${nodeId}`;
    await new Promise<void>((resolve) => window.setTimeout(resolve, 500));
    completed.push(nodeId);
    if (activeLink) completedLinks.push(activeLink);
    paint(null, completed, [], null, completedLinks, null);
  }
  const skipped = nodes.map((node) => node.id ?? '').filter((id) => !path.includes(id));
  const skippedLink = edges.map((edge) => edge.id ?? '').find((id) => !pathLinks.includes(id) && id !== 'finish-link') ?? null;
  paint(null, completed, skipped, null, completedLinks, skippedLink);
  readout.value = `Completed the ${approved ? 'approved' : 'rejected'} branch`;
}

function onInit(api: DiagramInstance): void {
  api.fitView(30);
  instance.value = api;
  paint(null, [], [], null, [], null);
}
</script>

<template>
  <button type="button" @click="run">Run workflow</button>
  <p>{{ readout }}</p>
  <div style="height: 440px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
  </div>
</template>
```
:::

## What the run displays

While a step is active, its label ends in `running` and its fill and border turn blue; the incoming selected link is also blue and labelled `running`. Completed steps and traversed links turn green. At the end, `Hold` and the rejected branch are grey and labelled `not selected`. The status text above the canvas shows the current step and the selected branch result.

The instance is the facade to the mounted canvas and its data model. In these examples, the instance's [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) methods `setNodes()` and `setEdges()` reconcile new specs into that live diagram. The runner—not the graph renderer—owns the example's approval rule and the sequence of steps.

## Props used

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `defaultNodes` | `NodeSpec[]` | Not specified | Seeds the mounted flow with its step nodes. |
| `defaultEdges` | `EdgeSpec[]` | Not specified | Seeds the mounted flow with its branch links. |
| `onInit` | `(instance: DiagramInstance) => void` | Not specified | Gives React and Vue the mounted instance. |
| `nodes` (Qwik) | `NodeSpec[]` | Not specified | Supplies controlled node data; the sample updates labels and styles as its runner advances. |
| `edges` (Qwik) | `EdgeSpec[]` | Not specified | Supplies controlled link data; the sample updates link labels and styles during the run. |
| `fitView` (Qwik) | `boolean` | Not specified | Fits the initial workflow in the canvas. |
| `readonly` (Qwik) | `boolean` | Not specified | Disables canvas editing while the runner updates its controlled data. |
| `nodes` (Angular) | `readonly (`NodeSpec` \| [`NodeModel`](doc:grafloria-engine-models-nodemodel#nodemodel))[] \| `undefined` | `undefined` | Controlled nodes; `[(nodes)]` writes canvas changes back to the host. |
| `edges` (Angular) | `readonly (`EdgeSpec` \| [`LinkModel`](doc:grafloria-engine-models-linkmodel#linkmodel))[] \| `undefined` | `undefined` | Controlled links; `[(edges)]` writes canvas changes back to the host. |

Plain JavaScript gets the instance directly from `render()`. Angular binds its node and edge arrays with the canvas's two-way `nodes` and `edges` inputs.

## Pitfalls

- Give the canvas parent a real height. The canvas fills its parent; an unresolved parent height leaves a blank canvas.
- Keep the workflow rule in your runner. The graph describes steps and connections; replace the example's fixed `approved` value with your application's branch condition.

## See it running

The [n8n-style workflow demo](https://grafloria.com/demos/interaction/n8n-workflow.html) runs a graph from its trigger, shows running and completed node states, and routes a condition down one branch. Its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/n8n-workflow.html) shows the repository's fuller execution UI.

The [workflow automation builder](https://grafloria.com/demos/interaction/workflow-builder.html) tests a Condition and health-check Switch against sample inputs; its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/workflow-builder.html) includes the step editor and run card.

## Related

- [Execute and compute flows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/execute-and-compute-flows) — separate workflow execution from the graph that displays it.
- [Add nodes from palettes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/add-nodes-from-palettes) — let users build the graph interactively.
- [The instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow) — understand how specs reconcile into the live model.

<!-- source: execute-and-compute-flows.md -->

# Execute and compute flows

This page focuses on what happens after the graph is mounted: update execution status as a runner advances, or follow live links to recompute values. For the framework-specific mounting setup, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows).

Grafloria does not run your business logic for you. Set each live node's status as your runner advances, and calculate values by following the diagram's current links. Each framework example uses typed graph data; the JavaScript example shows the same host-side logic in the browser.

The JavaScript example runs in a browser app whose build resolves npm package imports.

## Prepare the graph and its host-side logic

This module declares two small graphs: a workflow whose nodes receive execution statuses, and a typed-port pipeline that calculates `input × 3 + 10`. `compute()` follows the live link models, while `execute()` updates the mounted model's status and active-wire style.

```ts title="flow-logic.ts"
import type { DiagramModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export const executionNodes: NodeSpec[] = [
  { id: 'trigger', position: { x: 60, y: 120 }, size: { width: 130, height: 54 }, label: 'Trigger' },
  { id: 'fetch', position: { x: 260, y: 120 }, size: { width: 130, height: 54 }, label: 'Fetch data' },
  { id: 'transform', position: { x: 460, y: 120 }, size: { width: 130, height: 54 }, label: 'Transform' },
];

export const executionEdges: EdgeSpec[] = [
  { id: 'fetch-link', source: 'trigger', target: 'fetch' },
  { id: 'transform-link', source: 'fetch', target: 'transform' },
];

export const computeNodes: NodeSpec[] = [
  {
    id: 'in', position: { x: 40, y: 120 }, size: { width: 120, height: 56 }, label: 'input',
    ports: [{ id: 'in.out', side: 'right', type: 'output', dataType: 'number' }],
    data: { value: 2 },
  },
  {
    id: 'mul', position: { x: 240, y: 120 }, size: { width: 120, height: 56 }, label: '× 3',
    ports: [
      { id: 'mul.in', side: 'left', type: 'input', dataType: 'number' },
      { id: 'mul.out', side: 'right', type: 'output', dataType: 'number' },
    ],
    data: { operation: 'multiply', factor: 3, value: 0 },
  },
  {
    id: 'add', position: { x: 440, y: 120 }, size: { width: 120, height: 56 }, label: '+ 10',
    ports: [
      { id: 'add.in', side: 'left', type: 'input', dataType: 'number' },
      { id: 'add.out', side: 'right', type: 'output', dataType: 'number' },
    ],
    data: { operation: 'add', amount: 10, value: 0 },
  },
  {
    id: 'out', position: { x: 640, y: 120 }, size: { width: 120, height: 56 }, label: 'sink',
    ports: [{ id: 'out.in', side: 'left', type: 'input', dataType: 'number' }],
    data: { operation: 'sink', value: 0 },
  },
];

export const computeEdges: EdgeSpec[] = [
  { id: 'l1', source: 'in', target: 'mul', sourceHandle: 'in.out', targetHandle: 'mul.in' },
  { id: 'l2', source: 'mul', target: 'add', sourceHandle: 'mul.out', targetHandle: 'add.in' },
  { id: 'l3', source: 'add', target: 'out', sourceHandle: 'add.out', targetHandle: 'out.in' },
];

export async function execute(model: DiagramModel, report: (message: string) => void): Promise<void> {
  const order = ['trigger', 'fetch', 'transform'];
  for (const id of order) model.getNode(id)?.setState({ status: 'pending' });

  for (const id of order) {
    const node = model.getNode(id);
    if (!node) continue;
    const incoming = model.getLinks().filter((link) => link.targetNodeId === id);
    for (const link of incoming) link.updateStyle({ animation: { type: 'flow' } });
    node.setState({ status: 'running', animateStatus: true });
    report(`running: ${id}`);
    await new Promise<void>((resolve) => window.setTimeout(resolve, 500));
    node.setState({ status: 'completed' });
    for (const link of incoming) link.updateStyle({ animation: { type: 'none' } });
  }

  report('flow completed');
}

export function compute(model: DiagramModel, value: number): string {
  const source = model.getNode('in');
  if (source) source.data.value = Number.isFinite(value) ? value : 0;

  for (const id of ['mul', 'add', 'out']) {
    const node = model.getNode(id);
    if (!node) continue;
    const incoming = model.getLinks().find((link) => link.targetNodeId === id);
    const fromId = incoming?.sourceNodeId;
    const from = fromId ? model.getNode(fromId) : undefined;
    if (!from || typeof from.data.value !== 'number') continue;

    const incomingValue = from.data.value;
    if (node.data.operation === 'multiply') {
      node.data.value = incomingValue * node.data.factor;
    } else if (node.data.operation === 'add') {
      node.data.value = incomingValue + node.data.amount;
    } else {
      node.data.value = incomingValue;
    }
  }

  const valueAt = (id: string): number => {
    const node = model.getNode(id);
    return typeof node?.data.value === 'number' ? node.data.value : 0;
  };
  return `→  ×3=${valueAt('mul')}  →  +10=${valueAt('add')}  →  sink=${valueAt('out')}`;
}

export function watchCompute(model: DiagramModel, report: (message: string) => void): (value: number) => void {
  let currentValue = Number(model.getNode('in')?.data.value ?? 0);
  const refresh = (): void => report(compute(model, currentValue));
  model.on('link:added', refresh);
  model.on('link:removed', refresh);
  refresh();
  return (value: number): void => {
    currentValue = value;
    refresh();
  };
}
```

The execution example sets `pending`, then marks one node `running` and `completed` at a time; the node status classes and link animation are rendered by Grafloria. The computing example stores each result in the live node data and prints the derived chain above the canvas. Its order is fixed for this pipeline; for a graph that branches or can be reordered, derive a topological order from your graph.

## Execute a flow

Use execution statuses when your application already knows which work is ready, active, or complete. The runner remains host code; the mounted diagram displays the status changes and animated incoming link. For framework-specific mounting, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows).

:::code-group
```html title="JavaScript"
<div style="height: 430px">
  <button id="run" type="button">Run flow</button>
  <output id="status">ready</output>
  <div id="app" style="height: 380px"></div>
</div>
<script type="module">
  import { render } from '@grafloria/element';

  /** @type {import('@grafloria/renderer').NodeSpec[]} */
  const nodes = [
    { id: 'trigger', position: { x: 60, y: 120 }, size: { width: 130, height: 54 }, label: 'Trigger' },
    { id: 'fetch', position: { x: 260, y: 120 }, size: { width: 130, height: 54 }, label: 'Fetch data' },
    { id: 'transform', position: { x: 460, y: 120 }, size: { width: 130, height: 54 }, label: 'Transform' },
  ];
  /** @type {import('@grafloria/renderer').EdgeSpec[]} */
  const edges = [
    { id: 'fetch-link', source: 'trigger', target: 'fetch' },
    { id: 'transform-link', source: 'fetch', target: 'transform' },
  ];
  const host = document.querySelector('#app');
  const button = document.querySelector('#run');
  const output = document.querySelector('#status');
  if (!(host instanceof HTMLElement) || !(button instanceof HTMLButtonElement) || !(output instanceof HTMLOutputElement)) {
    throw new Error('The flow demo elements are missing.');
  }
  const instance = render({ nodes, edges }, host);
  const model = instance.getModel();

  button.addEventListener('click', async () => {
    const order = ['trigger', 'fetch', 'transform'];
    for (const id of order) model.getNode(id)?.setState({ status: 'pending' });
    for (const id of order) {
      const node = model.getNode(id);
      if (!node) continue;
      const incoming = model.getLinks().filter((link) => link.targetNodeId === id);
      for (const link of incoming) link.updateStyle({ animation: { type: 'flow' } });
      node.setState({ status: 'running', animateStatus: true });
      output.value = `running: ${id}`;
      await new Promise((resolve) => window.setTimeout(resolve, 500));
      node.setState({ status: 'completed' });
      for (const link of incoming) link.updateStyle({ animation: { type: 'none' } });
    }
    output.value = 'flow completed';
  });
</script>
```
```ts title="Angular"
import { AfterViewInit, Component, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { DiagramModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { execute, executionEdges, executionNodes } from './flow-logic';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="run()">Run flow</button>
    <output>{{ status() }}</output>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:380px" />
  `,
})
export class ExecuteFlowComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = executionNodes;
  edges: EdgeSpec[] = executionEdges;
  readonly status = signal('ready');
  private model: DiagramModel | null = null;

  ngAfterViewInit(): void {
    this.model = this.canvas().activeEngine()?.getDiagram() ?? null;
  }

  async run(): Promise<void> {
    if (this.model) await execute(this.model, (message) => { this.status.set(message); });
  }
}
```
```tsx title="Qwik"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export default component$(() => {
  const nodes: NodeSpec[] = [
    { id: 'trigger', position: { x: 60, y: 120 }, size: { width: 130, height: 54 }, label: 'Trigger' },
    { id: 'fetch', position: { x: 260, y: 120 }, size: { width: 130, height: 54 }, label: 'Fetch data' },
    { id: 'transform', position: { x: 460, y: 120 }, size: { width: 130, height: 54 }, label: 'Transform' },
  ];
  const runningNodes: NodeSpec[] = nodes.map((node) => ({ ...node, label: `${node.label} · running` }));
  const edges: EdgeSpec[] = [
    { id: 'fetch-link', source: 'trigger', target: 'fetch' },
    { id: 'transform-link', source: 'fetch', target: 'transform' },
  ];
  const running = useSignal(false);

  return (
    <div style={{ height: '430px' }}>
      <label><input type="checkbox" bind:checked={running} /> Run flow</label>
      <output>{running.value ? 'running: all workflow stages' : 'ready'}</output>
      <div style={{ height: '380px' }}>
        <GrafloriaFlow nodes={running.value ? runningNodes : nodes} edges={edges} />
      </div>
    </div>
  );
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { DiagramModel } from '@grafloria/engine';
import { execute, executionEdges, executionNodes } from './flow-logic';

export function ExecuteFlow() {
  const model = useRef<DiagramModel | null>(null);
  const [status, setStatus] = useState('ready');

  return (
    <div style={{ height: 430 }}>
      <button type="button" onClick={() => {
        if (model.current) void execute(model.current, setStatus);
      }}>Run flow</button>
      <output>{status}</output>
      <div style={{ height: 380 }}>
        <GrafloriaFlow defaultNodes={executionNodes} defaultEdges={executionEdges}
          onInit={(instance: DiagramInstance) => { model.current = instance.getModel(); }} />
      </div>
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/vue';
import type { DiagramModel } from '@grafloria/engine';
import { execute, executionEdges, executionNodes } from './flow-logic';

const model = shallowRef<DiagramModel | null>(null);
const status = ref('ready');
function onInit(instance: DiagramInstance): void {
  model.value = instance.getModel();
}
async function run(): Promise<void> {
  if (model.value) await execute(model.value, (message) => { status.value = message; });
}
</script>

<template>
  <div style="height:430px">
    <button type="button" @click="run">Run flow</button>
    <output>{{ status }}</output>
    <div style="height:380px">
      <GrafloriaFlow :default-nodes="executionNodes" :default-edges="executionEdges" @init="onInit" />
    </div>
  </div>
</template>
```
:::

In the JavaScript sample's initial render, look for the three connected nodes and the **Run flow** control above the canvas.

![The JavaScript sample mounts the connected three-node workflow and Run flow control.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/bd51678b7e84c6866749c039c264bbaa.png)

Press **Run flow** in the JavaScript, Angular, React, or Vue sample to move each node through pending, running, and completed. While a node runs, its incoming link uses the `flow` animation; the status readout follows the same order. In Qwik, check **Run flow** to reconcile running annotations into the mounted nodes and update the readout; that example uses node labels rather than engine status animation. The other samples set node statuses and link styles on the mounted model.

![The canvas starts with Trigger, Fetch data, and Transform connected below the Run flow control.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4ecd2f7c7860d37ba27796642efcc3e1.png)

The status value is a [`NodeModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-nodemodel) state field. Grafloria renders statuses such as `running`, `completed`, `error`, and `warning` as status classes; `animateStatus: false` disables motion while preserving the status treatment. Link animation is set through the live link's `updateStyle()` method.

| Option or field | Type | Default | What it does |
|---|---|---|---|
| `status` | `'idle' \| 'pending' \| 'running' \| 'completed' \| 'error' \| 'warning'` | Not specified | Supplies the node's execution state for rendering. |
| `animateStatus` | `boolean` | Not specified | Set to `false` to keep the status appearance without its motion. |
| `animation.type` | `'marching-ants' \| 'flow' \| 'pulse' \| 'dash-flow' \| 'none'` | Not specified | Chooses the link animation; this example uses `flow` while the link is active and `none` afterward. |

The runner above is intentionally small. Add your own cancellation, retries, failure policy, or branching rules around the same model updates. If you expose a controlled React graph, wire its change callback so user edits do not get replaced by stale application state; see [the React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start).

## Compute values along the live links

Use live topology when graph edits should change the computation path. The host reads the current links, calculates the downstream values, and updates a readout; typing a new source value recomputes the chain. The `ports` and `sourceHandle` / `targetHandle` fields declare numeric ports and the endpoints each edge names, but the arithmetic remains application code.

:::code-group
```html title="JavaScript"
<div style="height: 430px">
  <label>Input <input id="source" type="number" step="1" value="2"></label>
  <output id="result"></output>
  <div id="app" style="height: 380px"></div>
</div>
<script type="module">
  import { render } from '@grafloria/element';

  /** @type {import('@grafloria/renderer').NodeSpec[]} */
  const nodes = [
    { id: 'in', position: { x: 40, y: 120 }, size: { width: 120, height: 56 }, label: 'input',
      ports: [{ id: 'in.out', side: 'right', type: 'output', dataType: 'number' }], data: { value: 2 } },
    { id: 'mul', position: { x: 240, y: 120 }, size: { width: 120, height: 56 }, label: '× 3',
      ports: [{ id: 'mul.in', side: 'left', type: 'input', dataType: 'number' }, { id: 'mul.out', side: 'right', type: 'output', dataType: 'number' }],
      data: { operation: 'multiply', factor: 3, value: 0 } },
    { id: 'add', position: { x: 440, y: 120 }, size: { width: 120, height: 56 }, label: '+ 10',
      ports: [{ id: 'add.in', side: 'left', type: 'input', dataType: 'number' }, { id: 'add.out', side: 'right', type: 'output', dataType: 'number' }],
      data: { operation: 'add', amount: 10, value: 0 } },
    { id: 'out', position: { x: 640, y: 120 }, size: { width: 120, height: 56 }, label: 'sink',
      ports: [{ id: 'out.in', side: 'left', type: 'input', dataType: 'number' }], data: { operation: 'sink', value: 0 } },
  ];
  /** @type {import('@grafloria/renderer').EdgeSpec[]} */
  const edges = [
    { id: 'l1', source: 'in', target: 'mul', sourceHandle: 'in.out', targetHandle: 'mul.in' },
    { id: 'l2', source: 'mul', target: 'add', sourceHandle: 'mul.out', targetHandle: 'add.in' },
    { id: 'l3', source: 'add', target: 'out', sourceHandle: 'add.out', targetHandle: 'out.in' },
  ];
  const host = document.querySelector('#app');
  const sourceInput = document.querySelector('#source');
  const output = document.querySelector('#result');
  if (!(host instanceof HTMLElement) || !(sourceInput instanceof HTMLInputElement) || !(output instanceof HTMLOutputElement)) {
    throw new Error('The computing-flow demo elements are missing.');
  }
  const instance = render({ nodes, edges }, host);
  const model = instance.getModel();
  let sourceValue = 2;

  const recompute = () => {
    const source = model.getNode('in');
    if (source) source.data.value = sourceValue;
    for (const id of ['mul', 'add', 'out']) {
      const node = model.getNode(id);
      if (!node) continue;
      const link = model.getLinks().find((item) => item.targetNodeId === id);
      const sourceId = link?.sourceNodeId;
      const upstream = sourceId ? model.getNode(sourceId) : undefined;
      if (!upstream || typeof upstream.data.value !== 'number') continue;
      if (node.data.operation === 'multiply') node.data.value = upstream.data.value * node.data.factor;
      else if (node.data.operation === 'add') node.data.value = upstream.data.value + node.data.amount;
      else node.data.value = upstream.data.value;
    }
    /** @param {string} id */
    const valueAt = (id) => model.getNode(id)?.data.value ?? 0;
    output.value = `→ ×3=${valueAt('mul')} → +10=${valueAt('add')} → sink=${valueAt('out')}`;
  };
  sourceInput.addEventListener('input', () => {
    const value = Number(sourceInput.value);
    sourceValue = Number.isFinite(value) ? value : 0;
    recompute();
  });
  model.on('link:added', recompute);
  model.on('link:removed', recompute);
  recompute();
</script>
```
```ts title="Angular"
import { AfterViewInit, Component, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { DiagramModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { computeEdges, computeNodes, watchCompute } from './flow-logic';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <label>Input <input type="number" step="1" value="2" (input)="update($event)" /></label>
    <output>{{ result() }}</output>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:380px" />
  `,
})
export class ComputingFlowsComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = computeNodes;
  edges: EdgeSpec[] = computeEdges;
  readonly result = signal('');
  private model: DiagramModel | null = null;
  private setInput: ((value: number) => void) | null = null;

  ngAfterViewInit(): void {
    this.model = this.canvas().activeEngine()?.getDiagram() ?? null;
    if (this.model) this.setInput = watchCompute(this.model, (message) => { this.result.set(message); });
  }

  update(event: Event): void {
    const input = event.target;
    if (input instanceof HTMLInputElement) this.setInput?.(Number(input.value));
  }
}
```
```tsx title="Qwik"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export default component$(() => {
  const nodes: NodeSpec[] = [
    {
      id: 'in', position: { x: 40, y: 120 }, size: { width: 120, height: 56 }, label: 'input',
      ports: [{ id: 'in.out', side: 'right', type: 'output', dataType: 'number' }], data: { value: 2 },
    },
    {
      id: 'mul', position: { x: 240, y: 120 }, size: { width: 120, height: 56 }, label: '× 3',
      ports: [
        { id: 'mul.in', side: 'left', type: 'input', dataType: 'number' },
        { id: 'mul.out', side: 'right', type: 'output', dataType: 'number' },
      ], data: { operation: 'multiply', factor: 3, value: 0 },
    },
    {
      id: 'add', position: { x: 440, y: 120 }, size: { width: 120, height: 56 }, label: '+ 10',
      ports: [
        { id: 'add.in', side: 'left', type: 'input', dataType: 'number' },
        { id: 'add.out', side: 'right', type: 'output', dataType: 'number' },
      ], data: { operation: 'add', amount: 10, value: 0 },
    },
    {
      id: 'out', position: { x: 640, y: 120 }, size: { width: 120, height: 56 }, label: 'sink',
      ports: [{ id: 'out.in', side: 'left', type: 'input', dataType: 'number' }], data: { operation: 'sink', value: 0 },
    },
  ];
  const edges: EdgeSpec[] = [
    { id: 'l1', source: 'in', target: 'mul', sourceHandle: 'in.out', targetHandle: 'mul.in' },
    { id: 'l2', source: 'mul', target: 'add', sourceHandle: 'mul.out', targetHandle: 'add.in' },
    { id: 'l3', source: 'add', target: 'out', sourceHandle: 'add.out', targetHandle: 'out.in' },
  ];
  const input = useSignal('2');

  return (
    <div style={{ height: '430px' }}>
      <label>Input <input type="number" step={1} bind:value={input} /></label>
      <output>→ ×3={Number(input.value) * 3} → +10={Number(input.value) * 3 + 10} → sink={Number(input.value) * 3 + 10}</output>
      <div style={{ height: '380px' }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
      </div>
    </div>
  );
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { DiagramModel } from '@grafloria/engine';
import { computeEdges, computeNodes, watchCompute } from './flow-logic';

export function ComputingFlows() {
  const setInput = useRef<((value: number) => void) | null>(null);
  const [result, setResult] = useState('');

  return (
    <div style={{ height: 430 }}>
      <label>Input <input type="number" step={1} defaultValue={2}
        onChange={(event) => setInput.current?.(Number(event.currentTarget.value))} /></label>
      <output>{result}</output>
      <div style={{ height: 380 }}>
        <GrafloriaFlow defaultNodes={computeNodes} defaultEdges={computeEdges}
          onInit={(instance: DiagramInstance) => {
            const model: DiagramModel = instance.getModel();
            setInput.current = watchCompute(model, setResult);
          }} />
      </div>
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/vue';
import type { DiagramModel } from '@grafloria/engine';
import { computeEdges, computeNodes, watchCompute } from './flow-logic';

const result = ref('');
const setInput = shallowRef<((value: number) => void) | null>(null);
function onInit(instance: DiagramInstance): void {
  const model: DiagramModel = instance.getModel();
  setInput.value = watchCompute(model, (message) => { result.value = message; });
}
function update(event: Event): void {
  const input = event.target;
  if (input instanceof HTMLInputElement) setInput.value?.(Number(input.value));
}
</script>

<template>
  <div style="height:430px">
    <label>Input <input type="number" step="1" value="2" @input="update" /></label>
    <output>{{ result }}</output>
    <div style="height:380px">
      <GrafloriaFlow :default-nodes="computeNodes" :default-edges="computeEdges" @init="onInit" />
    </div>
  </div>
</template>
```
:::

In the JavaScript sample's initial render, look for the calculated readout above the canvas: the source value flows through ×3 and +10 to the sink.

![The JavaScript readout shows the input value propagated through multiplication, addition, and the sink.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ad4875f8f76f7171baf6ec4890c849c8.png)

The JavaScript, Angular, React, and Vue readouts start with the graph's initial value (`2`), then update after input events and link additions or removals by reading the current connections. If a node no longer has an incoming value, these samples leave its previous value in place; define a reset or missing-input policy that matches your application. The Qwik readout recalculates when its bound input changes for this fixed three-stage pipeline; it does not subscribe to rewiring.

![The input readout shows the calculated values through the multiply, add, and sink nodes.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/b47563b4883e0f88e8ac1253b8e77bb2.png)

| Field | Type | Default | What it does |
|---|---|---|---|
| `source` / `target` | `string` | Required by `EdgeSpec` | Identifies the source and target nodes of a graph edge. |
| `sourceHandle` / `targetHandle` | `string` | Optional | Pins an edge to the declared output and input port ids. |
| Port `dataType` | `string` | Not specified | Labels each port's value type; the example uses `number` at both ends of every connection. |

The links and typed ports describe the graph; they do not execute the arithmetic. Keep computation and missing-input rules in your application, and in the JavaScript, Angular, React, and Vue variants recalculate from the live model when the source value or topology changes. For port configuration and connection rules, see [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports) and [Validate connections](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/validate-connections).

## Demos and related pages

- [Execute flow demo](https://grafloria.com/demos/interaction/execute-flow.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/execute-flow.html)
- [Computing flows demo](https://grafloria.com/demos/interaction/computing-flows.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/computing-flows.html)
- [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows)
- [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document)
- [The instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow)

<!-- source: add-nodes-from-palettes.md -->

# Add nodes from palettes

Build a small palette beside a mounted diagram; choosing a shape adds a labelled node to the live model in the next available grid position.

Use this pattern when your app owns a short list of node types and wants readers to add them without editing diagram data directly. The framework bindings mount a canvas; its instance reaches the engine, which adds each selected node to the diagram.

## Build a palette

Start with an empty diagram. In JavaScript, React and Vue, keep the live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) from the component's init callback and call `getEngine().addNode()` from each palette button. Angular gets its active engine from the canvas component when a button is clicked; Qwik updates controlled node data. The engine returns a promise for the node it adds; each sample places new nodes in a grid so their labels stay visible beside previous choices.

Unlike a workflow that starts from a fixed graph, each palette choice adds one labelled `rect` at the next grid position; see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows) for the framework-specific mounting patterns.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const root = document.createElement('div');
root.style.cssText = 'display:grid;grid-template-columns:160px 1fr;height:420px';
document.body.append(root);

const palette = document.createElement('div');
palette.style.cssText = 'display:flex;flex-direction:column;gap:8px;padding:12px';
const canvas = document.createElement('div');
canvas.style.height = '420px';
root.append(palette, canvas);

const instance = render({ nodes: [], edges: [] }, canvas);
const kinds = ['Source', 'Filter', 'Sink'];

async function addNode(kind) {
  const count = instance.getModel().getNodes().length;
  await instance.getEngine().addNode({
    type: 'rect',
    position: { x: 40 + (count % 4) * 170, y: 40 + Math.floor(count / 4) * 90 },
    size: { width: 140, height: 64 },
    data: { label: kind },
  });
  instance.renderNow();
}

for (const kind of kinds) {
  const button = document.createElement('button');
  button.textContent = kind;
  button.addEventListener('click', () => { void addNode(kind); });
  palette.append(button);
}
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-node-palette',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="display:grid;grid-template-columns:160px 1fr;height:420px">
      <div style="display:flex;flex-direction:column;gap:8px;padding:12px">
        <button type="button" (click)="addNode('Source')">Source</button>
        <button type="button" (click)="addNode('Filter')">Filter</button>
        <button type="button" (click)="addNode('Sink')">Sink</button>
      </div>
      <grafloria-diagram-canvas [nodes]="nodes" [edges]="edges" style="display:block;height:100%" />
    </div>
  `,
})
export class NodePaletteComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly nodes: NodeSpec[] = [];
  readonly edges: EdgeSpec[] = [];

  async addNode(kind: string): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    const diagram = engine.getDiagram() ?? engine.createDiagram();
    const count = diagram.getNodes().length;
    await engine.addNode({
      type: 'rect',
      position: { x: 40 + (count % 4) * 170, y: 40 + Math.floor(count / 4) * 90 },
      size: { width: 140, height: 64 },
      data: { label: kind },
    });
  }
}
```
```tsx title="Qwik"
import { $, component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { NodeSpec } from '@grafloria/renderer';

export default component$(() => {
  const nodes = useSignal<NodeSpec[]>([]);
  const kinds = ['Source', 'Filter', 'Sink'];

  return (
    <div style={{ display: 'grid', gridTemplateColumns: '160px 1fr', height: '420px' }}>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', padding: '12px' }}>
        {kinds.map((kind) => (
          <button key={kind} type="button" data-kind={kind} onClick$={$((_event: Event, button: HTMLButtonElement) => {
            const selectedKind = button.dataset['kind'];
            if (!selectedKind) return;
            const count = nodes.value.length;
            nodes.value = [...nodes.value, {
              id: `palette-${count + 1}`,
              type: 'rect',
              position: { x: 40 + (count % 4) * 170, y: 40 + Math.floor(count / 4) * 90 },
              size: { width: 140, height: 64 },
              data: { label: selectedKind },
            }];
          })}>
            {kind}
          </button>
        ))}
      </div>
      <div style={{ height: '420px' }}>
        <GrafloriaFlow nodes={nodes.value} defaultEdges={[]} />
      </div>
    </div>
  );
});
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';

export function NodePalette() {
  const api = useRef<DiagramInstance | null>(null);
  const kinds = ['Source', 'Filter', 'Sink'];

  async function addNode(kind: string): Promise<void> {
    const instance = api.current;
    if (!instance) return;
    const count = instance.getModel().getNodes().length;
    await instance.getEngine().addNode({
      type: 'rect',
      position: { x: 40 + (count % 4) * 170, y: 40 + Math.floor(count / 4) * 90 },
      size: { width: 140, height: 64 },
      data: { label: kind },
    });
    instance.renderNow();
  }

  return (
    <div style={{ display: 'grid', gridTemplateColumns: '160px 1fr', height: 420 }}>
      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, padding: 12 }}>
        {kinds.map((kind) => <button key={kind} type="button" onClick={() => { void addNode(kind); }}>{kind}</button>)}
      </div>
      <div style={{ height: 420 }}>
        <GrafloriaFlow defaultNodes={[]} defaultEdges={[]} onInit={(instance) => { api.current = instance; }} />
      </div>
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';

const api = ref<DiagramInstance | null>(null);
const kinds = ['Source', 'Filter', 'Sink'];

async function addNode(kind: string): Promise<void> {
  const instance = api.value;
  if (!instance) return;
  const count = instance.getModel().getNodes().length;
  await instance.getEngine().addNode({
    type: 'rect',
    position: { x: 40 + (count % 4) * 170, y: 40 + Math.floor(count / 4) * 90 },
    size: { width: 140, height: 64 },
    data: { label: kind },
  });
  instance.renderNow();
}
</script>

<template>
  <div style="display:grid;grid-template-columns:160px 1fr;height:420px">
    <div style="display:flex;flex-direction:column;gap:8px;padding:12px">
      <button v-for="kind in kinds" :key="kind" type="button" @click="addNode(kind)">{{ kind }}</button>
    </div>
    <div style="height:420px">
      <GrafloriaFlow :default-nodes="[]" :default-edges="[]" @init="api = $event" />
    </div>
  </div>
</template>
```
:::

Click a palette button to add a labelled `rect` node. JavaScript, React and Vue call `addNode()` on the mounted instance; Angular calls `addNode()` on its active engine, and Qwik updates its controlled node array. Each addition occupies the next grid position.

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `defaultNodes` | `NodeSpec[]` | Not specified | Seeds the diagram once; the JavaScript, React and Vue samples pass an empty array. Angular and Qwik pass empty controlled node arrays. |
| `defaultEdges` | `EdgeSpec[]` | Not specified | Seeds the diagram's edges; the samples pass an empty array. |
| `onInit` / `onInit$` | `(instance: DiagramInstance) => void` | Not specified | Gives the mounted instance to the JavaScript, React and Vue palette code. Angular reads the active engine from its canvas component; Qwik uses controlled node data. |
| `addNode` config `type` | `string` | Required | Selects the node type; the sample uses `rect`. |
| `addNode` config `position` | `Point` | Required | Sets the node's top-left position in diagram coordinates. |
| `addNode` config `size` | `Size` | Optional | Sets the node's width and height. |
| `addNode` config `data` | `any` | Optional | Carries node data; `data.label` supplies the visible label in these samples. |

## Pitfalls

- If you later replace externally edited node data with `setNodes()` or `loadText()`, those calls reconcile rather than rebuild: ids that remain keep their live objects. Clear the current edges and nodes first, then apply the edited data. See [Edit and copy nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/edit-and-copy-nodes) for node-data workflows.
- This palette uses the built-in `rect` node and a data label. For custom-rendered nodes, follow [Create custom nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/create-custom-nodes).

## See it running

The [Drag & drop demo](https://grafloria.com/demos/interaction/drag-and-drop.html) shows a drag-and-drop palette whose nodes land at the drop point. For categorized, searchable built-in shapes, see the [Stencil palette demo](https://grafloria.com/demos/diagrams/stencil-palette.html).

## Related

- [JavaScript quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/javascript-quick-start)
- [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start)
- [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start)
- [Angular quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/angular-quick-start)
- [Qwik quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/qwik-quick-start)
- [The instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow)
- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history)

<!-- source: edit-and-copy-nodes.md -->

# Edit, copy, and remove nodes

Use the canvas for the user's selection and the instance's engine for command-based edits. This lets you edit a node label in place, copy or duplicate selected nodes, paste clipboard contents, and remove selected nodes without rebuilding the diagram.

## Edit a label in place

Enable in-place editing on the mounted instance. A double-click opens an editor on the node label; Enter or blur commits the new label as one undoable step, while Escape abandons it. The JavaScript, Angular, React, and Vue examples also add toolbar actions for copy, paste, duplicate, and delete; the Qwik example follows the mounted-canvas pattern and uses its keyboard shortcuts for clipboard actions.

For the typed node data and mounting patterns across JavaScript, Angular, React, and Vue, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows). This page adds the engine actions for editing, copying, pasting, duplicating, and deleting selected nodes; click a node before using Copy, Duplicate, or Delete. Paste uses the engine clipboard rather than the operating system clipboard.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import type { NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'draft', position: { x: 80, y: 110 }, size: { width: 150, height: 60 }, label: 'Draft' },
  { id: 'review', position: { x: 360, y: 110 }, size: { width: 150, height: 60 }, label: 'Review' },
];

const root = document.createElement('main');
root.style.height = '620px';
document.body.append(root);
const toolbar = document.createElement('div');
const canvas = document.createElement('div');
canvas.style.height = '570px';
root.append(toolbar, canvas);

const instance = render({ nodes }, canvas);
instance.getEngine().setInteractionConfig({ enableInPlaceTextEdit: true });

async function act(action: 'copy' | 'paste' | 'duplicate' | 'delete'): Promise<void> {
  const engine = instance.getEngine();
  const hasSelection = instance.getModel().getSelectedNodes().length > 0;
  if (action === 'copy' && hasSelection) await engine.copy();
  if (action === 'paste' && engine.hasClipboardData()) await engine.paste();
  if (action === 'duplicate' && hasSelection) await engine.duplicate();
  if (action === 'delete' && hasSelection) await engine.deleteSelection();
  instance.renderNow();
}

for (const action of ['copy', 'paste', 'duplicate', 'delete'] as const) {
  const button = document.createElement('button');
  button.textContent = action[0].toUpperCase() + action.slice(1);
  button.addEventListener('click', () => { void act(action); });
  toolbar.append(button);
}
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="height:620px">
      <button type="button" (click)="copy()">Copy</button>
      <button type="button" (click)="paste()">Paste</button>
      <button type="button" (click)="duplicate()">Duplicate</button>
      <button type="button" (click)="deleteSelection()">Delete</button>
      <grafloria-diagram-canvas [(nodes)]="nodes"
        style="display:block;height:570px" />
    </div>
  `,
})
export class NodeEditorComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = [
    { id: 'draft', position: { x: 80, y: 110 }, size: { width: 150, height: 60 }, label: 'Draft' },
    { id: 'review', position: { x: 360, y: 110 }, size: { width: 150, height: 60 }, label: 'Review' },
  ];
  ngAfterViewInit(): void {
    this.canvas().activeEngine()?.setInteractionConfig({ enableInPlaceTextEdit: true });
  }

  async copy(): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (engine && engine.getDiagram()?.getSelectedNodes().length) await engine.copy();
  }

  async paste(): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (engine?.hasClipboardData()) await engine.paste();
  }

  async duplicate(): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (engine && engine.getDiagram()?.getSelectedNodes().length) await engine.duplicate();
  }

  async deleteSelection(): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (engine && engine.getDiagram()?.getSelectedNodes().length) await engine.deleteSelection();
  }
}
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'draft', position: { x: 80, y: 110 }, size: { width: 150, height: 60 }, label: 'Draft' },
  { id: 'review', position: { x: 360, y: 110 }, size: { width: 150, height: 60 }, label: 'Review' },
];

export default function NodeEditor() {
  const instance = useRef<DiagramInstance | null>(null);

  async function act(action: 'copy' | 'paste' | 'duplicate' | 'delete'): Promise<void> {
    const api = instance.current;
    if (!api) return;
    const engine = api.getEngine();
    const hasSelection = api.getModel().getSelectedNodes().length > 0;
    if (action === 'copy' && hasSelection) await engine.copy();
    if (action === 'paste' && engine.hasClipboardData()) await engine.paste();
    if (action === 'duplicate' && hasSelection) await engine.duplicate();
    if (action === 'delete' && hasSelection) await engine.deleteSelection();
    api.renderNow();
  }

  return (
    <div style={{ height: '620px' }}>
      <button type="button" onClick={() => { void act('copy'); }}>Copy</button>
      <button type="button" onClick={() => { void act('paste'); }}>Paste</button>
      <button type="button" onClick={() => { void act('duplicate'); }}>Duplicate</button>
      <button type="button" onClick={() => { void act('delete'); }}>Delete</button>
      <div style={{ height: '570px' }}>
        <GrafloriaFlow defaultNodes={nodes} onInit={(api) => {
          instance.current = api;
          api.getEngine().setInteractionConfig({ enableInPlaceTextEdit: true });
        }} />
      </div>
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'draft', position: { x: 80, y: 110 }, size: { width: 150, height: 60 }, label: 'Draft' },
  { id: 'review', position: { x: 360, y: 110 }, size: { width: 150, height: 60 }, label: 'Review' },
];
const instance = ref<DiagramInstance | null>(null);

function onInit(api: DiagramInstance): void {
  instance.value = api;
  api.getEngine().setInteractionConfig({ enableInPlaceTextEdit: true });
}

async function copy(): Promise<void> {
  const api = instance.value;
  if (api && api.getModel().getSelectedNodes().length > 0) { await api.getEngine().copy(); api.renderNow(); }
}
async function paste(): Promise<void> {
  const api = instance.value;
  if (api?.getEngine().hasClipboardData()) { await api.getEngine().paste(); api.renderNow(); }
}
async function duplicate(): Promise<void> {
  const api = instance.value;
  if (api && api.getModel().getSelectedNodes().length > 0) { await api.getEngine().duplicate(); api.renderNow(); }
}
async function deleteSelection(): Promise<void> {
  const api = instance.value;
  if (api && api.getModel().getSelectedNodes().length > 0) { await api.getEngine().deleteSelection(); api.renderNow(); }
}
</script>

<template>
  <div style="height:620px">
    <button type="button" @click="copy">Copy</button>
    <button type="button" @click="paste">Paste</button>
    <button type="button" @click="duplicate">Duplicate</button>
    <button type="button" @click="deleteSelection">Delete</button>
    <div style="height:570px">
      <GrafloriaFlow :default-nodes="nodes" @init="onInit" />
    </div>
  </div>
</template>
```
:::

On the canvas, double-click Draft or Review to edit its label. Enter and blur commit the edit; Escape cancels it. Click a node to select it, then use Copy followed by Paste to create a separate node; repeat Paste to place further copies at cascading offsets. Duplicate creates a copy directly from the selection, and Delete removes the selected node. The JavaScript, Angular, React, and Vue examples expose these actions as toolbar buttons that run only when their required selection or clipboard content exists. Command-based changes participate in the engine's undo history; ⌘Z or Ctrl+Z undoes the last edit.

## Copy and paste versus duplicate

`copy()` snapshots the current selection to the engine clipboard; `paste()` creates new entities from that clipboard. `duplicate()` creates copies directly from the current selection. Both operations create nodes with new IDs and positions, so editing one copy does not change its source. Paste can be repeated from the same clipboard contents. These are engine operations, not browser clipboard integration.

| Operation | Option | Type | Default | Effect |
| --- | --- | --- | --- | --- |
| `copy()` | `includeGroups` | `boolean` | `false` | Includes groups containing selected nodes. |
| `copy()` | `includeLinks` | `boolean` | `true` | Includes links between copied nodes. |
| `paste()` | `offset` | [`Point`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-a-t#point) | First paste: `{ x: 20, y: 20 }`; later pastes cascade | Shifts pasted entities to a new position. |
| `paste()` | `selectPasted` | `boolean` | `true` | Selects the pasted entities. |
| `duplicate()` | `offset` | [`Point`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-a-t#point) | `{ x: 20, y: 20 }` | Shifts duplicated entities to a new position. |
| `duplicate()` | `selectDuplicated` | `boolean` | `true` | Selects the duplicated entities. |
| `deleteSelection()` | `deleteChildren` | `boolean` | `true` | Recursively deletes child nodes. |
| `deleteSelection()` | `deleteLinks` | `boolean` | `true` | Removes links before deleting nodes; links attached to a removed node are removed either way. |

The default paste offset starts at 20 pixels down and right and advances for subsequent pastes of the same clipboard contents. The copy and paste demo shows the rendered result: each paste has a different ID and position, and moving one copy leaves the others in place.

Try [Copy / paste](https://grafloria.com/demos/interaction/copy-paste.html) while you click Original, copy it, and paste more than once. The demo source is [copy-paste.html](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/copy-paste.html).

## Remove selected nodes

`deleteSelection()` acts on the current selection. When you remove a node, its connected links are removed too, so the diagram does not retain dangling edges. The deletion is undoable with the engine's command history. This is ordinary deletion; reconnecting neighbors across a removed middle node is an extra behavior implemented by the separate delete-middle-node demo, not an effect of `deleteSelection()` itself.

See [Delete a middle node](https://grafloria.com/demos/nodes/delete-middle-node.html) for the custom variant that adds an undoable A-to-C bridge after removing B; its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/nodes/delete-middle-node.html) explicitly reads the neighbors before deleting.

## Add a context menu

A context menu is host UI: the [context-menu demo](https://grafloria.com/demos/interaction/context-menu.html) builds a Rename / Duplicate / Delete menu, listens for a real `contextmenu` event, anchors its menu at the pointer, and calls model or engine operations for the targeted node. Its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/context-menu.html) is a starting point when you need that interaction rather than the toolbar used above.

For plain JavaScript, the same task is also shown in the [edit-label demo](https://grafloria.com/demos/nodes/edit-label.html), where double-click opens the editor and Enter commits the label. See its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/nodes/edit-label.html).

## Options that affect the edit

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `enableInPlaceTextEdit` | `boolean` | `false` | Enables double-click editing of node labels. |
| `offset` on `paste()` | `Point` | First paste: `{ x: 20, y: 20 }`; later pastes cascade | Sets the position shift applied to pasted entities. Pass an explicit point to control placement. |
| `offset` on `duplicate()` | `Point` | `{ x: 20, y: 20 }` | Sets the position shift applied to duplicated entities. |
| `selectPasted` | `boolean` | `true` | Selects the pasted entities. |
| `selectDuplicated` | `boolean` | `true` | Selects the duplicated entities. |

## Pitfalls

- The engine clipboard is separate from `navigator.clipboard`; connect it to the operating-system clipboard yourself if cross-tab or system paste is required.
- In-place label editing is opt-in. Leave `enableInPlaceTextEdit` off if your app handles the node's double-click event with its own editor.
- Do not put user-supplied node data into `innerHTML` in a custom renderer. Use `textContent` for untrusted values to avoid interpreting them as markup. See [Create custom nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/create-custom-nodes).
- For a custom delete that reconnects neighboring nodes, use the delete-middle-node demo's separate read-neighbors, remove, and bridge steps; node deletion alone does not create that bridge.

## Related

- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) explains how edits enter the undo stack.
- [Undo and redo edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/undo-and-redo) covers the user-facing history controls.
- [Resize and size nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/resize-and-size-nodes) covers custom node rendering and registration timing.

<!-- source: undo-and-redo.md -->

# Undo and redo diagram edits

Use the diagram's command history when users need to reverse a gesture or when your feature edits the graph on their behalf. A drag is one undoable step; your own toolbar action can use that same history.

## Add undo and redo controls

The canvas already handles `Ctrl+Z` / `⌘Z` for undo and `Ctrl+Y` / `⌘⇧Z` for redo. To add buttons, keep the live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance) and call `undo()` or `redo()` on its engine. In Angular, [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent) exposes those operations directly.

Each sample starts with two nodes. Drag either node and undo to return it to the start of the drag; redo reapplies the move. In JavaScript, Angular, Vue, and React, **Add node** adds a rectangle through the engine; Undo removes it and Redo restores it. The Qwik sample demonstrates drag undo with the built-in keyboard shortcuts rather than a custom **Add node** control.

[Live drag-and-undo demo](https://grafloria.com/demos/interaction/drag-undo.html). Its canvas starts with two nodes; drag one before trying undo.

### JavaScript, Angular, Qwik, Vue, and React

Each example is a mounted canvas with a real height. In JavaScript, mount with [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core); use `getEngine().addNode()` for a programmatic addition. The typed sample data uses [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec); Angular controlled arrays can also carry live [`NodeModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-nodemodel) and [`LinkModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-linkmodel) instances. For React use [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react); for Vue use [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue); for Qwik use [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik). React and Vue acquire the instance through their component callback. Angular obtains the canvas with `viewChild.required()` and calls `activeEngine().addNode()` for programmatic edits, while its undo and redo buttons call the canvas methods directly. The Qwik sample uses the default-data component and the built-in keyboard shortcuts.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

/** @type {import('@grafloria/renderer').NodeSpec[]} */
const nodes = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 160, height: 70 }, label: 'Drag, then undo' },
  { id: 'b', position: { x: 360, y: 180 }, size: { width: 160, height: 70 }, label: 'Every step counts' },
];
/** @type {import('@grafloria/renderer').EdgeSpec[]} */
const edges = [{ id: 'e1', source: 'a', target: 'b' }];

const wrapper = document.createElement('div');
wrapper.style.height = '460px';
document.body.append(wrapper);
const toolbar = document.createElement('div');
wrapper.append(toolbar);
const host = document.createElement('div');
host.style.height = '420px';
wrapper.append(host);
const instance = render({ nodes, edges }, host);

let nextSuggestion = 1;
async function addSuggestion() {
  const number = nextSuggestion++;
  await instance.getEngine().addNode({
    type: 'rect',
    position: { x: 220 + (number - 1) * 24, y: 300 },
    size: { width: 160, height: 70 },
  });
}

/** @param {string} label @param {() => void} action */
function addButton(label, action) {
  const button = document.createElement('button');
  button.textContent = label;
  button.addEventListener('click', action);
  toolbar.append(button);
}

addButton('Add node', () => { void addSuggestion(); });
addButton('Undo', () => { void instance.getEngine().undo(); });
addButton('Redo', () => { void instance.getEngine().redo(); });
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { LinkModel, NodeModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-undo-redo',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="height:460px">
      <div>
        <button type="button" (click)="addSuggestion()">Add node</button>
        <button type="button" (click)="undo()">Undo</button>
        <button type="button" (click)="redo()">Redo</button>
      </div>
      <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
        style="display:block;height:420px" />
    </div>
  `,
})
export class UndoRedoComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: readonly (NodeSpec | NodeModel)[] | undefined = [
    { id: 'a', position: { x: 80, y: 80 }, size: { width: 160, height: 70 }, label: 'Drag, then undo' },
    { id: 'b', position: { x: 360, y: 180 }, size: { width: 160, height: 70 }, label: 'Every step counts' },
  ];
  edges: readonly (EdgeSpec | LinkModel)[] | undefined = [{ id: 'e1', source: 'a', target: 'b' }];
  private nextSuggestion = 1;

  addSuggestion(): void {
    const number = this.nextSuggestion++;
    const engine = this.canvas().activeEngine();
    if (engine) void engine.addNode({
      type: 'rect',
      position: { x: 220 + (number - 1) * 24, y: 300 },
      size: { width: 160, height: 70 },
    });
  }

  undo(): void { void this.canvas().undo(); }
  redo(): void { void this.canvas().redo(); }
}
```
```tsx title="Qwik"
import { component$ } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 160, height: 70 }, label: 'Drag, then undo' },
  { id: 'b', position: { x: 360, y: 180 }, size: { width: 160, height: 70 }, label: 'Every step counts' },
];
const edges: EdgeSpec[] = [];

export default component$(() => (
  <div style={{ height: '460px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
  </div>
));
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 160, height: 70 }, label: 'Drag, then undo' },
  { id: 'b', position: { x: 360, y: 180 }, size: { width: 160, height: 70 }, label: 'Every step counts' },
];
const edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];
let instance: DiagramInstance | null = null;
let nextSuggestion = 1;

function onInit(diagramInstance: DiagramInstance): void { instance = diagramInstance; }
function addSuggestion(): void {
  const number = nextSuggestion++;
  const engine = instance?.getEngine();
  if (engine) void engine.addNode({
    type: 'rect',
    position: { x: 220 + (number - 1) * 24, y: 300 },
    size: { width: 160, height: 70 },
  });
}
function undo(): void { const engine = instance?.getEngine(); if (engine) void engine.undo(); }
function redo(): void { const engine = instance?.getEngine(); if (engine) void engine.redo(); }
</script>

<template>
  <div style="height:460px">
    <div>
      <button type="button" @click="addSuggestion">Add node</button>
      <button type="button" @click="undo">Undo</button>
      <button type="button" @click="redo">Redo</button>
    </div>
    <div style="height:420px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
    </div>
  </div>
</template>
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 160, height: 70 }, label: 'Drag, then undo' },
  { id: 'b', position: { x: 360, y: 180 }, size: { width: 160, height: 70 }, label: 'Every step counts' },
];
const edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];

export default function UndoRedoExample() {
  const instance = useRef<DiagramInstance | null>(null);
  const nextSuggestion = useRef(1);

  function addSuggestion(): void {
    const number = nextSuggestion.current++;
    const engine = instance.current?.getEngine();
    if (engine) void engine.addNode({
      type: 'rect',
      position: { x: 220 + (number - 1) * 24, y: 300 },
      size: { width: 160, height: 70 },
    });
  }

  return (
    <div style={{ height: '460px' }}>
      <div>
        <button type="button" onClick={addSuggestion}>Add node</button>
        <button type="button" onClick={() => { const engine = instance.current?.getEngine(); if (engine) void engine.undo(); }}>Undo</button>
        <button type="button" onClick={() => { const engine = instance.current?.getEngine(); if (engine) void engine.redo(); }}>Redo</button>
      </div>
      <div style={{ height: '420px' }}>
        <GrafloriaFlow
          defaultNodes={nodes}
          defaultEdges={edges}
          onInit={(diagramInstance) => { instance.current = diagramInstance; }}
        />
      </div>
    </div>
  );
}
```
:::

## What the calls change

`undo()` and `redo()` return promises because a command can do asynchronous work. Await them when the next step depends on the history operation finishing. After an undo, the engine's model contains the reverted state. Controlled React, Angular, and Vue bindings reflect model changes back to application data; these React and Vue examples use initial `defaultNodes` and `defaultEdges` instead.

For programmatic edits, use command-backed operations when users must be able to undo them; setup and restoration stay outside history. See [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the instance, engine, and model roles.

| Input | Type | Default | Effect |
| --- | --- | --- | --- |
| `defaultNodes` | [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec) `[]` | Not stated | Initial nodes for React and Vue. |
| `defaultEdges` | [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec) `[]` | Not stated | Initial edges for React and Vue. |
| `nodes` | `readonly (NodeSpec \| NodeModel)[] \| undefined` | `undefined` | Angular's controlled node data; two-way binding reflects canvas edits. |
| `edges` | `readonly (EdgeSpec \| LinkModel)[] \| undefined` | `undefined` | Angular's controlled edge data; two-way binding reflects canvas edits. |

## Pitfalls

- Do not use model-level mutations for a feature action that users need to undo. Model operations used to set up, load, or synchronize a diagram stay out of the history.
- Await engine operations before starting a dependent operation. The command methods are asynchronous.
- A drag is one history step, not one step per pointer movement. Undo returns the node to the position where that drag started.

## Related

- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) explains commands and the shared history in more depth.
- [Synchronize diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/synchronize-diagrams) covers collaboration between diagrams.
- [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start), [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start), [Angular quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/angular-quick-start), and [Qwik quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/qwik-quick-start) show the surrounding framework setup.
- [Collaboration-aware undo demo](https://grafloria.com/demos/interaction/undo-redo.html) shows how a peer's undo applies to that peer's own edits.

<!-- source: create-custom-nodes.md -->

# Create custom nodes

Use a custom node when a node needs content beyond Grafloria's built-in label and shape. Declare nodes as [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec) values and connect them with [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) edges. The framework bindings put your own component or template inside the node; the diagram still owns its geometry, hit-testing, selection and connections. The plain JavaScript example uses a structured HTML body inside an SVG `foreignObject`.

## 1. Render content inside a node

Give each node a `type`, a real `size`, and data for its content. Then connect node IDs with edges. In React, register a component for the type and set `custom: true`; Vue and Angular use the matching type declaration to opt into framework templates. Plain JavaScript and Qwik can use the structured `metadata.html` body shown below.

The sample renders two connected service cards. Each framework's node body stays inside its box as the diagram moves and zooms; the link remains attached to the node geometry. The HTML-node demo shows a card with a heading, progress line and badge inside its node.

The examples use these node fields:

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `type` | `string` | `'rect'` | Selects the custom-node type rendered by a matching component, slot or template. |
| `size` | `{ width: number; height: number }` | Not specified | Sets the node box that contains the custom content. |
| `data` | `Record<string, any>` | Not specified | Carries the node payload to custom components and templates. |
| `custom` | `boolean` | Not specified | On React nodes, `true` routes the node through the HTML layer. Vue and Angular also opt in from a matching declared type. |

### Framework examples

Use [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) in the browser to mount a data spec. For structured HTML, put a sanitized content tree in `metadata.html.content`; the body renders inside the node's `foreignObject`, so it moves with the node group. The code creates a host with a real height.

Angular's [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) and exact `grafloriaNode` template, Qwik's [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow), React's [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow), and Vue's [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow) and named slot are the framework front doors. Angular and Vue opt matching template types in automatically; React uses both a `nodeTypes` entry and `custom: true`. In Qwik, mount the flow with Qwik's renderer and pass nodes with structured HTML metadata.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const nodes = [
  {
    id: 'api',
    position: { x: 80, y: 100 },
    size: { width: 210, height: 100 },
    metadata: {
      html: {
        content: {
          tag: 'div',
          className: 'service-card',
          children: [
            { tag: 'strong', text: 'API gateway' },
            { tag: 'span', className: 'status', text: 'Healthy' },
          ],
        },
      },
    },
  },
  {
    id: 'worker',
    position: { x: 400, y: 100 },
    size: { width: 210, height: 100 },
    metadata: {
      html: {
        content: {
          tag: 'div',
          className: 'service-card',
          children: [
            { tag: 'strong', text: 'Order worker' },
            { tag: 'span', className: 'status', text: 'Running' },
          ],
        },
      },
    },
  },
];

const edges = [{ id: 'api-worker', source: 'api', target: 'worker' }];
const target = document.createElement('div');
target.style.height = '420px';
target.style.width = '100%';
target.id = 'diagram';
document.body.append(target);

const style = document.createElement('style');
style.textContent = '#diagram .service-card { font: 14px/1.4 system-ui, sans-serif; padding: 12px; } #diagram .service-card strong { display: block; } #diagram .service-card .status { color: #059669; font-size: 12px; }';
document.head.append(style);

const instance = render({ nodes, edges }, target);
instance.fitView();
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaNodeDefDirective } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-board',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaNodeDefDirective],
  template: `
    <grafloria-diagram-canvas [nodes]="nodes" [edges]="edges"
      style="display:block; height:420px">
      <ng-template grafloriaNode="service" let-data="data">
        <div class="service-card">
          <strong>{{ data['name'] }}</strong>
          <span>{{ data['status'] }}</span>
        </div>
      </ng-template>
    </grafloria-diagram-canvas>
  `,
  styles: [`.service-card { height: 100%; box-sizing: border-box; padding: 12px;
    border: 1px solid #94a5f0; border-radius: 10px; background: white; }
    .service-card strong, .service-card span { display: block; }
    .service-card span { color: #059669; font-size: 12px; }`],
})
export class BoardComponent {
  nodes: NodeSpec[] = [
    { id: 'api', type: 'service', position: { x: 80, y: 100 }, size: { width: 210, height: 100 }, data: { name: 'API gateway', status: 'Healthy' } },
    { id: 'worker', type: 'service', position: { x: 400, y: 100 }, size: { width: 210, height: 100 }, data: { name: 'Order worker', status: 'Running' } },
  ];
  edges: EdgeSpec[] = [{ id: 'api-worker', source: 'api', target: 'worker' }];
}
```
```tsx title="Qwik"
import { render as renderQwik } from '@builder.io/qwik';
import { GrafloriaFlow, type EdgeSpec, type NodeSpec } from '@grafloria/qwik';

const nodes: NodeSpec[] = [
  {
    id: 'api',
    position: { x: 80, y: 100 },
    size: { width: 210, height: 100 },
    metadata: {
      html: {
        content: {
          tag: 'div',
          children: [
            { tag: 'strong', text: 'API gateway' },
            { tag: 'span', text: 'Healthy' },
          ],
        },
      },
    },
  },
  {
    id: 'worker',
    position: { x: 400, y: 100 },
    size: { width: 210, height: 100 },
    metadata: {
      html: {
        content: {
          tag: 'div',
          children: [
            { tag: 'strong', text: 'Order worker' },
            { tag: 'span', text: 'Running' },
          ],
        },
      },
    },
  },
];
const edges: EdgeSpec[] = [{ id: 'api-worker', source: 'api', target: 'worker' }];

const target = typeof document === 'undefined' ? null : document.createElement('div');
if (target) {
  target.style.height = '420px';
  document.body.append(target);
  void renderQwik(target, <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView />);
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeProps, NodeSpec, NodeTypes } from '@grafloria/react';

function ServiceNode({ id, selected }: NodeProps<never>) {
  return (
    <div style={{
      boxSizing: 'border-box',
      width: '100%',
      height: '100%',
      padding: '12px',
      border: selected ? '2px solid #3b52d9' : '1px solid #94a5f0',
      borderRadius: 10,
      background: '#fff',
      font: '14px/1.4 system-ui, sans-serif',
    }}>
      <strong>{id}</strong>
      <div>Service node</div>
    </div>
  );
}

const nodeTypes: NodeTypes = { service: ServiceNode };
const nodes: NodeSpec[] = [
  { id: 'api', type: 'service', custom: true, position: { x: 80, y: 100 }, size: { width: 210, height: 100 } },
  { id: 'worker', type: 'service', custom: true, position: { x: 400, y: 100 }, size: { width: 210, height: 100 } },
];
const edges: EdgeSpec[] = [{ id: 'api-worker', source: 'api', target: 'worker' }];

export function Board() {
  return (
    <div style={{ height: '420px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} nodeTypes={nodeTypes} fitView />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type EdgeSpec, type NodeSpec } from '@grafloria/vue';

const nodes: NodeSpec[] = [
  { id: 'api', type: 'service', position: { x: 80, y: 100 }, size: { width: 210, height: 100 }, data: { name: 'API gateway', status: 'Healthy' } },
  { id: 'worker', type: 'service', position: { x: 400, y: 100 }, size: { width: 210, height: 100 }, data: { name: 'Order worker', status: 'Running' } },
];
const edges: EdgeSpec[] = [{ id: 'api-worker', source: 'api', target: 'worker' }];
</script>

<template>
  <div style="height: 420px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" fit-view>
      <template #node-service="{ data }">
        <div class="service-card">
          <strong>{{ data['name'] }}</strong>
          <span>{{ data['status'] }}</span>
        </div>
      </template>
    </GrafloriaFlow>
  </div>
</template>

<style>
.service-card { box-sizing: border-box; height: 100%; padding: 12px;
  border: 1px solid #94a5f0; border-radius: 10px; background: white; }
.service-card strong, .service-card span { display: block; }
.service-card span { color: #059669; font-size: 12px; }
</style>
```
:::

In plain JavaScript, `render()` returns the mounted instance and `fitView()` frames both cards and their connecting edge. Grafloria sanitizes the structured tree rather than inserting it as raw HTML.

Angular renders the template with the node's `data` payload inside the sized canvas. Read payload keys with index syntax because the template context uses `Record<string, unknown>`. The `GrafloriaNodeDefDirective` import is required for `grafloriaNode` to match.

Qwik's renderer mounts the flow in the browser when `document` exists. The flow shows the two cards from their structured HTML trees and connects them with the edge.

React renders a custom component for both nodes; each card shows its node ID and a selection-aware border, and each React spec sets `custom: true`.

Vue renders the named slot for each matching node and exposes its data in the slot scope. Both service cards fill their node boxes while the edge connects them.

## 2. Keep the content within the node box

Set `size` on each node; the diagram uses that geometry to size and position the custom-content host. Make the root element fill the box with `height: 100%` and `box-sizing: border-box`, so padding and borders fit within the node's hit area. Give the canvas parent a real height as well.

In React, a missing or mismatched `custom: true` flag or `nodeTypes` key means the custom component does not render. In Vue and Angular, match the type exactly to the named slot or template directive. For Angular, include `GrafloriaNodeDefDirective` in the component's `imports`; without it the `grafloriaNode` template is ignored.

The JavaScript `metadata.html` route is sanitized and structured. Supply element descriptions and text values rather than interpolating untrusted values into raw HTML.

## 3. See the nodes running

- [Live HTML-node demo](https://grafloria.com/demos/nodes/html-nodes.html) — structured HTML rendered inside a node.
- [Custom-node demo](https://grafloria.com/demos/nodes/custom-nodes.html) — built-in terminal, predefined-process and document shapes connected in one diagram.
- [Custom-node demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/nodes/custom-nodes.html)

If you need a different built-in silhouette or fill rather than custom content, use the per-node `shape` option; the custom-node demo shows terminal, predefined-process and document silhouettes. For node sizing and geometry, see [Resize and size nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/resize-and-size-nodes).

<!-- source: resize-and-size-nodes.md -->

# Resize and size nodes

Set a node's starting dimensions, constrain a user's resize gesture, or let the renderer fit a node to its label. This page focuses on node sizing; for mounting patterns and framework-specific data bindings, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows). These steps cover JavaScript, Angular, React, and Vue; the Qwik binding is outside this page's scope.

## Mount nodes with sizes and sizing rules

The example renders four nodes: one with a declared starting size, one whose resize gesture has minimums and maximums, one with a locked aspect ratio, and one that opts into content-aware sizing. Give the canvas a real height so the rendered diagram has room to appear.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '700px';
document.body.append(host);

const diagram = render({
  nodes: [
    {
      id: 'sized',
      position: { x: 120, y: 80 },
      size: { width: 180, height: 90 },
      label: 'Declared size: 180 × 90',
    },
    {
      id: 'resizable',
      position: { x: 120, y: 220 },
      size: { width: 160, height: 100 },
      label: 'Resize me: 80–260 wide',
      metadata: {
        sizing: {
          minWidth: 80,
          minHeight: 60,
          maxWidth: 260,
          maxHeight: 200,
        },
      },
    },
    {
      id: 'ratio',
      position: { x: 420, y: 220 },
      size: { width: 160, height: 100 },
      label: 'Aspect ratio stays at 1.6',
      metadata: { sizing: { aspectLock: true } },
    },
    {
      id: 'auto',
      position: { x: 120, y: 360 },
      size: { width: 60, height: 36 },
      label: 'This long label grows beyond the declared sixty-pixel width',
      metadata: { sizing: { auto: true, padding: 10 } },
    },
  ],
  edges: [],
}, host);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import type { LinkModel, NodeModel } from '@grafloria/engine';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      style="display:block; height:700px" />
  `,
})
export class AppComponent {
  nodes: readonly (NodeSpec | NodeModel)[] | undefined = [
    {
      id: 'sized',
      position: { x: 120, y: 80 },
      size: { width: 180, height: 90 },
      label: 'Declared size: 180 × 90',
    },
    {
      id: 'resizable',
      position: { x: 120, y: 220 },
      size: { width: 160, height: 100 },
      label: 'Resize me: 80–260 wide',
      metadata: {
        sizing: {
          minWidth: 80,
          minHeight: 60,
          maxWidth: 260,
          maxHeight: 200,
        },
      },
    },
    {
      id: 'ratio',
      position: { x: 420, y: 220 },
      size: { width: 160, height: 100 },
      label: 'Aspect ratio stays at 1.6',
      metadata: { sizing: { aspectLock: true } },
    },
    {
      id: 'auto',
      position: { x: 120, y: 360 },
      size: { width: 60, height: 36 },
      label: 'This long label grows beyond the declared sixty-pixel width',
      metadata: { sizing: { auto: true, padding: 10 } },
    },
  ];
  edges: readonly (EdgeSpec | LinkModel)[] | undefined = [];
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  {
    id: 'sized',
    position: { x: 120, y: 80 },
    size: { width: 180, height: 90 },
    label: 'Declared size: 180 × 90',
  },
  {
    id: 'resizable',
    position: { x: 120, y: 220 },
    size: { width: 160, height: 100 },
    label: 'Resize me: 80–260 wide',
    metadata: {
      sizing: {
        minWidth: 80,
        minHeight: 60,
        maxWidth: 260,
        maxHeight: 200,
      },
    },
  },
  {
    id: 'ratio',
    position: { x: 420, y: 220 },
    size: { width: 160, height: 100 },
    label: 'Aspect ratio stays at 1.6',
    metadata: { sizing: { aspectLock: true } },
  },
  {
    id: 'auto',
    position: { x: 120, y: 360 },
    size: { width: 60, height: 36 },
    label: 'This long label grows beyond the declared sixty-pixel width',
    metadata: { sizing: { auto: true, padding: 10 } },
  },
];
const edges: EdgeSpec[] = [];

export function App() {
  return (
    <div style={{ height: 700 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  {
    id: 'sized',
    position: { x: 120, y: 80 },
    size: { width: 180, height: 90 },
    label: 'Declared size: 180 × 90',
  },
  {
    id: 'resizable',
    position: { x: 120, y: 220 },
    size: { width: 160, height: 100 },
    label: 'Resize me: 80–260 wide',
    metadata: {
      sizing: {
        minWidth: 80,
        minHeight: 60,
        maxWidth: 260,
        maxHeight: 200,
      },
    },
  },
  {
    id: 'ratio',
    position: { x: 420, y: 220 },
    size: { width: 160, height: 100 },
    label: 'Aspect ratio stays at 1.6',
    metadata: { sizing: { aspectLock: true } },
  },
  {
    id: 'auto',
    position: { x: 120, y: 360 },
    size: { width: 60, height: 36 },
    label: 'This long label grows beyond the declared sixty-pixel width',
    metadata: { sizing: { auto: true, padding: 10 } },
  },
];
const edges: EdgeSpec[] = [];
</script>

<template>
  <div style="height:700px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" />
  </div>
</template>
```
:::

The first box starts at its declared 180 × 90 size. Select the constrained box to show the renderer's corner and edge resize handles, then drag a handle: its dimensions stay within the declared limits. The adjacent node holds its initial 1.6 width-to-height ratio while you resize it. The bottom node opts into content-aware sizing, so its long label expands it beyond its declared 60-pixel width. The non-auto node remains at its declared dimensions until a user resizes it.

## Choose the sizing fields

Put per-node constraints in `metadata.sizing`. The renderer applies the same constraints to the interactive resize and content-aware sizing paths.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `size` | `{ width: number; height: number }` | No default stated | Declares a node's width and height in its [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec). |
| `metadata.sizing.auto` | `boolean` | Off unless `true` | Opts that node into content-aware sizing to fit its label. |
| `metadata.sizing.minWidth`, `minHeight` | `number` | No per-node constraint; the resizer's global floor still applies | Sets the node's minimum width or height during resizing and auto-sizing. |
| `metadata.sizing.maxWidth`, `maxHeight` | `number` | No per-node limit | Sets the node's maximum width or height during resizing and auto-sizing. |
| `metadata.sizing.aspectLock` | `boolean \| number` | Unlocked | `true` locks to the node's current width-to-height ratio; a positive number locks to that explicit ratio. |
| `metadata.sizing.padding` | `number` | `8` px | Reserves space around the label when auto-sizing. |

The selected-node handles appear for one selected, resizable, unlocked node. A multi-node selection does not provide proportional resize handles. For automatic fitting, only nodes with `metadata.sizing.auto: true` grow; `padding` defaults to 8 pixels unless you set it, as the example does. The auto-sized node's measured dimensions update on the renderer's frame, and the sizing pass uses the same min/max limits and aspect lock as dragging.

## Watch the demos

- [Auto-sizing nodes](https://grafloria.com/demos/nodes/auto-sizing.html) shows an opted-in node fitting its label and growing again when the label changes.
- [Node resize gesture](https://grafloria.com/demos/nodes/node-resize-gesture.html) shows the built-in handles, per-handle cursors, and live min/max/aspect constraints.
- [Node resizer](https://grafloria.com/demos/nodes/node-resizer.html) contrasts the selected-node resizer with a custom resize control.

## Pitfalls

- Register a custom node renderer before mounting the diagram. If a node's type has no renderer when its host mounts, that host stays empty; registering later does not back-fill it. A custom renderer runs at mount, not as a data binding, so update the DOM you own or use a component with its own reactive source when its content must change.
- Give the canvas a parent with a resolved height. A canvas inside a zero-height wrapper has no visible area to draw into.

## Related

- [Lay out diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams)
- [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows)

<!-- source: configure-ports.md -->

# Configure ports

Declare connection points on each node to control their glyphs, labels, shared layout, and data-type rules; the same node specs work across Grafloria's framework bindings.

## When to use declared ports

Use declared ports when a node needs named inputs and outputs, more than the four default connection points, or visible distinctions between connection types. The graph data belongs to the diagram model; the framework binding converts your node specs into live models, and the instance connects the rendered canvas to engine behavior.

Each node can declare a `ports` array on its [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec). Give each port an id, then add a `shape`, a `label`, a `group`, or a `dataType` as needed. Nodes without `ports` keep their four deterministic default ports.

## Declare and mount the ports

The samples below all render the same small data-flow diagram: a `Source` node has number and string outputs, and a `Convert` node has matching inputs. Both nodes arrange their ports in named side groups. The port glyphs have different shapes and labels; the initial number-to-number link is present in every sample. A registered type palette adds type colours and can declare compatibility beyond exact type-name matches.

The JavaScript and framework mounting patterns are covered in [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows); this page adds port declarations and a registered type palette to the node data.

:::code-group
```ts title="JavaScript"
import {
  render,
  portTypeRegistry,
  type EdgeSpec,
  type NodeSpec,
} from '@grafloria/element';

portTypeRegistry.registerAll([
  { name: 'number', color: '#2563eb', compatibleWith: ['number'] },
  { name: 'string', color: '#9333ea', compatibleWith: ['string'] },
]);

const nodes: NodeSpec[] = [
  {
    id: 'source',
    position: { x: 80, y: 130 },
    size: { width: 160, height: 120 },
    label: 'Source',
    metadata: {
      portGroups: {
        outputs: {
          id: 'outputs',
          side: 'right',
          visibility: 'always',
          layout: { strategy: 'sideLinear', args: { padding: 18 } },
        },
      },
    },
    ports: [
      {
        id: 'number-out',
        group: 'outputs',
        type: 'output',
        dataType: 'number',
        shape: { shape: 'circle', size: 14 },
        label: { text: 'number', layout: 'outside' },
      },
      {
        id: 'string-out',
        group: 'outputs',
        type: 'output',
        dataType: 'string',
        shape: { shape: 'square', size: 14 },
        label: { text: 'string', layout: 'outside' },
      },
    ],
  },
  {
    id: 'convert',
    position: { x: 430, y: 130 },
    size: { width: 160, height: 120 },
    label: 'Convert',
    metadata: {
      portGroups: {
        inputs: {
          id: 'inputs',
          side: 'left',
          visibility: 'always',
          layout: { strategy: 'sideLinear', args: { padding: 18 } },
        },
      },
    },
    ports: [
      {
        id: 'number-in',
        group: 'inputs',
        type: 'input',
        dataType: 'number',
        shape: { shape: 'diamond', size: 14 },
        label: { text: 'number', layout: 'outside' },
      },
      {
        id: 'string-in',
        group: 'inputs',
        type: 'input',
        dataType: 'string',
        shape: { shape: 'triangle', size: 14 },
        label: { text: 'string', layout: 'outside' },
      },
    ],
  },
];

const edges: EdgeSpec[] = [
  { id: 'number-link', source: 'source', sourceHandle: 'number-out', target: 'convert', targetHandle: 'number-in' },
];

const host = document.createElement('div');
host.style.width = '100%';
host.style.height = '420px';
document.body.append(host);

requestAnimationFrame(() => render({ nodes, edges }, host));
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { portTypeRegistry } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

portTypeRegistry.registerAll([
  { name: 'number', color: '#2563eb', compatibleWith: ['number'] },
  { name: 'string', color: '#9333ea', compatibleWith: ['string'] },
]);

@Component({
  selector: 'app-port-example',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      style="display: block; height: 420px"
    />
  `,
})
export class PortExampleComponent {
  nodes: NodeSpec[] = [
    {
      id: 'source',
      position: { x: 80, y: 130 },
      size: { width: 160, height: 120 },
      label: 'Source',
      metadata: {
        portGroups: {
          outputs: {
            id: 'outputs',
            side: 'right',
            visibility: 'always',
            layout: { strategy: 'sideLinear', args: { padding: 18 } },
          },
        },
      },
      ports: [
        {
          id: 'number-out', group: 'outputs', type: 'output', dataType: 'number',
          shape: { shape: 'circle', size: 14 },
          label: { text: 'number', layout: 'outside' },
        },
        {
          id: 'string-out', group: 'outputs', type: 'output', dataType: 'string',
          shape: { shape: 'square', size: 14 },
          label: { text: 'string', layout: 'outside' },
        },
      ],
    },
    {
      id: 'convert',
      position: { x: 430, y: 130 },
      size: { width: 160, height: 120 },
      label: 'Convert',
      metadata: {
        portGroups: {
          inputs: {
            id: 'inputs',
            side: 'left',
            visibility: 'always',
            layout: { strategy: 'sideLinear', args: { padding: 18 } },
          },
        },
      },
      ports: [
        {
          id: 'number-in', group: 'inputs', type: 'input', dataType: 'number',
          shape: { shape: 'diamond', size: 14 },
          label: { text: 'number', layout: 'outside' },
        },
        {
          id: 'string-in', group: 'inputs', type: 'input', dataType: 'string',
          shape: { shape: 'triangle', size: 14 },
          label: { text: 'string', layout: 'outside' },
        },
      ],
    },
  ];

  edges: EdgeSpec[] = [
    { id: 'number-link', source: 'source', sourceHandle: 'number-out', target: 'convert', targetHandle: 'number-in' },
  ];
}
```
```tsx title="Qwik"
import { $, component$ } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance, type EdgeSpec, type NodeSpec } from '@grafloria/qwik';
import { portTypeRegistry } from '@grafloria/element';

const nodes: NodeSpec[] = [
  {
    id: 'source', position: { x: 80, y: 130 }, size: { width: 160, height: 120 }, label: 'Source',
    metadata: { portGroups: { outputs: {
      id: 'outputs', side: 'right', visibility: 'always',
      layout: { strategy: 'sideLinear', args: { padding: 18 } },
    } } },
    ports: [
      { id: 'number-out', group: 'outputs', type: 'output', dataType: 'number', shape: { shape: 'circle', size: 14 }, label: { text: 'number', layout: 'outside' } },
      { id: 'string-out', group: 'outputs', type: 'output', dataType: 'string', shape: { shape: 'square', size: 14 }, label: { text: 'string', layout: 'outside' } },
    ],
  },
  {
    id: 'convert', position: { x: 430, y: 130 }, size: { width: 160, height: 120 }, label: 'Convert',
    metadata: { portGroups: { inputs: {
      id: 'inputs', side: 'left', visibility: 'always',
      layout: { strategy: 'sideLinear', args: { padding: 18 } },
    } } },
    ports: [
      { id: 'number-in', group: 'inputs', type: 'input', dataType: 'number', shape: { shape: 'diamond', size: 14 }, label: { text: 'number', layout: 'outside' } },
      { id: 'string-in', group: 'inputs', type: 'input', dataType: 'string', shape: { shape: 'triangle', size: 14 }, label: { text: 'string', layout: 'outside' } },
    ],
  },
];

const edges: EdgeSpec[] = [
  { id: 'number-link', source: 'source', sourceHandle: 'number-out', target: 'convert', targetHandle: 'number-in' },
];

export default component$(() => (
  <div style={{ height: '420px' }}>
    <GrafloriaFlow
      defaultNodes={nodes}
      defaultEdges={edges}
      onInit$={$((instance: DiagramInstance) => {
        portTypeRegistry.registerAll([
          { name: 'number', color: '#2563eb', compatibleWith: ['number'] },
          { name: 'string', color: '#9333ea', compatibleWith: ['string'] },
        ]);
        instance.renderNow();
      })}
    />
  </div>
));
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import { portTypeRegistry } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/vue';

portTypeRegistry.registerAll([
  { name: 'number', color: '#2563eb', compatibleWith: ['number'] },
  { name: 'string', color: '#9333ea', compatibleWith: ['string'] },
]);

const nodes: NodeSpec[] = [
  {
    id: 'source',
    position: { x: 80, y: 130 },
    size: { width: 160, height: 120 },
    label: 'Source',
    metadata: {
      portGroups: {
        outputs: {
          id: 'outputs', side: 'right', visibility: 'always',
          layout: { strategy: 'sideLinear', args: { padding: 18 } },
        },
      },
    },
    ports: [
      {
        id: 'number-out', group: 'outputs', type: 'output', dataType: 'number',
        shape: { shape: 'circle', size: 14 }, label: { text: 'number', layout: 'outside' },
      },
      {
        id: 'string-out', group: 'outputs', type: 'output', dataType: 'string',
        shape: { shape: 'square', size: 14 }, label: { text: 'string', layout: 'outside' },
      },
    ],
  },
  {
    id: 'convert',
    position: { x: 430, y: 130 },
    size: { width: 160, height: 120 },
    label: 'Convert',
    metadata: {
      portGroups: {
        inputs: {
          id: 'inputs', side: 'left', visibility: 'always',
          layout: { strategy: 'sideLinear', args: { padding: 18 } },
        },
      },
    },
    ports: [
      {
        id: 'number-in', group: 'inputs', type: 'input', dataType: 'number',
        shape: { shape: 'diamond', size: 14 }, label: { text: 'number', layout: 'outside' },
      },
      {
        id: 'string-in', group: 'inputs', type: 'input', dataType: 'string',
        shape: { shape: 'triangle', size: 14 }, label: { text: 'string', layout: 'outside' },
      },
    ],
  },
];

const edges: EdgeSpec[] = [
  { id: 'number-link', source: 'source', sourceHandle: 'number-out', target: 'convert', targetHandle: 'number-in' },
];
</script>

<template>
  <div style="height: 420px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" />
  </div>
</template>
```
:::

When the canvas mounts, you see two labelled nodes, four always-visible ports, and the initial number-to-number connection. The source and target groups inherit their side and `sideLinear` layout; each port supplies its own glyph, label, and type. In every sample, the palette colors number ports blue and string ports purple. Drag `number-out` to `string-in` to see the mismatch refused; both registrations allow only the same named type.

## Port fields that shape the result

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `ports` | [`PortSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-portspec#portspec)[] | Omitted: four deterministic default ports | Declares the node's own connection points. |
| `shape` | Shape object | Circle | Chooses `circle`, `square`, `diamond`, `triangle`, or an SVG `path`; `size` sets the glyph box in pixels. |
| `label` | Label object | No label; when present, `layout` defaults to `outside` | Adds text near the port. Choose `inside`, `outside`, `orthogonal`, or `radial` placement. |
| `group` | `string` | No group | Inherits shared settings from the same id in the node's `metadata.portGroups`; a port's own settings override group values. |
| `metadata.portGroups` | Node metadata object | No groups | Defines shared port settings such as side, visibility, shape, and layout. A `sideLinear` layout distributes group members along that side. |
| `dataType` | `string` | Untyped | Associates the port with a registered type for glyph colour and connection compatibility. |

The default visibility mode shows ports on hover. The examples set each group's visibility to `always` so the ports and their labels appear immediately. `shape: 'path'` accepts caller-provided SVG path data; use it when the built-in glyphs do not distinguish your port.

## See the port behaviors

The [port shapes demo](https://grafloria.com/demos/ports/port-shapes.html) compares circle, square, diamond, triangle, and custom-path glyphs as distinct SVG primitives.

The [port labels demo](https://grafloria.com/demos/ports/port-labels.html) shows labels placed inside, outside, and orthogonal to their glyphs.

The [port groups and layouts demo](https://grafloria.com/demos/ports/port-groups-and-layouts.html) compares a side column, a line segment, and an ellipse spread.

The [typed ports demo](https://grafloria.com/demos/ports/typed-ports.html) registers number and string types, then shows a matching connection and a mismatched target.

## Pitfalls

- If the node spec omits `ports`, it keeps the four deterministic defaults; add a `ports` array to replace that set with your declared ports.
- Put shared configuration under the node's `metadata.portGroups` and match each port's `group` value to that entry's id. A port-level value takes precedence over the inherited group value.
- Register named data types to assign colours or declare compatibility beyond exact matches. Compatibility is directional when `compatibleWith` is used; an untyped endpoint remains unconstrained.
- A `dataType` alone does not pick a colour. Register a color for the type, then the renderer uses it for that type's port glyph.

## Related

- [Validate connections](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/validate-connections) for connection rules beyond a port's direction and data type.
- [Handle connection interactions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/handle-connection-interactions) for responding to connection gestures.
- [The diagram model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document) for how diagram specs become the live model.

<!-- source: validate-connections.md -->

# Validate connections

Refuse connections that break an application rule, and give users a reason for each refusal.

Use a registered validator for rules that depend on your diagram's data, such as preventing a Sink from acting as a connection source. The validator evaluates a proposed connection on the live canvas; framework bindings still use the same model and rule.

## Mount the diagram and register a rule

The examples mount a small Source → Transform → Sink diagram. A registered rule rejects any proposal whose source node has `data.role === 'sink'`; returning a string supplies the refusal reason, while `true` allows the proposal. The callback can also update the small status line so the reason appears in the view.

For typed graph data and mounting the canvas in JavaScript, Angular, Qwik, React, or Vue, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows). This page adds the connection rule: register [`registerConnectionValidator`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-functions#registerconnectionvalidator) when the view mounts and keep its returned disposer for teardown.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';
import { registerConnectionValidator } from '@grafloria/renderer';

const host = document.createElement('div');
host.style.height = '500px';
host.style.width = '100%';
document.body.append(host);

const status = document.createElement('p');
status.textContent = 'Try drawing a connection out of the Sink.';
document.body.insertBefore(status, host);

const nodes = [
  { id: 'source', position: { x: 80, y: 120 }, size: { width: 120, height: 46 }, label: 'Source', data: { role: 'source' } },
  { id: 'transform', position: { x: 320, y: 120 }, size: { width: 120, height: 46 }, label: 'Transform', data: { role: 'transform' } },
  { id: 'sink', position: { x: 560, y: 120 }, size: { width: 120, height: 46 }, label: 'Sink', data: { role: 'sink' } },
];
const edges = [];

const dispose = registerConnectionValidator(({ sourceNode }) => {
  if (sourceNode.data?.role === 'sink') {
    status.textContent = 'Refused: a Sink has no outputs';
    return 'A Sink has no outputs';
  }
  return true;
});

const instance = render({ nodes, edges }, host);
instance.fitView();
window.addEventListener('pagehide', dispose, { once: true });
```
```ts title="Angular"
import { Component, OnDestroy, signal } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { registerConnectionValidator } from '@grafloria/renderer';

@Component({
  selector: 'app-validated-flow',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <p>{{ reason() }}</p>
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      style="display: block; height: 500px"
    />
  `,
})
export class ValidatedFlowComponent implements OnDestroy {
  readonly reason = signal('Try drawing a connection out of the Sink.');
  nodes: NodeSpec[] = [
    { id: 'source', position: { x: 80, y: 120 }, size: { width: 120, height: 46 }, label: 'Source', data: { role: 'source' } },
    { id: 'transform', position: { x: 320, y: 120 }, size: { width: 120, height: 46 }, label: 'Transform', data: { role: 'transform' } },
    { id: 'sink', position: { x: 560, y: 120 }, size: { width: 120, height: 46 }, label: 'Sink', data: { role: 'sink' } },
  ];
  edges: EdgeSpec[] = [];

  private readonly dispose = registerConnectionValidator(({ sourceNode }) => {
    if (sourceNode.data['role'] === 'sink') {
      this.reason.set('Refused: a Sink has no outputs');
      return 'A Sink has no outputs';
    }
    return true;
  });

  ngOnDestroy(): void {
    this.dispose();
  }
}
```
```tsx title="Qwik"
import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik';
import { render } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { registerConnectionValidator } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'source', position: { x: 80, y: 120 }, size: { width: 120, height: 46 }, label: 'Source', data: { role: 'source' } },
  { id: 'transform', position: { x: 320, y: 120 }, size: { width: 120, height: 46 }, label: 'Transform', data: { role: 'transform' } },
  { id: 'sink', position: { x: 560, y: 120 }, size: { width: 120, height: 46 }, label: 'Sink', data: { role: 'sink' } },
];
const edges: EdgeSpec[] = [];

export default component$(() => {
  const host = useSignal<HTMLElement>();
  const reason = useSignal('Try drawing a connection out of the Sink.');

  useVisibleTask$(({ cleanup }) => {
    const container = host.value;
    if (!container) return;

    const dispose = registerConnectionValidator(({ sourceNode }) => {
      if (sourceNode.data['role'] === 'sink') {
        reason.value = 'Refused: a Sink has no outputs';
        return 'A Sink has no outputs';
      }
      return true;
    });
    const instance = render({ nodes, edges }, container);
    instance.fitView();
    cleanup(() => {
      dispose();
      instance.dispose();
    });
  }, { strategy: 'document-ready' });

  return (
    <div style={{ height: '500px' }}>
      <p>{reason.value}</p>
      <div ref={host} style={{ height: '460px' }} />
    </div>
  );
});
```
```tsx title="React"
import { useEffect, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { registerConnectionValidator } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'source', position: { x: 80, y: 120 }, size: { width: 120, height: 46 }, label: 'Source', data: { role: 'source' } },
  { id: 'transform', position: { x: 320, y: 120 }, size: { width: 120, height: 46 }, label: 'Transform', data: { role: 'transform' } },
  { id: 'sink', position: { x: 560, y: 120 }, size: { width: 120, height: 46 }, label: 'Sink', data: { role: 'sink' } },
];
const edges: EdgeSpec[] = [];

export default function ValidatedFlow() {
  const [reason, setReason] = useState('Try drawing a connection out of the Sink.');

  useEffect(() => {
    const dispose = registerConnectionValidator(({ sourceNode }) => {
      if (sourceNode.data?.role === 'sink') {
        setReason('Refused: a Sink has no outputs');
        return 'A Sink has no outputs';
      }
      return true;
    });
    return dispose;
  }, []);

  return (
    <div style={{ height: '500px' }}>
      <p>{reason}</p>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/vue';
import { registerConnectionValidator } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'source', position: { x: 80, y: 120 }, size: { width: 120, height: 46 }, label: 'Source', data: { role: 'source' } },
  { id: 'transform', position: { x: 320, y: 120 }, size: { width: 120, height: 46 }, label: 'Transform', data: { role: 'transform' } },
  { id: 'sink', position: { x: 560, y: 120 }, size: { width: 120, height: 46 }, label: 'Sink', data: { role: 'sink' } },
];
const edges: EdgeSpec[] = [];
const reason = ref('Try drawing a connection out of the Sink.');
let dispose: ReturnType<typeof registerConnectionValidator> | undefined;

onMounted(() => {
  dispose = registerConnectionValidator(({ sourceNode }) => {
    if (sourceNode.data?.role === 'sink') {
      reason.value = 'Refused: a Sink has no outputs';
      return 'A Sink has no outputs';
    }
    return true;
  });
});

onBeforeUnmount(() => dispose?.());
</script>

<template>
  <div style="height: 500px">
    <p>{{ reason }}</p>
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" />
  </div>
</template>
```
:::

When the canvas mounts, it shows Source, Transform, and Sink with no links. Drag from Source to Transform or Transform to Sink to make a legal connection; dragging out of Sink leaves no link and changes the status line to “Refused: a Sink has no outputs.” The validator's returned string is the rule's reason; the status line is application UI updated by the same callback.

## Validator contract

Write the rule against the source and target nodes. Return `true` to allow the proposal, `false` to veto without a reason, or a string to veto with that reason. Every registered validator must pass, so a single veto refuses the connection.

| Return value | Type | Effect |
| --- | --- | --- |
| Allow | `true` | Accepts this validator's candidate. |
| Veto | `false` | Refuses without a reason string. |
| Veto with reason | `string` | Refuses and supplies the returned text as the reason. |

## Pitfalls

- The validator registry is process-global, not per canvas. Keep the disposer returned by `registerConnectionValidator` and call it when this view unmounts; otherwise its rule also applies to other diagrams in the same process.
- [`clearConnectionValidators`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-functions#clearconnectionvalidators) removes every registered validator, not only the current view's. Use it only when you intentionally want a clean registry; normal teardown calls the view's own disposer.
- Port direction and type compatibility are separate built-in validation layers. Use [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports) for rules expressed by port direction or data types; register a custom validator for application-specific rules.

## See it running

Open the [live connection-validation demo](https://grafloria.com/demos/interaction/validation.html) to try a rejected Sink connection and accepted connections in the browser. Its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/validation.html) drives the connection pipeline with a registered validator.

## Related

- [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports) for direction and data-type constraints.
- [Handle connection interactions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/handle-connection-interactions) for responding to connection gestures.

<!-- source: handle-connection-interactions.md -->

# Handle connection interactions

Observe a connection drag from start through completion or cancellation, and let users create links by dragging from a node body to another node.

Use body-to-body connection when users should not have to aim at a small port. The built-in mode starts from the nearest port on the first node and completes at the nearest port on the second. With the mode off, the usual interaction is port-to-port dragging, and dragging a node body moves the node.

## Mount the diagram and listen to its connection lifecycle

These examples mount two typed nodes and an empty edge list, then enable body-to-body connection and write each lifecycle event to a visible log. Drag anywhere on the source node to the target node and release to create a link; the log records the gesture as it happens. Drag off the target or press Escape to cancel instead.

For the JavaScript, Angular, and Vue mounting patterns and access to the live canvas, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows). This page adds body-to-body connection and a log of its lifecycle events. The diagram data uses [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec).

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const log = document.createElement('pre');
log.style.height = '88px';
log.style.overflow = 'auto';
log.textContent = 'Drag from source to target to see the connection lifecycle.';
const canvas = document.createElement('div');
canvas.style.width = '700px';
canvas.style.height = '420px';
document.body.append(log, canvas);

/** @type {import('@grafloria/element').NodeSpec[]} */
const nodes = [
  {
    id: 'src',
    position: { x: 80, y: 70 },
    size: { width: 150, height: 60 },
    label: 'source',
    ports: [{ id: 'src.out', side: 'right', type: 'output' }],
  },
  {
    id: 'dst',
    position: { x: 430, y: 70 },
    size: { width: 150, height: 60 },
    label: 'target',
    ports: [{ id: 'dst.in', side: 'left', type: 'input' }],
  },
];
/** @type {import('@grafloria/element').EdgeSpec[]} */
const edges = [];
const instance = render({ nodes, edges }, canvas);
const engine = instance.getEngine();
engine.setInteractionConfig({ enableEasyConnect: true });

const connectionEvents = [
  'connection:start',
  'connection:update',
  'connection:port-enter',
  'connection:port-leave',
  'connection:complete',
  'connection:cancel',
];
for (const name of connectionEvents) {
  engine.eventBus.on(name, () => {
    if (log.textContent?.startsWith('Drag from')) log.textContent = '';
    log.prepend(`${name}\n`);
  });
}
```
```ts title="Angular"
import { AfterViewInit, Component, OnDestroy, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="height: 88px; overflow: auto">
      @for (row of rows(); track $index) {
        <div>{{ row }}</div>
      }
    </div>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display: block; width: 700px; height: 420px" />
  `,
})
export class ConnectionInteractionsComponent implements AfterViewInit, OnDestroy {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly rows = signal<string[]>(['Drag from source to target to see the connection lifecycle.']);
  nodes: NodeSpec[] = [
    {
      id: 'src',
      position: { x: 80, y: 70 },
      size: { width: 150, height: 60 },
      label: 'source',
      ports: [{ id: 'src.out', side: 'right', type: 'output' }],
    },
    {
      id: 'dst',
      position: { x: 430, y: 70 },
      size: { width: 150, height: 60 },
      label: 'target',
      ports: [{ id: 'dst.in', side: 'left', type: 'input' }],
    },
  ];
  edges: EdgeSpec[] = [];
  private disposers: Array<() => void> = [];

  ngAfterViewInit(): void {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    engine.setInteractionConfig({ enableEasyConnect: true });
    const connectionEvents = [
      'connection:start',
      'connection:update',
      'connection:port-enter',
      'connection:port-leave',
      'connection:complete',
      'connection:cancel',
    ];
    this.disposers = connectionEvents.map((name) =>
      engine.eventBus.on(name, () => this.rows.update((rows) => [name, ...rows].slice(0, 12))),
    );
  }

  ngOnDestroy(): void {
    this.disposers.forEach((dispose) => dispose());
  }
}
```
```vue title="Vue"
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue';
import { GrafloriaFlow, type DiagramInstance, type EdgeSpec, type NodeSpec } from '@grafloria/vue';

const nodes: NodeSpec[] = [
  {
    id: 'src',
    position: { x: 80, y: 70 },
    size: { width: 150, height: 60 },
    label: 'source',
    ports: [{ id: 'src.out', side: 'right', type: 'output' }],
  },
  {
    id: 'dst',
    position: { x: 430, y: 70 },
    size: { width: 150, height: 60 },
    label: 'target',
    ports: [{ id: 'dst.in', side: 'left', type: 'input' }],
  },
];
const edges: EdgeSpec[] = [];
const connectionEvents = [
  'connection:start',
  'connection:update',
  'connection:port-enter',
  'connection:port-leave',
  'connection:complete',
  'connection:cancel',
];
const rows = ref<string[]>(['Drag from source to target to see the connection lifecycle.']);
let disposers: Array<() => void> = [];

function onInit(instance: DiagramInstance): void {
  const engine = instance.getEngine();
  engine.setInteractionConfig({ enableEasyConnect: true });
  disposers = connectionEvents.map((name) =>
    engine.eventBus.on(name, () => {
      rows.value = [name, ...rows.value].slice(0, 12);
    }),
  );
}

onBeforeUnmount(() => disposers.forEach((dispose) => dispose()));
</script>

<template>
  <div style="width: 700px; height: 520px">
    <div style="height: 88px; overflow: auto">
      <div v-for="(row, index) in rows" :key="`${index}-${row}`">{{ row }}</div>
    </div>
    <div style="height: 420px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
    </div>
  </div>
</template>
```
:::

The log names the six engine events. `connection:start` carries the source port and valid target ports; `connection:update` reports the current target and whether it is valid, including a rejection reason; `connection:port-enter` and `connection:port-leave` mark target-port crossings; `connection:complete` identifies the connected ports; and `connection:cancel` marks an abandoned or refused drag. `update` can fire repeatedly while the pointer moves. A successful drop ends with `complete`; a refused drop or Escape ends with `cancel`.

[Open the live connection-events demo](https://grafloria.com/demos/interaction/connection-events.html) or [read its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/connection-events.html).

## Choose the connection gesture

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `enableEasyConnect` | `boolean` | `false` | Starts a connection from the nearest port when the user presses a node body, instead of moving the node. |

JavaScript and Vue turn on `enableEasyConnect` after mount with `instance.getEngine().setInteractionConfig(...)`. Angular accesses its engine through `activeEngine()` and calls `setInteractionConfig(...)` there. Leave the option off to keep body-drag-to-move and start connections from ports instead. With it on, press anywhere on the source node and release on the target node; the built-in interaction creates the link without a custom tool.

[Open the live easy-connect-body demo](https://grafloria.com/demos/interaction/easy-connect-body.html) or [read its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/easy-connect-body.html).

## Watch for

- Keep the event subscriptions for the lifetime of the mounted canvas and call each returned disposer when the host unmounts. Otherwise, repeated mounts can leave old listeners recording the same gesture.
- `enableEasyConnect` changes what a node-body press does: it starts a connection rather than moving that node. Leave the option disabled when users need body dragging to move nodes.
- This example logs event names. Read the event payload when the host needs port details or a validation reason.

## Related

- [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports)
- [Validate connections](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/validate-connections)
- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history)
- [Events and interaction reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance)

<!-- source: lay-out-diagrams.md -->

# Lay out diagrams automatically

Use automatic layout when you have a populated graph and want Grafloria to place its nodes instead of positioning them by hand. Each example lays out a small tree whose nodes start at the origin.

## Arrange a tree when the canvas mounts

Choose a layout algorithm for your populated graph. In plain JavaScript, pass node and edge specs to `render()`, then call the mounted instance's engine layout method. In Angular, React, and Vue, pass the specs and layout request to the rendered component. In Qwik, mount and lay out the canvas in a browser-only visible task. Each canvas starts with nodes stacked at `(0, 0)`; the selected layout arranges the nodes into a tree.

For plain JavaScript, [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) mounts the specs into an element and returns a live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance). The sample calls the engine through that mounted instance.

```js title="JavaScript"
import { render } from '@grafloria/element';

const ids = ['root', 'a', 'b', 'a1', 'a2', 'b1', 'b2'];
const nodes = ids.map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 120, height: 48 },
  label: id,
}));
const edges = [
  { id: 'e1', source: 'root', target: 'a' },
  { id: 'e2', source: 'root', target: 'b' },
  { id: 'e3', source: 'a', target: 'a1' },
  { id: 'e4', source: 'a', target: 'a2' },
  { id: 'e5', source: 'b', target: 'b1' },
];

const container = document.createElement('div');
container.style.height = '520px';
document.body.append(container);

async function showTree() {
  const instance = render({ nodes, edges }, container);
  const engine = instance.getEngine();
  await engine.layout('dagre', {
    nodeSpacing: 40,
    rankSpacing: 80,
  });
  instance.renderNow();
  instance.fitView(40);
}

void showTree();
```

The Angular, React, and Vue samples reuse [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec) and the mounting patterns from [Execute and compute flows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/execute-and-compute-flows), adding a `layout` request to [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent) and [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react) / [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue) to arrange the nodes automatically.

:::code-group
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const ids = ['root', 'a', 'b', 'a1', 'a2', 'b1', 'b2'];

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      [layout]="'dagre'"
      style="display:block; height:520px" />
  `,
})
export class DagreTreeComponent {
  nodes: NodeSpec[] = ids.map((id) => ({
    id,
    position: { x: 0, y: 0 },
    size: { width: 120, height: 48 },
    label: id,
  }));
  edges: EdgeSpec[] = [
    { id: 'e1', source: 'root', target: 'a' },
    { id: 'e2', source: 'root', target: 'b' },
    { id: 'e3', source: 'a', target: 'a1' },
    { id: 'e4', source: 'a', target: 'a2' },
    { id: 'e5', source: 'b', target: 'b1' },
  ];
}
```
```tsx title="Qwik"
import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik';
import { render } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const ids = ['root', 'a', 'b', 'a1', 'a2', 'b1', 'b2'];
const nodes: NodeSpec[] = ids.map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 120, height: 48 },
  label: id,
}));
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'root', target: 'a' },
  { id: 'e2', source: 'root', target: 'b' },
  { id: 'e3', source: 'a', target: 'a1' },
  { id: 'e4', source: 'a', target: 'a2' },
  { id: 'e5', source: 'b', target: 'b1' },
];

export default component$(() => {
  const host = useSignal<HTMLDivElement>();
  useVisibleTask$(({ cleanup }) => {
    const container = host.value;
    if (!container) return;
    const instance = render({ nodes, edges }, container);
    void instance.getEngine().layout('dagre', {
      nodeSpacing: 40,
      rankSpacing: 80,
    }).then(() => {
      instance.renderNow();
      instance.fitView(40);
    });
    cleanup(() => instance.dispose());
  });
  return <div ref={host} style={{ height: '520px' }} />;
});
```
```tsx title="React"
import { GrafloriaFlow, type EdgeSpec, type NodeSpec } from '@grafloria/react';

const ids = ['root', 'a', 'b', 'a1', 'a2', 'b1', 'b2'];
const nodes: NodeSpec[] = ids.map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 120, height: 48 },
  label: id,
}));
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'root', target: 'a' },
  { id: 'e2', source: 'root', target: 'b' },
  { id: 'e3', source: 'a', target: 'a1' },
  { id: 'e4', source: 'a', target: 'a2' },
  { id: 'e5', source: 'b', target: 'b1' },
];

export function DagreTree() {
  return (
    <div style={{ height: '520px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} layout="dagre" />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/vue';

const ids = ['root', 'a', 'b', 'a1', 'a2', 'b1', 'b2'];
const layout = {
  name: 'dagre',
  options: { nodeSpacing: 40, rankSpacing: 80 },
};
const nodes: NodeSpec[] = ids.map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 120, height: 48 },
  label: id,
}));
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'root', target: 'a' },
  { id: 'e2', source: 'root', target: 'b' },
  { id: 'e3', source: 'a', target: 'a1' },
  { id: 'e4', source: 'a', target: 'a2' },
  { id: 'e5', source: 'b', target: 'b1' },
];
</script>

<template>
  <div style="height:520px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :layout="layout" />
  </div>
</template>
```
:::

### What you see

The nodes no longer overlap at their shared starting point: Dagre positions the tree, including the disconnected `b2` node, and the canvas shows the arranged graph.

Try the [Dagre tree demo](https://grafloria.com/demos/layout/dagre-tree.html) and its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/layout/dagre-tree.html) to see the same graph laid out live.

## Choose a layout

The registry names documented for whole-diagram layout are `auto`, `architecture`, `elk`, `dagre`, `layered`, `tree`, `grid`, `circular`, `radial`, `force`, `spectral`, and `community`. Use `auto` when you want Grafloria to classify the graph and select an algorithm. For a pipeline or DAG, choose `elk`, `layered`, or `dagre`; for a hierarchy, choose `tree`; for networks and clusters, consider `force`, `community`, or `spectral`; and for a catalog, use `grid`, `circular`, or `radial`.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `layout` | `string` or object request | Not set | Selects the algorithm on the component. An object request can include the algorithm's options. |
| `name` | `string` | — | Names the algorithm in an object layout request. |
| `nodeSpacing` | `number` | Algorithm default | Sets space between nodes in the same rank or row. |
| `rankSpacing` | `number` | Algorithm default | Sets space between ranks or layers. |

The engine also accepts the selected algorithm directly. Call `layout()` through the mounted instance and await it; the engine commits the new node positions to the diagram. The JavaScript sample calls the [`DiagramEngine`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-engine) through the instance.

## Re-run layout on demand

The component layout binding runs when its value changes, not when node data changes. This keeps a data update caused by dragging from starting a layout that would fight the user's gesture. When you need an explicit rerun, call `instance.getEngine().layout('dagre', options)` through the mounted instance, or use `applyLayout()` on the Angular or Vue component. `applyLayout()` reruns the bound request or accepts a registry layout request.

## Related

- [Preserve the layout mental map](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/preserve-the-layout-mental-map) when new nodes arrive in a diagram that users have already arranged.
- [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the shared engine model behind its framework bindings.

<!-- source: preserve-the-layout-mental-map.md -->

# Preserve the layout mental map

Add a node to an arranged graph with an incremental pass while minimizing movement to existing diagram content.

Use incremental layout after inserting or editing nodes in a graph people already know. A full layout can move the entire graph; the incremental pass confines disturbance around the changed nodes and reports movement.

## Add a node with incremental layout

1. Mount a connected graph and lay it out with `layered` so its starting positions come from the same layout engine. In JavaScript, [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) mounts the spec and returns the live instance; framework apps use their canvas component.
2. Add the new node and its edges to the live [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance). Mark the new node in `changed`, then call `layoutIncremental()` on the engine returned by `getEngine()`.
3. Repaint and frame the result. The new node appears in the chain, while nodes outside the affected neighborhood remain anchors. The result includes a movement report and a tween plan; the engine returns the plan rather than animating it, so a host can drive the animation if needed.

The task-specific difference is inserting a node into an arranged chain and measuring movement among the existing nodes; see [Lay out diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams) for the shared mounting, framework-binding, and typed-spec patterns.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

async function main() {
const nodes = ['n0', 'n1', 'n2', 'n3', 'n4', 'n5'].map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 110, height: 46 },
  label: id,
}));
const edges = [
  { id: 'e0', source: 'n0', target: 'n1' },
  { id: 'e1', source: 'n1', target: 'n2' },
  { id: 'e2', source: 'n2', target: 'n3' },
  { id: 'e3', source: 'n3', target: 'n4' },
  { id: 'e4', source: 'n4', target: 'n5' },
];
const host = document.getElementById('app');
if (!host) throw new Error('Missing #app element');
host.style.height = '400px';
const instance = render({ nodes, edges }, host);
const engine = instance.getEngine();

await engine.layout('layered');
instance.renderNow();
instance.fitView(40);

instance.setNodes([
  ...nodes,
  { id: 'inserted', position: { x: 0, y: 0 }, size: { width: 110, height: 46 }, label: 'inserted' },
]);
instance.setEdges([
  ...edges,
  { id: 'x0', source: 'n2', target: 'inserted' },
  { id: 'x1', source: 'inserted', target: 'n4' },
]);
const result = await engine.layoutIncremental({ name: 'layered', changed: ['inserted'], radius: 1 });
instance.renderNow();
instance.fitView(40);

console.log(result.movement.total, result.tween.movingIds);
}

void main();
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { LinkModel, NodeModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="insertNode()">Insert node</button>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      [layout]="'layered'" style="display:block; height:400px" />
  `,
})
export class AppComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: readonly (NodeSpec | NodeModel)[] | undefined = ['n0', 'n1', 'n2', 'n3', 'n4', 'n5'].map((id) => ({
    id,
    position: { x: 0, y: 0 },
    size: { width: 110, height: 46 },
    label: id,
  }));
  edges: readonly (EdgeSpec | LinkModel)[] | undefined = [
    { id: 'e0', source: 'n0', target: 'n1' },
    { id: 'e1', source: 'n1', target: 'n2' },
    { id: 'e2', source: 'n2', target: 'n3' },
    { id: 'e3', source: 'n3', target: 'n4' },
    { id: 'e4', source: 'n4', target: 'n5' },
  ];

  insertNode(): void {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    this.nodes = [
      ...(this.nodes ?? []),
      { id: 'inserted', position: { x: 0, y: 0 }, size: { width: 110, height: 46 }, label: 'inserted' },
    ];
    this.edges = [
      ...(this.edges ?? []),
      { id: 'x0', source: 'n2', target: 'inserted' },
      { id: 'x1', source: 'inserted', target: 'n4' },
    ];

    setTimeout(() => {
      const liveEngine = this.canvas().activeEngine();
      if (liveEngine) void liveEngine.layoutIncremental({ name: 'layered', changed: ['inserted'], radius: 1 });
    }, 0);
  }
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = ['n0', 'n1', 'n2', 'n3', 'n4', 'n5'].map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 110, height: 46 },
  label: id,
}));
const edges: EdgeSpec[] = [
  { id: 'e0', source: 'n0', target: 'n1' },
  { id: 'e1', source: 'n1', target: 'n2' },
  { id: 'e2', source: 'n2', target: 'n3' },
  { id: 'e3', source: 'n3', target: 'n4' },
  { id: 'e4', source: 'n4', target: 'n5' },
];

async function onInit(instance: DiagramInstance): Promise<void> {
  const engine = instance.getEngine();
  await engine.layout('layered');
  instance.renderNow();
  instance.fitView(40);

  instance.setNodes([
    ...nodes,
    { id: 'inserted', position: { x: 0, y: 0 }, size: { width: 110, height: 46 }, label: 'inserted' },
  ]);
  instance.setEdges([
    ...edges,
    { id: 'x0', source: 'n2', target: 'inserted' },
    { id: 'x1', source: 'inserted', target: 'n4' },
  ]);
  const result = await engine.layoutIncremental({ name: 'layered', changed: ['inserted'], radius: 1 });
  instance.renderNow();
  instance.fitView(40);
  console.log(result.movement.total, result.tween.movingIds);
}
</script>

<template>
  <div style="height:400px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
  </div>
</template>
```
:::

In Qwik, mount `GrafloriaFlow` with `defaultNodes={baseNodes}` and `defaultEdges={baseEdges}`, then wrap the handler below with `$()` and pass it as `onInit$`. It lays out the mounted chain, inserts a node between `n2` and `n4`, and incrementally lays out the changed neighborhood.

```ts title="Qwik"
import type { DiagramInstance } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export const baseNodes: NodeSpec[] = ['n0', 'n1', 'n2', 'n3', 'n4', 'n5'].map((id) => ({
  id,
  position: { x: 0, y: 0 },
  size: { width: 110, height: 46 },
  label: id,
}));
export const baseEdges: EdgeSpec[] = [
  { id: 'e0', source: 'n0', target: 'n1' },
  { id: 'e1', source: 'n1', target: 'n2' },
  { id: 'e2', source: 'n2', target: 'n3' },
  { id: 'e3', source: 'n3', target: 'n4' },
  { id: 'e4', source: 'n4', target: 'n5' },
];

export async function onInit(instance: DiagramInstance): Promise<void> {
  const engine = instance.getEngine();
  await engine.layout('layered');
  instance.renderNow();
  instance.fitView(40);
  instance.setNodes([
    ...baseNodes,
    { id: 'inserted', position: { x: 0, y: 0 }, size: { width: 110, height: 46 }, label: 'inserted' },
  ]);
  instance.setEdges([
    ...baseEdges,
    { id: 'x0', source: 'n2', target: 'inserted' },
    { id: 'x1', source: 'inserted', target: 'n4' },
  ]);
  await engine.layoutIncremental({ name: 'layered', changed: ['inserted'], radius: 1 });
  instance.renderNow();
  instance.fitView(40);
}
```

The repository's [Qwik dynamic-layouting component](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/apps/demos-qwik/gallery/demos/dynamic-layouting.tsx) uses this `onInit$` flow in a Qwik-optimized application.

The visible result is a laid-out chain with `inserted` connected after `n2` and before `n4`. `movement.total` reports the total distance traveled by pre-existing nodes; `tween.movingIds` identifies which existing nodes move. The tween plan is data only: call `result.tween.at(t)` over normalized time values if your host wants to animate positions.

See the [live incremental-layout demo](https://grafloria.com/demos/layout/dynamic-layouting.html) and its [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/layout/dynamic-layouting.html).

## Options that shape the incremental pass

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `changed` | `string[]` | `[]` | Identifies newly added or edited node IDs. All other nodes count as existing for the movement report. |
| `radius` | `number` | `1` | Sets how many graph hops the affected region may spread from changed nodes. |
| `budget` | `{ maxPerNode?: number; averagePerNode?: number }` | — | Sets a maximum permitted movement per existing node or average movement. The returned report includes `withinBudget`. |

The incremental call's `name` option selects a registered layout. When prior positions came from another engine, an incremental pass can redraw the graph because the engines do not share a common layout geometry.

## Pitfalls

- Include the new node ID in `changed`; otherwise its default position can distort the baseline used to align the result.
- A declarative `layout` prop reruns when the prop value changes, not when node data changes. Call the engine method for an on-demand pass; Angular also exposes `applyLayout()` for its bound layout.
- Give the canvas wrapper a resolved height. The canvas fills its parent, so a zero-height parent renders a blank area.
- In plain JavaScript and React, custom renderers are not used unless the node spec opts into the HTML layer with `custom: true`; see [Lay out diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams).

## Related

- [Lay out diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams) for layout choices and declarative layout.
- [Add nodes from palettes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/add-nodes-from-palettes) for reconciliation behavior when node IDs remain in the data.
- [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) for undoing user edits.

<!-- source: route-and-edit-edges.md -->

# Route and edit edges

Use an edge's router to choose the path, reconnect an endpoint by dragging it to another node, and enable waypoint editing when readers need to shape a route by hand. An [edge spec](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) stores the connection and routing intent; the mounted diagram renders that intent as geometry.

## Choose a route

`type` describes the line's shape; `router` selects the path-finding behavior. The examples below put three routers on the same A-to-B corridor, with a wall in each lane. Drag a wall and compare the route.

| `router` | Behavior |
| --- | --- |
| `orthogonal` | Right-angled path from the port's exit direction. |
| `manhattan` | Grid-based right-angle routing with turn minimization. |
| `avoid` | Routes around nodes and recalculates as nodes move. |
| `elk` | Uses ELK edge routes, consistent with an ELK-laid-out graph. |
| `straight` | Direct line between endpoints. |

If `router` is unset, it is derived from `type`. The `orthogonal`, `manhattan`, and `elk` lanes below follow the routing-algorithms demo; the single-obstacle demo also shows an orthogonal route bending around a wall.

For the shared framework setup and typed node and edge specs, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows); the examples here add routing and edge-editing behavior.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '600px';
document.body.append(host);

const lanes = ['orthogonal', 'manhattan', 'elk'];
const nodes = lanes.flatMap((router, index) => {
  const y = 110 + index * 150;
  return [
    { id: `a${index}`, position: { x: 70, y: y - 24 }, size: { width: 108, height: 48 }, label: 'A' },
    { id: `b${index}`, position: { x: 760, y: y - 24 }, size: { width: 108, height: 48 }, label: 'B' },
    { id: `wall${index}`, position: { x: 410, y: y - 42 }, size: { width: 100, height: 84 }, label: router },
  ];
});
const edges = lanes.map((router, index) => ({
  id: `edge${index}`,
  source: `a${index}`,
  target: `b${index}`,
  router,
}));
const instance = render({ nodes, edges }, host);
instance.fitView();
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const lanes: NonNullable<EdgeSpec['router']>[] = ['orthogonal', 'manhattan', 'elk'];

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:600px" />
  `,
})
export class RoutingExampleComponent {
  nodes: NodeSpec[] = lanes.flatMap((router, index) => {
    const y = 110 + index * 150;
    return [
      { id: `a${index}`, position: { x: 70, y: y - 24 }, size: { width: 108, height: 48 }, label: 'A' },
      { id: `b${index}`, position: { x: 760, y: y - 24 }, size: { width: 108, height: 48 }, label: 'B' },
      { id: `wall${index}`, position: { x: 410, y: y - 42 }, size: { width: 100, height: 84 }, label: router },
    ];
  });
  edges: EdgeSpec[] = lanes.map((router, index) => ({
    id: `edge${index}`,
    source: `a${index}`,
    target: `b${index}`,
    router,
  }));
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const lanes: NonNullable<EdgeSpec['router']>[] = ['orthogonal', 'manhattan', 'elk'];
const nodes: NodeSpec[] = lanes.flatMap((router, index) => {
  const y = 110 + index * 150;
  return [
    { id: `a${index}`, position: { x: 70, y: y - 24 }, size: { width: 108, height: 48 }, label: 'A' },
    { id: `b${index}`, position: { x: 760, y: y - 24 }, size: { width: 108, height: 48 }, label: 'B' },
    { id: `wall${index}`, position: { x: 410, y: y - 42 }, size: { width: 100, height: 84 }, label: router },
  ];
});
const edges: EdgeSpec[] = lanes.map((router, index) => ({
  id: `edge${index}`,
  source: `a${index}`,
  target: `b${index}`,
  router,
}));

export function RoutingExample() {
  return (
    <div style={{ height: '600px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const lanes: NonNullable<EdgeSpec['router']>[] = ['orthogonal', 'manhattan', 'elk'];
const nodes: NodeSpec[] = lanes.flatMap((router, index) => {
  const y = 110 + index * 150;
  return [
    { id: `a${index}`, position: { x: 70, y: y - 24 }, size: { width: 108, height: 48 }, label: 'A' },
    { id: `b${index}`, position: { x: 760, y: y - 24 }, size: { width: 108, height: 48 }, label: 'B' },
    { id: `wall${index}`, position: { x: 410, y: y - 42 }, size: { width: 100, height: 84 }, label: router },
  ];
});
const edges: EdgeSpec[] = lanes.map((router, index) => ({
  id: `edge${index}`,
  source: `a${index}`,
  target: `b${index}`,
  router,
}));
</script>

<template>
  <div style="height:600px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :fit-view="true" />
  </div>
</template>
```
:::

The canvas shows three A-to-B lanes, with a labelled wall in each. Move a wall to see the route respond to the new geometry.

[Open the live routing-algorithms demo](https://grafloria.com/demos/edges/routing-algorithms.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/routing-algorithms.html).

## Reconnect an endpoint

Select the edge, then drag its endpoint handle onto a valid port on another node. The following examples pin the endpoints to named sides so the handles begin on the shown node edges.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '600px';
document.body.append(host);

const nodes = [
  { id: 'a', position: { x: 80, y: 260 }, size: { width: 120, height: 60 }, label: 'A' },
  { id: 'b', position: { x: 660, y: 110 }, size: { width: 120, height: 60 }, label: 'B' },
  { id: 'c', position: { x: 660, y: 430 }, size: { width: 120, height: 60 }, label: 'C' },
];
const edges = [{ id: 'e1', source: 'a', target: 'b', sourceHandle: 'right', targetHandle: 'left', type: 'direct' }];
const instance = render({ nodes, edges }, host);
instance.fitView();
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:600px" />
  `,
})
export class ReconnectExampleComponent {
  nodes: NodeSpec[] = [
    { id: 'a', position: { x: 80, y: 260 }, size: { width: 120, height: 60 }, label: 'A' },
    { id: 'b', position: { x: 660, y: 110 }, size: { width: 120, height: 60 }, label: 'B' },
    { id: 'c', position: { x: 660, y: 430 }, size: { width: 120, height: 60 }, label: 'C' },
  ];
  edges: EdgeSpec[] = [{
    id: 'e1', source: 'a', target: 'b', sourceHandle: 'right', targetHandle: 'left', type: 'direct',
  }];
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 80, y: 260 }, size: { width: 120, height: 60 }, label: 'A' },
  { id: 'b', position: { x: 660, y: 110 }, size: { width: 120, height: 60 }, label: 'B' },
  { id: 'c', position: { x: 660, y: 430 }, size: { width: 120, height: 60 }, label: 'C' },
];
const edges: EdgeSpec[] = [{
  id: 'e1', source: 'a', target: 'b', sourceHandle: 'right', targetHandle: 'left', type: 'direct',
}];

export function ReconnectExample() {
  return (
    <div style={{ height: '600px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 80, y: 260 }, size: { width: 120, height: 60 }, label: 'A' },
  { id: 'b', position: { x: 660, y: 110 }, size: { width: 120, height: 60 }, label: 'B' },
  { id: 'c', position: { x: 660, y: 430 }, size: { width: 120, height: 60 }, label: 'C' },
];
const edges: EdgeSpec[] = [{
  id: 'e1', source: 'a', target: 'b', sourceHandle: 'right', targetHandle: 'left', type: 'direct',
}];
</script>

<template>
  <div style="height:600px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :fit-view="true" />
  </div>
</template>
```
:::

After you select the wire between A and B, its endpoint handles appear. Drag the handle at B to C: the link now ends at C. A drop without a valid target leaves the original connection in place.

[Open the live reconnect-edge demo](https://grafloria.com/demos/edges/reconnect-edge.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/reconnect-edge.html).

## Add and move waypoints

Waypoint editing is opt-in. Enable it on the diagram, select an edge, click its path to add a bend, and drag that waypoint. Its interior path changes while the connection remains attached to both nodes.

The JavaScript sample mounts the same two-node direct edge using [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render). Its returned [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) is the live diagram instance.

For the basic mounted two-node pattern, see [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works); the Vue sample below keeps its setup runnable while adding waypoint editing on a diagonal edge.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '400px';
document.body.append(host);

const nodes = [
  { id: 'a', position: { x: 120, y: 180 }, size: { width: 150, height: 70 }, label: 'A' },
  { id: 'b', position: { x: 620, y: 180 }, size: { width: 150, height: 70 }, label: 'B' },
];
const edges = [{ id: 'e1', source: 'a', target: 'b', type: 'direct' }];
const instance = render({ nodes, edges }, host, {
  interaction: { enableWaypointEditing: true, showWaypointHandles: true },
});
instance.fitView();
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class EditableEdgeExampleComponent implements AfterViewInit {
  canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = [
    { id: 'a', position: { x: 120, y: 180 }, size: { width: 150, height: 70 }, label: 'A' },
    { id: 'b', position: { x: 620, y: 180 }, size: { width: 150, height: 70 }, label: 'B' },
  ];
  edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b', type: 'direct' }];

  ngAfterViewInit(): void {
    this.canvas().activeEngine()?.setInteractionConfig({
      enableWaypointEditing: true,
      showWaypointHandles: true,
    });
  }
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', position: { x: 120, y: 180 }, size: { width: 150, height: 70 }, label: 'A' },
  { id: 'b', position: { x: 620, y: 180 }, size: { width: 150, height: 70 }, label: 'B' },
];
const edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b', type: 'direct' }];

export function EditableEdgeExample() {
  return (
    <div style={{ height: '400px' }}>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        interaction={{ enableWaypointEditing: true, showWaypointHandles: true }}
        fitView
      />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'draft', position: { x: 100, y: 70 }, size: { width: 150, height: 70 }, label: 'Draft' },
  { id: 'review', position: { x: 540, y: 250 }, size: { width: 150, height: 70 }, label: 'Review' },
];
const edges: EdgeSpec[] = [{ id: 'review-route', source: 'draft', target: 'review', type: 'direct' }];
</script>

<template>
  <div style="height:400px">
    <GrafloriaFlow
      :default-nodes="nodes"
      :default-edges="edges"
      :interaction="{ enableWaypointEditing: true, showWaypointHandles: true }"
      :fit-view="true"
    />
  </div>
</template>
```
:::

The initial wire is straight. Once selected, clicking along its path adds a waypoint at that location; dragging the waypoint bends the line without moving either endpoint. A second path click adds another bend. Angular needs the interaction settings applied to the mounted canvas's engine; the other bindings accept them through their `interaction` prop.

[Open the live editable-edge demo](https://grafloria.com/demos/edges/editable-edge.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/editable-edge.html).

## Options and pitfalls

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `router` | `'straight' \| 'orthogonal' \| 'manhattan' \| 'avoid' \| 'elk'` or a registered router name | Derived from `type` when omitted | Chooses the edge's route. |
| `type` | `'direct' \| 'smooth' \| 'orthogonal' \| 'bezier'` | — | Chooses the edge's line shape. |
| `sourceHandle`, `targetHandle` | `string` | Not specified | Pin an endpoint to a port or side; omit them for port-facing attachment. |
| `interaction.enableWaypointEditing` | `boolean` | `false` | Allows adding, moving, or removing waypoints interactively. |
| `interaction.showWaypointHandles` | `boolean` | `true` | Shows waypoint handles on selected edges. |

- `type` and `router` answer different questions: line shape versus path selection. A connector controls corner drawing and is separate from both.
- Waypoint editing is disabled by default. Without enabling it, clicking the path does not add a bend.
- Endpoint reconnection drops onto a port. If the target is missing or invalid, the existing connection is restored.
- An edge-handles route is pinned when you give it `sourceHandle` and `targetHandle`; a hand-bent route stores its waypoints in the edge's `points` after editing.

For port compatibility and connection rules, see [Configure ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/configure-ports) and [Validate connections](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/validate-connections). For undoing edits, see [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history).

<!-- source: style-and-label-edges.md -->

# Style and label edges

Use edge specifications to choose a route, draw labels and arrowheads, and make crossing edges visibly hop. A mounted diagram renders each of these settings as part of its live graph.

This page focuses on the visual changes edge settings make in a mounted graph; for framework-specific setup and entry points, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows).

## Set route geometry and appearance

For the distinction among `type`, `router`, and `connector`, see [Diagram intent and rendering](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/diagram-intent-and-rendering); this mounted graph shows the visible differences: sharp versus rounded corners, distinct labels and markers, and hops at crossings.

The `style` field accepts a partial [`LinkStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-linkstyle#linkstyle); it carries stroke properties, arrowheads, and crossing configuration. In all the framework samples, the canvas has a fixed height so the rendered diagram has space to appear.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';
const target = document.getElementById('app');
if (!target) throw new Error('Missing #app');
target.style.height = '900px';

const nodes = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 140, height: 56 }, label: 'Direct' },
  { id: 'b', position: { x: 570, y: 150 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'c', position: { x: 80, y: 230 }, size: { width: 140, height: 56 }, label: 'Sharp step' },
  { id: 'd', position: { x: 570, y: 300 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'e', position: { x: 80, y: 380 }, size: { width: 140, height: 56 }, label: 'Rounded step' },
  { id: 'f', position: { x: 570, y: 450 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'g', position: { x: 80, y: 530 }, size: { width: 140, height: 56 }, label: 'Bezier' },
  { id: 'h', position: { x: 570, y: 600 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'i', position: { x: 760, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross A' },
  { id: 'j', position: { x: 1040, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross D' },
  { id: 'k', position: { x: 760, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross B' },
  { id: 'l', position: { x: 1040, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross C' },
];

const edges = [
  { id: 'direct', source: 'a', target: 'b', type: 'direct', label: 'direct', labelPlacement: 'above', labelStyle: { color: '#1d4ed8', fontSize: 12 }, style: { stroke: '#2563eb', strokeWidth: 2, arrowHead: { type: 'arrow', size: 14, filled: true } } },
  { id: 'sharp', source: 'c', target: 'd', router: 'orthogonal', connector: 'straight', label: 'sharp corners', labelPlacement: 'above', style: { stroke: '#475569', strokeDasharray: '6 3', arrowHead: { type: 'diamond', size: 14, filled: false } } },
  { id: 'rounded', source: 'e', target: 'f', router: 'orthogonal', connector: 'rounded', label: 'rounded corners', labelPlacement: 'below', labelStyle: { background: '#eff6ff', padding: 4, borderRadius: 4 }, style: { stroke: '#059669', strokeWidth: 2, arrowHead: { type: 'crow-foot', size: 14, filled: false } } },
  { id: 'curve', source: 'g', target: 'h', type: 'bezier', label: 'no arrowhead', style: { stroke: '#9333ea', strokeWidth: 2, arrowHead: { type: 'none', size: 14, filled: false } } },
  { id: 'cross-ad', source: 'i', target: 'l', type: 'direct', style: { stroke: '#0f766e', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
  { id: 'cross-bc', source: 'k', target: 'j', type: 'direct', style: { stroke: '#b91c1c', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
];

render({ nodes, edges }, target);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:900px" />
  `,
})
export class EdgeStylesComponent {
  nodes = [
    { id: 'a', position: { x: 80, y: 80 }, size: { width: 140, height: 56 }, label: 'Direct' },
    { id: 'b', position: { x: 570, y: 150 }, size: { width: 140, height: 56 }, label: 'Target' },
    { id: 'c', position: { x: 80, y: 230 }, size: { width: 140, height: 56 }, label: 'Sharp step' },
    { id: 'd', position: { x: 570, y: 300 }, size: { width: 140, height: 56 }, label: 'Target' },
    { id: 'e', position: { x: 80, y: 380 }, size: { width: 140, height: 56 }, label: 'Rounded step' },
    { id: 'f', position: { x: 570, y: 450 }, size: { width: 140, height: 56 }, label: 'Target' },
    { id: 'g', position: { x: 80, y: 530 }, size: { width: 140, height: 56 }, label: 'Bezier' },
    { id: 'h', position: { x: 570, y: 600 }, size: { width: 140, height: 56 }, label: 'Target' },
    { id: 'i', position: { x: 760, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross A' },
    { id: 'j', position: { x: 1040, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross D' },
    { id: 'k', position: { x: 760, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross B' },
    { id: 'l', position: { x: 1040, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross C' },
  ];
  edges: EdgeSpec[] = [
    { id: 'direct', source: 'a', target: 'b', type: 'direct', label: 'direct', labelPlacement: 'above', labelStyle: { color: '#1d4ed8', fontSize: 12 }, style: { stroke: '#2563eb', strokeWidth: 2, arrowHead: { type: 'arrow', size: 14, filled: true } } },
    { id: 'sharp', source: 'c', target: 'd', router: 'orthogonal', connector: 'straight', label: 'sharp corners', labelPlacement: 'above', style: { stroke: '#475569', strokeDasharray: '6 3', arrowHead: { type: 'diamond', size: 14, filled: false } } },
    { id: 'rounded', source: 'e', target: 'f', router: 'orthogonal', connector: 'rounded', label: 'rounded corners', labelPlacement: 'below', labelStyle: { background: '#eff6ff', padding: 4, borderRadius: 4 }, style: { stroke: '#059669', strokeWidth: 2, arrowHead: { type: 'crow-foot', size: 14, filled: false } } },
    { id: 'curve', source: 'g', target: 'h', type: 'bezier', label: 'no arrowhead', style: { stroke: '#9333ea', strokeWidth: 2, arrowHead: { type: 'none', size: 14, filled: false } } },
    { id: 'cross-ad', source: 'i', target: 'l', type: 'direct', style: { stroke: '#0f766e', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
    { id: 'cross-bc', source: 'k', target: 'j', type: 'direct', style: { stroke: '#b91c1c', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
  ];
}
```
```tsx title="Qwik"
import { render as renderQwik } from '@builder.io/qwik';
import { GrafloriaFlow, type EdgeSpec } from '@grafloria/qwik';

const nodes = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 140, height: 56 }, label: 'Direct' },
  { id: 'b', position: { x: 570, y: 150 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'c', position: { x: 80, y: 230 }, size: { width: 140, height: 56 }, label: 'Sharp step' },
  { id: 'd', position: { x: 570, y: 300 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'e', position: { x: 80, y: 380 }, size: { width: 140, height: 56 }, label: 'Rounded step' },
  { id: 'f', position: { x: 570, y: 450 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'g', position: { x: 80, y: 530 }, size: { width: 140, height: 56 }, label: 'Bezier' },
  { id: 'h', position: { x: 570, y: 600 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'i', position: { x: 760, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross A' },
  { id: 'j', position: { x: 1040, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross D' },
  { id: 'k', position: { x: 760, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross B' },
  { id: 'l', position: { x: 1040, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross C' },
];
const edges: EdgeSpec[] = [
  { id: 'direct', source: 'a', target: 'b', type: 'direct', label: 'direct', labelPlacement: 'above', labelStyle: { color: '#1d4ed8', fontSize: 12 }, style: { stroke: '#2563eb', strokeWidth: 2, arrowHead: { type: 'arrow', size: 14, filled: true } } },
  { id: 'sharp', source: 'c', target: 'd', router: 'orthogonal', connector: 'straight', label: 'sharp corners', labelPlacement: 'above', style: { stroke: '#475569', strokeDasharray: '6 3', arrowHead: { type: 'diamond', size: 14, filled: false } } },
  { id: 'rounded', source: 'e', target: 'f', router: 'orthogonal', connector: 'rounded', label: 'rounded corners', labelPlacement: 'below', labelStyle: { background: '#eff6ff', padding: 4, borderRadius: 4 }, style: { stroke: '#059669', strokeWidth: 2, arrowHead: { type: 'crow-foot', size: 14, filled: false } } },
  { id: 'curve', source: 'g', target: 'h', type: 'bezier', label: 'no arrowhead', style: { stroke: '#9333ea', strokeWidth: 2, arrowHead: { type: 'none', size: 14, filled: false } } },
  { id: 'cross-ad', source: 'i', target: 'l', type: 'direct', style: { stroke: '#0f766e', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
  { id: 'cross-bc', source: 'k', target: 'j', type: 'direct', style: { stroke: '#b91c1c', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
];

const target = typeof document === 'undefined' ? null : document.createElement('div');
if (target) {
  target.style.height = '900px';
  document.body.append(target);
  void renderQwik(target, <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />);
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec } from '@grafloria/renderer';

const nodes = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 140, height: 56 }, label: 'Direct' },
  { id: 'b', position: { x: 570, y: 150 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'c', position: { x: 80, y: 230 }, size: { width: 140, height: 56 }, label: 'Sharp step' },
  { id: 'd', position: { x: 570, y: 300 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'e', position: { x: 80, y: 380 }, size: { width: 140, height: 56 }, label: 'Rounded step' },
  { id: 'f', position: { x: 570, y: 450 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'g', position: { x: 80, y: 530 }, size: { width: 140, height: 56 }, label: 'Bezier' },
  { id: 'h', position: { x: 570, y: 600 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'i', position: { x: 760, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross A' },
  { id: 'j', position: { x: 1040, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross D' },
  { id: 'k', position: { x: 760, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross B' },
  { id: 'l', position: { x: 1040, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross C' },
];
const edges: EdgeSpec[] = [
  { id: 'direct', source: 'a', target: 'b', type: 'direct', label: 'direct', labelPlacement: 'above', labelStyle: { color: '#1d4ed8', fontSize: 12 }, style: { stroke: '#2563eb', strokeWidth: 2, arrowHead: { type: 'arrow', size: 14, filled: true } } },
  { id: 'sharp', source: 'c', target: 'd', router: 'orthogonal', connector: 'straight', label: 'sharp corners', labelPlacement: 'above', style: { stroke: '#475569', strokeDasharray: '6 3', arrowHead: { type: 'diamond', size: 14, filled: false } } },
  { id: 'rounded', source: 'e', target: 'f', router: 'orthogonal', connector: 'rounded', label: 'rounded corners', labelPlacement: 'below', labelStyle: { background: '#eff6ff', padding: 4, borderRadius: 4 }, style: { stroke: '#059669', strokeWidth: 2, arrowHead: { type: 'crow-foot', size: 14, filled: false } } },
  { id: 'curve', source: 'g', target: 'h', type: 'bezier', label: 'no arrowhead', style: { stroke: '#9333ea', strokeWidth: 2, arrowHead: { type: 'none', size: 14, filled: false } } },
  { id: 'cross-ad', source: 'i', target: 'l', type: 'direct', style: { stroke: '#0f766e', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
  { id: 'cross-bc', source: 'k', target: 'j', type: 'direct', style: { stroke: '#b91c1c', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
];

export default function EdgeStyles() {
  return (
    <div style={{ height: '900px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec } from '@grafloria/renderer';

const nodes = [
  { id: 'a', position: { x: 80, y: 80 }, size: { width: 140, height: 56 }, label: 'Direct' },
  { id: 'b', position: { x: 570, y: 150 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'c', position: { x: 80, y: 230 }, size: { width: 140, height: 56 }, label: 'Sharp step' },
  { id: 'd', position: { x: 570, y: 300 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'e', position: { x: 80, y: 380 }, size: { width: 140, height: 56 }, label: 'Rounded step' },
  { id: 'f', position: { x: 570, y: 450 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'g', position: { x: 80, y: 530 }, size: { width: 140, height: 56 }, label: 'Bezier' },
  { id: 'h', position: { x: 570, y: 600 }, size: { width: 140, height: 56 }, label: 'Target' },
  { id: 'i', position: { x: 760, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross A' },
  { id: 'j', position: { x: 1040, y: 680 }, size: { width: 120, height: 48 }, label: 'Cross D' },
  { id: 'k', position: { x: 760, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross B' },
  { id: 'l', position: { x: 1040, y: 840 }, size: { width: 120, height: 48 }, label: 'Cross C' },
];
const edges: EdgeSpec[] = [
  { id: 'direct', source: 'a', target: 'b', type: 'direct', label: 'direct', labelPlacement: 'above', labelStyle: { color: '#1d4ed8', fontSize: 12 }, style: { stroke: '#2563eb', strokeWidth: 2, arrowHead: { type: 'arrow', size: 14, filled: true } } },
  { id: 'sharp', source: 'c', target: 'd', router: 'orthogonal', connector: 'straight', label: 'sharp corners', labelPlacement: 'above', style: { stroke: '#475569', strokeDasharray: '6 3', arrowHead: { type: 'diamond', size: 14, filled: false } } },
  { id: 'rounded', source: 'e', target: 'f', router: 'orthogonal', connector: 'rounded', label: 'rounded corners', labelPlacement: 'below', labelStyle: { background: '#eff6ff', padding: 4, borderRadius: 4 }, style: { stroke: '#059669', strokeWidth: 2, arrowHead: { type: 'crow-foot', size: 14, filled: false } } },
  { id: 'curve', source: 'g', target: 'h', type: 'bezier', label: 'no arrowhead', style: { stroke: '#9333ea', strokeWidth: 2, arrowHead: { type: 'none', size: 14, filled: false } } },
  { id: 'cross-ad', source: 'i', target: 'l', type: 'direct', style: { stroke: '#0f766e', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
  { id: 'cross-bc', source: 'k', target: 'j', type: 'direct', style: { stroke: '#b91c1c', jumpPoints: { enabled: true, size: 10, detectMode: 'all' } } },
];
</script>

<template>
  <div style="height:900px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" />
  </div>
</template>
```
:::

The first four rows render four distinct path families. `router: 'orthogonal'` keeps both step routes axis-aligned; changing `connector` from `'straight'` to `'rounded'` changes their corner treatment without changing that routing choice. Each row also renders its own label and marker style. The two lower edges cross, and one draws a small hop at the crossing.

## Place and style labels

Set `label` to put text on an edge. `labelPlacement: 'on'` places it on the line in its own box; `'above'` and `'below'` place it beside the line without that box. `labelStyle` controls the label's color, size, weight, family, and background. In the example, the direct edge's label has blue text and sits above its line, while the rounded route's label has a pale background and sits below.

Labels belong to the edge path: when its route changes, the label follows the route. In the live label demo, drag the label along the wire, then move a node to see the edge and label re-route together.

## Choose edge markers

Set `style.arrowHead` to a built-in marker type. The sample uses `arrow`, `diamond`, and `crow-foot`; `none` explicitly renders no arrowhead. The head stays at the endpoint as the route changes. The live marker demo shows the full built-in set: `arrow`, `open-arrow`, `circle`, `square`, `diamond`, `crow-foot`, `hollow-diamond`, and `one-or-many`, as well as `none`.

## Show crossings

Give crossing edges `style.jumpPoints` with `enabled: true` to draw an arc where a line crosses another. The lower pair in the sample starts in an X, so the owning edge renders a hop. Move a node until the lines no longer cross and the hop disappears; move it back and the hop returns. `size` controls the arc size in pixels, and `detectMode: 'all'` selects all crossings.

## Options used here

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `type` | `'direct' \| 'smooth' \| 'orthogonal' \| 'bezier'` | Not specified | Selects a path family. |
| `router` | [`LinkRouterName`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-types#linkroutername) | Derived from `type` when unset | Chooses where the line goes. |
| `connector` | [`LinkConnectorName`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-types#linkconnectorname) | Derived from `type` when unset | Chooses how the route is drawn. |
| `label` | `string` | Not specified | Adds text to the edge. |
| `labelPlacement` | `'on' \| 'above' \| 'below'` | `'on'` | Places the label on, above, or below the edge. |
| `labelStyle` | [`LabelStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-interfaces-b-r#labelstyle) | Not specified | Sets label color, size, weight, family, and background. |
| `style` | `Partial<LinkStyle>` | Not specified | Sets the link's visual style, including stroke and arrowheads. |
| `style.jumpPoints` | `JumpPointConfig` | Disabled unless enabled | Controls edge hops at crossings. `size` defaults to 10 px and `detectMode` to `'all'`. |

These values live on the edge spec; you do not need to reach into the model to style a link. The route and connector answer different questions, so changing the connector does not select a new router. For more routing options and saved bends, see [Route and edit edges](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/route-and-edit-edges).

## Live demos and related pages

- [Edge types](https://grafloria.com/demos/edges/edge-types.html) — [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/edge-types.html)
- [Edge labels](https://grafloria.com/demos/edges/edge-labels.html) — [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/edge-labels.html)
- [Edge markers](https://grafloria.com/demos/edges/edge-markers.html) — [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/edge-markers.html)
- [Jump-overs](https://grafloria.com/demos/edges/jump-overs.html) — [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/edges/jump-overs.html)
- [Route and edit edges](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/route-and-edit-edges)
- [Theme and style diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/theme-and-style-diagrams)

<!-- source: group-nodes-and-containers.md -->

# Group nodes and containers

Create a visible container and add nodes to its membership.

Use a group when a set of nodes needs a real container relationship, not only a decorative rectangle: the engine tracks membership. This page shows the task in JavaScript, Angular, Qwik, Vue, and React.

Unlike the mounted workflow graph in [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows), this task adds explicit group membership: a node travels with a frame because its ID is a member, not because it overlaps the frame. See that page for framework mounting and instance setup.

## Create a frame and add members

In Angular, Vue, and React, mount ordinary node data, then use the mounted instance's engine to create a group, set its frame, and add node IDs to it. The renderer shows the frame behind the nodes. Membership is explicit: a node does not become a member merely because it overlaps the frame.

For groups declared with the diagram data, use [`GroupSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance#groupspec). The JavaScript and Qwik examples declare the group in their initial specifications; Angular, Vue, and React add it through the mounted engine.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '400px';
document.body.append(host);

const nodes = [
  { id: 'ingest', position: { x: 320, y: 160 }, size: { width: 120, height: 60 }, label: 'ingest' },
  { id: 'transform', position: { x: 520, y: 160 }, size: { width: 120, height: 60 }, label: 'transform' },
  { id: 'retry', position: { x: 420, y: 280 }, size: { width: 120, height: 60 }, label: 'retry' },
];
const edges = [
  { id: 'e1', source: 'ingest', target: 'transform' },
  { id: 'e2', source: 'ingest', target: 'retry' },
];
const groups = [
  {
    id: 'pipeline',
    label: 'Pipeline',
    children: ['ingest', 'transform', 'retry'],
    bounds: { x: 290, y: 120, width: 400, height: 240 },
  },
];

render({ nodes, edges, groups }, host);
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class PipelineComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = [
    { id: 'ingest', position: { x: 320, y: 160 }, size: { width: 120, height: 60 }, label: 'ingest' },
    { id: 'transform', position: { x: 520, y: 160 }, size: { width: 120, height: 60 }, label: 'transform' },
    { id: 'retry', position: { x: 420, y: 280 }, size: { width: 120, height: 60 }, label: 'retry' },
  ];
  edges: EdgeSpec[] = [
    { id: 'e1', source: 'ingest', target: 'transform' },
    { id: 'e2', source: 'ingest', target: 'retry' },
  ];

  async ngAfterViewInit(): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    const pipeline = await engine.addGroup({ name: 'Pipeline' });
    pipeline.setFrame({ x: 290, y: 120, width: 400, height: 240 });
    await engine.addToGroup(pipeline.id, 'ingest');
    await engine.addToGroup(pipeline.id, 'transform');
    await engine.addToGroup(pipeline.id, 'retry');
  }
}
```
```tsx title="Qwik"
import { component$ } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { EdgeSpec, GroupSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 320, y: 160 }, size: { width: 120, height: 60 }, label: 'ingest' },
  { id: 'transform', position: { x: 520, y: 160 }, size: { width: 120, height: 60 }, label: 'transform' },
  { id: 'retry', position: { x: 420, y: 280 }, size: { width: 120, height: 60 }, label: 'retry' },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'ingest', target: 'transform' },
  { id: 'e2', source: 'ingest', target: 'retry' },
];
const groups: GroupSpec[] = [
  {
    id: 'pipeline',
    label: 'Pipeline',
    children: ['ingest', 'transform', 'retry'],
    bounds: { x: 290, y: 120, width: 400, height: 240 },
  },
];

export default component$(() => (
  <div style={{ height: '400px' }}>
    <GrafloriaFlow nodes={nodes} edges={edges} groups={groups} />
  </div>
));
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 320, y: 160 }, size: { width: 120, height: 60 }, label: 'ingest' },
  { id: 'transform', position: { x: 520, y: 160 }, size: { width: 120, height: 60 }, label: 'transform' },
  { id: 'retry', position: { x: 420, y: 280 }, size: { width: 120, height: 60 }, label: 'retry' },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'ingest', target: 'transform' },
  { id: 'e2', source: 'ingest', target: 'retry' },
];

async function onInit(instance: DiagramInstance): Promise<void> {
  const engine = instance.getEngine();
  const pipeline = await engine.addGroup({ name: 'Pipeline' });
  pipeline.setFrame({ x: 290, y: 120, width: 400, height: 240 });
  await engine.addToGroup(pipeline.id, 'ingest');
  await engine.addToGroup(pipeline.id, 'transform');
  await engine.addToGroup(pipeline.id, 'retry');
  instance.renderNow();
}
</script>

<template>
  <div style="height:400px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
  </div>
</template>
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ingest', position: { x: 320, y: 160 }, size: { width: 120, height: 60 }, label: 'ingest' },
  { id: 'transform', position: { x: 520, y: 160 }, size: { width: 120, height: 60 }, label: 'transform' },
  { id: 'retry', position: { x: 420, y: 280 }, size: { width: 120, height: 60 }, label: 'retry' },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'ingest', target: 'transform' },
  { id: 'e2', source: 'ingest', target: 'retry' },
];

export function Pipeline() {
  const onInit = async (instance: DiagramInstance): Promise<void> => {
    const engine = instance.getEngine();
    const pipeline = await engine.addGroup({ name: 'Pipeline' });
    pipeline.setFrame({ x: 290, y: 120, width: 400, height: 240 });
    await engine.addToGroup(pipeline.id, 'ingest');
    await engine.addToGroup(pipeline.id, 'transform');
    await engine.addToGroup(pipeline.id, 'retry');
    instance.renderNow();
  };

  return (
    <div style={{ height: 400 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} onInit={onInit} />
    </div>
  );
}
```
:::

The examples render three ordinary nodes inside a labelled **Pipeline** frame, with two edges still connecting them. The frame's coordinates are in diagram world space.

For a nested container, create another group, add its node members, and add that group's ID to the outer group. Call `fitToContents()` from the inner group outward when the frames need to wrap their contents. Membership remains a model relationship rather than a rule inferred from current node positions.

## Group definition options

For groups declared in diagram data instead of added after mount, use [`GroupSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance#groupspec). A group spec defines the frame and its initial member node IDs.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `id` | `string` | — | Identifies the group. |
| `label` | `string` | — | Supplies the frame's visible label. |
| `children` | `string[]` | — | Names the node IDs that become members. |
| `bounds` | `{ x: number; y: number; width: number; height: number }` | — | Pins the frame to a world-space rectangle; without it, the frame fits around its children using `padding`. |
| `padding` | `number` | `20` | Sets the space between the children and a fitted frame. |
| `labelPlacement` | `GroupLabelPlacement` | `'top-left'` | Places the frame label. |
| `style` | `GroupFrameStyle` | — | Sets the frame's style. |

## What to watch for

- Set a real height on the canvas wrapper. The canvas fills its parent; an unresolved height leaves no drawing area.
- Use `addToGroup(groupId, entityId)` in that order. It returns a promise, so await it before treating membership as complete.
- A node positioned inside a frame is not necessarily a member. Add it to the group explicitly.
- Groups and membership are edits made through engine operations; use the engine's history APIs for undo and redo rather than looking for those methods on the instance.

## See it running

- [Group frames](https://grafloria.com/demos/grouping/group-frames.html) — visible labelled frames, including a nested frame.
- [Sub-flow](https://grafloria.com/demos/grouping/sub-flow.html) — nested group membership and fit-to-contents behavior.

For collapsing and expanding a group, see [Collapse and expand groups](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/collapse-and-expand-groups). For the model behind groups and membership, see [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document).

<!-- source: collapse-and-expand-groups.md -->

# Collapse and expand groups

Collapse a group into a compact placeholder, then expand it to restore its members and connections.

## When to use this

Use collapse when readers need to focus on the surrounding graph without losing a group's contents. The diagram engine treats the group as a container: collapsing hides its members, moves crossing links to a placeholder, and merges parallel crossings; expanding restores the saved state.

## Set up a group and add collapse controls

1. Render nodes and edges, then add a group around the member nodes. The instance gives you the [`DiagramEngine`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-engine#diagramengine) through `getEngine()`; `addGroup()` creates the group, and `addToGroup()` assigns its members.
2. Call `collapseGroup(groupId, options?)` or `expandGroup(groupId)` from your controls. Both calls return promises, so await them before treating the operation as complete.

The example places three member nodes inside the Service group. On load, all five nodes and four links are visible. Click **collapse group**: the three members disappear, the group becomes a Service placeholder, and links crossing the group boundary attach to the placeholder. The two links from `ext 1` merge into one proxy link labelled `2×`; the internal member link disappears while collapsed. Click **expand group** to restore the three members, their original positions, and all four links.

This page adds collapse and expand controls to the mounted diagram; for mounting the canvas and retrieving its instance in each framework, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows).

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const toolbar = document.createElement('div');
const collapseButton = document.createElement('button');
const expandButton = document.createElement('button');
const host = document.createElement('div');
collapseButton.textContent = 'collapse group';
expandButton.textContent = 'expand group';
host.style.height = '480px';
toolbar.append(collapseButton, expandButton);
document.body.append(toolbar, host);

const nodes = [
  { id: 'ext1', position: { x: 60, y: 80 }, size: { width: 120, height: 60 }, label: 'ext 1' },
  { id: 'ext2', position: { x: 60, y: 300 }, size: { width: 120, height: 60 }, label: 'ext 2' },
  { id: 'm1', position: { x: 420, y: 80 }, size: { width: 120, height: 60 }, label: 'member 1' },
  { id: 'm2', position: { x: 420, y: 200 }, size: { width: 120, height: 60 }, label: 'member 2' },
  { id: 'm3', position: { x: 420, y: 320 }, size: { width: 120, height: 60 }, label: 'member 3' },
];
const edges = [
  { id: 'a', source: 'ext1', target: 'm1' },
  { id: 'b', source: 'ext1', target: 'm2' },
  { id: 'c', source: 'ext2', target: 'm3' },
  { id: 'd', source: 'm1', target: 'm2' },
];

async function mountDiagram() {
  const instance = render({ nodes, edges }, host);
  const engine = instance.getEngine();
  const group = await engine.addGroup({ name: 'Service' });
  group.setFrame({ x: 400, y: 60, width: 180, height: 340 });
  for (const id of ['m1', 'm2', 'm3']) {
    await engine.addToGroup(group.id, id);
  }
  instance.fitView(40);
  instance.renderNow();

  collapseButton.addEventListener('click', async () => {
    await engine.collapseGroup(group.id, { proxyLabel: (info) => `${info.count}×` });
    instance.renderNow();
  });
  expandButton.addEventListener('click', async () => {
    await engine.expandGroup(group.id);
    instance.renderNow();
  });
}

void mountDiagram();
```
```tsx title="Angular"
import { AfterViewInit, Component, ViewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="display:flex;gap:8px;padding:10px 24px">
      <button type="button" (click)="collapse()">collapse group</button>
      <button type="button" (click)="expand()">expand group</button>
    </div>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:480px" />
  `,
})
export class CollapseExpandComponent implements AfterViewInit {
  @ViewChild(DiagramCanvasComponent) private canvas!: DiagramCanvasComponent;
  nodes: NodeSpec[] = [
    { id: 'ext1', position: { x: 60, y: 80 }, size: { width: 120, height: 60 }, label: 'ext 1' },
    { id: 'ext2', position: { x: 60, y: 300 }, size: { width: 120, height: 60 }, label: 'ext 2' },
    { id: 'm1', position: { x: 420, y: 80 }, size: { width: 120, height: 60 }, label: 'member 1' },
    { id: 'm2', position: { x: 420, y: 200 }, size: { width: 120, height: 60 }, label: 'member 2' },
    { id: 'm3', position: { x: 420, y: 320 }, size: { width: 120, height: 60 }, label: 'member 3' },
  ];
  edges: EdgeSpec[] = [
    { id: 'a', source: 'ext1', target: 'm1' },
    { id: 'b', source: 'ext1', target: 'm2' },
    { id: 'c', source: 'ext2', target: 'm3' },
    { id: 'd', source: 'm1', target: 'm2' },
  ];
  private groupId: string | undefined;

  async ngAfterViewInit(): Promise<void> {
    const engine = this.canvas.activeEngine();
    if (!engine) return;
    const group = await engine.addGroup({ name: 'Service' });
    group.setFrame({ x: 400, y: 60, width: 180, height: 340 });
    for (const id of ['m1', 'm2', 'm3']) {
      await engine.addToGroup(group.id, id);
    }
    this.groupId = group.id;
  }

  async collapse(): Promise<void> {
    const engine = this.canvas.activeEngine();
    if (engine && this.groupId) {
      await engine.collapseGroup(this.groupId, { proxyLabel: (info) => `${info.count}×` });
    }
  }

  async expand(): Promise<void> {
    const engine = this.canvas.activeEngine();
    if (engine && this.groupId) await engine.expandGroup(this.groupId);
  }
}
```
```tsx title="Qwik"
import { $, component$ } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ext1', position: { x: 60, y: 80 }, size: { width: 120, height: 60 }, label: 'ext 1' },
  { id: 'ext2', position: { x: 60, y: 300 }, size: { width: 120, height: 60 }, label: 'ext 2' },
  { id: 'm1', position: { x: 420, y: 80 }, size: { width: 120, height: 60 }, label: 'member 1' },
  { id: 'm2', position: { x: 420, y: 200 }, size: { width: 120, height: 60 }, label: 'member 2' },
  { id: 'm3', position: { x: 420, y: 320 }, size: { width: 120, height: 60 }, label: 'member 3' },
];
const edges: EdgeSpec[] = [
  { id: 'a', source: 'ext1', target: 'm1' },
  { id: 'b', source: 'ext1', target: 'm2' },
  { id: 'c', source: 'ext2', target: 'm3' },
  { id: 'd', source: 'm1', target: 'm2' },
];

export default component$(() => (
  <div id="qwik-collapse-demo" style={{ height: '520px' }}>
    <GrafloriaFlow
      defaultNodes={nodes}
      defaultEdges={edges}
      style={{ height: '480px' }}
      onInit$={$(async (api: DiagramInstance) => {
        const engine = api.getEngine();
        const group = await engine.addGroup({ name: 'Service' });
        group.setFrame({ x: 400, y: 60, width: 180, height: 340 });
        for (const id of ['m1', 'm2', 'm3']) {
          await engine.addToGroup(group.id, id);
        }

        const toolbar = document.createElement('div');
        const collapseButton = document.createElement('button');
        const expandButton = document.createElement('button');
        toolbar.style.display = 'flex';
        toolbar.style.gap = '8px';
        toolbar.style.padding = '10px 24px';
        collapseButton.type = 'button';
        collapseButton.textContent = 'collapse group';
        expandButton.type = 'button';
        expandButton.textContent = 'expand group';
        toolbar.append(collapseButton, expandButton);
        const root = document.getElementById('qwik-collapse-demo');
        root?.prepend(toolbar);

        collapseButton.addEventListener('click', async () => {
          await engine.collapseGroup(group.id, { proxyLabel: (info) => `${info.count}×` });
          api.renderNow();
        });
        expandButton.addEventListener('click', async () => {
          await engine.expandGroup(group.id);
          api.renderNow();
        });
        api.renderNow();
      })}
    />
  </div>
));
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ext1', position: { x: 60, y: 80 }, size: { width: 120, height: 60 }, label: 'ext 1' },
  { id: 'ext2', position: { x: 60, y: 300 }, size: { width: 120, height: 60 }, label: 'ext 2' },
  { id: 'm1', position: { x: 420, y: 80 }, size: { width: 120, height: 60 }, label: 'member 1' },
  { id: 'm2', position: { x: 420, y: 200 }, size: { width: 120, height: 60 }, label: 'member 2' },
  { id: 'm3', position: { x: 420, y: 320 }, size: { width: 120, height: 60 }, label: 'member 3' },
];
const edges: EdgeSpec[] = [
  { id: 'a', source: 'ext1', target: 'm1' },
  { id: 'b', source: 'ext1', target: 'm2' },
  { id: 'c', source: 'ext2', target: 'm3' },
  { id: 'd', source: 'm1', target: 'm2' },
];

export default function CollapseExpandDemo() {
  const instance = useRef<DiagramInstance | null>(null);
  const groupId = useRef<string | undefined>(undefined);

  const collapse = async () => {
    const api = instance.current;
    const id = groupId.current;
    if (!api || !id) return;
    await api.getEngine().collapseGroup(id, { proxyLabel: (info) => `${info.count}×` });
    api.renderNow();
  };
  const expand = async () => {
    const api = instance.current;
    const id = groupId.current;
    if (!api || !id) return;
    await api.getEngine().expandGroup(id);
    api.renderNow();
  };

  const onInit = async (api: DiagramInstance): Promise<void> => {
    instance.current = api;
    const engine = api.getEngine();
    const group = await engine.addGroup({ name: 'Service' });
    group.setFrame({ x: 400, y: 60, width: 180, height: 340 });
    for (const id of ['m1', 'm2', 'm3']) {
      await engine.addToGroup(group.id, id);
    }
    groupId.current = group.id;
    api.renderNow();
  };

  return (
    <div style={{ height: '520px' }}>
      <div style={{ display: 'flex', gap: 8, padding: '10px 24px' }}>
        <button type="button" onClick={() => void collapse()}>collapse group</button>
        <button type="button" onClick={() => void expand()}>expand group</button>
      </div>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        onInit={onInit}
        style={{ height: '480px' }}
      />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'ext1', position: { x: 60, y: 80 }, size: { width: 120, height: 60 }, label: 'ext 1' },
  { id: 'ext2', position: { x: 60, y: 300 }, size: { width: 120, height: 60 }, label: 'ext 2' },
  { id: 'm1', position: { x: 420, y: 80 }, size: { width: 120, height: 60 }, label: 'member 1' },
  { id: 'm2', position: { x: 420, y: 200 }, size: { width: 120, height: 60 }, label: 'member 2' },
  { id: 'm3', position: { x: 420, y: 320 }, size: { width: 120, height: 60 }, label: 'member 3' },
];
const edges: EdgeSpec[] = [
  { id: 'a', source: 'ext1', target: 'm1' },
  { id: 'b', source: 'ext1', target: 'm2' },
  { id: 'c', source: 'ext2', target: 'm3' },
  { id: 'd', source: 'm1', target: 'm2' },
];

let instance: DiagramInstance | null = null;
let groupId: string | undefined;

async function onInit(api: DiagramInstance): Promise<void> {
  instance = api;
  const engine = api.getEngine();
  const group = await engine.addGroup({ name: 'Service' });
  group.setFrame({ x: 400, y: 60, width: 180, height: 340 });
  for (const id of ['m1', 'm2', 'm3']) {
    await engine.addToGroup(group.id, id);
  }
  groupId = group.id;
  api.renderNow();
}

async function collapse(): Promise<void> {
  if (!instance || !groupId) return;
  await instance.getEngine().collapseGroup(groupId, { proxyLabel: (info) => `${info.count}×` });
  instance.renderNow();
}

async function expand(): Promise<void> {
  if (!instance || !groupId) return;
  await instance.getEngine().expandGroup(groupId);
  instance.renderNow();
}
</script>

<template>
  <div style="height:520px">
    <div style="display:flex;gap:8px;padding:10px 24px">
      <button type="button" @click="collapse">collapse group</button>
      <button type="button" @click="expand">expand group</button>
    </div>
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
      @init="onInit" :style="{ height: '480px' }" />
  </div>
</template>
```
:::

Each sample renders the same five nodes and four links. Its setup creates the Service group and assigns `m1`, `m2`, and `m3`; the buttons await the engine operation. The JavaScript, Qwik, React, and Vue samples call `renderNow()` after the change. The Angular sample gets the active engine from its canvas view.

## Options that affect the result

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `groupId` | `string` | Required | Identifies the group to collapse or expand. |
| `options` | `CollapseOptions` | `undefined` | Optional collapse settings. |
| `CollapseOptions.proxyLabel` | `(info: ProxyLabelInfo) => string` | The crossing count as a string when greater than one; no synthetic label for a single crossing | Supplies the label for each aggregated proxy link. Returning an empty string suppresses the label. |

`collapseGroup()` resolves after the engine executes the collapse command; `expandGroup()` resolves after it executes the expand command. Both calls operate on the live diagram through its instance's engine. The collapse snapshot retains member positions and prior group geometry; expanding restores those positions and geometry, restores removed links, and removes the placeholder. Internal links are removed while collapsed. Boundary links are grouped by external node and direction, with one proxy link retained per group.

An empty group has no member nodes to hide, so it collapses without creating a placeholder. For the compact visual representation shown here, add member nodes before collapsing.

## Try the live demo

Open the [Collapse & expand demo](https://grafloria.com/demos/grouping/collapse-expand.html) to see the member nodes hide, boundary links re-home to the placeholder, and the parallel links merge into one labelled proxy. The demo source is [collapse-expand.html](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/grouping/collapse-expand.html).

## Related

- [Group nodes and containers](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/group-nodes-and-containers) — create groups and manage membership.
- [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) — understand the engine commands behind edits.

<!-- source: navigate-diagrams.md -->

# Navigate diagrams

Add viewport controls, make visible detail respond to zoom, and support touch navigation in a mounted diagram. The canvas and camera share one headless model across framework bindings.

## Add a minimap, controls, and zoom-level feedback

Use the shipped canvas plugins for the minimap, zoom/fit toolbar, and dotted background; the plugin-enabled canvas also supports the built-in pan, zoom, tap-selection, node-drag, and pinch gestures. Add your own zoom choices through the mounted instance when you want a predictable detail readout: the renderer chooses a level-of-detail tier from the current zoom. The JavaScript, Angular, React, and Vue samples disable the adaptive quality governor so the tier follows zoom directly, matching the contextual-zoom demo.

Each sample mounts a small connected diagram and leaves room for touch navigation. JavaScript, Angular, Qwik, React, and Vue show the minimap and shipped zoom/fit controls; only React and Vue add buttons with a tier readout. Angular displays its chosen zoom. The renderer changes detail as the camera zooms, without application code rewriting node data.

Build on the mounting and typed-data pattern in [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows): this page adds the minimap, zoom-level controls and rendered-tier feedback, plus touch navigation. The Angular example uses [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent).

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';
import { attachCanvasPlugins } from '@grafloria/renderer';

const nodes = Array.from({ length: 9 }, (_, i) => ({
  id: `n${i}`,
  position: { x: 90 + (i % 3) * 300, y: 70 + Math.floor(i / 3) * 190 },
  size: { width: 170, height: 74 },
  data: { label: `Step ${i + 1}` },
}));
const edges = Array.from({ length: 8 }, (_, i) => ({
  id: `e${i}`, source: `n${i}`, target: `n${i + 1}`,
}));

const app = document.createElement('main');
app.style.height = '100vh';
const host = document.createElement('div');
host.style.cssText = 'height:100%;touch-action:none';
document.body.append(app);
app.append(host);

const instance = render({ nodes, edges }, host, { renderer: { qualityGovernor: false } });
attachCanvasPlugins(instance, {
  background: { variant: 'dots' },
  minimap: true,
  controls: true,
});
instance.fitView(40);
instance.renderNow();
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <main style="height:100vh;display:flex;flex-direction:column">
      <div>
        <button type="button" (click)="setZoom(1.5)">1.5×</button>
        <button type="button" (click)="setZoom(0.7)">0.7×</button>
        <button type="button" (click)="setZoom(0.3)">0.3×</button>
        <button type="button" (click)="setZoom(0.15)">0.15×</button>
        <output>zoom {{ zoom }}×</output>
      </div>
      <grafloria-diagram-canvas
        [(nodes)]="nodes"
        [(edges)]="edges"
        [plugins]="true"
        [rendererConfig]="{ qualityGovernor: false }"
        style="display:block;flex:1;min-height:0;touch-action:none" />
    </main>
  `,
})
export class NavigateDiagramsComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  zoom = 1;
  nodes: NodeSpec[] = Array.from({ length: 9 }, (_, i) => ({
    id: `n${i}`,
    position: { x: 90 + (i % 3) * 300, y: 70 + Math.floor(i / 3) * 190 },
    size: { width: 170, height: 74 },
    data: { label: `Step ${i + 1}` },
  }));
  edges: EdgeSpec[] = Array.from({ length: 8 }, (_, i) => ({
    id: `e${i}`, source: `n${i}`, target: `n${i + 1}`,
  }));

  ngAfterViewInit(): void {
    this.canvas().fitToContent(40);
  }

  setZoom(zoom: number): void {
    this.canvas().viewportController()?.setZoom(zoom);
    this.zoom = zoom;
  }
}
```
```tsx title="Qwik"
import { component$, $, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow, type EdgeSpec, type NodeSpec } from '@grafloria/qwik';

const nodes: NodeSpec[] = Array.from({ length: 9 }, (_, i) => ({
  id: `n${i}`,
  position: { x: 90 + (i % 3) * 300, y: 70 + Math.floor(i / 3) * 190 },
  size: { width: 170, height: 74 },
  data: { label: `Step ${i + 1}` },
}));
const edges: EdgeSpec[] = Array.from({ length: 8 }, (_, i) => ({
  id: `e${i}`, source: `n${i}`, target: `n${i + 1}`,
}));

export default component$(() => {
  const ready = useSignal(false);
  return (
    <main style={{ height: '100vh', display: 'flex', flexDirection: 'column', touchAction: 'none' }}>
      <output>{ready.value ? 'Diagram ready' : 'Loading diagram'}</output>
      <div style={{ flex: '1', minHeight: '0' }}>
        <GrafloriaFlow
          defaultNodes={nodes}
          defaultEdges={edges}
          plugins
          rendererConfig={{ qualityGovernor: false }}
          onInit$={$(() => { ready.value = true; })}
        />
      </div>
    </main>
  );
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/react';

const nodes: NodeSpec[] = Array.from({ length: 9 }, (_, i) => ({
  id: `n${i}`,
  position: { x: 90 + (i % 3) * 300, y: 70 + Math.floor(i / 3) * 190 },
  size: { width: 170, height: 74 },
  data: { label: `Step ${i + 1}` },
}));
const edges: EdgeSpec[] = Array.from({ length: 8 }, (_, i) => ({
  id: `e${i}`, source: `n${i}`, target: `n${i + 1}`,
}));

export default function NavigateDiagrams() {
  const instance = useRef<DiagramInstance | null>(null);
  const [tier, setTier] = useState('');
  const zoomTo = (zoom: number) => {
    const api = instance.current;
    if (!api) return;
    api.viewport.setZoom(zoom);
    api.renderNow();
    setTier(`Selected ${zoom}×; zoom ${api.viewport.getZoom()}× — ${api.getQualityState().tier}`);
  };

  return (
    <main style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <div>
        <button onClick={() => zoomTo(1.5)}>1.5×</button>
        <button onClick={() => zoomTo(0.7)}>0.7×</button>
        <button onClick={() => zoomTo(0.3)}>0.3×</button>
        <button onClick={() => zoomTo(0.15)}>0.15×</button>
        <output>{tier}</output>
      </div>
      <div style={{ flex: 1, minHeight: 0, touchAction: 'none' }}>
        <GrafloriaFlow
          defaultNodes={nodes}
          defaultEdges={edges}
          plugins
          rendererConfig={{ qualityGovernor: false }}
          onInit={(api: DiagramInstance) => {
            instance.current = api;
            api.fitView(40);
            api.renderNow();
            setTier(`Current zoom ${api.viewport.getZoom()}× — ${api.getQualityState().tier}`);
          }}
        />
      </div>
    </main>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/vue';

const nodes: NodeSpec[] = Array.from({ length: 9 }, (_, i) => ({
  id: `n${i}`,
  position: { x: 90 + (i % 3) * 300, y: 70 + Math.floor(i / 3) * 190 },
  size: { width: 170, height: 74 },
  data: { label: `Step ${i + 1}` },
}));
const edges: EdgeSpec[] = Array.from({ length: 8 }, (_, i) => ({
  id: `e${i}`, source: `n${i}`, target: `n${i + 1}`,
}));
const tier = ref('');
let instance: DiagramInstance | null = null;

function zoomTo(zoom: number): void {
  if (!instance) return;
  instance.viewport.setZoom(zoom);
  instance.renderNow();
  tier.value = `Selected ${zoom}×; zoom ${instance.viewport.getZoom()}× — ${instance.getQualityState().tier}`;
}

function onInit(api: DiagramInstance): void {
  instance = api;
  api.fitView(40);
  api.renderNow();
  tier.value = `Current zoom ${api.viewport.getZoom()}× — ${api.getQualityState().tier}`;
}
</script>

<template>
  <main style="height:100vh;display:flex;flex-direction:column">
    <div>
      <button @click="zoomTo(1.5)">1.5×</button>
      <button @click="zoomTo(0.7)">0.7×</button>
      <button @click="zoomTo(0.3)">0.3×</button>
      <button @click="zoomTo(0.15)">0.15×</button>
      <output>{{ tier }}</output>
    </div>
    <div style="flex:1;min-height:0;touch-action:none">
      <GrafloriaFlow
        :default-nodes="nodes"
        :default-edges="edges"
        :plugins="true"
        :renderer-config="{ qualityGovernor: false }"
        @init="onInit"
      />
    </div>
  </main>
</template>
```
:::

In the React and Vue samples, the buttons set zoom to 1.5×, 0.7×, 0.3×, or 0.15× and the readout shows the tier reported after each selection. The tiers are high, medium, sketch, and low at those zoom levels in the contextual-zoom demo, and rendered detail falls as you zoom out. Angular displays its current zoom value. JavaScript and Qwik use the minimap and zoom/fit toolbar; Qwik's status output changes when its canvas initializes.

The minimap mirrors the nodes and camera; its camera rectangle follows navigation. On a touch screen, drag empty canvas to pan, pinch to zoom, tap a node to select it, or drag a node with one finger. The canvas container uses `touch-action: none` so the browser does not consume those gestures for page scrolling or zooming.

## Options that affect navigation

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `plugins` | `boolean \| CanvasPluginOptions` | Off unless enabled | On a framework canvas, `true` mounts the minimap, zoom/fit controls, and background grid. In JavaScript, configure those pieces with `attachCanvasPlugins()`. |
| `minZoom` | `number` | `0.1` | Sets the camera's lower zoom bound. |
| `maxZoom` | `number` | `3.0` | Sets the camera's upper zoom bound. |
| `zoomSensitivity` | `number` | `0.1` | Sets the relative step per wheel notch or keyboard zoom. |
| `enablePan` | `boolean` | Enabled | Enables canvas panning. |
| `enableZoom` | `boolean` | Enabled | Enables canvas zooming. Angular names the wheel option `enableMouseWheelZoom`; touch zoom uses the shared gesture pipeline. |
| `rendererConfig.qualityGovernor` | `boolean \| GovernorOptions` | Enabled | The adaptive governor can adjust detail under load. Set it to `false` when you want detail tier to follow zoom alone, as in the sample. |

`NodeSpec` and `EdgeSpec` are the framework data types used for the mounted graph. The instance-level camera methods and the Angular `viewportController()` provide the same zoom operation; the Angular example binds the canvas through its component rather than constructing a second camera.

Use the `plugins` prop when its default minimap, controls, and grid suit the editor. Use `attachCanvasPlugins()` when mounting through `render()` and when you need to choose plugin options separately. The instance's `viewport` controller sets zoom and reads the current zoom; `getQualityState()` reports the tier actually rendered.

## Pitfalls

- Give the canvas a resolved height. It fills its parent; a zero-height parent appears blank.
- Keep touch handling on the canvas area: `touch-action: none` prevents native browser gestures from interrupting pointer movement.
- The zoom values in the sample are choices for its buttons, not universal thresholds. `minZoom` and `maxZoom` clamp camera movement; use the tier readout and your own diagram to choose useful stops.

## See it running

- [Minimap & controls](https://grafloria.com/demos/misc/minimap-and-controls.html) — see the live minimap, its moving camera rectangle, zoom controls, and fit-view behavior. [Demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/misc/minimap-and-controls.html)
- [Contextual zoom (LOD)](https://grafloria.com/demos/interaction/contextual-zoom.html) — compare the high, medium, sketch, and low tiers as zoom changes. [Demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/contextual-zoom.html)
- [Touch device](https://grafloria.com/demos/interaction/touch-device.html) — try pan, pinch, tap-to-select, and node dragging on a touch screen or in device emulation. [Demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/interaction/touch-device.html)

## Related

- [DiagramInstance](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance)
- [Canvas plugins](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-components)
- [The element API](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core)
- [Angular canvas component](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent)

<!-- source: theme-and-style-diagrams.md -->

# Theme and style diagrams

Use a [theme](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-interfaces-t-v) for the diagram-wide palette, then use node specs for individual differences. A named style class lets you reuse a set of node styles; `strokeWidth` sets a node's border width.

Start with [LIGHT_THEME](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-constants) or [DARK_THEME](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-constants) for the overall palette. A node's spec supplies local styling, and a mounted [DiagramInstance](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance) can update the theme or reconcile node specs without replacing the diagram. For plain JavaScript, [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) mounts the spec and returns that instance.

## Register styles and mount a styled diagram

Call [`defineStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-functions) before mounting the diagram, and refer to each named style in a node's `style.styleClass`. The JavaScript sample uses [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec) values and an [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec) list. It mounts three nodes: the `priority` node combines `warn` and `bold`; the second node overrides the named class's fill with an inline green fill; the third keeps the theme's node styling. Click **Toggle theme** to switch the mounted diagram's palette. Click **Emphasize priority** to change only the node whose id is `priority` to a 9px stroke.

The names are prefixed to avoid collisions with other named styles in the application. Named styles are applied in order, so the later `bold` definition overrides `warn`'s `strokeWidth`; an element's own inline style overrides a named class. The cascade is theme, type default, named class, element inline, then state.

```ts
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/renderer';

async function mountStyledDiagram(): Promise<void> {
const { render, defineStyle } = await import('@grafloria/element');
const { DARK_THEME, LIGHT_THEME } = await import('@grafloria/renderer');

const WARN = 'guide-warn';
const BOLD = 'guide-bold';
defineStyle(WARN, { fill: '#f97316', stroke: '#9a3412', strokeWidth: 2 });
defineStyle(BOLD, { strokeWidth: 6 });

const nodes: NodeSpec[] = [
  {
    id: 'priority',
    position: { x: 50, y: 60 },
    size: { width: 190, height: 78 },
    data: { label: 'warn + bold' },
    style: { styleClass: `${WARN} ${BOLD}` },
  },
  {
    id: 'override',
    position: { x: 280, y: 60 },
    size: { width: 190, height: 78 },
    data: { label: 'warn + inline fill' },
    style: { styleClass: WARN, fill: '#22c55e' },
  },
  {
    id: 'plain',
    position: { x: 510, y: 60 },
    size: { width: 190, height: 78 },
    data: { label: 'theme default' },
  },
];
const edges: EdgeSpec[] = [];
const themeButton = document.createElement('button');
themeButton.type = 'button';
themeButton.textContent = 'Toggle theme';
const emphasizeButton = document.createElement('button');
emphasizeButton.type = 'button';
emphasizeButton.textContent = 'Emphasize priority';
const canvas = document.createElement('div');
canvas.style.height = '220px';
document.body.append(themeButton, emphasizeButton, canvas);

let themeIsDark = false;
let emphasized = false;
const instance: DiagramInstance = render(
  { nodes, edges },
  canvas,
  { theme: LIGHT_THEME },
);

themeButton.onclick = () => {
  themeIsDark = !themeIsDark;
  instance.setTheme(themeIsDark ? DARK_THEME : LIGHT_THEME);
};

emphasizeButton.onclick = () => {
  emphasized = !emphasized;
  instance.setNodes(nodes.map((node) =>
    node.id === 'priority'
      ? { ...node, style: { ...node.style, strokeWidth: emphasized ? 9 : 6 } }
      : node,
  ));
  instance.renderNow();
};
}

void mountStyledDiagram();
```

The JavaScript example creates a sized canvas and its controls, then uses [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) to get the live instance. `setTheme()` changes that instance's theme, and `setNodes()` reconciles the full node list. Keep the other nodes in the array: `setNodes()` reconciles the diagram, including removing nodes that are missing from the next list.

## Use the diagram in Angular, React, Vue, and Qwik

These versions render the same named-class and inline-style examples. Angular and React switch themes by changing the component's `theme` input; Vue mounts with `DARK_THEME` as its component input. The Qwik sample mounts through `render()` in a visible task and keeps the live instance out of serialized state. [GrafloriaFlow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik) provides the React and Vue canvas; Angular uses [DiagramCanvasComponent](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent). Each canvas has a resolved height.

:::code-group
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { defineStyle } from '@grafloria/renderer';
import {
  DARK_THEME,
  LIGHT_THEME,
  type EdgeSpec,
  type NodeSpec,
  type Theme,
} from '@grafloria/renderer';

const WARN = 'guide-angular-warn';
const BOLD = 'guide-angular-bold';
defineStyle(WARN, { fill: '#f97316', stroke: '#9a3412', strokeWidth: 2 });
defineStyle(BOLD, { strokeWidth: 6 });

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="toggleTheme()">Toggle theme</button>
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      [theme]="theme"
      style="display: block; height: 220px" />
  `,
})
export class StyledDiagramComponent {
  theme: Theme = LIGHT_THEME;
  nodes: NodeSpec[] = [
    {
      id: 'priority', position: { x: 50, y: 60 }, size: { width: 190, height: 78 },
      data: { label: 'warn + bold' }, style: { styleClass: `${WARN} ${BOLD}` },
    },
    {
      id: 'override', position: { x: 280, y: 60 }, size: { width: 190, height: 78 },
      data: { label: 'warn + inline fill' }, style: { styleClass: WARN, fill: '#22c55e' },
    },
    {
      id: 'plain', position: { x: 510, y: 60 }, size: { width: 190, height: 78 },
      data: { label: 'theme default' },
    },
  ];
  edges: EdgeSpec[] = [];

  toggleTheme(): void {
    this.theme = this.theme === LIGHT_THEME ? DARK_THEME : LIGHT_THEME;
  }
}
```
```tsx title="Qwik"
import {
  $,
  component$,
  noSerialize,
  useSignal,
  useVisibleTask$,
  type NoSerialize,
} from '@builder.io/qwik';
import { defineStyle, render } from '@grafloria/element';
import { DARK_THEME, LIGHT_THEME } from '@grafloria/renderer';
import type { DiagramInstance, EdgeSpec, NodeSpec } from '@grafloria/renderer';

const WARN = 'guide-qwik-warn';
const BOLD = 'guide-qwik-bold';
const nodes: NodeSpec[] = [
  {
    id: 'priority', position: { x: 50, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + bold' }, style: { styleClass: `${WARN} ${BOLD}` },
  },
  {
    id: 'override', position: { x: 280, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + inline fill' }, style: { styleClass: WARN, fill: '#22c55e' },
  },
  {
    id: 'plain', position: { x: 510, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'theme default' },
  },
];
const edges: EdgeSpec[] = [];

export default component$(() => {
  const host = useSignal<HTMLElement>();
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const dark = useSignal(true);
  const emphasized = useSignal(false);

  useVisibleTask$(({ cleanup }) => {
    const element = host.value;
    if (!element) return;
    defineStyle(WARN, { fill: '#f97316', stroke: '#9a3412', strokeWidth: 2 });
    defineStyle(BOLD, { strokeWidth: 6 });
    const api = render({ nodes, edges }, element, { theme: DARK_THEME });
    instance.value = noSerialize(api);
    cleanup(() => api.dispose());
  });

  const toggleTheme = $(() => {
    const api = instance.value;
    if (!api) return;
    dark.value = !dark.value;
    api.setTheme(dark.value ? DARK_THEME : LIGHT_THEME);
  });

  const emphasizePriority = $(() => {
    const api = instance.value;
    if (!api) return;
    emphasized.value = !emphasized.value;
    api.setNodes(nodes.map((node) =>
      node.id === 'priority'
        ? { ...node, style: { ...node.style, strokeWidth: emphasized.value ? 9 : 6 } }
        : node,
    ));
    api.renderNow();
  });

  return (
    <div>
      <button type="button" onClick$={toggleTheme}>Toggle theme</button>
      <button type="button" onClick$={emphasizePriority}>Emphasize priority</button>
      <div ref={host} style={{ height: '220px' }} />
    </div>
  );
});
```
```tsx title="React"
import { useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import { defineStyle } from '@grafloria/element';
import { DARK_THEME, LIGHT_THEME } from '@grafloria/renderer';
import type { EdgeSpec, NodeSpec, Theme } from '@grafloria/renderer';

const WARN = 'guide-react-warn';
const BOLD = 'guide-react-bold';
defineStyle(WARN, { fill: '#f97316', stroke: '#9a3412', strokeWidth: 2 });
defineStyle(BOLD, { strokeWidth: 6 });

const nodes: NodeSpec[] = [
  {
    id: 'priority', position: { x: 50, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + bold' }, style: { styleClass: `${WARN} ${BOLD}` },
  },
  {
    id: 'override', position: { x: 280, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + inline fill' }, style: { styleClass: WARN, fill: '#22c55e' },
  },
  {
    id: 'plain', position: { x: 510, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'theme default' },
  },
];
const edges: EdgeSpec[] = [];

export function StyledDiagram() {
  const [theme, setTheme] = useState<Theme>(LIGHT_THEME);
  return (
    <div style={{ height: 260 }}>
      <button type="button" onClick={() => {
        setTheme((current) => current === LIGHT_THEME ? DARK_THEME : LIGHT_THEME);
      }}>Toggle theme</button>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} theme={theme} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import { defineStyle } from '@grafloria/element';
import { DARK_THEME } from '@grafloria/renderer';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const WARN = 'guide-vue-warn';
const BOLD = 'guide-vue-bold';
defineStyle(WARN, { fill: '#f97316', stroke: '#9a3412', strokeWidth: 2 });
defineStyle(BOLD, { strokeWidth: 6 });

const nodes: NodeSpec[] = [
  {
    id: 'priority', position: { x: 50, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + bold' }, style: { styleClass: `${WARN} ${BOLD}` },
  },
  {
    id: 'override', position: { x: 280, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'warn + inline fill' }, style: { styleClass: WARN, fill: '#22c55e' },
  },
  {
    id: 'plain', position: { x: 510, y: 60 }, size: { width: 190, height: 78 },
    data: { label: 'theme default' },
  },
];
const edges: EdgeSpec[] = [];
</script>

<template>
  <div style="height: 260px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :theme="DARK_THEME" />
  </div>
</template>
```
:::

In each component, the `priority` node's id and style travel together in its spec. Change a mounted node by id through the instance's `setNodes()` method, as in the JavaScript sample; pass the full node list so reconciliation keeps the other nodes. The frameworks use the same theme and node-style data because each binding feeds the same diagram model.

## Options that affect the result

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `theme` | `Theme` | `LIGHT_THEME` | Supplies the canvas palette and default node and link styles. |
| `style.styleClass` | `string` | None | Names one or more registered styles for a node; separate multiple names with spaces. |
| `style.strokeWidth` | `number` | Theme's node default | Sets the node's border width; a later cascade layer can override it. |

The cascade makes conflicts predictable: an inline node style overrides its named class, while selection and other state styling sit above both. An unknown style-class name contributes no style. Keep named-style names distinctive: named styles use an application-wide registry.

## See the demos

The [Named style classes demo](https://grafloria.com/demos/styling/named-style-classes.html) shows class stacking, inline overrides, and selection styling. Its initial view has an orange `warn` node, a green inline-fill override, and a thicker `warn bold` node.

The [Dark mode demo](https://grafloria.com/demos/styling/dark-mode.html) demonstrates the theme palette change on a rendered diagram.

## Related

- [Lay out diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams)
- [Resize and size nodes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/resize-and-size-nodes)

<!-- source: import-and-round-trip-diagrams.md -->

# Import and round-trip diagrams

Import Mermaid-compatible text—including a `.mmd` file—into a live, editable canvas, then export the same diagram back to text without flattening it into an image.

Use the canvas instance: [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) exposes `loadText()` and `exportText()`. Loading reconciles the parsed diagram into the mounted model, so its renderer and listeners remain attached. Exported text includes a Grafloria document sidecar by default: an untouched import/export round-trip retains the full document, while the readable Mermaid body remains available to other Mermaid tools.

## Import and export in the browser

Use this pattern when a user supplies Mermaid text or a text file. The file picker accepts `.mmd`, `.mermaid`, and `.txt`; the file contents—not the file wrapper—are passed to the canvas. The JavaScript, Angular, React, and Vue examples start with two real nodes and an edge, then import or export on demand. The Qwik example mounts its editable canvas from typed node and edge specs. Give each canvas a sized parent so it can draw.

### JavaScript

```js
import { render } from '@grafloria/element';

const app = document.createElement('main');
app.style.cssText = 'font: 14px sans-serif; padding: 12px;';
const file = document.createElement('input');
file.type = 'file';
file.accept = '.mmd,.mermaid,.txt';
const loadButton = document.createElement('button');
loadButton.type = 'button';
loadButton.textContent = 'Load text';
const exportButton = document.createElement('button');
exportButton.type = 'button';
exportButton.textContent = 'Export text';
const editor = document.createElement('textarea');
editor.setAttribute('aria-label', 'Mermaid diagram text');
editor.style.cssText = 'display:block;box-sizing:border-box;width:100%;height:150px;margin:8px 0;';
const status = document.createElement('p');
const host = document.createElement('div');
host.style.cssText = 'height:420px;width:100%;';
app.append(file, loadButton, exportButton, editor, status, host);
document.body.append(app);

const nodes = [
  { id: 'start', position: { x: 60, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
  { id: 'finish', position: { x: 300, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Finish' } },
];
const edges = [{ id: 'next', source: 'start', target: 'finish' }];
const instance = render({ nodes, edges }, host);
editor.value = instance.exportText();

function applyText(source) {
  const result = instance.loadText(source);
  status.textContent = result.unsupported
    ? `Unsupported diagram type: ${result.unsupported}`
    : `Loaded from ${result.source}${result.bodyEdited ? ' (text body edited)' : ''}.`;
}

loadButton.addEventListener('click', () => applyText(editor.value));
exportButton.addEventListener('click', () => {
  editor.value = instance.exportText();
  status.textContent = 'Exported the live diagram to Mermaid-compatible text.';
});
file.addEventListener('change', async () => {
  const selected = file.files?.[0];
  if (!selected) return;
  editor.value = await selected.text();
  applyText(editor.value);
});
```

The page mounts a two-node diagram, and Export text fills the editor with its Mermaid-compatible representation and lossless sidecar. Load text or choose a text file to update the same editable canvas. This uses [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) to mount the spec and the returned instance to do the round-trip.

### Angular

```ts
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="display:flex;gap:8px;align-items:center">
      <input type="file" accept=".mmd,.mermaid,.txt" (change)="loadFile($event)" />
      <button type="button" (click)="loadText()">Load text</button>
      <button type="button" (click)="exportText()">Export text</button>
    </div>
    <textarea aria-label="Mermaid diagram text" [value]="text" (input)="editText($event)"
      style="box-sizing:border-box;width:100%;height:150px;margin:8px 0"></textarea>
    <p>{{ status }}</p>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;width:100%;height:420px" />
  `,
})
export class ImportTextComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = [
    { id: 'start', position: { x: 60, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
    { id: 'finish', position: { x: 300, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Finish' } },
  ];
  edges: EdgeSpec[] = [{ id: 'next', source: 'start', target: 'finish' }];
  text = '';
  status = 'Export text to begin.';

  ngAfterViewInit(): void {
    this.text = this.canvas().exportText();
  }

  editText(event: Event): void {
    this.text = (event.currentTarget as HTMLTextAreaElement).value;
  }

  async loadFile(event: Event): Promise<void> {
    const input = event.currentTarget as HTMLInputElement;
    const selected = input.files?.[0];
    if (!selected) return;
    this.text = await selected.text();
    this.loadText();
  }

  loadText(): void {
    this.canvas().loadText(this.text);
    this.status = 'Applied the Mermaid-compatible text to the canvas.';
  }

  exportText(): void {
    this.text = this.canvas().exportText();
    this.status = 'Exported the live diagram to Mermaid-compatible text.';
  }
}
```

Here the mounted [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) owns the live diagram. Choosing a text file or clicking Load text reconciles its text into the canvas; Export text writes the live diagram back to the textarea. The Angular canvas methods return text for export and apply text to the existing diagram for import.

### Qwik

```tsx
import { component$ } from '@builder.io/qwik';
import { GrafloriaFlow, type EdgeSpec, type NodeSpec } from '@grafloria/qwik';

const nodes: NodeSpec[] = [
  { id: 'start', position: { x: 60, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
  { id: 'finish', position: { x: 300, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Finish' } },
];
const edges: EdgeSpec[] = [{ id: 'next', source: 'start', target: 'finish' }];

export default component$(() => (
  <div style={{ width: '100%', height: '420px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
  </div>
));
```

The Qwik [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow) mounts the typed specs as an editable canvas. Use `loadText()` and `exportText()` on the live instance for the text round-trip described above.

### React

```tsx
import { useRef, useState, type ChangeEvent } from 'react';
import { GrafloriaFlow, type DiagramInstance, type EdgeSpec, type NodeSpec } from '@grafloria/react';

const nodes: NodeSpec[] = [
  { id: 'start', position: { x: 60, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
  { id: 'finish', position: { x: 300, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Finish' } },
];
const edges: EdgeSpec[] = [{ id: 'next', source: 'start', target: 'finish' }];

export function ImportTextDiagram() {
  const instance = useRef<DiagramInstance | null>(null);
  const [text, setText] = useState('');
  const [status, setStatus] = useState('The canvas is ready.');

  function applyText(source: string): void {
    const live = instance.current;
    if (!live) return;
    const result = live.loadText(source);
    setStatus(result.unsupported
      ? `Unsupported diagram type: ${result.unsupported}`
      : `Loaded from ${result.source}${result.bodyEdited ? ' (text body edited)' : ''}.`);
  }

  async function loadFile(event: ChangeEvent<HTMLInputElement>): Promise<void> {
    const selected = event.currentTarget.files?.[0];
    if (!selected) return;
    const source = await selected.text();
    setText(source);
    applyText(source);
  }

  function exportText(): void {
    const live = instance.current;
    if (!live) return;
    setText(live.exportText());
    setStatus('Exported the live diagram to Mermaid-compatible text.');
  }

  return (
    <div>
      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
        <input type="file" accept=".mmd,.mermaid,.txt" onChange={loadFile} />
        <button type="button" onClick={() => applyText(text)}>Load text</button>
        <button type="button" onClick={exportText}>Export text</button>
      </div>
      <textarea aria-label="Mermaid diagram text" value={text}
        onChange={(event) => setText(event.currentTarget.value)}
        style={{ boxSizing: 'border-box', width: '100%', height: 150, margin: '8px 0' }} />
      <p>{status}</p>
      <div style={{ width: '100%', height: 420 }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} onInit={(api) => {
          instance.current = api;
          setText(api.exportText());
        }} />
      </div>
    </div>
  );
}
```

The React [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow) callback keeps the instance in a ref across renders. Load text and file selection both apply the editor contents to that instance; Export text replaces the editor contents with the current diagram's text.

### Vue

```vue
<script setup lang="ts">
import { shallowRef, ref } from 'vue';
import { GrafloriaFlow, type DiagramInstance, type EdgeSpec, type NodeSpec } from '@grafloria/vue';

const nodes: NodeSpec[] = [
  { id: 'start', position: { x: 60, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
  { id: 'finish', position: { x: 300, y: 70 }, size: { width: 140, height: 60 }, data: { label: 'Finish' } },
];
const edges: EdgeSpec[] = [{ id: 'next', source: 'start', target: 'finish' }];
const instance = shallowRef<DiagramInstance | null>(null);
const text = ref('');
const status = ref('The canvas is ready.');

function onInit(api: DiagramInstance): void {
  instance.value = api;
  text.value = api.exportText();
}

function applyText(source: string): void {
  const live = instance.value;
  if (!live) return;
  const result = live.loadText(source);
  status.value = result.unsupported
    ? `Unsupported diagram type: ${result.unsupported}`
    : `Loaded from ${result.source}${result.bodyEdited ? ' (text body edited)' : ''}.`;
}

async function loadFile(event: Event): Promise<void> {
  const input = event.currentTarget as HTMLInputElement;
  const selected = input.files?.[0];
  if (!selected) return;
  const source = await selected.text();
  text.value = source;
  applyText(source);
}

function exportText(): void {
  const live = instance.value;
  if (!live) return;
  text.value = live.exportText();
  status.value = 'Exported the live diagram to Mermaid-compatible text.';
}
</script>

<template>
  <div>
    <div style="display:flex;gap:8px;align-items:center">
      <input type="file" accept=".mmd,.mermaid,.txt" @change="loadFile" />
      <button type="button" @click="applyText(text)">Load text</button>
      <button type="button" @click="exportText">Export text</button>
    </div>
    <textarea aria-label="Mermaid diagram text" v-model="text"
      style="box-sizing:border-box;width:100%;height:150px;margin:8px 0"></textarea>
    <p>{{ status }}</p>
    <div style="width:100%;height:420px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
    </div>
  </div>
</template>
```

The Vue [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow) emits its init callback with the live instance. The shallow ref keeps that instance unproxied; loading changes the canvas, while export replaces the textarea value with a new text representation.

## Text format and options

[`importDiagramText`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization#importdiagramtext), which `loadText()` uses, returns an [`ImportTextResult`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization#importtextresult) describing the parsed model, which source won, and whether a sidecar body was edited. If a Mermaid type is recognized but unsupported, `unsupported` names it instead of guessing at a flowchart. The example status displays that result; unsupported text does not render as a valid diagram.

An exported sidecar keeps the full Grafloria document for an untouched round trip. If a reader edits the Mermaid body, the default `auto` preference applies that body over the sidecar document: text structure and labels reflect the edit while data Mermaid cannot express, such as positions, styles, ports, and groups, remains from the sidecar. Pure Mermaid text has no sidecar and parses on a best-effort basis.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `prefer` on [`ImportTextOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization#importtextoptions) | `'auto' \| 'sidecar' \| 'text'` | `'auto'` | Chooses which source wins when the text contains both a sidecar and a body. `auto` uses the sidecar unless the body hash shows a hand edit; `sidecar` ignores body edits; `text` parses the body and ignores the sidecar. |

The import reconciles into the existing diagram rather than replacing the instance; listeners, plugins, and the renderer stay attached. It is the model—not a screenshot—that the text sidecar carries. See [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the document and model relationship.

## What the demos show

The [Mermaid text demo](https://grafloria.com/demos/misc/mermaid-text.html) starts with a Mermaid-shaped text pane and a rendered three-node flow. Its sidecar supports an unchanged, lossless round-trip; edit `build[Build]` to `build[Verify]` and the canvas reflects the body edit while the other nodes remain.

The [Mermaid viewer demo](https://grafloria.com/demos/misc/mermaid-viewer.html) provides a paste-and-apply workflow for supported Mermaid diagram types. It names unsupported types instead of rendering them as a misleading flowchart.

For `.drawio` XML rather than Mermaid text, see the [draw.io import demo](https://grafloria.com/demos/misc/drawio-import.html). It demonstrates plain and compressed imports, multi-page files, and editable canvas models.

For the separate workflow of embedding a model in an exported SVG or PNG and reopening it as an editable diagram, see the [editable round-trip demo](https://grafloria.com/demos/misc/editable-round-trip.html).

## Pitfalls

- `loadText()` reconciles entities by id. If you need a genuinely fresh document and the incoming text reuses ids, clear the current data before applying it; see [Add nodes from palettes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/add-nodes-from-palettes) for the reconciliation warning.
- Untouched sidecar text carries more than Mermaid structure. Removing its `%%grafloria` comments leaves pure Mermaid, which parses best-effort and cannot retain every Grafloria-only detail.
- The canvas fills its parent. Keep a real height on the wrapper; otherwise the imported diagram has no visible drawing area.

## Related

- [Mermaid & the text format](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization) — import and export behavior, sidecars, and supported Mermaid syntax.
- [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document) — the editable document represented by the sidecar.
- [Export diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/export-diagrams) — image and document export options.

<!-- source: export-diagrams.md -->

# Export diagrams

This page covers live diagram exports in JavaScript, Angular, React and Vue, plus server-side SVG output; Qwik is outside its scope. Use it when you need a downloadable image or PDF from a live diagram, or a static SVG from a server process with no DOM. The server-side path uses the framework-independent static renderer.

For how to mount a diagram and obtain its live instance in JavaScript and the framework bindings, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows); this page adds image and PDF downloads plus DOM-free SVG rendering.

## Download an image from a live diagram

Mount a real diagram first, then call the instance's async `export()` method from a user action. PNG returns an image data URL; SVG returns its source string, which you can wrap in an SVG data URL for download. The export includes the diagram's rendered labels, edges and styling; PNG at `scale: 2` requests a 2× raster.

1. Mount a diagram with at least one node and edge, then call `export()` from a user action. The examples use the same three-node flow; their buttons download `diagram.png` or `diagram.svg` from the mounted canvas.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '400px';
const pngButton = document.createElement('button');
pngButton.textContent = 'Download PNG';
const svgButton = document.createElement('button');
svgButton.textContent = 'Download SVG';
const status = document.createElement('span');
document.body.append(pngButton, svgButton, status, host);

const instance = render({
  nodes: [
    { id: 'ingest', label: 'Ingest', position: { x: 40, y: 80 }, size: { width: 150, height: 66 } },
    { id: 'transform', label: 'Transform', position: { x: 260, y: 80 }, size: { width: 150, height: 66 } },
    { id: 'publish', label: 'Publish', position: { x: 480, y: 80 }, size: { width: 150, height: 66 } },
  ],
  edges: [
    { id: 'e1', source: 'ingest', target: 'transform', label: 'rows' },
    { id: 'e2', source: 'transform', target: 'publish' },
  ],
}, host);

instance.renderNow();

function download(href, name) {
  const anchor = document.createElement('a');
  anchor.href = href;
  anchor.download = name;
  anchor.click();
}

async function downloadPng() {
  const image = await instance.export('png', { scale: 2 });
  download(image, 'diagram.png');
  status.textContent = 'PNG download started.';
}

async function downloadSvg() {
  const svg = await instance.export('svg');
  download(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`, 'diagram.svg');
  status.textContent = 'SVG download started.';
}

pngButton.addEventListener('click', downloadPng);
svgButton.addEventListener('click', downloadSvg);
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="downloadPng()">Download PNG</button>
    <button type="button" (click)="downloadSvg()">Download SVG</button>
    <span>{{ note }}</span>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class DiagramExportComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  note = 'Choose an image format to download.';

  nodes: NodeSpec[] = [
    { id: 'ingest', label: 'Ingest', position: { x: 40, y: 80 }, size: { width: 150, height: 66 } },
    { id: 'transform', label: 'Transform', position: { x: 260, y: 80 }, size: { width: 150, height: 66 } },
    { id: 'publish', label: 'Publish', position: { x: 480, y: 80 }, size: { width: 150, height: 66 } },
  ];
  edges: EdgeSpec[] = [
    { id: 'e1', source: 'ingest', target: 'transform', label: 'rows' },
    { id: 'e2', source: 'transform', target: 'publish' },
  ];

  async downloadPng(): Promise<void> {
    const href = await this.canvas().exportDiagram('png', { scale: 2 });
    this.download(href, 'diagram.png');
    this.note = 'PNG download started.';
  }

  async downloadSvg(): Promise<void> {
    const svg = await this.canvas().exportDiagram('svg');
    this.download(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`, 'diagram.svg');
    this.note = 'SVG download started.';
  }

  private download(href: string, name: string): void {
    const anchor = document.createElement('a');
    anchor.href = href;
    anchor.download = name;
    anchor.click();
  }
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { ref } from 'vue';

const nodes: NodeSpec[] = [
  { id: 'ingest', label: 'Ingest', position: { x: 40, y: 80 }, size: { width: 150, height: 66 } },
  { id: 'transform', label: 'Transform', position: { x: 260, y: 80 }, size: { width: 150, height: 66 } },
  { id: 'publish', label: 'Publish', position: { x: 480, y: 80 }, size: { width: 150, height: 66 } },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'ingest', target: 'transform', label: 'rows' },
  { id: 'e2', source: 'transform', target: 'publish' },
];

const note = ref('Choose an image format to download.');
let instance: DiagramInstance | null = null;

async function downloadImage(format: 'png' | 'svg'): Promise<void> {
  const live = instance;
  if (!live) return;
  const output = format === 'png'
    ? await live.export('png', { scale: 2 })
    : await live.export('svg');
  const href = format === 'svg'
    ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(output)}`
    : output;
  const anchor = document.createElement('a');
  anchor.href = href;
  anchor.download = `diagram.${format}`;
  anchor.click();
  note.value = `${format.toUpperCase()} download started.`;
}

function onInit(live: DiagramInstance): void {
  instance = live;
}
</script>

<template>
  <button type="button" @click="downloadImage('png')">Download PNG</button>
  <button type="button" @click="downloadImage('svg')">Download SVG</button>
  <span>{{ note }}</span>
  <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
    style="display:block; height:400px" @init="onInit" />
</template>
```
:::

After either button, the page reports that the PNG or SVG download started, and the browser downloads the selected file. The PNG contains a rasterized export; the SVG is vector markup you can open in a text editor or scale without rasterizing.

[Open the live image-export demo](https://grafloria.com/demos/misc/download-image.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/misc/download-image.html).

## Download a PDF

2. Add a PDF action to the mounted diagram and call `export('pdf')`. The result is a PDF data URL, so the browser can download it with the same anchor pattern. This output is a vector PDF: node paths remain paths and labels remain selectable text.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const host = document.createElement('div');
host.style.height = '400px';
const pdfButton = document.createElement('button');
pdfButton.textContent = 'Download PDF';
const status = document.createElement('span');
document.body.append(pdfButton, status, host);

const instance = render({
  nodes: [
    { id: 'requirements', label: 'Requirements', position: { x: 40, y: 80 }, size: { width: 170, height: 66 } },
    { id: 'design', label: 'Design', position: { x: 280, y: 80 }, size: { width: 170, height: 66 } },
    { id: 'ship', label: 'Ship', position: { x: 520, y: 80 }, size: { width: 170, height: 66 } },
  ],
  edges: [
    { id: 'e1', source: 'requirements', target: 'design' },
    { id: 'e2', source: 'design', target: 'ship' },
  ],
}, host);

instance.renderNow();

async function downloadPdf() {
  const href = await instance.export('pdf');
  const anchor = document.createElement('a');
  anchor.href = href;
  anchor.download = 'diagram.pdf';
  anchor.click();
  status.textContent = 'PDF download started.';
}

pdfButton.addEventListener('click', () => void downloadPdf());
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="downloadPdf()">Download PDF</button>
    <span>{{ note }}</span>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class PdfExportComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  note = 'Choose PDF to download.';

  nodes: NodeSpec[] = [
    { id: 'requirements', label: 'Requirements', position: { x: 40, y: 80 }, size: { width: 170, height: 66 } },
    { id: 'design', label: 'Design', position: { x: 280, y: 80 }, size: { width: 170, height: 66 } },
    { id: 'ship', label: 'Ship', position: { x: 520, y: 80 }, size: { width: 170, height: 66 } },
  ];
  edges: EdgeSpec[] = [
    { id: 'e1', source: 'requirements', target: 'design' },
    { id: 'e2', source: 'design', target: 'ship' },
  ];

  async downloadPdf(): Promise<void> {
    const href = await this.canvas().exportDiagram('pdf');
    const anchor = document.createElement('a');
    anchor.href = href;
    anchor.download = 'diagram.pdf';
    anchor.click();
    this.note = 'PDF download started.';
  }
}
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'requirements', label: 'Requirements', position: { x: 40, y: 80 }, size: { width: 170, height: 66 } },
  { id: 'design', label: 'Design', position: { x: 280, y: 80 }, size: { width: 170, height: 66 } },
  { id: 'ship', label: 'Ship', position: { x: 520, y: 80 }, size: { width: 170, height: 66 } },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'requirements', target: 'design' },
  { id: 'e2', source: 'design', target: 'ship' },
];

export default function PdfExport() {
  const instanceRef = useRef<DiagramInstance | null>(null);
  const [note, setNote] = useState('Choose PDF to download.');

  async function downloadPdf(): Promise<void> {
    const instance = instanceRef.current;
    if (!instance) return;
    const href = await instance.export('pdf');
    const anchor = document.createElement('a');
    anchor.href = href;
    anchor.download = 'diagram.pdf';
    anchor.click();
    setNote('PDF download started.');
  }

  return (
    <div>
      <button type="button" onClick={() => void downloadPdf()}>Download PDF</button>
      <span>{note}</span>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        style={{ display: 'block', height: '400px' }}
        onInit={(instance) => { instanceRef.current = instance; }}
      />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { ref } from 'vue';

const nodes: NodeSpec[] = [
  { id: 'requirements', label: 'Requirements', position: { x: 40, y: 80 }, size: { width: 170, height: 66 } },
  { id: 'design', label: 'Design', position: { x: 280, y: 80 }, size: { width: 170, height: 66 } },
  { id: 'ship', label: 'Ship', position: { x: 520, y: 80 }, size: { width: 170, height: 66 } },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'requirements', target: 'design' },
  { id: 'e2', source: 'design', target: 'ship' },
];

const note = ref('Choose PDF to download.');
let instance: DiagramInstance | null = null;

async function downloadPdf(): Promise<void> {
  const live = instance;
  if (!live) return;
  const href = await live.export('pdf');
  const anchor = document.createElement('a');
  anchor.href = href;
  anchor.download = 'diagram.pdf';
  anchor.click();
  note.value = 'PDF download started.';
}

function onInit(live: DiagramInstance): void {
  instance = live;
}
</script>

<template>
  <button type="button" @click="downloadPdf">Download PDF</button>
  <span>{{ note }}</span>
  <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
    style="display:block; height:400px" @init="onInit" />
</template>
```
:::

The page reports that the PDF download started, and the browser downloads `diagram.pdf`. Select and copy a node label in a PDF reader to confirm that the text is selectable rather than part of a screenshot.

[Open the live PDF-export demo](https://grafloria.com/demos/misc/pdf-export.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/misc/pdf-export.html).

## Render an SVG on the server

3. For a server-rendered artifact, call [`renderStatic`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) with plain node and edge specs. It returns `svg` and the stylesheet `css` without mounting a canvas or needing a DOM. Inline the stylesheet into the SVG before writing the file so the artifact carries its styles.

This Node.js ESM example writes a self-contained `diagram.svg`; render the same specs again to produce the same SVG and CSS.

```ts
import { writeFile } from 'node:fs/promises';
import { renderStatic } from '@grafloria/element';

const result = renderStatic({
  nodes: [
    { id: 'extract', label: 'Extract', position: { x: 40, y: 40 }, size: { width: 150, height: 66 } },
    { id: 'load', label: 'Load', position: { x: 260, y: 40 }, size: { width: 150, height: 66 } },
    { id: 'model', label: 'Model', position: { x: 150, y: 170 }, size: { width: 150, height: 66 } },
  ],
  edges: [
    { id: 'e1', source: 'extract', target: 'load' },
    { id: 'e2', source: 'extract', target: 'model' },
  ],
  width: 520,
  height: 300,
  standalone: true,
  instanceId: 'pipeline-diagram',
});

const artifact = result.svg.replace(
  /^(<svg[^>]*>)/,
  `$1<style>${result.css}</style>`,
);
async function writeArtifact(): Promise<void> {
  await writeFile('diagram.svg', artifact, 'utf8');
}

void writeArtifact();
```

The saved SVG contains the Extract, Load and Model nodes with their edges; the call returns `{ html, svg, css, snapshot }`, and only `svg` plus its inlined CSS goes into this standalone file. `renderStatic()` supports SVG-rendered diagram content, not framework custom-node components.

[Open the live server-side export demo](https://grafloria.com/demos/misc/server-side-export.html) or [view its source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/misc/server-side-export.html).

## Options and caveats

The instance's `export()` returns a `Promise<string>`: SVG source for `svg`, and a `data:` URL for PNG, JPEG, WebP and PDF. It waits for asynchronous custom-node painters before capturing them. Angular exposes the equivalent async path as `exportDiagram(format, options)` on the canvas component.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `scale` | `number` | `1` | Sets raster image scale. |
| `quality` | `number` from `0` to `1` | `0.92` | Sets JPEG or WebP quality. |
| `backgroundColor` | `string` | transparent | Sets the export background color. |
| `viewport` | `Rectangle` | content bounds | Selects a world-space rectangle to export. |
| `padding` | `number` | `20` | Adds margin in world units around content bounds; ignored when `viewport` is explicit. |
| `embedModel` | `boolean` | not specified | Embeds the source model in SVG metadata or a PNG text chunk for editable round-trips; JPEG and WebP ignore it. |
| `onWarnings` | `(warnings: string[]) => void` | not specified | Receives fidelity warnings for the export. |

`export()` needs a painted live canvas; call it in response to an action after mounting, not before the first paint. For SVG downloads, wrap the returned markup in an SVG data URL as the examples do. External images can depend on browser fetch/CORS access; check `onWarnings` when an asset or custom-node capture does not appear. The synchronous `exportSvgString()` and `exportPdf()` instance methods are alternatives when you need immediate results; they return result objects with warnings and do not wait for asynchronous painters or fetch external assets.

## Related

- [The `DiagramInstance` API](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance)
- [The element package API](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core)
- [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start)

<!-- source: build-er-and-uml-diagrams.md -->

# Build ER and UML diagrams

Use the ER and UML kits when your schema or class model already exists as data and you want Grafloria to render its cards, relationship notation, and interactive canvas. The kits return diagram specs; [`render()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) mounts those specs in JavaScript, while framework bindings mount the same specs in their host components.

## Build an ER diagram

Pass entities and relationships to [`erDiagram()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-functions#erdiagram). Each entity becomes a table card with typed column rows and PK/FK badges. Relationships draw as orthogonal edges with cardinality markers; endpoints written as `ENTITY.column` attach to that column's row. The kit provides row selection by default.

The JavaScript example connects `CUSTOMER.id` to `ORDER.customer_id`. It renders two table cards, their key badges, and a one-to-many relationship with its label. Give the mounted canvas a real height so it has space to draw. The Angular sample uses column-qualified ends too, so each relationship endpoint attaches to the matching row.

The JavaScript samples create and append a 500-pixel host before mounting. React and Vue mount the same ER data through their framework hosts; Angular uses a separate AUTHOR-to-BOOK example to show column-qualified endpoints.

The React [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriadiagram) and Vue [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriadiagram) bindings accept the kit spec directly. Angular uses [`GrafloriaDiagramComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes#grafloriadiagramcomponent). Qwik uses [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriadiagram) with a serializable [`RenderSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#renderspec) of nodes and edges; that Qwik variant draws generic nodes and labeled edges, not the kits' HTML cards, key badges, cardinality markers, UML relationship markers, or multiplicity labels. The ER builder accepts [`ErDiagramOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-interfaces#erdiagramoptions); the UML builder accepts [`UmlDiagramOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-interfaces#umldiagramoptions).

:::code-group
```js title="JavaScript"
import { erDiagram, render } from '@grafloria/element';

const spec = erDiagram({
  entities: [
    { id: 'CUSTOMER', name: 'Customer', position: { x: 60, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDER', name: 'Order', position: { x: 390, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'placed_at', type: 'date' },
    ] },
  ],
  relationships: [
    {
      from: 'CUSTOMER.id',
      to: 'ORDER.customer_id',
      label: 'places',
      cardinality: 'one-to-many',
    },
  ],
});

const host = document.createElement('div');
host.style.cssText = 'display:block; width:100%; height:500px';
document.body.append(host);
const instance = render(spec, host);
instance.fitView(40);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { erDiagram } from '@grafloria/element';

@Component({
  selector: 'app-er-diagram',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: '<grafloria-diagram [spec]="spec" style="display:block; height:500px" />',
})
export class ErDiagramComponent {
  spec = erDiagram({
    entities: [
      { id: 'AUTHOR', name: 'Author', position: { x: 60, y: 80 }, columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'name', type: 'varchar' },
      ] },
      { id: 'BOOK', name: 'Book', position: { x: 390, y: 80 }, columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'author_id', type: 'int', fk: true },
        { name: 'title', type: 'varchar' },
      ] },
    ],
    relationships: [{ from: 'AUTHOR.id', to: 'BOOK.author_id', label: 'writes', cardinality: 'one-to-many' }],
  });
}
```
```tsx title="Qwik"
import { component$ } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import type { RenderSpec } from '@grafloria/element';

const spec: RenderSpec = {
  nodes: [
    { id: 'CUSTOMER', position: { x: 60, y: 80 }, size: { width: 240, height: 90 }, label: 'Customer · PK id · email' },
    { id: 'ORDER', position: { x: 390, y: 80 }, size: { width: 260, height: 90 }, label: 'Order · PK id · FK customer_id' },
  ],
  edges: [{ id: 'places', source: 'CUSTOMER', target: 'ORDER', label: 'places' }],
};

export default component$(() => (
  <div style={{ height: '500px' }}>
    <GrafloriaDiagram spec={spec} />
  </div>
));
```
```tsx title="React"
import { GrafloriaDiagram } from '@grafloria/react';
import { erDiagram } from '@grafloria/element';

const spec = erDiagram({
  entities: [
    { id: 'CUSTOMER', name: 'Customer', position: { x: 60, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDER', name: 'Order', position: { x: 390, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'placed_at', type: 'date' },
    ] },
  ],
  relationships: [{ from: 'CUSTOMER.id', to: 'ORDER.customer_id', label: 'places', cardinality: 'one-to-many' }],
});

export function ErDiagramView() {
  return (
    <div style={{ height: 500 }}>
      <GrafloriaDiagram spec={spec} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaDiagram } from '@grafloria/vue';
import { erDiagram } from '@grafloria/element';

const spec = erDiagram({
  entities: [
    { id: 'CUSTOMER', name: 'Customer', position: { x: 60, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDER', name: 'Order', position: { x: 390, y: 80 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'placed_at', type: 'date' },
    ] },
  ],
  relationships: [{ from: 'CUSTOMER.id', to: 'ORDER.customer_id', label: 'places', cardinality: 'one-to-many' }],
});
</script>

<template>
  <div style="height:500px">
    <GrafloriaDiagram :spec="spec" />
  </div>
</template>
```
:::

To connect tables without pinning to a specific row, use the entity IDs as relationship ends, such as `{ from: 'CUSTOMER', to: 'ORDER', label: 'places' }`. Use column-qualified ends for FK-to-PK relationships: the column name must exist on the named entity or the kit throws an error when it builds the spec. The default cardinality is `one-to-many`; choose another supported cardinality when the model calls for it.

[Open the live ER diagram demo](https://grafloria.com/demos/diagrams/table-er.html) to see the rendered table cards, key badges, and relationship markers.

For multiple foreign keys between the same tables, self-references, junction tables, and optional or mandatory cardinalities, see the [advanced ER demo](https://grafloria.com/demos/diagrams/er-advanced.html). Its column-level ends and cardinality choices use the same entity and relationship data model.

## Build a UML class diagram

Pass class definitions and relationships to [`umlDiagram()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-functions#umldiagram). Classes render in compartments for the class name, attributes, and methods. An abstract class name is italicized; relationship kinds supply their UML marker and line style. Multiplicity values add positioned labels to the live links.

This example renders an abstract `Animal`, its `Dog` subclass, and an `Owner` aggregation. The kit draws the three-compartment cards, inheritance triangle, and hollow diamond; `render()` runs the kit's finalization hook when it mounts a spec.

The React and Vue samples pass the spec to their framework binding. Angular mounts it with [`GrafloriaDiagramComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes#grafloriadiagramcomponent).

:::code-group
```js title="JavaScript"
import { render, umlDiagram } from '@grafloria/element';

const spec = umlDiagram({
  classes: [
    {
      id: 'Animal',
      abstract: true,
      position: { x: 180, y: 50 },
      attributes: ['# name: String'],
      methods: ['+ speak(): void'],
    },
    {
      id: 'Dog',
      position: { x: 180, y: 300 },
      attributes: ['+ breed: String'],
      methods: ['+ fetch(): void'],
    },
    {
      id: 'Owner',
      position: { x: 500, y: 300 },
      attributes: ['+ name: String'],
      methods: ['+ adopt(dog): void'],
    },
  ],
  relationships: [
    { from: 'Dog', to: 'Animal', kind: 'inheritance' },
    { from: 'Owner', to: 'Dog', kind: 'aggregation', label: 'owns', multiplicity: ['1', '0..*'] },
  ],
});

const host = document.createElement('div');
host.style.cssText = 'display:block; width:100%; height:500px';
document.body.append(host);
const instance = render(spec, host);
instance.fitView(40);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { umlDiagram } from '@grafloria/element';

@Component({
  selector: 'app-uml-diagram',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: '<grafloria-diagram [spec]="spec" style="display:block; height:500px" />',
})
export class UmlDiagramComponent {
  spec = umlDiagram({
    classes: [
      { id: 'Animal', abstract: true, position: { x: 180, y: 50 }, attributes: ['# name: String'], methods: ['+ speak(): void'] },
      { id: 'Dog', position: { x: 180, y: 300 }, attributes: ['+ breed: String'], methods: ['+ fetch(): void'] },
      { id: 'Owner', position: { x: 500, y: 300 }, attributes: ['+ name: String'], methods: ['+ adopt(dog): void'] },
    ],
    relationships: [
      { from: 'Dog', to: 'Animal', kind: 'inheritance' },
      { from: 'Owner', to: 'Dog', kind: 'aggregation', label: 'owns', multiplicity: ['1', '0..*'] },
    ],
  });
}
```
```tsx title="Qwik"
import { component$ } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import type { RenderSpec } from '@grafloria/element';

const spec: RenderSpec = {
  nodes: [
    { id: 'Animal', position: { x: 180, y: 50 }, size: { width: 220, height: 90 }, label: 'Animal · abstract · # name: String' },
    { id: 'Dog', position: { x: 180, y: 300 }, size: { width: 220, height: 90 }, label: 'Dog · + breed: String' },
    { id: 'Owner', position: { x: 500, y: 300 }, size: { width: 220, height: 90 }, label: 'Owner · + name: String' },
  ],
  edges: [
    { id: 'inherits', source: 'Dog', target: 'Animal', label: 'inherits' },
    { id: 'owns', source: 'Owner', target: 'Dog', label: 'owns' },
  ],
};

export default component$(() => (
  <div style={{ height: '500px' }}>
    <GrafloriaDiagram spec={spec} />
  </div>
));
```
```tsx title="React"
import { GrafloriaDiagram } from '@grafloria/react';
import { umlDiagram } from '@grafloria/element';

const spec = umlDiagram({
  classes: [
    { id: 'Animal', abstract: true, position: { x: 180, y: 50 }, attributes: ['# name: String'], methods: ['+ speak(): void'] },
    { id: 'Dog', position: { x: 180, y: 300 }, attributes: ['+ breed: String'], methods: ['+ fetch(): void'] },
    { id: 'Owner', position: { x: 500, y: 300 }, attributes: ['+ name: String'], methods: ['+ adopt(dog): void'] },
  ],
  relationships: [
    { from: 'Dog', to: 'Animal', kind: 'inheritance' },
    { from: 'Owner', to: 'Dog', kind: 'aggregation', label: 'owns', multiplicity: ['1', '0..*'] },
  ],
});

export function UmlDiagramView() {
  return (
    <div style={{ height: 500 }}>
      <GrafloriaDiagram spec={spec} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaDiagram } from '@grafloria/vue';
import { umlDiagram } from '@grafloria/element';

const spec = umlDiagram({
  classes: [
    { id: 'Animal', abstract: true, position: { x: 180, y: 50 }, attributes: ['# name: String'], methods: ['+ speak(): void'] },
    { id: 'Dog', position: { x: 180, y: 300 }, attributes: ['+ breed: String'], methods: ['+ fetch(): void'] },
    { id: 'Owner', position: { x: 500, y: 300 }, attributes: ['+ name: String'], methods: ['+ adopt(dog): void'] },
  ],
  relationships: [
    { from: 'Dog', to: 'Animal', kind: 'inheritance' },
    { from: 'Owner', to: 'Dog', kind: 'aggregation', label: 'owns', multiplicity: ['1', '0..*'] },
  ],
});
</script>

<template>
  <div style="height:500px">
    <GrafloriaDiagram :spec="spec" />
  </div>
</template>
```
:::

Relationship kinds supported by the UML kit are `inheritance`, `realization`, `association`, `directed-association`, `aggregation`, `composition`, and `dependency`. The kit draws each kind's notation, including dashed lines for realization and dependency, diamonds at the source end for aggregation and composition, and an open target arrow for directed association. Provide `multiplicity: ['from', 'to']` to add a chip at each endpoint. The [class diagram demo](https://grafloria.com/demos/diagrams/class-uml.html) shows the basic class-card and relationship pattern.

The [UML relationships demo](https://grafloria.com/demos/diagrams/uml-relationships.html) shows all seven relationship kinds, multiplicities, stereotypes, and their rendered markers.

## Use node and edge data directly

Use the kits when you want their table or class cards and relationship notation. If your ER or UML model is already expressed as graph data, mount [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec#nodespec) nodes and [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec#edgespec) edges directly. The resulting canvas uses regular diagram nodes and links; it does not add the kits' HTML cards, PK/FK badges, UML markers, or multiplicity chips.

For the JavaScript and framework mounting patterns, see [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows). Here, ordinary graph nodes carry class members as label text, so the canvas shows the relationships without UML compartments, markers, or multiplicity chips.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';

const nodes = [
  { id: 'CUSTOMER', position: { x: 60, y: 80 }, size: { width: 240, height: 90 }, label: 'Customer · id: int (PK) · email: varchar' },
  { id: 'ORDER', position: { x: 390, y: 80 }, size: { width: 260, height: 90 }, label: 'Order · id: int (PK) · customer_id: int (FK)' },
];
const edges = [{ id: 'places', source: 'CUSTOMER', target: 'ORDER', label: 'places' }];
const host = document.getElementById('diagram');
if (!host) throw new Error('Missing #diagram');
host.style.height = '500px';
const instance = render({ nodes, edges }, host);
instance.fitView(40);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-entity-graph',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `<grafloria-diagram-canvas [nodes]="nodes" [edges]="edges" style="display:block; height:500px" />`,
})
export class EntityGraphComponent {
  nodes: NodeSpec[] = [
    { id: 'CUSTOMER', position: { x: 60, y: 80 }, size: { width: 240, height: 90 }, label: 'Customer · id: int (PK) · email: varchar' },
    { id: 'ORDER', position: { x: 390, y: 80 }, size: { width: 260, height: 90 }, label: 'Order · id: int (PK) · customer_id: int (FK)' },
  ];
  edges: EdgeSpec[] = [{ id: 'places', source: 'CUSTOMER', target: 'ORDER', label: 'places' }];
}
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'CUSTOMER', position: { x: 60, y: 80 }, size: { width: 240, height: 90 }, label: 'Customer · id: int (PK) · email: varchar' },
  { id: 'ORDER', position: { x: 390, y: 80 }, size: { width: 260, height: 90 }, label: 'Order · id: int (PK) · customer_id: int (FK)' },
];
const edges: EdgeSpec[] = [{ id: 'places', source: 'CUSTOMER', target: 'ORDER', label: 'places' }];

export function EntityGraphView() {
  return (
    <div style={{ height: 500 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'Animal', position: { x: 100, y: 60 }, size: { width: 260, height: 110 }, label: 'Animal\n# name: String\n+ speak(): void' },
  { id: 'Dog', position: { x: 100, y: 280 }, size: { width: 260, height: 110 }, label: 'Dog\n+ breed: String\n+ fetch(): void' },
];
const edges: EdgeSpec[] = [{ id: 'inherits', source: 'Dog', target: 'Animal', label: 'inherits' }];
</script>

<template>
  <div style="height:500px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" fit-view />
  </div>
</template>
```
:::

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `relationships` | ER relationship records or UML relationship records | `[]` | Describes the connections between entity or class IDs. ER relationship ends can include a column name; UML relationships can set a kind and multiplicities. |
| `cardinality` (ER) | Named cardinality or `{ tail: string; head: string }` | `'one-to-many'` | Chooses ER endpoint markers. Named values include one-to-one, many-to-many, one-to-zero-or-many, and one-to-one-or-many. |
| `multiplicity` (UML) | `[string, string]` | None | Adds the from-end and to-end multiplicity labels. |
| `rowSelection` | `boolean` | `true` | Enables member/column row selection. Set `false` to opt out. |
| `editable` | `boolean` | `false` | Adds in-canvas rename, add, and delete controls for entity columns or class members. Edits are undoable. |
| `height` (entity or class) | `number` | Content-sized | Fixes a card's height; content exceeding it scrolls inside the card. |

## Pitfalls

- Column-qualified ER relationship ends must name an existing entity and column. A missing entity or field causes `erDiagram()` to throw while building its spec.
- The UML multiplicity labels need a live diagram model. Mount the spec; `render()` runs its `finalize` hook, which adds the labels after the links exist.
- Framework components need a parent with a nonzero height. The examples set a 500-pixel canvas height; adapt that value to your layout.
- The kit's UML relationship vocabulary does not include self-association. For the ER kit's supported self-reference pattern, see the [advanced ER demo](https://grafloria.com/demos/diagrams/er-advanced.html); a custom UML self-loop needs edge-level modeling beyond this kit.

## Related

- [Lay out diagrams automatically](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/lay-out-diagrams) — arrange diagram nodes after building their data.
- [Edit data models visually](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/edit-data-models-visually) — edit tables and fields on the canvas.
- [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) — understand undoable diagram edits.

<!-- source: edit-data-models-visually.md -->

# Edit data models visually

Use the ER diagram kit when you want readers to rename tables and columns in place, add or remove columns, and see relationships stay attached to their fields as the schema changes.

The kit turns entity and relationship data into table cards with typed columns, key badges, and crow’s-foot relationships. Set `editable: true` to add inline editing controls; a `TABLE.column` relationship endpoint pins its edge to that column’s row. [`erDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-functions#erdiagram) builds the spec, and [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) or a framework diagram component mounts it.

## Build an editable ER diagram

Use this pattern when your data is a relational schema and the diagram itself should be the editor. The example includes a field-level foreign-key relationship from `ORDERS.customer_id` to `CUSTOMERS.id`, plus a table-level relationship from `PRODUCTS` to `ORDERS`.

The mounted diagram shows three entity cards, their columns and key badges, and orthogonal crow’s-foot edges. Double-click a table header or column name to edit it; use the card’s add and delete controls to change columns. Each edit is an undoable step, and the field-level edge remains attached to its column when rows move.

Create the same kit spec in JavaScript, Angular, React, or Vue, then mount it with the framework’s diagram component. The JavaScript example mounts the spec directly. Each sample gives the canvas a real height.

React’s [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriadiagram) and Vue’s [`GrafloriaDiagram`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriadiagram) mount the kit spec directly. Angular’s diagram component takes the spec as an input.

:::code-group
```js title="JavaScript"
import { erDiagram, render } from '@grafloria/element';

const spec = erDiagram({
  editable: true,
  entities: [
    { id: 'PRODUCTS', name: 'Products', position: { x: 80, y: 96 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'sku', type: 'varchar' },
      { name: 'price', type: 'decimal' },
    ] },
    { id: 'CUSTOMERS', name: 'Customers', position: { x: 80, y: 360 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'name', type: 'varchar' },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDERS', name: 'Orders', position: { x: 500, y: 150 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'status', type: 'varchar' },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'total', type: 'decimal' },
    ] },
  ],
  relationships: [
    { from: 'ORDERS.customer_id', to: 'CUSTOMERS.id', id: 'fk_customer', fromSide: 'left', toSide: 'right' },
    { from: 'PRODUCTS', to: 'ORDERS', label: 'ordered as', fromSide: 'right', toSide: 'left' },
  ],
});

const host = document.createElement('div');
host.style.height = '640px';
document.body.append(host);
const instance = render(spec, host);
instance.fitView(40);
window.addEventListener('pagehide', () => instance.dispose(), { once: true });
```

```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { erDiagram } from '@grafloria/element';

const spec = erDiagram({
  editable: true,
  entities: [
    { id: 'PRODUCTS', name: 'Products', position: { x: 80, y: 96 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'sku', type: 'varchar' },
      { name: 'price', type: 'decimal' },
    ] },
    { id: 'CUSTOMERS', name: 'Customers', position: { x: 80, y: 360 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'name', type: 'varchar' },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDERS', name: 'Orders', position: { x: 500, y: 150 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'status', type: 'varchar' },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'total', type: 'decimal' },
    ] },
  ],
  relationships: [
    { from: 'ORDERS.customer_id', to: 'CUSTOMERS.id', id: 'fk_customer', fromSide: 'left', toSide: 'right' },
    { from: 'PRODUCTS', to: 'ORDERS', label: 'ordered as', fromSide: 'right', toSide: 'left' },
  ],
});

@Component({
  selector: 'app-erd-editor',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: '<grafloria-diagram [spec]="spec" style="display:block; height:640px" />',
})
export class ErdEditorComponent {
  readonly spec = spec;
}
```

```tsx title="React"
import { GrafloriaDiagram } from '@grafloria/react';
import { erDiagram } from '@grafloria/element';

const spec = erDiagram({
  editable: true,
  entities: [
    { id: 'PRODUCTS', name: 'Products', position: { x: 80, y: 96 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'sku', type: 'varchar' },
      { name: 'price', type: 'decimal' },
    ] },
    { id: 'CUSTOMERS', name: 'Customers', position: { x: 80, y: 360 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'name', type: 'varchar' },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDERS', name: 'Orders', position: { x: 460, y: 200 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'status', type: 'varchar' },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'total', type: 'decimal' },
    ] },
  ],
  relationships: [
    { from: 'ORDERS.customer_id', to: 'CUSTOMERS.id', id: 'fk_customer', fromSide: 'left', toSide: 'right' },
    { from: 'PRODUCTS', to: 'ORDERS', label: 'ordered as', fromSide: 'right', toSide: 'left' },
  ],
});

export default function ErdEditor() {
  return (
    <div style={{ height: '640px' }}>
      <GrafloriaDiagram spec={spec} />
    </div>
  );
}
```

```vue title="Vue"
<script setup lang="ts">
import { GrafloriaDiagram } from '@grafloria/vue';
import { erDiagram } from '@grafloria/element';

const spec = erDiagram({
  editable: true,
  entities: [
    { id: 'PRODUCTS', name: 'Products', position: { x: 80, y: 96 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'sku', type: 'varchar' },
      { name: 'price', type: 'decimal' },
    ] },
    { id: 'CUSTOMERS', name: 'Customers', position: { x: 80, y: 360 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'name', type: 'varchar' },
      { name: 'email', type: 'varchar' },
    ] },
    { id: 'ORDERS', name: 'Orders', position: { x: 460, y: 200 }, columns: [
      { name: 'id', type: 'int', pk: true },
      { name: 'status', type: 'varchar' },
      { name: 'customer_id', type: 'int', fk: true },
      { name: 'total', type: 'decimal' },
    ] },
  ],
  relationships: [
    { from: 'ORDERS.customer_id', to: 'CUSTOMERS.id', id: 'fk_customer', fromSide: 'left', toSide: 'right' },
    { from: 'PRODUCTS', to: 'ORDERS', label: 'ordered as', fromSide: 'right', toSide: 'left' },
  ],
});
</script>

<template>
  <div style="height:640px">
    <GrafloriaDiagram :spec="spec" />
  </div>
</template>
```

:::

The kit spec is regular diagram data plus a finalization step that installs the row interactions and, when editing is enabled, the inline editing behavior. Framework bindings mount that same spec; the JavaScript call returns a live instance, which the sample uses to fit the diagram and dispose it when its host page leaves.

For a model that is not a relational schema, use the generic canvas: React’s [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-react#grafloriaflow), Vue’s [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-vue#grafloriaflow), or Angular’s [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent).

For a non-relational model, the generic canvas changes the task: readers move entity nodes and create or remove connections, rather than editing table and column names or rows. See the [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start) for typed flow data and framework binding patterns, and [How Grafloria works](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/how-grafloria-works) for the shared model and Angular controlled-binding example.

## Options that shape the schema

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `entities` | Array of entity specs | Required | Declares each table’s id, optional display name, columns, and optional position. Each column can specify a name, type, primary-key flag, and foreign-key flag. |
| `relationships` | Array of relationship specs | Empty | Declares links between entity ids or between `ENTITY.column` endpoints. A column endpoint anchors the edge to that row. |
| `editable` | `boolean` | `false` | Adds table rename, column rename, add-column, and delete-column controls. Every edit is one undoable step. |
| `rowSelection` | `boolean` | `true` | Enables column-row selection and the kit’s row selection events. Set it to `false` to opt out. |

## Pitfalls

- Use the exact entity id and column name in a field endpoint such as `ORDERS.customer_id`. The kit throws if an entity or referenced column does not exist.
- `editable` is opt-in. Without it, the diagram remains the read-only ER card view.
- Deleting a column removes a relationship attached to that column. Other field relationships stay connected to their columns as those rows shift.
- Give the canvas host a resolved height. The renderer fills its parent; a zero-height parent leaves no visible diagram.

## See it running

[Open the live ERD editor demo](https://grafloria.com/demos/diagrams/erd-editor.html) to try inline table and column edits, column insertion and deletion, row selection, and field-level relationships.

## Related

- [Build ER and UML diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-er-and-uml-diagrams) for read-only ER and UML diagrams from data.
- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) for how diagram edits enter the undo history.
- [Validate connections](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/validate-connections) for rules that allow or veto connections.

<!-- source: build-dashboards.md -->

# Build dashboards

Declare dashboard views and widgets as data, mount the board in your framework, then switch views or layout and save the live board as a snapshot.

## When to use the dashboard kit

Use [`GrafloriaDashboard`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik) (React and Vue) or [`GrafloriaDashboardComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-grafloriadashboardcomponent) (Angular) when people arrange widgets in grid cells. A dashboard is data first: views contain widget specs, and the kit supplies the grid, drag and resize behavior, and undo. The same headless model drives every framework binding. Plain JavaScript builds a spec with [`dashboard()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-functions) and mounts it with [`render()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core); framework bindings expose a live [`DashboardHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardhandle), whose snapshot has the [`DashboardSnapshot`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-types) shape. Widget declarations use [`DashboardWidgetSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardwidgetspec).

The built-in widget renderers draw `kpi`, `line`, `bar`, `donut`, `funnel`, and `table` widgets from their `data`; start with those before supplying custom rendering. The examples below use KPI, line, and donut data.

See the [live dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html) for a multi-view board with built-in widgets. The [demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/dashboard/dashboard-builder.html) shows its full builder UI.

## Declare and mount the board

Each view has an `id` and a `widgets` array; each widget needs an `id` and can name a renderer `kind`, cell `span` and `rows`, and renderer data. With no explicit `x` and `y`, widgets flow in declaration order. `span` defaults to 3 columns and `rows` to 1. The framework components mount the board from these specs; give their host a height so the rendered dashboard has room.

The following examples declare two real views and mount the same board in each supported framework. The initial board displays KPI cards and a donut in Overview; the Revenue view has its own line and KPI widgets.

:::code-group
```js title="JavaScript"
import { dashboard, render } from '@grafloria/element';

const root = document.createElement('main');
const nav = document.createElement('nav');
const overviewButton = document.createElement('button');
overviewButton.textContent = 'Overview';
const revenueButton = document.createElement('button');
revenueButton.textContent = 'Revenue';
const layoutButton = document.createElement('button');
layoutButton.textContent = 'Switch layout';
const saveButton = document.createElement('button');
saveButton.textContent = 'Save board';
nav.append(overviewButton, revenueButton, layoutButton, saveButton);
const canvas = document.createElement('div');
canvas.style.height = '560px';
root.append(nav, canvas);
document.body.append(root);

const views = [
  { id: 'overview', name: 'Overview', widgets: [
    { id: 'sales-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Sales', value: '$6.8M', delta: 12.4, spark: [4.2, 4.5, 5.1, 6.8] } },
    { id: 'customers-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Customers', value: '1,284', delta: 8.1, spark: [980, 1090, 1150, 1284] } },
    { id: 'region-mix', kind: 'donut', span: 6, rows: 2, title: 'Sales by region',
      data: { slices: [{ label: 'EMEA', value: 2.9 }, { label: 'Americas', value: 2.4 }, { label: 'APAC', value: 1.5 }] } },
  ] },
  { id: 'revenue', name: 'Revenue', widgets: [
    { id: 'revenue-line', kind: 'line', span: 8, rows: 2, title: 'Revenue trend',
      data: { series: [{ name: 'Revenue', values: [4.2, 4.5, 5.1, 6.8] }], labels: ['Jan', 'Feb', 'Mar', 'Apr'] } },
    { id: 'revenue-kpi', kind: 'kpi', span: 4, rows: 1,
      data: { label: 'Quarter total', value: '$6.8M', delta: 12.4 } },
  ] },
];

const saved = localStorage.getItem('sales-dashboard');
const spec = dashboard(saved ? JSON.parse(saved) : { columns: 12, views });
const instance = render(spec, canvas);
const handle = spec.handle;
overviewButton.addEventListener('click', () => handle.showView('overview'));
revenueButton.addEventListener('click', () => handle.showView('revenue'));
layoutButton.addEventListener('click', () => {
  const next = handle.getLayout() === 'grid' ? 'split' : 'grid';
  handle.setLayout(next);
});
saveButton.addEventListener('click', () => {
  localStorage.setItem('sales-dashboard', JSON.stringify(handle.toJSON()));
});
window.addEventListener('pagehide', () => instance.dispose(), { once: true });
```
```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDashboardComponent } from '@grafloria/angular';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

@Component({
  selector: 'app-sales-dashboard',
  standalone: true,
  imports: [GrafloriaDashboardComponent],
  template: `
    <nav>
      <button (click)="tab = 'overview'">Overview</button>
      <button (click)="tab = 'revenue'">Revenue</button>
      <button (click)="switchLayout()">Switch layout</button>
      <button (click)="save()">Save board</button>
    </nav>
    <grafloria-dashboard [views]="views" [options]="options" [(activeView)]="tab"
      (ready)="handle = $event" style="display:block; height:560px" />
  `,
})
export class SalesDashboardComponent {
  tab: string | undefined = 'overview';
  handle?: DashboardHandle;
  options = { columns: 12, gap: 8 };
  views: DashboardViewSpec[] = [
    { id: 'overview', name: 'Overview', widgets: [
      { id: 'sales-kpi', kind: 'kpi', span: 3, rows: 1,
        data: { label: 'Sales', value: '$6.8M', delta: 12.4, spark: [4.2, 4.5, 5.1, 6.8] } },
      { id: 'customers-kpi', kind: 'kpi', span: 3, rows: 1,
        data: { label: 'Customers', value: '1,284', delta: 8.1, spark: [980, 1090, 1150, 1284] } },
      { id: 'region-mix', kind: 'donut', span: 6, rows: 2, title: 'Sales by region',
        data: { slices: [{ label: 'EMEA', value: 2.9 }, { label: 'Americas', value: 2.4 }, { label: 'APAC', value: 1.5 }] } },
    ] },
    { id: 'revenue', name: 'Revenue', widgets: [
      { id: 'revenue-line', kind: 'line', span: 8, rows: 2, title: 'Revenue trend',
        data: { series: [{ name: 'Revenue', values: [4.2, 4.5, 5.1, 6.8] }], labels: ['Jan', 'Feb', 'Mar', 'Apr'] } },
      { id: 'revenue-kpi', kind: 'kpi', span: 4, rows: 1,
        data: { label: 'Quarter total', value: '$6.8M', delta: 12.4 } },
    ] },
  ];

  switchLayout(): void {
    const handle = this.handle;
    if (handle) handle.setLayout(handle.getLayout() === 'grid' ? 'split' : 'grid');
  }

  save(): void {
    const snapshot = this.handle?.toJSON();
    if (snapshot) localStorage.setItem('sales-dashboard', JSON.stringify(snapshot));
  }
}
```
```tsx title="React"
import { useState } from 'react';
import { GrafloriaDashboard } from '@grafloria/react';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

const views: DashboardViewSpec[] = [
  { id: 'overview', name: 'Overview', widgets: [
    { id: 'sales-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Sales', value: '$6.8M', delta: 12.4, spark: [4.2, 4.5, 5.1, 6.8] } },
    { id: 'customers-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Customers', value: '1,284', delta: 8.1, spark: [980, 1090, 1150, 1284] } },
    { id: 'region-mix', kind: 'donut', span: 6, rows: 2, title: 'Sales by region',
      data: { slices: [{ label: 'EMEA', value: 2.9 }, { label: 'Americas', value: 2.4 }, { label: 'APAC', value: 1.5 }] } },
  ] },
  { id: 'revenue', name: 'Revenue', widgets: [
    { id: 'revenue-line', kind: 'line', span: 8, rows: 2, title: 'Revenue trend',
      data: { series: [{ name: 'Revenue', values: [4.2, 4.5, 5.1, 6.8] }], labels: ['Jan', 'Feb', 'Mar', 'Apr'] } },
    { id: 'revenue-kpi', kind: 'kpi', span: 4, rows: 1,
      data: { label: 'Quarter total', value: '$6.8M', delta: 12.4 } },
  ] },
];

export default function SalesDashboard() {
  const [handle, setHandle] = useState<DashboardHandle>();
  const [tab, setTab] = useState('overview');
  const [layout, setLayout] = useState<'grid' | 'split'>('grid');

  return (
    <main>
      <nav>
        <button onClick={() => setTab('overview')}>Overview</button>
        <button onClick={() => setTab('revenue')}>Revenue</button>
        <button onClick={() => setLayout(layout === 'grid' ? 'split' : 'grid')}>Switch layout</button>
        <button onClick={() => {
          if (handle) localStorage.setItem('sales-dashboard', JSON.stringify(handle.toJSON()));
        }}>Save board</button>
      </nav>
      <GrafloriaDashboard views={views} activeView={tab} layout={layout} onReady={setHandle}
        style={{ display: 'block', height: 560 }} />
    </main>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle, DashboardViewSpec } from '@grafloria/element';

const handle = ref<DashboardHandle | null>(null);
const tab = ref('overview');
const layout = ref<'grid' | 'split'>('grid');
const views: DashboardViewSpec[] = [
  { id: 'overview', name: 'Overview', widgets: [
    { id: 'sales-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Sales', value: '$6.8M', delta: 12.4, spark: [4.2, 4.5, 5.1, 6.8] } },
    { id: 'customers-kpi', kind: 'kpi', span: 3, rows: 1,
      data: { label: 'Customers', value: '1,284', delta: 8.1, spark: [980, 1090, 1150, 1284] } },
    { id: 'region-mix', kind: 'donut', span: 6, rows: 2, title: 'Sales by region',
      data: { slices: [{ label: 'EMEA', value: 2.9 }, { label: 'Americas', value: 2.4 }, { label: 'APAC', value: 1.5 }] } },
  ] },
  { id: 'revenue', name: 'Revenue', widgets: [
    { id: 'revenue-line', kind: 'line', span: 8, rows: 2, title: 'Revenue trend',
      data: { series: [{ name: 'Revenue', values: [4.2, 4.5, 5.1, 6.8] }], labels: ['Jan', 'Feb', 'Mar', 'Apr'] } },
    { id: 'revenue-kpi', kind: 'kpi', span: 4, rows: 1,
      data: { label: 'Quarter total', value: '$6.8M', delta: 12.4 } },
  ] },
];

function switchLayout(): void {
  const current = handle.value;
  if (current) layout.value = current.getLayout() === 'grid' ? 'split' : 'grid';
}

function save(): void {
  const snapshot = handle.value?.toJSON();
  if (snapshot) localStorage.setItem('sales-dashboard', JSON.stringify(snapshot));
}
</script>

<template>
  <main>
    <nav>
      <button @click="tab = 'overview'">Overview</button>
      <button @click="tab = 'revenue'">Revenue</button>
      <button @click="switchLayout">Switch layout</button>
      <button @click="save">Save board</button>
    </nav>
    <GrafloriaDashboard :views="views" v-model:active-view="tab" :layout="layout"
      @ready="handle = $event" style="display:block; height:560px" />
  </main>
</template>
```
:::

The JavaScript, Angular, React, and Vue examples mount with Overview visible. Their built-in painters render the KPI, donut, and line cards from their data, and the board fits them into grid cells. Choose Revenue to frame the other view; Switch layout toggles the board between the cell grid and split layout. Save board stores the live snapshot in `localStorage`.

## Switch views and layout

The framework components keep view selection in their `activeView` prop or model. Their `layout` prop is a live switch: changing it applies a handle call without remounting. For JavaScript, get the live handle from the dashboard spec and call `showView(id)` or `setLayout('grid' | 'split')` directly. In every binding, choose a declared view id; `DashboardHandle` exposes `views` in declaration order and `activeView` as the current id.

The JavaScript sample uses [`dashboard()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-functions) to create the render spec, then [`render()`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) to mount it. `spec.handle` is the mounted [`DashboardHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardhandle): `setLayout()` switches the active view between grid and split, while `showView()` frames the requested view.

## Persist the live board

Call `toJSON()` on the handle after edits to capture the live board as plain data, then serialize that snapshot with your application's storage. The snapshot includes the current view layouts and board options; it excludes function callbacks. Restore it by passing the saved data back into `dashboard()` in JavaScript. Supply any non-serializable rendering callbacks again when rebuilding. In Angular, `snapshot()` returns the same data as `toJSON()`.

The JavaScript, Angular, React, and Vue examples demonstrate saving to browser `localStorage`. Use storage appropriate to your application when the board must survive a browser change or be shared between users. A saved snapshot has the [`DashboardSnapshot`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-types) shape.

## Options that shape the board

Pass board geometry and behavior through `options`. A view can also override its column count. Widget `span` and `rows` describe its cell size, while optional `x` and `y` place it explicitly.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `columns` | `number` | `12` | Sets the column count for every view unless a view overrides it. |
| `gap` | `number` | `8` | Sets the gap between widgets and the board padding, in pixels. |
| `sizing` | `'fit' \| 'grow'` | `'grow'` on fluid boards; `'fit'` on fixed boards | `grow` keeps row height and extends the board; `fit` keeps the board height and squeezes rows. |
| `layout` | `'grid' \| 'split'` | `'grid'` | Chooses a cell grid or a splitter tree. Switch it live with the handle or component prop. |
| `rowHeight` | `number` | `130` | Sets row height in `grow` mode, in pixels. |
| `float` | `boolean` | `false` | With `false`, gravity packs widgets upward; with `true`, gaps can remain where widgets are dropped. |
| `width`, `height` | `number` | `1180 × 660` | Set a fixed board size. An explicit `width` selects fixed mode. |
| `static` | `boolean` | `false` | Turns off pointer dragging, resizing, and handles for a viewer board. |

On [`DashboardWidgetSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardwidgetspec), `id` identifies a widget, `kind` selects its renderer, `data` carries its payload, and `title` supplies a title. `pinned: true` prevents reflow from moving that widget. The six built-in kinds need no custom renderer; unknown kinds use a titled placeholder frame.

## Pitfalls

- Give the dashboard host a resolved height; otherwise its canvas has no space to draw into.
- `views` and the single-view `widgets` shorthand are mutually exclusive. Use `views` when people switch between boards.
- Framework wrappers mount the board once; changing data or `options` afterward does not rebuild it. Use live props for `activeView`, `layout`, and `sizing`, and use the handle for live board operations.
- React custom widgets use `widgetTypes`, not `options.renderWidget`; Vue uses `widget-<kind>` slots and Angular uses `grafloriaWidget` templates. This page uses built-in renderers instead.

## Live demo

Open the [dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html) to see its tabs, built-in widget cards, and dashboard layout. Read the [demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/dashboard/dashboard-builder.html) for the full palette and persistence controls.

## Related

- [Dashboard handle reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardhandle)
- [Dashboard options reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardoptions)
- [Dashboard widget spec reference](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardwidgetspec)
- [Dashboard kit functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-functions)

<!-- source: synchronize-diagrams.md -->

# Synchronize diagrams

Connect each diagram instance to a transport and give each peer its own actor id. Connected peers share edits; after a transport reconnects, the session exchanges missed operations so the replicas converge.

## Connect two peers

Use the component's `collab` prop when both diagrams run in a supported framework. Each peer gets its own transport connection and actor id, while both transports connect through the same room. The framework examples use [`MemoryHub`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-classes#memoryhub) to put two visible peers on one page; edits cross between their canvases. The plain JavaScript [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) entry point mounts a diagram, but does not expose that component prop.

For the framework bindings and typed graph data, see [Execute and compute flows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/execute-and-compute-flows); this page adds the per-peer `collab` configuration that connects mounted diagrams to the same sync room.

:::code-group
```html title="JavaScript"
<!-- The plain JavaScript render() API mounts a diagram but does not expose a collab option. -->
<div id="app" style="height: 460px"></div>
<script type="module">
  import { render } from '@grafloria/element';

  const container = document.getElementById('app');
  const instance = render({
    nodes: [
      { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
      { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
    ],
    edges: [{ id: 'e1', source: 'a', target: 'b' }],
  }, container);

  instance.fitView();
</script>
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { MemoryHub } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const hub = new MemoryHub();

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div style="display:flex; height:460px">
      <grafloria-diagram-canvas [(nodes)]="nodesA" [(edges)]="edgesA"
        [collab]="collabA" style="display:block; flex:1" />
      <grafloria-diagram-canvas [(nodes)]="nodesB" [(edges)]="edgesB"
        [collab]="collabB" style="display:block; flex:1" />
    </div>
  `,
})
export class AppComponent {
  nodesA: NodeSpec[] = [
    { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
    { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
  ];
  edgesA: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];
  nodesB: NodeSpec[] = [
    { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
    { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
  ];
  edgesB: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];
  collabA = { transport: hub.connect('ana'), actor: 'ana' };
  collabB = { transport: hub.connect('bo'), actor: 'bo' };
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type GrafloriaCollabOptions } from '@grafloria/qwik';
import { MemoryHub } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
  { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
];
const edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];

export default component$(() => {
  const collabA = useSignal<NoSerialize<GrafloriaCollabOptions> | undefined>();
  const collabB = useSignal<NoSerialize<GrafloriaCollabOptions> | undefined>();
  useVisibleTask$(() => {
    const hub = new MemoryHub();
    collabA.value = noSerialize({ transport: hub.connect('ana'), actor: 'ana' });
    collabB.value = noSerialize({ transport: hub.connect('bo'), actor: 'bo' });
  });

  const peerA = collabA.value;
  const peerB = collabB.value;
  return (
    <div style={{ display: 'flex', height: '460px' }}>
      {peerA && peerB && (
        <>
          <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} collab={peerA}
            style={{ display: 'block', flex: '1' }} />
          <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} collab={peerB}
            style={{ display: 'block', flex: '1' }} />
        </>
      )}
    </div>
  );
});
```
```tsx title="React"
import { useMemo } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import { MemoryHub } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
  { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
];
const edges: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];

export default function App() {
  const peers = useMemo(() => {
    const hub = new MemoryHub();
    return {
      a: { transport: hub.connect('ana'), actor: 'ana' },
      b: { transport: hub.connect('bo'), actor: 'bo' },
    };
  }, []);

  return (
    <div style={{ display: 'flex', height: 460 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} collab={peers.a}
        style={{ display: 'block', flex: 1 }} />
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} collab={peers.b}
        style={{ display: 'block', flex: 1 }} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import { MemoryHub } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const hub = new MemoryHub();
const nodesA: NodeSpec[] = [
  { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
  { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
];
const nodesB: NodeSpec[] = [
  { id: 'a', label: 'Alpha', position: { x: 80, y: 90 }, size: { width: 150, height: 66 } },
  { id: 'b', label: 'Beta', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
];
const edgesA: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];
const edgesB: EdgeSpec[] = [{ id: 'e1', source: 'a', target: 'b' }];
const collabA = { transport: hub.connect('ana'), actor: 'ana' };
const collabB = { transport: hub.connect('bo'), actor: 'bo' };
</script>

<template>
  <div style="display:flex; height:460px">
    <GrafloriaFlow :default-nodes="nodesA" :default-edges="edgesA" :collab="collabA"
      style="display:block; flex:1" />
    <GrafloriaFlow :default-nodes="nodesB" :default-edges="edgesB" :collab="collabB"
      style="display:block; flex:1" />
  </div>
</template>
```
:::

Each Angular, Qwik, React, and Vue version mounts two canvases with the same two nodes and connecting edge. Move a node in either pane: the other pane receives the operation and renders the edit. The framework canvas joins a CRDT sync session when it mounts and leaves when it unmounts; set up its collaboration options before mounting.

The diagram data is the document peers converge on. CRDT operations merge per property, so concurrent changes to different properties of the same node—for example, one peer moving it while another renames it—both survive. This is not whole-node last-write-wins replacement.

## Options and boundaries

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `collab` | Object containing a transport and actor id | Unset | Joins the canvas to a sync session. Give each peer a distinct actor id and connect its transport to the same room. |

The collaboration option is fixed for the lifetime of a mounted instance. If a peer needs a new transport or actor, mount an instance with that configuration rather than changing `collab` in place. In Qwik, create transports in `useVisibleTask$` and retain them with Qwik's non-serializable state handling; a live transport is not serializable application data.

Grafloria starts an anti-entropy round when a transport reports that it has reconnected, exchanging the operations each peer missed. Grafloria supplies convergence and the operation log, not your product's rooms, authentication, or storage; implement those at the transport and application layers.

## See the synchronization states

In the conflict-resolution demo, peer A moves a node while peer B renames it. The status readouts disagree before exchange and show both edits after they converge. The initial view shows both peers with the same `Draft` node.

[Open the live conflict-resolution demo](https://grafloria.com/demos/collab/conflict-resolution.html).

For disconnected edits, open the offline-and-reconnect demo. Disconnect both peers, edit each side, and reconnect; the missed operations are exchanged and both diagrams converge. Its initial view shows two matching diagrams with `Alpha` connected to `Beta`.

[Open the live offline-and-reconnect demo](https://grafloria.com/demos/collab/offline-and-reconnect.html).

For actual cross-tab collaboration without a server, open the two-tabs demo in two browser tabs. It uses `BroadcastChannel` for transport, so edits in either tab reach the other; each tab keeps its own viewport. Its initial view shows the same two-node diagram in both panes.

[Open the live two-tabs demo](https://grafloria.com/demos/collab/two-tabs-live.html).

## Pitfalls

- Use one hub/room for peers that share a document, but a distinct actor id for each peer. The sender does not receive its own echo from [`MemoryHub`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-classes#memoryhub).
- A shared transport has to report status changes if you rely on automatic reconnect catch-up.
- The plain JavaScript [`render`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core#render) API mounts a diagram but does not accept the framework `collab` prop. Its sample above demonstrates mounting only; it does not connect peers. Use a framework binding's collaboration prop for peer synchronization.
- Do not treat the collaboration channel as persistence or authorization. The app still owns rooms, identity, and storage.

## Related

- [Add presence and comments](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/add-presence-and-comments) — add live cursors and anchored threads to a collaboration session.
- [The graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document) — understand the document peers synchronize.
- [Command history and edits](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) — understand how local edits become operations.

<!-- source: add-presence-and-comments.md -->

# Add presence and comments

Use presence when participants need to see each other’s cursors and selections, and use anchored comment threads when discussion belongs to a node or link. A presenter can also broadcast a viewport so followers see the same world region and zoom.

## Show participants’ presence

Give each canvas a collaboration transport and a unique actor id. The flow joins its sync session when it mounts; setting `presence` adds live cursors and remote selection outlines. For a local, server-free example, connect two peers through [`MemoryHub`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-classes#memoryhub). Move the pointer over either canvas: the other pane shows that participant’s labelled cursor. Cursor presence is separate from diagram edits; it does not add cursor updates to the operation log.

```js
import { MemoryHub } from '@grafloria/engine';
import { render } from '@grafloria/element';
import { createSyncSession } from '@grafloria/engine';
import { bindPresence } from '@grafloria/renderer';

const hub = new MemoryHub();
const anaHost = document.createElement('div');
const boHost = document.createElement('div');
anaHost.style.cssText = 'height:400px; flex:1';
boHost.style.cssText = 'height:400px; flex:1';
document.body.append(anaHost, boHost);
const nodes = [
  { id: 'plan', label: 'Plan', position: { x: 70, y: 90 }, size: { width: 150, height: 66 } },
  { id: 'build', label: 'Build', position: { x: 320, y: 90 }, size: { width: 150, height: 66 } },
];
const edges = [{ id: 'e1', source: 'plan', target: 'build' }];
const ana = render({ nodes, edges }, anaHost);
const bo = render({ nodes, edges }, boHost);
const sessionAna = createSyncSession(ana.getModel(), hub.connect('ana'), { actor: 'ana' });
const sessionBo = createSyncSession(bo.getModel(), hub.connect('bo'), { actor: 'bo' });
sessionAna.join();
sessionBo.join();
bindPresence(ana, sessionAna, { name: 'Ana' });
bindPresence(bo, sessionBo, { name: 'Bo' });
```

Give both targets a real height:

```html
<div style="display:flex; height:400px">
  <div id="ana" style="flex:1"></div>
  <div id="bo" style="flex:1"></div>
</div>
```

The two-peer setup for React, Vue, Qwik, and Angular is shown in [Synchronize diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/synchronize-diagrams). For presence, add a display identity to each peer's `collab` value, such as `presence: { name: 'Ana' }`; the remote canvas then labels that participant's cursor.

In Qwik, set the same `collab` prop on each [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow). Wrap each live transport configuration in `noSerialize()` and create it in a visible task; the [Qwik live-cursors demo source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/apps/demos-qwik/gallery/demos/live-cursors.tsx) shows the binding.

[`bindPresence`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) accepts a mounted instance and a sync session; its options include the display name and cursor smoothing. Use it when you need to bind presence yourself rather than enabling it through a framework’s `collab` prop. [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) exposes the model used by a session and the viewport used by the renderer.

## Follow a presenter

Use a viewport channel when one participant drives the camera and others follow. [`InMemoryViewportChannel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) is the shipped in-process channel for two canvases on one page; replace it with a channel backed by your application’s network transport when participants are on separate clients. [`presentTo`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) broadcasts the presenter’s camera, and [`followPresenter`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core) applies it to a follower. The follower retains its own canvas size while matching the presenter’s world center and zoom.

```js
import { render } from '@grafloria/element';
import { InMemoryViewportChannel, followPresenter, presentTo } from '@grafloria/element';

const spec = {
  nodes: [
    { id: 'a', label: 'Plan', position: { x: 60, y: 80 }, size: { width: 130, height: 60 } },
    { id: 'b', label: 'Build', position: { x: 320, y: 80 }, size: { width: 130, height: 60 } },
  ],
  edges: [{ id: 'e1', source: 'a', target: 'b' }],
};
const presenterHost = document.createElement('div');
const followerHost = document.createElement('div');
presenterHost.style.cssText = 'height:400px; flex:1';
followerHost.style.cssText = 'height:400px; flex:1';
document.body.append(presenterHost, followerHost);
const presenter = render(spec, presenterHost);
const follower = render(spec, followerHost);
const channel = new InMemoryViewportChannel();
const presenting = presentTo(presenter, channel, { presenterId: 'ana' });
const following = followPresenter(follower, channel, { ignorePresenterId: 'bo' });
presenter.fitView(60);
```

Give both mount targets a height as in the earlier example. Panning or zooming the presenter then moves the follower’s camera to the corresponding view. Keep the returned handles and call their `stop()` methods when presentation ends. To make a follower read-only as well, lock its engine with the presentation-mode API; camera following and document edit permission are separate concerns.

Live demo: [Presentation mode](https://grafloria.com/demos/collab/presentation-mode.html).

The presentation helpers accept the same host shape used by a mounted [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance), so the setup can run from a framework’s init/ready callback. The wrapper-specific way to capture that instance is shown in the React, Vue, and Qwik bindings’ `onInit` callback and the Angular canvas component’s instance accessors.

## Add anchored comment threads

Enable `comments` on the canvas, get its store from the mounted instance, and pass that store to the shipped comment panel. The panel renders the thread list and composer; `createThread()` starts a thread anchored to a node or link, and `reply()` adds a message to it. In this example, the panel shows a two-message conversation attached to the Review node.

React and Vue use the same comment-panel setup as their quick starts: [React quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/react-quick-start) and [Vue quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/vue-quick-start). This page focuses on the added reply, so the thread panel shows a conversation rather than only its opening comment.

:::code-group
```tsx title="Qwik"
import { $, component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaCommentPanel, GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import type { CommentStore } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'design', position: { x: 80, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Design' } },
  { id: 'review', position: { x: 330, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Review' } },
  { id: 'ship', position: { x: 580, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Ship' } },
];
const edges: EdgeSpec[] = [
  { id: 'e1', source: 'design', target: 'review' },
  { id: 'e2', source: 'review', target: 'ship' },
];

function panelBound(root: HTMLElement | undefined): Promise<void> {
  return new Promise((resolve) => {
    const poll = () => {
      if (root?.querySelector('[data-grafloria-comment-panel]')) resolve();
      else requestAnimationFrame(poll);
    };
    poll();
  });
}

export default component$(() => {
  const root = useSignal<HTMLDivElement>();
  const store = useSignal<NoSerialize<CommentStore>>();
  return (
    <div ref={root} style={{ display: 'flex', height: '400px' }}>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        comments
        style={{ flex: 1 }}
        onInit$={$(async (instance: DiagramInstance) => {
          const comments = instance.getCommentStore();
          if (!comments) return;
          store.value = noSerialize(comments);
          await panelBound(root.value);
          const thread = comments.createThread({ kind: 'node', id: 'review' }, 'Can we tighten the hero copy?');
          comments.reply(thread, 'On it — draft by Friday.');
        })}
      />
      {store.value && <GrafloriaCommentPanel store={store.value} />}
    </div>
  );
});
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaCommentPanelComponent } from '@grafloria/angular';
import type { CommentStore } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaCommentPanelComponent],
  template: `
    <div style="display:flex; height:400px">
      <grafloria-diagram-canvas [nodes]="nodes" [edges]="edges" [comments]="true" style="display:block; flex:1" />
      @if (store) { <grafloria-comment-panel [store]="store" /> }
    </div>
  `,
})
export class CommentsDemoComponent implements AfterViewInit {
  canvas = viewChild.required(DiagramCanvasComponent);
  store: CommentStore | null = null;
  nodes: NodeSpec[] = [
    { id: 'design', position: { x: 80, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Design' } },
    { id: 'review', position: { x: 330, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Review' } },
    { id: 'ship', position: { x: 580, y: 120 }, size: { width: 150, height: 66 }, data: { label: 'Ship' } },
  ];
  edges: EdgeSpec[] = [
    { id: 'e1', source: 'design', target: 'review' },
    { id: 'e2', source: 'review', target: 'ship' },
  ];
  ngAfterViewInit() {
    this.store = this.canvas().getCommentStore();
    if (this.store) {
      const thread = this.store.createThread({ kind: 'node', id: 'review' }, 'Can we tighten the hero copy?');
      this.store.reply(thread, 'On it — draft by Friday.');
    }
  }
}
```
:::

For Qwik's component, store, and panel setup, see the [Qwik quick start](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/qwik-quick-start); this page adds a reply so the anchored thread contains a conversation.

For plain JavaScript, mount a store on the rendered model and render a conversation from its thread view:

```js
import { CommentStore } from '@grafloria/engine';
import { render } from '@grafloria/element';

const diagramHost = document.createElement('div');
const conversationHost = document.createElement('div');
diagramHost.style.height = '400px';
document.body.append(diagramHost, conversationHost);
const instance = render({
  nodes: [
    { id: 'review', label: 'Review', position: { x: 120, y: 90 }, size: { width: 180, height: 70 } },
  ],
}, diagramHost);
const store = new CommentStore(instance.getModel(), { viewer: 'ana' });
const threadId = store.createThread({ kind: 'node', id: 'review' }, 'Can we tighten the hero copy?');
store.reply(threadId, 'On it — draft by Friday.');
const thread = store.thread(threadId);
if (thread) conversationHost.textContent = thread.messages.map((message) => message.body).join('\n');
```

The framework examples use the shipped comment panel instead of hand-building the conversation UI.

Live demo: [Threaded comments](https://grafloria.com/demos/collab/comments.html).

## Options and behavior

| Option or call | Type | Default | What it does |
|---|---|---|---|
| `collab` | transport, actor id, and optional sync settings | unset | Joins a collaboration session for the mounted canvas. A framework flow leaves the session when it unmounts. |
| `presence` in `collab` | `boolean \| BindPresenceOptions` | off | Enables live cursor and remote selection presence; an object can set identity and cursor smoothing. |
| `comments` | `boolean \| CommentStore` | unset | Enables anchored comments; `true` creates a store, or pass a shared store. |
| `commentsViewer` | `string` | `'local'` for a created store | Sets the viewer id for a store created by the canvas. |
| `bindPresence()` | `(instance, syncSession, options?) => PresenceBinding` | — | Connects a live instance to session awareness; the returned binding has `dispose()`. |
| `presentTo()` | `(host, channel, options?) => { stop }` | 50 ms broadcast throttle | Publishes viewport center and zoom; the trailing update sends the final camera position. |
| `followPresenter()` | `(host, channel, options?) => { stop }` | — | Applies presenter center and zoom while retaining the follower’s viewport dimensions. |
| `createThread()` | `(anchor, body) => string` | — | Creates a thread and returns its id. |
| `reply()` | `(threadId, body) => string` | — | Adds a reply and returns the new message id. |

The collaboration layer supplies convergence, presence, and comments. Your application still provides rooms, authentication, storage, and a network transport for clients on different devices. `MemoryHub` and `InMemoryViewportChannel` are in-process examples, not network transports.

## Pitfalls

- Give each simultaneous peer its own actor id, while keeping peers in the same room on transports that connect them to one another.
- `collab` is fixed for the lifetime of a mounted framework instance; supply the transport and actor before mounting.
- In Qwik, transports and comment stores are live objects. Keep them out of serializable component state with `noSerialize()` and create them on the client where needed.
- A presenter channel broadcasts only camera state. It does not synchronize the document or enforce read-only mode. Use collaboration sync for document changes and the presentation lock when followers must not edit.

## Demos

- [Live cursors](https://grafloria.com/demos/collab/live-cursors.html) — move over either pane to see the remote cursor and selection.
- [Presentation mode](https://grafloria.com/demos/collab/presentation-mode.html) — pan and zoom the presenter pane to drive the follower’s view.
- [Threaded comments](https://grafloria.com/demos/collab/comments.html) — start a comment and reply in its thread.

Related: [Synchronize diagrams](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/synchronize-diagrams), [the graph model and document](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/graph-model-and-document), and [the instance and data flow](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/instance-and-data-flow).

<!-- source: draw-on-a-whiteboard.md -->

# Draw on a whiteboard

Use a mounted canvas to draw freehand marks, change a committed mark's style, and remove a mark. Draw a closed outline when you want a freehand shape: it remains ink, not a diagram node.

## When to use this

Use the freehand tool for annotations, sketches, arrows, and outlines that belong on top of a diagram. A committed mark is a vector stroke, not a screenshot. The live draw preview follows the pointer; releasing commits the stroke to the mounted diagram.

[`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) is the mounted canvas facade: its `getModel()` reaches the diagram data and its `renderNow()` repaints after a change. [`createDrawTool`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-functions#createdrawtool) creates a tool for that live canvas, and [`registerTool`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-functions#registertool) connects it to the canvas's pointer-tool registry. The instance satisfies [`WhiteboardHost`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-v-w#whiteboardhost), which the tool factory accepts.

## Mount the canvas and draw

1. Start with an empty diagram and a red pen; draw a line or return to its starting point to make a closed outline.
2. Register the draw tool after the canvas instance exists. Use the toolbar buttons to recolor the first committed mark or remove it.

In the JavaScript, Angular, React, and Vue examples, **Edit first mark** changes the live stroke's style and **Erase first mark** removes it from the live model. Either button does nothing until you draw. Those examples hold the mounted instance in the framework's normal lifecycle state and unregister the tool when that owner unmounts.

:::code-group
```js title="JavaScript"
import { render } from '@grafloria/element';
import { createDrawTool, registerTool } from '@grafloria/renderer';

const app = document.getElementById('app');
if (!app) throw new Error('Missing #app');

const toolbar = document.createElement('div');
const canvas = document.createElement('div');
canvas.style.height = '400px';
app.append(toolbar, canvas);

const editButton = document.createElement('button');
editButton.textContent = 'Edit first mark';
const eraseButton = document.createElement('button');
eraseButton.textContent = 'Erase first mark';
toolbar.append(editButton, eraseButton);

const instance = render({ nodes: [], edges: [] }, canvas);
const unregisterTool = registerTool(
  createDrawTool(instance, { color: '#e11d48', width: 3, simplifyEpsilon: 0.8 })
);

editButton.addEventListener('click', () => {
  const stroke = instance.getModel().getStrokes()[0];
  if (!stroke) return;
  stroke.setStyle({ color: '#2563eb', width: 5 });
  instance.renderNow();
});

eraseButton.addEventListener('click', () => {
  const stroke = instance.getModel().getStrokes()[0];
  if (!stroke) return;
  instance.getModel().removeStroke(stroke.id);
  instance.renderNow();
});

window.addEventListener('pagehide', () => {
  unregisterTool();
  instance.dispose();
}, { once: true });
```
```ts title="Angular"
import { AfterViewInit, Component, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { createDrawTool, registerTool, type WhiteboardHost } from '@grafloria/renderer';

@Component({
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div>
      <button type="button" (click)="editFirstMark()">Edit first mark</button>
      <button type="button" (click)="eraseFirstMark()">Erase first mark</button>
    </div>
    <div #host style="display:block; height:400px">
      <grafloria-diagram-canvas style="display:block; height:100%" />
    </div>
  `,
})
export class WhiteboardComponent implements AfterViewInit, OnDestroy {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly hostElement = viewChild.required<ElementRef<HTMLElement>>('host');
  private unregisterTool: (() => void) | undefined;

  ngAfterViewInit(): void {
    const canvas = this.canvas();
    const whiteboardHost: WhiteboardHost = {
      getModel: () => canvas.activeEngine()!.getDiagram()!,
      getEngine: () => canvas.activeEngine() ?? null,
      get viewport() { return canvas.viewportController()!; },
      container: this.hostElement().nativeElement,
      render: () => canvas.scheduleRender(),
    };
    this.unregisterTool = registerTool(
      createDrawTool(whiteboardHost, { color: '#e11d48', width: 3, simplifyEpsilon: 0.8 })
    );
  }

  editFirstMark(): void {
    const canvas = this.canvas();
    const stroke = canvas.activeEngine()?.getDiagram()?.getStrokes()[0];
    if (!stroke) return;
    stroke.setStyle({ color: '#2563eb', width: 5 });
    canvas.scheduleRender();
  }

  eraseFirstMark(): void {
    const canvas = this.canvas();
    const model = canvas.activeEngine()?.getDiagram();
    const stroke = model?.getStrokes()[0];
    if (!model || !stroke) return;
    model.removeStroke(stroke.id);
    canvas.scheduleRender();
  }

  ngOnDestroy(): void {
    this.unregisterTool?.();
  }
}
```
```tsx title="Qwik"
import { $, component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { createDrawTool, registerTool } from '@grafloria/element';

export default component$(() => {
  const hostRef = useSignal<HTMLDivElement>();

  return (
    <div ref={hostRef} style={{ display: 'block', height: '400px' }}>
      <GrafloriaFlow
        defaultNodes={[]}
        defaultEdges={[]}
        style={{ display: 'block', height: '100%' }}
        onInit$={$((instance: DiagramInstance) => {
          registerTool(createDrawTool(instance, { color: '#e11d48', width: 3, simplifyEpsilon: 0.8 }));
        })}
      />
    </div>
  );
});
```
```tsx title="React"
import { useEffect, useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import { createDrawTool, registerTool } from '@grafloria/renderer';

export function Whiteboard() {
  const instanceRef = useRef<DiagramInstance | null>(null);
  const unregisterRef = useRef<(() => void) | null>(null);

  useEffect(() => () => {
    unregisterRef.current?.();
  }, []);

  const onInit = (instance: DiagramInstance): void => {
    instanceRef.current = instance;
    unregisterRef.current = registerTool(
      createDrawTool(instance, { color: '#e11d48', width: 3, simplifyEpsilon: 0.8 })
    );
  };

  const editFirstMark = (): void => {
    const instance = instanceRef.current;
    const stroke = instance?.getModel().getStrokes()[0];
    if (!instance || !stroke) return;
    stroke.setStyle({ color: '#2563eb', width: 5 });
    instance.renderNow();
  };

  const eraseFirstMark = (): void => {
    const instance = instanceRef.current;
    const stroke = instance?.getModel().getStrokes()[0];
    if (!instance || !stroke) return;
    instance.getModel().removeStroke(stroke.id);
    instance.renderNow();
  };

  return (
    <section>
      <div>
        <button type="button" onClick={editFirstMark}>Edit first mark</button>
        <button type="button" onClick={eraseFirstMark}>Erase first mark</button>
      </div>
      <GrafloriaFlow
        defaultNodes={[]}
        defaultEdges={[]}
        style={{ display: 'block', height: '400px' }}
        onInit={onInit}
      />
    </section>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/vue';
import { createDrawTool, registerTool } from '@grafloria/renderer';

const instance = ref<DiagramInstance | null>(null);
let unregisterTool: (() => void) | undefined;

function onInit(liveInstance: DiagramInstance): void {
  instance.value = liveInstance;
  unregisterTool = registerTool(
    createDrawTool(liveInstance, { color: '#e11d48', width: 3, simplifyEpsilon: 0.8 })
  );
}

function editFirstMark(): void {
  const liveInstance = instance.value;
  const stroke = liveInstance?.getModel().getStrokes()[0];
  if (!liveInstance || !stroke) return;
  stroke.setStyle({ color: '#2563eb', width: 5 });
  liveInstance.renderNow();
}

function eraseFirstMark(): void {
  const liveInstance = instance.value;
  const stroke = liveInstance?.getModel().getStrokes()[0];
  if (!liveInstance || !stroke) return;
  liveInstance.getModel().removeStroke(stroke.id);
  liveInstance.renderNow();
}

onBeforeUnmount(() => unregisterTool?.());
</script>

<template>
  <section>
    <div>
      <button type="button" @click="editFirstMark">Edit first mark</button>
      <button type="button" @click="eraseFirstMark">Erase first mark</button>
    </div>
    <GrafloriaFlow style="display:block; height:400px" @init="onInit" />
  </section>
</template>
```
:::

For Qwik, mount [`GrafloriaFlow`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-qwik#grafloriaflow) and register the draw tool from `onInit$`, which receives the mounted instance. See the [Qwik demo gallery](https://grafloria.com/demos-qwik/) for runnable Qwik examples.

The drawing interaction is the same in every binding: draw with a mouse, pen, or finger, then release to commit a stroke. For a freehand shape, trace a closed path yourself. In the JavaScript, Angular, React, and Vue examples, the first toolbar action recolors and widens the first live stroke; the second removes that whole stroke. Both update the mounted canvas, not a detached model.

## Tune the pen

[`DrawToolOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-a-t#drawtooloptions) controls the created pen. The defaults below come from the tool implementation; `simplifyEpsilon` is left to the model's tuned default when omitted.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `color` | `string` | `'#1f2933'` | Sets the ink and live preview color. |
| `width` | `number` | `3` | Sets the stroke width and preview width. |
| `opacity` | `number` | Not set | Sets ink opacity; use it for translucent highlighter marks. |
| `simplifyEpsilon` | `number` | Model's tuned default | Sets the Douglas–Peucker tolerance applied when the gesture commits. |
| `label` | `string` | Not set | Gives committed ink an accessible name. |
| `active` | `boolean` | `true` | Set to `false` to create the draw tool inactive. |

## What to know

- `registerTool()` is a registry operation, so keep its returned disposer and call it when the owning view unmounts. Registering another tool with the same id replaces the current one; disposing restores the previous registration.
- These toolbar actions call model methods directly. They update the document and repaint, but they do not create a user-gesture history command. For command-based undo behavior, see [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history).
- The pen stays active for pointer gestures. Do not leave multiple point-agnostic drawing modes active together.

## See the pointer-driven tools

The freehand demo shows the pen on a blank canvas; drag a line and release to commit crisp vector ink.

Live demo: [Freehand draw](https://grafloria.com/demos/whiteboard/freehand-draw.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/whiteboard/freehand-draw.html)

The rectangle demo starts ready for a drag that creates a box node, rather than a stroke.

Live demo: [Rectangle tool](https://grafloria.com/demos/whiteboard/rectangle.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/whiteboard/rectangle.html)

The eraser demo loads with three parallel strokes; its pointer sweep removes whole strokes.

Live demo: [Eraser](https://grafloria.com/demos/whiteboard/eraser.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/whiteboard/eraser.html)

The stroke-edit demo loads with the draw and edit controls; draw ink, choose edit, and drag a committed mark to translate it.

Live demo: [Stroke edit](https://grafloria.com/demos/whiteboard/stroke-edit.html) · [source](https://github.com/grafloria/grafloria/blob/6538c1506102712e4265e25bd8ffbb240b3e5038/demos/whiteboard/stroke-edit.html)

## Related

- [Command history](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/command-history) — understand how user gestures become undoable commands.
- [Build runnable workflows](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/build-runnable-workflows) — mount and configure a usable canvas.

<!-- source: grafloria-react.md -->

# @grafloria/react

React bindings for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, native in React.

## Install

```bash
npm install @grafloria/react @grafloria/engine @grafloria/renderer react react-dom @grafloria/element
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.0
- `@grafloria/renderer` ^0.4.16
- `react` ^17.0.0 || ^18.0.0 || ^19.0.0
- `react-dom` ^17.0.0 || ^18.0.0 || ^19.0.0
- `@grafloria/element` ^0.4.3

## Functions

### `createGrafloriaStore`

```ts
function createGrafloriaStore(): GrafloriaStore
```

### `GrafloriaCommentPanel`

```ts
function GrafloriaCommentPanel(props: GrafloriaCommentPanelProps)
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `CommentStore` |  |  |
| `options?` | `CommentPanelOptions` |  |  |
| `onSelect?` | `(threadId: string) => void` |  |  |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |

**Events**

- `onSelect`

### `GrafloriaDashboard`

```ts
function GrafloriaDashboard(props: GrafloriaDashboardProps)
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  | Multi-view (tabbed) board. Mutually exclusive with `widgets`. |
| `widgets?` | `DashboardWidgetSpec[]` |  | Single-view shorthand. |
| `options?` | `Partial<DashboardOptions>` |  | Board options: columns, gap, sizing, rtl, responsive, binder… |
| `widgetTypes?` | `WidgetTypes` |  | Maps a widget `kind` to the React component that renders it. |
| `activeView?` | `string` |  | The visible view (the tab pattern). Omit for kit-managed. |
| `layout?` | `"split" \| "grid"` |  | LIVE SWITCHES — the toolbar toggles as props. Each is applied at mount |
| `sizing?` | `"fit" \| "grow"` |  |  |
| `static?` | `boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |
| `onReady?` | `(handle: DashboardHandle) => void` |  | The typed handle, once the board is live. |
| `onLayoutChange?` | `(change: { viewId: string; widgets: DashboardWidgetSpec[]; }) => void` |  | Mirrors the kit's committed gestures (drag, resize, add, remove). |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |
| `children?` | `ReactNode` |  |  |

**Events**

- `onReady` — The typed handle, once the board is live.
- `onLayoutChange` — Mirrors the kit's committed gestures (drag, resize, add, remove).

### `GrafloriaDiagram`

```ts
function GrafloriaDiagram(props: GrafloriaDiagramProps)
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — `erDiagram(...)`, `umlDiagram(...)`, `dashboard(...)`, or DSL text. |
| `options?` | `RenderOptions` |  | Options passed through to the underlying `createDiagram`. |
| `onReady?` | `(instance: DiagramInstance) => void` |  |  |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |

**Events**

- `onReady`

### `GrafloriaFlow`

```ts
function GrafloriaFlow(props: GrafloriaFlowProps)
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  | Controlled nodes. Provide with `onNodesChange` (see `useNodesState`). |
| `edges?` | `EdgeSpec[]` |  | Controlled edges. |
| `groups?` | `(GroupModel \| GroupSpec)[]` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live |
| `defaultNodes?` | `NodeSpec[]` |  | Uncontrolled nodes — the instance owns them from here on. |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `(GroupModel \| GroupSpec)[]` |  |  |
| `onNodesChange?` | `(nodes: NodeModel[]) => void` |  |  |
| `onEdgesChange?` | `(edges: LinkModel[]) => void` |  |  |
| `onSelectionChange?` | `(change: { nodes: NodeModel[]; edges: LinkModel[]; }) => void` |  |  |
| `onConnect?` | `(change: { link: LinkModel; }) => void` |  |  |
| `onNodeClick?` | `(change: { node: NodeModel; world: { x: number; y: number; }; }) => void` |  |  |
| `onEdgeClick?` | `(change: { edge: LinkModel; world: { x: number; y: number; }; }) => void` |  |  |
| `onInit?` | `(instance: DiagramInstance) => void` |  |  |
| `nodeTypes?` | `NodeTypes` |  | Custom node components, keyed by node `type`. |
| `theme?` | `Theme` |  |  |
| `fitView?` | `boolean` |  |  |
| `enablePan?` | `boolean` |  |  |
| `enableZoom?` | `boolean` |  |  |
| `zoomSensitivity?` | `number` |  |  |
| `dragThreshold?` | `number` |  |  |
| `readonly?` | `boolean` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `ssr?` | `{ html: string; snapshot: HydrationSnapshot; }` |  | The `renderToStaticSVG()` result. Renders server-side, hydrates client-side. |
| `layout?` | `string \| { name: string; options?: Record<string, unknown>; }` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', |
| `onLayoutDone?` | `(result: unknown) => void` |  | Fires after each declarative layout completes. |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background |
| `collab?` | `GrafloriaCollabOptions` |  | Real-time collaboration: hand in a transport (BroadcastChannelTransport, |
| `onCollabReady?` | `(session: SyncAdapter) => void` |  | The live SyncAdapter, right after `join()`. |
| `comments?` | `boolean \| CommentStore` |  | Anchored comment threads — `true` creates a store, or pass a shared |
| `commentsViewer?` | `string` |  | Viewer id for a `comments: true`-created store. |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer Angular's canvas draws: outlines around the hovered node, |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |
| `children?` | `ReactNode` |  | Overlays (toolbars, panels). Rendered as siblings of the canvas. |

**Events**

- `onNodesChange`
- `onEdgesChange`
- `onSelectionChange`
- `onConnect`
- `onNodeClick`
- `onEdgeClick`
- `onInit`
- `onLayoutDone` — Fires after each declarative layout completes.
- `onCollabReady` — The live SyncAdapter, right after `join()`.

### `GrafloriaProvider`

Wrap anything that needs `useGrafloria()` outside of `<GrafloriaFlow>`'s subtree.

```tsx
<GrafloriaProvider>
  <Toolbar />           // useGrafloria() works here…
  <GrafloriaFlow … />       // …because the flow publishes its instance to the store
</GrafloriaProvider>
```

`<GrafloriaFlow>` also creates its own store when there is no provider, so the
simple single-canvas case needs no wrapper at all.

```ts
function GrafloriaProvider({ children }: GrafloriaProviderProps)
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children?` | `ReactNode` |  |  |

### `useEdgesState`

Controlled edge state. Mirrors {@link useNodesState}.

```ts
function useEdgesState(initial: EdgeSpec[] = []): EdgesState
```

### `useGrafloria`

The live `DiagramInstance`, or `null` until `<GrafloriaFlow>` has mounted.

Works from anywhere inside an `<GrafloriaProvider>` (a toolbar, a minimap, a
sidebar) and from inside `<GrafloriaFlow>`'s own children.

```tsx
const grafloria = useGrafloria();
<button onClick={() => grafloria?.fitView()}>Fit</button>
```

```ts
function useGrafloria(): DiagramInstance | null
```

### `useGrafloriaStore`

The nearest store, or null when there is no provider above us.

```ts
function useGrafloriaStore(): GrafloriaStore | null
```

### `useNodesState`

Controlled node state — the React Flow tuple everyone already knows:

```tsx
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
<GrafloriaFlow nodes={nodes} onNodesChange={onNodesChange} … />
```

`onNodesChange` is what closes the loop: the user drags a node, the ENGINE
moves it, the instance emits `nodes:change`, `<GrafloriaFlow>` calls this, and
React state catches up. Without it a controlled `<GrafloriaFlow>` would snap the
node back on the next render — the classic controlled-component trap.

```ts
function useNodesState(initial: NodeSpec[] = []): NodesState
```

### `useOnSelectionChange`

Fire a callback whenever the selection changes.

```tsx
useOnSelectionChange(({ nodes }) => setInspected(nodes[0] ?? null));
```

The handler is held in a ref, so passing an inline arrow (the common case)
does NOT re-subscribe on every render.

```ts
function useOnSelectionChange(handler: (change: SelectionChange) => void): void
```

### `useSelection`

The current selection as state (for rendering an inspector panel).

```ts
function useSelection(): SelectionChange
```

### `useViewport`

The live camera (zoom + world rect) as state — for a minimap or a zoom badge.

```ts
function useViewport(): { zoom: number; x: number; y: number }
```

## Constants

### `GrafloriaContext`

```ts
const GrafloriaContext: any
```

## Interfaces

### `GrafloriaCommentPanelProps`

```ts
interface GrafloriaCommentPanelProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `CommentStore` |  |  |
| `options?` | `CommentPanelOptions` |  |  |
| `onSelect?` | `(threadId: string \| null) => void` |  |  |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |

### `GrafloriaDashboardProps`

```ts
interface GrafloriaDashboardProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  | Multi-view (tabbed) board. Mutually exclusive with `widgets`. |
| `widgets?` | `DashboardWidgetSpec[]` |  | Single-view shorthand. |
| `options?` | `Partial<DashboardOptions>` |  | Board options: columns, gap, sizing, rtl, responsive, binder… |
| `widgetTypes?` | `WidgetTypes` |  | Maps a widget `kind` to the React component that renders it. |
| `activeView?` | `string` |  | The visible view (the tab pattern). Omit for kit-managed. |
| `layout?` | `'grid' \| 'split'` |  | LIVE SWITCHES — the toolbar toggles as props. Each is applied at mount (over `options`) and, when it changes afterwards, through the handle (`setLayout` / `setSizing` / `setStatic`) — no remount, like `activeView`. 'split' is the DevExpress splitter tree; 'grid' the cell grid. |
| `sizing?` | `'fit' \| 'grow'` |  |  |
| `static?` | `boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |
| `onReady?` | `(handle: DashboardHandle) => void` |  | The typed handle, once the board is live. |
| `onLayoutChange?` | `(change: { viewId: string; widgets: DashboardWidgetSpec[] }) => void` |  | Mirrors the kit's committed gestures (drag, resize, add, remove). |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |
| `children?` | `ReactNode` |  |  |

### `GrafloriaDiagramProps`

```ts
interface GrafloriaDiagramProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — `erDiagram(...)`, `umlDiagram(...)`, `dashboard(...)`, or DSL text. |
| `options?` | `RenderOptions` |  | Options passed through to the underlying `createDiagram`. |
| `onReady?` | `(instance: DiagramInstance) => void` |  |  |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |

### `GrafloriaFlowProps`

```ts
interface GrafloriaFlowProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  | Controlled nodes. Provide with `onNodesChange` (see `useNodesState`). |
| `edges?` | `EdgeSpec[]` |  | Controlled edges. |
| `groups?` | `Array<GroupSpec \| GroupModel>` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live GroupModels of a loaded document). Reconciled like `nodes`. |
| `defaultNodes?` | `NodeSpec[]` |  | Uncontrolled nodes — the instance owns them from here on. |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `Array<GroupSpec \| GroupModel>` |  |  |
| `onNodesChange?` | `(nodes: NodeModel[]) => void` |  |  |
| `onEdgesChange?` | `(edges: LinkModel[]) => void` |  |  |
| `onSelectionChange?` | `(change: { nodes: NodeModel[]; edges: LinkModel[] }) => void` |  |  |
| `onConnect?` | `(change: { link: LinkModel }) => void` |  |  |
| `onNodeClick?` | `(change: { node: NodeModel; world: { x: number; y: number } }) => void` |  |  |
| `onEdgeClick?` | `(change: { edge: LinkModel; world: { x: number; y: number } }) => void` |  |  |
| `onInit?` | `(instance: DiagramInstance) => void` |  |  |
| `nodeTypes?` | `NodeTypes` |  | Custom node components, keyed by node `type`. |
| `theme?` | `Theme` |  |  |
| `fitView?` | `boolean` |  |  |
| `enablePan?` | `boolean` |  |  |
| `enableZoom?` | `boolean` |  |  |
| `zoomSensitivity?` | `number` |  |  |
| `dragThreshold?` | `number` |  |  |
| `readonly?` | `boolean` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `ssr?` | `{ html: string; snapshot: HydrationSnapshot }` |  | The `renderToStaticSVG()` result. Renders server-side, hydrates client-side. |
| `layout?` | `string \| { name: string; options?: Record<string, unknown> }` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', 'force', 'tree', 'grid', 'auto', …) or `{ name, options }`. Re-runs when the prop VALUE changes, never when node data changes. |
| `onLayoutDone?` | `(result: unknown) => void` |  | Fires after each declarative layout completes. |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background grid with defaults; an object picks and configures them. |
| `collab?` | `GrafloriaCollabOptions` |  | Real-time collaboration: hand in a transport (BroadcastChannelTransport, WebSocketTransport, MemoryTransport, …) and an actor id — the flow joins a CRDT sync session at mount and leaves on unmount. Fixed for the life of the instance. |
| `onCollabReady?` | `(session: SyncAdapter) => void` |  | The live SyncAdapter, right after `join()`. |
| `comments?` | `boolean \| CommentStore` |  | Anchored comment threads — `true` creates a store, or pass a shared `CommentStore`. Read it back with `useGrafloria()?.getCommentStore()`. |
| `commentsViewer?` | `string` |  | Viewer id for a `comments: true`-created store. |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer Angular's canvas draws: outlines around the hovered node, the selected node, nodes with a validation issue, and valid connection targets. `true` turns every kind on; an object turns kinds on or off one by one. Off when unset. Live: follows the prop by value. |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or options (depth, stroke, outgoing, dimOpacity). Off when unset. Live: follows the prop by value. |
| `className?` | `string` |  |  |
| `style?` | `CSSProperties` |  |  |
| `children?` | `ReactNode` |  | Overlays (toolbars, panels). Rendered as siblings of the canvas. |

### `GrafloriaProviderProps`

```ts
interface GrafloriaProviderProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children?` | `ReactNode` |  |  |

### `GrafloriaStore`

The provider + the store behind `useGrafloria()`.

React Flow's ergonomics come from exactly this shape: a `<ReactFlowProvider>`
that lets a toolbar, a sidebar or a minimap — components that are SIBLINGS of
the canvas, not children of it — reach the live instance. We keep that shape,
but the thing being shared is our framework-agnostic `DiagramInstance`, so the
provider is a 40-line store and NOT a re-implementation of the diagram.

Why a hand-rolled store rather than `useSyncExternalStore`: that hook is React
18+, and this package supports React 17–19. Subscribe + `useState` costs one
extra render on attach and works everywhere.

```ts
interface GrafloriaStore
```

**Members**

- `get(): DiagramInstance | null` — The live instance, or null before `<GrafloriaFlow>` has mounted.
- `set(instance: DiagramInstance | null): void` — Called by `<GrafloriaFlow>` on mount/unmount.
- `subscribe(listener: (instance: DiagramInstance | null) => void): () => void` — Notified whenever the instance is attached or detached.

### `NodeProps`

Props a custom node component receives. Deliberately React-Flow-shaped.

```ts
interface NodeProps<TData = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `data` | `TData` |  |  |
| `selected` | `boolean` |  |  |
| `node` | `NodeModel` |  | The live engine model — the escape hatch. |

### `SelectionChange`

```ts
interface SelectionChange
```

**Properties**

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

### `WidgetProps`

Props a widget component receives — the `NodeProps` twin for boards.

```ts
interface WidgetProps<TData = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `widget` | `DashboardWidgetSpec` |  |  |
| `data` | `TData` |  |  |

## Types

### `EdgesState`

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

```ts
type EdgesState = [
  EdgeSpec[],
  Dispatch<SetStateAction<EdgeSpec[]>>,
  (edges: LinkModel[]) => void,
];
```

### `NodesState`

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

What `useNodesState` hands back — React Flow's tuple, with our types.

```ts
type NodesState = [
  NodeSpec[],
  Dispatch<SetStateAction<NodeSpec[]>>,
  (nodes: NodeModel[]) => void,
];
```

### `NodeTypes`

`nodeTypes` maps a node's `type` to the component that renders it.

```ts
type NodeTypes = Record<string, ComponentType<NodeProps<never>>>;
```

### `WidgetTypes`

```ts
type WidgetTypes = Record<string, ComponentType<WidgetProps>>;
```

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `HydrationSnapshot`, `LIGHT_THEME`, `NodeSpec`, `PortSpec`, `renderToStaticSVG`, `StaticRenderOptions`, `StaticRenderResult`, `Theme`

<!-- source: grafloria-qwik.md -->

# @grafloria/qwik

Qwik bindings for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, server-rendered and resumable in Qwik.

## Install

```bash
npm install @grafloria/qwik @grafloria/engine @grafloria/renderer @builder.io/qwik @grafloria/element
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.0
- `@grafloria/renderer` ^0.4.18
- `@builder.io/qwik` ^1.5.0
- `@grafloria/element` ^0.4.3

## Functions

### `useGrafloria`

The live `DiagramInstance` signal. Falls back to a component-local signal
when there is no `<GrafloriaProvider>` above, so the hook is always safe to
call — it simply never fills in without a provider or a sibling flow.

```ts
function useGrafloria(): GrafloriaStore
```

### `useOnSelectionChangeQrl`

Fire a QRL on every selection change; teardown is automatic.

The handler is a QRL rather than a plain function because Qwik has to be
able to serialize the subscription and load the handler lazily — that is
the whole point of the `$` suffix, and it is why this reads
`useOnSelectionChange$(...)` at the call site.

```ts
function useOnSelectionChangeQrl(handler: QRL<(change: SelectionChange) => void>): void
```

### `useSelection`

The current selection as reactive state (for an inspector panel).

```ts
function useSelection(): Signal<SelectionChange>
```

### `useViewport`

The live camera (zoom + world origin) as reactive state.

```ts
function useViewport(): Signal<{ zoom: number; x: number; y: number }>
```

## Constants

### `GRAFLORIA_STORE`

```ts
const GRAFLORIA_STORE: any
```

### `GrafloriaCommentPanel`

```ts
const GrafloriaCommentPanel: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `NoSerialize<CommentStore>` |  | The live comment store. Must be `noSerialize()`d. |
| `options?` | `CommentPanelOptions` |  |  |
| `onSelect$?` | `QRL<(threadId: string) => void>` |  |  |
| `class?` | `string` |  |  |

**Events**

- `onSelect$`

### `GrafloriaDashboard`

```ts
const GrafloriaDashboard: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  |  |
| `widgets?` | `DashboardWidgetSpec[]` |  |  |
| `options?` | `Partial<DashboardOptions>` |  |  |
| `activeView?` | `string` |  | The visible view. |
| `layout?` | `"split" \| "grid"` |  | LIVE SWITCHES — the toolbar toggles as props: applied at mount (over |
| `sizing?` | `"fit" \| "grow"` |  |  |
| `static?` | `boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |
| `widgetTypes?` | `WidgetTypes` |  | Qwik components for widget kinds, keyed by `kind`. |
| `onReady$?` | `QRL<(handle: DashboardHandle) => void>` |  |  |
| `onLayoutChange$?` | `QRL<(change: { viewId: string; widgets: DashboardWidgetSpec[]; }) => void>` |  |  |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

**Events**

- `onReady$`
- `onLayoutChange$`

### `GrafloriaDiagram`

```ts
const GrafloriaDiagram: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — erDiagram(...), umlDiagram(...), dashboard(...), or DSL text. |
| `options?` | `RenderOptions` |  |  |
| `onReady$?` | `QRL<(instance: DiagramInstance) => void>` |  | Fires once the kit has rendered, with the live instance. |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

**Events**

- `onReady$` — Fires once the kit has rendered, with the live instance.

### `GrafloriaFlow`

```ts
const GrafloriaFlow: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  |  |
| `edges?` | `EdgeSpec[]` |  |  |
| `groups?` | `(GroupModel \| GroupSpec)[]` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live |
| `defaultNodes?` | `NodeSpec[]` |  |  |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `(GroupModel \| GroupSpec)[]` |  |  |
| `onInit$?` | `QRL<(instance: DiagramInstance) => void>` |  |  |
| `onNodesChange$?` | `QRL<(nodes: NodeSpec[]) => void>` |  |  |
| `onEdgesChange$?` | `QRL<(edges: EdgeSpec[]) => void>` |  |  |
| `onSelectionChange$?` | `QRL<(change: SelectionChange) => void>` |  |  |
| `onConnect$?` | `QRL<(change: { link: LinkModel; }) => void>` |  |  |
| `onNodeClick$?` | `QRL<(change: { node: NodeModel; world: { x: number; y: number; }; }) => void>` |  |  |
| `onEdgeClick$?` | `QRL<(change: { edge: LinkModel; world: { x: number; y: number; }; }) => void>` |  |  |
| `onLayoutDone$?` | `QRL<(result: unknown) => void>` |  |  |
| `onCollabReady$?` | `QRL<(session: SyncAdapter) => void>` |  |  |
| `nodeTypes?` | `NodeTypes` |  | Custom node components, keyed by node `type`. |
| `theme?` | `Theme` |  |  |
| `fitView?` | `boolean` |  |  |
| `enablePan?` | `boolean` |  |  |
| `enableZoom?` | `boolean` |  |  |
| `zoomSensitivity?` | `number` |  |  |
| `dragThreshold?` | `number` |  |  |
| `readonly?` | `boolean` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `ssr?` | `{ html: string; snapshot: HydrationSnapshot; }` |  | The `renderToStaticSVG()` result. Renders server-side; the visible task |
| `layout?` | `string \| GrafloriaLayoutRequest` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background |
| `collab?` | `NoSerialize<GrafloriaCollabOptions>` |  | Real-time collaboration: a transport + actor id. The flow joins a CRDT |
| `comments?` | `any` |  | Anchored comment threads — `true` creates a store, or pass a shared |
| `commentsViewer?` | `string` |  | Viewer id for a `comments: true`-created store. |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer: outlines around the hovered node, the selected node, |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

**Events**

- `onInit$`
- `onNodesChange$`
- `onEdgesChange$`
- `onSelectionChange$`
- `onConnect$`
- `onNodeClick$`
- `onEdgeClick$`
- `onLayoutDone$`
- `onCollabReady$`

### `GrafloriaProvider`

Makes the nearest `<GrafloriaFlow>`'s instance reachable by SIBLINGS —
toolbars, inspectors, minimaps — through the hooks below.

```ts
const GrafloriaProvider: any
```

### `useOnSelectionChange$`

```ts
const useOnSelectionChange$: any
```

## Interfaces

### `GrafloriaCollabOptions`

The uniform collab contract every Grafloria wrapper shares.

```ts
interface GrafloriaCollabOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `transport` | `SyncTransport` |  | The transport (BroadcastChannelTransport, WebSocketTransport, …). |
| `actor` | `string` |  |  |
| `presence?` | `boolean \| BindPresenceOptions` |  | Live cursors + remote selection outlines. `true` for defaults. |

### `GrafloriaCommentPanelProps`

```ts
interface GrafloriaCommentPanelProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `NoSerialize<CommentStore>` |  | The live comment store. Must be `noSerialize()`d. |
| `options?` | `CommentPanelOptions` |  |  |
| `onSelect$?` | `QRL<(threadId: string \| null) => void>` |  |  |
| `class?` | `string` |  |  |

### `GrafloriaDashboardProps`

```ts
interface GrafloriaDashboardProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  |  |
| `widgets?` | `DashboardWidgetSpec[]` |  |  |
| `options?` | `Partial<DashboardOptions>` |  |  |
| `activeView?` | `string` |  | The visible view. |
| `layout?` | `'grid' \| 'split'` |  | LIVE SWITCHES — the toolbar toggles as props: applied at mount (over `options`) and, when they change, through the handle (`setLayout` / `setSizing` / `setStatic`), never by remounting. 'split' is the splitter tree; 'grid' the cell grid. |
| `sizing?` | `'fit' \| 'grow'` |  |  |
| `static?` | `boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |
| `widgetTypes?` | `WidgetTypes` |  | Qwik components for widget kinds, keyed by `kind`. |
| `onReady$?` | `QRL<(handle: DashboardHandle) => void>` |  |  |
| `onLayoutChange$?` | `QRL< (change: { viewId: string; widgets: DashboardWidgetSpec[] }) => void >` |  |  |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

### `GrafloriaDiagramProps`

```ts
interface GrafloriaDiagramProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — erDiagram(...), umlDiagram(...), dashboard(...), or DSL text. |
| `options?` | `RenderOptions` |  |  |
| `onReady$?` | `QRL<(instance: DiagramInstance) => void>` |  | Fires once the kit has rendered, with the live instance. |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

### `GrafloriaFlowProps`

```ts
interface GrafloriaFlowProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  |  |
| `edges?` | `EdgeSpec[]` |  |  |
| `groups?` | `Array<GroupSpec \| GroupModel>` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live GroupModels of a loaded document). Reconciled like `nodes`. |
| `defaultNodes?` | `NodeSpec[]` |  |  |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `Array<GroupSpec \| GroupModel>` |  |  |
| `onInit$?` | `QRL<(instance: DiagramInstance) => void>` |  |  |
| `onNodesChange$?` | `QRL<(nodes: NodeSpec[]) => void>` |  |  |
| `onEdgesChange$?` | `QRL<(edges: EdgeSpec[]) => void>` |  |  |
| `onSelectionChange$?` | `QRL<(change: SelectionChange) => void>` |  |  |
| `onConnect$?` | `QRL<(change: { link: LinkModel }) => void>` |  |  |
| `onNodeClick$?` | `QRL<(change: { node: NodeModel; world: { x: number; y: number } }) => void>` |  |  |
| `onEdgeClick$?` | `QRL<(change: { edge: LinkModel; world: { x: number; y: number } }) => void>` |  |  |
| `onLayoutDone$?` | `QRL<(result: unknown) => void>` |  |  |
| `onCollabReady$?` | `QRL<(session: SyncAdapter) => void>` |  |  |
| `nodeTypes?` | `NodeTypes` |  | Custom node components, keyed by node `type`. |
| `theme?` | `Theme` |  |  |
| `fitView?` | `boolean` |  |  |
| `enablePan?` | `boolean` |  |  |
| `enableZoom?` | `boolean` |  |  |
| `zoomSensitivity?` | `number` |  |  |
| `dragThreshold?` | `number` |  |  |
| `readonly?` | `boolean` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `ssr?` | `{ html: string; snapshot: HydrationSnapshot }` |  | The `renderToStaticSVG()` result. Renders server-side; the visible task adopts the markup instead of rebuilding it, so there is no flash and no re-layout. Put `ssr.css` in your document head. |
| `layout?` | `string \| GrafloriaLayoutRequest` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', 'force', 'tree', 'grid', 'auto', …) or `{ name, options }`. Re-runs when the prop VALUE changes, never when node data changes. |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background grid with defaults; an object picks and configures them. |
| `collab?` | `NoSerialize<GrafloriaCollabOptions>` |  | Real-time collaboration: a transport + actor id. The flow joins a CRDT sync session on mount and leaves on unmount. Fixed for the life of the instance. `collab.transport` must be `noSerialize()`d. |
| `comments?` | `boolean \| NoSerialize<CommentStore>` |  | Anchored comment threads — `true` creates a store, or pass a shared `CommentStore` (which must be `noSerialize()`d). |
| `commentsViewer?` | `string` |  | Viewer id for a `comments: true`-created store. |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer: outlines around the hovered node, the selected node, nodes with a validation issue, and valid connection targets. `true` turns every kind on; an object turns kinds on or off one by one. Off when unset. Follows the prop by VALUE. |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or options (depth, stroke, outgoing, dimOpacity). Off when unset. Follows the prop by VALUE. |
| `class?` | `string` |  |  |
| `style?` | `Record<string, string \| number>` |  |  |

### `GrafloriaLayoutRequest`

```ts
interface GrafloriaLayoutRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `options?` | `Record<string, unknown>` |  |  |

### `NodeProps`

Props a custom node component receives.

```ts
interface NodeProps<TData = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `data` | `TData` |  |  |
| `selected` | `boolean` |  |  |
| `node` | `NodeModel` |  | The live engine model — the escape hatch. |

### `SelectionChange`

```ts
interface SelectionChange
```

**Properties**

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

### `WidgetProps`

Props a custom widget component receives.

```ts
interface WidgetProps<TData = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `widget` | `DashboardWidgetSpec` |  |  |
| `data` | `TData` |  |  |

## Types

### `GrafloriaStore`

The live instance, or `undefined` until a `<GrafloriaFlow>` mounts. Always
`noSerialize`d — see the note at the top of this file.

```ts
type GrafloriaStore = Signal<NoSerialize<DiagramInstance> | undefined>;
```

### `NodeTypes`

`nodeTypes` maps a node's `type` to the Qwik component that renders it.

Declaring a type here IS the opt-in: specs whose `type` has an entry are
flagged `custom` automatically, the same rule the Vue and Angular wrappers
use. An explicit `custom` on the spec always wins.

```ts
type NodeTypes = Record<string, Component<NodeProps<never>>>;
```

### `WidgetTypes`

```ts
type WidgetTypes = Record<string, Component<WidgetProps<never>>>;
```

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `GroupSpec`, `HighlightConnectedOptions`, `HydrationSnapshot`, `LIGHT_THEME`, `NodeSpec`, `renderToStaticSVG`, `StaticRenderOptions`, `StaticRenderResult`, `Theme`

<!-- source: grafloria-vue.md -->

# @grafloria/vue

Vue 3 bindings for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, native in Vue.

## Install

```bash
npm install @grafloria/vue @grafloria/engine @grafloria/renderer vue @grafloria/element
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.0
- `@grafloria/renderer` ^0.4.16
- `vue` ^3.4.0
- `@grafloria/element` ^0.4.3

## Functions

### `useGrafloria`

The live `DiagramInstance` ref, `null` until a `<GrafloriaFlow>` mounts.

```ts
function useGrafloria(): ShallowRef<DiagramInstance | null>
```

### `useOnSelectionChange`

Fire a callback on every selection change; teardown is automatic.

```ts
function useOnSelectionChange(handler: (change: SelectionChange) => void): void
```

### `useSelection`

The current selection as reactive state (for an inspector panel).

```ts
function useSelection(): Ref<SelectionChange>
```

### `useViewport`

The live camera (zoom + world rect) as reactive state.

```ts
function useViewport(): Ref<{ zoom: number; x: number; y: number }>
```

## Constants

### `GRAFLORIA_STORE`

```ts
const GRAFLORIA_STORE: InjectionKey<ShallowRef<DiagramInstance | null>>
```

### `GrafloriaCommentPanel`

```ts
const GrafloriaCommentPanel: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `CommentStore` |  |  |
| `options?` | `CommentPanelOptions>, default: () =` |  |  |

**Events**

- `select`

### `GrafloriaDashboard`

```ts
const GrafloriaDashboard: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[]` |  |  |
| `widgets?` | `DashboardWidgetSpec[]` |  |  |
| `options?` | `Partial<DashboardOptions>>, default: () =` |  |  |
| `activeView?` | `String` |  | The visible view — `v-model:active-view`. |
| `layout?` | `'grid' \| 'split'` |  | LIVE SWITCHES — the toolbar toggles as props: applied at mount (over |
| `sizing?` | `'fit' \| 'grow'` |  |  |
| `static?` | `Boolean` |  | Static board: the viewer's mode — no drag, no resize, no handles. |

**Events**

- `update:activeView`
- `ready`
- `layoutChange`

### `GrafloriaDiagram`

```ts
const GrafloriaDiagram: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — erDiagram(...), umlDiagram(...), dashboard(...), or DSL text. |
| `options?` | `RenderOptions>, default: () =` |  |  |

**Events**

- `ready`

### `GrafloriaFlow`

```ts
const GrafloriaFlow: any
```

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  | Controlled nodes — `v-model:nodes`. |
| `edges?` | `EdgeSpec[]` |  | Controlled edges — `v-model:edges`. |
| `groups?` | `Array<GroupSpec \| GroupModel>` |  | Controlled groups — zones around some nodes (a spec's `groups`, or the live |
| `defaultNodes?` | `NodeSpec[]` |  | Uncontrolled initial data. |
| `defaultEdges?` | `EdgeSpec[]` |  |  |
| `defaultGroups?` | `Array<GroupSpec \| GroupModel>` |  |  |
| `theme?` | `Theme` |  |  |
| `layout?` | `string \| GrafloriaLayoutRequest` |  | Declarative auto-layout — any engine registry name ('elk', 'dagre', |
| `plugins?` | `boolean \| CanvasPluginOptions` |  | Canvas plugins — `true` mounts minimap + zoom/fit controls + background |
| `collab?` | `GrafloriaCollabOptions` |  | Real-time collaboration: a transport + actor id — the flow joins a CRDT |
| `comments?` | `boolean \| object` |  | Anchored comment threads — `true` creates a store; or pass a shared one. |
| `commentsViewer?` | `String` |  |  |
| `fitView?` | `Boolean` |  |  |
| `enablePan?` | `Boolean` |  |  |
| `enableZoom?` | `Boolean` |  |  |
| `readonly?` | `Boolean` |  |  |
| `minZoom?` | `Number` |  |  |
| `maxZoom?` | `Number` |  |  |
| `zoomSensitivity?` | `Number` |  |  |
| `rendererConfig?` | `Record<string, unknown>` |  | Renderer config passthrough (parallelLinks, parallelSpacing, jump styles, …). |
| `interaction?` | `Record<string, unknown>` |  | Interaction config passthrough (portVisibility, enableHelperLines, …). |
| `tokenBridge?` | `unknown` |  | Design-token bridge — adopt the app's shadcn / MUI / Tailwind CSS variables. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The outline layer Angular's canvas draws: outlines around the hovered node, |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Bring the selected nodes' lines forward and fade the rest: `true`, or |

**Events**

- `update:nodes`
- `update:edges`
- `init`
- `selectionChange`
- `connect`
- `nodeClick`
- `edgeClick`
- `layoutDone`
- `collabReady`

### `GrafloriaProvider`

Makes the nearest `<GrafloriaFlow>`'s instance reachable by SIBLINGS —
toolbars, inspectors, minimaps — through the composables below.

```ts
const GrafloriaProvider: any
```

## Interfaces

### `GrafloriaCollabOptions`

The uniform collab contract every Grafloria wrapper shares.

```ts
interface GrafloriaCollabOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `transport` | `SyncTransport` |  |  |
| `actor` | `string` |  |  |
| `presence?` | `boolean \| BindPresenceOptions` |  | Live cursors + remote selection outlines. `true` for defaults. |

### `GrafloriaLayoutRequest`

```ts
interface GrafloriaLayoutRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `options?` | `Record<string, unknown>` |  |  |

### `NodeSlotProps`

Context handed to `#node-<type>` slots.

```ts
interface NodeSlotProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node` | `NodeModel` |  |  |
| `data` | `Record<string, unknown>` |  |  |
| `engine` | `DiagramEngine` |  |  |

### `SelectionChange`

```ts
interface SelectionChange
```

**Properties**

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

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `LIGHT_THEME`, `NodeSpec`, `Theme`

<!-- source: grafloria-canvas-ng.md -->

# @grafloria/canvas-ng

Angular canvas integration for the Grafloria diagram engine

## Install

```bash
npm install @grafloria/canvas-ng @angular/common @angular/core
```

It expects these alongside it:

- `@angular/common` ^18.1.0
- `@angular/core` ^18.1.0

## Classes

### `CanvasNgCanvasNgComponent`

```ts
@Component({
    selector: 'lib-canvas-ng-canvas-ng',
    imports: [CommonModule],
    templateUrl: './canvas-ng-canvas-ng.component.html',
    styleUrl: './canvas-ng-canvas-ng.component.scss',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CanvasNgCanvasNgComponent
```

Use it as `<lib-canvas-ng-canvas-ng>` in a template.

<!-- source: grafloria-dashboard.md -->

# @grafloria/dashboard

Grafloria Dashboards is an MIT JavaScript dashboard layout library: draggable, resizable widgets on a grid or a splitter layout, with undo, nesting and persistence built in, for Angular, React, Vue or plain JavaScript.

## Install

```bash
npm install @grafloria/dashboard @grafloria/element @grafloria/engine @grafloria/renderer
```

It expects these alongside it:

- `@grafloria/element` ^0.4.9
- `@grafloria/engine` ^0.3.0
- `@grafloria/renderer` ^0.4.0

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/element](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-overview): `bindDashboardGrid`, `BUILT_IN_WIDGET_KINDS`, `dashboard`, `DashboardGridHandle`, `DashboardGridOptions`, `DashboardHandle`, `DashboardOptions`, `DashboardSnapshot`, `DashboardSpec`, `DashboardViewSpec`, `DashboardWidgetSpec`, `defaultWidgetRenderer` and 7 more

<!-- source: grafloria-renderer-overview.md -->

# @grafloria/renderer

SVG renderer for the Grafloria diagram engine — interaction, theming, accessibility, and SVG/PNG/PDF vector export

## Install

```bash
npm install @grafloria/renderer @grafloria/engine
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.18

## What it exports

- [Core](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-core): 17 exports, including `cancelFrame`, `CanvasRect`, `getDocument`, `hasDocument`
- [A11y](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y): 51 exports, including `Adjacency`, `analyseTopology`, `boundsOfPoints`, `buildAdjacency`
- [Canvas](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas): 79 exports, including `ALWAYS_SAFE_MODE`, `applyMatrix`, `arcToCubics`, `BackendMode`
- [Comments](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-comments): 9 exports, including `CommentOverlayController`, `CommentOverlayOptions`, `CommentPanelOptions`, `CommentPanelView`
- [Export](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export): 106 exports, including `Artifact`, `AssetFetcher`, `AVG_CHAR_WIDTH_EM`, `base64ToBytes`
- [Ext](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext): 115 exports, including `activeRegistryScope`, `AnchorContext`, `AnchorFn`, `AnchorResult`
- [Ext — Components](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-components): 15 exports, including `attachCanvasPlugins`, `BACKGROUND_LAYER_CLASS`, `BackgroundHandle`, `BackgroundOptions`
- [Instance](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance): 49 exports, including `applyEdges`, `applyEdgeSpec`, `applyGroups`, `applyNodes`
- [Interaction](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction): 85 exports, including `AddWaypointResult`, `AlignmentGuide`, `angleAt`, `Announcement`
- [Lazy](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-lazy): 13 exports, including `DeferredQuery`, `EntityKind`, `FreezeQuery`, `HostCullMode`
- [Perf](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-perf): 8 exports, including `EMPTY_SNAPSHOT`, `formatSnapshot`, `GovernorOptions`, `GovernorState`
- [Presence](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-presence): 12 exports, including `actorColor`, `actorInitials`, `bindPresence`, `BindPresenceOptions`
- [Presentation](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-presentation): 11 exports, including `FollowOptions`, `followPresenter`, `InMemoryViewportChannel`, `isDocumentLocked`
- [Services](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-services): 25 exports, including `AnimationConfig`, `AnimationEventData`, `AnimationLifecycleEvent`, `AnimationLifecycleManager`
- [Svg](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg): 198 exports, including `applySpread`, `ArrowRenderer`, `assignSpreadLanes`, `autoSizeDiagram`
- [Themes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes): 83 exports, including `assertThemeContrast`, `auditThemeContrast`, `BASE_STYLE_RULES`, `BRIDGEABLE_TOKENS`
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types): 50 exports, including `BooleanPropertyDefinition`, `BoundingBox`, `CanvasRendererConfig`, `ColorPalette`
- [Utils](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-utils): 37 exports, including `AnimationColorSchemes`, `AnimationDescriptor`, `AnimationPresets`, `AnimationPriority`
- [Vnode](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-vnode): 17 exports, including `camelToKebab`, `ContainerIdGenerator`, `createDomElement`, `createForeignObject`

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/engine](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-overview): `NodeModel`, `PortLayoutArgs`, `PortLayoutSpec`, `PortModel`

<!-- source: grafloria-renderer-core.md -->

# Core

Import these from `@grafloria/renderer`.

## Functions

### `cancelFrame`

Cancel a handle from {@link requestFrame}, whichever mechanism produced it.

```ts
function cancelFrame(handle: number): void
```

### `getDocument`

The ambient `Document`, or `undefined` on the server. Never throws.

```ts
function getDocument(): Document | undefined
```

### `hasDocument`

True when a real DOM `document` is reachable (browser, jsdom, happy-dom).

```ts
function hasDocument(): boolean
```

### `isBrowser`

True in a browser-like environment: a `window` AND a `document`.

```ts
function isBrowser(): boolean
```

### `now`

Monotonic-ish clock that also works where `performance` is absent.

```ts
function now(): number
```

### `renderToStaticSVG`

```ts
function renderToStaticSVG(options: StaticRenderOptions = {}): StaticRenderResult
```

### `requestFrame`

`requestAnimationFrame`, or a `setTimeout(…, 16)` shim where it is missing
(Node, older jsdom). Returns an opaque handle usable with {@link cancelFrame}.

```ts
function requestFrame(callback: (time: number) => void): number
```

## Classes

### `ViewportController`

ViewportController — the framework-agnostic camera.

This is the piece every framework wrapper otherwise re-implements (and gets
subtly wrong): screen↔world conversion, zoom clamping, pan accumulation, and
the `viewBox` convention that the SVG renderer and the hit-tester MUST agree
on. Owning it here means a React/Vue/web-component host inherits pixel-exact
hit-testing for free.

Like {@link InteractionController } it answers **"what is the camera now?"** and
never **"who should re-render?"** — hosts subscribe via {@link onChange} and
translate that into their own render trigger (`markForCheck`, `setState`, …). It has zero framework imports, zero engine imports, and no DOM dependency:
callers hand it a plain {@link CanvasRect}, not an element.

## The coordinate contract

`viewport.x/y` are WORLD coordinates. `viewport.width/height` are the canvas's
**CSS-pixel** size — NOT a world-space span. The world span actually shown is
derived by dividing by `zoom`, which is exactly what {@link getViewBox} does:

```text
  center      = (viewport.x + w/2, viewport.y + h/2)      // zoom is centre-preserving
  viewBox.w/h = (w / zoom, h / zoom)                      // higher zoom ⇒ less world visible
  viewBox.x/y = center − viewBox.w/h / 2
```

This is the identical formula `SVGRenderer.render()` applies to the viewport
it is handed (`libs/renderer/src/svg/svg-renderer.ts`, "Apply zoom to viewBox"),
and the one {@link clientToWorld} inverts. Because both sides derive from the
same {@link getViewBox}, screen→world round-trips exactly at any zoom — see
the round-trip tests in `viewport-controller.spec.ts`.

⚠️ Feed {@link getRenderViewport} — not a pre-scaled rectangle — to
`IRenderer.render(viewport, zoom)`. Dividing width/height by `zoom` *before*
calling `render()` makes the renderer divide by `zoom` a second time, applying
zoom quadratically and desynchronising the picture from the hit-tester at any
zoom ≠ 1. (`DiagramCanvasComponent.calculateActualViewport()` currently does
exactly that; the fix belongs to the zoom card and is why this convention now
lives in one place.)

```ts
class ViewportController
```

**Methods**

- `constructor(options: ViewportControllerOptions = {})`
- `getViewport(): Rectangle`
- `getZoom(): number`
- `getState(): ViewportState`
- `setViewport(viewport: Rectangle): void` — Replace the camera rectangle wholesale.
- `setCanvasSize(width: number, height: number): void` — Track the canvas element's pixel size. Call on mount and on resize: the
width/height of the camera rect must stay equal to the canvas's CSS-pixel
size for {@link clientToWorld} to be the true inverse of the rendered
`viewBox` (see the coordinate contract).
- `syncCanvasSize(rect: CanvasRect): void` — Convenience form of {@link setCanvasSize} taking a `getBoundingClientRect()`.
- `clampZoom(zoom: number): number` — Clamp to `[minZoom, maxZoom]`. Non-finite input falls back to the current zoom.
- `setZoom(zoom: number): number` — Set zoom (centre-preserving), clamped. Returns the zoom actually applied.
- `zoomBy(delta: number): number` — Additive zoom step, clamped — the convention the Angular canvas's wheel
handler uses (`zoom + delta`, not `zoom * factor`). Returns the applied zoom.
- `zoomByWheel(deltaY: number): number` — Apply one wheel notch. Mirrors `DiagramCanvasComponent.onWheel`: scrolling
DOWN (`deltaY > 0`) zooms OUT by `zoomSensitivity`, scrolling up zooms in.
- `zoomAtPoint(zoom: number, clientX: number, clientY: number, rect: CanvasRect): number` — Cursor-anchored zoom: change zoom while keeping the world point currently
under `(clientX, clientY)` pinned to that same screen pixel. This is the
standard "zoom towards the pointer" behaviour; the plain {@link setZoom} /
{@link zoomByWheel} pair is centre-anchored instead.

Returns the zoom actually applied (clamped).
- `pan(dx: number, dy: number): void` — Translate the camera by a WORLD-space delta.
- `panByScreenDelta(dxPx: number, dyPx: number): void` — Translate the camera by a SCREEN-space (pixel) drag delta, converting to
world units by dividing by zoom.

Sign convention matches the canvas's middle-drag handler: pass
`(lastClientX - clientX, lastClientY - clientY)`, i.e. dragging the pointer
RIGHT moves the camera LEFT, so the content appears to follow the cursor.
- `getViewBox(): Rectangle` — The world-space rectangle actually visible — centre-preserving zoom applied
to the camera rect. Identical to the `viewBox` `SVGRenderer` emits, and the
basis of {@link clientToWorld}.
- `getViewBoxString(): string` — The `viewBox` attribute string: `"x y width height"`.
- `getRenderViewport(): Rectangle` — The rectangle to hand to `IRenderer.render(viewport, zoom)` alongside
{@link getZoom}. The renderer applies the zoom itself, so this is the raw
camera rect — do NOT pre-divide it by zoom (see the class docs).
- `getHtmlLayerTransform(): string` — CSS transform that keeps an HTML overlay layer registered with the SVG
layer in the hybrid renderer: `translate(...) scale(zoom)`.

MUST be driven off the same {@link getViewBox} the SVG viewBox and
{@link worldToClient} use — NOT the raw `viewport.x/y`. Since the camera
rect's width/height became CANVAS PIXELS (see setCanvasSize), the visible
world box is the pixel rect expanded around its centre by 1/zoom; the SVG
renderer applies exactly that expansion (svg-renderer.ts `viewBoxX =
centerX - width/zoom/2`). Using the raw `viewport.x` here omitted the
`width*(1-zoom)/2` centring term, so the HTML custom-node layer drifted
from the SVG at any zoom != 1 — invisible until a custom-node dashboard was
framed with fitToBounds. Routing through getViewBox() makes a host at world
W land at the identical pixel worldToClient(W) reports. Identical at zoom 1.
- `clientToWorld(clientX: number, clientY: number, rect: CanvasRect): ViewportPoint` — Convert a client/screen point (e.g. `event.clientX/Y`) into world space. Exact inverse of {@link worldToClient} at any zoom.
- `worldToClient(worldX: number, worldY: number, rect: CanvasRect): ViewportPoint` — Convert a world point into client/screen coordinates — for positioning
overlays, toolbars and tooltips over the canvas. Exact inverse of
{@link clientToWorld}.
- `fitToBounds(bounds: Rectangle, padding = 40, options?: { maxZoom?: number }): number` — Frame `bounds` (a world-space content rectangle): pick the largest clamped
zoom at which it fits inside the canvas with `padding` CSS pixels of margin
on every side, and centre it. A zero-area canvas or bounds is a no-op.

Returns the zoom actually applied.
- `onChange(listener: ViewportChangeListener): Unsubscribe` — Subscribe to camera changes. Returns an unsubscribe function.
- `dispose(): void` — Drop all subscribers.

## Interfaces

### `CanvasRect`

The subset of `DOMRect` the camera actually needs. Any `getBoundingClientRect()`
result satisfies it; tests can pass a plain object. Keeping it structural is
what lets this class run in Node with no DOM.

```ts
interface CanvasRect
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `left` | `number` |  |  |
| `top` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `HydrationSnapshot`

Everything the client needs to reproduce this render exactly.

```ts
interface HydrationSnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `instanceId` | `string` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `zoom` | `number` |  |  |
| `viewport` | `{ x: number; y: number }` |  |  |

### `StaticRenderOptions`

The deterministic SERVER path.

`renderToStaticSVG()` runs the real `DiagramEngine` + the real `SVGRenderer`
in Node, with no DOM anywhere, and returns:

- `html`     — the exact markup `createDiagram()` would have mounted,
  - `svg`      — just the `<svg>` (for an `<img>`, an email, a README),
  - `snapshot` — the four values the client must reuse to reproduce the same
                 VNode tree byte-for-byte: instance scope, canvas size, camera
                 origin and zoom.

Hand the snapshot back to `createDiagram(el, { hydrate: snapshot })` and the
client rebuilds the same model, renders the same VNodes, and ADOPTS the DOM
that is already on the page — no re-creation, no flash, no re-layout. The
competitors either punt on SSR entirely (React Flow is `'use client'`-only) or
server-render something that can never become interactive (Mermaid).

## What makes it deterministic

- ids: `node-<i>` / `edge-<i>` when the spec omits them (never a nanoid);
- ports: rewritten to `<nodeId>__<side>` (the engine's auto-ports are nanoids
  and the renderer emits them as VNode keys) — see `instance/model-input.ts`;
- instance scope: `instanceId` is fixed here and echoed in the snapshot,
  because the renderer's fallback counter restarts in every process;
- camera: the snapshot carries width/height/zoom/origin, so the client's
  `viewBox` is identical even before it has measured the container.

## Scope (stated plainly)

Custom / HTML-layer nodes are NOT server-rendered: they are framework
components, and the server has no framework. They mount on hydration, inside
the (empty, correctly-transformed) HTML layer this emits. Everything the SVG
renderer draws — nodes, ports, edges, labels, arrows, routing — IS in the
snapshot, which is the part that would otherwise re-layout.

```ts
interface StaticRenderOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  |  |
| `edges?` | `EdgeSpec[]` |  |  |
| `theme?` | `Theme` |  |  |
| `width?` | `number` |  | Canvas width in CSS px. Default 800. |
| `height?` | `number` |  | Canvas height in CSS px. Default 600. |
| `zoom?` | `number` |  |  |
| `viewport?` | `{ x: number; y: number }` |  | Camera origin in world coordinates. Default (0, 0). |
| `instanceId?` | `string` |  | CSS scope for this diagram. Default `'grafloria-ssr'`. Give each diagram on a page its own id if you server-render more than one. |
| `fitView?` | `boolean` |  | Frame the content instead of using `viewport`/`zoom`. Default false. |
| `fitPadding?` | `number` |  | Padding (CSS px) for `fitView`. Default 40. |
| `standalone?` | `boolean` |  | Add `xmlns` to the `<svg>` so it stands alone as a file. Default false. |

### `StaticRenderResult`

```ts
interface StaticRenderResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `html` | `string` |  | The full layer skeleton — drop this straight into your container. |
| `svg` | `string` |  | Only the `<svg>` element. |
| `css` | `string` |  | The stylesheet the diagram needs. In CSS mode the theme is expressed purely as `--grafloria-*` variables, so the SVG above is theme-INDEPENDENT (which is what makes hydration a no-op) — but it is also unstyled until this CSS is on the page. Ship it in a `<style>` tag; the client re-injects identical content under the same ids, so nothing repaints. |
| `snapshot` | `HydrationSnapshot` |  |  |

### `ViewportControllerOptions`

```ts
interface ViewportControllerOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport?` | `Rectangle` |  | Camera rectangle. `x`/`y` are WORLD coordinates; `width`/`height` are the canvas's CSS-PIXEL dimensions (see the coordinate contract below). |
| `zoom?` | `number` |  |  |
| `minZoom?` | `number` |  | Default 0.1 — matches `DiagramCanvasComponent.minZoom`. |
| `maxZoom?` | `number` |  | Default 3.0 — matches `DiagramCanvasComponent.maxZoom`. |
| `zoomSensitivity?` | `number` |  | Additive step applied per wheel notch. Default 0.1. |

### `ViewportPoint`

A point in world space. Declared structurally (rather than imported from
`@grafloria/engine`) so the viewport module stays dependency-free: camera math
needs no diagram model. Structurally identical to `Point` from `@grafloria/engine`,
so the two interoperate without conversion.

```ts
interface ViewportPoint
```

**Properties**

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

### `ViewportState`

Immutable snapshot of the camera.

```ts
interface ViewportState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `Rectangle` |  |  |
| `zoom` | `number` |  |  |

## Types

### `Unsubscribe`

Remove a previously registered listener.

```ts
type Unsubscribe = () => void;
```

### `ViewportChangeListener`

```ts
type ViewportChangeListener = (state: ViewportState) => void;
```

<!-- source: grafloria-renderer-a11y.md -->

# A11y

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y-classes): 3 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y-constants): 5 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y-functions): 30 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y-interfaces): 11 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-a11y-types): 2 types.

<!-- source: grafloria-renderer-a11y-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `DiagramOutlineView`

```ts
class DiagramOutlineView
```

**Methods**

- `constructor(container: HTMLElement, options: OutlineViewOptions = {})`
- `getElement(): HTMLElement` — The hidden region, for tests and hosts that want to relocate it.
- `getRebuildCount(): number` — How many times the DOM has actually been rebuilt. The thrash proof.
- `getOutline(): DiagramOutline | null` — The outline currently mirrored (null before the first update).
- `update(diagram: DiagramLike | undefined): boolean` — Sync the mirror to the model. Cheap and idempotent: returns false — having
touched no DOM — when the topology-relevant signature is unchanged.
- `dispose(): void`

### `FocusContainmentController`

```ts
class FocusContainmentController
```

**Methods**

- `constructor(viewport: ViewportController, options: FocusContainmentOptions = {})`
- `isFullyVisible(bounds: Rectangle, padding = this.padding): boolean` — Is `bounds` fully inside the padded visible box? The predicate the whole
card turns on — and the one a test can assert directly.
- `paddedViewBox(padding = this.padding): Rectangle` — The visible world box, deflated by `padding` CSS pixels on every side.
- `plan(bounds: Rectangle, padding = this.padding): ContainmentResult` — Compute what would have to happen to bring `bounds` fully into view —
WITHOUT touching the camera. Pure: this is what the tests assert, and what
`ensureVisible` then applies.
- `ensureVisible(bounds: Rectangle, padding = this.padding): ContainmentResult` — Bring `bounds` fully into view. Returns what it did — `'none'` when the
element was already visible, which is the common case and costs nothing.
- `isAnimating(): boolean` — True while a containment pan is animating.
- `stop(): void` — Cancel any in-flight pan.
- `dispose(): void`

### `LiveRegionController`

```ts
class LiveRegionController
```

**Methods**

- `constructor(container: HTMLElement, options: LiveRegionOptions = {})`
- `getElement(politeness: Politeness): HTMLElement` — The live elements, for tests and for hosts that relocate them.
- `getMessage(politeness: Politeness): string` — What the region currently says.
- `getSpeakCount(): number` — How many times we have actually written to the DOM. The thrash proof.
- `announce(message: string, politeness: Politeness = 'polite', force = false): boolean` — Announce. Returns true if the message will be spoken, false if it was
suppressed as a duplicate.
- `announceError(message: string): boolean` — Errors and validation failures. Always assertive, never coalesced.
- `flushPending(): void` — Speak any coalesced message immediately.
- `clear(): void` — Clear both regions (e.g. on blur) without announcing anything.
- `dispose(): void`

<!-- source: grafloria-renderer-a11y-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `DIAGRAM_ROLE`

Roles we emit. `graphics-*` come from the W3C Graphics ARIA module.

```ts
const DIAGRAM_ROLE: "graphics-document"
```

### `EDGE_ROLE`

```ts
const EDGE_ROLE: "graphics-symbol"
```

### `MOTION_PREFERENCE_CSS`

Reduced motion, high contrast, performance/battery modes, epilepsy safety,
and the screen-reader-only recipe.

Two routes to the same behaviour, deliberately:
  - `@media (prefers-reduced-motion: reduce)` — the OS preference;
  - `.reduced-motion` on `<body>` — the APP's own toggle, which is what
    `AnimationService` sets. Both must work; only the first used to.

```ts
const MOTION_PREFERENCE_CSS: "\n/* ==========================================================================\n   REDUCED MOTION — OS preference\n   ========================================================================== */\n@media (prefers-reduced-motion: reduce) {\n  .link-animated-marching-ants,\n  .link-animated-flow,\n  .link-animated-pulse {\n    animation: none !important;\n    stroke-dasharray: none !important;\n  }\n\n  .node-border-gradient,\n  .node-border-gradient::before,\n  .node-border-pulse,\n  .node-border-pulse-svg,\n  .node-border-breathe,\n  .node-border-shimmer,\n  …
```

### `MOTION_PREFERENCE_STYLE_ID`

Id of the injected `<style>` element. Idempotent by construction.

```ts
const MOTION_PREFERENCE_STYLE_ID: "grafloria-motion-preferences"
```

### `NODE_ROLE`

```ts
const NODE_ROLE: "graphics-symbol"
```

<!-- source: grafloria-renderer-a11y-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `analyseTopology`

```ts
function analyseTopology(diagram: DiagramLike): Topology
```

### `boundsOfPoints`

The world bounds of a routed link — its polyline, grown a little.

```ts
function boundsOfPoints(
  points: { x: number; y: number }[],
  pad = 8
): Rectangle | null
```

### `buildAdjacency`

```ts
function buildAdjacency(diagram: DiagramLike): Adjacency
```

### `buildOutline`

```ts
function buildOutline(diagram: DiagramLike): DiagramOutline
```

### `childrenByParent`

Group/parent containment: parentId → child nodes.

```ts
function childrenByParent(diagram: DiagramLike): Map<string, NodeModel[]>
```

### `degreeOf`

Incoming / outgoing degree of a node. Self-loops count on both sides.

```ts
function degreeOf(
  nodeId: string,
  diagram: DiagramLike
): { incoming: number; outgoing: number }
```

### `diagramAccessibleName`

The canvas's own accessible name: "Diagram, 12 nodes, 14 edges". Read when focus first enters the canvas, so the user knows the size of what
they have landed in before they start walking it.

```ts
function diagramAccessibleName(diagram: DiagramLike, title?: string): string
```

### `diagramOf`

Resolve the diagram off an engine, tolerating a bare DiagramModel.

```ts
function diagramOf(engine: DiagramEngine | DiagramLike | undefined): DiagramLike | undefined
```

### `diagramRoleDescription`

The `aria-roledescription` for the whole canvas.

```ts
function diagramRoleDescription(diagramType?: string): string
```

### `edgeAccessibleName`

An edge's ACCESSIBLE NAME.

"Edge from Start to Is order valid?, labelled yes, selected"

```ts
function edgeAccessibleName(link: LinkModel, diagram: DiagramLike): string
```

### `edgeRoleDescription`

The `aria-roledescription` for an edge. Respects the link's own semantics.

```ts
function edgeRoleDescription(link: LinkModel): string
```

### `ensureMotionPreferenceStyles`

Inject the motion-preference stylesheet once per document.

Idempotent and SSR-safe: no document → no-op, and a second call finds the
existing element by id and returns it.

```ts
function ensureMotionPreferenceStyles(doc?: Document): HTMLStyleElement | undefined
```

### `findComponents`

Connected components, treating edges as undirected.

```ts
function findComponents(diagram: DiagramLike, adjacency: Adjacency): string[][]
```

### `findCycles`

Every cycle reachable in the directed graph, found by DFS with a colour mark. Reported once each, normalised to start at its smallest node id so the same
cycle is never announced twice under two rotations.

```ts
function findCycles(diagram: DiagramLike, adjacency: Adjacency): string[][]
```

### `humaniseType`

Humanise an unknown type: `my_customNode` → "My custom node".

```ts
function humaniseType(type: string | undefined): string
```

### `incidentEdges`

The edges incident on a node, ordered for keyboard traversal: outgoing first
(the direction a reader follows a flow), then incoming, each in the reading
order of the node at the far end — so pressing the same key twice always
walks the same way.

```ts
function incidentEdges(
  nodeId: string,
  diagram: DiagramLike,
  adjacency?: Adjacency
): Incidence[]
```

### `linkLabelText`

A link's own label text, if it carries one.

```ts
function linkLabelText(link: LinkModel): string | undefined
```

### `nameOf`

Debug/summary helper: name a node id.

```ts
function nameOf(id: string, diagram: DiagramLike): string
```

### `nodeAccessibleName`

A node's ACCESSIBLE NAME — what the screen reader reads on focus.

"Decision, Is order valid?, 1 incoming, 2 outgoing, selected"

The degree counts are the position context an AT user cannot get any other
way: sighted users see the edges converging on a shape; a screen-reader user
is told.

```ts
function nodeAccessibleName(node: NodeModel, diagram?: DiagramLike): string
```

### `nodeName`

A node's human NAME: its label, else its type + a short id. Single source of truth — the renderer's `aria-label`, the keyboard
controller's announcements, and the outline text-mirror all call THIS, so a
node can never be called two different things by two different surfaces.

```ts
function nodeName(node: NodeModel): string
```

### `nodeRoleDescription`

The `aria-roledescription` for a node — its SHAPE, in human words.

```ts
function nodeRoleDescription(node: NodeModel): string
```

### `outlineNodeLabel`

"Decision, Is order valid?, node 3 of 12, 1 incoming, 2 outgoing, in a loop"

```ts
function outlineNodeLabel(node: OutlineNode): string
```

### `outlineSignature`

A cheap signature of everything the outline DEPENDS on: ids, names, states,
containment and endpoints. Geometry is deliberately NOT in it — dragging a
node changes the picture but not the topology, so it must not rebuild the
mirror.

This is what makes the "no thrash" guarantee real rather than aspirational:
the view rebuilds only when this string changes, so a quiet frame — and a
pure-movement frame — does ZERO outline work.

```ts
function outlineSignature(diagram: DiagramLike): string
```

### `positionContext`

Reading-order position context: "node 3 of 12, 2 incoming, 1 outgoing".

```ts
function positionContext(nodeId: string, diagram: DiagramLike): string
```

### `readingOrder`

Reading order: the order a sighted user's eye takes. Focus order matches it.

```ts
function readingOrder(nodes: NodeModel[]): NodeModel[]
```

### `removeMotionPreferenceStyles`

Remove the injected stylesheet (teardown / tests).

```ts
function removeMotionPreferenceStyles(doc?: Document): void
```

### `rootNodes`

Nodes with no parent — the roots of the containment tree.

```ts
function rootNodes(diagram: DiagramLike): NodeModel[]
```

### `sourceNodeIdOf`

```ts
function sourceNodeIdOf(link: LinkModel, diagram: DiagramLike): string
```

### `summarise`

The NATURAL-LANGUAGE SUMMARY. What a colleague would say if you asked them
"what does this diagram show?" over the phone.

"Flowchart with 8 nodes and 9 edges. It starts at Receive order. It ends at
 Ship order or Reject order. It contains 1 loop: Review → Amend → Review.
 1 node is disconnected: Legacy step."

```ts
function summarise(
  outline: Omit<DiagramOutline, 'summary' | 'signature'>,
  diagram: DiagramLike
): string
```

### `targetNodeIdOf`

```ts
function targetNodeIdOf(link: LinkModel, diagram: DiagramLike): string
```

<!-- source: grafloria-renderer-a11y-interfaces.md -->

# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `Adjacency`

```ts
interface Adjacency
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `outgoing` | `Map<string, Incidence[]>` |  | nodeId → edges leaving it. |
| `incoming` | `Map<string, Incidence[]>` |  | nodeId → edges arriving at it. |

### `ContainmentResult`

```ts
interface ContainmentResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `action` | `ContainmentAction` |  |  |
| `dx` | `number` |  | World-space delta applied (or to be applied, when animating). |
| `dy` | `number` |  |  |
| `zoom?` | `number` |  | Zoom applied, when `action === 'zoom'`. |

### `DiagramLike`

The minimum of DiagramModel these pure functions need.

```ts
interface DiagramLike
```

**Members**

- `getNode(id: string): NodeModel | undefined`
- `getNodes(): NodeModel[]`
- `getLink(id: string): LinkModel | undefined`
- `getLinks(): LinkModel[]`
- `getNodeByPortId?(portId: string): NodeModel | undefined`
- `getGroups?(): unknown[]`

### `DiagramOutline`

```ts
interface DiagramOutline
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `summary` | `string` |  | Natural-language summary, read when focus enters the diagram. |
| `roots` | `OutlineNode[]` |  | The containment forest, in reading order. |
| `flat` | `OutlineNode[]` |  | Flat reading-order view — what the roving tabindex walks. |
| `entryPoints` | `string[]` |  |  |
| `terminals` | `string[]` |  |  |
| `isolated` | `string[]` |  |  |
| `cycles` | `string[][]` |  |  |
| `nodeCount` | `number` |  |  |
| `edgeCount` | `number` |  |  |
| `componentCount` | `number` |  |  |
| `edges` | `{ linkId: string; text: string }[]` |  | Every edge, as an AT-readable sentence (the edge list of the mirror). |
| `signature` | `string` |  | Cheap change key — see `outlineSignature`. |

### `FocusContainmentOptions`

```ts
interface FocusContainmentOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `padding?` | `number` |  | CSS-pixel margin kept between the focused element and the viewport edge. |
| `durationMs?` | `number` |  | Pan animation duration, ms. 0 (or reduced motion) → instant. |
| `reducedMotion?` | `() => boolean` |  | Override reduced-motion detection (tests). |
| `now?` | `() => number` |  | Injected clock/frame source (tests). |
| `requestFrame?` | `(cb: (t: number) => void) => number` |  |  |
| `cancelFrame?` | `(handle: number) => void` |  |  |

### `Incidence`

Graph TOPOLOGY — the structural facts an assistive-technology user cannot
see: which nodes start the flow, which end it, what cycles back, what is
unreachable.

This is the analysis engine behind two cards:
  - follow-edge keyboard traversal — walking the real graph, not
    the geometry;
  - the navigable outline + natural-language summary.

Pure, framework-free, model-in / facts-out. No DOM, no rendering.

.

```ts
interface Incidence
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  | The link. |
| `otherId` | `string` |  | The node at the OTHER end of it. |
| `direction` | `'outgoing' \| 'incoming'` |  | Are we the source (outgoing) or the target (incoming)? |

### `LiveRegionOptions`

```ts
interface LiveRegionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `coalesceMs?` | `number` |  | Announcements arriving within this many ms of the previous one REPLACE it rather than following it. 0 disables coalescing (tests use this). |
| `now?` | `() => number` |  | Injected clock, so tests need no timers. |
| `schedule?` | `(fn: () => void, ms: number) => unknown` |  | Injected scheduler, so tests need no real setTimeout. |
| `cancel?` | `(handle: unknown) => void` |  |  |

### `OutlineEdgeRef`

The DIAGRAM OUTLINE — a screen-reader-navigable TEXT MIRROR of the graph.

This is the capability no competitor ships. Mermaid is read-only pictures;
React Flow / GoJS / JointJS give a screen reader, at best, a bag of labelled
shapes with no edges. None of them
give an AT user the *topology*: where a flow starts, what each node leads to,
what loops back, what is unreachable.

The outline is that topology, as a structured tree the AT virtual cursor can
browse with its normal list/tree keys — plus a natural-language summary read
on entry, so the user knows the shape of the thing before walking it.

Pure model → outline. Rendering it to DOM is `outline-view.ts`'s job; keeping
the two apart is what lets us unit-test the *content* with no DOM at all.

.

```ts
interface OutlineEdgeRef
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `linkId` | `string` |  |  |
| `targetId` | `string` |  |  |
| `targetName` | `string` |  |  |
| `label?` | `string` |  | The edge's own label ("yes" / "no" on a decision), if any. |
| `closesCycle` | `boolean` |  | True when this edge closes a cycle — the single most useful fact. |

### `OutlineNode`

```ts
interface OutlineNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `name` | `string` |  |  |
| `roleDescription` | `string` |  | Human shape name — "Decision", "Process". |
| `incoming` | `number` |  |  |
| `outgoing` | `number` |  |  |
| `targets` | `OutlineEdgeRef[]` |  | Where this node leads. |
| `children` | `OutlineNode[]` |  | Nested nodes (group / parent containment). |
| `isEntryPoint` | `boolean` |  |  |
| `isTerminal` | `boolean` |  |  |
| `isIsolated` | `boolean` |  |  |
| `inCycle` | `boolean` |  | Participates in at least one cycle. |
| `index` | `number` |  | 1-based position in reading order, and the total — "node 3 of 12". |
| `total` | `number` |  |  |

### `OutlineViewOptions`

The outline's DOM MIRROR: a visually-hidden, semantically-structured tree the
AT virtual cursor browses with its ordinary list/tree keys.

Structure (all off-screen, never focusable by Tab — the canvas owns the tab
stop; this is virtual-cursor territory):

<div role="region" aria-label="Diagram outline">
    <p>{natural-language summary}</p>
    <ul role="tree">
      <li role="treeitem" aria-level=1 aria-label="Decision, Is order valid?, …">
        <ul role="group"> …children… </ul>
      </li>
    </ul>
    <ul role="list" aria-label="Edges"> … </ul>
  </div>

THRASH CONTROL — the non-negotiable. `update()` is safe to call on every
frame: it recomputes only the outline SIGNATURE (ids/names/states/endpoints,
never geometry) and returns immediately when it is unchanged. A quiet frame,
and a pure-drag frame, do ZERO DOM work. `getRebuildCount()` exists so a test
can PROVE it rather than trust it.

.

```ts
interface OutlineViewOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` |  | Accessible name of the outline region. |
| `diagramType?` | `string` |  | Diagram type, used in the roledescription ("Flowchart diagram"). |
| `includeEdgeList?` | `boolean` |  | Include the per-edge list. Default true. |

### `Topology`

```ts
interface Topology
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `adjacency` | `Adjacency` |  |  |
| `entryPoints` | `NodeModel[]` |  | Nodes with no incoming edges — where a reader should start. |
| `terminals` | `NodeModel[]` |  | Nodes with no outgoing edges — where flows terminate. |
| `isolated` | `NodeModel[]` |  | Nodes with neither incoming nor outgoing edges. |
| `cycles` | `string[][]` |  | Each cycle as the ordered node ids around it. |
| `components` | `string[][]` |  | Connected components (undirected), as node-id lists. |
| `ordered` | `NodeModel[]` |  | Nodes in reading order (top-to-bottom, then left-to-right). |

<!-- source: grafloria-renderer-a11y-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `ContainmentAction`

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

FOCUS CONTAINMENT — focus must never rest on geometry the user cannot see.

This is a real WCAG failure (2.4.11 Focus Not Obscured / 2.4.7 Focus Visible)
and, before this wave, we failed it outright: keyboard focus walked the whole
graph while the camera sat still, so tabbing past the edge of the viewport
left the focus ring on a node that was scrolled off-screen — announced, but
invisible. A sighted keyboard user simply lost the cursor.

The fix, in order of escalation:

1. Already fully visible (with padding) → DO NOTHING. Not panning is the
     most important case: a stationary camera is what makes the diagram
     readable, and gratuitous re-centring on every focus step is nauseating.
  2. Off-screen but it FITS at the current zoom → pan the minimum distance
     that brings it inside the padded box. Minimum, not centring: the user
     keeps their mental map.
  3. Too big to fit at the current zoom → zoom OUT via `fitToBounds`, which
     is the existing camera maths. We do not fork it.

Motion honours `prefers-reduced-motion`: an animated pan becomes an instant
jump. All camera writes go through {@link ViewportController} — this class
owns policy, not geometry.

.

```ts
type ContainmentAction = 'none' | 'pan' | 'zoom';
```

### `Politeness`

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

The managed `aria-live` REGION — the canvas's voice.

Two live regions, not one: an AT will not reliably re-announce a node whose
politeness changed, and mixing an error into the polite queue means it waits
behind whatever selection chatter is already in flight. So:

- `polite`    — selection, movement, focus, connect/disconnect;
  - `assertive` — validation failures and errors, which interrupt.

DE-DUPLICATION is the whole design problem. A naive live region wired to a
render loop says "Process node, 2 connections" sixty times a second and is
worse than useless — the user turns it off. Three defences, all here:

1. IDENTICAL-MESSAGE SUPPRESSION. The same text in the same channel is
     dropped, unless `force` is set (a repeated action the user *did* repeat
     — nudging twice — is legitimately worth re-announcing).
  2. COALESCING. Announcements inside a short window replace, rather than
     queue behind, the previous one. Holding an arrow key produces the FINAL
     position, not fifty intermediate ones.
  3. MODEL-CHANGE DRIVEN. The controller is called on model change, never
     from the render loop. `getSpeakCount()` lets a test prove a quiet frame
     speaks zero times.

Framework-free: takes a container, owns two divs, no Angular anywhere.

.

```ts
type Politeness = 'polite' | 'assertive';
```

<!-- source: grafloria-renderer-canvas.md -->

# Canvas

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-classes): 3 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-constants): 5 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-functions): 42 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-interfaces): 20 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-types): 5 types.
- [`Canvas2DLike`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-canvas2dlike): The subset of `CanvasRenderingContext2D` the painter uses. A real 2D context
- [`CanvasRenderer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-canvasrenderer)
- [`DiagramRenderBackend`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-diagramrenderbackend): One diagram, two backends, one VNode tree.
- [`RecordingContext2D`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-canvas-recordingcontext2d): A `Canvas2DLike` that records what was drawn instead of rasterising it.

<!-- source: grafloria-renderer-canvas-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `CanvasStyleResolver`

Resolves VNode props → concrete paint values, reproducing the SVG cascade. The CLASS-RULE layer is the export card's flattener; this adds priority order,
inheritance and typed parsing on top.

```ts
class CanvasStyleResolver
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `warnings` | `string[]` | `[]` | Declarations dropped because a variable could not be resolved. |

**Methods**

- `constructor(options: StyleResolverOptions)`
- `setTheme(theme: Theme, varOverrides?: Record<string, string>): void`
- `getTheme(): Theme`
- `rootStyle(): ComputedStyle` — The root style every diagram starts from (theme font, no paint inherited).
- `resolve(props: VNodeProps | undefined, inherited: ComputedStyle): ComputedStyle` — Compute an element's style: inherit from the parent, then apply
presentation attributes < matched class rules < inline style.

### `DirtyRegionTracker`

```ts
class DirtyRegionTracker
```

**Methods**

- `invalidateAll(): void` — Next frame repaints everything (camera moved, theme swapped, resized …).
- `reset(): void` — Forget everything (a new diagram, or a disposed renderer).
- `diff(current: Map<string, VNode>, measure: (vnode: VNode) => Bounds | null): DirtyDiff` — Diff this frame's entities against the last one.
- `getBounds(key: string): Bounds | null | undefined` — Bounds recorded for an entity on the last frame (testing / diagnostics).
- `get size(): number`

### `VNodePainter`

Paints VNode trees. Stateless between frames apart from the colour-key
allocator the caller injects.

```ts
class VNodePainter
```

**Methods**

- `constructor(private readonly resolver: CanvasStyleResolver)`
- `paint(ctx: Canvas2DLike, root: VNode, options: PaintOptions): PaintResult`
- `measure(vnode: VNode, worldToDevice: Matrix = IDENTITY): Bounds | null` — World bounds of a subtree, drawing nothing. Used by the dirty tracker to
measure the entities that actually changed (and only those).

<!-- source: grafloria-renderer-canvas-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `ALWAYS_SAFE_MODE`

Modes it is always safe to be in.

```ts
const ALWAYS_SAFE_MODE: BackendMode
```

### `CANVAS_LINK_HIT_TOLERANCE`

Link pick tolerance, in WORLD units.

Not a new number — it IS the floor `InteractionController` applies in SVG
mode, imported from the one place that owns it. Hit parity between the two
backends is therefore a property of the code, not a coincidence maintained by
two constants that happen to agree today. (The full grab distance is per
link — `linkBodyHitTolerance(strokeWidth)` — which both backends now use.)

```ts
const CANVAS_LINK_HIT_TOLERANCE: 5
```

### `IDENTITY`

```ts
const IDENTITY: Matrix
```

### `INHERITED_DEFAULTS`

Style values that INHERIT from a parent element in SVG.

```ts
const INHERITED_DEFAULTS: ComputedStyle
```

### `NULL_CONTEXT`

A `Canvas2DLike` that does nothing — the measure pass draws into it.

```ts
const NULL_CONTEXT: Canvas2DLike
```

<!-- source: grafloria-renderer-canvas-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `applyMatrix`

```ts
function applyMatrix(m: Matrix, p: Point): Point
```

### `arcToCubics`

SVG elliptical arc → cubic béziers (endpoint→centre parameterisation, SVG 1.1
appendix F.6). Used by `A` path commands — the actor shape's head, cylinder
caps, jump-point arcs.

```ts
function arcToCubics(
  x1: number,
  y1: number,
  rx: number,
  ry: number,
  rotationDeg: number,
  largeArc: boolean,
  sweep: boolean,
  x2: number,
  y2: number
): PathCmd[]
```

### `boundsIntersect`

```ts
function boundsIntersect(a: Bounds, b: Bounds): boolean
```

### `boundsUnion`

```ts
function boundsUnion(a: Bounds | null, b: Bounds | null): Bounds | null
```

### `canvasSafety`

What would canvas mode cost this diagram?

Note the asymmetry, and that it is the whole design: this question is only ever asked
about stepping TO canvas. Going back to SVG can lose nothing — it only ever restores
focusable, labelled, HTML-capable DOM — so it is never guarded, never refused, and
always allowed.

```ts
function canvasSafety(input: CanvasSafetyInput): CanvasSafety
```

### `circlePath`

```ts
function circlePath(cx: number, cy: number, r: number): PathCmd[]
```

### `classListOf`

The class tokens on an element (`className` prop, space separated).

```ts
function classListOf(props: VNodeProps | undefined): string[]
```

### `collectDefinitions`

Every `id`-bearing definition anywhere in the tree: paint servers and filters
from `<defs>`, and the per-node `<clipPath>`s the label engine emits INLINE
(as a sibling of the text it clips). A single recursive pre-pass, because
`<defs>` is appended LAST by the SVG renderer while the elements referencing
it are painted first.

```ts
function collectDefinitions(root: VNode): Map<string, VNode>
```

### `collectEntities`

The top-level entities of a rendered tree: every keyed child of the links and
nodes layers. These are the units of change — the granularity at which the SVG
renderer caches, and therefore the granularity at which identity means
"unchanged".

The connection-preview layer is deliberately NOT an entity: it exists only
mid-drag, changes every frame, and is handled by {@link previewIsActive}.

```ts
function collectEntities(root: VNode): Map<string, VNode>
```

### `colorKeyFromPixel`

`#rrggbb` from a picking-canvas pixel.

```ts
function colorKeyFromPixel(r: number, g: number, b: number, a: number): string | null
```

### `distanceToPath`

Shortest distance from `p` to the path's outline (open OR closed).

```ts
function distanceToPath(cmds: PathCmd[], p: Point): number
```

### `distanceToSegment`

```ts
function distanceToSegment(p: Point, a: Point, b: Point): number
```

### `ellipsePath`

Ellipse centred at (cx, cy) as four cubic segments.

```ts
function ellipsePath(cx: number, cy: number, rx: number, ry: number): PathCmd[]
```

### `entityOf`

`node-n1` / `link-l1` / `port-p3` → the entity that owns the subtree.

```ts
function entityOf(vnode: VNode): EntityScope | null
```

### `explainHazards`

A human-readable account of what a canvas switch would take away.

```ts
function explainHazards(hazards: readonly CanvasHazard[]): string
```

### `flattenPath`

Flatten a command list into polylines. `steps` controls curve subdivision —
16 segments per curve keeps the deviation well under a pixel for the curve
sizes a diagram draws, and hit-testing only ever needs "within tolerance".

```ts
function flattenPath(cmds: PathCmd[], steps = 16): SubPath[]
```

### `fontString`

Build the canvas `font` shorthand from a resolved style.

```ts
function fontString(style: ComputedStyle): string
```

### `geometryOf`

VNode primitive → path commands, in the element's own local coordinates.

```ts
function geometryOf(vnode: VNode): PathCmd[]
```

### `linePath`

```ts
function linePath(x1: number, y1: number, x2: number, y2: number): PathCmd[]
```

### `mergeRects`

Merge rects that overlap or nearly touch, so we don't clip 40 slivers.

```ts
function mergeRects(rects: Bounds[], slack = 8): Bounds[]
```

### `multiply`

`m1 · m2` — apply m2 FIRST, then m1 (the SVG/canvas nesting convention).

```ts
function multiply(m1: Matrix, m2: Matrix): Matrix
```

### `nextColorKey`

Colour keys for the offscreen picking canvas.

The index is spread across the 24-bit colour space with a stride so that
adjacent records get FAR-APART colours. That matters: a browser antialiases
even the picking pass, and a blended edge pixel between two adjacent keys must
not land on a third VALID key. With a large stride, a blend of two keys is
overwhelmingly likely to be a colour no record owns — which reads as "miss",
not as "wrong entity". Exact-match lookup does the rest.

```ts
function nextColorKey(index: number): string
```

### `padBounds`

```ts
function padBounds(b: Bounds, pad: number): Bounds
```

### `parseDashArray`

`"5,5"` / `"5 5"` / `[5,5]` → `[5, 5]`. `"none"` → `[]`.

```ts
function parseDashArray(value: unknown): number[] | undefined
```

### `parseInlineStyle`

Parse an inline `style` — the renderer emits BOTH forms: a CSS string
(`"fill: red; stroke-width: 2"`, from the shape registry and the link style
computation) and an object (`{ cursor: 'move' }`, from the interaction
overlays). Both are normalised to kebab-case CSS declarations here.

```ts
function parseInlineStyle(style: unknown): Record<string, string>
```

### `parsePath`

Parse an SVG path `d` string into {@link PathCmd}s.

Full command coverage (M m L l H h V v C c S s Q q T t A a Z z) including
implicit repeated coordinate sets ("M 0 0 10 10" ⇒ moveto + lineto) and the
smooth-curve reflection rules. Arcs are converted to cubics.

Written by hand rather than leaned on the DOM (`SVGPathElement`) so it works
headlessly — in Node, in a worker, in a test — which is exactly where the
canvas backend has to be provable.

```ts
function parsePath(d: string | undefined | null): PathCmd[]
```

### `parseTransform`

Parse an SVG `transform` attribute into a matrix.

Supports the forms the renderer actually emits — translate / rotate / scale /
matrix — composed left-to-right, exactly as SVG composes them. An
unrecognised function is skipped rather than throwing: a transform we cannot
read must not take the whole frame down.

```ts
function parseTransform(transform: string | undefined | null): Matrix
```

### `parseViewBox`

`"0 0 800 600"` → a rectangle.

```ts
function parseViewBox(raw: unknown): Rectangle | null
```

### `pathBounds`

Bounding box of the flattened path. `null` for an empty path.

```ts
function pathBounds(cmds: PathCmd[]): Bounds | null
```

### `pointInPath`

Non-zero-winding point-in-path — the same fill rule a 2D context uses by
default, so "is this point inside the filled shape?" answers identically to
"did the fill put a pixel here?".

```ts
function pointInPath(cmds: PathCmd[], p: Point): boolean
```

### `polyPath`

`points="1,2 3,4"` (or `1 2 3 4`) → a polyline / polygon command list.

```ts
function polyPath(points: string | undefined, close: boolean): PathCmd[]
```

### `previewIsActive`

True when the tree carries a live connection / reconnection preview. It has no
stable identity and moves with the pointer, so any frame containing one is
repainted whole — the honest, correct answer, and it only happens mid-drag.

```ts
function previewIsActive(root: VNode): boolean
```

### `readCssVarOverrides`

Read the `--grafloria-*` values ACTUALLY COMPUTED on a host element.

This is what makes canvas mode honour a host that overrides the theme through
CSS (`.dark-mode [data-grafloria-instance] { --grafloria-node-fill: #222 }`) — the
variable is resolved by the browser's own cascade and handed to the canvas
resolver as a concrete value. Returns `{}` in a headless environment.

```ts
function readCssVarOverrides(element: Element | null | undefined): Record<string, string>
```

### `rectPath`

Axis-aligned rectangle, with optional (possibly asymmetric) corner radii.

```ts
function rectPath(
  x: number,
  y: number,
  width: number,
  height: number,
  rx = 0,
  ry = rx
): PathCmd[]
```

### `rotation`

```ts
function rotation(degrees: number, cx = 0, cy = 0): Matrix
```

### `scaling`

```ts
function scaling(sx: number, sy: number = sx): Matrix
```

### `textAlignFor`

SVG `text-anchor` → canvas `textAlign`.

```ts
function textAlignFor(anchor: ComputedStyle['textAnchor']): CanvasTextAlign
```

### `textBaselineFor`

SVG `dominant-baseline` → canvas `textBaseline`.

The renderer only ever emits `middle` (centred labels), `hanging` (top-aligned
text blocks) and `baseline`; anything else falls back to the canvas default,
which is what an unset `dominant-baseline` means in SVG too.

```ts
function textBaselineFor(baseline: string | undefined): CanvasTextBaseline
```

### `textLines`

The lines a `<text>` element draws.

Two shapes, both emitted by the shared text-block engine:
  - single line  → `textContent` on the `<text>` itself,
  - multi line   → one `<tspan>` per line, each with `x` and a `dy` offset
    from the running baseline (the first `dy` carries the block's vertical
    alignment). Canvas has no tspan, so the dy chain is accumulated here.

```ts
function textLines(vnode: VNode, x: number, y: number): TextLine[]
```

### `toNumber`

`"2px"` / `2` / `"2"` → 2. Returns `undefined` for anything unparseable.

```ts
function toNumber(value: unknown): number | undefined
```

### `transformCmds`

```ts
function transformCmds(cmds: PathCmd[], m: Matrix): PathCmd[]
```

### `translation`

```ts
function translation(dx: number, dy: number): Matrix
```

<!-- source: grafloria-renderer-canvas-interfaces.md -->

# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `Bounds`

```ts
interface Bounds
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minX` | `number` |  |  |
| `minY` | `number` |  |  |
| `maxX` | `number` |  |  |
| `maxY` | `number` |  |  |

### `CanvasFrameStats`

Per-frame numbers the dirty-redraw path actually produces.

```ts
interface CanvasFrameStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `painted` | `number` |  | Elements drawn this frame. |
| `culled` | `number` |  | Elements skipped because they fell outside every dirty rect. |
| `dirtyRects` | `number` |  | Dirty rects this frame; 0 means a full repaint. |
| `fullRepaint` | `boolean` |  | True when the whole canvas was repainted. |
| `changedEntities` | `number` |  | Entities whose VNode changed. |

### `CanvasLike`

A canvas element, structurally — so tests can hand in a fake.

```ts
interface CanvasLike
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `style?` | `{ width?: string; height?: string; [key: string]: unknown }` |  |  |

**Members**

- `getContext(id: '2d', options?: unknown): Canvas2DLike | null`
- `toDataURL?(type?: string, quality?: number): string`

### `CanvasPick`

What was under the cursor.

```ts
interface CanvasPick
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `HitRecord['kind']` |  |  |
| `id` | `string` |  |  |
| `vnode` | `VNode` |  |  |

### `CanvasRefusedEvent`

```ts
interface CanvasRefusedEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `hazards` | `readonly CanvasHazard[]` |  |  |
| `explanation` | `string` |  |  |

### `CanvasRendererOptions`

```ts
interface CanvasRendererOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `canvas?` | `CanvasLike \| null` |  | The visible canvas. Required to paint; omit only for pure measurement. |
| `hitCanvas?` | `CanvasLike \| null` |  | The offscreen picking canvas. Created from `canvas`'s document when absent. Pass `null` (with `enableHitDetection: false`) to run without one. |
| `devicePixelRatio?` | `number` |  | Default: `globalThis.devicePixelRatio ?? 1`. Overridable for tests. |
| `theme?` | `Theme` |  |  |
| `producerConfig?` | `SVGRendererConfig` |  | Config for the VNode producer. Defaults match the SVG backend exactly. |
| `producer?` | `SVGRenderer` |  | Reuse an existing VNode producer — this is how a live diagram switches backends without rebuilding its scene (render-backend.ts). |
| `enableHitDetection?` | `boolean` |  | Enable the colour-keyed hit canvas. Default true. |
| `hitCanvasScale?` | `number` |  | Sub-sampling factor for the hit canvas. 1 = pixel-exact picking (default). 0.5 halves its memory at the cost of ~1px of picking slop. |
| `enableDirtyRegions?` | `boolean` |  | Enable dirty-rectangle partial redraw. Default true. |
| `styleHost?` | `Element \| null` |  | Element whose computed `--grafloria-*` custom properties override the theme — normally the canvas's host. This is what lets a host theme canvas mode with the same CSS variables it uses for SVG mode. |

### `CanvasSafety`

```ts
interface CanvasSafety
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `safe` | `boolean` |  | True when nothing would be lost by drawing this diagram on a canvas. |
| `hazards` | `CanvasHazard[]` |  | Everything that would be lost. Empty iff `safe`. |

### `CanvasSafetyInput`

```ts
interface CanvasSafetyInput
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `a11yActive` | `boolean` |  |  |
| `focusInside` | `boolean` |  |  |
| `hasForeignObject` | `boolean` |  |  |

### `ComputedStyle`

Everything the painter needs to know to draw one element.

```ts
interface ComputedStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth` | `number` |  |  |
| `strokeDasharray?` | `number[]` |  |  |
| `opacity` | `number` |  | Element opacity, already multiplied down the group chain. |
| `fillOpacity?` | `number` |  |  |
| `strokeOpacity?` | `number` |  |  |
| `fontFamily` | `string` |  |  |
| `fontSize` | `number` |  |  |
| `fontWeight` | `string` |  |  |
| `fontStyle` | `string` |  |  |
| `textAnchor` | `'start' \| 'middle' \| 'end'` |  |  |
| `dominantBaseline` | `string` |  |  |
| `visible` | `boolean` |  | `display: none` / `visibility: hidden` → not painted at all. |
| `filter?` | `string` |  | CSS filter string (e.g. `blur(4px)`), passed through when supported. |
| `clipPathId?` | `string` |  | `clip-path: url(#id)` → the referenced clip id. |

### `DirtyDiff`

```ts
interface DirtyDiff
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `rects` | `Bounds[] \| null` |  | World rects to repaint, or `null` for "repaint everything" (first frame, camera move, theme swap, or too much changed to be worth clipping). |
| `changed` | `string[]` |  | Entities whose VNode object is new this frame. |
| `removed` | `string[]` |  | Entities that disappeared. |

### `EntityScope`

The entity a subtree belongs to.

```ts
interface EntityScope
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `HitKind` |  |  |
| `id` | `string` |  |  |
| `key` | `string` |  | The VNode key — `node-n1`, and therefore the dirty tracker's entity key. |

### `EntitySnapshot`

The bounds of one top-level entity, and the VNode that produced them.

```ts
interface EntitySnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `vnode` | `VNode` |  |  |
| `bounds` | `Bounds \| null` |  |  |

### `HitRecord`

One pickable region, in WORLD coordinates.

Produced by the paint pass, consumed by both picking strategies (the colour-
keyed hit canvas and the geometric fallback). `zIndex` is paint order, so the
last-painted region under the cursor is the topmost one — which is the same
rule `DiagramModel.getNodeAtPosition` applies when it iterates nodes in
reverse.

```ts
interface HitRecord
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `HitKind` |  |  |
| `id` | `string` |  | Entity id (node id / link id / port id). |
| `cmds` | `PathCmd[]` |  | World-space geometry — the exact path that was drawn. |
| `filled` | `boolean` |  | True when the region is the filled interior; false when it is the stroke. |
| `tolerance` | `number` |  | Pick tolerance for stroke regions (world units, half-width). |
| `zIndex` | `number` |  | Paint order. |
| `vnode` | `VNode` |  | The VNode that produced the region (the `IRenderer.hitTest` return value). |
| `colorKey` | `string` |  | Colour key for the offscreen picking canvas (`#rrggbb`). |
| `bounds` | `Bounds \| null` |  |  |

### `Matrix`

A 2D affine transform, in the order a canvas `setTransform(a,b,c,d,e,f)` takes.

```ts
interface Matrix
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `a` | `number` |  |  |
| `b` | `number` |  |  |
| `c` | `number` |  |  |
| `d` | `number` |  |  |
| `e` | `number` |  |  |
| `f` | `number` |  |  |

### `PaintOptions`

```ts
interface PaintOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `worldToDevice` | `Matrix` |  | World → device matrix (viewBox + zoom + devicePixelRatio, composed). |
| `dirtyWorld?` | `Bounds[]` |  | Only repaint elements intersecting these WORLD rects. Omit for a full repaint. The caller is responsible for having clipped/cleared them. |
| `pickingPass?` | `boolean` |  | Paint the colour-key silhouettes instead of the real styles (hit canvas). |
| `measureOnly?` | `boolean` |  | Compute bounds and hit regions, draw nothing. Used to measure a changed entity's extent before deciding what to repaint. |
| `allocateColorKey?` | `(stableId: string) => string` |  | Colour-key allocator, keyed by a STABLE per-element id. |

### `PaintResult`

```ts
interface PaintResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `hitRecords` | `HitRecord[]` |  | Every pickable region produced this frame, in paint order. |
| `colorKeyIndex` | `Map<string, HitRecord>` |  | colour key → record, for the offscreen picking canvas. |
| `unpaintableNodes` | `VNode[]` |  | Elements the canvas cannot draw (foreignObject) — the host may overlay them. |
| `bounds` | `Bounds \| null` |  | World bounds of everything painted. |
| `entityBounds` | `Map<string, Bounds \| null>` |  | Per-entity world bounds (`node-n1` → its extent), for the dirty tracker. |
| `paintedCount` | `number` |  | Elements actually painted (after dirty-rect culling). |
| `culledCount` | `number` |  | Elements skipped because they fell outside the dirty region. |

### `RenderBackendOptions`

```ts
interface RenderBackendOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `BackendMode` |  | Initial backend. Default 'svg' — the historical behaviour. |
| `theme?` | `Theme` |  |  |
| `producerConfig?` | `SVGRendererConfig` |  | Config for the shared VNode producer. |
| `devicePixelRatio?` | `number` |  |  |
| `enableHitDetection?` | `boolean` |  |  |
| `enableDirtyRegions?` | `boolean` |  |  |
| `guardCanvas?` | `boolean` |  | REFUSE a switch to canvas that would take something away. |
| `onCanvasRefused?` | `(event: CanvasRefusedEvent) => void` |  | Told when the backend refuses a canvas switch, and what it would have cost. |

### `StyleResolverOptions`

```ts
interface StyleResolverOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `Theme` |  |  |
| `varOverrides?` | `Record<string, string>` |  | CSS custom-property overrides — normally read off the diagram's host element with {@link readCssVarOverrides}, so a host that redefines `--grafloria-*` in its own stylesheet gets the same paint on canvas as it does on SVG. |

### `SubPath`

One flattened sub-path: a polyline, plus whether it was explicitly closed.

```ts
interface SubPath
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `Point[]` |  |  |
| `closed` | `boolean` |  |  |

### `TextLine`

One drawn line of text, already positioned in the element's local space.

```ts
interface TextLine
```

**Properties**

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

<!-- source: grafloria-renderer-canvas-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `BackendMode`

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

```ts
type BackendMode = 'svg' | 'canvas';
```

### `CanvasHazard`

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

Why canvas mode would take something away from this particular diagram, right now.

```ts
type CanvasHazard =

  | 'a11y-active'

  | 'focus-inside'

  | 'foreign-object';
```

### `DrawCall`

One recorded paint operation, with the state that produced it.

```ts
type DrawCall =
  | {
      op: 'fill';
      path: PathCmd[];
      fillStyle: unknown;
      globalAlpha: number;
      transform: Matrix;
      filter?: string;
    }
  | {
      op: 'stroke';
      path: PathCmd[];
      strokeStyle: unknown;
      lineWidth: number;
      lineDash: number[];
      globalAlpha: number;
      transform: Matrix;
      filter?: string;
    }
  | { op: 'clip'; path: PathCmd[]; transform: Matrix }
  | {
      op: 'fillText';
      text: string;
      x: number;
      y: number;
      font: string;
      fillStyle: unknown;
      textAlign: CanvasTextAlign;
      textBaseline: CanvasTextBaseline;
      globalAlpha: number;
      transform: Matrix;
    }
  | { op: 'clearRect'; x: number; y: number; w: number; h: number; transform: Matrix }
  | {
      op: 'fillRect';
      x: number;
      y: number;
      w: number;
      h: number;
      fillStyle: unknown;
      transform: Matrix;
    }
  | { op: 'save' }
  | { op: 'restore' }
  | { op: 'setTransform'; transform: Matrix };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `op` | `'fill'` |  |  |

### `HitKind`

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

What a hit region belongs to.

```ts
type HitKind = 'node' | 'link' | 'port' | 'other';
```

### `PathCmd`

```ts
type PathCmd =
  | { op: 'M'; x: number; y: number }
  | { op: 'L'; x: number; y: number }
  | { op: 'C'; x1: number; y1: number; x2: number; y2: number; x: number; y: number }
  | { op: 'Q'; x1: number; y1: number; x: number; y: number }
  | { op: 'Z' };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `op` | `'M'` |  |  |

<!-- source: grafloria-renderer-canvas-canvas2dlike.md -->

# Canvas2DLike

Import it from `@grafloria/renderer`.

The subset of `CanvasRenderingContext2D` the painter uses. A real 2D context
satisfies this structurally — no adapter needed.

```ts
interface Canvas2DLike
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fillStyle` | `unknown` |  |  |
| `strokeStyle` | `unknown` |  |  |
| `lineWidth` | `number` |  |  |
| `lineJoin` | `CanvasLineJoin` |  |  |
| `lineCap` | `CanvasLineCap` |  |  |
| `globalAlpha` | `number` |  |  |
| `font` | `string` |  |  |
| `textAlign` | `CanvasTextAlign` |  |  |
| `textBaseline` | `CanvasTextBaseline` |  |  |
| `filter?` | `string` |  |  |

**Members**

- `save(): void`
- `restore(): void`
- `setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void`
- `beginPath(): void`
- `moveTo(x: number, y: number): void`
- `lineTo(x: number, y: number): void`
- `bezierCurveTo(x1: number, y1: number, x2: number, y2: number, x: number, y: number): void`
- `quadraticCurveTo(x1: number, y1: number, x: number, y: number): void`
- `closePath(): void`
- `fill(): void`
- `stroke(): void`
- `clip(): void`
- `clearRect(x: number, y: number, w: number, h: number): void`
- `fillRect(x: number, y: number, w: number, h: number): void`
- `setLineDash(segments: number[]): void`
- `fillText(text: string, x: number, y: number): void`
- `measureText(text: string): { width: number }`
- `createLinearGradient?(x0: number, y0: number, x1: number, y1: number): unknown`
- `createRadialGradient?( x0: number, y0: number, r0: number, x1: number, y1: number, r1: number ): unknown`

<!-- source: grafloria-renderer-canvas-canvasrenderer.md -->

# CanvasRenderer

Import it from `@grafloria/renderer`.

```ts
class CanvasRenderer implements IRenderer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` |  |  | Renderer mode |
| `capabilities` | `RendererCapabilities` |  | Optional: capability flags for runtime feature detection, so callers can ask instead of assuming (e.g. "can this renderer do foreignObject?"). |

**Methods**

- `constructor(engine: DiagramEngine, options: CanvasRendererOptions = {})`
- `render(viewport: Rectangle, zoom: number): VNode` — Produce the frame's VNode tree and paint it.

Returns the tree (rather than `void`) on purpose: it is the same tree SVG
mode would have reconciled, so a caller can assert parity, or hand it to the
SVG patcher, without re-rendering.
- `getPerformanceMetrics(): PerformanceMetrics` — Get performance metrics
- `hitTest(x: number, y: number): VNode | null` — The topmost element at a WORLD coordinate.

Colour-keyed pixel picking when a real hit canvas is available (O(1), and
exactly what was drawn); the geometric fallback otherwise. They are two
implementations of ONE geometry — both read the hit records the paint pass
produced — and they are pinned to each other, and to the engine's own
`getNodeAtPosition`, in `canvas-hit-parity.spec.ts` and in the browser e2e.
- `pick(x: number, y: number): CanvasPick | null` — Hit-test, with the entity identity the interaction layer wants.
- `pickPixel(x: number, y: number): HitRecord | null` — Colour-key pick: read one pixel off the hit canvas and look the colour up. `null` when there is no hit canvas (headless) OR when the pixel is empty.
- `pickGeometric(x: number, y: number): HitRecord | null` — Geometric pick: reverse paint order over the hit records, point-in-path for
filled regions and distance-to-path for stroked ones. O(n), used headlessly
and as the oracle the pixel picker is checked against.
- `measureText(text: string, style: TextStyle): TextMetrics` — Text measurement through the real 2D context when there is one (proper glyph
metrics), falling back to the same average-glyph estimate the SVG text-block
engine uses so headless measurement stays consistent with the wrapping the
producer already did.
- `async export(format: ExportFormat, options: ExportOptions = {}): Promise<string>` — Export the CURRENT canvas contents. `svg` is not a canvas capability.
- `dispose(): void` — Dispose renderer and clean up resources
- `getTheme(): Theme`
- `setTheme(theme: Theme): void` — Swap the theme. Repaints everything: every resolved colour just changed.
- `getProducer(): SVGRenderer` — The VNode producer — shared with the SVG backend on a mode switch.
- `setCanvas(canvas: CanvasLike | null, hitCanvas?: CanvasLike | null): void` — Attach (or replace) the canvas this renderer paints into.
- `setDevicePixelRatio(dpr: number): void` — Change the device pixel ratio (a window moved to a retina display).
- `getDevicePixelRatio(): number`
- `getFrameStats(): CanvasFrameStats` — What the last frame actually repainted — the dirty-region proof.
- `getHitRecords(): readonly HitRecord[]` — Every pickable region of the current frame, in paint order.
- `getUnpaintableNodes(): readonly VNode[]` — Nodes the canvas could not paint (`foreignObject` — live HTML/components). A host that uses them should mount an HTML overlay for exactly these.
- `invalidate(): void` — Force the next frame to repaint the whole canvas.

<!-- source: grafloria-renderer-canvas-diagramrenderbackend.md -->

# DiagramRenderBackend

Import it from `@grafloria/renderer`.

One diagram, two backends, one VNode tree.

The host owns a container element; the backend owns whatever goes inside it
(`<svg>` or `<canvas>`) and swaps that out on `setMode`.

```ts
class DiagramRenderBackend
```

**Methods**

- `constructor(engine: DiagramEngine, container: Element, options: RenderBackendOptions = {})`
- `getMode(): BackendMode`
- `getRenderer(): SVGRenderer | CanvasRenderer` — The renderer currently driving the picture.
- `getProducer(): SVGRenderer` — The shared VNode producer (identical object in both modes).
- `setMode(mode: BackendMode, options: { force?: boolean } = {}): boolean` — Switch backend on a LIVE diagram. The producer, the engine, the theme and
the camera all survive; only the paint target changes. The next `render()`
repaints from scratch into the new target.

A switch TO canvas is now REFUSED when it would take something away
(an AT surface is live, focus is inside the diagram, or the scene has HTML nodes
canvas cannot paint). Returns whether the switch happened. Going back to SVG is never
refused — that direction can only ever restore what canvas lacks.

`setMode('canvas', { force: true })` overrides the guard. A host that has taken the
decision knowingly can still have it; what it cannot do is take it by accident.
- `render(viewport: Rectangle, zoom: number): VNode`
- `canvasSafety(): CanvasSafety` — What canvas mode would cost this diagram right now. `safe` iff it would cost nothing.
- `setAccessibilityActive(active: boolean): void` — Tell the backend an assistive-technology surface is live for this diagram (an outline
view, a live region, keyboard navigation).

While it is, `setMode('canvas')` is refused — and if we are ALREADY on canvas, this
immediately returns the diagram to SVG rather than waiting for the next frame. A
screen reader that arrives mid-session gets its semantics back at once.
- `hitTest(worldX: number, worldY: number): CanvasPick | null`
- `setTheme(theme: Theme): void`
- `dispose(): void`

<!-- source: grafloria-renderer-canvas-recordingcontext2d.md -->

# RecordingContext2D

Import it from `@grafloria/renderer`.

A `Canvas2DLike` that records what was drawn instead of rasterising it.

The recording is the assertion surface for the canvas backend's unit tests:
"the VNode tree said `<rect fill=#fff stroke=#333 stroke-width=2>` at
(100,100)" ⇒ "the context received a fill with fillStyle #fff and a stroke
with lineWidth 2 over exactly that path, under exactly that transform".

It faithfully models the parts of the 2D state machine the painter depends on
— the save/restore stack, the current transform, the current path — so a bug
in the painter's state handling (a missing `restore`, a transform applied
twice) shows up in the recording rather than hiding behind a mock.

```ts
class RecordingContext2D implements Canvas2DLike
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `calls` | `DrawCall[]` | `[]` |  |
| `charWidthRatio` |  | `0.6` | Width of one character, used by `measureText`. Matches the SVG-side estimate. |

**Methods**

- `get fillStyle(): unknown`
- `set fillStyle(v: unknown)`
- `get strokeStyle(): unknown`
- `set strokeStyle(v: unknown)`
- `get lineWidth(): number`
- `set lineWidth(v: number)`
- `get lineJoin(): CanvasLineJoin`
- `set lineJoin(v: CanvasLineJoin)`
- `get lineCap(): CanvasLineCap`
- `set lineCap(v: CanvasLineCap)`
- `get globalAlpha(): number`
- `set globalAlpha(v: number)`
- `get font(): string`
- `set font(v: string)`
- `get textAlign(): CanvasTextAlign`
- `set textAlign(v: CanvasTextAlign)`
- `get textBaseline(): CanvasTextBaseline`
- `set textBaseline(v: CanvasTextBaseline)`
- `get filter(): string`
- `set filter(v: string)`
- `save(): void`
- `restore(): void`
- `setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void`
- `beginPath(): void`
- `moveTo(x: number, y: number): void`
- `lineTo(x: number, y: number): void`
- `bezierCurveTo(x1: number, y1: number, x2: number, y2: number, x: number, y: number): void`
- `quadraticCurveTo(x1: number, y1: number, x: number, y: number): void`
- `closePath(): void`
- `fill(): void`
- `stroke(): void`
- `clip(): void`
- `clearRect(x: number, y: number, w: number, h: number): void`
- `fillRect(x: number, y: number, w: number, h: number): void`
- `setLineDash(segments: number[]): void`
- `fillText(text: string, x: number, y: number): void`
- `measureText(text: string): { width: number }` — The same average-glyph estimate the SVG text-block engine uses
(`text.length * fontSize * 0.6`), so headless measurement agrees with the
line-breaking the VNode producer already did. A real 2D context measures
glyphs properly; this is only the headless stand-in.
- `createLinearGradient(x0: number, y0: number, x1: number, y1: number): unknown`
- `createRadialGradient( x0: number, y0: number, r0: number, x1: number, y1: number, r1: number ): unknown`
- `reset(): void` — Drop the recording (keeps the current state — mirrors a fresh frame).
- `paintCalls(): DrawCall[]` — Every paint call (ignores bookkeeping ops) — the usual assertion target.

<!-- source: grafloria-renderer-comments.md -->

# Comments

Import these from `@grafloria/renderer`.

## Functions

### `commentPinAccessibleName`

The accessible name of a pin. This is the ONLY thing an AT user hears about a comment
before they decide whether to open it, so it has to answer the question they are
actually asking: what is this about, is it live, and is any of it new to me?

```ts
function commentPinAccessibleName(thread: CommentThreadView): string
```

### `renderCommentPins`

Build the pin layer.

Returns a `<g>` even when empty: a stable element keeps the patcher's keyed diff
simple, and an empty `<g>` costs nothing to reconcile.

```ts
function renderCommentPins(
  threads: readonly CommentThreadView[],
  options: CommentPinsOptions = {}
): VNode
```

## Classes

### `CommentOverlayController`

```ts
class CommentOverlayController implements CommentSource
```

**Methods**

- `constructor( private readonly store: CommentStore, private readonly renderer: CommentRendererHost, private readonly options: CommentOverlayOptions = {} )`
- `getThreads(): readonly CommentThreadView[]` — The threads to draw. Called once per BUILT frame (never on a skipped one).
- `getPinOptions(): Pick<CommentPinsOptions, 'selectedThreadId' | 'showResolved' | 'radius'>` — Local view state — selection and the resolved filter.

NOT keyboard focus. That is the RENDERER's `a11yFocus`, which already owns the roving
tabindex for nodes and edges, and a comment pin is just a third kind of thing in the
same one-tab-stop widget. Two authorities for "what is focused" is how you get two
elements with `tabindex=0`, which is the exact bug the roving tabindex exists to
prevent — so there is one, and it is the one that already existed.
- `select(threadId: string | null): void` — Open a thread. Opening it is READING it, which is what "unread" means.
- `getSelected(): string | null`
- `setShowResolved(show: boolean): void`
- `markRead(threadId: string): void` — Mark a thread read WITHOUT opening it (the "mark all read" affordance).
- `getInvalidationCount(): number` — How many times the picture has been declared stale. A test asserts this moves.
- `dispose(): void`

### `CommentPanelView`

```ts
class CommentPanelView
```

**Methods**

- `constructor( container: HTMLElement, private readonly store: CommentStore, options: CommentPanelOptions = {} )`
- `getElement(): HTMLElement`
- `getRebuildCount(): number`
- `select(threadId: string | null, opts?: { focus?: boolean }): void` — Which thread is open. Setting it re-renders and moves focus onto the conversation.
- `getSelected(): string | null`
- `update(): boolean` — Rebuild if — and only if — something the panel SHOWS has changed.

Safe on every frame. A drag, a pan and a zoom all change the diagram and change
nothing here, and must therefore cost zero DOM operations.
- `dispose(): void`

## Interfaces

### `CommentOverlayOptions`

```ts
interface CommentOverlayOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `showResolved?` | `boolean` |  |  |
| `onSelectionChange?` | `(threadId: string \| null) => void` |  | Notified when the open thread changes (a host pans to it, opens the panel, …). |

### `CommentPanelOptions`

```ts
interface CommentPanelOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` |  | Accessible name of the region. |
| `showResolved?` | `boolean` |  | Show resolved threads too. Default false — a resolved thread is an answered one. |
| `onSelect?` | `(threadId: string \| null) => void` |  | Called when the user picks a thread (the host selects it and pans to it). |
| `onDismiss?` | `() => void` |  | Called on Escape. The host MUST return focus to the canvas. |
| `formatTime?` | `(ms: number) => string` |  | Render a wall-clock timestamp. Injectable so tests are not clock-dependent. |

### `CommentPinsOptions`

```ts
interface CommentPinsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `visibleRect?` | `{ x: number; y: number; width: number; height: number }` |  | World rect currently on screen. Pins outside it are not built. |
| `zoom?` | `number` |  | Current zoom, so the pin can be counter-scaled to a constant screen size. |
| `selectedThreadId?` | `string \| null` |  | The thread whose panel is open — drawn selected, and `aria-expanded=true`. |
| `focusedThreadId?` | `string \| null` |  | The comment the roving tabindex has focused, if any. |
| `showResolved?` | `boolean` |  | Hide resolved threads (the default view — a resolved thread is answered). |
| `radius?` | `number` |  | Radius in SCREEN pixels. |

### `CommentRendererHost`

The slice of the renderer this controller drives. Structural, so it is trivial to fake.

```ts
interface CommentRendererHost
```

**Members**

- `setCommentSource(source: CommentSource | null): void`
- `invalidateFrame(): void`

### `CommentSource`

What the renderer needs from a comment source. Deliberately tiny — the renderer must not
know what a thread IS, only where the pins go and what they are called.

```ts
interface CommentSource
```

**Members**

- `getThreads(): readonly CommentThreadView[]` — The threads to draw. Called once per BUILT frame (never on a skipped one).
- `getPinOptions(): Pick<CommentPinsOptions, 'selectedThreadId' | 'showResolved' | 'radius'>` — Local view state — selection and the resolved filter.

NOT keyboard focus. That is the RENDERER's `a11yFocus`, which already owns the roving
tabindex for nodes and edges, and a comment pin is just a third kind of thing in the
same one-tab-stop widget. Two authorities for "what is focused" is how you get two
elements with `tabindex=0`, which is the exact bug the roving tabindex exists to
prevent — so there is one, and it is the one that already existed.

<!-- source: grafloria-renderer-export.md -->

# Export

Import these from `@grafloria/renderer`.

## On their own pages

- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-constants): 10 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-functions): 55 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-interfaces): 25 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-types): 14 types.
- [`SerializeOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-serializeoptions)
- [`SvgExportOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-export-svgexportoptions)

<!-- source: grafloria-renderer-export-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `AVG_CHAR_WIDTH_EM`

The average glyph advance, as a fraction of font-size.

THE SAME CONSTANT `LabelRenderer.estimateTextWidth` uses. It is a rough mean for
proportional Latin text — and it being rough is fine, because the renderer sizes
label backgrounds with it too. What matters is that the two AGREE: a bbox derived
from a different estimate than the one that placed the text would crop labels the
renderer thought it had left room for.

```ts
const AVG_CHAR_WIDTH_EM: 0.6
```

### `DEFAULT_MAX_OUTPUT_SIZE`

The default cap on an exported raster's pixel size, per side.

```ts
const DEFAULT_MAX_OUTPUT_SIZE: 4000
```

### `GRAFLORIA_MODEL_KEY`

The PNG text-chunk keyword, and the SVG element name.

NOT `grafloria-diagram`: that is already the CSS class on the exported root
(`class="grafloria-diagram"`), so "does this file carry a model?" would answer YES for
every export we have ever produced.

```ts
const GRAFLORIA_MODEL_KEY: "grafloria-model"
```

### `GRAFLORIA_NS`

The XML namespace the embedded model lives in.

```ts
const GRAFLORIA_NS: "https://grafloria.dev/ns/diagram"
```

### `IMAGE_NOT_INLINED_WARNING`

Companion caveat from `resolveImageHref` — same lifecycle as {@link IMAGE_PDF_WARNING}.

```ts
const IMAGE_NOT_INLINED_WARNING: string
```

### `IMAGE_PDF_WARNING`

The capture-time verdict on an external image, EXPORTED because the async export path
revises it: `await export(…)` fetches external URLs (environment fetch, then
`ExportOptions.assetFetcher`) and STRIPS this warning from any capture whose images it
embedded — see `stripResolvedImageWarnings`. The synchronous entry points cannot fetch,
so for them this text is the whole truth, and it names the way out.

```ts
const IMAGE_PDF_WARNING: string
```

### `PAGE_SIZES`

Page sizes in POINTS (1/72"), which is PDF's only unit.

```ts
const PAGE_SIZES: { readonly a4: { readonly width: 595.28; readonly height: 841.89; }; readonly letter: { readonly width: 612; readonly height: 792; }; readonly legal: { readonly width: 612; readonly height: 1008; }; readonly a3: { readonly width: 841.89; readonly height: 1190.55; }; readonly tabloid: { readonly width: 792; readonly height: 1224; }; }
```

### `SVG_XMLNS`

```ts
const SVG_XMLNS: "http://www.w3.org/2000/svg"
```

### `utf8`

UTF-8, implemented rather than borrowed.

`TextEncoder`/`TextDecoder` are NOT reliably global: they are absent in jsdom (which
is what the renderer's own tests run in) and were late to Node. Sniffing for them and
falling back would give two code paths that can disagree about a surrogate pair — in a
module whose entire job is lossless bytes. So: one path, always, everywhere.

```ts
const utf8: { encode(text: string): Uint8Array<ArrayBufferLike>; decode(bytes: Uint8Array<ArrayBufferLike>): string; }
```

### `XML_DECLARATION`

The XML prolog. Required by strict XML parsers and by most SVG→PDF toolchains.

```ts
const XML_DECLARATION: "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>"
```

<!-- source: grafloria-renderer-export-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `base64ToBytes`

Pure base64 → bytes. (No `atob`: it does not exist in Node, and this must stay DOM-free.)

```ts
function base64ToBytes(base64: string): Uint8Array
```

### `buildPrintDocument`

Build a printable HTML document from already-exported SVG pages.

PURE — it returns a string. That is deliberate: it keeps the page-building testable, and
leaves the one genuinely browser-side act (opening a print dialog) to `printDocument`.

The `page-break-after` on every sheet but the last is what makes the browser emit one
physical page per tile instead of reflowing them all into a single column.

```ts
function buildPrintDocument(svgPages: string[], options: PrintOptions = {}): string
```

### `bytesToBase64`

Pure bytes → base64.

```ts
function bytesToBase64(bytes: Uint8Array): string
```

### `bytesToDataUrl`

bytes → `data:<mime>;base64,…`

```ts
function bytesToDataUrl(bytes: Uint8Array, mimeType: string): string
```

### `canRasterizeInThisEnvironment`

Is there a canvas we can draw into? (browser main thread or worker)

```ts
function canRasterizeInThisEnvironment(): boolean
```

### `captureCustomNodeHost`

Capture ONE custom node's host into plain data.

Never throws: an export must not be taken down by a host in a state we did not
anticipate. A failed capture degrades to `fidelity: 'empty'`, which the pure layer
turns into a marked box and a warning — the whole point being that a blank is never
silent.

```ts
function captureCustomNodeHost(
  id: string,
  rect: Rectangle,
  host: unknown,
  options: CaptureHostOptions = {}
): CustomNodeCapture
```

### `clampOutputSize`

Clamp an export's PIXEL size.

A 3x export of a big diagram is how you ask a browser for a 30000 × 20000 canvas
and get back a blank image — canvas has a hard area/side limit (~16k on most
engines, less on Safari/mobile), and it fails SILENTLY: `toDataURL` hands you a
blank or throws deep inside the driver. So we cap the output and REDUCE THE SCALE
to fit, rather than emitting a request we know will fail.

Reducing scale (not cropping) is the right lever: it keeps the whole picture and
only spends fewer pixels on it, which is exactly the trade a caller who asked for
"3x, and it must fit" wants.

`minSize` floors the result so a tiny diagram still yields a usable image rather
than a 12 × 8 sliver.

```ts
function clampOutputSize(
  width: number,
  height: number,
  requestedScale: number,
  maxSize: number = DEFAULT_MAX_OUTPUT_SIZE,
  minSize = 1
): ClampResult
```

### `collectAssetUrls`

Every external asset URL the tree references. PURE.

Deduplicated and returned in a STABLE order (first appearance), so a caller that fetches
them and re-inlines gets the same bytes for the same diagram every time — determinism runs
all the way through this module.

```ts
function collectAssetUrls(root: VNode): string[]
```

### `computeBreaks`

Choose the break positions along ONE axis.

Walks left to right. At each naive break (`origin + pageSize`) it looks for boxes the
break would slice; if there are any, it tries pulling the break back to the leftmost
slicee's leading edge. That move is only taken when the page it leaves is still at least
`1 - tolerance` full — otherwise we would trade one cut node for a page count explosion.

```ts
function computeBreaks(
  start: number,
  end: number,
  pageSize: number,
  boxes: Box[],
  options: { snap: boolean; tolerance: number; overlap: number; warnings: string[]; axis: 'x' | 'y' }
): number[]
```

### `crc32`

```ts
function crc32(bytes: Uint8Array): number
```

### `createClassStyleResolver`

Build the resolver for a theme. Compiles BASE_STYLE_RULES once (var refs
resolved against the theme's variable values), then matches class lists
against it.

```ts
function createClassStyleResolver(theme: Theme, warnings: string[] = []): ClassStyleResolver
```

**Parameters**

- `theme`: the theme whose `--grafloria-*` values get baked in
- `warnings`: collector — a declaration whose variable cannot be resolved is dropped and reported here rather than silently emitting `var(--…)`.

### `createDomRasterBackend`

The zero-dependency browser backend: draw the SVG into a canvas and read the
pixels back out.

Prefers `OffscreenCanvas` when present (so it works in a worker, off the main
thread) and falls back to a detached `<canvas>`.

```ts
function createDomRasterBackend(): RasterBackend
```

### `createResvgBackend`

A PNG rasterizer backed by resvg. PNG only — resvg has no JPEG or WebP encoder, and
pretending otherwise would mean handing a caller PNG bytes under a `image/jpeg` mime
type, which is the kind of quiet lie this seam exists to prevent.

`fitTo: width` is what applies the export's scale: the SVG carries the picture, and
resvg renders it at the pixel width we ask for.

```ts
function createResvgBackend(resvg: ResvgModule): RasterBackend
```

### `createSharpBackend`

A rasterizer backed by sharp (libvips + librsvg). Produces all three raster formats.

The SVG goes in as BYTES, not as a path: sharp reads an SVG buffer through librsvg. `density` is how sharp scales vector input — 72 is the 1:1 baseline, so we scale the
DPI by the ratio of the target pixel width to the SVG's intrinsic width and let
librsvg rasterize at that resolution rather than upscaling a small bitmap.

```ts
function createSharpBackend(sharp: SharpModule): RasterBackend
```

### `customNodeBounds`

The union of the captures' world rects.

Needed because a lifted chart is a `<g transform>` full of nested geometry and a
`foreignObject`'s content is opaque — so `vnodeBounds` alone can under-measure a
board. On an all-custom-node dashboard it would find NOTHING and fit the file to a
40px square. The node rects are the truth about where the widgets are, so the box
is fitted to those as well.

```ts
function customNodeBounds(
  captures: readonly CustomNodeCapture[],
  includeIds?: ReadonlySet<string>
): Rectangle | null
```

### `customNodeVNodes`

Turn captures into VNodes ready to append to the exported tree.

Pure: same captures in, same VNodes and same warnings out. Order follows the input,
which the boundary builds from the model's node order — so an export is byte-stable.

```ts
function customNodeVNodes(
  captures: readonly CustomNodeCapture[],
  options: CustomNodeOptions = {}
): { nodes: VNode[]; warnings: string[] }
```

### `dataUrlToBytes`

`data:image/png;base64,…` → the bytes. Throws on a URL that is not base64 data.

```ts
function dataUrlToBytes(dataUrl: string): Uint8Array
```

### `embedModelInPng`

Insert the model into a PNG as an `iTXt` chunk, immediately before `IEND`.

The pixels are untouched: the result is the same image, and any decoder that does
not know the chunk simply skips it (text chunks are ancillary by definition).

```ts
function embedModelInPng(png: Uint8Array, envelope: DiagramDocumentEnvelope): Uint8Array
```

### `embedModelInSvg`

Insert the model into an SVG document, right after the root `<svg …>` tag.

The JSON is XML-escaped text, not base64 — it stays greppable and diffable, and the
envelope's checksum catches any tool that mangles it on the way through.

```ts
function embedModelInSvg(svg: string, envelope: DiagramDocumentEnvelope): string
```

### `escapeAttr`

XML-escape an attribute value.

```ts
function escapeAttr(value: string): string
```

### `escapeText`

XML-escape text content.

```ts
function escapeText(value: string): string
```

### `exportBatch`

Export many documents. Never throws for a job-level failure — a failed job comes back
with `error` set and the batch keeps going.

Results are returned IN INPUT ORDER regardless of the order they finish in, because a
caller zipping results back onto its own list should not have to think about the pool.

```ts
async function exportBatch(jobs: BatchJob[], options: BatchOptions = {}): Promise<BatchResult[]>
```

### `exportPdf`

Export a rendered VNode tree as a vector PDF.

```ts
function exportPdf(root: VNode, options: PdfExportOptions = {}): PdfExportResult
```

### `exportSvg`

Serialize a rendered VNode tree to a standalone SVG string.

```ts
function exportSvg(root: VNode, options: SvgExportOptions = {}): SvgExportResult
```

**Parameters**

- `root`: the root `<svg>` VNode from `SVGRenderer.render(viewport, zoom)`

### `extractModel`

Find the embedded model in ANY exported artifact — SVG text, a `data:` URL of
either kind, or PNG bytes. `null` when the artifact carries no model (a plain image
is not an error; it is simply not editable).

```ts
function extractModel(artifact: Artifact): DiagramDocumentEnvelope | null
```

### `extractModelFromPng`

Pull the model back out of a PNG. `null` when the image carries none.

Reads BOTH `iTXt` (what we write) and `tEXt` (so a file produced by another tool, or
an older writer, still opens).

```ts
function extractModelFromPng(png: Uint8Array): DiagramDocumentEnvelope | null
```

### `extractModelFromSvg`

Pull the model back out of an SVG. `null` when there is none — a plain SVG is not
an error, it is just not editable.

THROWS if a model IS present but does not parse: a corrupted payload must not
silently degrade into "no model", which would look to the user like a successful
import of an empty diagram.

```ts
function extractModelFromSvg(svg: string): DiagramDocumentEnvelope | null
```

### `fetchAssetsTiered`

Fetch every URL through the tiers above. Deduplicated: a URL is fetched once no
matter how many elements reference it. Resolves when the last URL settles; never
rejects.

```ts
async function fetchAssetsTiered(
  urls: readonly string[],
  options: TieredFetchOptions = {}
): Promise<TieredFetchResult>
```

### `fetchFont`

Fetch a font and turn it into a {@link FontSource}, ready for {@link fontFaceCss}.

```ts
async function fetchFont(
  url: string,
  descriptor: Omit<FontSource, 'data' | 'format'> & { format?: FontFormat },
  options: ResolveAssetsOptions = {}
): Promise<FontSource>
```

### `filterCaptures`

Keep only the captures whose node id is in `ids` — the `includeIds` scoping rule.

```ts
function filterCaptures(
  captures: readonly CustomNodeCapture[],
  ids: Iterable<string> | undefined
): readonly CustomNodeCapture[]
```

### `filterTreeByIds`

Prune a rendered tree down to the given node/link ids.

Returns a new tree; the input is not mutated (the caller's tree is the live
render, and mutating it would corrupt the next frame).

```ts
function filterTreeByIds(root: VNode, ids: Iterable<string>): VNode
```

### `fontFaceCss`

Build the `@font-face` CSS that makes an export carry its own glyphs.

PURE — bytes in, CSS out. Hand the result to `SvgExportOptions.embedFontCss` and the file
renders identically on a machine that has never heard of the typeface.

The `format('…')` hint is not decoration: without it a renderer must sniff the bytes, and
some (notably older librsvg) simply decline and fall back.

```ts
function fontFaceCss(fonts: FontSource[]): string
```

### `fontFormatFromUrl`

`woff2` from a `.woff2` URL, etc. Defaults to woff2 — by far the most common on the web.

```ts
function fontFormatFromUrl(url: string): FontFormat
```

### `importDiagram`

Re-open an exported artifact as a live diagram.

The rehydration runs through the ENGINE's own `DiagramSerializer.deserialize`, which
unwraps the envelope, VERIFIES the checksum (throwing on a mismatch), and runs the
schema migrations. So an artifact exported by an older build opens in a newer one,
and a corrupted one refuses to open rather than opening subtly wrong.

Returns `null` for an artifact with no embedded model.

```ts
function importDiagram(artifact: Artifact, options?: DiagramLoadOptions): DiagramModel | null
```

### `inlineAssets`

Replace external asset URLs with the supplied `data:` URIs. PURE — returns a new tree.

A URL with no entry in the map is LEFT ALONE rather than blanked: a broken-but-present
reference is debuggable, and an element silently stripped of its href is not. The async
layer reports those as warnings.

```ts
function inlineAssets(root: VNode, byUrl: ReadonlyMap<string, string>): VNode
```

### `isEditableArtifact`

Does this artifact carry a model we could re-open?

```ts
function isEditableArtifact(artifact: Artifact): boolean
```

### `isExternalUrl`

Is this a reference that has to leave the document to resolve?

```ts
function isExternalUrl(value: unknown): value is string
```

### `loadNodeRasterBackend`

Find a rasterizer in this Node process.

The imports are DYNAMIC and the specifiers are built at runtime, so a bundler cannot
statically resolve them and will not try to pull a native module into a browser bundle
(which is how an optional native dep usually breaks a web build).

```ts
async function loadNodeRasterBackend(format: 'png' | 'jpeg' | 'webp' = 'png'): Promise<RasterBackend>
```

**Parameters**

- `format`: the format you intend to produce — only sharp can do the lossy ones, so asking for jpeg/webp will not hand you a resvg backend that would then throw.

### `mimeTypeForFormat`

`'png'` → `'image/png'`. Throws for a format that is not a raster format.

```ts
function mimeTypeForFormat(format: string): string
```

### `n`

Deterministic number formatting — no `-0`, no float noise, no locale.

```ts
function n(value: number): string
```

### `nodeBoxes`

Collect the world boxes of the diagram's NODES.

Nodes only. Links are lines: cutting one across a page boundary is normal and reads fine
(the line simply continues on the next tile). Cutting a NODE leaves half a box and half a
word, which is what makes a tiled print look broken.

```ts
function nodeBoxes(root: VNode): Array<{ x: Box; y: Box }>
```

### `padRect`

Grow a rectangle by `padding` on every side.

```ts
function padRect(rect: Rectangle, padding: number): Rectangle
```

### `pageDimensions`

The page's dimensions in points, after orientation.

```ts
function pageDimensions(
  size: PageSize | { width: number; height: number },
  orientation: Orientation
): { width: number; height: number }
```

### `paginate`

Lay a diagram out across a grid of pages.

```ts
function paginate(root: VNode, options: PaginationOptions): PaginationResult
```

### `printDocument`

Open the browser's print dialog for a document built by {@link buildPrintDocument}.

Prints through a hidden IFRAME rather than `window.open`: a popup is blocked by default in
every browser unless the call is inside a user gesture, and a blocked popup means the
print button silently does nothing. An iframe always works, and it does not disturb the
page the user is on.

Browser-only, and it says so rather than throwing something cryptic in Node.

```ts
function printDocument(html: string): Promise<void>
```

### `resolveAssets`

Fetch every external asset the tree references and inline it as a `data:` URI.

A FAILED ASSET IS A WARNING, NOT A THROW. One 404 avatar must not lose you the export of a
200-node diagram — the reference is left as-is (still broken, but visible and debuggable)
and the caller is told. That is the same rule the batch exporter follows.

```ts
async function resolveAssets(root: VNode, options: ResolveAssetsOptions = {}): Promise<ResolveAssetsResult>
```

### `resolveCssVars`

Replace every `var(--grafloria-*)` in a declaration with its literal theme value. Returns `undefined` when a referenced variable has no value and no fallback —
the declaration is then DROPPED rather than emitted as an unresolvable
reference, and the caller records a warning.

```ts
function resolveCssVars(
  value: string,
  vars: Record<string, string>
): string | undefined
```

### `resolveRasterBackend`

The backend an export will actually use: the caller's, else the browser one,
else a hard failure that tells you exactly what to do.

```ts
function resolveRasterBackend(explicit?: RasterBackend): RasterBackend
```

### `scopeKeysFor`

Every key shape the renderer can mint for a given diagram id.

`renderNode` has a second early-return path for HTML-layer nodes that keys them
`node-<id>-html-layer`, so an exact-match set built only from `node-<id>` would
silently drop those from a selection export.

```ts
function selectionKeys(ids: Iterable<string>): Set<string>
```

### `selectionKeys`

Every key shape the renderer can mint for a given diagram id.

`renderNode` has a second early-return path for HTML-layer nodes that keys them
`node-<id>-html-layer`, so an exact-match set built only from `node-<id>` would
silently drop those from a selection export.

```ts
function selectionKeys(ids: Iterable<string>): Set<string>
```

### `serializeVNode`

Serialize ONE VNode (and its subtree) to an XML string.

Pure: same VNode in, same string out — no ambient state, no DOM, no clock, no
randomness. Attribute order follows prop insertion order, which the renderer
builds deterministically, so two calls on the same tree are byte-identical.

```ts
function serializeVNode(vnode: VNode, options: SerializeOptions = {}): string
```

### `stripResolvedImageWarnings`

Remove the two external-image caveats from a capture's warning — called by the async
export AFTER it embedded every external image the capture held, at which point both
sentences assert a problem that no longer exists (the same defect, mirrored, as
staying silent about one that does). Returns undefined when nothing else remains.

```ts
function stripResolvedImageWarnings(warning: string | undefined): string | undefined
```

### `svgToDataUri`

SVG string → `data:image/svg+xml` URL.

`encodeURIComponent`, NOT base64: `btoa` throws on any non-Latin-1 character,
so a diagram with a non-ASCII label (or the renderer's own '…' ellipsis, or the
📌 lock indicator) would blow up the PNG path.

```ts
function svgToDataUri(svg: string): string
```

### `viewBoxTransform`

The transform that maps a `viewBox` onto a rect the way `preserveAspectRatio` says
— the fit an inline `<svg>` gets from the browser for free, resolved into an
ordinary affine transform so every target can honour it.

Supports the two forms that actually occur: `none` (stretch each axis
independently) and `x??Y?? meet` (uniform scale, then align). `slice` is treated as
`meet`: over-filling the widget box would paint a chart over its neighbours, and a
chart that is slightly small is a far smaller lie than one that overlaps.

```ts
function viewBoxTransform(
  viewBox: Rectangle,
  rect: { width: number; height: number },
  preserveAspectRatio = 'xMidYMid meet'
): string
```

### `vnodeBounds`

The union box of everything a VNode tree paints, in the tree's own user space.

Returns `null` for a tree that paints nothing (an empty diagram) — the caller
decides what an empty document should be, because "nothing" is not a rectangle.

```ts
function vnodeBounds(root: VNode, options: BoundsOptions = {}): Rectangle | null
```

<!-- source: grafloria-renderer-export-interfaces.md -->

# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `BatchJob`

```ts
interface BatchJob
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Echoed back on the result, so a caller can correlate without relying on order. |
| `document` | `BatchDocument` |  |  |
| `format?` | `ExportFormat` |  | Default `'svg'` — the only format that needs no rasterizer at all. |
| `options?` | `ExportOptions` |  | Merged over the batch-wide options. |

### `BatchOptions`

```ts
interface BatchOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options?` | `ExportOptions` |  | Applied to every job; a job's own `options` win. |
| `theme?` | `Theme` |  | Theme for every job. |
| `rendererConfig?` | `SVGRendererConfig` |  | Renderer config for every job. |
| `concurrency?` | `number` |  | How many jobs run at once. Default 4. |
| `onProgress?` | `(done: number, total: number, result: BatchResult) => void` |  | Called as each job settles — for a progress bar or a log line. |

### `BatchResult`

```ts
interface BatchResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `format` | `ExportFormat` |  |  |
| `output?` | `string` |  | The artifact: an SVG string, or a `data:` URL for a raster. Absent when `error` is set. |
| `warnings` | `string[]` |  | Fidelity caveats (foreignObject, unresolved theme vars, a clamped size). |
| `error?` | `Error` |  | Set when THIS job failed. The rest of the batch still ran. |

### `BoundsOptions`

```ts
interface BoundsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeIds?` | `Set<string>` |  | Only union elements whose subtree is one of these diagram ids (node ids / link ids). This is what makes a SELECTION export tight around the selection. |

### `CaptureHostOptions`

```ts
interface CaptureHostOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale?` | `number` |  | The camera zoom the html layer is transformed by. Client rects are SCREEN space, so they are divided by this to get the host-local layout coordinates the export needs. Defaults to being inferred from the host itself, which is more reliable than trusting a caller to remember. |
| `maxElements?` | `number` |  | Safety valve for a pathologically deep host. Default 4000 elements. |

### `ClampResult`

```ts
interface ClampResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale` | `number` |  | The scale that actually gets used (≤ the requested one). |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `warning?` | `string` |  | Set when the requested scale had to be reduced. |

### `CustomNodeCapture`

What the DOM boundary hands the pure layer for one custom node.

```ts
interface CustomNodeCapture
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The node id — carried onto the group, and what `includeIds` scoping matches. |
| `rect` | `Rectangle` |  | The node's WORLD rect (position + size), i.e. where to place the content. |
| `fidelity` | `CustomNodeFidelity` |  |  |
| `content?` | `VNode[]` |  | The transcribed display list, in HOST-RELATIVE coordinates (0,0 = the host's top-left). Placed by translating to `rect`. Only for `fidelity: 'vector'`. |
| `html?` | `string` |  | Raw XHTML for the `foreignObject` attempt. Only for `fidelity: 'html'`. |
| `warning?` | `string` |  | A caveat the DOM boundary knows and this layer cannot see. |

### `CustomNodeOptions`

```ts
interface CustomNodeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `htmlFallback?` | `HtmlFallbackMode` |  | How to export a `fidelity: 'html'` capture. Default `'foreignObject'` — the honest best effort: browsers render it, so an SVG opened in a browser or placed in a web page is correct. It is still reported as a fidelity risk, because a PDF and most standalone rasterizers will drop it. |

### `FontSource`

```ts
interface FontSource
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `family` | `string` |  | The family name the diagram's `font-family` refers to, e.g. `Inter`. |
| `data` | `Uint8Array` |  | The font program's bytes. |
| `format?` | `FontFormat` |  |  |
| `weight?` | `string \| number` |  | e.g. `400`, `700`, `'bold'`. Default `'normal'`. |
| `style?` | `string` |  | `'normal'` \| `'italic'`. Default `'normal'`. |
| `unicodeRange?` | `string` |  | Optional `unicode-range` descriptor. |

### `Page`

```ts
interface Page
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  | 0-based, reading order (left→right, top→bottom). |
| `row` | `number` |  |  |
| `column` | `number` |  |  |
| `rect` | `Rectangle` |  | The world window mapped onto the paper. Always the full page size — see the header. |
| `clip` | `Rectangle` |  | The sub-rectangle actually painted. Equals `rect` unless a break was snapped in. |

### `PaginationOptions`

```ts
interface PaginationOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pageWidth` | `number` |  | One page's width in WORLD units. |
| `pageHeight` | `number` |  | One page's height in WORLD units. |
| `overlap?` | `number` |  | World units each page repeats from its neighbour — a bleed, so a printed poster can be trimmed and taped without losing a strip. Default 0. |
| `snapToNodes?` | `boolean` |  | Pull a page break back so it does not slice through a node. Default true — a break through the middle of a box is the thing that makes tiled printouts unusable. |
| `snapTolerance?` | `number` |  | How far a break may be pulled back, as a fraction of the page. Default 0.25. |
| `content?` | `Rectangle` |  | The region to paginate. Default: the tree's content bounds. |
| `padding?` | `number` |  | Padding around the content bounds, in world units. Default 20. |

### `PaginationResult`

```ts
interface PaginationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pages` | `Page[]` |  |  |
| `columns` | `number` |  |  |
| `rows` | `number` |  |  |
| `columnBreaks` | `number[]` |  | The x break positions (page origins). |
| `rowBreaks` | `number[]` |  | The y break positions. |
| `warnings` | `string[]` |  | Nodes we could NOT spare — a break had to cut them. |

### `PdfExportOptions`

```ts
interface PdfExportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme?` | `Theme` |  | The theme the tree was rendered with. REQUIRED for fidelity in CSS mode: a node's fill and a link's stroke live in the stylesheet, not on the element, so without the theme to resolve them the PDF comes out nearly blank. Defaults to LIGHT_THEME. |
| `pageSize?` | `PageSize \| { width: number; height: number }` |  |  |
| `orientation?` | `Orientation` |  |  |
| `margin?` | `number \| { top: number; right: number; bottom: number; left: number }` |  | Points (1/72"). Default 36 (half an inch) on every side. |
| `viewBox?` | `Rectangle` |  | The world rectangle to draw. Default: the tree's content bounds. |
| `padding?` | `number` |  | Padding around the content bounds, in world units. Default 20. |
| `metadata?` | `PdfMetadata` |  |  |
| `backgroundColor?` | `string` |  | Paint a page background. Default: none (white paper shows through). |
| `pages?` | `Array<Rectangle \| { rect: Rectangle; clip?: Rectangle }>` |  | Pages to lay the diagram across. Supplied by the paginator. |
| `pageNumbers?` | `boolean` |  | Draw "n / total" at the foot of each page. Default false; the paginator turns it on. |

### `PdfExportResult`

```ts
interface PdfExportResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pdf` | `Uint8Array` |  |  |
| `pageCount` | `number` |  |  |
| `warnings` | `string[]` |  |  |

### `PdfMetadata`

```ts
interface PdfMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `string` |  |  |
| `author?` | `string` |  |  |
| `subject?` | `string` |  |  |
| `keywords?` | `string` |  |  |
| `creationDate?` | `string` |  | ISO-8601. Omit for a deterministic file — a wall-clock stamp makes bytes differ. |

### `PdfRgb`

PDF paints in 0–1 channels, not 0–255. Named `PdfRgb` so it cannot be confused with the theme's `Rgb` (which is 0–255).

```ts
interface PdfRgb
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `r` | `number` |  |  |
| `g` | `number` |  |  |
| `b` | `number` |  |  |

### `PrintOptions`

```ts
interface PrintOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `string` |  | Shown in the browser's print dialog and as the default filename. |
| `pageSize?` | `string` |  | CSS page size, e.g. `'A4 landscape'`. Default `'auto'`. |
| `margin?` | `string` |  | CSS margin for |

### `RasterBackend`

Pluggable rasterizer. Returns a `data:` URL.

```ts
interface RasterBackend
```

**Members**

- `rasterize(request: RasterizeRequest): Promise<string>`

### `RasterizeRequest`

What a rasterizer is asked to produce.

```ts
interface RasterizeRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `svg` | `string` |  | A standalone SVG document (styles inlined, no external references). |
| `width` | `number` |  | Target pixel width (already scaled). |
| `height` | `number` |  | Target pixel height (already scaled). |
| `mimeType` | `string` |  | `image/png` \| `image/jpeg` \| `image/webp`. |
| `quality?` | `number` |  | 0–1, for the lossy formats. |

### `ResolveAssetsOptions`

```ts
interface ResolveAssetsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fetcher?` | `AssetFetcher` |  | How to get the bytes. Defaults to `fetch` when the environment has one. |
| `maxBytes?` | `number` |  | Cap on one asset's size, in bytes. Default 5MB — a data: URI is ~33% bigger than the file. |

### `ResolveAssetsResult`

```ts
interface ResolveAssetsResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tree` | `VNode` |  |  |
| `inlined` | `number` |  | How many external references were replaced. |
| `warnings` | `string[]` |  |  |

### `ResvgModule`

The slice of `@resvg/resvg-js` we use.

```ts
interface ResvgModule
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `Resvg` | `new ( svg: string \| Uint8Array, options?: { fitTo?: { mode: 'width' \| 'height'; value: number } } ) => { render(): { asPng(): Uint8Array } }` |  |  |

### `SvgExportResult`

```ts
interface SvgExportResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `svg` | `string` |  | The standalone SVG document. |
| `width` | `number` |  | Intrinsic width in px (viewBox width × the CLAMPED scale). |
| `height` | `number` |  | Intrinsic height in px. |
| `viewBox` | `ViewBox` |  | The world rectangle the document actually covers — what pagination and PDF page off. |
| `warnings` | `string[]` |  | Fidelity caveats hit during this export (foreignObject, unresolved vars, size clamp, …). |

### `TieredFetchOptions`

```ts
interface TieredFetchOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fetcher?` | `AssetFetcher` |  | Tier 2: consulted only when the environment's own fetch fails. |
| `maxBytes?` | `number` |  | Cap on one asset's size, in bytes. Default 5MB. TERMINAL — no tier retries it. |
| `timeoutMs?` | `number` |  | Bound on fetching ONE URL, per tier, in milliseconds. Default 5000. |

### `TieredFetchResult`

```ts
interface TieredFetchResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `byUrl` | `Map<string, string>` |  | URL → `data:` URI, for every asset some tier could produce. |
| `failures` | `Map<string, string>` |  | URL → why EVERY tier failed — ready to surface as a warning. |

<!-- source: grafloria-renderer-export-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `Artifact`

Anything a user might drop on the canvas: an SVG string, a data: URL, or raw bytes.

```ts
type Artifact = string | Uint8Array;
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` |  | Returns the length of a String object. |

**Members**

- `toString(): string` — Returns a string representation of a string.
- `indexOf(searchString: string, position?: number): number` — Returns the position of the first occurrence of a substring.
- `lastIndexOf(searchString: string, position?: number): number` — Returns the last occurrence of a substring in the string.
- `slice(start?: number, end?: number): string` — Returns a section of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.
- `includes(searchString: string, position?: number): boolean` — Returns true if searchString appears as a substring of the result of converting this
object to a String, at one or more positions that are
greater than or equal to position; otherwise, returns false.
- `[Symbol.iterator](): StringIterator<string>` — Iterator
- `toLocaleString(): string` — Returns a date converted to a string using the current locale.

### `AssetFetcher`

Fetch bytes for a URL. Injectable — so tests never touch the network.

```ts
type AssetFetcher = (url: string) => Promise<{ data: Uint8Array; mimeType: string }>;
```

### `BaseFont`

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

```ts
type BaseFont =
  | 'Helvetica'
  | 'Helvetica-Bold'
  | 'Helvetica-Oblique'
  | 'Helvetica-BoldOblique'
  | 'Times-Roman'
  | 'Times-Bold'
  | 'Times-Italic'
  | 'Times-BoldItalic'
  | 'Courier'
  | 'Courier-Bold';
```

### `BatchDocument`

A document to export: the engine's envelope, or the flat serialized form.

```ts
type BatchDocument = SerializedDiagramData | DiagramDocumentEnvelope;
```

### `ClassStyleResolver`

Resolves an element's class list to the concrete presentation attributes the
renderer's stylesheet would have painted, for THIS theme.

```ts
type ClassStyleResolver = (classList: string[]) => Record<string, string>;
```

### `CustomNodeFidelity`

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

How faithfully a host's content could be captured.

- `vector` the host's paint was transcribed to SVG primitives. Exact, and it
  survives every target including PDF.
- `html`   the host holds markup we could not transcribe. The SVG target can carry
  it in a `<foreignObject>` (browsers render it); PDF and most standalone
  rasterizers cannot. Always warned about.
- `empty`  nothing capturable. A marked box plus a warning — never a silent blank.

```ts
type CustomNodeFidelity = 'vector' | 'html' | 'empty';
```

### `ExportScope`

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

WHAT rectangle of the world an export covers.

'content'   the whole diagram, tight around everything drawn (the default —
              a thumbnail of "whatever the user happened to be scrolled to" is
              almost never what anyone means)
  'viewport'  exactly what is on screen right now
  'selection' tight around the selected nodes/links alone

```ts
type ExportScope = 'content' | 'viewport' | 'selection';
```

### `FontFormat`

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

```ts
type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
```

### `ForeignObjectMode`

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

What the serializer does with a `<foreignObject>` (HTML-in-SVG) subtree.

```ts
type ForeignObjectMode = 'serialize' | 'placeholder' | 'omit';
```

### `HtmlFallbackMode`

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

What to do with a capture we could only get as HTML.

```ts
type HtmlFallbackMode = 'foreignObject' | 'placeholder' | 'omit';
```

### `Orientation`

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

```ts
type Orientation = 'portrait' | 'landscape';
```

### `PageSize`

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

```ts
type PageSize = keyof typeof PAGE_SIZES;
```

### `SerializeFidelity`

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

WHO is going to read this string — the only axis on which the two callers differ.

'file' (default)  A standalone `.svg` a rasterizer / Inkscape / an email client
                    will read. It has no stylesheet, so the cascade is FLATTENED
                    into presentation attributes; live-pipeline attributes minted
                    from process-global counters are DROPPED (they mean nothing in
                    a file and would destroy determinism); CSS `filter: blur()` is
                    translated into a real `<filter>` def.

'dom'             An SSR snapshot the client's VNodePatcher will ADOPT. Here the
                    string must describe exactly the DOM the patcher would have
                    built from the same tree — otherwise hydration sees a different
                    attribute set, tears the node down and rebuilds it, and the
                    diagram flashes. So: `style` is kept verbatim, nothing is
                    dropped, no cascade flattening, and the patcher's `data-vnode-key`
                    mirror is reproduced.

ONE traversal serves both. Keeping two would have meant two copies of the
prop→attribute rules, and the moment one learned a new verbatim attribute and the
other did not, exported files and hydrated pages would quietly disagree about what
the diagram looks like.

```ts
type SerializeFidelity = 'file' | 'dom';
```

### `SharpModule`

The slice of `sharp` we use.

```ts
type SharpModule = (input: Uint8Array, options?: { density?: number }) => {
  resize(width: number, height: number): ReturnType<SharpModule>;
  png(): ReturnType<SharpModule>;
  jpeg(options?: { quality?: number }): ReturnType<SharpModule>;
  webp(options?: { quality?: number }): ReturnType<SharpModule>;
  flatten(options?: { background?: string }): ReturnType<SharpModule>;
  toBuffer(): Promise<Uint8Array>;
};
```

<!-- source: grafloria-renderer-export-serializeoptions.md -->

# SerializeOptions

Import it from `@grafloria/renderer`.

```ts
interface SerializeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fidelity?` | `SerializeFidelity` |  | Who reads the output. Default `'file'`. See {@link SerializeFidelity}. |
| `standalone?` | `boolean` |  | Stamp `xmlns` on the root element (needed for a standalone `.svg` file). |
| `classStyles?` | `ClassStyleResolver` |  | Resolves an element's classes to the presentation attributes the renderer's stylesheet would have painted. Omit for a tree rendered in programmatic mode (there is no stylesheet there — every value is already on the element). Ignored under `fidelity: 'dom'` — the client has the real stylesheet. |
| `foreignObject?` | `ForeignObjectMode` |  | How to handle `<foreignObject>` subtrees. Default `'serialize'`. |
| `captureForeignObject?` | `(vnode: VNode) => string \| undefined` |  | Faithful foreignObject export. The VNode tree does NOT contain the HTML a framework mounted into a foreignObject (the patcher treats those subtrees as opaque and never touches their children) — so a headless serializer CANNOT know what is in there. A browser-side caller that has the live DOM can hand the markup back through this hook (e.g. |
| `warnings?` | `string[]` |  | Collector for fidelity caveats hit while serializing. |
| `extraDefs?` | `Map<string, string>` |  | Collector for `<defs>` elements the serializer had to synthesize (blur filters). |
| `html?` | `boolean` |  | This subtree is XHTML, not SVG (i.e. it is inside a `<foreignObject>`). Set automatically when recursing into one — HTML has no presentation attributes, so there the `style` attribute is kept verbatim and no class flattening is attempted (the host's own CSS, which we do not own, styles that content). |

<!-- source: grafloria-renderer-export-svgexportoptions.md -->

# SvgExportOptions

Import it from `@grafloria/renderer`.

```ts
interface SvgExportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme?` | `Theme` |  | The theme whose values get baked into the output. MUST be the theme the tree was rendered with — it is the source of every `--grafloria-*` value the live stylesheet would have supplied. Defaults to LIGHT_THEME. |
| `scale?` | `number` |  | Multiplies the SVG's `width`/`height` (its intrinsic size) while the `viewBox` stays put — so the picture is unchanged, just rendered larger. This is what makes a 2x PNG a 2x PNG. |
| `backgroundColor?` | `string` |  | Painted as a full-viewBox rect behind everything. Default: transparent. |
| `foreignObject?` | `ForeignObjectMode` |  | What to do with `<foreignObject>` subtrees. Default `'serialize'`. |
| `captureForeignObject?` | `(vnode: VNode) => string \| undefined` |  | Supply the live HTML inside a foreignObject (browser-side callers). |
| `customNodes?` | `readonly CustomNodeCapture[]` |  | CUSTOM-NODE CONTENT — the widgets an HTML-layer node paints, which the VNode tree does not contain and cannot contain (the renderer emits an empty `<g>` for those nodes; the page paints a raw HTML host that is a SIBLING of the SVG). |
| `htmlFallback?` | `HtmlFallbackMode` |  | What to do with a custom node that could only be captured as HTML. Default `'foreignObject'`. Whatever you choose, it is REPORTED in `warnings` — a widget that cannot make it into the file faithfully never does so quietly. |
| `embedFontCss?` | `string` |  | CSS emitted verbatim into a `<style>` inside `<defs>`. THE font seam: pass an `@font-face` whose `src` is a `data:` URI and the exported file carries its own glyphs. We do not fetch, subset or embed fonts for you — that is a deliberate boundary, not an oversight. |
| `embedFonts?` | `FontSource[]` |  | Fonts to EMBED as base64 `@font-face` rules — the built form of the `embedFontCss` seam. Both are honoured; `embedFontCss` is appended after these. |
| `fitToContent?` | `boolean` |  | Fit the viewBox to the CONTENT — the union box of everything the tree actually draws (labels, ports and arrowheads included), not the root's own viewBox. |
| `padding?` | `number` |  | Margin around the fitted content box, in world units. Default 20. |
| `includeIds?` | `Iterable<string>` |  | Export ONLY these node/link ids. The tree is pruned to them (not merely cropped — an un-selected node outside the viewBox is invisible but its markup, and its labels, would still be in the bytes) and the box is fitted around them. |
| `viewBox?` | `Rectangle` |  | Use this exact viewBox and fit nothing. Wins over `fitToContent`. |
| `maxSize?` | `number` |  | Cap on the output's intrinsic size, per side, in px. Default 4000. The scale is REDUCED to fit rather than the picture being cropped — see `clampOutputSize`. |
| `minSize?` | `number` |  | Floor on the output's intrinsic size, per side, in px. Default 1. |
| `xmlDeclaration?` | `boolean` |  | Prepend the `<?xml …?>` prolog. Default false (an inline `<svg>` must not have one). |
| `embedModel?` | `DiagramDocumentEnvelope` |  | Embed this document envelope in the SVG's `<metadata>`, making the exported file an EDITABLE artifact: re-import it and get the diagram back, losslessly. |

<!-- source: grafloria-renderer-ext.md -->

# Ext

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-classes): 3 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-constants): 13 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-functions): 45 functions.
- [Interfaces A–T](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-interfaces-a-t): 34 interfaces, `AnchorContext` to `TemplateCapability`.
- [Interfaces T–V](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-interfaces-t-v): 5 interfaces, `ToolCapability` to `ViewportPortal`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-types): 14 types.
- [`DiagramRegistry`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-ext-diagramregistry): The contribution surface. Obtained from a diagram as `diagram.registry`, or as

<!-- source: grafloria-renderer-ext-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `DisposableStore`

A bag of disposers with a single `dispose()`. Extensions accumulate their
registrations here so the host can tear the whole extension down atomically.

Disposal runs in REVERSE registration order (like a stack unwind) and is
failure-tolerant: one throwing disposer must not strand the rest, or a single
bad extension would leak every registry behind it.

```ts
class DisposableStore implements Disposable
```

**Methods**

- `add(disposer: Disposer): Disposer` — Track a disposer. If the store is ALREADY disposed, run it immediately.
- `get size(): number` — How many live registrations this store holds (tests assert on this).
- `get isDisposed(): boolean`
- `dispose(): void`

### `ExtensionHost`

```ts
class ExtensionHost
```

**Methods**

- `constructor(options: ExtensionHostOptions)`
- `get engine(): DiagramEngine` — The engine this host is bound to (hosts, not extensions, may ask).
- `register<C extends CapabilityName>(extension: Extension<C>): Disposer` — Register and ACTIVATE an extension.

Throws — deliberately, and before any side effect — when the manifest is
malformed, the id is taken, the engine range excludes this host, or the
extension asks for a capability this host cannot grant. A plugin that half-
loads is worse than one that refuses to.
- `registerLazy<C extends CapabilityName>( manifest: ExtensionManifest<C>, load: LazyExtension<C> ): Disposer` — Register WITHOUT loading. The factory is not called until `activate(id)`,
so a 500 KB plugin costs nothing until something needs it.

The manifest is supplied up front precisely so the host can answer "what
shapes/routers exist?" and validate compatibility WITHOUT paying the import.
- `async activate(id: string): Promise<void>` — Activate a lazily-registered extension (imports it on first call).
- `dispose(id: string): void` — Tear one extension down. Every registration it made is undone.
- `disposeAll(): void` — Tear everything down. The host is unusable afterwards.
- `has(id: string): boolean`
- `get(id: string): RegisteredExtension | undefined`
- `list(): RegisteredExtension[]` — Everything registered, loaded or not.

### `RegistryScope`

One diagram's private overlay over the process-global registries.

An entry here SHADOWS the global one of the same name for reads taken inside
this scope; a name absent here falls through. That layering is what lets a
diagram override a built-in (or an app-wide `registerShape()` at import time)
for itself alone, without mutating what anybody else sees.

```ts
class RegistryScope
```

**Methods**

- `table<V>(name: string): Map<string, V>` — The named table, created on demand. Use for WRITES.
- `peek<V>(name: string): Map<string, V> | undefined` — The named table if it exists, WITHOUT creating it. Use for READS.
- `isEmpty(): boolean` — True when this diagram has contributed nothing — i.e. it is pure fall-through.
- `clear(): void` — Drop every contribution (instance teardown).

<!-- source: grafloria-renderer-ext-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `ANCHORS`

```ts
const ANCHORS: "anchors"
```

### `CONNECTION_POINTS`

```ts
const CONNECTION_POINTS: "connectionPoints"
```

### `CONNECTORS`

```ts
const CONNECTORS: "connectors"
```

### `EXTENSION_API_VERSION`

The engine/host API version extensions declare compatibility against.

```ts
const EXTENSION_API_VERSION: "1.0.0"
```

### `GLOBAL_DIAGRAM_REGISTRY`

The process-wide registry — what the module-level `register*` functions write to.

```ts
const GLOBAL_DIAGRAM_REGISTRY: DiagramRegistry
```

### `LABEL_TEMPLATES`

```ts
const LABEL_TEMPLATES: "labelTemplates"
```

### `LINK_TEMPLATES`

```ts
const LINK_TEMPLATES: "linkTemplates"
```

### `MARKERS`

```ts
const MARKERS: "markers"
```

### `PORTAL_CLASS`

```ts
const PORTAL_CLASS: "grafloria-portal"
```

### `SCREEN_LAYER_CLASS`

```ts
const SCREEN_LAYER_CLASS: "grafloria-screen-layer"
```

### `SHAPES`

Table names. Constants rather than string literals so a typo cannot silently
create a second, empty table that reads as "nothing registered".

```ts
const SHAPES: "shapes"
```

### `STYLES`

```ts
const STYLES: "styles"
```

### `WORLD_PORTAL_CLASS`

```ts
const WORLD_PORTAL_CLASS: "grafloria-world-portal"
```

<!-- source: grafloria-renderer-ext-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `activeRegistryScope`

The active scope, or null. Hosts should not need this; the registries do.

```ts
function activeRegistryScope(): RegistryScope | null
```

### `assertEngineCompatible`

Reject a plugin built against an incompatible host API.

```ts
function assertEngineCompatible(
  manifest: ExtensionManifest<CapabilityName>,
  apiVersion: string
): void
```

### `clearConnectionValidators`

```ts
function clearConnectionValidators(): void
```

### `clearLinkPipeline`

Drop every registration (tests, host teardown). Built-ins are re-seeded.

```ts
function clearLinkPipeline(): void
```

### `clearTools`

```ts
function clearTools(): void
```

### `connectionValidatorCount`

How many validators are live (tests assert this returns to 0 after dispose).

```ts
function connectionValidatorCount(): number
```

### `createCounterScaledPortal`

A world-space portal that must also stay a FIXED SCREEN SIZE (a resize handle,
a badge that should not grow when you zoom in). It lives in world space but
counter-scales by 1/zoom on every camera change.

```ts
function createCounterScaledPortal(
  htmlLayer: HTMLElement,
  viewport: ViewportController,
  options: { x?: number; y?: number; className?: string; style?: string } = {}
): ViewportPortal
```

### `createDiagramApi`

```ts
function createDiagramApi(instance: DiagramInstance): DiagramApi
```

### `createExtensionHost`

Convenience: a host bound to a live `createDiagram()` instance.

```ts
function createExtensionHost(options: ExtensionHostOptions): ExtensionHost
```

### `createPortal`

Mount a SCREEN-SPACE portal — a floating panel pinned to the viewport.

```ts
const panel = createPortal(diagram.container, { placement: 'top-right' });
panel.element.appendChild(myToolbar);
// later
panel.dispose();
```

```ts
function createPortal(root: HTMLElement, options: PortalOptions = {}): Portal
```

### `createViewportPortal`

Mount a WORLD-SPACE portal — content that pans and zooms WITH the canvas.

`x`/`y` are WORLD coordinates. The element is placed inside the camera-
transformed HTML layer, so it needs no per-frame updates: the single transform
on the layer moves it. That is why this takes the layer, not the viewport, and
why there is no `onChange` subscription to leak.

```ts
const note = createViewportPortal(htmlLayer, { x: 320, y: 180 });
note.element.textContent = 'sticky note';
```

```ts
function createViewportPortal(
  htmlLayer: HTMLElement,
  options: { x?: number; y?: number; className?: string; style?: string } = {}
): ViewportPortal
```

### `defineNodeComponent`

```ts
function defineNodeComponent<D = Record<string, unknown>>(
  component: NodeComponent<D>
): NodeComponent<D>
```

### `ensureScreenLayer`

The screen-space layer, created lazily on the diagram root. Idempotent: many
portals share one layer.

```ts
function ensureScreenLayer(root: HTMLElement): HTMLElement
```

### `getAnchor`

```ts
function getAnchor(name: string): AnchorFn | undefined
```

### `getConnectionPoint`

```ts
function getConnectionPoint(name: string): ConnectionPointFn | undefined
```

### `getConnector`

```ts
function getConnector(name: string): ConnectorFn | undefined
```

### `getLinkPipelineVersion`

```ts
function getLinkPipelineVersion(): number
```

### `getTool`

```ts
function getTool(id: string): CanvasTool | undefined
```

### `hasAnchor`

```ts
function hasAnchor(name: string): boolean
```

### `hasConnectionPoint`

```ts
function hasConnectionPoint(name: string): boolean
```

### `hasConnector`

```ts
function hasConnector(name: string): boolean
```

### `hasTool`

```ts
function hasTool(id: string): boolean
```

### `isValidConnection`

Evaluate every registered validator. This is the public `isValidConnection`
hook. With no validators registered it is `{ valid: true }` — i.e. free.

```ts
function isValidConnection(candidate: ConnectionCandidate): ConnectionValidity
```

### `listAnchors`

```ts
function listAnchors(): string[]
```

### `listConnectionPoints`

```ts
function listConnectionPoints(): string[]
```

### `listConnectors`

```ts
function listConnectors(): string[]
```

### `listTools`

```ts
function listTools(): string[]
```

### `loadCanvasPlugins`

```ts
function loadCanvasPlugins(): Promise<typeof import('./components/attach')>
```

### `mountNodeComponents`

Wire a component registry into a live diagram.

Returns a disposer that unmounts every component and disconnects every
observer — the leak rule; a stranded ResizeObserver keeps its target's whole
subtree alive.

```ts
function mountNodeComponents(
  instance: DiagramInstance,
  registry: NodeComponentRegistry
): Disposer
```

### `nodeComponentOptions`

The options you hand to `createDiagram()` to use a component registry from the
very first paint (preferred over `mountNodeComponents` on a running instance,
because the first render then already has the components).

```ts
const diagram = createDiagram(el, {
  nodes, edges,
  ...nodeComponentOptions(registry, () => diagram),
});
```

```ts
function nodeComponentOptions(
  registry: NodeComponentRegistry,
  getInstance: () => DiagramInstance
): {
  renderCustomNode: (node: NodeModel, element: HTMLElement) => void;
  removeCustomNode: (id: string, element: HTMLElement) => void;
}
```

### `notifyLinkPipelineChanged`

Internal: let a PER-DIAGRAM registry participate in the version/notify
protocol. A scoped registration must invalidate cached VNodes for exactly the
reason a global one must — the definition is baked into the cache. Notifying
every renderer (not just the contributing one) is deliberate: over-invalidation
costs a repaint, under-invalidation shows a stale picture.

```ts
function notifyLinkPipelineChanged(): void
```

### `once`

Wrap a function so it can only ever run once.

```ts
function once(fn: Disposer): Disposer
```

### `onLinkPipelineChange`

```ts
function onLinkPipelineChange(listener: () => void): Disposer
```

### `registerAnchor`

Register a named anchor. Address it per link via
`link.metadata.sourceAnchor` / `link.metadata.targetAnchor`.

```ts
function registerAnchor(name: string, fn: AnchorFn): Disposer
```

**Returns** a disposer that RESTORES whatever was registered under this name
before (so overriding a built-in is reversible).

### `registerConnectionPoint`

Register a named connection-point strategy. Address it per link via
`link.metadata.connectionPoint`, or set it as the diagram-wide default with
the renderer's `connectionPoint` config.

The built-in `'smart'` strategy is the draw.io-style floating attachment that
used to be reachable ONLY through the boolean `smartConnectionPoints` config
flag. That flag still works (it now selects this strategy by name), so nothing
that relied on it changes behaviour.

```ts
function registerConnectionPoint(name: string, fn: ConnectionPointFn): Disposer
```

### `registerConnectionValidator`

Register a connection validator. ALL registered validators must pass for a
connection to be offered — veto power, not voting power, because a rule that
can be outvoted is not a rule.

```ts
function registerConnectionValidator(validator: ConnectionValidator): Disposer
```

### `registerConnector`

Register a named connector. Address it per link via `link.connector`
.

The four built-in names — `straight` / `rounded` / `smooth` / `bezier` — are
NOT in this map: they are the renderer's own internal branches and stay
exactly as they were. This registry is consulted only for names the renderer
does not recognise, which is precisely the case that used to be dropped.

```ts
function registerConnector(name: string, fn: ConnectorFn): Disposer
```

### `registerTool`

Register (or replace) a canvas tool. Returns a disposer that RESTORES the
previous tool of the same id — so overriding `'node-drag'` and then unloading
the extension gives the original back rather than leaving a hole.

On every pointerdown, {@link resolveTool} asks EVERY registered tool
`hitTest(event, hit)` and the gesture goes to the claiming tool with the
HIGHEST `priority` (default 1; the built-in ladder is effectively 0). Ties
resolve by registration order — first registered wins — and that is a
fallback, NOT a contract: tools composed from different waves and extensions
register in an order nobody designed. A tool that can ever be active at the
same time as another MUST state an explicit priority.

Choosing one: a POINT-SPECIFIC claim (hitTest inspects the point — "is there
ink under the pointer?") should outrank a POINT-AGNOSTIC mode claim (hitTest
is just "am I active?"), because the specific tool only fires where it means
to and would otherwise be starved by the broad one everywhere it matters. The whiteboard tools are the worked example: draw/rectangle/eraser sit at
`WHITEBOARD_MODE_TOOL_PRIORITY` (1), the ink-hit-only StrokeEditTool at
`WHITEBOARD_INK_TOOL_PRIORITY` (2) — see whiteboard-tools.ts.

```ts
function registerTool(tool: CanvasTool): Disposer
```

### `resolveTool`

The tool (if any) that claims this gesture, highest priority first (ties:
first registered — see the arbitration contract on {@link registerTool}).

The DomEventBinder calls this FIRST on pointerdown. `undefined` means "no
registered tool wants it" — and then the built-in ladder runs untouched, which
is why adding this seam changed no existing behaviour.

```ts
function resolveTool(
  event: ToolPointerEvent,
  hit: ToolHitContext
): CanvasTool | undefined
```

### `runInRegistryScope`

Run `fn` with `scope` active, restoring whatever was active before.

An EMPTY scope is treated as no scope at all. That is not merely an
optimisation: it keeps the hot read path for a diagram that contributed
nothing — which is every existing embedder and all 104 demos — at exactly its
previous cost, one null check with no Map lookup behind it.

```ts
function runInRegistryScope<T>(scope: RegistryScope | null | undefined, fn: () => T): T
```

### `satisfies`

A deliberately small semver range matcher. Supports:
  *  / x            any
  1.2.3             exact
  ^1.2.3            >=1.2.3 <2.0.0   (and ^0.2.3 → >=0.2.3 <0.3.0)
  ~1.2.3            >=1.2.3 <1.3.0
  >=1.2.3, >1.2.3, <=1.2.3, <1.2.3
  1.x / 1.2.x
  " || "            union of any of the above

```ts
function satisfies(version: string, range: string): boolean
```

### `scopedTable`

The active scope's table for `name`, or undefined when there is no scope or it
has no such table. THE READ HELPER every registry uses — deliberately one
function so all of them shadow identically.

```ts
function scopedTable<V>(name: string): Map<string, V> | undefined
```

### `sideTowards`

The side of `rect` you would leave from to head towards `towards` — the same
dominant-axis rule the built-in smart strategy uses.

```ts
function sideTowards(rect: ExtRect, towards: ExtPoint): ExtSide
```

### `snapshotRestore`

Build a disposer that puts a registry key back the way it was.

```ts
function snapshotRestore<T>(
  previous: T | undefined,
  restore: (value: T) => void,
  remove: () => void
): Disposer
```

**Parameters**

- `previous`: the value read out of the registry BEFORE the write (or `undefined` when the key did not exist)
- `restore`: re-register the previous value
- `remove`: delete the key (used when there was no previous value)

### `validateManifest`

Throw with a precise reason. A malformed manifest must never half-load.

```ts
function validateManifest(manifest: ExtensionManifest<CapabilityName>): void
```

<!-- source: grafloria-renderer-ext-interfaces-a-t.md -->

# Interfaces A–T

Import these from `@grafloria/renderer`.

## Interfaces

### `AnchorContext`

```ts
interface AnchorContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `end` | `LinkEnd` |  | The end being anchored. |
| `other` | `LinkEnd` |  | The OTHER end's node — direction-aware anchors (perimeter) need it. |
| `link` | `LinkModel` |  | The link, for reading style/metadata. |
| `defaultPoint` | `ExtPoint` |  | The point the DEFAULT (port-based) pipeline would have produced. An anchor that only wants to nudge the default does not have to recompute it. |
| `args` | `Record<string, unknown>` |  | Free-form args from `link.metadata.sourceAnchorArgs` / `targetAnchorArgs`. |

### `AnchorResult`

```ts
interface AnchorResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `point` | `ExtPoint` |  |  |
| `side?` | `ExtSide` |  | The side the link should LEAVE from. Routers use it to pick the exit stub. |

### `AnimationCapability`

Contribute named animations. Wraps CustomAnimationRegistry.

```ts
interface AnimationCapability
```

**Members**

- `register(definition: CustomAnimationDefinition): Disposer`
- `has(name: string): boolean`
- `list(): CustomAnimationDefinition[]`

### `CanvasTool`

A canvas tool. `hitTest` is the claim: return true on pointerdown and this
tool OWNS the whole gesture (move/up/cancel) — no other tool, and none of the
built-in ladder, will see it.

```ts
interface CanvasTool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `ToolId` |  |  |
| `priority?` | `number` |  | Higher wins when several tools claim the same gesture. Built-in-replacing tools should use a priority > 0; the built-in ladder is effectively 0. |

**Members**

- `hitTest(event: ToolPointerEvent, hit: ToolHitContext): boolean` — Claim this gesture?
- `onPointerDown?(event: ToolPointerEvent, hit: ToolHitContext): void`
- `onPointerMove?(event: ToolPointerEvent, hit: ToolHitContext): void`
- `onPointerUp?(event: ToolPointerEvent, hit: ToolHitContext): void`
- `onCancel?(): void`
- `dispose?(): void` — Called when the tool is unregistered while active.

### `ConnectionCandidate`

Everything a validator needs to judge a proposed connection.

```ts
interface ConnectionCandidate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sourceNode` | `NodeModel` |  |  |
| `sourcePort` | `PortModel \| null` |  |  |
| `targetNode` | `NodeModel` |  |  |
| `targetPort` | `PortModel \| null` |  |  |
| `link?` | `LinkModel` |  | Present when RECONNECTING an existing link rather than drawing a new one. |

### `ConnectionPointContext`

```ts
interface ConnectionPointContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  |  |
| `source` | `LinkEnd` |  |  |
| `target` | `LinkEnd` |  |  |
| `defaults` | `ConnectionPointResult` |  | What the default port-based pipeline would have produced for both ends. |

**Members**

- `boundaryPoint(node: NodeModel, rect: ExtRect, side: ExtSide, cross: number): ExtPoint` — The shape registry's boundary solver, handed in so a strategy can attach to
a node's REAL silhouette (a diamond's slanted face, a custom path shape)
without importing the shape registry itself.
- `nearestVisiblePort(node: NodeModel, side: ExtSide, near: ExtPoint): ExtPoint | null` — The nearest VISIBLE port on a side, or null. Strategies use it to honour the
rule that visible ports win over free-floating attachment.
- `nearestPort(node: NodeModel, side: ExtSide, near: ExtPoint): ExtPoint | null` — The nearest port on a side REGARDLESS of visibility, or null. The
'port-facing' default uses it: a node's ports are its connection anatomy
whether or not the glyphs are currently drawn, so attachment must not
change when visibility does (an endpoint that jumps when you hover a node
is worse than either behaviour it jumps between).

### `ConnectionPointResult`

```ts
interface ConnectionPointResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `ExtPoint` |  |  |
| `end` | `ExtPoint` |  |  |
| `sourceDirection?` | `ExtSide` |  |  |
| `targetDirection?` | `ExtSide` |  |  |

### `ConnectionValidity`

```ts
interface ConnectionValidity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `valid` | `boolean` |  |  |
| `reason?` | `string` |  | The first veto's reason, when it gave one. |

### `ConnectorContext`

```ts
interface ConnectorContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `ExtPoint[]` |  | The routed polyline in world coordinates. Never empty; never length 1. |
| `link?` | `LinkModel` |  | The link being drawn. Optional because a few internal call sites (the connection PREVIEW, which has no LinkModel yet) also build paths. |
| `style?` | `Partial<LinkStyle>` |  |  |
| `cornerRadius` | `number` |  | The corner radius the renderer resolved for this link. |

### `DiagramApi`

```ts
interface DiagramApi
```

**Members**

- `getNodes(): NodeModel[]`
- `getEdges(): LinkModel[]`
- `getSelectedNodes(): NodeModel[]`
- `getSelectedEdges(): LinkModel[]`
- `getViewport(): Rectangle`
- `getZoom(): number`
- `getSnapshot(): DiagramSnapshot` — One consistent snapshot — never a torn read across two getters.
- `subscribe<T>(selector: Selector<T>, listener: (value: T) => void): Disposer` — Observe a projection of the state. The listener fires only when the
SELECTED value changes, not on every internal event.
- `fitView(padding?: number): void` — Frame all content.
- `zoomTo(zoom: number): void` — Set absolute zoom, about the viewport centre.
- `zoomIn(step?: number): void`
- `zoomOut(step?: number): void`
- `centerOn(point: FlowPoint): void` — Pan so `point` sits at the centre of the viewport.
- `screenToFlow(point: FlowPoint): FlowPoint` — Screen (client) coordinates → world/flow coordinates.
- `flowToScreen(point: FlowPoint): FlowPoint` — World/flow coordinates → screen (client) coordinates.
- `getIntersectingNodes(rect: Rectangle, options?: GetIntersectingOptions): NodeModel[]` — Every node overlapping `rect` (world coords). The marquee/drop-target primitive.
- `getNodeAt(point: FlowPoint): NodeModel | null` — The topmost node under a world point, or null.
- `execute(command: unknown): Promise<void>` — Run an engine command through the undo/redo stack. Async — see the impl.
- `undo(): Promise<void>`
- `redo(): Promise<void>`
- `dispose(): void`

### `DiagramSnapshot`

The reactive snapshot a host binds to.

```ts
interface DiagramSnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `NodeModel[]` |  |  |
| `edges` | `LinkModel[]` |  |  |
| `selectedNodes` | `NodeModel[]` |  |  |
| `selectedEdges` | `LinkModel[]` |  |  |
| `viewport` | `Rectangle` |  |  |
| `zoom` | `number` |  |  |

### `Disposable`

Something that can be torn down.

```ts
interface Disposable
```

**Members**

- `dispose(): void`

### `Extension`

An extension. `activate` receives ONLY the capabilities its manifest declared.

```ts
const starPlugin: Extension<'shapes'> = {
  manifest: {
    id: 'acme.stars',
    version: '1.2.0',
    engines: { grafloria: '^1.0.0' },
    capabilities: ['shapes'],
  },
  activate({ capabilities }) {
    // `capabilities.routers` does not exist here — not typed, not present.
    capabilities.shapes.registerPath('star', starPath);
  },
};
host.register(starPlugin);
```

```ts
interface Extension<C extends CapabilityName = CapabilityName>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `manifest` | `ExtensionManifest<C>` |  |  |

**Members**

- `activate(context: ExtensionContext<C>): void | Disposer | Promise<void | Disposer>` — Set up. Anything you register is tracked and undone on dispose; you may also
return a disposer (or push onto `context.onDispose`) for your own resources.
- `deactivate?(): void` — Optional explicit teardown, run before the tracked disposers.

### `ExtensionCapabilities`

The full capability set. An extension's `activate()` receives a PARTIAL of
this — exactly the keys its manifest declared.

```ts
interface ExtensionCapabilities
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shapes` | `ShapeCapability` |  |  |
| `links` | `LinkCapability` |  |  |
| `routers` | `RouterCapability` |  |  |
| `templates` | `TemplateCapability` |  |  |
| `animations` | `AnimationCapability` |  |  |
| `tools` | `ToolCapability` |  |  |
| `panels` | `PanelCapability` |  |  |

### `ExtensionContext`

What an extension is given at activation, beyond its capabilities: a scoped
logger, its own resolved manifest, and a disposal bag.

```ts
interface ExtensionContext<C extends CapabilityName = CapabilityName>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `capabilities` | `Pick<ExtensionCapabilities, C>` |  | Only the capabilities the manifest declared. |
| `id` | `string` |  | The extension's own id. |

**Members**

- `onDispose(disposer: Disposer): void` — Anything pushed here is disposed with the extension. Use it for your own
timers/listeners; registry registrations are tracked automatically.

### `ExtensionContributions`

What a plugin says it adds. Discovery/UX only — not a security boundary.

```ts
interface ExtensionContributions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shapes?` | `string[]` |  |  |
| `routers?` | `string[]` |  |  |
| `connectors?` | `string[]` |  |  |
| `anchors?` | `string[]` |  |  |
| `connectionPoints?` | `string[]` |  |  |
| `markers?` | `string[]` |  |  |
| `linkTemplates?` | `string[]` |  |  |
| `labelTemplates?` | `string[]` |  |  |
| `tools?` | `string[]` |  |  |
| `panels?` | `string[]` |  |  |
| `animations?` | `string[]` |  |  |
| `templates?` | `string[]` |  |  |

### `ExtensionHostOptions`

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

```ts
interface ExtensionHostOptions extends HostBindings
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `apiVersion?` | `string` |  | Reject manifests whose `engines.grafloria` range excludes this. |

### `ExtensionManifest`

```ts
interface ExtensionManifest<C extends CapabilityName = CapabilityName>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Reverse-DNS recommended: `acme.flowchart-shapes`. Must be unique per host. |
| `version` | `string` |  | The plugin's own semver. |
| `name?` | `string` |  | Human-facing. |
| `description?` | `string` |  |  |
| `engines?` | `{ grafloria?: string }` |  | The host API range this plugin supports, e.g. `{ grafloria: '^1.0.0' }`. Checked against `EXTENSION_API_VERSION` and REJECTED on mismatch. |
| `capabilities` | `readonly C[]` |  | The ENFORCED privilege grant. `activate()` receives exactly these and nothing else. |
| `contributes?` | `ExtensionContributions` |  | Declarative inventory, for discovery before load. |

### `ExtPoint`

```ts
interface ExtPoint
```

**Properties**

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

### `ExtRect`

A node's world-space box.

```ts
interface ExtRect
```

**Properties**

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

### `FlowPoint`

```ts
interface FlowPoint
```

**Properties**

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

### `GetIntersectingOptions`

```ts
interface GetIntersectingOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fully?` | `boolean` |  | Require FULL containment rather than any overlap. This is the difference between a marquee that grabs everything it touches and one that only grabs what it encloses — both are legitimate, so it is the caller's call. |
| `visibleOnly?` | `boolean` |  | Ignore hidden nodes. Default true. |

### `HostBindings`

The host's own view of the world. Passed to the capability factories so they
can reach the real registries. NOT exposed to extensions.

```ts
interface HostBindings
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` | `DiagramEngine` |  |  |
| `registry?` | `import('./diagram-registry').DiagramRegistry` |  | The registry every contribution is written into. Pass `diagram.registry` and this host's extensions contribute to THAT DIAGRAM ONLY. |
| `templateRegistry?` | `TemplateRegistry` |  | The engine's node-template registry. |
| `root?` | `HTMLElement` |  | The diagram root element — panels attach here. May be absent (headless). |
| `htmlLayer?` | `HTMLElement` |  | The camera-transformed HTML layer — world-space panels attach here. |
| `viewport?` | `import('../viewport/viewport-controller').ViewportController` |  | The camera, for counter-scaled panels. |
| `requestRender?` | `() => void` |  | Ask the host to repaint (a contributed shape/connector changes the picture). |

### `LinkCapability`

Contribute link visuals + the four link-pipeline stages.

```ts
interface LinkCapability
```

**Members**

- `registerTemplate(name: string, template: LinkTemplate): Disposer` — Whole-link VNode template (`link.style.template`).
- `registerLabelTemplate(name: string, template: LabelTemplate): Disposer` — Label VNode template (`label.template`).
- `registerMarker(name: string, definition: MarkerDefinition): Disposer` — Arrowhead / marker (`arrowHead.type`).
- `registerConnector(name: string, connector: ConnectorFn): Disposer` — Polyline → SVG path `d` (`link.connector`).
- `registerAnchor(name: string, anchor: AnchorFn): Disposer` — Per-end attachment point (`link.metadata.sourceAnchor` / `targetAnchor`).
- `registerConnectionPoint(name: string, strategy: ConnectionPointFn): Disposer` — Whole-link, two-ended attachment strategy (`link.metadata.connectionPoint`).
- `listConnectors(): string[]`
- `listAnchors(): string[]`
- `listConnectionPoints(): string[]`

### `LinkEnd`

One end of a link, as the strategies see it.

```ts
interface LinkEnd
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node` | `NodeModel` |  |  |
| `port` | `PortModel \| null` |  | The assigned port, when the link has one. |
| `rect` | `ExtRect` |  | The node's world rect. |

### `NodeComponent`

```ts
interface NodeComponent<D = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `NodeRenderFn<D>` |  |  |
| `onUpdate?` | `(props: NodeComponentProps<D>, element: HTMLElement) => void` |  | Called on every prop change AFTER the first render. Optional fast path. |
| `onDestroy?` | `(element: HTMLElement) => void` |  | Unmount your framework's subtree here. |
| `autoSize?` | `boolean` |  | Measure the rendered element and write the size back into the model, so layout + routing see the node's REAL extent. Default false — a node whose size is authored should not be silently overridden by its content. |
| `sizeThreshold?` | `number` |  | Ignore measurement deltas smaller than this (px). Default 1. |

### `NodeComponentProps`

The typed props a node component receives. Recomputed on every update.

```ts
interface NodeComponentProps<D = Record<string, unknown>>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `data` | `D` |  | The node's own data bag (`node.data` / metadata). |
| `selected` | `boolean` |  |  |
| `dragging` | `boolean` |  |  |
| `hovered` | `boolean` |  |  |
| `zoom` | `number` |  | Current camera zoom — for LOD rendering ("hide the detail below 0.5"). |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `ports` | `ReadonlyArray<{ id: string; side: string; type: string }>` |  | The node's ports, so a component can position its own handles. |
| `node` | `NodeModel` |  | Escape hatch: the live model. Prefer the fields above. |

### `PanelCapability`

Contribute on-canvas UI. This is the ONLY capability that hands back
a DOM element, and it is scoped to the diagram's own layers — an extension
cannot reach the rest of the page through it.

```ts
interface PanelCapability
```

**Members**

- `createPanel(options?: PortalOptions): Portal` — A floating panel pinned to the viewport (does not pan/zoom).
- `createViewportPanel(options?: { x?: number; y?: number; className?: string; style?: string }): ViewportPortal` — Content that lives IN the diagram (pans/zooms with the canvas).
- `createCounterScaledPanel(options?: { x?: number; y?: number; className?: string; style?: string }): ViewportPortal` — World-space, but held at a constant on-screen size.

### `Portal`

```ts
interface Portal
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `element` | `HTMLElement` |  | The element you render into. Already in the DOM. |

**Members**

- `update(options?: PortalOptions): void` — Re-pin (after changing placement/offset).
- `dispose(): void`

### `PortalOptions`

```ts
interface PortalOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement?` | `PortalPlacement` |  | Where to pin it. Default `'top-left'`. |
| `offset?` | `number` |  | Offset from the placement corner, in CSS px. Default 12. |
| `className?` | `string` |  | Extra class names on the portal element. |
| `style?` | `string` |  | Inline style appended after the placement rules (so it wins). |
| `zIndex?` | `number` |  | Stacking order within the screen layer. |

### `RegisteredExtension`

```ts
interface RegisteredExtension
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `manifest` | `ExtensionManifest` |  |  |
| `active` | `boolean` |  |  |
| `registrationCount` | `number` |  | Registrations this extension currently holds. |

### `RouterCapability`

Contribute routing algorithms. Wraps `RoutingEngine.registerRouter`.

```ts
interface RouterCapability
```

**Members**

- `register(name: string, router: IRouter): Disposer`
- `list(): string[]`
- `has(name: string): boolean`

### `ShapeCapability`

Contribute node geometry. Wraps the (already unified) shape registry.

```ts
interface ShapeCapability
```

**Members**

- `register(type: string, definition: Omit<ShapeDefinition, 'type'> & { type?: string }): Disposer` — Register a full shape definition.
- `registerPath(type: string, geometry: PathGeometry, options?: PathShapeOptions): Disposer` — Register a shape from an SVG path (boundary + port anchors auto-derived).
- `has(type: string): boolean`
- `list(): string[]`

### `TemplateCapability`

Contribute reusable node templates. Wraps the engine's TemplateRegistry.

```ts
interface TemplateCapability
```

**Members**

- `register(template: NodeTemplate): Disposer`
- `list(): NodeTemplate[]`
- `has(id: string): boolean`

<!-- source: grafloria-renderer-ext-interfaces-t-v.md -->

# Interfaces T–V

Import these from `@grafloria/renderer`.

## Interfaces

### `ToolCapability`

Contribute interaction tools + connection validation.

```ts
interface ToolCapability
```

**Members**

- `register(tool: CanvasTool): Disposer` — Register (or REPLACE, by name) a canvas tool. Replacing `'node-drag'` with
your own is the point: the built-ins are registrations, not privileged code.
- `registerConnectionValidator(validator: ConnectionValidator): Disposer` — Veto connections. All registered validators must pass.
- `list(): string[]`
- `has(id: string): boolean`

### `ToolHitContext`

What the gesture landed on, resolved once on pointerdown.

```ts
interface ToolHitContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node?` | `NodeModel` |  |  |
| `link?` | `LinkModel` |  |  |
| `port?` | `PortModel` |  |  |
| `empty` | `boolean` |  | True when the pointer went down on empty canvas. |
| `nodeWasSelected?` | `boolean` |  | Was the hit node already selected BEFORE this gesture? (DELIBERATE mode). |

### `ToolModifiers`

```ts
interface ToolModifiers
```

**Properties**

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

### `ToolPointerEvent`

A pointer gesture event, in both coordinate spaces.

```ts
interface ToolPointerEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'down' \| 'move' \| 'up' \| 'cancel'` |  |  |
| `world` | `{ x: number; y: number }` |  | World-space (camera applied). |
| `screen` | `{ x: number; y: number }` |  | Element-local CSS px — the drag threshold is measured here. |
| `modifiers` | `ToolModifiers` |  |  |
| `source?` | `PointerEvent \| MouseEvent` |  | The original DOM event, when there was one. |

### `ViewportPortal`

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

```ts
interface ViewportPortal extends Portal
```

**Members**

- `setPosition(x: number, y: number): void` — Move the portal's world-space origin.

<!-- source: grafloria-renderer-ext-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `AnchorFn`

```ts
type AnchorFn = (ctx: AnchorContext) => AnchorResult;
```

### `BuiltinToolId`

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

The built-in gesture tools, by name. A registration may REPLACE any of them.

```ts
type BuiltinToolId = 'select' | 'node-drag' | 'link-draw' | 'marquee' | 'pan';
```

### `CapabilityName`

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

The names an extension may request. Mirrors the keys of {@link ExtensionCapabilities}.

```ts
type CapabilityName =
  | 'shapes'
  | 'links'
  | 'routers'
  | 'templates'
  | 'animations'
  | 'tools'
  | 'panels';
```

### `ConnectionPointFn`

Return `null` to decline and fall through to the default pipeline.

```ts
type ConnectionPointFn = (ctx: ConnectionPointContext) => ConnectionPointResult | null;
```

### `ConnectionValidator`

Return false (or a reason string) to veto.

```ts
type ConnectionValidator = (candidate: ConnectionCandidate) => boolean | string;
```

### `ConnectorFn`

Must return a complete SVG path `d`.

```ts
type ConnectorFn = (ctx: ConnectorContext) => string;
```

### `Disposer`

The universal teardown handle. Idempotent by contract.

```ts
type Disposer = () => void;
```

### `ExtSide`

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

```ts
type ExtSide = 'left' | 'right' | 'top' | 'bottom';
```

### `LazyExtension`

A lazily-loaded extension: nothing is imported until `activate(id)`.

```ts
type LazyExtension<C extends CapabilityName = CapabilityName> = () => Promise<
  Extension<C> | { default: Extension<C> }
>;
```

### `NodeComponentRegistry`

type → component.

```ts
type NodeComponentRegistry = Record<string, NodeComponent<never>>;
```

### `NodeRenderFn`

A component's render function.

Return a `VNode` to have the renderer patch it (the framework-agnostic path),
or take the `HTMLElement` and own it yourself (the React/Angular/Vue path —
mount a portal into it and return `void`).

```ts
type NodeRenderFn<D = Record<string, unknown>> = (
  props: NodeComponentProps<D>,
  element: HTMLElement
) => VNode | void;
```

### `PortalPlacement`

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

Corner placements for a screen-space portal.

```ts
type PortalPlacement =
  | 'top-left'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-right'
  | 'top-center'
  | 'bottom-center'
  | 'center'

  | 'none';
```

### `Selector`

```ts
type Selector<T> = (snapshot: DiagramSnapshot) => T;
```

### `ToolId`

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

```ts
type ToolId = BuiltinToolId | (string & {});
```

<!-- source: grafloria-renderer-ext-diagramregistry.md -->

# DiagramRegistry

Import it from `@grafloria/renderer`.

The contribution surface. Obtained from a diagram as `diagram.registry`, or as
{@link GLOBAL_DIAGRAM_REGISTRY} for the process-wide one.

```ts
class DiagramRegistry
```

**Methods**

- `constructor(private readonly scope: RegistryScope | null = null)`
- `get isScoped(): boolean` — True when writes here are private to one diagram.
- `registerShape( type: string, definition: Omit<ShapeDefinition, 'type'> & { type?: string } ): Disposer`
- `registerPathShape(type: string, path: PathGeometry, options?: PathShapeOptions): Disposer`
- `unregisterShape(type: string): boolean`
- `hasShape(type: string): boolean`
- `listShapes(): string[]`
- `getShapeDefinition(type: string): ShapeDefinition | undefined`
- `defineStyle(name: string, style: NamedStyle): Disposer`
- `defineStyles(styles: Record<string, NamedStyle>): Disposer`
- `removeStyle(name: string): boolean`
- `clearStyles(): void` — Drop THIS diagram's named styles. The process-global ones are untouched and
become visible again — which is what makes this safe to call from a teardown
that has no idea what else is on the page.
- `getStyle(name: string): NamedStyle | undefined`
- `hasStyle(name: string): boolean`
- `listStyles(): string[]`
- `registerLinkTemplate(name: string, template: LinkTemplate): Disposer`
- `registerLabelTemplate(name: string, template: LabelTemplate): Disposer`
- `registerMarker(name: string, definition: MarkerDefinition): Disposer`
- `getLinkTemplate(name: string): LinkTemplate | undefined`
- `getLabelTemplate(name: string): LabelTemplate | undefined`
- `getMarker(name: string): MarkerDefinition | undefined`
- `hasMarker(name: string): boolean`
- `listLinkTemplates(): string[]`
- `listLabelTemplates(): string[]`
- `listMarkers(): string[]`
- `registerAnchor(name: string, anchor: AnchorFn): Disposer`
- `registerConnectionPoint(name: string, strategy: ConnectionPointFn): Disposer`
- `registerConnector(name: string, connector: ConnectorFn): Disposer`
- `listAnchors(): string[]`
- `listConnectionPoints(): string[]`
- `listConnectors(): string[]`
- `get animations(): CustomAnimationRegistry` — This diagram's own {@link CustomAnimationRegistry}, or the process-global
singleton when unscoped.

Lazy: the constructor appends a `<style>` element to the document, so a
diagram that never contributes an animation must not pay for one.
- `dispose(): void` — Drop every contribution this diagram made. No-op on the global registry.

<!-- source: grafloria-renderer-ext-components.md -->

# Ext — Components

Import these from `@grafloria/renderer`.

## Functions

### `attachCanvasPlugins`

```ts
function attachCanvasPlugins(
  instance: CanvasPluginHost,
  options: CanvasPluginOptions = {}
): CanvasPlugins
```

### `createBackground`

Create the background grid inside `root`, tracking `viewport`.

```ts
function createBackground(
  root: HTMLElement,
  viewport: ViewportController,
  options: BackgroundOptions = {}
): BackgroundHandle
```

### `createControls`

```ts
function createControls(
  root: HTMLElement,
  viewport: ViewportController,
  options: ControlsOptions = {}
): ControlsHandle
```

### `createMiniMap`

```ts
function createMiniMap(
  root: HTMLElement,
  viewport: ViewportController,
  getModel: () => DiagramModel,
  options: MiniMapOptions = {}
): MiniMapHandle
```

## Constants

### `BACKGROUND_LAYER_CLASS`

```ts
const BACKGROUND_LAYER_CLASS: "grafloria-background-layer"
```

## Interfaces

### `BackgroundHandle`

```ts
interface BackgroundHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `element` | `SVGSVGElement` |  |  |

**Members**

- `update(options: Partial<BackgroundOptions>): void` — Change any option; re-renders immediately.
- `setVisible(visible: boolean): void` — Show/hide without tearing down (this is what `gridEnabled` drives).
- `isVisible(): boolean`
- `dispose(): void`

### `BackgroundOptions`

```ts
interface BackgroundOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `BackgroundVariant` |  | Pattern style. Default `'dots'`. |
| `gap?` | `number` |  | Grid spacing in WORLD units. Default 20. |
| `size?` | `number` |  | Dot radius / line thickness in CSS px. Default 1 (dots) or 1 (lines). |
| `color?` | `string` |  | Pattern colour. Default a theme-neutral grey. |
| `backgroundColor?` | `string` |  | Page colour painted under the pattern. Default transparent. |
| `majorEvery?` | `number` |  | Draw a heavier line every N cells (graph-paper look). 0 = off (default). Only meaningful for `'lines'` / `'cross'`. |
| `majorColor?` | `string` |  | Colour of the major lines. Defaults to `color` at higher opacity. |
| `minZoom?` | `number` |  | Hide the grid below this zoom, so it does not turn into visual mud when you zoom way out. Default 0.25. Set 0 to always draw. |
| `idSuffix?` | `string` |  | Unique-ish suffix for the pattern id, when several diagrams share a page. |

### `CanvasPluginHost`

The structural surface the plugins actually need. `DiagramInstance`
satisfies it; so does any framework canvas that keeps a live
`ViewportController` (the Angular wrapper builds exactly this adapter).

```ts
interface CanvasPluginHost
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |
| `viewport` | `DiagramInstance['viewport']` |  |  |

**Members**

- `getModel(): DiagramModel`
- `getEngine(): DiagramEngine`
- `fitView(padding?: number): void`

### `CanvasPluginOptions`

```ts
interface CanvasPluginOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `boolean \| BackgroundOptions` |  | Background grid. `true` = defaults; an object = options; omitted/false = off. When the engine's `gridEnabled` flag is present it OVERRIDES visibility. |
| `minimap?` | `boolean \| MiniMapOptions` |  | MiniMap. Visibility is additionally gated by the store's `showMinimap`. |
| `controls?` | `boolean \| ControlsOptions` |  | Zoom/fit/lock toolbar. |
| `bindToStore?` | `boolean` |  | Honour `DiagramStore.gridEnabled` / `showMinimap` and keep them in sync. Default true — this is what makes the flags real. Turn it off if you want the component visibility to be purely declarative. |

### `CanvasPlugins`

```ts
interface CanvasPlugins
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background?` | `BackgroundHandle` |  |  |
| `minimap?` | `MiniMapHandle` |  |  |
| `controls?` | `ControlsHandle` |  |  |
| `dispose` | `Disposer` |  |  |

### `ControlsHandle`

```ts
interface ControlsHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `portal` | `Portal` |  |  |
| `element` | `HTMLElement` |  |  |

**Members**

- `setVisible(visible: boolean): void`
- `isVisible(): boolean`
- `setLocked(locked: boolean): void` — Reflect a lock state changed elsewhere (keeps `aria-pressed` honest).
- `dispose(): void`

### `ControlsOptions`

```ts
interface ControlsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement?` | `PortalPlacement` |  |  |
| `offset?` | `number` |  |  |
| `showZoom?` | `boolean` |  | Which buttons to show. Default: all except lock. |
| `showFitView?` | `boolean` |  |  |
| `showLock?` | `boolean` |  |  |
| `orientation?` | `'vertical' \| 'horizontal'` |  | Lay the buttons out horizontally instead of vertically. |
| `zoomStep?` | `number` |  | Zoom step per click (multiplicative). Default 1.2. |
| `onFitView?` | `() => void` |  | Called when "fit view" is pressed. Wire this to `instance.fitView()`. |
| `onToggleLock?` | `(locked: boolean) => void` |  | Called when the lock is toggled. Return/ignore as you like. |
| `locked?` | `boolean` |  | Initial lock state. |

### `MiniMapHandle`

```ts
interface MiniMapHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `portal` | `Portal` |  |  |
| `element` | `SVGSVGElement` |  |  |

**Members**

- `refresh(): void` — Rebuild the node layer (call when the model changed).
- `setVisible(visible: boolean): void`
- `isVisible(): boolean`
- `update(options: Partial<MiniMapOptions>): void`
- `dispose(): void`

### `MiniMapOptions`

```ts
interface MiniMapOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement?` | `PortalPlacement` |  |  |
| `offset?` | `number` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `padding?` | `number` |  | Padding (world units) around the content in the minimap's viewBox. |
| `nodeColor?` | `string \| ((node: NodeModel) => string)` |  | Node fill. A function lets you colour-code by type/state. |
| `maskColor?` | `string` |  | Fill of the camera rectangle. |
| `maskStroke?` | `string` |  | Stroke of the camera rectangle. |
| `panelBackground?` | `string` |  |  |
| `panelBorder?` | `string` |  |  |
| `interactive?` | `boolean` |  | Allow click/drag-to-pan and wheel-to-zoom. Default true. |
| `showLinks?` | `boolean` |  | Draw links too. Default false (nodes carry the shape of a diagram). |
| `linkColor?` | `string` |  |  |
| `ariaLabel?` | `string` |  | ARIA label on the panel. |

## Types

### `BackgroundVariant`

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

```ts
type BackgroundVariant = 'dots' | 'lines' | 'cross' | 'none';
```

<!-- source: grafloria-renderer-instance.md -->

# Instance

Import these from `@grafloria/renderer`.

## On their own pages

- [`CreateDiagramOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-creatediagramoptions)
- [`DiagramInstance`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-diagraminstance)
- [`EdgeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-edgespec): An edge, as a host hands it in. Node-to-node, like React Flow.
- [`NodeSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-nodespec)
- [`PortSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-instance-portspec): A port on a node. Omit `id` to get the deterministic `<nodeId>__<side>` name.

## Functions

### `applyEdges`

Reconcile the diagram's links against `specs`. See {@link applyNodes}.

```ts
function applyEdges(diagram: DiagramModel, specs: Array<EdgeSpec | LinkModel>): boolean
```

### `applyEdgeSpec`

Apply the mutable parts of an edge spec onto an existing link.

```ts
function applyEdgeSpec(link: LinkModel, spec: EdgeSpec): void
```

### `applyGroups`

Reconcile the diagram's groups against `specs` — add, update, remove — the
way {@link applyNodes} does for nodes. A live `GroupModel` passes through (a
Mermaid subgraph arrives that way). Removing a group never removes its boxes.

```ts
function applyGroups(diagram: DiagramModel, specs: Array<GroupSpec | GroupModel>): boolean
```

**Returns** whether anything changed.

### `applyNodes`

Reconcile the diagram's nodes against `specs`: add what is new, update what
moved, remove what disappeared. Live `NodeModel`s pass through untouched, so a
host can mix "give me the data" with "here is my own model".

```ts
function applyNodes(diagram: DiagramModel, specs: Array<NodeSpec | NodeModel>): boolean
```

**Returns** whether anything changed (i.e. whether a repaint is warranted).

### `applyNodeSpec`

Apply the mutable parts of a spec onto an existing node (the update path).

```ts
function applyNodeSpec(node: NodeModel, spec: NodeSpec): void
```

### `buildEdge`

Build a fresh `LinkModel` from a spec. Returns null when an endpoint is unresolvable.

```ts
function buildEdge(
  diagram: DiagramModel,
  spec: EdgeSpec,
  index: number
): LinkModel | null
```

### `buildNode`

Build a fresh `NodeModel` from a spec, with deterministic ports.

```ts
function buildNode(spec: NodeSpec, index: number): NodeModel
```

### `buildPort`

The gating spec is flattened onto the model's individual fields because that
is the shape `resolvePortConfig()` reads; `PortSpec.gating` is only the
ergonomic grouping of them.

A port with no explicit `side` and no `group` still lands on `right` (the
`PortModel` default) — but a port that names a group and no side is now built
WITHOUT `side`, so `explicitSide` stays false and the group's side is
inherited, which is the entire reason that flag exists.

```ts
function buildPort(nodeId: string, spec: PortSpec, index: number): PortModel
```

### `contentBounds`

World bounding box of every visible node, or null when there is nothing to fit.

```ts
function contentBounds(model: DiagramModel): Rectangle | null
```

### `createDiagram`

```ts
function createDiagram(
  container: HTMLElement,
  options: CreateDiagramOptions = {}
): DiagramInstance
```

### `defaultPortId`

The deterministic id of a node's default port on `side`.

```ts
function defaultPortId(nodeId: string, side: (typeof PORT_SIDES)[number]): string
```

### `edgeSpecId`

Stable id for the nth edge of a spec list.

```ts
function edgeSpecId(spec: EdgeSpec, index: number): string
```

### `htmlLayerStyle`

The HTML layer's style for a given camera transform (see ViewportController).

```ts
function htmlLayerStyle(transform: string): string
```

### `isGroupModel`

True for a live `GroupModel`.

```ts
function isGroupModel(value: unknown): value is GroupModel
```

### `isLinkModel`

True for a live `LinkModel`.

```ts
function isLinkModel(value: unknown): value is LinkModel
```

### `isNodeModel`

True for a live `NodeModel` (vs a plain spec object).

```ts
function isNodeModel(value: unknown): value is NodeModel
```

### `nodeHostStyle`

The style of one custom node's host element inside the HTML layer.

```ts
function nodeHostStyle(
  x: number,
  y: number,
  width: number,
  height: number
): string
```

### `nodeSpecId`

Stable id for the nth node of a spec list.

```ts
function nodeSpecId(spec: NodeSpec, index: number): string
```

### `resolvePortId`

Resolve an edge endpoint to a PORT id. Accepts (in order): an explicit port id, a side name, or the node's default
port for `fallbackSide`. Returns undefined when the node does not exist.

```ts
function resolvePortId(
  diagram: DiagramModel,
  nodeOrPortId: string,
  handle: string | undefined,
  fallbackSide: (typeof PORT_SIDES)[number]
): string | undefined
```

### `toEdgeSpec`

Model → spec for a link. See {@link toNodeSpec}.

```ts
function toEdgeSpec(link: LinkModel): EdgeSpec
```

### `toNodeSpec`

Model → spec: the projection a host needs to write model changes BACK into its
own state (a React `useState`, a Vue `ref`, a web-component property). Without
it a wrapper would have to reach into engine models, which is exactly the
coupling these specs exist to avoid.

```ts
function toNodeSpec(node: NodeModel): NodeSpec
```

## Classes

### `DomEventBinder`

```ts
class DomEventBinder
```

**Methods**

- `getDraggingNodeIds(): string[]` — . The nodes currently being DRAGGED (past the movement
threshold — an armed-but-uncommitted press is a click, not a drag).

Node-drag state lives here, not on the InteractionController, so a custom
node component had no way to know it was being dragged — and `dragging` is
one of the props the component contract promises. This is the read-only
window onto it.
- `hasActiveGesture(): boolean` — True while a resize / rotate / vertex gesture owns the pointer.

The companion to {@link getDraggingNodeIds} for the gestures that are NOT node drags. Custom-node culling needs it: unmounting a host element mid-resize would take the
pointer capture and the handles with it, and `SelectionToolsController` keeps the
gesture's own node private, so "is a gesture live" plus the current selection is the
answer available from out here.
- `constructor( private readonly container: HTMLElement, private readonly host: DomEventBinderHost, options: DomEventBinderOptions = {} )`
- `attach(): void` — Bind DOM listeners. No-op on the server and no-op if already attached.
- `detach(): void` — Remove EXACTLY the listeners we added, and drop all gesture state.
- `get isAttached(): boolean`
- `onWheel(event: WheelEvent): void`
- `onMouseDown(event: MouseEvent): void`
- `onMouseMove(event: MouseEvent): void`
- `onMouseUp(event: MouseEvent): void`
- `onMouseLeave(): void` — Pointer left the canvas — abort every in-flight gesture so nothing sticks.
- `onDoubleClick(event: MouseEvent): void` — Double-click: node → in-place rename; link label → rename; link body → waypoint.
- `onKeyDown(event: KeyboardEvent): void`
- `onKeyUp(event: KeyboardEvent): void`
- `beginLabelEdit(target: TextEditTarget, options?: { seed?: string }): boolean` — Open the in-place label editor programmatically — the seam behind F2 and a
host's context-menu Rename. Unlike the double-click path this is NOT gated
on `enableInPlaceTextEdit`: an explicit call IS the host's opt-in. Returns false when the target does not exist / is not editable / readonly.

### `RenderScheduler`

```ts
class RenderScheduler
```

**Methods**

- `constructor(options: RenderSchedulerOptions)`
- `get stats(): Readonly<RenderSchedulerStats>`
- `get pending(): boolean` — True while a frame is queued but has not run yet.
- `schedule(): void` — Mark dirty and queue a frame. Idempotent within a tick — the second and
later calls before the frame runs are counted as `coalesced`, not queued.
- `flush(): void` — Paint NOW, bypassing rAF and the idle-skip check, and cancel any queued
frame. This is the mount paint (and the "give me a correct DOM before I
measure it" escape hatch).
- `cancel(): void` — Drop a queued frame without painting.
- `dispose(): void`

## Constants

### `HTML_LAYER_CLASS`

```ts
const HTML_LAYER_CLASS: "grafloria-html-layer"
```

### `INSTANCE_ATTR`

`data-grafloria-instance` — the renderer's CSS scope, mirrored onto the root.

```ts
const INSTANCE_ATTR: "data-grafloria-instance"
```

### `PORT_SIDES`

```ts
const PORT_SIDES: readonly ["top", "right", "bottom", "left"]
```

### `ROOT_CLASS`

The DOM skeleton of a mounted diagram — ONE definition, used by both halves.

The server (`renderToStaticSVG`) emits this markup as a string; the client
(`createDiagram`) builds the identical structure with `createElement`, or
ADOPTS the server's when hydrating. Any divergence between the two — a class
name, a style declaration, an attribute — is a hydration mismatch, so both
paths read the constants from here rather than each spelling them out.

<div class="grafloria-diagram-root" data-grafloria-instance="grafloria-1">
    <div class="grafloria-svg-layer">   <svg …/>  </div>   ← the deterministic part
    <div class="grafloria-html-layer">  …custom nodes…  </div>  ← client-only
  </div>

The HTML layer holds nodes that render as framework components (React
portals, slotted templates). It carries the camera as a CSS transform so it
stays registered with the SVG layer, and is `pointer-events: none` so it does
not eat clicks meant for the SVG underneath — each mounted node host turns
pointer events back on for itself.

```ts
const ROOT_CLASS: "grafloria-diagram-root"
```

### `ROOT_STYLE`

```ts
const ROOT_STYLE: "position:relative;width:100%;height:100%;overflow:hidden"
```

### `SVG_LAYER_CLASS`

```ts
const SVG_LAYER_CLASS: "grafloria-svg-layer"
```

### `SVG_LAYER_STYLE`

```ts
const SVG_LAYER_STYLE: "position:absolute;top:0;left:0;width:100%;height:100%"
```

## Interfaces

### `DiagramEventMap`

```ts
interface DiagramEventMap
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `'nodes:change'` | `{ nodes: NodeModel[] }` |  |  |
| `'edges:change'` | `{ edges: LinkModel[] }` |  |  |
| `'selection:change'` | `{ nodes: NodeModel[]; edges: LinkModel[] }` |  |  |
| `connect` | `{ link: LinkModel }` |  |  |
| `reconnect` | `{ link: LinkModel; endpoint: 'source' \| 'target' }` |  |  |
| `'node:click'` | `{ node: NodeModel; world: { x: number; y: number } }` |  |  |
| `'node:doubleclick'` | `{ node: NodeModel; world: { x: number; y: number } }` |  |  |
| `'edge:click'` | `{ edge: LinkModel; world: { x: number; y: number } }` |  |  |
| `'viewport:change'` | `{ viewport: Rectangle; zoom: number }` |  |  |
| `ready` | `void` |  |  |
| `'nodes:change'` | `{ nodes: NodeModel[] }` |  |  |
| `'edges:change'` | `{ edges: LinkModel[] }` |  |  |
| `'selection:change'` | `{ nodes: NodeModel[]; edges: LinkModel[] }` |  |  |
| `'node:click'` | `{ node: NodeModel; world: { x: number; y: number } }` |  |  |
| `'node:doubleclick'` | `{ node: NodeModel; world: { x: number; y: number } }` |  |  |
| `'edge:click'` | `{ edge: LinkModel; world: { x: number; y: number } }` |  |  |
| `'viewport:change'` | `{ viewport: Rectangle; zoom: number }` |  |  |

### `DomEventBinderHost`

Everything the binder needs from its host. Keeps this class DI-free.

```ts
interface DomEventBinderHost
```

**Properties**

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

**Members**

- `getEngine(): DiagramEngine | null` — The engine, or null before a diagram is attached.
- `getRect(): CanvasRect` — The canvas' client rect (for screen→world).
- `requestRender(): void` — "Something visible changed" — the host coalesces this into a frame.
- `emit(event: string, payload: unknown): void` — Emit a public diagram event (`node:click`, `connect`, …).

### `DomEventBinderOptions`

```ts
interface DomEventBinderOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enablePan?` | `boolean` |  | Middle-drag / space-drag / wheel-scroll panning. Default true. |
| `enableZoom?` | `boolean` |  | Ctrl/⌘ + wheel zoom. Default true. |
| `zoomSensitivity?` | `number` |  | Relative zoom step per wheel notch. Default 0.1 (a notch is ×1.1). |
| `dragThreshold?` | `number` |  | CSS px the pointer must travel before a node drag commits. Default 4. |
| `readonly?` | `boolean` |  | Ignore every mutation-causing gesture (still pans/zooms). Default false. |

### `GroupFrameStyle`

A zone's own frame — what makes a group look like the tinted, captioned
regions of the diagrams AI tools draw instead of the theme's titled box. Declaring any of it replaces the theme frame (no title band).

```ts
interface GroupFrameStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `borderRadius?` | `number` |  |  |
| `color?` | `string` |  | Caption colour. |
| `fontSize?` | `number` |  | Caption size in px. Default 11. |
| `fontWeight?` | `string \| number` |  |  |
| `fontFamily?` | `string` |  |  |
| `letterSpacing?` | `number` |  | Caption letter spacing in px. |
| `textTransform?` | `'none' \| 'uppercase' \| 'lowercase' \| 'capitalize'` |  |  |

### `GroupSpec`

A GROUP in the spec — a zone around some boxes. `bounds` pins its frame;
without it the frame is fitted around `children` with `padding`. The children
become the group's members (they travel with it). Stored as a GroupModel whose
`metadata.frameStyle` carries `style` + `labelPlacement`, so it serializes.

```ts
interface GroupSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label?` | `string` |  |  |
| `children?` | `string[]` |  |  |
| `bounds?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `padding?` | `number` |  | Space between the children and the fitted frame. Default 20. |
| `style?` | `GroupFrameStyle` |  |  |
| `labelPlacement?` | `GroupLabelPlacement` |  | Default 'top-left'. |
| `direction?` | `'LR' \| 'RL' \| 'TB' \| 'TD' \| 'BT'` |  | How the zone lays its boxes out under a composing layout: `'LR'` a row, `'TB'` a column. |

### `NodeSublabel`

A node's second line, when it needs its own font or colour. See `NodeSpec.sublabel`.

```ts
interface NodeSublabel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  |  |
| `fontFamily?` | `string` |  | A CSS font stack, or `'mono'` for a monospace one. |
| `fontSize?` | `number` |  | px. Default: 0.85 of the label's size. |
| `color?` | `string` |  | Default: the theme's secondary text colour. |
| `fontWeight?` | `string \| number` |  |  |

### `RenderSchedulerOptions`

RenderScheduler — framework-agnostic rAF coalescing + idle-skip.

Blocker #3 of the headless-instance contract (see ./diagram-instance.ts): the
only render loop in the codebase was `DiagramCanvasComponent.scheduleRender()`,
a private Angular method. This is that logic, lifted verbatim in behaviour and
with no framework or DOM imports, so React / the web component / a plain
`<script>` host all inherit the same frame discipline:

- **Coalescing.** Any number of `schedule()` calls in one tick collapse into
    exactly ONE painted frame. A burst of engine events (`node:changed` ×N, a
    drag's mousemoves, several prop changes in one React commit) paints once.
  - **Idle-skip.** A queued frame is DROPPED when `shouldSkip()` says nothing
    visible can have changed — cheaper than a no-op render of a big diagram.
  - **Synchronous escape.** `flush()` paints right now and cancels the queued
    frame; used for the mount paint (so the first frame is not one rAF late)
    and by tests.

`requestFrame`/`cancelFrame` are injectable: pass fakes in tests, and note the
default falls back to `setTimeout` where rAF is missing (Node), so a scheduler
constructed during SSR never throws — it simply never gets a chance to fire
because nothing calls `schedule()` on the server.

```ts
interface RenderSchedulerOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onFrame` | `() => void` |  | The paint. Called at most once per frame. |
| `shouldSkip?` | `() => boolean` |  | Idle-skip predicate, evaluated INSIDE the frame (not at schedule time, so it sees the final state of the tick). Return true to drop the frame. |
| `requestFrame?` | `(cb: (time: number) => void) => number` |  | Injectable rAF (defaults to the platform one, with a setTimeout fallback). |
| `cancelFrame?` | `(handle: number) => void` |  | Injectable cancel, must pair with `requestFrame`. |

### `RenderSchedulerStats`

Cheap counters — a steady-state idle canvas should paint 0 frames.

```ts
interface RenderSchedulerStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scheduled` | `number` |  | `schedule()` calls. |
| `painted` | `number` |  | Frames actually painted (`onFrame` ran). |
| `skipped` | `number` |  | Queued frames dropped by `shouldSkip()`. |
| `coalesced` | `number` |  | `schedule()` calls that folded into an already-queued frame. |
| `lastFrameMs` | `number` |  | Duration (ms) of the most recent paint. |

## Types

### `CreateDiagram`

The factory's own signature, for hosts that store it.

```ts
type CreateDiagram = typeof import('./create-diagram').createDiagram;
```

### `DiagramEventHandler`

```ts
type DiagramEventHandler<K extends DiagramEventName> = (
  payload: DiagramEventMap[K]
) => void;
```

### `DiagramEventName`

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

```ts
type DiagramEventName = keyof DiagramEventMap;
```

### `EdgeInput`

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

```ts
type EdgeInput = EdgeSpec | LinkModel;
```

### `GroupLabelPlacement`

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

Where a zone's caption sits.

```ts
type GroupLabelPlacement = 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right';
```

### `NodeInput`

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

Nodes/edges may be handed in as plain specs or as live engine models.

```ts
type NodeInput = NodeSpec | NodeModel;
```

<!-- source: grafloria-renderer-instance-creatediagramoptions.md -->

# CreateDiagramOptions

Import it from `@grafloria/renderer`.

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

```ts
interface CreateDiagramOptions extends DomEventBinderOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeInput[]` |  |  |
| `edges?` | `EdgeInput[]` |  |  |
| `groups?` | `Array<GroupSpec \| GroupModel>` |  | Zones: groups around some boxes, each with a frame of its own — fill, border, dash, a caption in a corner (the tinted regions of the diagrams AI tools draw). A live `GroupModel` passes through. See {@link GroupSpec}. |
| `theme?` | `Theme` |  |  |
| `colorMode?` | `ColorMode` |  | Follow the OS colour scheme instead of pinning `theme`. |
| `themes?` | `ThemeSet` |  | The themes `colorMode` switches between. Defaults to `DEFAULT_THEME_SET`. |
| `tokenBridge?` | `TokenBridge` |  | Drive Grafloria's variables from the host's design tokens (shadcn/MUI/Tailwind). |
| `renderer?` | `Omit<SVGRendererConfig, 'instanceId'>` |  | The full renderer config, for every knob the ergonomic fields above do not name: `connectionPoint` / `smartConnectionPoints` (floating edges), `parallelLinks` + `parallelSpacing`, `channelNudging`, `jumpOwnership`, `globalRouting`, `linkHitAreaWidth`. |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Select a node and its lines come forward in the page's ink while every other line fades back; a line of the selection that runs across another node is lifted above the cards and drawn dashed. Off by default; see {@link HighlightConnectedOptions}. Wins over `renderer.highlightConnected`. Switch it live with `setHighlightConnected()`. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | The OUTLINE LAYER Angular's canvas draws: an outline around the hovered node, the selected node, nodes with a validation issue, and the valid targets while a connection is drawn. `true` turns every kind on; an object turns kinds on or off one by one, over the defaults ({@link HighlighterConfig}). Off when unset, so an existing app is unchanged. |
| `layout?` | `'architecture'` |  | Arrange the diagram on mount. `'architecture'` composes it the way AI tools hand-draw one: zones as regions on a grid, boxes sized to their words and aligned in rows, lines straight where boxes line up and bent in the gutters, a node's `near` note beside its target. Positions in the spec are not needed (and are overridden). |
| `zoom?` | `number` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `viewport?` | `{ x: number; y: number }` |  | Camera origin in world coordinates. |
| `engine?` | `DiagramEngine` |  | Attach to an existing engine instead of creating one. |
| `interaction?` | `Record<string, unknown>` |  | Passed through to `new DiagramEngine({ interaction })`. |
| `instanceId?` | `string` |  | Force the renderer's CSS scope (hydration does this for you). |
| `fitView?` | `boolean` |  | Fit the camera to the content on mount. |
| `renderCustomNode?` | `(node: NodeModel, element: HTMLElement) => void \| Promise<void>` |  | Blocker #4: host hook for nodes that render as framework components rather than SVG (`custom: true` / `metadata.useHTMLLayer`). The instance creates and positions an absolutely-placed host element inside the HTML layer and hands it to you; you own what goes inside it. |
| `removeCustomNode?` | `(nodeId: string, element: HTMLElement) => void` |  | Called before a custom node's host element is removed — unmount your component. |
| `cullCustomNodes?` | `boolean \| HostCullOptions` |  | VIEWPORT-CULL the custom-node hosts: keep only the ones near the viewport in the document. `true` for the defaults, or an options object (`margin`, `hysteresis`, `mode` — see {@link HostCullOptions}). |
| `viewLifecycle?` | `ViewLifecycle` |  | Install a {@link ViewLifecycle} — freeze/unfreeze, `autoFreeze`, and the admission set a {@link ProgressiveMounter } drives. |
| `hydrate?` | `HydrationSnapshot` |  | Adopt a server-rendered snapshot instead of mounting fresh. Pass the `snapshot` returned by `renderToStaticSVG()`. The instance rebuilds the identical model, renders the identical VNode tree, and ADOPTS the DOM already in the container — no re-creation, no flash, no re-layout. |
| `comments?` | `boolean \| CommentStore` |  | Anchored comment threads. `true` creates a store (viewer `'local'`); pass a `CommentStore` to share one (collab). Pins render into the VNode tree via the comment overlay; read them back with `getCommentStore()`. |
| `commentsViewer?` | `string` |  | Viewer id for a `comments: true`-created store (default `'local'`). |

<!-- source: grafloria-renderer-instance-diagraminstance.md -->

# DiagramInstance

Import it from `@grafloria/renderer`.

```ts
interface DiagramInstance
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `ViewportController` |  |  |
| `interaction` | `InteractionController` |  |  |
| `animations` | `AnimationService` |  | The renderer's animation service. Host policy lives here: global enable/speed, reduced-motion overrides, and the battery-saver auto-toggle (`updateConfig({ respectBatteryStatus: false })` to opt out — on by default, and on a low unplugged battery it disables edge animations). |
| `registry` | `DiagramRegistry` |  | THIS diagram's contribution registry — shapes, named styles, link/label templates, markers, anchors, connection points, connectors, animations. |
| `container` | `HTMLElement` |  | Escape hatches for hosts and tests. |
| `scheduler` | `RenderScheduler` |  |  |
| `patcher` | `VNodePatcher` |  |  |

**Members**

- `setNodes(nodes: NodeInput[]): void`
- `setEdges(edges: EdgeInput[]): void`
- `setGroups(groups: Array<GroupSpec | GroupModel>): void` — Reconcile the zones (groups) — add, restyle, remove. Removing a zone keeps its boxes.
- `getModel(): DiagramModel`
- `getEngine(): DiagramEngine`
- `getCommentStore(): CommentStore | null` — The comment store, when `comments` was enabled; `null` otherwise.
- `on<K extends DiagramEventName>(event: K, handler: DiagramEventHandler<K>): Unsubscribe`
- `off<K extends DiagramEventName>(event: K, handler: DiagramEventHandler<K>): void`
- `setTheme(theme: Theme): void` — Theme swap (re-injects this instance's CSS variable block only).
- `setColorMode(mode: ColorMode, themes?: ThemeSet): void` — Follow the OS colour scheme (`'system'`), or pin light/dark.

`'system'` also honours `prefers-contrast: more` and forced-colors by
upgrading to the high-contrast theme — an accessibility preference outranks
an aesthetic one.
- `getColorMode(): ColorMode | undefined`
- `setTokenBridge(bridge: TokenBridge | null | undefined): void` — Re-point Grafloria's CSS variables at the host design system's tokens.
- `setHighlightConnected(value: boolean | HighlightConnectedOptions): void` — Turn the selected nodes' line highlight on (`true`, or options) or off
(`false`) — see `CreateDiagramOptions.highlightConnected`. Repaints.
- `setHighlighterConfig(value: boolean | Partial<HighlighterConfig>): void` — Turn the outline layer on (`true`, or an object of kinds) or off (`false`) —
see `CreateDiagramOptions.highlighterConfig`. Repaints.
- `getHighlightConnected(): boolean | HighlightConnectedOptions` — The current `highlightConnected` setting (`false` when off).
- `export(format?: ExportFormat, options?: ExportOptions): Promise<string>` — Export the CURRENT view. `'svg'` returns SVG source; `'png' | 'jpeg' |
'webp' | 'pdf'` return a `data:` URL.

Pass `{ embedModel: true }` (PNG and SVG) and the diagram model rides inside
the artifact — the exported file re-opens as an editable diagram.

THE ASYNC ONE, and the only one. If a custom node's `renderCustomNode` returned a
promise — "I draw later: a rAF, a fetch, a framework's render, a web font" — this
waits for it before reading the host, bounded by
{@link ExportOptions.customNodeTimeout}. The synchronous entry points below cannot,
and say so in their `warnings`. Read the fidelity report through
{@link ExportOptions.onWarnings}, which fires on every format.
- `exportSvgString(options?: ExportOptions): SvgExportResult` — Synchronous, DOM-free, deterministic. Carries `warnings`.

Synchronous means a widget whose painter is still running is captured as it stands
and REPORTED, not waited for — `await export('svg')` is the entry point that waits.
- `exportPdf(options?: ExportOptions): PdfExportResult` — A real vector PDF: paths stay paths, text stays selectable text.
- `getQualityState(): { tier: LODLevel; governor?: GovernorState }` — The LOD tier actually rendered, and the adaptive governor's last verdict.
- `fitView(padding?: number): void` — Frame all content.
- `render(): void` — Queue a repaint (coalesced into one frame).
- `renderNow(): void` — Repaint synchronously — use when you must measure right after a change.
- `batchUpdate(mutate: (model: DiagramModel) => void): void` — Apply many mutations as ONE frame.

```ts
diagram.batchUpdate((model) => {
  for (const n of model.getNodes()) n.setPosition(n.position.x + 10, n.position.y);
});
```

Two distinct things are coalesced, and they are coalesced in two different
places, which is worth being precise about:

- **Events.** `DiagramModel.beginBatch()` QUEUES its change events instead
    of firing them, so a thousand `setPosition()` calls do not walk a
    thousand listener chains on their way to the same rAF.
  - **Frames.** `RenderScheduler` folds every `schedule()` in a tick into one
    rAF callback, so the thousand mutations produce exactly one `render()`
    and one `reconcile()` — one patch, not a thousand.

Nesting is depth-counted (it bottoms out in `DiagramEntity`), so a batch
inside a batch is still one frame. `mutate` throwing does not strand the
model in batch mode.

It never paints synchronously — that is the point. If you need the DOM to be
correct before you measure it, follow with `renderNow()`.
- `exportText(options?: ExportTextOptions): string` — Mermaid-compatible text export (with the lossless sidecar by default) —
feed the result back to `loadText` for a full round-trip.
- `loadText(text: string, options?: ImportTextOptions): ImportTextResult` — Parse Mermaid-compatible text (sidecar-aware) and reconcile it INTO the
live diagram through the same spec reconciler `setNodes`/`setEdges` use —
listeners, plugins, and the renderer all stay attached.
- `dispose(): void`
- `getDraggingNodeIds(): string[]` — The nodes currently being dragged (past the movement
threshold). Custom node components receive this as the `dragging` prop.
- `beginLabelEdit( target: { type: 'node' | 'link-label'; nodeId?: string; linkId?: string; labelIndex?: number }, opts?: { seed?: string } ): boolean` — visio-depth — open the in-place label editor programmatically: a node's
label (`{ type: 'node', nodeId }`) or a link label
(`{ type: 'link-label', linkId, labelIndex }`). The seam a host's
context-menu Rename / F2 binding uses; the same editor + undoable commit
that double-click opens. `seed` replaces the text the editor opens with
(type-to-replace). Returns false when the target is missing, not editable,
or the instance is readonly.

<!-- source: grafloria-renderer-instance-edgespec.md -->

# EdgeSpec

Import it from `@grafloria/renderer`.

An edge, as a host hands it in. Node-to-node, like React Flow.

Both
fields live on `LinkModel`, both round-trip through `serialize()`… and neither
was on `EdgeSpec`. So the A* / manhattan obstacle routers, and every custom
connector, were addressable only by reaching past the spec layer into the live
model. Same for `metadata`, which is how a link names its anchor and its
connection-point strategy (floating edges), and for `points`, which is how a
host restores saved waypoints.

```ts
interface EdgeSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  |  |
| `source` | `string` |  | Source NODE id (a port id also resolves, for full control). |
| `target` | `string` |  | Target NODE id. |
| `sourceHandle?` | `string` |  | Port id, or a bare side name (`'right'`). Naming a handle PINS the edge to that port. When neither handle is named the edge is PORT-FACING: it attaches to the node's real port on whichever side faces its partner (the `'port-facing'` strategy), so a layouted tree connects bottom→top instead of looping out of a frozen right→left pick — and the endpoint always sits on a port, never sliding along the … |
| `targetHandle?` | `string` |  | Port id, a bare side name (`'left'`), or a side AT a point along it: `'left@36'` (36 px down the left side), `'bottom@138'` (138 px from the bottom's left end), `'right@50%'`. See `sourceHandle` for the default. |
| `type?` | `'direct' \| 'smooth' \| 'orthogonal' \| 'bezier'` |  |  |
| `router?` | `LinkRouterName` |  | WHERE the line goes: `straight` \| `orthogonal` \| `manhattan` \| `avoid` \| `elk`, or any router registered on the RoutingEngine. Unset = derived from `type`. |
| `connector?` | `LinkConnectorName` |  | HOW the polyline is drawn: `straight` \| `rounded` \| `smooth` \| `bezier`, or any name passed to `registerConnector`. Unset = derived from `type`. |
| `label?` | `string` |  |  |
| `labelPlacement?` | `'on' \| 'above' \| 'below'` |  | Where the label sits: `'on'` the line on its own little box (the default), or `'above'` / `'below'` it with no box — the labels of the diagrams AI tools draw. Decided against the line's direction where the label lands, so on a vertical run `'above'` means to its left. |
| `labelStyle?` | `LabelStyle` |  | The label's own colour, size, weight, family, background (`'none'` for no box). |
| `waypoints?` | `Point[]` |  | The bends the line must take, in world coordinates — interior points only; its ends stay on their ports. Drawn as MANUAL waypoints (the user's own bends), so the router keeps them: "M580,264 V204 H850 V154" is `waypoints: [{ x: 580, y: 204 }, { x: 850, y: 204 }]`. |
| `style?` | `Partial<LinkStyle>` |  |  |
| `selected?` | `boolean` |  |  |
| `data?` | `Record<string, any>` |  |  |
| `metadata?` | `Record<string, any>` |  | Link metadata. This is how a link names its `sourceAnchor` / `targetAnchor` and its `connectionPoint` strategy — i.e. how floating edges are turned on per link. |
| `points?` | `Point[]` |  | Explicit waypoints. Restores a user-edited route. |

<!-- source: grafloria-renderer-instance-nodespec.md -->

# NodeSpec

Import it from `@grafloria/renderer`.

```ts
interface NodeSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  |  |
| `type?` | `string` |  | Engine node type. Default `'rect'`. |
| `position?` | `{ x: number; y: number }` |  | Where the box sits. Optional: absent, a new box starts at the origin and an existing one stays put — and a composing layout (`layout: 'architecture'`) places it anyway. |
| `size?` | `{ width: number; height: number }` |  |  |
| `data?` | `Record<string, any>` |  | Free-form user payload — passed straight to custom node components. |
| `label?` | `string` |  | Convenience for `metadata.label`. |
| `sublabel?` | `string \| NodeSublabel` |  | A second, smaller, muted line under the label — the name-and-description box of the diagrams AI tools draw ("Our API" / "sherkety-erp-api"). With a sublabel the label is drawn semi-bold (a `style.fontWeight` still wins). An object sets the line's own font (`'mono'` = a monospace stack), size and colour. Stored on `metadata.sublabel`, so it serializes with the node. |
| `near?` | `{ target: string; side?: 'right' \| 'left' \| 'above' \| 'below'; gap?: number } \| null` |  | A note placed BESIDE what it is about — a relation, not a coordinate: the architecture layout puts this box to the `side` of `target` (a node or zone), `gap` px away. Stored on `metadata.near`. |
| `shape?` | `Record<string, any>` |  | Convenience for `metadata.shape` (fill / stroke / cornerRadius / …). |
| `style?` | `Partial<NodeStyle>` |  |  |
| `selected?` | `boolean` |  |  |
| `draggable?` | `boolean` |  |  |
| `selectable?` | `boolean` |  |  |
| `custom?` | `boolean` |  | Render this node through the host's custom-node callback (React component, slotted template, …) instead of as SVG. Sets `metadata.useHTMLLayer`. |
| `ports?` | `PortSpec[]` |  | Ports. Omit to keep the four deterministic defaults. |
| `metadata?` | `Record<string, any>` |  | Anything else you want on `node.metadata`. |

<!-- source: grafloria-renderer-instance-portspec.md -->

# PortSpec

Import it from `@grafloria/renderer`.

A port on a node. Omit `id` to get the deterministic `<nodeId>__<side>` name.

`PortSpec` used to be `{ id, side, type, index }` and `buildNode()` passed
exactly those four fields to `new PortModel(...)`.

`Grafloria.render()`, `<grafloria-flow>` and `<GrafloriaFlow>` (React) ALL build their
ports here. So an entire wave of feature work — square/diamond/triangle/path
glyphs, `sideLinear`/`line`/`ellipse` layouts, typed data-flow ports, "this
port accepts at most one link" — could not be expressed by any embedder, from
any framework, through any public entry point. It had passing unit tests the
whole time, because the unit tests construct `PortModel` directly.

This is the demo gallery's canonical finding shape, and it is why the gallery
exists: a unit test proves a unit works; it never proves anything CALLS it.

```ts
interface PortSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  |  |
| `side?` | `'top' \| 'right' \| 'bottom' \| 'left'` |  | Which edge of the node the port sits on. Optional when the port names a `group` that declares one — `PortModel.explicitSide` exists precisely so an inherited side is not clobbered by a default. |
| `type?` | `'input' \| 'output' \| 'bi'` |  |  |
| `index?` | `number` |  |  |
| `group?` | `string` |  | Named port group. Config is inherited from it; these fields override. |
| `shape?` | `PortShapeSpec` |  | Glyph: square / diamond / triangle / a custom SVG path. Default: circle. |
| `label?` | `PortLabelSpec` |  | Port label + its placement (inside / outside / orthogonal / radial). |
| `layout?` | `PortLayoutSpec` |  | Layout strategy (line / sideLinear / ellipse / …). Default: the shape anchor. |
| `gating?` | `PortGatingSpec` |  | Directional connectability + link caps + allowed types. |
| `dataType?` | `string` |  | Data-flow type. Drives glyph colour AND connection validity. |
| `fromSpot?` | `PortSpot` |  | Where links leave / land on the glyph box. |
| `toSpot?` | `PortSpot` |  |  |
| `spread?` | `PortSpreadSpec` |  | Fan several links out along the port's edge instead of piling them. |
| `style?` | `Record<string, unknown>` |  | Raw SVG presentation attributes merged onto the glyph. |
| `maxConnections?` | `number` |  | The legacy single cap. `gating` is the richer form. |
| `visible?` | `boolean` |  |  |

<!-- source: grafloria-renderer-interaction.md -->

# Interaction

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-classes): 8 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-constants): 9 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-functions): 14 functions.
- [Interfaces A–T](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-a-t): 33 interfaces, `AddWaypointResult` to `TouchGestureOptions`.
- [Interfaces V–W](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interfaces-v-w): 5 interfaces, `ValidationIssue` to `WhiteboardHost`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-types): 9 types.
- [`ControlPointEditor`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-controlpointeditor): ControlPointEditor provides functionality for editing bezier curve control points
- [`InteractionController`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-interactioncontroller): InteractionController — the framework-agnostic interaction brain.
- [`KeyboardNavigationController`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-keyboardnavigationcontroller)
- [`SelectionToolsController`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-selectiontoolscontroller)
- [`SnapController`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-snapcontroller)
- [`ToolHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-toolhandle): One grabbable tool in the floating layer.
- [`WaypointEditor`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-interaction-waypointeditor): WaypointEditor

<!-- source: grafloria-renderer-interaction-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `DrawTool`

```ts
class DrawTool extends WhiteboardTool implements CanvasTool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` |  | `'whiteboard-draw'` |  |
| `priority` |  |  | Every whiteboard tool STATES its tier — see the arbitration header above. |

**Methods**

- `constructor(host: WhiteboardHost, private readonly opts: DrawToolOptions = {})`
- `onPointerDown(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerMove(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerUp(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `setActive(active: boolean): void`
- `isActive(): boolean`
- `hitTest(): boolean`
- `dispose(): void`
- `onCancel(): void`

### `EraserTool`

```ts
class EraserTool extends WhiteboardTool implements CanvasTool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` |  | `'whiteboard-eraser'` |  |
| `priority` |  |  | Every whiteboard tool STATES its tier — see the arbitration header above. |

**Methods**

- `constructor(host: WhiteboardHost, private readonly opts: EraserToolOptions = {})`
- `onPointerDown(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerMove(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerUp(_ev?: ToolPointerEvent, _hit?: ToolHitContext): void`
- `override onCancel(): void`
- `setActive(active: boolean): void`
- `isActive(): boolean`
- `hitTest(): boolean`
- `dispose(): void`

### `HighlighterController`

```ts
class HighlighterController
```

**Methods**

- `constructor(config: Partial<HighlighterConfig> = {})`
- `getConfig(): HighlighterConfig`
- `updateConfig(patch: Partial<HighlighterConfig>): void`
- `refreshValidation(engine: DiagramEngine): ValidationIssue[]` — Run the engine's validation once and cache the per-entity issues.

Called on structure changes (node/link added/removed/reconnected) — NOT per
frame: `validateDiagram()` walks every node, link, hierarchy and group.
- `getIssues(entityId: string): ValidationIssue[]` — Issues cached for one entity (empty when clean / never refreshed).
- `clearValidation(): void` — Drop the cached validation (e.g. when the diagram is swapped).
- `compute(engine: DiagramEngine): Highlighter[]` — Every highlighter that applies right now, in paint order: validation first
(bottom), then selection, then hover, then connect targets (top).

### `InkOverlay`

A camera-registered SVG scratch layer for transient drawing feedback.

Draws in WORLD coordinates: the layer's `<g>` carries the same translate+scale the SVG
layer's viewBox implies, so a pan or a zoom re-registers every preview with ONE transform
write instead of re-projecting points in JS.

```ts
class InkOverlay
```

**Methods**

- `constructor(private readonly options: InkOverlayOptions)`
- `get element(): SVGSVGElement` — For tests and the a11y audit — the DOM this owns.
- `drawPolyline(points: ReadonlyArray<{ x: number; y: number }>, style: InkPreviewStyle): void` — Paint (or repaint) the in-progress freehand line through `points` (world coordinates). ONE `d` attribute write — no VNode, no frame.
- `drawRect(x: number, y: number, width: number, height: number, style: InkPreviewStyle): void` — Paint the rubber-band rectangle for the rectangle tool (world coordinates).
- `clear(): void` — Remove all preview geometry. Called on pointerup/cancel, once per gesture.
- `dispose(): void`

### `InPlaceTextEditor`

```ts
class InPlaceTextEditor
```

**Methods**

- `getSession(): TextEditSession | null`
- `isEditing(): boolean`
- `begin(engine: DiagramEngine, target: TextEditTarget): TextEditSession | null` — Open a session on a target. Returns null when the target does not exist or
is not editable (`behavior.editable === false`, or a locked node).
- `commit(engine: DiagramEngine, value: string): Command | null` — Commit the session's new value. Returns the undoable command (null for a
no-op edit, or when the session is gone). Always ends the session.
- `cancel(): void` — Abandon the session without touching the model.

### `RectangleTool`

```ts
class RectangleTool extends WhiteboardTool implements CanvasTool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` |  | `'whiteboard-rectangle'` |  |
| `priority` |  |  | Every whiteboard tool STATES its tier — see the arbitration header above. |

**Methods**

- `constructor(host: WhiteboardHost, private readonly opts: RectangleToolOptions = {})`
- `onPointerDown(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerMove(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerUp(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `setActive(active: boolean): void`
- `isActive(): boolean`
- `hitTest(): boolean`
- `dispose(): void`
- `onCancel(): void`

### `StrokeEditTool`

```ts
class StrokeEditTool extends WhiteboardTool implements CanvasTool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` |  | `'whiteboard-stroke-edit'` |  |
| `priority` |  |  | INK tier: outranks the mode tools, and is SAFE to because {@link hitTest} only ever claims a press that lands on ink — see the arbitration header. |

**Methods**

- `constructor(host: WhiteboardHost, private readonly opts: StrokeEditToolOptions = {})`
- `getSelectedStroke(): StrokeModel | null` — What the tool considers selected — for hosts, tests, and a future style panel.
- `override hitTest(ev?: ToolPointerEvent): boolean` — CLAIM the gesture only when ink is under the pointer. This is what lets the tool
coexist with the whole built-in ladder instead of monopolising the canvas.
- `onPointerDown(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerMove(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `onPointerUp(ev: ToolPointerEvent, _hit?: ToolHitContext): void`
- `override onCancel(): void` — Escape / pointercancel: drop the gesture AND the selection. Nothing was committed.
- `override setActive(active: boolean): void`
- `isActive(): boolean`
- `dispose(): void`

### `TouchGestureController`

```ts
class TouchGestureController
```

**Methods**

- `constructor( private readonly host: TouchGestureHost, options: TouchGestureOptions = {}, private readonly selectionTools?: SelectionToolsController )`
- `get activePointerCount(): number` — How many fingers are down. Exposed for tests and for the binder's cursor logic.
- `get isPinching(): boolean` — True while a two-finger pinch owns the gesture.
- `onPointerDown(event: PointerEvent): void`
- `onPointerMove(event: PointerEvent): void`
- `onPointerUp(event: PointerEvent): void`
- `onPointerCancel(event: PointerEvent): void` — The OS took the gesture (call, notification, browser back-swipe). Abort cleanly.
- `reset(): void` — Drop every listener-visible bit of state (binder detach).

<!-- source: grafloria-renderer-interaction-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `DEFAULT_HIGHLIGHTER_CONFIG`

```ts
const DEFAULT_HIGHLIGHTER_CONFIG: HighlighterConfig
```

### `DEFAULT_KEYBOARD_NAV_CONFIG`

```ts
const DEFAULT_KEYBOARD_NAV_CONFIG: KeyboardNavConfig
```

### `DEFAULT_SELECTION_TOOLS_CONFIG`

```ts
const DEFAULT_SELECTION_TOOLS_CONFIG: SelectionToolsConfig
```

### `DEFAULT_SNAP_CONFIG`

```ts
const DEFAULT_SNAP_CONFIG: SnapConfig
```

### `INK_OVERLAY_CLASS`

```ts
const INK_OVERLAY_CLASS: "grafloria-ink-overlay"
```

### `RESIZE_HANDLE_IDS`

```ts
const RESIZE_HANDLE_IDS: ResizeHandleId[]
```

### `TOUCH_HIT_SLOP_PX`

Extra hit radius, in CSS px, granted to a TOUCH pointer.

A port renders at ~5 px radius. A fingertip is ~9 mm. WCAG 2.5.8 wants a 24×24
target and Apple/Material ask for 44/48. 16 px of slop takes an effective port
target from ~14 px to ~46 px across, which clears 44. Applied in WORLD units
(slop ÷ zoom) because every hit test in this engine is world-space — applying it
in screen px would make ports unhittable when zoomed out, which is exactly when
they are smallest and you need the help most.

```ts
const TOUCH_HIT_SLOP_PX: 16
```

### `WHITEBOARD_INK_TOOL_PRIORITY`

The point-specific INK tools (stroke edit): only ever claims a press that
actually lands on ink, so it must not lose that press to a mode tool that
claims everything. See the arbitration header.

```ts
const WHITEBOARD_INK_TOOL_PRIORITY: 2
```

### `WHITEBOARD_MODE_TOOL_PRIORITY`

The point-agnostic MODE tools: draw, rectangle, eraser. Above the built-in
ladder (0), below the ink-specific tier — see the arbitration header.

```ts
const WHITEBOARD_MODE_TOOL_PRIORITY: 1
```

<!-- source: grafloria-renderer-interaction-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `angleAt`

Angle (deg) of `point` seen from `center`; 0° = straight up, growing clockwise.

```ts
function angleAt(center: Point, point: Point): number
```

### `applyResizeToNode`

Apply a resize drag to a possibly-ROTATED node.

The pointer delta arrives in WORLD space, but the box the user is resizing is
drawn in the node's local (unrotated) frame and rotated about its centre. So:

1. rotate the world delta by −θ → the node's local frame;
 2. resize the local box;
 3. the node re-renders rotated about its NEW centre, so compensate the
    position by rotating the centre shift back into world space.

At θ = 0 this collapses to `pos + (box.x, box.y)`. Getting step 3 wrong is what
makes rotated resize "swim" away from the cursor in most implementations.

```ts
function applyResizeToNode(
  start: { position: Point; size: { width: number; height: number }; rotation: number },
  handle: ResizeHandleId,
  worldDx: number,
  worldDy: number,
  options: ResizeOptions = {}
): { position: Point; size: { width: number; height: number } }
```

### `canConnectPorts`

Can ports `a` (on `nodeA`) and `b` (on `nodeB`) be linked?

The ONE rule shared by proximity connect and keyboard connect
, so the two can never disagree about what is legal.

It no longer OWNS that rule — it delegates to
`evaluatePortConnection`, the engine-side validator the connection drag also
runs through. A port
you could legally drag to was one the magnet refused to snap to.

`rejectDuplicatesByDefault` preserves this call site's own historical stance:
auto-linking a duplicate because a node drifted near is never what the user
meant, whatever the port's `allowDuplicateLinks` says.

Note the argument order: `a` is the SOURCE. The rule is directional, and the
proximity search calls it once per orientation.

```ts
function canConnectPorts(
  a: PortModel,
  b: PortModel,
  nodeA: NodeModel,
  nodeB: NodeModel,
  engine: DiagramEngine,
  diagram: { getLinks(): LinkModel[] }
): boolean
```

### `createDrawTool`

```ts
function createDrawTool(host: WhiteboardHost, options?: DrawToolOptions): DrawTool
```

### `createEraserTool`

```ts
function createEraserTool(host: WhiteboardHost, options?: EraserToolOptions): EraserTool
```

### `createRectangleTool`

```ts
function createRectangleTool(host: WhiteboardHost, options?: RectangleToolOptions): RectangleTool
```

### `createStrokeEditTool`

```ts
function createStrokeEditTool(
  host: WhiteboardHost,
  options?: StrokeEditToolOptions
): StrokeEditTool
```

### `normalizeAngle`

Fold an angle into [0, 360).

```ts
function normalizeAngle(deg: number): number
```

### `parseValidationPath`

Parse a ValidationEngine `path` back to the entity it names. Paths look like `node.<id>`, `node.<id>.port.<id>`, `node.<id>.hierarchy`,
`link.<id>`. Anything else (diagram-level) is not entity-scoped.

```ts
function parseValidationPath(
  path: string
): { entity: 'node' | 'link'; entityId: string } | null
```

### `resizeBox`

Apply a resize drag to a box, in the box's OWN frame.

`dx/dy` is the pointer delta since the drag began (same frame as the box). The
dragged edge(s) follow the pointer; the opposite edge stays put. Min/max clamp
the DRAGGED edge, never the anchored one — so a runaway drag can neither flip
nor shrink past the minimum nor grow past the maximum, all mid-gesture.

```ts
function resizeBox(
  start: Rectangle,
  handle: ResizeHandleId,
  dx: number,
  dy: number,
  options: ResizeOptions = {}
): Rectangle
```

### `rotatePoint`

Rotate `point` about `center` by `deg` degrees.

```ts
function rotatePoint(point: Point, center: Point, deg: number): Point
```

### `rotateVector`

Rotate `(x, y)` about the origin by `deg` degrees (SVG's positive = clockwise).

```ts
function rotateVector(x: number, y: number, deg: number): Point
```

### `sideHandleYieldsToPort`

resize-ux: the ONE side-handle-vs-port priority predicate.

The four side handles live ON the node border, where the default side ports
also live. React Flow resolves the coincidence by z-order: the port glyph
(drawn on top of the resize line) wins its own core, the line wins the rest
of the edge. Ours is the same rule expressed in hover state: when the pointer
is inside a port's grab radius (`hoveredPort` is set) on the SAME node, the
port claims the press/cursor; everywhere else along the band, resize does.

Exported so the mouse ladder, the touch ladder AND the hover-cursor logic
share one predicate — three private copies is how they drift.

```ts
function sideHandleYieldsToPort(
  handle: ToolHandle,
  hoveredPort: { nodeId?: string } | null | undefined
): boolean
```

### `snapAngle`

Snap `deg` to the nearest multiple of `step` (step ≤ 0 → unchanged).

```ts
function snapAngle(deg: number, step: number): number
```

<!-- source: grafloria-renderer-interaction-interfaces-a-t.md -->

# 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. |

<!-- source: grafloria-renderer-interaction-interfaces-v-w.md -->

# Interfaces V–W

Import these from `@grafloria/renderer`.

## Interfaces

### `ValidationIssue`

One validation issue, resolved to the entity it is about.

```ts
interface ValidationIssue
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entity` | `'node' \| 'link'` |  |  |
| `entityId` | `string` |  |  |
| `severity` | `'error' \| 'warning'` |  |  |
| `message` | `string` |  |  |
| `code` | `string` |  |  |

### `Waypoint`

Represents a waypoint on a link path

```ts
interface Waypoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` |  |  |
| `point` | `Point` |  |  |

### `WaypointHandle`

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

Waypoint handle for rendering

```ts
interface WaypointHandle extends Waypoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `linkId` | `string` |  |  |

### `WaypointHitResult`

Result of hit testing a waypoint

```ts
interface WaypointHitResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `waypointIndex` | `number` |  |  |
| `waypoint` | `Waypoint` |  |  |
| `distance` | `number` |  |  |

### `WhiteboardHost`

The slice of a mounted diagram the whiteboard tools need. `DiagramInstance` satisfies it
structurally, but a test can hand over a fake with four members instead of forty.

```ts
interface WhiteboardHost
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `ViewportController` |  |  |
| `container` | `HTMLElement` |  |  |
| `batch?` | `(fn: () => void) => void` |  | Run a multi-op commit as ONE undo step. A collab/undo-aware host passes `replica.transact`; the default runs it inline (a plain instance has no undo stack, and one add / N removes are still atomic to the model either way). |

**Members**

- `getModel(): DiagramModel`
- `render(): void` — Queue a repaint after a commit.
- `getEngine?(): DiagramEngine | null` — The command manager, when the host has one. `DiagramInstance`
already exposes exactly this signature, so an embed keeps handing the instance over
unchanged. The EDIT tool commits its translate through `engine.commandManager` so the
gesture is Ctrl-Z-able; without an engine it falls back to a plain `setPoints` commit
(still correct, still ONE op for collab — just not on an undo stack that doesn't exist).

<!-- source: grafloria-renderer-interaction-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `AnnouncementListener`

```ts
type AnnouncementListener = (announcement: Announcement) => void;
```

### `AnnouncementUnsubscribe`

Remove an announcement listener. (Named to avoid clashing with the
viewport module's `Unsubscribe`, which is re-exported from the same barrel.)

```ts
type AnnouncementUnsubscribe = () => void;
```

### `FocusTargetType`

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

KeyboardNavigationController — a fully keyboard-operable, screen-reader-
announced canvas.

No diagramming competitor does this: Mermaid is read-only, and React Flow /
JointJS+ / GoJS are pointer-first with, at best, arrow-key nudging. This class
owns the whole keyboard model:

- a FOCUS ring that walks nodes and links (Tab / Shift+Tab, arrow keys for
   spatial movement) — focus is distinct from selection, as in every native UI;
 - arrow-key NUDGE of the selection (Shift = coarse step), committed as ONE
   undoable command per key press;
 - Enter to edit the focused node's label (the host opens the editor);
 - keyboard CONNECT: pick a source port, then a target node/port, commit;
 - ARIA ANNOUNCEMENTS for selection and structure changes, which the host pipes
   into an `aria-live` region.

Framework-agnostic: it emits state + {@link Command}s, and never renders.

```ts
type FocusTargetType = 'node' | 'link';
```

### `HaloAction`

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

Halo (context toolbar) actions, JointJS+-style.

```ts
type HaloAction = 'connect' | 'clone' | 'fork' | 'delete';
```

### `HighlighterKind`

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

HighlighterController — hover / selection / validation / drop-target
decorations.

JointJS calls these "highlighters": decorations layered OVER an element rather
than baked into it. Keeping them out of the shape lets several stack (a node
can be selected AND invalid) and lets a host restyle them without touching the
node renderer.

Like the rest of the interaction layer this class only produces geometry — it
never renders and never mutates the model.

```ts
type HighlighterKind = 'hover' | 'selection' | 'validation' | 'connect-target';
```

### `NavDirection`

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

```ts
type NavDirection = 'up' | 'down' | 'left' | 'right';
```

### `ResizeHandleId`

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

The 8 resize handles, named by compass direction.

```ts
type ResizeHandleId = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
```

### `TextEditTargetType`

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

A host cannot avoid owning the actual text widget (an `<input>`, a
`contenteditable`, a native text field), but everything AROUND it is
framework-agnostic and belongs here:

- WHAT is being edited (node label / link label) and its current text;
 - WHERE the editor goes, in world coordinates (the host maps to screen with
   its viewport, so the editor lands exactly over the text at any zoom);
 - the ONE undoable {@link Command} that commits the new value.

The commit path is the point: before this, in-place edits wrote straight to the
model and could not be undone.

```ts
type TextEditTargetType = 'node' | 'link-label';
```

### `ToolKind`

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

```ts
type ToolKind =
  | 'resize'
  | 'rotate'
  | 'remove'
  | 'halo'
  | 'link-endpoint'
  | 'vertex-add'
  | 'vertex-remove';
```

<!-- source: grafloria-renderer-interaction-controlpointeditor.md -->

# ControlPointEditor

Import it from `@grafloria/renderer`.

ControlPointEditor provides functionality for editing bezier curve control points

Features:
- Detect and track control points from path segments
- Hit testing for control point handles
- Move control points via drag
- Auto-generate smooth bezier curves from points
- Grid snapping support
- Symmetric control point mirroring
- Visual rendering of control handles and lines

```ts
class ControlPointEditor
```

**Methods**

- `constructor(config: ControlPointEditorConfig)`
- `getControlPoints(segments: PathSegment[]): ControlPoint[]` — Get all control points from path segments
- `hitTestControlPoint( mouseX: number, mouseY: number, segments: PathSegment[], hitSlop = 0 ): ControlPointHitResult | null` — Hit test for control point handles
Optimized to avoid allocations on hot path (mousemove)
- `moveControlPoint( segmentIndex: number, controlType: 'control1' | 'control2', newPosition: Point, segments: PathSegment[] ): PathSegment[] | null` — Move a control point to a new position
- `generateBezierSegments(points: Point[]): PathSegment[]` — Auto-generate bezier curve segments from an array of points

Uses Catmull-Rom algorithm to generate smooth curves
- `snapToGrid(point: Point): Point` — Snap a point to the grid
- `calculateDistance(p1: Point, p2: Point): number` — Calculate Euclidean distance between two points
- `renderControlPointHandle(controlPoint: ControlPoint, linkId: string): VNode` — Render a control point handle as a VNode
- `renderControlLine(controlPoint: ControlPoint, linkId: string): VNode` — Render a control line (from anchor to control point) as a VNode
- `renderControlPointHandles(segments: PathSegment[], linkId: string): VNode[]` — Render all control point handles for a link
- `updateConfig(partialConfig: Partial<ControlPointEditorConfig>): void` — Update configuration (partial update)
- `getConfig(): Readonly<ControlPointEditorConfig>` — Get current configuration

**Example**

```typescript
const editor = new ControlPointEditor(config);

// Detect control points from segments
const controlPoints = editor.getControlPoints(link.segments);

// Hit test for click
const hit = editor.hitTestControlPoint(mouseX, mouseY, link.segments);

// Move control point
const newSegments = editor.moveControlPoint(hit.segmentIndex, hit.controlType, newPos, link.segments);

// Render visual handles
const handles = editor.renderControlPointHandles(link.segments, link.id);
```

<!-- source: grafloria-renderer-interaction-interactioncontroller.md -->

# InteractionController

Import it from `@grafloria/renderer`.

InteractionController — the framework-agnostic interaction brain.

Owns all pointer/keyboard-driven interaction LOGIC for a diagram: hover
detection, port connection dragging, link endpoint reconnection, inline label
repositioning, and waypoint / control-point editing.

## Framework contract

This class answers **"WHAT changed?"** — never **"who should re-render?"**. Every handler returns a boolean (or a value) telling the host whether a
re-render is warranted; the host framework decides how to act on that:

- Angular  → `cdr.markForCheck()`   (see `InteractionHandlerService`)
- React    → `setState` / `useSyncExternalStore`
- Vue      → touch a `ref`
- Vanilla  → call your own `render()`

It therefore has **zero framework imports** (no Angular, no DOM beyond the
ambient `performance.now()` clock) and is instantiated with a plain `new`. It takes WORLD coordinates only: converting client/screen pixels into world
space is the job of {@link ViewportController }, so this class never touches
an event, an element, or a bounding rect.

Supports three interaction modes (driven by the engine's interaction config):
- DIRECT: Drag node body to move, drag port to connect
- DELIBERATE: Select node first, then drag to move
- SMART: Visio-style with hover-based port visibility

The Angular `InteractionHandlerService` is a thin `@Injectable` subclass of
this class and adds no behaviour of its own.

```ts
class InteractionController
```

**Methods**

- `setHitSlop(world: number): void` — Grow every hit target by `world` units (0 = mouse-precision, the default).
- `getHitSlop(): number`
- `setLinkHitAreaWidth(width: number): void`
- `constructor()`
- `dispose(): void` — Dispose and cleanup resources
- `getPerformanceMetrics()` — Get performance metrics
- `invalidatePortHitCache(): void` — Invalidate port hit cache (call when nodes move or ports change)
- `handleMouseMove( worldX: number, worldY: number, engine: DiagramEngine ): boolean` — Handle mouse move for hover detection
Enhanced with performance monitoring and validation
Updates hover states for nodes, ports, and links
CRITICAL FIX: Added comprehensive debugging
- `handleConnectionDrag( worldX: number, worldY: number, engine: DiagramEngine ): boolean` — Handle connection drag update
Enhanced with performance monitoring and validation
Updates connection preview during drag
- `startConnection(port: PortModel, worldX: number, worldY: number, engine: DiagramEngine): void` — Start connection from port
Enhanced with validation and error handling
CRITICAL FIX: Added detailed logging
- `startNodeBodyConnection( node: NodeModel, worldX: number, worldY: number, engine: DiagramEngine ): boolean` — Start a connection from a
node BODY, not a port glyph. Picks the source port nearest the press point
(so a drag off the right side starts from the right port) and begins the
normal connection drag from it. Returns false when the node has no port to
start from. The whole gesture then flows through the existing connection
pipeline (preview on move, {@link completeConnection} on drop).
- `completeConnection(engine: DiagramEngine): boolean` — Complete connection to target port
Enhanced with validation and error handling
- `cancelConnection(engine: DiagramEngine): void` — Cancel connection
- `startLinkReconnection( link: LinkModel, endpoint: 'source' | 'target', worldX: number, worldY: number, engine: DiagramEngine ): void` — Start link reconnection.

Enters endpoint-drag mode: the dragged endpoint follows the cursor while
the OTHER endpoint stays put. Seeds the engine's {@link ReconnectionPreview }
so the renderer can draw a ghost link, and primes port validity highlights.
- `updateLinkReconnection(worldX: number, worldY: number, engine: DiagramEngine): boolean` — Update the in-progress endpoint reconnection as the cursor moves.

Refreshes the ghost-preview endpoint, recomputes which ports are valid drop
targets (highlighting them), and reflects whether the currently hovered
port would be accepted. Returns true when a re-render is warranted.
- `isValidReconnectionTarget( link: LinkModel, endpoint: 'source' | 'target', candidatePort: PortModel, engine: DiagramEngine ): boolean` — Is `candidatePort` a legal target for reconnecting `endpoint` of
`link`? The OTHER endpoint's port stays fixed; the candidate must differ
from it, live on a different node, be type-compatible (input↔output, or a
bidirectional port), and satisfy the connection-group rules. Pure w.r.t.
the passed models — the core of the reconnect-validation tests.
- `completeLinkReconnection(engine: DiagramEngine): boolean` — Complete link reconnection.

Drops the dragged endpoint on the hovered port. Rejects (and restores the
original connection) when there is no port under the cursor or the port
fails {@link isValidReconnectionTarget}.
- `cancelLinkReconnection(engine: DiagramEngine): void` — Cancel an in-progress endpoint reconnection, restoring the link to
its original connection. Safe to call when not reconnecting.
- `computeLabelDragUpdate( link: LinkModel, worldPoint: Point ): { position: number; offset: Point } | null` — Map a dragged world point to a model-space label placement.

Returns the `{ position, offset }` to store on the label such that the
renderer draws it exactly under the cursor now AND it sticks to the same
fraction of the path after re-routing:
  - `position` (0-1) = closest point on the path to the cursor;
  - `offset`         = cursor − on-path anchor at `position`.

The offset is measured against the SAME anchor the renderer uses
({@link LinkModel.getPointAtPosition}), so `getPointAtPosition(position) +
offset` reproduces the cursor by construction. Falls back to a direct
polyline projection over `link.points` when the model has no segments
(renderers sync `points` but leave `segments` stale). Returns null when the
link has no drawable path.
- `startLabelDrag(link: LinkModel, labelIndex: number): void` — Begin dragging label `labelIndex` of `link`.
- `moveLabelDrag(worldX: number, worldY: number): boolean` — Move the dragging label to follow the cursor. Writes the remapped
`{ position, offset }` back onto the model so the label survives re-routing. Returns true when a re-render is warranted.
- `endLabelDrag(): void` — End the label drag.
- `selectLink(link: LinkModel, engine: DiagramEngine, multiSelect: boolean = false): void` — Handle link selection
FIXED: Support multi-select with Ctrl key, deselect other links otherwise
- `deleteSelectedLink(engine: DiagramEngine): boolean` — Delete selected link
- `getLinkAtPosition(worldX: number, worldY: number, engine: DiagramEngine): LinkModel | null` — Find link at world position (public wrapper for hit testing)
Used for direct link selection without requiring hover state
- `getLinkHitAtPosition( worldX: number, worldY: number, engine: DiagramEngine ): LinkPartHit | null` — Part-aware public wrapper: like {@link getLinkAtPosition} but also reports
WHICH sub-part of the link was hit (body / label / endpoint / arrow) plus
local info. Foundation for later edge cards (label editing, endpoint
reconnection, edge toolbar placement).
- `getState()` — Get current interaction state
- `isInteracting(): boolean` — Check if currently interacting
- `getCursor(engine: DiagramEngine): string` — Get appropriate cursor for current state
- `findLinkHitAtPosition( worldX: number, worldY: number, diagram: any ): LinkPartHit | null`
- `hitTestWaypoint(mouseX: number, mouseY: number, link: LinkModel): number | null` — Hit test for waypoint handle at mouse position
Returns the waypoint index if hit, null otherwise
- `hitTestPath(mouseX: number, mouseY: number, link: LinkModel): boolean` — Hit test for clicking on link path (to add waypoint)
- `startWaypointDrag(waypointIndex: number, link: LinkModel): void` — Start dragging a waypoint
- `moveWaypoint(worldX: number, worldY: number, engine: DiagramEngine): boolean` — Move waypoint during drag
The waypoint is just moved, orthogonal routing happens during rendering
- `endWaypointDrag(engine?: DiagramEngine): void` — End waypoint drag
- `addWaypoint(clickX: number, clickY: number, link: LinkModel): boolean` — Add waypoint at click position on path
- `removeWaypoint(waypointIndex: number, link: LinkModel): boolean` — Remove waypoint at index
- `updateWaypointEditorConfig(config: Partial<any>): void` — Update waypoint editor configuration
- `syncWithEngineConfig(engine: DiagramEngine): void` — Synchronize editor configs with engine interaction config
ADDED: Call this when engine config changes to update editor visuals
- `updateHoveredWaypoint(worldX: number, worldY: number, link: LinkModel | null): void` — Update hovered waypoint (for Delete key support)
Call this from mousemove to track which waypoint is under cursor
- `deleteHoveredWaypoint(): boolean` — Delete currently hovered waypoint (for Delete key)
- `hitTestControlPoint( mouseX: number, mouseY: number, link: LinkModel ): { segmentIndex: number; controlType: 'control1' | 'control2' } | null` — Hit test for control point handle at mouse position
Returns the control point info if hit, null otherwise
- `startControlPointDrag( segmentIndex: number, controlType: 'control1' | 'control2', link: LinkModel ): void` — Start dragging a control point
- `moveControlPoint(worldX: number, worldY: number, engine: DiagramEngine): boolean` — Move control point during drag
- `endControlPointDrag(): void` — End control point drag
- `updateControlPointEditorConfig(config: Partial<any>): void` — Update control point editor configuration
- `updateHoveredControlPoint(worldX: number, worldY: number, link: LinkModel | null): void` — Update hovered control point (for Delete key support)
Call this from mousemove to track which control point is under cursor
- `resetHoveredControlPoint(): boolean` — Reset control point to auto-generated position (for Delete key)
This removes custom control point adjustment, reverting to default bezier

<!-- source: grafloria-renderer-interaction-keyboardnavigationcontroller.md -->

# KeyboardNavigationController

Import it from `@grafloria/renderer`.

```ts
class KeyboardNavigationController
```

**Methods**

- `constructor(config: Partial<KeyboardNavConfig> = {})`
- `getConfig(): KeyboardNavConfig`
- `updateConfig(patch: Partial<KeyboardNavConfig>): void`
- `getFocusOrder(engine: DiagramEngine): FocusTarget[]` — Tab order: nodes in reading order (top-to-bottom, then left-to-right), then
links ordered by their source node's place in that same order — so tabbing
walks the structure the way a sighted user reads it.
- `getFocused(): FocusTarget | null`
- `setFocus(target: FocusTarget | null, engine?: DiagramEngine): FocusTarget | null` — Set focus (null clears it) and announce the new target.
- `focusNext(engine: DiagramEngine): FocusTarget | null` — Tab.
- `focusPrevious(engine: DiagramEngine): FocusTarget | null` — Shift+Tab.
- `focusDirection(engine: DiagramEngine, direction: NavDirection): FocusTarget | null` — Spatial arrow-key focus movement across NODES: pick the nearest node whose
centre lies in the requested half-plane, preferring small perpendicular
offset (the standard "directional focus" heuristic).
- `getFocusRing(engine: DiagramEngine): FocusRing | null` — The visible focus ring for the current target (null when nothing is focused).
- `selectFocused(engine: DiagramEngine, additive = false): boolean` — Make the focused entity the selection (Space, or Enter on a link). Selection lives on the model, which is what the renderer draws and what the
clipboard/delete commands read once the host syncs it to the store.
- `incidentEdgesOfFocus(engine: DiagramEngine): Incidence[]` — The edges incident on the focused node, in a stable traversal order.
- `followEdge(engine: DiagramEngine, index = 0): FocusTarget | null` — FOLLOW-EDGE NAVIGATION. From a focused node, step along its Nth incident
edge to the node at the far end. From a focused EDGE, step to its endpoints.

This is the move that makes a diagram traversable without sight: you are on
"Is order valid?", you are told it has 2 outgoing edges, and you walk one.
- `followOutgoing(engine: DiagramEngine, index = 0): FocusTarget | null` — Walk to the Nth node this one points AT.
- `followIncoming(engine: DiagramEngine, index = 0): FocusTarget | null` — Walk back to the Nth node that points at this one.
- `focusIncidentEdge(engine: DiagramEngine, index = 0): FocusTarget | null` — Focus the EDGE itself (rather than jumping over it) — so it can be deleted.
- `focusEntryPoint(engine: DiagramEngine, index = 0): FocusTarget | null` — Jump to the first entry point — "take me back to the start of the flow".
- `positionContextOfFocus(engine: DiagramEngine): string` — The POSITION CONTEXT for the focused node — "node 3 of 12, 2 incoming,
1 outgoing". The orientation a sighted user gets for free from the picture.
- `announcePosition(engine: DiagramEngine): Announcement | null` — Announce where we are in the graph. Bound to a key in the host.
- `announceSummary(engine: DiagramEngine): Announcement | null` — The whole-diagram natural-language summary, announced on entry.
- `deleteCommand(engine: DiagramEngine): Command | null` — Delete the selection (or, with nothing selected, the focused entity), as one
undoable macro. Deleting a node takes its incident edges with it — leaving
dangling links is how a keyboard user silently corrupts a diagram.
- `duplicateCommand(engine: DiagramEngine, offset: Point = { x: 24, y: 24 }): Command | null` — Duplicate the focused/selected nodes at an offset, carrying any edge that
runs BETWEEN two duplicated nodes (an edge to a node you did not copy has
no meaningful counterpart, so it is dropped — the same rule the pointer
duplicate uses).
- `reparentCommand(engine: DiagramEngine, parentId: string | null): Command | null` — REPARENT the focused node into (or out of) a container — the last thing that
was pointer-only. `null` unparents.

`SetParentCommand` already rejects a cycle; we catch it EARLY so the user
gets an assertive "cannot" instead of an exception thrown into the void.
- `reparentCandidates(engine: DiagramEngine): NodeModel[]` — The containers the focused node could legally be reparented into — what a
host puts in a "move to…" list. Excludes itself and its own descendants.
- `nudgeDelta(key: string, coarse = false): Point | null` — World delta for an arrow key (null when the key is not an arrow).
- `nudgeCommand( engine: DiagramEngine, dx: number, dy: number, options: { mergeable?: boolean } = {} ): Command | null` — Move the selection (or, with nothing selected, the focused node) by a world
delta, as ONE undoable command per key press. Locked / undraggable nodes are
skipped; returns null when there is nothing to move.

`mergeable` defaults FALSE — the a11y contract is "⌘Z undoes each nudge to
the exact pixel". An editor that wants held-key auto-repeat to collapse
into one undo entry (Visio's feel) passes true and the CommandManager's
merge window does the rest.
- `getConnectState(): KeyboardConnectState | null`
- `isConnecting(): boolean`
- `beginConnect(engine: DiagramEngine): boolean` — Returns false when the focused
node has no connectable port.
- `cyclePort(engine: DiagramEngine, delta: number): boolean` — Cycle the port being picked in the current phase.
- `cycleTargetNode(engine: DiagramEngine, delta: number): boolean` — Cycle the TARGET node.
- `confirmConnect(engine: DiagramEngine): Command | null`
- `cancelConnect(): void` — Escape.
- `onAnnounce(listener: AnnouncementListener): AnnouncementUnsubscribe`
- `getLastAnnouncement(): Announcement | null`
- `announce(message: string, politeness: 'polite' | 'assertive' = 'polite'): Announcement`
- `announceSelection(engine: DiagramEngine): Announcement | null` — "2 nodes and 1 link selected" — announced whenever the selection changes.
- `announceStructure(engine: DiagramEngine, change: string): Announcement | null` — "Node Start added. 4 nodes, 3 links." — for structure changes.
- `describe(engine: DiagramEngine, target: FocusTarget): string` — The accessible name of a target: what a screen reader reads on focus, and
what the host puts in `aria-label` on the rendered element.
- `nodeName(node: NodeModel): string` — Human name of a node: its label, else its type + short id.
- `dispose(): void`

<!-- source: grafloria-renderer-interaction-selectiontoolscontroller.md -->

# SelectionToolsController

Import it from `@grafloria/renderer`.

```ts
class SelectionToolsController
```

**Methods**

- `constructor(config: Partial<SelectionToolsConfig> = {})`
- `getConfig(): SelectionToolsConfig`
- `updateConfig(patch: Partial<SelectionToolsConfig>): void`
- `isActive(): boolean` — True while a resize / rotate / vertex drag owns the pointer.
- `activeGesture(): 'resize' | 'rotate' | 'vertex' | null` — The kind of gesture in flight (`null` when idle) — hosts branch on it.
- `activeGestureNodeId(): string | null` — The node the in-flight gesture is acting on (`null` when idle). Lets a host
exclude it from a snap's sibling set — a box must not snap to itself.
- `computeLayer(engine: DiagramEngine, zoom = 1): SelectionToolLayer` — Compute the tool layer for the CURRENT selection.

`zoom` converts the screen-px sizes in the config into world units, so the
handles are the same physical size at every zoom level.

Scope note (deliberate): resize + rotate are offered for a SINGLE selected
node. A multi-node selection gets the bounding frame, the halo and the remove
button — proportional multi-node resize is not implemented.
- `hitTest(layer: SelectionToolLayer, worldX: number, worldY: number): ToolHandle | null` — Which tool (if any) is under a world point.

Later handles win ties, so the halo/remove buttons (emitted last) stay
clickable where they overlap a resize handle.

resize-ux: a handle that carries a `segment` (the four side resize handles)
hit-tests as a BAND around that segment — the whole edge is grabbable, the
React Flow line behaviour. POINT handles always beat bands: the corner dots
sit exactly where two bands end, and the dot must win its own pixel (RF
draws the dots on top of the lines for the same reason). Halo/remove/rotate
are point handles, so their priority over resize is unchanged.
- `hitTestResize( layer: SelectionToolLayer, worldX: number, worldY: number, slop = 0 ): ToolHandle | null` — resize-ux: the RESIZE handle under a world point, with optional extra grab
slop (world units). One entry point for the mouse ladder (slop 0) and the
touch ladder (finger-sized slop), so bands and dots grow identically.
- `beginResize( handle: ToolHandle, engine: DiagramEngine, worldX: number, worldY: number ): boolean` — Arm a resize. Returns false when the handle/node is not resizable.
- `updateResize( engine: DiagramEngine, worldX: number, worldY: number, modifiers: ToolModifierState = {}, snap?: (box: Rectangle) => Rectangle ): boolean` — Live-resize the node (direct model mutation, like the drag tool: smooth, no
command churn — the single undo entry is minted at {@link endGesture}).
- `beginRotate(handle: ToolHandle, engine: DiagramEngine, worldX: number, worldY: number): boolean`
- `updateRotate( engine: DiagramEngine, worldX: number, worldY: number, modifiers: ToolModifierState = {} ): boolean` — Live-rotate; Shift snaps to `rotationSnapDegrees`.
- `beginVertexDrag(handle: ToolHandle, engine: DiagramEngine): boolean`
- `updateVertexDrag( engine: DiagramEngine, worldX: number, worldY: number, snapPoint?: (p: Point) => Point ): boolean`
- `endGesture(engine: DiagramEngine): Command | null` — End the active gesture and return the ONE command that makes it undoable
(null for a no-op gesture). The model already sits at its final state — the
command re-applies it (a no-op) and records the inverse, exactly like the
Node-drag commit.
- `cancelGesture(engine: DiagramEngine): void` — Abandon the gesture, restoring the model to its pre-gesture state.
- `addVertexCommand(handle: ToolHandle, engine: DiagramEngine): Command | null` — Insert a vertex at the clicked segment midpoint. Undoable.
- `removeVertexCommand(handle: ToolHandle, engine: DiagramEngine): Command | null` — Remove the vertex under the tool. Undoable.
- `removeSelectionCommand(engine: DiagramEngine): Command | null` — The command behind a remove button / halo `delete`: drop the whole selection
(every selected node AND link) in ONE undo step.
- `cloneNodeCommand( engine: DiagramEngine, nodeId: string, offset: Point = { x: 40, y: 40 } ): Command | null` — Halo `clone`: a copy of the node, offset, as one undoable AddNodeCommand. Ports get fresh ids (via the engine's shared {@link remapNodePortIds}) so the
clone never shares port identity with its source — the bug paste/duplicate
already learned.
- `forkNodeCommand( engine: DiagramEngine, nodeId: string, offset: Point = { x: 160, y: 0 } ): Command | null` — Halo `fork`: clone the node AND link the original to the clone — one undo
step (MacroCommand). The link runs from an output-capable port on the source
to an input-capable port on the clone; null when either side has no usable port.

<!-- source: grafloria-renderer-interaction-snapcontroller.md -->

# SnapController

Import it from `@grafloria/renderer`.

```ts
class SnapController
```

**Methods**

- `constructor(config: Partial<SnapConfig> = {})`
- `getConfig(): SnapConfig`
- `updateConfig(patch: Partial<SnapConfig>): void`
- `syncWithEngineConfig(engine: DiagramEngine): void` — Read the snapping knobs off the engine's interaction config.

`snapToPortRadius` has existed in `InteractionConfig` since the first
interaction phase and was read by NOTHING — the config panel wrote it, the
default was 30, and no code path ever consulted it. This is the seam that
finally consumes it (see {@link findPortMagnet} / {@link findProximityConnection}),
along with the waypoint editor's grid settings.
- `computeSnap(box: Rectangle, others: Rectangle[]): SnapResult` — Snap `box` against `others`.

Precedence per axis (strongest first):
  1. alignment snapline (edge/centre) within `snapThreshold`
  2. equal-spacing guide within `snapThreshold`
  3. grid
then keep-in-bounds clamps whatever survived. Precedence matters: a grid snap
that fought an alignment snap would visibly jitter between the two.
- `snapPointToGrid(point: Point): Point` — Quantise a single point to the grid (used by the vertex drag).
- `keepInBounds(box: Rectangle, bounds: Rectangle): Rectangle` — Clamp a box so it stays fully inside `bounds` (no-op when it cannot fit).
- `siblingBoxes(engine: DiagramEngine, excludeIds: Iterable<string> = []): Rectangle[]` — World bounding boxes of every node EXCEPT `excludeIds` (the moving ones).
- `portPosition(node: NodeModel, port: PortModel): Point` — World position of a port — THE one the port is actually drawn at.

BUG: this used `port.getAbsolutePosition(node.getBoundingBox())`,
which walks the BOUNDING BOX and lands on an edge midpoint — blind to the
node's silhouette and to how many ports share the side. The renderer draws
ports with `getPortPositionForShape`. So on a circle, a diamond, a hexagon,
a cylinder — or ANY side carrying more than one port — the magnet was
snapping to a point several pixels away from the port you could see, and
proximity-connect measured its radius from the wrong place.
- `findPortMagnet( engine: DiagramEngine, worldX: number, worldY: number, options: { excludeNodeId?: string; radius?: number; filter?: (port: PortModel, node: NodeModel) => boolean; } = {} ): PortHit | null` — The nearest port to a world point within `snapToPortRadius` — the magnet the
connection drag snaps to. `excludeNodeId` keeps a drag from snapping back to
the node it started on.
- `findProximityConnection( engine: DiagramEngine, nodeId: string, radius?: number ): ProximityCandidate | null` — React-Flow-style proximity connect: after dragging `nodeId`, is one of ITS
ports close enough to a compatible port on another node to auto-link them?

Validity is the same rule the connection drag enforces: different nodes,
direction-compatible ports (output→input, or a `bi` port on either side),
allowed by the connection groups, and not already connected.
- `buildProximityLinkCommand(candidate: ProximityCandidate): Command` — Turn a candidate into the ONE undoable command that creates the link.
- `highlightProximityTarget(engine: DiagramEngine, candidate: ProximityCandidate | null): void` — Paint the nearest valid target: exactly the flags the SVG renderer already
draws for a connection drag (`isValidTarget` = eligible, `isHighlighted` =
the one that would win). Clears every other port so the highlight can never
go stale — the failure mode of "highlight on, nothing turns it off".

<!-- source: grafloria-renderer-interaction-toolhandle.md -->

# ToolHandle

Import it from `@grafloria/renderer`.

One grabbable tool in the floating layer.

```ts
interface ToolHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable key (also the DOM key a host keys its |
| `kind` | `ToolKind` |  |  |
| `world` | `Point` |  | Centre of the handle, in WORLD coordinates. |
| `hitRadius` | `number` |  | Hit radius in WORLD units (= screen px / zoom). |
| `segment?` | `{ a: Point; b: Point }` |  | resize-ux: for the four SIDE resize handles (n/e/s/w), the full edge they own, as a WORLD segment (rotated with the node). React Flow's side affordance is the whole border line, not a midpoint dot — the live audit found the 6px dots unreachable (fully inside the port's hover halo), so a side handle hit-tests as a BAND around this segment: grab the border anywhere and that edge follows. |
| `cursor` | `string` |  | CSS cursor a host should show over this handle. |
| `label` | `string` |  | Accessible name (also used for tooltips / ARIA). |
| `handleId?` | `ResizeHandleId` |  | For `resize`. |
| `action?` | `HaloAction` |  | For `halo`. |
| `endpoint?` | `'source' \| 'target'` |  | For `link-endpoint`. |
| `index?` | `number` |  | Vertex index (`vertex-remove`) or segment index (`vertex-add`). |
| `nodeId?` | `string` |  | Owning entity. |
| `linkId?` | `string` |  |  |

<!-- source: grafloria-renderer-interaction-waypointeditor.md -->

# WaypointEditor

Import it from `@grafloria/renderer`.

WaypointEditor

Handles interactive waypoint editing on link paths:
- Add waypoints by clicking on path
- Move waypoints by dragging
- Remove waypoints by double-click
- Grid snapping
- Distance constraints

Architecture: Modular tool that can be enabled/disabled via InteractionConfig

```ts
class WaypointEditor
```

**Methods**

- `constructor(config: WaypointEditorConfig)`
- `getWaypointAt(index: number, points: Point[]): Waypoint | null` — Get waypoint at specific index
- `isWaypoint(index: number, points: Point[]): boolean` — Check if point at index is a waypoint (not an endpoint)
- `getWaypoints(points: Point[]): Waypoint[]` — Get all waypoints (excluding endpoints)
- `hitTestWaypoint( mouseX: number, mouseY: number, points: Point[], hitSlop = 0 ): WaypointHitResult | null` — Hit test for clicking on a waypoint handle
Optimized to avoid allocations on hot path (mousemove)
- `hitTestPath( mouseX: number, mouseY: number, points: Point[], hitSlop = 0 ): PathHitResult | null` — Hit test for clicking on a path segment (to add waypoint)
- `addWaypointAtPosition( clickX: number, clickY: number, points: Point[] ): AddWaypointResult | null` — Add waypoint at click position on path
- `moveWaypoint( waypointIndex: number, newPosition: Point, points: Point[], pathType?: 'direct' | 'orthogonal' | 'smooth' | 'bezier' | 'straight' ): Point[] | null` — Move waypoint to new position
For orthogonal paths, just move the waypoint - the rendering will use orthogonal routing
- `removeWaypoint(waypointIndex: number, points: Point[]): Point[] | null` — Remove waypoint at index
- `snapToGrid(point: Point): Point` — Snap point to grid
- `distanceToSegment(point: Point, segmentStart: Point, segmentEnd: Point): number` — Calculate distance from point to line segment
- `distance(p1: Point, p2: Point): number` — Calculate Euclidean distance between two points
- `getConfig(): WaypointEditorConfig` — Get current configuration
- `updateConfig(updates: Partial<WaypointEditorConfig>): void` — Update configuration
- `renderWaypointHandle(waypoint: Waypoint, linkId: string): VNode` — Render waypoint handle as VNode
- `renderWaypointHandles(points: Point[], linkId: string): VNode[]` — Render all waypoint handles for a link

<!-- source: grafloria-renderer-lazy.md -->

# Lazy

Import these from `@grafloria/renderer`.

## Classes

### `HtmlHostCuller`

The per-frame cull decision for HTML-layer node hosts.

Stateless with respect to the hosts themselves: `admits()` is told whether the host is
currently attached rather than remembering it. That is on purpose — a culler holding its
own attached-set is a second copy of a fact the DOM already owns, and the two desync the
first time a node is removed from the model mid-gesture. The DOM is the record; this is
only the policy.

culler.beginFrame(viewport.getViewBox(), viewport.getZoom(), heldByGesture);
    for (const node of customNodes) {
      if (culler.admits(node.id, bounds(node), host?.isConnected ?? false)) …
    }

```ts
class HtmlHostCuller
```

**Methods**

- `constructor(options: HostCullOptions = {}, freeze: FreezeQuery | null = null)`
- `getMode(): HostCullMode`
- `beginFrame(visible: Rectangle, zoom: number, exempt: ReadonlySet<string>): void` — Fix this frame's two rects and the set of nodes a live gesture owns.

`visible` is the WORLD rect actually on screen — the viewBox, not the raw camera rect. They diverge the moment zoom != 1, and culling against the camera rect drops hosts that
are on screen whenever the board is zoomed out (which fit-to-content always does). The
SVG side learned this the hard way; see `svg-renderer.ts` `visibleRect`.
- `admits(id: string, bounds: Rectangle, attached: boolean): boolean` — Should this node's host be in the document on this frame?

### `ProgressiveMounter`

```ts
class ProgressiveMounter
```

**Methods**

- `constructor( engine: DiagramEngine, lifecycle: ViewLifecycle, frame: MountFrame, deferred: DeferredQuery )`
- `isRunning(): boolean`
- `mount(viewport: Rectangle, zoom: number, options: ProgressiveMountOptions = {}): Promise<MountStats>` — Bring the scene up in rAF-yielded slices. Resolves when everything culling
admits has a view (or when the mount is cancelled).
- `cancel(): void` — Stop mounting. Whatever is not yet mounted is mounted by the next normal render
— the gate is handed back here, so a cancelled mount can never strand half a
diagram on screen.
- `dispose(): void`

### `ViewLifecycle`

```ts
class ViewLifecycle implements MountGate
```

**Methods**

- `constructor(options: ViewLifecycleOptions = {})`
- `freeze(kind: EntityKind, id: string): void` — Give up this entity's view. It keeps its model and its spatial-index entry;
it stops being drawn and stops costing anything per frame.
- `unfreeze(kind: EntityKind, id: string): void` — Give it a view again. It is rebuilt on the next frame that can see it.
- `isFrozen(kind: EntityKind, id: string): boolean`
- `isExplicitlyFrozen(kind: EntityKind, id: string): boolean` — Explicitly frozen only — NOT the ones autoFreeze is holding off-screen.
- `unfreezeAll(): void`
- `setAutoFreeze(on: boolean): void`
- `isAutoFreeze(): boolean`
- `retainedCount(): number` — The views currently retained — i.e. what the renderer is paying for.

This is the number autoFreeze exists to bound, so it is measurable rather
than asserted.
- `frozenCount(): number`
- `retainVisible(visible: ReadonlyArray<readonly [EntityKind, string]>): void` — Called by the renderer each frame with what culling admitted, BEFORE the gate
is applied. Anything that was on screen and no longer is gets its view dropped.

Not called at all when autoFreeze is off — the whole feature is one Set diff
per frame, and a host that has not asked for it pays nothing.
- `beginDeferred(): void` — Defer EVERYTHING. Nothing has a view until `admit()` says so.
- `admit(kind: EntityKind, id: string): void` — Let this entity's view be built from now on.
- `admitAll(kind: EntityKind): void` — Admit a whole KIND without naming its members. Slice 0 uses this for nodes: a
node's view is cheap (no routing), and enumerating 10k ids to admit them one
at a time would cost more than building the ~56 views culling actually keeps.
- `endDeferred(): void` — The mount is over (finished, cancelled, or pre-empted). Gate opens fully.
- `admits(kind: EntityKind, id: string): boolean` — May the renderer build (or refresh) this entity's view on this frame?
- `isDeferring(): boolean` — True while a progressive mount is running — the renderer's cue that the scene
is being brought up in slices and is not yet whole.
- `setChangeHook(hook: (() => void) | null): void` — Tell the renderer that what it would draw has changed, even though the model
has not. Set by `SVGRenderer.setViewLifecycle`; see `changeHook`.

## Interfaces

### `FreezeQuery`

The sliver of `ViewLifecycle` that host culling honours.

`isExplicitlyFrozen`, NOT `admits`, and the distinction is load-bearing. `admits` is also
false for anything autoFreeze is holding off-screen, and autoFreeze decides that against
the bare viewport with no margin — routing custom hosts through it would silently
override the hysteresis band with a zero-width one. `isExplicitlyFrozen` is the signal
that a HOST deliberately said "this node has no view", which is a decision custom nodes
should obey.

```ts
interface FreezeQuery
```

**Members**

- `isExplicitlyFrozen(kind: EntityKind, id: string): boolean`

### `HostCullOptions`

```ts
interface HostCullOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `margin?` | `number` |  | How far beyond the viewport edge a host is still kept mounted, in CSS pixels. |
| `hysteresis?` | `number` |  | The extra distance, in CSS pixels, a host must travel BEYOND `margin` before it is culled. This is the hysteresis band, and it is the difference between culling and thrashing. |
| `mode?` | `HostCullMode` |  | What a cull does to the element. Default `'detach'` — see {@link HostCullMode}. |

### `MountGate`

The gate the renderer consults before instantiating an entity's VIEW.

A gate can only ever SUBTRACT from what culling already admitted — it never adds
an off-screen entity back in. That asymmetry is deliberate: a gate bug can make
something arrive late, never wrong.

```ts
interface MountGate
```

**Members**

- `admits(kind: EntityKind, id: string): boolean` — May the renderer build (or refresh) this entity's view on this frame?
- `isDeferring?(): boolean` — True while a progressive mount is running — the renderer's cue that the scene
is being brought up in slices and is not yet whole.

### `MountStats`

What one `mount()` actually did — the numbers the claim lives on.

```ts
interface MountStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `firstPaintMs` | `number` |  | ms from `mount()` to the first frame that reached the screen. |
| `completeMs` | `number` |  | Wall clock from `mount()` to the last entity mounted — INCLUDING the rAF waits. |
| `cpuMs` | `number` |  | CPU actually spent, summed over the slices — i.e. `completeMs` minus the time spent yielded to the browser. |
| `slices` | `number` |  | rAF slices used (1 = it all fitted in the first frame). |
| `nodesMounted` | `number` |  | Entities whose views were built. |
| `linksMounted` | `number` |  |  |
| `worstSliceMs` | `number` |  | The worst single slice — the jank a user would actually feel. |
| `aborted` | `boolean` |  | True if the mount was cancelled or pre-empted by a model change. |

### `ProgressiveMountOptions`

```ts
interface ProgressiveMountOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sliceMs?` | `number` |  | Target ms per slice. The chunk size adapts to hit it. Default 8 (half a 60fps frame). |
| `initialChunk?` | `number` |  | Links admitted by the FIRST link slice — the one slice with no measurement to adapt from. Default 4, deliberately timid: link costs are wildly skewed (a typical link routes in 3ms, a long one against 10k obstacles in 850ms), so a big opening chunk is a coin-flip on a multi-second stall. It ramps up fast from here when links are cheap. |
| `maxSlices?` | `number` |  | Hard cap on slices, so a pathological scene still terminates. Default 500. |
| `onFirstPaint?` | `(stats: Readonly<MountStats>) => void` |  |  |
| `onSlice?` | `(stats: Readonly<MountStats>) => void` |  |  |

### `ViewLifecycleOptions`

```ts
interface ViewLifecycleOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFreeze?` | `boolean` |  | Drop the view of any entity that leaves the viewport. Default false — the historical behaviour (views linger in the LRU until evicted by pressure). |

## Types

### `DeferredQuery`

What the renderer deferred on the last frame — culling admitted it, the gate did not.

```ts
type DeferredQuery = () => ReadonlyArray<readonly [EntityKind, string]>;
```

### `EntityKind`

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

The two things that have views.

```ts
type EntityKind = 'node' | 'link';
```

### `HostCullMode`

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

What a cull does to the host element.

`'detach'` — remove the element from the document and keep the reference. Re-entry
re-appends the SAME element: `renderCustomNode` is NOT called again, `removeCustomNode`
is NOT called on the cull, and everything inside the widget survives byte for byte.

`'destroy'` — fire `removeCustomNode` and drop the element. Re-entry re-creates the host
and re-runs `renderCustomNode`. Frees the widget's memory; costs a full re-init and every
piece of state the widget was holding.

`'detach'` is the default, and the reasoning is that the cost this feature exists to
remove is a cost of being ATTACHED. Layout, style recalc, paint, compositing and hit
testing are all charged per element IN THE DOCUMENT; a detached subtree is inert heap. Detaching therefore captures essentially the whole win while keeping the mount-once
guarantee that makes custom nodes usable at all. Measured on a 300-widget board with ~16
tiles on screen: 2720 DOM nodes under the canvas fall to 164, a 94% reduction, and a pan
away and back re-runs the painter exactly zero times.

What `'detach'` does NOT bound is the RETAINED set. A host mounted once is kept for the
life of the instance, so panning a 10,000-widget board end to end eventually holds 10,000
detached elements — the same "cache versus leak" distinction `ViewLifecycle`'s header
draws about autoFreeze, and the honest reason `'destroy'` exists. (Same board, after a
sweep across and back: 20 attached, 78 retained off-screen.) Choose `'destroy'` when the
widgets are individually huge — a WebGL scene, a 50k-row grid — and heap rather than
frame time is the binding constraint. It is opt-in inside an opt-in, because a host that
asks for it is accepting that its painter re-runs and its widget state is lost.

```ts
type HostCullMode = 'detach' | 'destroy';
```

### `MountFrame`

Produce and PRESENT one frame. Deliberately not "the SVG renderer": the SVG
patcher, the canvas backend and the tier-switching backend all satisfy this, so
a progressive mount works on any of them.

```ts
type MountFrame = (viewport: Rectangle, zoom: number) => void;
```

<!-- source: grafloria-renderer-perf.md -->

# Perf

Import these from `@grafloria/renderer`.

## Functions

### `formatSnapshot`

Format a snapshot for a human.

Deliberately calls out the ratios that reveal a bug rather than just printing
numbers: "culled 0/10000" reads as fine until you notice it means nothing was
culled. The HUD's job is to make that impossible to miss.

```ts
function formatSnapshot(s: PerfSnapshot): string[]
```

## Classes

### `PerfHud`

A DOM overlay, framework-free.

Absolutely positioned, `pointer-events: none` — a debug HUD that eats clicks is a
bug generator of its own. It is opt-in and never mounted unless asked for.

```ts
class PerfHud
```

**Methods**

- `constructor(private readonly host: HTMLElement)`
- `show(): void`
- `update(snapshot: PerfSnapshot): void`
- `hide(): void`

### `QualityGovernor`

```ts
class QualityGovernor
```

**Methods**

- `constructor(options: GovernorOptions = {})`
- `record(frameMs: number): QualityBias` — Feed the governor one frame time (ms). Returns the bias to render the NEXT frame at.
- `getBias(): QualityBias` — The bias to apply right now.
- `getState(): GovernorState`
- `effectiveTier(zoomTier: string, tiers: readonly string[]): string` — Apply the bias to a zoom-derived tier.

`tiers` must be ordered richest → poorest, which is the order the LOD config
declares them in. The governor can only ever make the picture SIMPLER than the
zoom asked for — never richer. A governor that could upgrade detail beyond what
the zoom wants would draw labels on 4px nodes to fill spare budget, which is
not a feature.
- `reset(): void` — Forget everything — e.g. after a diagram swap, where past frames say nothing.

## Constants

### `EMPTY_SNAPSHOT`

```ts
const EMPTY_SNAPSHOT: PerfSnapshot
```

## Interfaces

### `GovernorOptions`

```ts
interface GovernorOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `budgetMs?` | `number` |  | The frame budget. 16.7ms = 60fps. |
| `downFactor?` | `number` |  | Step DOWN when the median frame exceeds budget × this. Default 1.0 — the budget IS the line; there is no point having a budget you are content to miss. |
| `upFactor?` | `number` |  | Step UP only when the median frame is below budget × this. Default 0.55 — the DEAD BAND. A tier that renders at 0.9× budget is doing its job; restoring detail would put us straight back over it, which is the oscillation this exists to prevent. |
| `window?` | `number` |  | Frames in the rolling window. |
| `recoveryWindows?` | `number` |  | Consecutive fast windows required before restoring a tier. Recovery is patient. |
| `maxBias?` | `QualityBias` |  | Worst tier the governor may impose. |
| `panicFactor?` | `number` |  | ESCALATION. A frame this many times over budget is not a slow frame, it is a structurally wrong one — and waiting a full window to notice means 12 frames of a visibly locked-up canvas. Default 4× (≈67ms: a third of a second of these and the user is already reaching for the tab close button). |
| `panicWindow?` | `number` |  | How many frames the escalation path looks at. THREE, NOT ONE — and that is the whole subtlety. Reacting to a single catastrophic frame would make one GC pause indistinguishable from a scene the machine genuinely cannot draw. A median over three still rejects a lone spike (two of the three must be bad for the median to be bad) while reacting 4× sooner than the main window. |

### `GovernorState`

```ts
interface GovernorState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bias` | `QualityBias` |  |  |
| `medianMs` | `number` |  | Median frame time over the window — what the decision is actually made on. |
| `samples` | `number` |  | Frames recorded so far in the current window. |
| `recoveryStreak` | `number` |  | Consecutive fast windows accumulated toward a step back up. |
| `lastDecision` | `'steady' \| 'stepped-down' \| 'stepped-up' \| 'escalated'` |  | Why the governor last changed its mind — surfaced in the HUD, because an invisible governor is indistinguishable from a bug. |

### `PerfSnapshot`

```ts
interface PerfSnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fps` | `number` |  | Rolling FPS. |
| `frameMs` | `number` |  | Last frame, ms. |
| `nodes` | `number` |  | Entities in the model. |
| `links` | `number` |  |  |
| `visibleNodes` | `number` |  | Entities that survived viewport culling — i.e. what we actually paid for. |
| `visibleLinks` | `number` |  |  |
| `mountedViews` | `number` |  | Entities whose views exist in the DOM right now. |
| `dirtyNodes` | `number` |  | Entities re-rendered this frame. |
| `dirtyLinks` | `number` |  |  |
| `routedLinks` | `number` |  | Links whose route was recomputed this frame. Should be ~0 on an idle frame. |
| `tier` | `string` |  | The LOD tier actually rendered, and the governor's reasoning. |
| `governor?` | `GovernorState` |  |  |

## Types

### `QualityBias`

How many tiers below the zoom-derived one we are currently rendering.

```ts
type QualityBias = 0 | 1 | 2;
```

**Members**

- `toString(radix?: number): string` — Returns a string representation of an object.
- `toFixed(fractionDigits?: number): string` — Returns a string representing a number in fixed-point notation.
- `toExponential(fractionDigits?: number): string` — Returns a string containing a number represented in exponential notation.
- `toPrecision(precision?: number): string` — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.
- `valueOf(): number` — Returns the primitive value of the specified object.
- `toLocaleString(locales?: string | string[], options?: Intl.NumberFormatOptions): string` — Converts a number to a string by using the current or specified locale.

<!-- source: grafloria-renderer-presence.md -->

# Presence

Import these from `@grafloria/renderer`.

## Functions

### `actorColor`

Deterministic per-actor colour.

Deterministic MATTERS: the colour must be the same on every peer's screen, or "the blue
cursor is Ana" is true for you and false for me. Derived from the actor id, so no
coordination, no allocation table, and no message on the wire to agree.

```ts
function actorColor(actor: string): string
```

### `actorInitials`

```ts
function actorInitials(name: string): string
```

### `bindPresence`

Mount a presence overlay on a diagram and feed it from a sync session.

```ts
const diagram = createDiagram(el, { nodes, edges });
const session = createSyncSession(diagram.getModel(), transport, { actor: userId });
session.join();
bindPresence(diagram, session, { name: 'Ana' });
```

```ts
function bindPresence(
  instance: DiagramInstance,
  source: PresenceSource,
  options: BindPresenceOptions = {}
): PresenceBinding
```

### `contrastingTextColor`

Black or white — whichever is actually READABLE on `background`.

---------------------------------------------------------------------------
FOUND BY AXE, IN THE a11y GATE, AFTER THE UNIT TESTS WERE ALL GREEN
---------------------------------------------------------------------------
The name badge was white text on the peer's colour. For a blue or purple actor that is
fine. For a green or yellow one — `hsl(124, 72%, 52%)` — it is white on light green, a
contrast ratio of about 2:1, and a user with low vision simply cannot read whose cursor
it is. It is a coin flip decided by a hash of the actor id, which is the worst kind of
accessibility bug: it works on your machine, for your account, every time you test it.

The unit tests could not have caught this. They assert `aria-hidden="true"`, which is
about ASSISTIVE TECH — and this is not an AT problem at all. It is a problem for someone
looking straight at the screen with their eyes. Only the real axe audit over a real page
with real badges on it could find it, which is the entire argument for that gate existing.

(Note that `aria-hidden` does NOT excuse it, and axe is right to say so: hiding text from
a screen reader does not hide it from a sighted user with poor contrast sensitivity.)

THE MATH. Pick whichever of pure black and pure white contrasts better. The two curves
cross at a background luminance of ~0.179, where BOTH give 4.58:1 — above the 4.5:1 WCAG
AA threshold for normal text. So this choice is guaranteed to pass for EVERY hue, not
merely for the ones I happened to look at.

```ts
function contrastingTextColor(background: string): string
```

## Classes

### `PresenceOverlay`

The presence layer.

Owns one `<div>` inside the diagram root, and nothing else. It does not know about the
SVGRenderer, the VNodePatcher, the RenderScheduler or the model, and it must not: the
moment it can reach the render loop, someone will make it call into it.

```ts
class PresenceOverlay
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `framesRun` |  | `0` | Interpolation frames actually run. An idle overlay must add ZERO. |

**Methods**

- `constructor(private readonly options: PresenceOverlayOptions)`
- `get element(): HTMLElement` — For the tests and the a11y audit — the DOM this owns, and nothing more.
- `get peerCount(): number`
- `setPeers(peers: readonly PresencePeer[]): void` — Publish the full peer set. Idempotent, and a peer that is gone is REMOVED — presence
has no tombstones and no history; the current picture is the entire truth.
- `remove(actor: string): void`
- `clear(): void`
- `dispose(): void`

## Constants

### `PRESENCE_LAYER_CLASS`

```ts
const PRESENCE_LAYER_CLASS: "grafloria-presence-layer"
```

## Interfaces

### `BindPresenceOptions`

```ts
interface BindPresenceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  | Our own display name — what the OTHER peers put on our badge. |
| `color?` | `string` |  | Our own colour. Omit and one is derived deterministically from the actor id. |
| `publishCursor?` | `boolean` |  | Publish the local cursor. Off ⇒ we see others but they do not see us. |
| `publishSelection?` | `boolean` |  | Publish the local selection. |
| `smoothing?` | `number` |  | Interpolation factor for remote cursors (0 = snap). |
| `requestFrame?` | `(cb: () => void) => number` |  |  |
| `cancelFrame?` | `(handle: number) => void` |  |  |

### `PresenceBinding`

```ts
interface PresenceBinding
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `overlay` | `PresenceOverlay` |  |  |

**Members**

- `dispose(): void`

### `PresenceOverlayOptions`

```ts
interface PresenceOverlayOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement` |  | The mounted diagram's root — `.grafloria-diagram-root`. |
| `viewport` | `ViewportController` |  |  |
| `getBounds?` | `BoundsLookup` |  | Where a selected entity is, in world space. Usually `model.getNode(id)`. |
| `smoothing?` | `number` |  | Interpolate remote cursors toward their target. 0 disables (jumps straight there). |
| `requestFrame?` | `(cb: () => void) => number` |  | Injectable rAF, so the interpolation tests are deterministic. |
| `cancelFrame?` | `(handle: number) => void` |  |  |

### `PresencePeer`

One peer, as far as the overlay is concerned. Ephemeral by construction.

```ts
interface PresencePeer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `string` |  |  |
| `name?` | `string` |  |  |
| `color?` | `string` |  |  |
| `cursor?` | `{ x: number; y: number } \| null` |  | WORLD coordinates — never screen: peers have different cameras. |
| `selection?` | `string[]` |  | Entity ids this peer has selected. |

### `PresenceSource`

What presence needs from a sync session — STRUCTURAL, not the concrete `SyncAdapter`.

The renderer therefore gains no hard dependency on the sync layer, a host can drive
presence from its own backend (a Firebase channel, a Phoenix presence, a server-sent
event stream) without adopting our transport at all, and a test can hand it a fake. The
real `SyncAdapter` satisfies it exactly, which is what `presence-reachability.spec.ts`
proves.

```ts
interface PresenceSource
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `string` |  |  |
| `awareness` | `{ getPeers(): Array<{ actor: string; state: Record<string, unknown> }>; onChange(listener: () => void): () => void; }` |  |  |

**Members**

- `setAwareness(patch: Record<string, unknown>): void`

## Types

### `BoundsLookup`

World-space box of an entity, so the overlay can outline a remote selection.

```ts
type BoundsLookup = (entityId: string) => { x: number; y: number; width: number; height: number } | null;
```

<!-- source: grafloria-renderer-presentation.md -->

# Presentation

Import these from `@grafloria/renderer`.

## Functions

### `followPresenter`

Slave this host's camera to the presenter's, for as long as the handle is alive.

The follower keeps its OWN canvas size and reconstructs the camera rectangle from
the presenter's centre + zoom, so a follower on a different screen size sees the
same content correctly framed — and, critically, its `clientToWorld()` stays the
exact inverse of what it renders. Copying the presenter's rectangle wholesale
would break that (see viewport-channel.ts).

```ts
function followPresenter(
  host: PresentationHost,
  channel: ViewportChannel,
  options: FollowOptions = {}
): { stop: Unsubscribe }
```

### `isDocumentLocked`

Is this engine's document locked against edits?

```ts
function isDocumentLocked(engine: DiagramEngine): boolean
```

### `loadReadonlySnapshot`

Build a READ-ONLY document from a snapshot — the "share a link to a frozen copy"
case.

The load runs as a SYSTEM write, so it works even against an engine that is
already in presentation mode. Otherwise the order of two host calls would decide
whether the share link renders a diagram or an empty canvas: lock-then-load would
have the lock (correctly!) refuse every node the loader tried to add.

```ts
function loadReadonlySnapshot(
  engine: DiagramEngine,
  snapshot: SerializedDiagram
): DiagramModel
```

### `lockDocument`

Lock (or unlock) the document through the engine's own mode.

Thin on purpose: it drives `DiagramMode`, which this wave finally wired to real
enforcement in the model and the CommandManager. There is no second read-only
flag here, because a second flag is how you end up with two read-only modes that
disagree.

```ts
function lockDocument(engine: DiagramEngine, locked = true): void
```

### `presentTo`

Broadcast this host's camera to `channel` for as long as the returned handle is
alive. Returns a `stop()` that unsubscribes and cancels any pending trailing send.

```ts
function presentTo(
  host: PresentationHost,
  channel: ViewportChannel,
  options: PresentOptions = {}
): { stop: Unsubscribe }
```

## Classes

### `InMemoryViewportChannel`

A working, in-process implementation — the local/in-memory transport this card
ships so the feature is demonstrably complete end-to-end rather than an interface
with nothing behind it.

Genuinely useful beyond tests: it drives two `createDiagram()` instances on the
same page (a presenter canvas and a follower/minimap canvas), which is a real
product surface. Swap it for the network implementation and nothing else moves.

```ts
class InMemoryViewportChannel implements ViewportChannel
```

**Methods**

- `broadcastViewport(viewport: PresenterViewport): void` — Publish the presenter's current view to every follower.
- `onViewportBroadcast(callback: (viewport: PresenterViewport) => void): Unsubscribe` — Subscribe to presenter broadcasts. Returns an unsubscribe function.
- `getLast(): PresenterViewport | null` — The most recent broadcast, or null.
- `dispose(): void` — Drop all subscribers (teardown).

## Interfaces

### `FollowOptions`

```ts
interface FollowOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ignorePresenterId?` | `string` |  | Ignore broadcasts carrying this presenterId — i.e. my own. |
| `onFollow?` | `(viewport: PresenterViewport) => void` |  | Called whenever a presenter's viewport is applied (for a "following X" badge). |

### `PresentationHost`

The minimum a host must expose to be presented from / followed. `DiagramInstance` satisfies it.

```ts
interface PresentationHost
```

**Properties**

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

**Members**

- `render(): void` — Queue a repaint.

### `PresenterViewport`

What a presenter broadcasts. Centre + zoom, deliberately NOT a camera rect.

```ts
interface PresenterViewport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `centerX` | `number` |  | World X of the centre of the presenter's view. |
| `centerY` | `number` |  | World Y of the centre of the presenter's view. |
| `zoom` | `number` |  | The presenter's magnification. |
| `presenterId?` | `string` |  | Who is presenting. Lets a follower ignore its own echo, and label the UI. |

### `PresentOptions`

```ts
interface PresentOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `presenterId?` | `string` |  | Identifies this presenter on the wire; echoed back in the payload. |
| `throttleMs?` | `number` |  | Coalesce broadcasts to at most one per N ms. Default 50 (≈20/s). |

### `ViewportChannel`

The transport seam. Two methods, no lifecycle, no assumptions about the wire. Implement over WebSocket / WebRTC / Yjs awareness / BroadcastChannel / postMessage.

```ts
interface ViewportChannel
```

**Members**

- `broadcastViewport(viewport: PresenterViewport): void` — Publish the presenter's current view to every follower.
- `onViewportBroadcast(callback: (viewport: PresenterViewport) => void): Unsubscribe` — Subscribe to presenter broadcasts. Returns an unsubscribe function.

<!-- source: grafloria-renderer-services.md -->

# Services

Import these from `@grafloria/renderer`.

## Functions

### `createSequencer`

Create a new animation sequencer

```ts
function createSequencer(
  animationRegistry?: CustomAnimationRegistry,
  lifecycleManager?: AnimationLifecycleManager
): AnimationSequencer
```

### `fadeInSequence`

Helper: Create a simple fade in sequence

```ts
function fadeInSequence(elements: HTMLElement[], delay: number = 100): AnimationSequencer
```

### `getGlobalAnimationLifecycleManager`

Get the global animation lifecycle manager

```ts
function getGlobalAnimationLifecycleManager(): AnimationLifecycleManager
```

### `getGlobalCustomAnimationRegistry`

Get the global custom animation registry

```ts
function getGlobalCustomAnimationRegistry(): CustomAnimationRegistry
```

### `resetGlobalAnimationLifecycleManager`

Reset the global lifecycle manager (useful for testing)

```ts
function resetGlobalAnimationLifecycleManager(): void
```

### `resetGlobalCustomAnimationRegistry`

Reset the global registry (useful for testing)

```ts
function resetGlobalCustomAnimationRegistry(): void
```

### `staggerSequence`

Helper: Create a stagger animation sequence

```ts
function staggerSequence(
  elements: HTMLElement[],
  animationName: string,
  staggerDelay: number = 100,
  options?: AnimationStepOptions
): AnimationSequencer
```

## Classes

### `AnimationLifecycleManager`

Animation Lifecycle Manager

Manages lifecycle event listeners for CSS animations

```ts
class AnimationLifecycleManager
```

**Methods**

- `constructor()`
- `trackElement(element: HTMLElement): void` — Track an element for animation events
- `untrackElement(element: HTMLElement): void` — Untrack an element
- `on(eventType: AnimationLifecycleEvent, animationName: string, callback: LifecycleCallback): () => void` — Listen to a specific animation lifecycle event
- `onAll(eventType: AnimationLifecycleEvent, callback: LifecycleCallback): () => void` — Listen to all animations for a specific event type
- `onElement(element: HTMLElement, eventType: AnimationLifecycleEvent, callback: LifecycleCallback): () => void` — Listen to animations on a specific element
- `off(eventType: AnimationLifecycleEvent, animationName: string): void` — Remove all listeners for a specific animation
- `waitFor(animationName: string, element?: HTMLElement): Promise<AnimationEventData>` — Wait for an animation to end
Returns a promise that resolves when the animation ends
- `waitForElement(element: HTMLElement): Promise<AnimationEventData>` — Wait for any animation to complete on an element
- `getTrackedElements(): HTMLElement[]` — Get all tracked elements
- `isTracking(element: HTMLElement): boolean` — Check if element is being tracked
- `destroy(): void` — Cleanup: Remove all listeners and untrack all elements

### `AnimationPerformanceService`

Animation Performance Service

Monitors animation performance and provides metrics

```ts
class AnimationPerformanceService
```

**Methods**

- `constructor(thresholds?: Partial<PerformanceThresholds>)`
- `startMonitoring(): void` — Start performance monitoring
- `stopMonitoring(): void` — Stop performance monitoring
- `getMetrics(): Readonly<AnimationMetrics>` — Get current metrics
- `getFPSHistory(): number[]` — Get FPS history
- `updateThresholds(thresholds: Partial<PerformanceThresholds>): void` — Update performance thresholds
- `getThresholds(): Readonly<PerformanceThresholds>` — Get current thresholds
- `onMetricsUpdate(listener: (metrics: AnimationMetrics) => void): () => void` — Subscribe to metrics updates
- `onPerformanceWarning(listener: (warning: PerformanceWarningEvent) => void): () => void` — Subscribe to performance warnings
- `reset(): void` — Reset metrics
- `isMonitoring(): boolean` — Check if monitoring is active
- `getSummary(): string` — Get performance summary
- `destroy(): void` — Cleanup

### `AnimationSequencer`

Animation Sequencer

Manages sequences of animations

```ts
class AnimationSequencer
```

**Methods**

- `constructor( animationRegistry?: CustomAnimationRegistry, lifecycleManager?: AnimationLifecycleManager )`
- `add(element: HTMLElement, animationName: string, options?: AnimationStepOptions): this` — Add a single animation step
- `parallel(animations: Array<{ element: HTMLElement; animationName: string; options?: AnimationStepOptions; }>): this` — Add multiple animations to run in parallel
- `delay(duration: number): this` — Add a delay
- `then(callback: () => void | Promise<void>): this` — Add a callback step
- `onComplete(callback: () => void): this` — Add completion callback
- `async play(): Promise<void>` — Play the sequence
- `pause(): void` — Pause the sequence
- `resume(): void` — Resume the sequence
- `cancel(): void` — Cancel the sequence
- `reset(): void` — Reset the sequence
- `getState(): SequenceState` — Get current state
- `getCurrentStepIndex(): number` — Get current step index
- `getTotalSteps(): number` — Get total number of steps
- `getSteps(): AnimationStep[]` — Get all steps
- `clear(): void` — Clear all steps
- `clone(): AnimationSequencer` — Clone this sequencer (creates a new instance with the same steps)
- `exportToJSON(): string` — Export sequence as JSON

### `AnimationService`

AnimationService - Manages all diagram animations

Features:
- Detects and respects prefers-reduced-motion
- Provides global animation enable/disable
- Generates animation CSS classes for nodes and links
- Supports animation speed control
- Performance and battery saving modes

```ts
class AnimationService
```

**Methods**

- `constructor(config?: Partial<AnimationConfig>)`
- `setEnabled(enabled: boolean): void` — Enable or disable all animations globally
- `getConfig(): Readonly<AnimationConfig>` — Get current configuration
- `updateConfig(config: Partial<AnimationConfig>): void` — Update configuration (partial update)
- `getEdgeAnimationClass(link: LinkModel): string` — Get animation CSS classes for an edge (link)
- `getNodeAnimationClass(node: NodeModel, useSVGVariant: boolean = false): string` — Get animation CSS classes for a node
- `getAnimationDuration(baseDuration: number): number` — Calculate animation duration with speed multiplier applied
- `pauseAllAnimations(): void` — Pause all animations (for debugging or screenshots)
- `resumeAllAnimations(): void` — Resume all animations
- `onConfigChange(listener: (config: AnimationConfig) => void): () => void` — Add listener for configuration changes
- `resetConfig(): void` — Reset configuration to defaults
- `injectCSS(): void` — Inject animation CSS into the document
This is called automatically when lazyLoadCSS is enabled and first animation is used
- `removeCSS(): void` — Remove injected animation CSS from the document
- `isCSSInjected(): boolean` — Check if CSS has been injected
- `destroy(): void` — Cleanup: Remove event listeners and injected CSS

### `CustomAnimationRegistry`

Custom Animation Registry

Manages custom animations and applies them to elements

```ts
class CustomAnimationRegistry
```

**Methods**

- `constructor()`
- `register(definition: CustomAnimationDefinition): void` — Register a custom animation
- `unregister(name: string): boolean` — Unregister a custom animation
- `get(name: string): CustomAnimationDefinition | undefined` — Get animation definition
- `has(name: string): boolean` — Check if animation exists
- `getAll(): CustomAnimationDefinition[]` — Get all registered animations
- `getByTag(tag: string): CustomAnimationDefinition[]` — Get animations by tag
- `getByTargetType(type: 'node' | 'edge' | 'both'): CustomAnimationDefinition[]` — Get animations by target type
- `applyToElement(element: HTMLElement, animationName: string): boolean` — Apply animation to an element
- `removeFromElement(element: HTMLElement, animationName: string): void` — Remove animation from an element
- `onAnimationApplied(animationName: string, listener: (element: HTMLElement) => void): () => void` — Subscribe to animation applications
- `getElementsWithAnimation(animationName: string): HTMLElement[]` — Get all elements with a specific animation applied
- `getElementAnimations(element: HTMLElement): string[]` — Get all animations applied to an element
- `clearElement(element: HTMLElement): void` — Clear all animations from an element
- `clearAll(): void` — Clear all animations
- `registerBatch(definitions: CustomAnimationDefinition[]): void` — Batch register multiple animations
- `exportToJSON(): string` — Export all animations as JSON
- `importFromJSON(json: string): void` — Import animations from JSON
- `destroy(): void` — Cleanup

## Interfaces

### `AnimationConfig`

```ts
interface AnimationConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  | Enable/disable all animations globally |
| `reducedMotion` | `boolean` |  | Respect user's prefers-reduced-motion system setting |
| `defaultEdgeAnimation` | `'marching-ants' \| 'flow' \| 'pulse' \| 'none'` |  | Default animation type for edges |
| `defaultNodeBorderAnimation` | `'gradient' \| 'pulse' \| 'breathe' \| 'shimmer' \| 'none'` |  | Default border animation type for nodes |
| `animationSpeed` | `number` |  | Global speed multiplier (0.5 = half speed, 2 = double speed) |
| `autoDetectMotionPreference` | `boolean` |  | Auto-detect and respect system motion preferences |
| `performanceMode` | `boolean` |  | Performance mode (simplifies animations) |
| `batterySavingMode` | `boolean` |  | Battery saving mode (disables expensive animations) |
| `respectBatteryStatus` | `boolean` |  | Auto-engage {@link batterySavingMode} from the (experimental) Battery Status API when the device is below 20% and not charging. Default true — but it is a HOST decision: with no off switch, a laptop dipping under 20% silently killed every edge animation (and turned the demo gallery's animation gates red on an unplugged machine — that is how this flag was born). |
| `lazyLoadCSS` | `boolean` |  | Lazy load CSS (only inject when first animation is used) |

### `AnimationEventData`

Animation event data

```ts
interface AnimationEventData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `animationName` | `string` |  | Animation name |
| `element` | `HTMLElement` |  | Element the animation is applied to |
| `type` | `AnimationLifecycleEvent` |  | Event type |
| `elapsedTime` | `number` |  | Elapsed time when event occurred |
| `pseudoElement?` | `string` |  | Pseudo-element (if applicable) |
| `originalEvent` | `AnimationEvent` |  | Original AnimationEvent |
| `timestamp` | `number` |  | Timestamp |

### `AnimationMetrics`

Performance metrics snapshot

```ts
interface AnimationMetrics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fps` | `number` |  | Current frames per second |
| `averageFps` | `number` |  | Average FPS over monitoring period |
| `minFps` | `number` |  | Minimum FPS recorded |
| `maxFps` | `number` |  | Maximum FPS recorded |
| `animatedElementCount` | `number` |  | Number of currently animated elements |
| `animatedNodeCount` | `number` |  | Number of animated nodes |
| `animatedEdgeCount` | `number` |  | Number of animated edges |
| `frameDrops` | `number` |  | Total frame drops detected |
| `memoryUsage?` | `number` |  | Memory usage (if available) |
| `cpuUsage?` | `number` |  | CPU usage estimate (0-100) |
| `timestamp` | `number` |  | Timestamp of metrics |
| `monitoringDuration` | `number` |  | Monitoring duration in seconds |

### `AnimationStepOptions`

Animation step options

```ts
interface AnimationStepOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `duration?` | `string` |  | Animation duration |
| `timingFunction?` | `string` |  | Timing function |
| `delay?` | `string` |  | Delay before starting |
| `iterationCount?` | `string` |  | Iteration count |
| `direction?` | `string` |  | Direction |
| `fillMode?` | `string` |  | Fill mode |

### `AppliedAnimation`

Applied animation instance

```ts
interface AppliedAnimation
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `element` | `HTMLElement` |  |  |
| `startTime` | `number` |  |  |
| `definition` | `CustomAnimationDefinition` |  |  |

### `CustomAnimationDefinition`

Custom animation definition

```ts
interface CustomAnimationDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Unique name for the animation |
| `keyframes` | `string` |  | CSS keyframes definition |
| `duration?` | `string` |  | Animation duration (e.g., '1s', '500ms') |
| `timingFunction?` | `string` |  | Timing function (e.g., 'ease', 'linear', 'ease-in-out') |
| `iterationCount?` | `string` |  | Iteration count (e.g., 'infinite', '3', '1') |
| `direction?` | `string` |  | Animation direction (e.g., 'normal', 'reverse', 'alternate') |
| `fillMode?` | `string` |  | Fill mode (e.g., 'none', 'forwards', 'backwards', 'both') |
| `delay?` | `string` |  | Delay before animation starts (e.g., '0s', '200ms') |
| `playState?` | `string` |  | Play state (e.g., 'running', 'paused') |
| `willChange?` | `string[]` |  | CSS properties that will change (for will-change hint) |
| `description?` | `string` |  | Description of the animation (for documentation) |
| `tags?` | `string[]` |  | Tags for categorization |
| `targetType?` | `'node' \| 'edge' \| 'both'` |  | Target type: 'node', 'edge', or 'both' |

### `PerformanceThresholds`

Performance threshold configuration

```ts
interface PerformanceThresholds
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minFps` | `number` |  | Minimum acceptable FPS (default: 30) |
| `maxAnimatedElements` | `number` |  | Maximum animated elements before warning (default: 100) |
| `maxFrameDrops` | `number` |  | Maximum frame drops before warning (default: 10) |
| `maxMemoryMB` | `number` |  | Maximum memory usage in MB (default: 100) |
| `maxFrameTime` | `number` |  | Maximum frame time in ms (default: 50) |

### `PerformanceWarningEvent`

Performance warning event

```ts
interface PerformanceWarningEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `PerformanceWarning` |  |  |
| `message` | `string` |  |  |
| `metrics` | `AnimationMetrics` |  |  |
| `timestamp` | `number` |  |  |

## Types

### `AnimationLifecycleEvent`

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

Animation lifecycle event types

```ts
type AnimationLifecycleEvent = 'start' | 'end' | 'iteration' | 'cancel';
```

### `AnimationStep`

Animation step union type

```ts
type AnimationStep = SingleAnimationStep | ParallelAnimationStep | DelayStep | CallbackStep;
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'single'` |  |  |

### `LifecycleCallback`

Lifecycle callback function

```ts
type LifecycleCallback = (data: AnimationEventData) => void;
```

### `SequenceState`

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

Sequence playback state

```ts
type SequenceState = 'idle' | 'playing' | 'paused' | 'completed' | 'cancelled';
```

## Enums

### `PerformanceWarning`

Performance warning types

```ts
enum PerformanceWarning
```

**Members**

- `LOW_FPS = 'LOW_FPS'`
- `HIGH_ELEMENT_COUNT = 'HIGH_ELEMENT_COUNT'`
- `FRAME_DROPS = 'FRAME_DROPS'`
- `HIGH_MEMORY = 'HIGH_MEMORY'`
- `LONG_FRAMES = 'LONG_FRAMES'`

<!-- source: grafloria-renderer-svg.md -->

# Svg

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-classes): 6 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-constants): 16 constants.
- [Functions A–P](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-functions-a-p): 66 functions, `applySpread` to `parallelOffsets`.
- [Functions P–W](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-functions-p-w): 39 functions, `pointAtPositionOnPolyline` to `wrapText`.
- [Interfaces A–O](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-interfaces-a-o): 26 interfaces, `AutoSizeOptions` to `OptimizerFrame`.
- [Interfaces O–S](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-interfaces-o-s): 29 interfaces, `OptimizerLabel` to `SpotInput`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-types): 12 types.
- [`ArrowRenderer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-arrowrenderer): ArrowRenderer generates SVG VNodes for different arrow types.
- [`ShapeDefinition`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-shapedefinition): The single geometry contract every node shape implements. Register once via
- [`SVGRenderer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-svgrenderer)
- [`TextBlockOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-svg-textblockoptions)

<!-- source: grafloria-renderer-svg-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `EdgeOptimizer`

```ts
class EdgeOptimizer
```

**Methods**

- `constructor(options: EdgeOptimizerOptions = {})`
- `get stats(): Readonly<OptimizerStats>`
- `update(frame: OptimizerFrame): void` — Run the pass for a frame. Cheap when little changed: a frame whose links and
nodes all carry the same signatures as last time performs zero segment tests
and zero label searches.
- `getJumps(linkId: string): Intersection[]` — The crossings on this link, for the jump-point path builder. Empty when the
link draws no jumps.
- `getLabelOffset(linkId: string, labelId: string, fallback: Point): Point` — The offset this label should actually be drawn at. For a label that did not
opt into `autoOffset` this is exactly the offset the author set.
- `reset(): void` — Drop all state (renderer disposal, or a wholesale diagram swap).

### `JumpPointDetector`

JumpPointDetector detects line-line intersections for jump point rendering.

Features:
- Line segment intersection detection
- Angle calculation between intersecting lines
- Multiple detection modes (all, perpendicular, threshold)
- Performance optimized for many links

Algorithm:
Uses parametric line intersection algorithm with bounds checking.

```ts
class JumpPointDetector
```

**Methods**

- `findIntersection(line1: LineSegment, line2: LineSegment): Intersection | null` — Find intersection between two line segments
- `detectIntersections( targetLink: LinkWithPoints, otherLinks: LinkWithPoints[], mode: DetectionMode = 'all', threshold: number = 45 ): Intersection[]` — Detect all intersections for a link with other links

### `JumpPointRenderer`

JumpPointRenderer modifies link paths to show jump points at intersections.

Supports three visual styles:
- arc: Small arc over intersection
- gap: Break in line
- bridge: Bridge shape over intersection

Algorithm:
1. Parse path to extract points
2. Sort intersections by position
3. Split path at intersections
4. Insert jump point geometry
5. Reconstruct path

```ts
class JumpPointRenderer
```

**Methods**

- `renderWithJumpPoints( pathData: string, intersections: Intersection[], config: JumpPointConfig, originalProps?: Record<string, any> ): VNode` — Render path with jump points at intersections

### `LabelRenderer`

LabelRenderer generates SVG (or HTML) VNodes for link labels.

Features:
- Position labels at any point along path (0-1), or in one of three slots
- Auto-rotation with path or fixed angle
- Text wrapping with maxWidth
- Multiple labels per link
- Rich styling support
- HTML content and author templates

Architecture:
Uses LinkModel utilities (getPointAtPosition, getAngleAt) for positioning. Returns VNode tree compatible with framework-agnostic rendering.

```ts
class LabelRenderer
```

**Methods**

- `renderLabel(label: LinkLabel, link: LinkModel, context: LabelRenderContext = {}): VNode | null` — Render a label on a link
- `labelBox(label: LinkLabel): { width: number; height: number }` — Estimated on-screen box of a label, in LOCAL units (before the path anchor
and offset are applied). The edge optimizer needs a box to test collisions
against; HTML/template labels declare their own, and text labels are
measured with the same estimator the background rect already uses.

### `RouteMemo`

```ts
class RouteMemo
```

**Methods**

- `get stats(): Readonly<RouteMemoStats>`
- `get size(): number`
- `beginFrame(rects: Map<string, Rect>, obstacleEpoch: string): Rect[]` — Start a frame. Diffs this frame's node rectangles against last frame's and
returns the world regions that changed — each moved node contributes BOTH
where it was and where it now is, because a link routed around its old
position is just as stale as one routed through its new one.

`obstacleEpoch` covers obstacle-set changes that are NOT node rects — a
group collapsing hides its members and adds a block, and no node moved. A
change there drops the whole cache, which is the honest thing to do: it is
rare, and reasoning about which links a collapse touched is how you ship a
stale route.
- `lookup(linkId: string, key: string): RoutedPath | undefined` — The route for this link if its inputs are unchanged since we cached it.
- `store(linkId: string, key: string, routed: RoutedPath): void`
- `drop(linkId: string): void` — A route computed but NOT cacheable (e.g. no route found) must not keep a stale entry.
- `invalidate(linkIds: Iterable<string>): void`
- `clear(): void`

### `RouteSolverBridge`

```ts
class RouteSolverBridge
```

**Methods**

- `constructor(options: RouteSolverBridgeOptions = {})`
- `get stats(): Readonly<RouteSolverStats>`
- `hasRoutesFor(version: number): boolean` — True once the solver has an answer for THIS world — i.e. one safe to paint.
- `routeFor(linkId: string, version: number): RoutedPath | undefined`
- `submit(version: number, edges: SolverEdge[], obstacles: Obstacle[]): void` — Ask for this world to be solved. Idempotent per version: submitting the same
world twice does nothing, so calling this every frame is free.

If a solve is already running for an older world, the new one is QUEUED, not
raced — and if a third arrives first, it replaces the queued one. At most one
solve in flight, and the newest world always wins.
- `dispose(): void`

<!-- source: grafloria-renderer-svg-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `BUILTIN_ICONS`

Grafloria's line icons, 24×24, stroked (never filled). Drawn by hand for this
library — the five Mermaid architecture-beta names. An href icon must be a
raster data URI (SVG data URIs are refused: SVG can carry script), so vector
icons are these paths, not user data.

```ts
const BUILTIN_ICONS: Readonly<Record<string, readonly string[]>>
```

### `DEFAULT_ARROW_RADIUS`

```ts
const DEFAULT_ARROW_RADIUS: 10
```

### `DEFAULT_ENDPOINT_RADIUS`

```ts
const DEFAULT_ENDPOINT_RADIUS: 8
```

### `DEFAULT_HTML_LABEL_HEIGHT`

```ts
const DEFAULT_HTML_LABEL_HEIGHT: 28
```

### `DEFAULT_HTML_LABEL_WIDTH`

Default box for an HTML / template label (a `foreignObject` needs a size).

```ts
const DEFAULT_HTML_LABEL_WIDTH: 120
```

### `DEFAULT_LABEL_HEIGHT`

```ts
const DEFAULT_LABEL_HEIGHT: 18
```

### `DEFAULT_LABEL_WIDTH`

```ts
const DEFAULT_LABEL_WIDTH: 40
```

### `DEFAULT_LINK_HIT_AREA_WIDTH`

Default width of the SVG renderer's transparent interaction stroke.

```ts
const DEFAULT_LINK_HIT_AREA_WIDTH: 12
```

### `DEFAULT_LINK_HIT_TOLERANCE`

Grab distance (WORLD units) for a link body — "how close to the line counts
as clicking it".

Exported because it is now a CROSS-BACKEND contract, not an implementation
detail of one hit path: `InteractionController` applies it to resolve a link
in SVG mode, and the Canvas backend strokes each link's pick region with
exactly `2 x` this width on the colour-keyed hit canvas. If the two ever
disagreed, switching backend would change which link is under the cursor. (It was previously a bare `5` inlined in the controller.)

This is the FLOOR, not the whole contract — see {@link linkBodyHitTolerance}.

```ts
const DEFAULT_LINK_HIT_TOLERANCE: 5
```

### `DEFAULT_PARALLEL_SPACING`

Default gap between adjacent links of a parallel bundle.

```ts
const DEFAULT_PARALLEL_SPACING: 16
```

### `DEFAULT_SELF_LOOP_SIZE`

Default self-loop bulge / lateral span / per-loop growth.

```ts
const DEFAULT_SELF_LOOP_SIZE: 40
```

### `DEFAULT_SELF_LOOP_SPACING`

```ts
const DEFAULT_SELF_LOOP_SPACING: 18
```

### `GRAFLORIA_BASE_STYLE_ID`

Id of the SHARED stylesheet: the theme-independent, `var(--grafloria-*)`-based
rules. Identical for every renderer on the page, so it is injected once and
deduped by this id — instances only own their tiny variable block.

```ts
const GRAFLORIA_BASE_STYLE_ID: "grafloria-renderer-styles"
```

### `GRAFLORIA_INSTANCE_OVERRIDE_PREFIX`

Prefix of a renderer's OVERRIDE `<style>` element — the design-token bridge and
the accessibility media queries.

A SEPARATE element from the theme block, and always inserted after it, because
the cascade inside the variables is the whole mechanism:
  theme values  <  host design tokens  <  prefers-contrast  <  forced-colors
Same selector, same specificity — so only SOURCE ORDER decides, and source
order is only guaranteed if we own it.

```ts
const GRAFLORIA_INSTANCE_OVERRIDE_PREFIX: "grafloria-renderer-overrides-"
```

### `GRAFLORIA_INSTANCE_STYLE_PREFIX`

Prefix of a renderer's own `<style>` element id (one per instance).

```ts
const GRAFLORIA_INSTANCE_STYLE_PREFIX: "grafloria-renderer-theme-"
```

### `ROUTE_INFLUENCE_PAD`

How far outside a link's routed bounding box an obstacle can still have shaped
that route. The router pushes off the port by `gapOffset` (30), keeps
`obstacleMargin` (20) clearance from every body, and moves on a `gridSize`
(10) lattice — so an obstacle that shaped this route is within ~60 units of
it. 80 buys margin over that without pulling in half the diagram.

This is the one approximation in the cache, and it is deliberately generous:
being too eager here costs a re-route, being too clever costs a wrong route.

```ts
const ROUTE_INFLUENCE_PAD: 80
```

<!-- source: grafloria-renderer-svg-functions-a-p.md -->

# Functions A–P

Import these from `@grafloria/renderer`.

## Functions

### `applySpread`

Slide an attachment point along the port's EDGE (its tangent) by one lane.

Along the tangent, deliberately — sliding along the NORMAL would push the
endpoint off the node and leave a visible gap between the link and the port
it is supposed to be touching.

```ts
function applySpread(
  point: { x: number; y: number },
  side: Side,
  laneOffset: number
): { x: number; y: number }
```

### `assignSpreadLanes`

The lane assignment for every link on one port: `linkId → offset`.

Lanes are ordered by a STABLE key (the id of the link's other endpoint, then
the link's own id) rather than by insertion order, so the fan doesn't reshuffle
itself every time an unrelated link is added or the diagram is reloaded.

```ts
function assignSpreadLanes(
  entries: Array<{ linkId: string; sortKey: string }>,
  spec: PortSpreadSpec | undefined
): Map<string, number>
```

### `autoSizeDiagram`

Auto-size every opted-in node in a diagram. Returns the count that changed —
a host can skip a re-route when it is 0. Intended to run just before a frame
so routing consumes the settled bounds.

```ts
function autoSizeDiagram(
  nodes: Iterable<NodeModel>,
  opts: AutoSizeOptions = {}
): number
```

### `autoSizeNode`

Auto-size ONE node in place. No-op (returns false) when the node hasn't opted
in, or is already within half a pixel of its desired size — the idempotence
that keeps this safe to call every frame. Mutates strictly via `setSize`, so
the spatial index + routing observe the new bounds.

```ts
function autoSizeNode(node: NodeModel, opts: AutoSizeOptions = {}): boolean
```

### `buildHtmlForeignObject`

Build the `<foreignObject>` body VNode for an HTML node, sized to the node. Returns null when the node has no HTML content. The wrapper div is
`pointer-events: none` unless the content opts into interactivity, so the
shape background beneath keeps receiving selection / drag hits.

```ts
function buildHtmlForeignObject(
  node: NodeModel,
  width: number,
  height: number
): VNode | null
```

### `buildPathShapeDefinition`

BUILD a path shape's definition without storing it anywhere.

Extracted from {@link registerPathShape} so a PER-DIAGRAM registry can offer
`registerPathShape` too. Everything expensive and everything subtle — path
parsing, the one-slot outline sample memo, the derived boundary and port
anchors — lives here, so the global and scoped paths cannot drift into
producing different geometry for the same path.

```ts
function buildPathShapeDefinition(
  type: string,
  path: PathGeometry,
  opts: PathShapeOptions = {}
): ShapeDefinition
```

### `buildSelfLoopPoints`

Route a self-loop as a polyline: out of the source port, around, back into the
target port. EVERY segment is axis-aligned, which is what lets the three path
emitters each do the right thing with the same points — rounded rectangle for
`orthogonal`, a smooth closed-looking curve for `smooth`/`bezier`, a hard
polygon for `direct`.

Three cases, and they cover every port pairing:

A. SAME side (incl. the same port twice — the common case). The loop bulges
    straight out and spans laterally. When the two attachment points coincide
    (or sit closer together than `width`) they are SPREAD apart along the side
    by `width`, clamped to the node's own span: a loop whose feet are the same
    point has zero area and cannot be drawn at all.

B. PERPENDICULAR sides (right → top, …). Out of the source, one corner, into
    the target. An L that wraps the node's corner.

C. OPPOSITE sides (left → right, …). Out of the source, over/around the node
    body in a lane `size` clear of it, and back in the far side.

```ts
function buildSelfLoopPoints(spec: SelfLoopSpec): FanoutPoint[]
```

### `buildShapeBody`

```ts
function buildShapeBody(
  def: ShapeDefinition,
  width: number,
  height: number,
  cornerRadius: number | undefined,
  // `any` (not Record<string, any>) so the inline `style` string below is
  // accepted — matches the original render helpers' loosely-typed styles arg.
  styles: any
): VNode
```

### `buildShapeSelection`

Selection-highlight VNode: the outline grown by `padding`, plus baseProps. `radius` is the corner of the GROWN outline — the renderer passes the node's
own corner + padding, so the ring stays concentric with a rounded card; 6 is
the corner a node that declares none has always had.

```ts
function buildShapeSelection(
  def: ShapeDefinition,
  width: number,
  height: number,
  padding: number,
  baseProps: Record<string, any>,
  radius = 6
): VNode
```

### `buildShapeShadow`

Drop-shadow VNode: the outline offset by (offset, offset), plus baseProps.

```ts
function buildShapeShadow(
  def: ShapeDefinition,
  width: number,
  height: number,
  offset: number,
  borderRadius: number,
  baseProps: Record<string, any>
): VNode
```

### `bundleNormal`

The unit LEFT normal of a → b, i.e. the axis a parallel bundle fans along.

The caller must derive `a`/`b` from the bundle's CANONICAL node order (e.g.
lower node id first), not from each link's own source → target. Otherwise the
two halves of a bidirectional pair compute opposite normals, their opposite
lane offsets cancel out, and both links land back on top of each other — the
exact bug the card exists to fix.

Degenerate input (coincident points) falls back to "up", so a bundle between
two concentric nodes still fans instead of collapsing to NaN.

```ts
function bundleNormal(a: FanoutPoint, b: FanoutPoint): FanoutPoint
```

### `clampSizeToConstraints`

Clamp a candidate width/height to a node's sizing constraints. The per-node
min/max win; a global floor (the resizer's `minWidth`/`minHeight`) fills in
when the node sets none. Used identically by the resizer and the auto-sizer,
so both cannot disagree about the legal range.

```ts
function clampSizeToConstraints(
  width: number,
  height: number,
  sizing: NodeSizing,
  opts: ClampOptions = {}
): { width: number; height: number }
```

### `clampValue`

Clamp a scalar into `[min, max]`, tolerating an inverted or absent bound.

```ts
function clampValue(value: number, min?: number, max?: number): number
```

### `clearEdgeTemplates`

Drop every registration (tests, hosts tearing a document down).

```ts
function clearEdgeTemplates(): void
```

### `coalesce`

Merge dirty rects that overlap or nearly touch, so a drag of one node does not
fire N separate spatial queries. Cheap and approximate: one pass, absorbing
into the first box that already covers the candidate's neighbourhood. The
result is a SUPERSET of the input regions, which is the safe direction — it
can only invalidate more links, never fewer.

```ts
function coalesce(rects: Rect[], maxBoxes = 16): Rect[]
```

### `compensateForRotation`

Rotate `point` about the node's centre by `-degrees`, so a port on a rotated
node keeps its WORLD-space arrangement (a `compensateRotation` group on a node
spun 90° still shows its inputs on the left of the screen).

Node-local in, node-local out: the node's own transform then rotates it BACK,
and the two cancel.

```ts
function compensateForRotation(
  point: { x: number; y: number },
  width: number,
  height: number,
  degrees: number
): { x: number; y: number }
```

### `defaultInnerRect`

Padded-bbox label box: inset by up to 8px, clamped so it never inverts.

```ts
function defaultInnerRect(width: number, height: number): InnerRect
```

### `desiredNodeSize`

Compute the desired OUTER size of an auto-sized node from its label + reserved
panel content, clamped to the node's sizing constraints and any aspect lock. Pure — returns the size, mutates nothing.

```ts
function desiredNodeSize(
  node: NodeModel,
  opts: AutoSizeOptions = {}
): { width: number; height: number }
```

### `estimateTextWidth`

Average-glyph width estimate. See the module header for the rationale.

```ts
function estimateTextWidth(text: string, fontSize: number): number
```

### `fitCmdsToBox`

Rescale a parsed static path from its `viewBox` reference frame into a
`width × height` box anchored at the origin. Degenerate viewBox dimensions
fall back to 1 so a zero-width authoring box can't divide by zero.

```ts
function fitCmdsToBox(
  cmds: PathCmd[],
  viewBox: PathViewBox,
  width: number,
  height: number
): PathCmd[]
```

### `fitFontSize`

```ts
function fitFontSize(text: string, maxWidth: number, base: number): number
```

### `getEdgeTemplateVersion`

Bumped on every mutation — renderers key cache invalidation off this.

```ts
function getEdgeTemplateVersion(): number
```

### `getHtmlContent`

Read a node's HTML body spec, or null when it has none.

```ts
function getHtmlContent(node: NodeModel): HtmlNodeContent | null
```

### `getInnerRect`

The label box for a shape in local coords. Falls back to a padded bounding
box when the shape doesn't override `innerRect`.

```ts
function getInnerRect(def: ShapeDefinition, width: number, height: number): InnerRect
```

### `getLabelTemplate`

```ts
function getLabelTemplate(name: string): LabelTemplate | undefined
```

### `getLinkTemplate`

```ts
function getLinkTemplate(name: string): LinkTemplate | undefined
```

### `getMarker`

```ts
function getMarker(name: string): MarkerDefinition | undefined
```

### `getNodePanel`

Read a node's panel spec, or null when it has none.

```ts
function getNodePanel(node: NodeModel): PanelSpec | null
```

### `getNodeSizing`

Read a node's sizing config (never null — an absent config is `{}`).

```ts
function getNodeSizing(node: NodeModel): NodeSizing
```

### `getNodeToolbar`

Read a node's own toolbar config from metadata, or undefined.

```ts
function getNodeToolbar(node: NodeModel): NodeToolbarConfig | undefined
```

### `getPortLayout`

```ts
function getPortLayout(name: string | undefined): PortLayoutStrategy
```

### `getPortPositionForShape`

Calculate port position based on node shape
Returns position relative to node's local coordinate system (0,0 = top-left)

Shape-aware port positioning
- Rectangle: ports spread evenly along the edge (single port = midpoint)
- Circle/Ellipse: ports on the perimeter, fanned symmetrically per side
- Diamond: ports at vertices
- Hexagon: ports spread along the flat edges

Multiple ports on the same side are distributed by their rank among that
side's ports (ordered by `index`, then declaration order) so they never
stack on the same point.

```ts
function getPortPositionForShape(
  port: PortModel,
  node: NodeModel
): { x: number; y: number }
```

### `getShape`

The rect shape is the default fallback for unknown / unset shape types.

Resolution order is DIAGRAM-FIRST, then process-global. A diagram that
contributed its own `badge` sees its own; every other diagram — and this one,
for every name it did not claim — still sees the global registry. See
`ext/registry-scope.ts` for why the lookup is ambient rather than threaded.

```ts
function getShape(type: string | undefined): ShapeDefinition
```

### `getShapeDefinition`

Snapshot the current catalogue, so a caller can restore it later. Used by the
ExtensionHost to give a scoped extension an exact "undo" even when it OVERWROTE
an existing shape rather than adding a new one.

```ts
function getShapeDefinition(type: string): ShapeDefinition | undefined
```

### `getShapeRegistryVersion`

Monotonic counter, incremented on every add/remove. Cheap cache key. NOTE: `registerShape` itself bumps it — see the wrapper installed below.

```ts
function getShapeRegistryVersion(): number
```

### `glyphHalfExtents`

Half-extents of the glyph box, honouring size/width/height with `radius` fallback.

```ts
function glyphHalfExtents(
  shape: PortShapeSpec | undefined,
  radius: number
): { hw: number; hh: number }
```

### `haloAllows`

Whether a Halo action is enabled: `undefined` → `def`, `false` → never,
`true` → always, an array → membership.

```ts
function haloAllows(
  config: NodeToolbarConfig,
  action: ToolbarHaloAction,
  def = true
): boolean
```

### `hashString`

FNV-1a — small, fast, stable across runs. Only used to key VNodes.

```ts
function hashString(value: string): string
```

### `hasHtmlContent`

True when the node renders an HTML body.

```ts
function hasHtmlContent(node: NodeModel): boolean
```

### `hasMarker`

```ts
function hasMarker(name: string): boolean
```

### `hasPanel`

True when the node carries a composite panel.

```ts
function hasPanel(node: NodeModel): boolean
```

### `hasPortLayout`

```ts
function hasPortLayout(name: string): boolean
```

### `hasShape`

Whether a shape type is registered (excludes the implicit rect fallback).

```ts
function hasShape(type: string): boolean
```

### `hitTestLink`

Part-aware link hit-test.

Precedence (highest first): endpoint / arrow handles (small grab radius) >
labels (bounding box) > body (near the path). Within the handle tier the
nearest handle wins, tie-broken by declaration order
(source-endpoint, target-endpoint, source-arrow, target-arrow).

```ts
function hitTestLink(
  options: LinkHitTestOptions,
  query: Point,
  tolerance: number
): LinkHitResult | null
```

**Parameters**

- `options`: the link geometry to test against
- `query`: the world-space point to test
- `tolerance`: grab distance for the body (and label box padding)

**Returns** the hit part with local info, or `null` when nothing is within reach

### `htmlLabelVNode`

A `foreignObject` VNode carrying arbitrary HTML, positioned so `anchor` is its
CENTRE (labels are centred on the path, unlike nodes which are top-left).

THE KEY CARRIES A CONTENT HASH, and that is load-bearing. The VNode patcher
treats `foreignObject` subtrees as OPAQUE: it patches their props but NEVER
diffs into their children, so that whatever a framework mounted inside stays
alive. That is exactly right for host-mounted content — and exactly wrong for
content we own, because an edited label would keep rendering its old HTML
forever. Folding the content into the key means changed HTML is a DIFFERENT
VNode identity, which the patcher replaces wholesale. Unchanged HTML keeps the
same key and the same live DOM.

```ts
function htmlLabelVNode(options: HtmlLabelOptions): VNode
```

### `inflate`

Grow a rect by `pad` on every side.

```ts
function inflate(r: Rect, pad: number): Rect
```

### `isAutoSized`

True when the node opts into content-aware auto-sizing.

```ts
function isAutoSized(node: NodeModel): boolean
```

### `linkBodyHitTolerance`

The grab distance for a link BODY — the one number the painted invitation
and the accepted press must both derive from.

The SVG renderer paints a transparent hit-area stroke `linkHitAreaWidth`
wide, but the interaction layer used to accept only the flat 5px floor: the
ring between them was DEAD — the DOM caught the pointer (cursor, native
focus — the "rectangle around the line" report) while the press selected
nothing. Every consumer of "how close is close enough to a link" now calls
this: the interaction controller (SVG mode), the canvas pick-buffer stroke,
and the hit-area painter (at exactly `2 x` this, minus slop).

`literalStrokeWidth` must be the resolved numeric width (fall back to 2 for
theme-bound `var(--…)` widths, matching the renderer's own literal
fallback).

```ts
function linkBodyHitTolerance(
  literalStrokeWidth: number,
  configWidth: number = DEFAULT_LINK_HIT_AREA_WIDTH
): number
```

### `linkHitAreaWidth`

Width of the invisible "interaction stroke" painted along a link.

Sized from the LITERAL stroke width, never a `var(--…)` expression — the
renderer resolves its literals before calling this. The `+ 8` keeps a grab
margin around fat strokes (a 10px casing would otherwise be pixel-hunting).

```ts
function linkHitAreaWidth(
  literalStrokeWidth: number,
  configWidth: number = DEFAULT_LINK_HIT_AREA_WIDTH
): number
```

### `listLabelTemplates`

```ts
function listLabelTemplates(): string[]
```

### `listLinkTemplates`

```ts
function listLinkTemplates(): string[]
```

### `listMarkers`

```ts
function listMarkers(): string[]
```

### `listShapes`

All registered shape type names (built-ins + extended library + aliases).

```ts
function listShapes(): string[]
```

### `mapPathCmds`

Map every coordinate in a command list through `fn` (structure preserved).

```ts
function mapPathCmds(cmds: PathCmd[], fn: (x: number, y: number) => Point): PathCmd[]
```

### `markerTipOffset`

Resolve a registered marker's tip offset for a concrete style.

```ts
function markerTipOffset(definition: MarkerDefinition, style: ArrowStyle): number
```

### `measureLabelContent`

The content box a label occupies: the widest wrapped line × the line count. Uses the same `estimateTextWidth` heuristic the label renderer wraps with, so
the measured box and the rendered text agree about where lines break.

```ts
function measureLabelContent(text: string, opts: MeasureLabelOptions = {}): ContentSize
```

### `measurePanelReserve`

Extra content space a panel reserves so content-aware auto-sizing
grows the shape to fit the WHOLE body. `top` = header + image stacked above
the label; `bottom` = the stacked rows below it; `width` = the widest text the
panel must show.

```ts
function measurePanelReserve(
  node: NodeModel
): { top?: number; bottom?: number; width?: number } | undefined
```

### `notifyEdgeTemplatesChanged`

Internal: let a PER-DIAGRAM registry participate in the version/notify
protocol. A scoped registration must invalidate cached VNodes for exactly the
reason a global one must — the definition is baked into the cache. Notifying
every renderer (not just the contributing one) is deliberate: over-invalidation
costs a repaint, under-invalidation shows a stale picture.

```ts
function notifyEdgeTemplatesChanged(): void
```

### `notifyShapeRegistered`

Internal: let `registerShape` participate in the version/notify protocol.

```ts
function notifyShapeRegistered(): void
```

### `nudgePortLabels`

Collision-aware nudging: when several port labels crowd, push them apart along
the axis they stack on.

Deliberately a ONE-AXIS resolver over labels that share a side. That is the
shape the crowding actually has — a column of inputs down the left edge whose
labels overlap vertically — and a general 2-D label-placement solver would be
both slower and less predictable (labels would visibly hop sideways as you
dragged a node). Returns a per-label nudge, so the caller can decide whether
to apply it.

`heights` are the labels' rendered heights, `centres` their unnudged centre
coordinates on the stacking axis, both in the SAME order.

```ts
function nudgePortLabels(centres: number[], heights: number[], gap = 2): number[]
```

### `onEdgeTemplateChange`

Subscribe to registry changes. Renderers use this to drop cached link VNodes
when a template is (re)defined — the template's OUTPUT is baked into the
cached VNode, so a redefinition that did not invalidate would never show up.

```ts
function onEdgeTemplateChange(listener: () => void): () => void
```

### `onShapeRegistryChange`

Subscribe to catalogue changes. Returns a disposer.

```ts
function onShapeRegistryChange(listener: () => void): () => void
```

### `outerSizeForInner`

Invert a shape's `innerRect`: the OUTER width/height whose label box is at
least `contentW × contentH`. `innerRect` is a monotone function of the outer
size (fractional insets for curved shapes, additive padding for the rect
default), so a few fixed-point steps converge — one step for the fractional
shapes, a handful for additive padding.

```ts
function outerSizeForInner(
  def: ShapeDefinition,
  contentW: number,
  contentH: number,
  seed?: { width: number; height: number }
): { width: number; height: number }
```

### `overlapArea`

```ts
function overlapArea(a: OptimizerRect, b: OptimizerRect): number
```

### `panelAdjustedInnerRect`

The body inner rect available to the node LABEL once the panel's header/image
(top) and rows (bottom) have taken their space. Keeps the label from
overlapping the panel bands. Given the shape's own inner rect.

```ts
function panelAdjustedInnerRect(
  node: NodeModel,
  inner: { x: number; y: number; w: number; h: number },
  width: number,
  height: number
): { x: number; y: number; w: number; h: number }
```

### `parallelOffsets`

The signed lane offsets for a bundle of `count` parallel links, spaced
`spacing` apart and centred on the un-separated route.

count 1 → [0]                     (a lone link NEVER moves — this is what
                                     keeps every existing diagram pixel-identical)
  count 2 → [-s/2, +s/2]
  count 3 → [-s, 0, +s]

Centred rather than one-sided so a bundle stays visually anchored on the line
the single link used to occupy: adding a second relationship between two
entities nudges both apart instead of shunting the diagram sideways.

```ts
function parallelOffsets(count: number, spacing = DEFAULT_PARALLEL_SPACING): number[]
```

<!-- source: grafloria-renderer-svg-functions-p-w.md -->

# Functions P–W

Import these from `@grafloria/renderer`.

## Functions

### `pointAtPositionOnPolyline`

Arc-length interpolation of a point at position `t` (0-1) along a polyline. Mirrors {@link LinkModel.getPointAtPosition }'s polyline fallback so label
anchors line up with what the renderer draws. Returns `null` for < 2 points.

```ts
function pointAtPositionOnPolyline(points: Point[], t: number): Point | null
```

### `portLabelGeometry`

Where does the label go, which way does it point, and how does it hang off its
anchor?

The `align`/`valign` choice matters as much as the position: a label to the
LEFT of a port must be right-aligned (`end`), or it grows away from the port
and collides with the node.

```ts
function portLabelGeometry(input: PortLabelInput): PortLabelGeometry
```

### `portLabelWidth`

The label's rendered width, using the shared text engine's estimator.

```ts
function portLabelWidth(spec: PortLabelSpec, fontSize: number): number
```

### `portLayoutNames`

For tests / tooling.

```ts
function portLayoutNames(): string[]
```

### `portPositionInBounds`

Same answer, for callers that already hold the node's bounding box.

```ts
function portPositionInBounds(
  port: PortModel,
  node: NodeModel,
  bounds: BoundingBox
): { x: number; y: number }
```

### `portWorldPosition`

The port's WORLD position — for hit-testing, magnets and link endpoints alike. Everything that needs "where is this port on screen" comes through here, so
what you click is always what you see.

```ts
function portWorldPosition(port: PortModel, node: NodeModel): { x: number; y: number }
```

### `registerLabelTemplate`

```ts
function registerLabelTemplate(name: string, template: LabelTemplate): void
```

### `registerLinkTemplate`

```ts
function registerLinkTemplate(name: string, template: LinkTemplate): void
```

### `registerMarker`

```ts
function registerMarker(name: string, definition: MarkerDefinition): void
```

### `registerNotationShapes`

Register every notation shape that the base registry does not already own.

```ts
function registerNotationShapes(): void
```

### `registerPathShape`

Register an arbitrary SVG-path shape. This is the payoff of the
geometry contract: a userland caller adds a brand-new silhouette in ONE call
and it works everywhere the built-ins do — node body, selection highlight,
drop shadow, smart-connection boundary and geometry-true port anchors — with
NO core-team switch edits.

```ts
// Parametric — a 5-point star that fills any box.
registerPathShape('star', (w, h) => starPath(w, h));
// Static — a chevron authored in a 24×24 art box.
registerPathShape('chevron', 'M2,4 L14,4 L22,12 L14,20 L2,20 L10,12 Z',
  { viewBox: { x: 0, y: 0, w: 24, h: 24 } });
```

```ts
function registerPathShape(
  type: string,
  path: PathGeometry,
  opts: PathShapeOptions = {}
): void
```

### `registerPortLayout`

Register a custom strategy. Hosts can add their own; the built-ins are just entries.

```ts
function registerPortLayout(name: string, strategy: PortLayoutStrategy): void
```

### `registerShape`

Register (or replace) a shape definition. This is the payoff: a new shape is
added in ONE place and immediately works across body/selection/shadow,
smart-connection boundaries and port positioning — no switch edits.

```ts
function registerShape(type: string, def: Omit<ShapeDefinition, 'type'> & { type?: string }): void
```

### `renderNodePanel`

Build the panel overlay VNodes for a node, in draw order (background bands
first, corner overlays last). Returns [] when the node has no panel. These are
appended to the node group ON TOP of the base shape body, so the panel rides
whatever silhouette the shape registry drew.

```ts
function renderNodePanel(
  node: NodeModel,
  width: number,
  height: number,
  ctx: PanelRenderContext
): VNode[]
```

### `renderPortGlyph`

Build the port's glyph VNode.

Every existing diagram's port
VNodes are unchanged.

```ts
function renderPortGlyph(input: PortGlyphInput): VNode
```

### `renderPortLabel`

Render the port's label as a `<text>` (or a `<g>` when it is rotated — a
rotation needs a transform, and putting it on the text itself would fight the
`x`/`y` the text-block engine emits for its tspans).

```ts
function renderPortLabel(input: PortLabelInput): VNode
```

### `renderTextBlock`

Render a text block as a single <text> VNode.

- one line  → a <text> carrying `textContent` (+ dominant-baseline for
  vertical centering), preserving the historical single-line output.
- many lines → a <text> with one <tspan> per line, vertically aligned via
  per-line `dy` (first line offset by {@link baselineOffset}).

```ts
function renderTextBlock(opts: TextBlockOptions): VNode
```

### `resolveAspectRatio`

The explicit aspect ratio (w÷h) a node is locked to, or null when unlocked. `aspectLock: true` resolves against a supplied current size.

```ts
function resolveAspectRatio(
  sizing: NodeSizing,
  current?: { width: number; height: number }
): number | null
```

### `resolveRotation`

Total label rotation, with keep-upright auto-flip.

`angle` rotates the label. `keepUpright` (default ON) then adds 180° to any
label that would end up reading upside-down — the standard trick, and the
reason a `radial` label on the LEFT half of a circle still reads
left-to-right instead of mirror-written.

```ts
function resolveRotation(spec: PortLabelSpec, direction: { x: number; y: number }): number
```

### `resolveSpot`

Resolve `spot` to a world point on the glyph box, plus the direction the link
travels there.

Nothing moves unless the
author asks it to.

```ts
function resolveSpot(
  spot: PortSpot | undefined,
  input: SpotInput
): { point: { x: number; y: number }; direction: Side }
```

### `resolveToolbar`

The effective toolbar config for a node: the node's own metadata, with a
host-supplied resolver (per-type policy) layered on top.

```ts
function resolveToolbar(node: NodeModel, resolver?: ToolbarResolver): NodeToolbarConfig
```

### `runPortLayout`

Run a port's layout: pick the strategy, apply it, then the shared `dx`/`dy`
nudge and optional rotation compensation.

```ts
function runPortLayout(spec: PortLayoutSpec | undefined, input: PortLayoutInput): { x: number; y: number }
```

### `sampleOutlineFromData`

Parse + sample a `d` string in one call.

```ts
function sampleOutlineFromData(d: string, steps = 24): Point[]
```

### `sampleOutlinePoints`

Sample a path's OUTLINE as a dense polygon of points.

The path is flattened (curves → line segments) and the single richest subpath
— the shape's main silhouette — is returned as a vertex ring. Interior detail
subpaths (a UML component's tabs, a cube's inner edges) are intentionally
dropped: the boundary/anchor scanline treats its input as ONE closed ring, and
stitching several subpaths into one ring would invent phantom edges.

Returns an empty array for an unparseable / empty `d` so callers fall back to
the bounding box.

```ts
function sampleOutlinePoints(cmds: PathCmd[], steps = 24): Point[]
```

### `sanitizeAssetUrl`

Allow only image-safe URL schemes on an asset href. Blocks `javascript:` and
`data:text/html` (the executable-URL vectors); permits `data:image/*`,
`blob:`, `http(s):`, and scheme-relative / path references. An unsafe or
non-string href resolves to '' so the slot renders empty instead of dangerous.

```ts
function sanitizeAssetUrl(href: unknown): string
```

### `sanitizeHtmlContent`

Convert ONE sanitized content node to a VNode. Unknown tags collapse to a
`<span>` (their text is kept, their dangerous identity is dropped). Returns
null for a node that contributes nothing.

```ts
function sanitizeHtmlContent(spec: HtmlContentNode): VNode | null
```

### `segmentIntersectsRect`

Liang-Barsky: does the segment touch the rect at all?

```ts
function segmentIntersectsRect(a: Point, b: Point, rect: OptimizerRect): boolean
```

### `separateParallelRoute`

Push a routed polyline onto its lane in a parallel bundle.

The two ENDPOINTS never move: they are the ports, and a fan that pulled the
line off its port would be worse than the overlap it fixes. Only the interior
of the route is displaced.

• `orthogonal` — every INTERIOR segment is slid along its own normal. A
    segment's neighbours run perpendicular to it, so sliding it only makes
    them longer or shorter: the route stays exactly orthogonal (no diagonal
    ever appears). A route with no interior segment (a straight 2-point
    orthogonal run between aligned ports) gets an S-jog inserted instead,
    because there is otherwise nothing to displace.
  • `direct` / `smooth` / `bezier` — the interior points are displaced along
    the bundle normal; a bare 2-point route gets an offset midpoint, which the
    path emitters turn into a bow (a spline for smooth, a shallow V for
    direct). This is the "curviness" fan GoJS and React Flow draw.

```ts
function separateParallelRoute(
  points: FanoutPoint[],
  offset: number,
  normal: FanoutPoint,
  pathType: string
): FanoutPoint[]
```

### `serializePathCmds`

Serialize a command list back into a compact `d` string.

```ts
function serializePathCmds(cmds: PathCmd[]): string
```

### `sideNormal`

Outward unit normal of a node side.

```ts
function sideNormal(side: FanoutSide): FanoutPoint
```

### `sideTangent`

Unit tangent of a side — the axis links spread along.

```ts
function sideTangent(side: Side): { x: number; y: number }
```

### `spreadOffsets`

The signed lane offsets for `count` links sharing one port, spaced `spacing`
apart and CENTRED on the port's own attachment point.

count 1 → [0]                 ← a lone link NEVER moves. This is the whole
                                  byte-stability guarantee: a port with one
                                  link renders exactly where it always did.
  count 2 → [-s/2, +s/2]
  count 3 → [-s, 0, +s]

```ts
function spreadOffsets(count: number, spacing: number, max = 0): number[]
```

### `toolbarAllows`

Whether a boolean tool (resize / rotate / remove) is enabled; `def` when unset.

```ts
function toolbarAllows(
  config: NodeToolbarConfig,
  tool: 'resize' | 'rotate' | 'remove',
  def = true
): boolean
```

### `translateCmds`

Offset every coordinate by (dx, dy) — used for grow/shadow transforms.

```ts
function translateCmds(cmds: PathCmd[], dx: number, dy: number): PathCmd[]
```

### `unregisterLabelTemplate`

Remove one label template. Returns false when it was not registered.

```ts
function unregisterLabelTemplate(name: string): boolean
```

### `unregisterLinkTemplate`

Remove one link template. Returns false when it was not registered.

```ts
function unregisterLinkTemplate(name: string): boolean
```

### `unregisterMarker`

Remove one marker. Returns false when it was not registered.

```ts
function unregisterMarker(name: string): boolean
```

### `unregisterShape`

Remove a registered shape. Returns false when the type was not registered.

```ts
function unregisterShape(type: string): boolean
```

### `wrapText`

Break `text` into display lines: split on hard '\n', then greedily word-wrap
each paragraph to `maxWidth`. A single word wider than maxWidth breaks at its
HYPHENS first ("predefined-process" → "predefined-" + "process" — a hyphen is
a legitimate break point; a centred clip eats BOTH ends of the word and reads
as gibberish, which is exactly what the screenshot audit caught). A word with
no hyphen is kept whole (clipped, not broken) — the historical LabelRenderer
behavior for genuinely unbreakable runs.

```ts
function wrapText(text: string, maxWidth: number | undefined, fontSize: number): string[]
```

<!-- source: grafloria-renderer-svg-interfaces-a-o.md -->

# Interfaces A–O

Import these from `@grafloria/renderer`.

## Interfaces

### `AutoSizeOptions`

```ts
interface AutoSizeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fontSize?` | `number` |  |  |
| `lineHeight?` | `number` |  |  |
| `floorWidth?` | `number` |  | Global resizer minimums, applied only where the node declares no per-node min. Keeps auto-size and the interactive resizer on the same floor. |
| `floorHeight?` | `number` |  |  |
| `reserve?` | `{ top?: number; bottom?: number; width?: number }` |  | Extra content a composite panel reserves around the label. `top` stacks above the label (header band + image), `width` widens the content box to fit a horizontal row (icon + label + badge). |

### `ClampOptions`

```ts
interface ClampOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `floorWidth?` | `number` |  | Global floor applied when the node declares no `minWidth`/`minHeight`. |
| `floorHeight?` | `number` |  |  |

### `ContentSize`

The intrinsic content box a node needs (before shape-inset expansion).

```ts
interface ContentSize
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `EdgeOptimizerOptions`

```ts
interface EdgeOptimizerOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `jumpOwnership?` | `'both' \| 'single'` |  | . Who draws the arc when two jump-drawing links cross: 'both' — legacy: each link bridges the other (a double bridge). 'single' — exactly ONE deterministic owner per intersection: the link whose crossing segment is HORIZONTAL arcs over the vertical (the classic drafting convention); when neither or both are horizontal, the smaller link id owns. |
| `cellSize?` | `number` |  | Uniform-grid cell size (world px) for the link broad phase. Should be on the order of a typical node — too small and long links occupy hundreds of cells, too large and the broad phase stops filtering. |
| `labelSearchSteps?` | `number` |  | How far out the label search pushes, in steps of `labelStep`. |
| `labelStep?` | `number` |  | Distance between successive label candidates (px). |

### `FanoutPoint`

Parallel-link auto-separation and self-loop routing. PURE GEOMETRY: no engine
models, no DOM, no framework — points in, points out — so every rule below is
unit-testable on its own and the SVG renderer only has to decide WHEN to call
it, not HOW the shape is built.

Why this is the biggest structural edge gap Grafloria had:
  • Two links between the same pair of nodes were drawn on the same centre
    line, one exactly on top of the other. ERD (two FKs between the same
    tables), BPMN (a flow and its compensation) and state machines (a→b and
    b→a) all produce that shape constantly.
  • A link whose source node IS its target node was handed to the router as an
    ordinary A→B route. The router excludes the link's own nodes from its
    obstacle set, so the "route" was a degenerate stub inside the node body.

The output of both routines is a POLYLINE, not a path string. That is
deliberate: the renderer's existing path emitters already turn a polyline into
the right shape per path type (rounded corners for `orthogonal`, a Catmull-Rom
spline for `smooth`/`bezier`, straight segments for `direct`), and hit
testing, jump-point detection, label placement and the edge toolbar all read
the same polyline. One geometry, every consumer.

```ts
interface FanoutPoint
```

**Properties**

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

### `FanoutRect`

```ts
interface FanoutRect
```

**Properties**

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

### `FrameCoverage`

What one live `render()` pass actually drew, in world coordinates — the
contract behind the host's camera fast path (see CAMERA_OVERSCAN).

`rect` is the node-cull rectangle INCLUDING overscan: every node, group,
stroke and comment intersecting it was rendered (links got LINK_CULL_MARGIN
of extra slack beyond it). While a new viewBox of the same size and zoom
stays inside `rect`, the DOM already contains everything that viewBox can
show, and the camera may move by rewriting the `viewBox` attribute alone.

`total` — every node and link in the diagram was admitted and no optional
layer (groups, ink, comment pins) exists, so containment is moot: ANY camera
position at this zoom shows a complete picture. This is what makes panning a
fit-to-content scene free.

Null when there is no diagram, or when the mount gate deferred anything (a
progressive mount in flight, frozen entities): the drawn set is then smaller
than the culled set and the coverage claim would be a lie.

```ts
interface FrameCoverage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `rect` | `Rectangle` |  |  |
| `zoom` | `number` |  |  |
| `viewBoxWidth` | `number` |  |  |
| `viewBoxHeight` | `number` |  |  |
| `total` | `boolean` |  |  |

### `HtmlContentNode`

A single node in the structured, sanitized rich-content tree.

```ts
interface HtmlContentNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tag` | `string` |  | Element tag — validated against {@link ALLOWED_TAGS}. |
| `text?` | `string` |  | Text content, emitted via `textContent` (never innerHTML). |
| `style?` | `Record<string, string \| number>` |  | Inline style (object form); values are sanitized. |
| `className?` | `string` |  |  |
| `attrs?` | `Record<string, string>` |  | Extra attributes — filtered against {@link ALLOWED_ATTRS} + sanitized. |
| `children?` | `HtmlContentNode[]` |  |  |

### `HtmlLabelOptions`

```ts
interface HtmlLabelOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable id: becomes part of the VNode key. |
| `html` | `string` |  | Raw HTML. Injected verbatim via `innerHTML` — the author owns its safety. |
| `anchor` | `Point` |  | Centre of the label box in world coordinates. |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `className?` | `string` |  | Extra class on the XHTML wrapper div. |

### `HtmlNodeContent`

The HTML-node body spec, stored at `node.metadata.html`.

```ts
interface HtmlNodeContent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text?` | `string` |  | Plain-text body (safe: rendered through `textContent`). |
| `content?` | `HtmlContentNode` |  | Structured, sanitized rich content. |
| `style?` | `Record<string, string \| number>` |  | Inline style for the root container (object form; values sanitized). |
| `className?` | `string` |  |  |
| `padding?` | `number` |  | Inner padding (px). Default 4. |
| `interactive?` | `boolean` |  | Let the HTML capture pointer events (forms / links). Default false, so the shape background beneath receives clicks and the node stays draggable / selectable like any shape. |

### `InnerRect`

A shape's inner label box in LOCAL coordinates (0,0 = node top-left). The
node label engine wraps + clips text to this rect. Curved / slanted shapes
(diamond, ellipse, triangle, cylinder …) inset it so text stays inside the
visible silhouette. See {@link getInnerRect}.

```ts
interface InnerRect
```

**Properties**

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

### `Intersection`

Intersection information

```ts
interface Intersection
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `point` | `Point` |  |  |
| `angle` | `number` |  |  |
| `t1` | `number` |  |  |
| `t2` | `number` |  |  |
| `linkId?` | `string` |  |  |
| `segmentIndex?` | `number` |  |  |

### `LabelRenderContext`

Extra, per-frame context — none of it belongs on the persisted model.

```ts
interface LabelRenderContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `offset?` | `Point` |  | The offset the edge optimizer settled on. Overrides `label.offset` when present (it IS `label.offset` for any label that did not opt into `autoOffset`). |
| `theme?` | `Theme` |  |  |
| `path?` | `ReadonlyArray<Point>` |  | The line AS PAINTED, when that is not `link.points`: a hand-bent right-angle line stores its bends and is drawn with the jogs between them, so a label placed on the stored points sat off the drawn line. The renderer passes the painted polyline; the label is placed (and turned) along it. |

### `LabelTemplateContext`

What a LABEL template is given.

```ts
interface LabelTemplateContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `LinkLabel` |  |  |
| `link` | `LinkModel` |  |  |
| `anchor` | `Point` |  | World-space anchor the label resolved to (position/slot + offset + optimizer). |
| `rotation?` | `number` |  | Rotation in degrees the default renderer would have applied, if any. |
| `theme` | `Theme` |  |  |

### `LineSegment`

Line segment defined by start and end points

```ts
interface LineSegment
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `Point` |  |  |
| `end` | `Point` |  |  |

### `LinkHitLabel`

A label placement, expressed independently of the model.

```ts
interface LinkHitLabel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `number` |  | Position along the path in [0, 1] (the label's on-path anchor). |
| `offset?` | `Point` |  | Offset of the label box centre from its on-path anchor. |
| `width?` | `number` |  | Label box width in world units (falls back to {@link DEFAULT_LABEL_WIDTH}). |
| `height?` | `number` |  | Label box height in world units (falls back to {@link DEFAULT_LABEL_HEIGHT}). |

### `LinkHitResult`

Result of a part-aware link hit-test.

```ts
interface LinkHitResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `part` | `LinkPart` |  | Which sub-part of the link was hit. |
| `labelIndex?` | `number` |  | Index into the supplied labels array — present only for `part === 'label'`. |
| `t?` | `number` |  | Position along the whole path in [0, 1] where the body was hit — present only for `part === 'body'`. Useful for inserting waypoints / positioning an edge toolbar on the segment under the cursor. |
| `distance?` | `number` |  | Distance from the query to the winning part's own metric (handle centre, body path; 0 for inside a label box). For ranking hits ACROSS links. |
| `bodyDistance?` | `number` |  | Distance from the query to this link's BODY path, present whenever the link has >= 2 points — even when a handle or label won the part. This is the cross-link tiebreaker: at a shared fan-out anchor every sibling's endpoint handle is equidistant, but only the link actually under the cursor has body distance ~0. |

### `LinkHitTestOptions`

Inputs describing a single link's geometry for hit-testing.

```ts
interface LinkHitTestOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `Point[]` |  | Routed points of the link, in world coordinates (>= 2 for a body). |
| `labels?` | `LinkHitLabel[]` |  | Label placements, in render order (later entries drawn on top). |
| `sourceEndpoint?` | `Point \| null` |  | Source endpoint anchor (defaults to `points[0]`). Pass `null` to disable. |
| `targetEndpoint?` | `Point \| null` |  | Target endpoint anchor (defaults to last point). Pass `null` to disable. |
| `sourceArrow?` | `Point \| null` |  | Source arrowhead anchor. Omit / `null` when there is no source arrow. |
| `targetArrow?` | `Point \| null` |  | Target arrowhead anchor. Omit / `null` when there is no target arrow. |
| `endpointRadius?` | `number` |  | Grab radius around endpoint anchors (default {@link DEFAULT_ENDPOINT_RADIUS}). |
| `arrowRadius?` | `number` |  | Grab radius around arrowhead anchors (default {@link DEFAULT_ARROW_RADIUS}). |
| `defaultLabelWidth?` | `number` |  | Fallback label box width when a label omits one. |
| `defaultLabelHeight?` | `number` |  | Fallback label box height when a label omits one. |

### `LinkTemplateContext`

What a LINK template is given. Everything it needs; nothing it can corrupt.

```ts
interface LinkTemplateContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  |  |
| `points` | `Point[]` |  | The ROUTED polyline for this frame — not the model's stale `segments`. |
| `pathData` | `string` |  | The SVG path string the default renderer would have drawn (jumps included). |
| `styles` | `Record<string, unknown>` |  | Resolved link styles (stroke, strokeWidth, className, …) for this state. |
| `theme` | `Theme` |  |  |
| `lod` | `string` |  | Current level-of-detail tier, so a template can drop detail when zoomed out. |
| `selected` | `boolean` |  | True when the link is selected — templates usually want to react to this. |

### `LinkWithPoints`

Link with points for intersection detection

```ts
interface LinkWithPoints
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  |  |
| `points` | `Point[]` |  |  |

### `MarkerContext`

What a custom MARKER is given.

```ts
interface MarkerContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `style` | `ArrowStyle` |  |  |
| `size` | `number` |  | Normalised size (never negative). |
| `color` | `string` |  | Resolved colour (the marker's own, else the link's stroke). |
| `width` | `number` |  | Stroke width for outlined markers. |
| `transform` | `string` |  | The SVG transform placing the marker: `translate(x, y) rotate(deg)`. The marker draws in its LOCAL frame — origin at the anchor, +x along the direction of travel — and MUST put this on its root element. |
| `backgroundColor` | `string` |  | Theme background — the fill for hollow markers, so they don't glare on dark. |
| `end` | `'source' \| 'target'` |  | Which end this marker sits on. |

### `MarkerDefinition`

```ts
interface MarkerDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `(ctx: MarkerContext) => VNode \| null` |  |  |
| `tipOffset?` | `number \| ((style: ArrowStyle) => number)` |  | Distance from the marker's local origin to its visual TIP along +x. The renderer pulls the marker back from the path endpoint by exactly this, so the tip lands ON the port. A triangle drawn from 0 to `size` has tipOffset `size`; a dot centred on the origin has `size / 2`; a bar has 0. |

### `MeasureLabelOptions`

```ts
interface MeasureLabelOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fontSize?` | `number` |  |  |
| `lineHeight?` | `number` |  | Line-height multiplier. Default 1.2. |
| `wrapWidth?` | `number` |  | Wrap the label to this content width; omit to measure it on one line. |

### `NodeSizing`

Sizing constraints for a single node. Every field is optional; an absent
field means "no constraint" (the global resizer minimum still applies as a
safety floor).

```ts
interface NodeSizing
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `auto?` | `boolean` |  | Content-aware auto-sizing: the node grows to fit its label + panel. |
| `minWidth?` | `number` |  |  |
| `minHeight?` | `number` |  |  |
| `maxWidth?` | `number` |  |  |
| `maxHeight?` | `number` |  |  |
| `aspectLock?` | `boolean \| number` |  | Aspect lock. `true` locks to the node's CURRENT width/height ratio; a number locks to that explicit width÷height ratio. Honored during a resize gesture even without the Shift modifier. |
| `padding?` | `number` |  | Content padding (px) reserved around the label when auto-sizing. |

### `NodeToolbarConfig`

Per-node tool visibility. Every field is optional; an absent field means "use
the controller's global default". `halo: true` → all actions, an array → only
those actions, `false` → no halo.

```ts
interface NodeToolbarConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `resize?` | `boolean` |  |  |
| `rotate?` | `boolean` |  |  |
| `remove?` | `boolean` |  |  |
| `halo?` | `boolean \| ToolbarHaloAction[]` |  |  |

### `OptimizerFrame`

```ts
interface OptimizerFrame
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `OptimizerNode[]` |  |  |
| `links` | `OptimizerLink[]` |  |  |

<!-- source: grafloria-renderer-svg-interfaces-o-s.md -->

# Interfaces O–S

Import these from `@grafloria/renderer`.

## Interfaces

### `OptimizerLabel`

A label awaiting placement.

```ts
interface OptimizerLabel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `anchor` | `Point` |  | On-path anchor the label hangs off (world). |
| `offset` | `Point` |  | The offset the AUTHOR asked for — the preferred placement, and the fallback. |
| `width` | `number` |  | Box size used for collision tests. |
| `height` | `number` |  |  |
| `autoOffset` | `boolean` |  | Opt-in to the collision search. Off ⇒ `offset` is returned verbatim. |
| `normal` | `Point` |  | Unit normal of the path at `anchor` — the axis the search pushes along. |

### `OptimizerLink`

```ts
interface OptimizerLink
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `points` | `Point[]` |  | The ROUTED polyline for this frame (post parallel-separation / self-loop). |
| `jumps?` | `{ mode: DetectionMode; threshold: number; }` |  | Jump config, if this link draws jumps at all. |
| `labels` | `OptimizerLabel[]` |  |  |

### `OptimizerNode`

A node, as far as the optimizer cares: an obstacle with an id.

```ts
interface OptimizerNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `rect` | `OptimizerRect` |  |  |

### `OptimizerRect`

```ts
interface OptimizerRect
```

**Properties**

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

### `OptimizerStats`

Per-frame work counters — the incrementality is only real if these are 0 on a quiet frame.

```ts
interface OptimizerStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dirtyLinks` | `number` |  | Links whose geometry changed this frame. |
| `jumpsRecomputed` | `number` |  | Links whose jump set was recomputed (dirty ones + their grid neighbours). |
| `jumpsReused` | `number` |  | Links that served their jump set from cache. |
| `labelsPlaced` | `number` |  | Labels whose placement was searched. |
| `labelsReused` | `number` |  | Labels served from cache. |
| `segmentTests` | `number` |  | Segment-pair intersection tests actually performed. |

### `OutlineSpec`

An SVG element type plus the geometry props for one outline instance.

```ts
interface OutlineSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `el` | `VNodeType` |  |  |
| `geom` | `Record<string, number \| string>` |  |  |
| `verts?` | `ShapePoint[]` |  | Polygon shapes expose their vertices so boundaryPoint can reuse them. |

### `OutlineTransform`

Transform applied to a shape outline. The same primitive drives every render
site: body = {}, selection = { grow: padding }, shadow = { dx, dy }.

```ts
interface OutlineTransform
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `grow?` | `number` |  | Expand the outline outward by this many px (selection highlight padding). |
| `dx?` | `number` |  | Translate the outline (drop-shadow offset). |
| `dy?` | `number` |  |  |
| `radius?` | `number` |  | Corner radius for rect (rx). Emitted only when truthy unless `radiusAlways`. |
| `radiusY?` | `boolean` |  | Also emit ry (= radius). Selection/body want rx+ry; shadow wants rx only. |
| `radiusAlways?` | `boolean` |  | Emit rx even when `radius` is 0 (shadow keeps rx: borderRadius ?? 4). |

### `PagedSvgResult`

```ts
interface PagedSvgResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pages` | `Array<Page & { svg: string }>` |  |  |
| `columns` | `number` |  |  |
| `rows` | `number` |  |  |
| `warnings` | `string[]` |  |  |

### `PanelBadge`

A count / status badge pinned to a corner.

```ts
interface PanelBadge
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  |  |
| `corner?` | `PanelCorner` |  |  |
| `fill?` | `string` |  |  |
| `textColor?` | `string` |  |  |

### `PanelHeader`

A header band across the top of the node (ERD/UML title row).

```ts
interface PanelHeader
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text?` | `string` |  |  |
| `lines?` | `string[]` |  | STACKED header lines — the UML classifier convention of a «stereotype» over the name. Wins over `text` when present; the band grows to hold every line, and each line is fitted to the band width (shrunk, never clipped: «enumeration» over a 120px card used to paint "umeration» Enumera" cut off at both edges). |
| `height?` | `number` |  | Band height in px. Default 22, or 16/line + 4 when `lines` stack. |
| `fill?` | `string` |  |  |
| `textColor?` | `string` |  |  |

### `PanelIcon`

A small icon — a raster href, an emoji/text glyph, or a built-in line icon — pinned to a corner.

```ts
interface PanelIcon
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `href?` | `string` |  |  |
| `glyph?` | `string` |  | Emoji or short glyph, used when `href` is absent. |
| `name?` | `string` |  | A built-in line icon, used when there is no href or glyph: one of {@link BUILTIN_ICONS} (`cloud`, `database`, `disk`, `internet`, `server` — Mermaid architecture-beta's own). Drawn as our paths in the node's ink; an unknown name draws nothing. |
| `size?` | `number` |  | Box size in px. Default 18. |
| `corner?` | `PanelCorner` |  | Corner to pin to. Default 'tl'. |

### `PanelImage`

A raster image slot below the header (data: URI strongly preferred).

```ts
interface PanelImage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` |  |  |
| `height?` | `number` |  | Slot height in px. Default 48. |

### `PanelRenderContext`

Style inputs the host renderer supplies (theme-derived, CSS-mode aware).

```ts
interface PanelRenderContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  | Node id — used for stable child keys. |
| `fontSize` | `number` |  |  |
| `headerFill` | `string` |  |  |
| `headerTextColor` | `string` |  |  |
| `bodyTextColor` | `string` |  |  |
| `badgeFill` | `string` |  |  |
| `badgeTextColor` | `string` |  |  |

### `PanelRow`

A stacked body text row (ERD field / UML member).

```ts
interface PanelRow
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  |  |
| `align?` | `'start' \| 'middle' \| 'end'` |  |  |

### `PanelSpec`

The composite-panel spec stored at `node.metadata.panel`.

```ts
interface PanelSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `header?` | `PanelHeader` |  |  |
| `image?` | `PanelImage` |  |  |
| `icon?` | `PanelIcon` |  |  |
| `badges?` | `PanelBadge[]` |  |  |
| `rows?` | `PanelRow[]` |  |  |
| `rowHeight?` | `number` |  | Per-row height in px. Default 18. |

### `PathShapeOptions`

Options for {@link registerPathShape}.

By default the boundary point (smart-connection attachment) and the port
anchors are DERIVED from the path outline by sampling — so a custom silhouette
attaches links to its real edge, not its bounding box. Supply `portAnchor` /
`boundaryPoint` to override the sampled geometry with exact analytic anchors
(the same override seam the built-in triangle uses for its apex/base points).

```ts
interface PathShapeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewBox?` | `PathViewBox` |  | Reference box for a STATIC path string (default `0 0 1 1` — unit box). |
| `portAnchor?` | `ShapeDefinition['portAnchor']` |  | Exact port anchors, bypassing outline sampling. |
| `boundaryPoint?` | `ShapeDefinition['boundaryPoint']` |  | Exact smart-connection boundary, bypassing outline sampling. |
| `innerRect?` | `ShapeDefinition['innerRect']` |  | Label box; defaults to the padded bounding box. |
| `sampleSteps?` | `number` |  | Curve subdivision when sampling the outline (default 24). |

### `PathViewBox`

The author's declared reference box for a STATIC path string.

```ts
interface PathViewBox
```

**Properties**

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

### `PortGlyphInput`

```ts
interface PortGlyphInput
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  | Node-local anchor: the port's position. The glyph is CENTRED on it. |
| `y` | `number` |  |  |
| `shape?` | `PortShapeSpec` |  | Resolved glyph spec. Undefined → a circle of `radius` (the legacy glyph). |
| `radius` | `number` |  | The circle radius the interaction config asks for, and the size fallback. |
| `props` | `Record<string, unknown>` |  | Presentation attributes (fill/stroke/…) already merged from theme+group+port. |

### `PortLabelGeometry`

```ts
interface PortLabelGeometry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `rotation` | `number` |  | Total rotation in degrees (0 when the label is horizontal). |
| `align` | `'start' \| 'middle' \| 'end'` |  |  |
| `valign` | `'top' \| 'middle' \| 'bottom'` |  |  |

### `PortLabelInput`

```ts
interface PortLabelInput
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `PortLabelSpec` |  |  |
| `x` | `number` |  | Node-local anchor of the port's glyph. |
| `y` | `number` |  |  |
| `hw` | `number` |  | Half-extents of the glyph box — the label clears the glyph, not its centre. |
| `hh` | `number` |  |  |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` |  | The port's side: the outward normal. |
| `width` | `number` |  | Node box, for the `radial` layout's centre and for `inside` clamping. |
| `height` | `number` |  |  |
| `nudge?` | `number` |  | Vertical nudge applied by collision resolution (see `nudgePortLabels`). |
| `fontSize` | `number` |  |  |
| `fontFamily?` | `string` |  |  |
| `color?` | `string` |  |  |
| `className?` | `string` |  |  |

### `PortLayoutInput`

```ts
interface PortLayoutInput
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` |  | Node-local box the ports live in. |
| `height` | `number` |  |  |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` |  | The port's side (after group inheritance). |
| `rank` | `number` |  | This port's rank among the ports sharing its LAYOUT SCOPE, and the scope size. |
| `count` | `number` |  |  |
| `shapeType` | `string` |  | The node's shape type — the `shape` strategy needs it. |
| `rotation?` | `number` |  | The node's rotation in degrees (for `compensateRotation`). |

### `Rect`

```ts
interface Rect
```

**Properties**

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

### `RouteMemoStats`

```ts
interface RouteMemoStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `routed` | `number` |  | links whose route had to be computed this frame |
| `reused` | `number` |  | links served from the previous frame's route |

### `RouteSolverBridgeOptions`

```ts
interface RouteSolverBridgeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `port?` | `SolverPort` |  | A real Worker (or anything satisfying SolverPort). Omit to run the solver INLINE — same protocol, same code, same answers, just on this thread. The bridge does not construct a Worker itself: that would bake one bundler's URL scheme into the renderer, which is the mistake the old LayoutWorkerPool made. |
| `solver?` | `SolverOptions` |  |  |
| `onRoutesReady?` | `() => void` |  | "I have better routes than the ones you painted." Ask for a re-render. |

### `RouteSolverStats`

```ts
interface RouteSolverStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `submitted` | `number` |  |  |
| `applied` | `number` |  |  |
| `discarded` | `number` |  | answers thrown away because the world had moved on under them |
| `superseded` | `number` |  |  |

### `SelfLoopSpec`

```ts
interface SelfLoopSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `rect` | `FanoutRect` |  | World rect of the node both ends live on. |
| `start` | `FanoutPoint` |  | Source attachment point (world, on the node outline). |
| `end` | `FanoutPoint` |  | Target attachment point (world, on the node outline). |
| `sourceSide` | `FanoutSide` |  |  |
| `targetSide` | `FanoutSide` |  |  |
| `size` | `number` |  | How far the loop bulges away from the node body (px). |
| `width` | `number` |  | Lateral span used when the two ends coincide (or nearly do). |

### `ShapePoint`

```ts
interface ShapePoint
```

**Properties**

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

### `ShapeRect`

Node bounding box in WORLD coordinates (used by boundaryPoint).

```ts
interface ShapeRect
```

**Properties**

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

### `SpotInput`

```ts
interface SpotInput
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  | World position of the port's anchor (its glyph centre). |
| `y` | `number` |  |  |
| `hw` | `number` |  | Glyph half-extents — a spot names a corner/edge of THIS box. |
| `hh` | `number` |  |  |
| `side` | `Side` |  | The port's side: the default direction, and the default spot. |

<!-- source: grafloria-renderer-svg-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `DetectionMode`

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

Detection mode type

```ts
type DetectionMode = 'all' | 'perpendicular' | 'threshold';
```

### `FanoutSide`

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

```ts
type FanoutSide = 'left' | 'right' | 'top' | 'bottom';
```

### `LabelTemplate`

```ts
type LabelTemplate = (ctx: LabelTemplateContext) => VNode | VNode[] | null;
```

### `LinkPart`

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

The sub-part of a link that a query point resolved to.

```ts
type LinkPart =
  | 'body'
  | 'label'
  | 'source-endpoint'
  | 'target-endpoint'
  | 'source-arrow'
  | 'target-arrow';
```

### `LinkTemplate`

```ts
type LinkTemplate = (ctx: LinkTemplateContext) => VNode | VNode[] | null;
```

### `PanelCorner`

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

Icon/badge anchor: a corner, or `'c'` — dead centre of the node body
(a BPMN event's trigger glyph sits in the middle of its circle).

```ts
type PanelCorner = 'tl' | 'tr' | 'bl' | 'br' | 'c';
```

### `PathGeometry`

A static SVG path string, or a parametric generator that returns the path `d`
for a specific `width × height` box (0,0 at top-left). The generator form is
preferred for shapes whose detail should NOT scale uniformly (rounded corners,
fixed-radius notches); the static form is the quickest way to drop in a figure
authored in a design tool.

```ts
type PathGeometry = string | ((width: number, height: number) => string);
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` |  | Returns the length of a String object. |

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.

### `PortLayoutStrategy`

```ts
type PortLayoutStrategy = (input: PortLayoutInput, args: PortLayoutArgs) => { x: number; y: number };
```

### `ShapeSide`

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

```ts
type ShapeSide = 'left' | 'right' | 'top' | 'bottom';
```

### `Side`

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

```ts
type Side = FanoutSide;
```

### `ToolbarHaloAction`

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

The Halo context-toolbar actions a node may expose.

```ts
type ToolbarHaloAction = 'connect' | 'clone' | 'fork' | 'delete';
```

### `ToolbarResolver`

A per-TYPE policy the host installs on the controller.

```ts
type ToolbarResolver = (node: NodeModel) => NodeToolbarConfig | undefined;
```

<!-- source: grafloria-renderer-svg-arrowrenderer.md -->

# ArrowRenderer

Import it from `@grafloria/renderer`.

ArrowRenderer generates SVG VNodes for different arrow types.

Supports:
- Basic arrows (arrow, circle, square, diamond)
- ERD arrows (crow-foot, one, zero-or-one, zero-or-many, one-or-many)
- UML arrows (hollow-diamond, filled-diamond, generalization, open-arrow, double-arrow)
- Additional arrows (cross, bar, dot, oval)
- Half-arrowheads (Mermaid 11.13) — `half-arrow-left` / `half-arrow-right`
- AUTHOR-DEFINED markers: a raw SVG `path`, or anything
  registered with `registerMarker` — the catalogue is no longer a closed enum.

```ts
class ArrowRenderer
```

**Methods**

- `getTipOffset(style: ArrowStyle): number` — Distance from the marker's local origin to its forward-most point (its
visual tip), in the +x direction the marker is rotated toward.

The renderer positions markers by pulling the transform origin back from
the path endpoint by exactly this amount so every tip lands ON the port —
a uniform offset only fits the triangle family and left circles/diamonds
floating off the node.

A custom marker declares its own. Precedence is
`style.tipOffset` (explicit) > the registered marker's > 0 (a raw `path`
marker is assumed to be drawn with its tip at the origin).
- `renderArrow( style: ArrowStyle, transform: string, backgroundColor: string = 'white', end: 'source' | 'target' = 'target' ): VNode | null` — Render an arrow based on the provided style and transform

**Example**

```typescript
const renderer = new ArrowRenderer();
const arrowVNode = renderer.renderArrow({
  type: 'crow-foot',
  size: 10,
  filled: false,
  color: '#000'
}, 'translate(100, 50) rotate(45)');
```

**Example**

 A custom marker
```typescript
registerMarker('feather', {
  tipOffset: style => style.size,
  render: ctx => ({ type: 'path', props: { d: `M0,0 L${ctx.size},0`, stroke: ctx.color, transform: ctx.transform } }),
});
link.updateStyle({ arrowHead: { type: 'feather', size: 12, filled: true } });
```

<!-- source: grafloria-renderer-svg-shapedefinition.md -->

# ShapeDefinition

Import it from `@grafloria/renderer`.

The single geometry contract every node shape implements. Register once via
{@link registerShape} and the shape works across body, selection, shadow,
smart-connection boundary and port positioning — no switch edits required.

```ts
interface ShapeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `styleMode?` | `'inline' \| 'spread'` |  | How the node body applies node styles. Defaults to 'inline'. |
| `bodyStripKeys?` | `string[]` |  | Style keys dropped from the body's pass-through props (circle: rx, ry). |
| `bodyDeferGeomKeys?` | `string[]` |  | Geometry keys emitted AFTER the pass-through props in the body, so an explicit value overrides one arriving via the styles object. rect defers rx/ry so an explicit cornerRadius wins over a themed borderRadius. |

**Members**

- `outline(width: number, height: number, transform?: OutlineTransform): OutlineSpec` — Outline geometry under a transform (drives body + selection + shadow).
- `boundaryPoint(rect: ShapeRect, side: ShapeSide, cross: number): ShapePoint | null` — Point on the outline for a floating smart-connection attachment on `side`
at cross-axis coordinate `cross` (world coords). Return null to fall back
to the bounding-box edge (rect and unknown shapes do this).
- `portAnchor( width: number, height: number, side: ShapeSide, rank: number, count: number ): ShapePoint` — Local-space port anchor on `side` for port `rank` of `count` on that side.
- `innerRect?(width: number, height: number): InnerRect` — The label box in local coords (0,0 = top-left). Used by the node label
engine to wrap, clip and ellipsis-truncate text inside the silhouette. Optional — omit to accept the padded-bbox default ({@link defaultInnerRect}).

<!-- source: grafloria-renderer-svg-svgrenderer.md -->

# SVGRenderer

Import it from `@grafloria/renderer`.

```ts
class SVGRenderer implements IRenderer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` |  |  | Renderer mode |
| `capabilities` | `RendererCapabilities` |  | What this renderer can actually do — so callers can ask instead of assuming. `supportsExport` is now TRUE (see `export()` below); hit-testing and text measurement still are not implemented here, and saying so is the point. |

**Methods**

- `getRegistry(): DiagramRegistry` — Register shapes / styles / markers / link-pipeline stages for THIS renderer
alone. The module-level `registerShape()` & friends remain the process-wide
registry, and this one shadows it — see `ext/diagram-registry.ts`.
- `constructor( private engine: DiagramEngine, config: SVGRendererConfig = {}, theme?: Theme )`
- `render(viewport: Rectangle, zoom: number): VNode` — Render diagram to VNode tree.

THE REGISTRY SCOPE IS ACTIVATED HERE, around the whole pass, and this is the
only place it needs to be for the picture to be right. Every contribution
registry the frame consults — shapes, named styles, link/label templates,
markers, anchors, connection points, connectors — resolves this diagram's
own table first and the process-global one second, including from the read
sites that are pure free functions three frames down (`shapeStrategy` in
port-layout, `resolveNodeStyle` in the style cascade) and could not have been
handed an instance without rewriting their signatures. See
`ext/registry-scope.ts`.

A diagram that contributed nothing activates nothing, so the single-diagram
path is byte-identical to what it was.
- `getQualityState(): { tier: LODLevel; governor?: GovernorState }` — The tier actually rendered last frame, and the governor's reasoning for it.

Exposed because an invisible governor is indistinguishable from a bug: if the
picture silently simplifies, the only honest thing to do is be able to say WHY. The perf HUD reads this; so can an application that wants to tell the user "this
diagram is being drawn at reduced detail to stay responsive".
- `invalidateFrame(): void` — Drop the cached frame. Call from anything whose effect on the picture the
mutation epoch cannot see — a topology event, a style/theme invalidation, a
registry swap. Cheap and idempotent: the cost of calling it when you did not
need to is one rebuilt frame; the cost of NOT calling it when you did is a
stale picture, so when in doubt, call it.
- `getInvalidationEpoch(): number` — How many times this renderer has been told "the picture you have is no longer
the picture you would draw".

A HOST'S idle-skip must consult this, not just the model's mutation epoch. The two are not the same, and the gap between them is a real bug: when the
off-thread route solver answers, the MODEL has not changed — the epoch does
not move — but the renderer's own answer about it has improved. A scheduler
keyed only on the model would drop that repaint before `render()` was ever
called, and the refined routes would never reach the screen. The renderer's
internal gate cannot save you there; it never gets asked.

So: model epoch says "did the world change", this says "did MY picture of it
change". Skip a frame only when both say no.
- `getFrameCoverage(): FrameCoverage | null` — The {@link FrameCoverage} of the most recent `render()` pass.

CAPTURE IT IMMEDIATELY after the render() call whose frame you patched into
the DOM — do not hold the renderer and ask later. Exports run through the
same render pass with their own viewport (see exportSvg callers), so this
field describes whatever rendered LAST, which is not necessarily what is on
screen. `createDiagram`'s paint() takes its own copy for exactly this
reason.
- `getFrameStats(): { built: number; skipped: number }` — The incrementality is only real if these move. `framesSkipped`
counts frames served from the previous root (zero DOM work); `framesBuilt`
counts frames actually walked. An idle canvas should build ONE.
- `getTheme(): Theme` — Get current theme
- `setHighlightConnected(value: boolean | HighlightConnectedOptions | undefined): void` — Switch `highlightConnected` live: `false` turns it off, `true` takes the
defaults, an object tunes it. The next frame redraws every line.
- `getHighlightConnected(): boolean | HighlightConnectedOptions`
- `getLineOverlay(): VNode | null` — The lifted lines, as an `<svg>` in WORLD coordinates for the overlay the
instance keeps at the end of the HTML layer — above SVG nodes and HTML
custom nodes alike, moved by the same camera transform. `null` when
`highlightConnected` is off; an empty `<svg>` when nothing is lifted.
- `setTheme(theme: Theme): void`
- `applyThemeVariables(theme: Theme): void` — THE HOT-SWAP. Re-theme by rewriting this instance's `--grafloria-*` variables.

In CSS mode every value the built-in stylesheet paints resolves through those
variables, and every `themeRef`-bound property that lands in an inline CSS
style string is emitted as `var(--grafloria-…)`. So for all of them, *this one
string write IS the re-theme*: no VNode is rebuilt, no element is touched,
the browser simply recomputes.

What it cannot cover, it does not pretend to: the entities recorded in
`themeBoundNodes` / `themeBoundLinks` (see the field docs) baked a theme
literal into their VNode, so they — and only they — are marked dirty and
re-resolve on the next frame. An idle diagram re-themes with zero restyles;
a diagram with three selected nodes restyles three nodes.

Programmatic (Canvas) mode has no stylesheet at all, so there is nothing to
rebind and the full invalidation is the only correct answer.
- `getColorMode(): ColorMode | undefined` — The colorMode in force, or undefined when the host never asked for one.
- `setColorMode(mode: ColorMode, themes?: ThemeSet): void` — Switch colour mode at runtime. `'system'` starts following the OS; the other
two pin it. Creates the media-query subscription on first use, so a host can
opt in after construction.
- `setTokenBridge(bridge: TokenBridge | null | undefined): void` — Point this diagram's variables at the host design system's tokens
(`shadcnBridge()`, `muiBridge()`, `tailwindBridge()`, or a hand-written map). `null` removes the bridge.

Pure CSS: the values are the host's own `var(--…)` expressions, so when the
host app flips ITS theme, this diagram follows with no code at all — and no
VNode is rebuilt here either, for exactly the reason the hot-swap works.
- `getTokenBridge(): TokenBridge | undefined` — The bridge currently applied, if any.
- `getInstanceId(): string` — This renderer's instance id (`grafloria-3`). It is the value of the
`data-grafloria-instance` attribute on the root `<svg>`, the scope of this
diagram's CSS variables, and the suffix of its `<style>` element id.
- `getStyleElementId(): string` — Id of the `<style>` element holding THIS renderer's theme variables.
- `getOverrideElementId(): string` — Id of the `<style>` element holding THIS renderer's bridge + a11y overrides.
- `getStyleSheet(): string` — The complete stylesheet this renderer would inject into `<head>`: the shared
theme-independent rules, the animation rules, and THIS instance's
`--grafloria-*` variable block.

Needed by the SSR path. In CSS mode the theme lives entirely in CSS
variables, so the emitted SVG is theme-INDEPENDENT — which is exactly what
makes hydration cheap, but it also means a server-rendered diagram is
unstyled until some stylesheet arrives. `renderToStaticSVG()` returns this
string so the server can ship it in a `<style>` tag; the client renderer then
re-injects byte-identical content under the same ids, so hydration is still a
no-op visually.
- `applyInstanceScope(element: Element | null | undefined): void` — Put this diagram's scope on a host element.

The root `<svg>` carries it automatically, and `foreignObject` content
inherits from it (it lives inside the SVG). Nodes rendered on an HTML LAYER
(`metadata.useHTMLLayer`) do NOT — they are siblings of the SVG. Call this
with the element that wraps BOTH layers (the canvas host) so those nodes
inherit the `--grafloria-*` variables and match the scoped rules too.
- `setViewLifecycle(lifecycle: ViewLifecycle | null): void` — Install the freeze / lazy-mount gate.

With no lifecycle installed the renderer behaves exactly as it always has —
every entity culling admits gets a view, on the frame it is admitted. That is
the default, and it stays the default: laziness is something a host asks for.
- `getViewLifecycle(): ViewLifecycle | null`
- `getDeferredEntities(): ReadonlyArray<readonly [LazyEntityKind, string]>` — What culling admitted on the last frame and the gate held back.

This is the progressive mounter's work queue, and it comes from the renderer
rather than being recomputed by the mounter because the viewport→viewBox→cull
maths (zoom, link margin) lives here and must not be reimplemented anywhere it
could drift.
- `getThemeBoundEntityCount(): number` — How many entities the NEXT theme swap would have to restyle. Zero means the
swap is a pure variable rebind. Exposed because "no restyle of every VNode"
is a claim that should be measurable, not taken on trust — the tests assert
on it, and so can a host.
- `getPerformanceMetrics(): PerformanceMetrics` — Get performance metrics
- `async export(format: ExportFormat = 'svg', options: ExportOptions = {}): Promise<string>` — Export the diagram.

- `'svg'` → a STANDALONE, styles-inlined SVG document. Pure, deterministic,
  and DOM-free: it runs in plain Node (an SSR pass, a thumbnail worker).
- `'png' | 'jpeg' | 'webp'` → a `data:` URL. Needs an SVG rasterizer: a
  canvas one is used automatically in a browser/worker; in bare Node you must
  pass `options.rasterBackend` (and you get a clear error if you don't).

Defaults to the whole diagram (content bounds + 20px), not the current
viewport — a thumbnail of the visible slice is rarely what anyone means.
- `exportSvgString(options: ExportOptions = {}): SvgExportResult` — The synchronous, fully headless SVG path — what `export('svg')` returns, plus
the fidelity `warnings` (foreignObject, unresolved theme vars) that the
string-only `IRenderer.export` signature has nowhere to put.
- `exportPdf(options: ExportOptions = {}): PdfExportResult` — A TRUE VECTOR PDF: paths stay paths and text stays text, so it is selectable,
searchable and scales without pixelation.

Painted straight from the VNode tree — the same tree the screen gets — so there is no
SVG→DOM→PDF round trip and no second rendering path. See `export/pdf/` for the
dependency decision (we do NOT use svg2pdf.js + jsPDF, and why) and for the honest
list of what a base-14-font PDF cannot do.
- `exportPages(pagination: PaginationOptions, options: ExportOptions = {}): PagedSvgResult` — Slice the diagram into pages.

Returns one standalone SVG per page — a tile grid you can print, or lay out as a poster. Breaks are snapped so they do not cut a node in half; see `export/pagination.ts`.
- `exportPaginatedPdf(pagination: PaginationOptions, options: ExportOptions = {}): PdfExportResult` — A multi-page PDF of a diagram too big for one sheet.

The paginator supplies the page grid; the PDF writer honours each page's `clip`, so a
break pulled back to spare a node leaves white space rather than half a box.
- `collectExportImageUrls(options: ExportOptions = {}): string[]` — Every EXTERNAL image URL the exported tree will reference — a panel node's
avatar/logo/icon (`<image href="https://…">` painted by the renderer itself), or
any registered shape that emits one. Widget (HTML-layer) captures are NOT in this
tree; their URLs are collected from the captures by the instance layer.

This is the LOOK-BEFORE-YOU-EXPORT half of the async image pass: `await export(…)`
calls this first, fetches the URLs through the tiers, and hands the resolved map
back down as {@link ExportOptions.resolvedAssets} for the pure sync substitution. The tree is enumerated from the SAME `render()` the export will serialize (VNode
caching makes the second call cheap), so what is collected and what is substituted
cannot drift. Synchronous and network-free.
- `getRoutingStats(): { routed: number; reused: number; cached: number }` — How many links this frame actually had to route, and how
many were served from the previous frame.

Public because a cache that silently stops hitting is indistinguishable from
no cache at all — it just gets slow again, and nothing says so. Tests assert
on this; the benchmark harness prints it.
- `dispose(): void` — Dispose renderer and clean up resources
- `getRouteSolverStats(): RouteSolverStats | null` — What the off-thread solver has been doing.
- `setAccessibleFocus(target: { type: 'node' | 'link' | 'comment'; id: string } | null): void` — Tell the renderer which entity the keyboard controller has focused, so the
next frame emits `tabindex=0` on it (and `-1` on everything else).

Marks only the OLD and NEW focus targets dirty — moving focus must not
invalidate the whole diagram.
- `getAccessibleFocus(): { type: 'node' | 'link' | 'comment'; id: string } | null`
- `setCommentSource(source: CommentSource | null): void` — Attach (or detach) the source of comment pins.

Installing a source CHANGES THE PICTURE while moving nothing the frame gate watches —
not the model epoch, not the viewport. Without the explicit invalidation the gate would
keep serving back the last frame, which has no pins in it, forever. This is the trap
this wave was warned about, and it is one line.
- `getCommentSource(): CommentSource | null`
- `getContainerId(nodeId: string): string | undefined` — Get container ID for a node (if it uses foreignObject)
- `isUsingForeignObject(nodeId: string): boolean` — Check if a node uses foreignObject rendering
- `getAnimationService(): AnimationService` — The animation service — global animation enable/speed, reduced-motion and
battery-saver policy. Public because these are HOST decisions: the service
existed with a full config surface and no accessor, so nothing outside
this class could e.g. opt out of the battery auto-toggle
(`respectBatteryStatus: false`) — a laptop under 20% silently killed every
edge animation with no way back.

<!-- source: grafloria-renderer-svg-textblockoptions.md -->

# TextBlockOptions

Import it from `@grafloria/renderer`.

```ts
interface TextBlockOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  | The label text. Honors explicit '\n' as hard line breaks. |
| `x` | `number` |  | Anchor X in the local coordinate space of the returned <text>. |
| `y` | `number` |  | Anchor Y in the local coordinate space of the returned <text>. |
| `maxWidth?` | `number` |  | Wrap width. Omit / Infinity → no wrapping (one line unless '\n' present). |
| `align?` | `'start' \| 'middle' \| 'end'` |  | Horizontal text anchor. Default 'middle'. |
| `valign?` | `'top' \| 'middle' \| 'bottom'` |  | Vertical alignment of the whole block around `y`. Default 'middle'. |
| `fontSize?` | `number` |  | Font size in px used for BOTH measurement and (optionally) emission. |
| `fontFamily?` | `string` |  |  |
| `fontWeight?` | `number \| string` |  | Font weight, emitted only when defined. |
| `color?` | `string` |  | Fill color. Emitted only when defined (CSS-mode callers omit it). |
| `className?` | `string` |  |  |
| `clipId?` | `string` |  | When set, apply clip-path: url(#clipId) so overflow is hard-clipped. |
| `maxLines?` | `number` |  | Max rendered lines; extra lines collapse into an ellipsis on the last. |
| `lineHeight?` | `number` |  | Line-height multiplier. Default 1.2. |
| `emitFontSize?` | `boolean` |  | Emit the numeric fontSize as an attribute. Default true (CSS mode: false). |
| `nonInteractive?` | `boolean` |  | Set pointer-events: none (node labels don't intercept the mouse). |

<!-- source: grafloria-renderer-themes.md -->

# Themes

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-classes): 1 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-constants): 16 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-functions): 50 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-interfaces): 11 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-themes-types): 5 types.

<!-- source: grafloria-renderer-themes-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `ColorModeController`

Watches the OS preferences and calls back with the theme that should now be
active. Owns its listeners; `dispose()` removes every one of them.

It subscribes to the contrast/forced-colors queries even in explicit
light/dark mode — those are ACCESSIBILITY preferences, and a user who turns on
high contrast must be honoured whether or not the host let them choose a
colour scheme.

```ts
class ColorModeController
```

**Methods**

- `constructor(mode: ColorMode, themes: ThemeSet, onTheme: (theme: Theme) => void)`
- `resolve(): Theme` — The theme the current mode + OS preferences resolve to.
- `getMode(): ColorMode` — The mode this controller is following.
- `setMode(mode: ColorMode): void` — Switch modes. Emits immediately if the resolved theme actually changed.
- `setThemes(themes: ThemeSet): void` — Swap the theme SET (e.g. the host shipped its own light/dark pair).
- `emit(): void` — Push the current resolution to the callback. Deduped by identity: an OS
change that does not change the ANSWER (contrast toggled while a host
supplied no high-contrast theme) must not trigger a re-theme.
- `prime(theme: Theme): void` — Prime `current` without calling back — the renderer already has this theme.
- `dispose(): void`

<!-- source: grafloria-renderer-themes-constants.md -->

# Constants

Import these from `@grafloria/renderer`.

## Constants

### `BASE_STYLE_RULES`

Every themed rule the renderer ships, in cascade order.

INVARIANT (pinned by svg-renderer.scoped-theme.spec): no rule here may carry a
theme literal — every painted value resolves through `var(--grafloria-*)`, and
every referenced variable is declared in {@link THEME_VARS}. `fill: none` on
links is structural (a link is a stroke, never a fill), not a theme value.

```ts
const BASE_STYLE_RULES: readonly StyleRule[]
```

### `BRIDGEABLE_TOKENS`

Every token a bridge MAY set — the contract a custom bridge is checked against.

```ts
const BRIDGEABLE_TOKENS: ThemeToken[]
```

### `CASCADE_ORDER`

The documented cascade, lowest → highest. Exported for docs/tests.

```ts
const CASCADE_ORDER: readonly ["theme", "type-default", "named-class", "element-inline", "state"]
```

### `DARK_THEME`

Dark Theme
Professional, accessible color palette optimized for dark backgrounds

```ts
const DARK_THEME: Theme
```

### `DEFAULT_THEME_SET`

Default set: our light/dark pair, plus the validated high-contrast pair the
ColorModeController upgrades to when the user asks for more contrast.

The high-contrast entries are populated on purpose. A host that never thinks
about accessibility still gets a real high-contrast theme the moment its user
turns the OS preference on — an a11y default that is opt-OUT, not opt-in.

```ts
const DEFAULT_THEME_SET: ThemeSet
```

### `GRAFLORIA_INSTANCE_ATTR`

Attribute stamped on a diagram's root `<svg>` (and, via
`SVGRenderer.applyInstanceScope()`, on any HTML host that wraps nodes rendered
outside the SVG) carrying the renderer's instance id. Both the variable block
and every rule in the shared stylesheet are scoped through it.

```ts
const GRAFLORIA_INSTANCE_ATTR: "data-grafloria-instance"
```

### `GRAFLORIA_VAR_PREFIX`

Prefix of every custom property this renderer defines.

```ts
const GRAFLORIA_VAR_PREFIX: "--grafloria-"
```

### `HIGH_CONTRAST_DARK_THEME`

Pure white on pure black: the maximum-contrast dark scheme.

```ts
const HIGH_CONTRAST_DARK_THEME: Theme
```

### `HIGH_CONTRAST_LIGHT_THEME`

Pure black on pure white: the maximum-contrast light scheme (21:1 text).

```ts
const HIGH_CONTRAST_LIGHT_THEME: Theme
```

### `LIGHT_THEME`

Light Theme (Default)
Professional, accessible color palette optimized for light backgrounds

```ts
const LIGHT_THEME: Theme
```

### `MEDIA_FORCED_COLORS`

```ts
const MEDIA_FORCED_COLORS: "(forced-colors: active)"
```

### `MEDIA_PREFERS_CONTRAST`

```ts
const MEDIA_PREFERS_CONTRAST: "(prefers-contrast: more)"
```

### `MEDIA_PREFERS_DARK`

```ts
const MEDIA_PREFERS_DARK: "(prefers-color-scheme: dark)"
```

### `THEME_TOKENS`

All tokens, in table order.

```ts
const THEME_TOKENS: ThemeToken[]
```

### `THEME_VARS`

THE table. One entry per token; nothing else in the renderer may invent a
`--grafloria-*` name.

A handful of bindings are CONSTANTS today (`() => 2`): the emphasis
stroke-widths the stylesheet has always hardcoded. Routing them through the
table means a later card can bind them to a real theme token (or let users
override the custom property directly) without touching the stylesheet.

```ts
const THEME_VARS: Record<ThemeToken, ThemeVarBinding>
```

### `WCAG`

WCAG 2.x conformance thresholds.

```ts
const WCAG: { readonly AA_TEXT: 4.5; readonly AA_LARGE: 3; readonly AA_NON_TEXT: 3; readonly AAA_TEXT: 7; readonly AAA_LARGE: 4.5; }
```

<!-- source: grafloria-renderer-themes-functions.md -->

# Functions

Import these from `@grafloria/renderer`.

## Functions

### `assertThemeContrast`

Throw with a readable diff when a theme does not conform. Use in tests/CI.

```ts
function assertThemeContrast(theme: Theme, textLevel: number = WCAG.AA_TEXT): void
```

### `auditThemeContrast`

Every contrast pair in a theme that a reader depends on.

`textLevel` defaults to AA (4.5:1). Pass `WCAG.AAA_TEXT` to hold a theme to
AAA — which is what the high-contrast themes are built and tested against.

```ts
function auditThemeContrast(theme: Theme, textLevel: number = WCAG.AA_TEXT): ContrastReport
```

### `clearStyles`

Drop every named style (tests, and hosts tearing a document down).

```ts
function clearStyles(): void
```

### `contrastRatio`

Contrast ratio between two colours, 1…21. `undefined` when either colour is
not one we can parse (see {@link parseColor}).

```ts
function contrastRatio(a: string, b: string): number | undefined
```

### `cssVarName`

`--grafloria-node-fill` — the custom property a token maps to.

```ts
function cssVarName(token: ThemeToken): string
```

### `defineStyle`

Define (or redefine) a named style. Definitions are copied, so later mutation
of the caller's object has no effect.

```ts
function defineStyle(name: string, style: NamedStyle): void
```

### `defineStyles`

Define several named styles at once.

```ts
function defineStyles(styles: Record<string, NamedStyle>): void
```

### `deriveTheme`

Auto-derive a theme from another one, then PROVE it conforms.

The generation step is deliberately dumb (flip lightness for 'dark', keep the
palette for 'high-contrast'); the value is in the second step, which walks the
SAME audit the caller can run and repairs every enforceable failure with
`ensureContrast`. The result is asserted before it is returned, so a derived
theme that could not be repaired is a loud error, never a subtly unreadable
diagram.

Derived alongside the surfaces: the STATE colours (selected / highlighted /
hovered / disabled / error), the SECONDARY text, and the semantic category
palette — i.e. everything a theme swap has to move together for the diagram to
stay coherent.

```ts
function deriveTheme(options: DeriveThemeOptions): Theme
```

### `ensureContrast`

Push `foreground` away from `background` until it clears `minimum`.

Walks in whichever direction the background is NOT (a light background darkens
the foreground, a dark one lightens it) in fixed steps, and takes the first
step that passes. Black/white are the endpoints, so on any real background
this terminates with a passing colour — that is why the derived themes can be
ASSERTED to conform rather than eyeballed.

Returns the input untouched when it already passes, or when either colour is
unparseable (nothing sensible to do — the audit will report it).

```ts
function ensureContrast(foreground: string, background: string, minimum: number): string
```

### `generateBaseStyleSheet`

The shared, theme-INDEPENDENT stylesheet. Identical for every renderer on the
page, so it is injected once and deduped by element id.

```ts
function generateBaseStyleSheet(): string
```

### `generateContrastPreferenceBlock`

`prefers-contrast: more`, in CSS.

The ColorModeController swaps in a whole high-contrast THEME when the host gave
it one. This block is what a host that did NOT still gets: thicker strokes. Weight is the half of contrast that colour cannot supply — a 1px hairline is
not an accessible border however dark it is — and it is the one thing we can
safely strengthen without knowing anything about the host's palette.

```ts
function generateContrastPreferenceBlock(instanceId: string): string
```

### `generateForcedColorsBlock`

The `@media (forced-colors: active)` variable override for one instance.

Emitted for every renderer, unconditionally: it costs one inert media block and
it is the FLOOR — it protects hosts that never supplied a high-contrast theme
and never touched `colorMode`. (The ColorModeController's high-contrast upgrade
is the ceiling: a better-looking, fully-checked theme when one exists.)

`forced-color-adjust: none` is deliberately NOT set: we are opting IN to the
user's colours, not out of them.

```ts
function generateForcedColorsBlock(instanceId: string): string
```

### `generateInstanceOverrideCSS`

Everything that must sit AFTER the theme's variable block, in cascade order. One string, one `<style>` element, one guaranteed ordering.

```ts
function generateInstanceOverrideCSS(
  bridge: TokenBridge | undefined,
  instanceId: string
): string
```

### `generateInstanceVarBlock`

One renderer's variable block: the ONLY place a theme's values are written. Scoped to that renderer's root, so a second diagram with a different theme
cannot be repainted by it.

```ts
function generateInstanceVarBlock(theme: Theme, instanceId: string): string
```

### `generateTokenBridgeBlock`

The bridge's CSS block for one instance, or `''` when there is nothing to map.

```ts
function generateTokenBridgeBlock(bridge: TokenBridge | undefined, instanceId: string): string
```

### `getStyle`

The raw definition, or undefined when the name was never defined.

DIAGRAM-FIRST, then process-global — see `ext/registry-scope.ts`. A diagram
that defined its own `critical` sees its own; one that did not still sees the
app-wide definition.

```ts
function getStyle(name: string): NamedStyle | undefined
```

### `getStyleRegistryVersion`

Bumped on every mutation — renderers key cache invalidation off this.

```ts
function getStyleRegistryVersion(): number
```

### `hasStyle`

```ts
function hasStyle(name: string): boolean
```

### `hslToRgb`

```ts
function hslToRgb({ h, s, l }: Hsl): Rgb
```

### `instanceScopeSelector`

`[data-grafloria-instance="grafloria-3"]` — selects one diagram's root (and scoped hosts).

```ts
function instanceScopeSelector(instanceId: string): string
```

### `isThemeRef`

True when a style value is a theme reference rather than a literal.

```ts
function isThemeRef(value: unknown): value is ThemeRef
```

### `lightnessOf`

HSL lightness of a colour, 0-1. Undefined for unparseable input.

```ts
function lightnessOf(hex: string): number | undefined
```

### `linkTypeKey`

A link's "type" for `theme.links[type]`: an explicit `type` metadata key when
the host sets one, else the path type (`smooth` / `orthogonal` / …), which is
the structural analogue of React Flow's `edge.type`.

```ts
function linkTypeKey(link: LinkModel): string
```

### `listStyles`

```ts
function listStyles(): string[]
```

### `meetsContrast`

Does this pair clear a threshold? Unparseable colours are NOT a pass.

```ts
function meetsContrast(a: string, b: string, minimum: number): boolean
```

### `muiBridge`

MUI (Material UI) with CSS-variable theming enabled
(`extendTheme` / `CssVarsProvider`, which publishes `--mui-palette-*`).

```ts
function muiBridge(prefix = '--mui'): TokenBridge
```

### `onStyleRegistryChange`

Subscribe to registry mutations. Returns the unsubscribe function.

```ts
function onStyleRegistryChange(listener: () => void): () => void
```

### `parseColor`

Parse the colour forms a theme can actually hold: `#rgb`, `#rgba`, `#rrggbb`,
`#rrggbbaa`, `rgb()/rgba()`.

`undefined` for anything else — a CSS system colour (`CanvasText`), a
`var(--x)`, a gradient spec. Callers must SKIP those rather than pretend a
ratio: a contrast claim about a value we cannot see is worse than no claim.

```ts
function parseColor(value: string): Rgb | undefined
```

### `readColorPreferences`

Read the three OS preferences right now.

```ts
function readColorPreferences(): ColorPreferences
```

### `relativeLuminance`

WCAG relative luminance (0 = black, 1 = white).

```ts
function relativeLuminance(color: Rgb): number
```

### `removeStyle`

```ts
function removeStyle(name: string): boolean
```

### `resolveBindableVars`

Every BINDABLE token of a theme, as `{ '--grafloria-colors-primary': '#2563eb', … }`.

This is the second half of the instance variable block (the first being the 33
chrome vars). Together they are the complete set of values a `themeRef` can
point at — which is exactly what makes a theme swap expressible as "rewrite
this instance's variables" instead of "rebuild every VNode".

```ts
function resolveBindableVars(theme: Theme): Record<string, string>
```

### `resolveLinkStyle`

Resolve a link's effective style. ONE ordered spread — see the header.

```ts
function resolveLinkStyle(
  link: LinkModel,
  theme: Theme,
  options: CascadeOptions = {}
): Partial<LinkStyle>
```

### `resolveNodeSelectionLook`

How this node shows it is selected, resolved through the cascade: its own
style, a named style, its type's theme defaults, the theme-wide default —
else 'both'. The renderer reads it for the ring and the CSS state class.

```ts
function resolveNodeSelectionLook(node: NodeModel, theme: Theme): NodeSelectionLook
```

### `resolveNodeStyle`

Resolve a node's effective style. ONE ordered spread — see the header.

```ts
function resolveNodeStyle(
  node: NodeModel,
  theme: Theme,
  options: CascadeOptions = {}
): Partial<NodeStyle>
```

### `resolveStyleClasses`

Merge a `styleClass` list into ONE partial style. Names are applied
left-to-right (later names win); unknown names are ignored.

```ts
function resolveStyleClasses<T extends NamedStyle>(styleClass: string | undefined): Partial<T>
```

### `resolveThemeFromPrefs`

THE resolution rule, as one pure function.

1. `colorMode` picks the light/dark AXIS ('system' → the OS's answer).
  2. An explicit contrast preference (`prefers-contrast: more`, or a forced-
     colors mode) then upgrades that axis to the high-contrast theme, when the
     caller supplied one. It is an UPGRADE, not a replacement: a user in dark
     mode who wants more contrast gets high-contrast DARK, not a light flash.

Note `forced-colors` ALSO gets a pure-CSS treatment (the variable block emits a
system-colour override under `@media (forced-colors: active)`), because the OS
palette must win even for a host that never passed a high-contrast theme. The
two are complementary: this picks the best THEME we have; that guarantees the
floor.

```ts
function resolveThemeFromPrefs(
  mode: ColorMode,
  prefs: ColorPreferences,
  themes: ThemeSet
): Theme
```

### `resolveThemeRef`

Resolve a token against a theme. `undefined` when the theme does not define it
— callers must treat that as "this property was never set" (the cascade layer
below it, or the stylesheet, then wins) rather than painting `undefined`.

```ts
function resolveThemeRef(token: string, theme: Theme): string | number | undefined
```

### `resolveThemeVars`

The whole theme as `{ '--grafloria-node-fill': '#ffffff', … }`. Also the natural shape for design-token export / Canvas-side lookups.

```ts
function resolveThemeVars(theme: Theme): Record<string, string>
```

### `rgbToHsl`

```ts
function rgbToHsl({ r, g, b }: Rgb): Hsl
```

### `shadcnBridge`

```ts
function shadcnBridge(options: { space?: 'hsl' | 'oklch' | 'raw' } = {}): TokenBridge
```

### `tailwindBridge`

Tailwind v4, whose theme IS a set of CSS variables (`--color-slate-200`, …). `scale` picks the neutral ramp so a host can stay on its own greys.

```ts
function tailwindBridge(options: { scale?: string; accent?: string } = {}): TokenBridge
```

### `themeRef`

Bind a property to a theme token.

node.setStyle({ fill: themeRef('category.critical') })

The `any` return is what lets a ThemeRef sit in a `fill?: string | Gradient | …`
slot: the engine's style types are the PUBLIC model contract and stay free of
any renderer type, so the renderer — the only thing that ever resolves a ref —
owns the marker and detects it structurally with {@link isThemeRef}.

```ts
function themeRef(token: ThemeToken | string): any
```

### `themeRefCssValue`

How a bound property is emitted in CSS mode when the target property accepts
`var()` (i.e. it is written into an inline CSS `style` string):
`var(--grafloria-category-critical, #b91c1c)`.

The literal FALLBACK matters: a theme that simply does not define the token
would otherwise make the declaration invalid at computed-value time and the
element would lose the property entirely (an SVG shape with no `fill` paints
black). With the fallback it degrades to the value the token had when the
VNode was built, which is the closest thing to "unchanged" available.

```ts
function themeRefCssValue(token: string, theme: Theme): string | undefined
```

### `themeRefToken`

The token a reference points at.

```ts
function themeRefToken(ref: ThemeRef): string
```

### `themeRefVar`

`node.selected.fill` → `--grafloria-node-selected-fill`.

Mechanical, not a lookup: the same rule reproduces every entry of THEME_VARS
(pinned by a test), so chrome tokens and caller tokens share ONE naming law
and nothing has to be registered ahead of time.

```ts
function themeRefVar(token: string): string
```

### `themeVar`

`var(--grafloria-node-fill)` — the reference the shared stylesheet is written in.

```ts
function themeVar(token: ThemeToken): string
```

### `themeVarValue`

Serialize one token's value for CSS (adds the unit for numeric bindings).

```ts
function themeVarValue(token: ThemeToken, theme: Theme): string
```

### `toHex`

`{r:255,g:0,b:0}` → `#ff0000`.

```ts
function toHex({ r, g, b }: Rgb): string
```

### `withLightness`

Same hue and saturation, new lightness. The primitive the dark-flip is built on.

```ts
function withLightness(hex: string, lightness: number): string
```

<!-- source: grafloria-renderer-themes-interfaces.md -->

# Interfaces

Import these from `@grafloria/renderer`.

## Interfaces

### `CascadeOptions`

```ts
interface CascadeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeThemeBase?` | `boolean` |  | Include the theme base as layer 1. Programmatic/Canvas mode must (there is no stylesheet); CSS mode must NOT (the stylesheet paints it, and inlining it would defeat the theme fallback and the CSS-variable scoping). |
| `connection?` | `Partial<LinkStyle>` |  | LINKS ONLY — the `highlightConnected` layer for a line touching the selection. It sits over the link's own style and its hover, and UNDER a selected or highlighted link's state: a line the user selected keeps the selection's look. |

### `ColorPreferences`

The OS-level preferences that decide which theme wins.

```ts
interface ColorPreferences
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `prefersDark` | `boolean` |  | `prefers-color-scheme: dark` |
| `prefersContrast` | `boolean` |  | `prefers-contrast: more` |
| `forcedColors` | `boolean` |  | `forced-colors: active` — Windows High Contrast and friends. |

### `ContrastCheck`

One checked pair.

```ts
interface ContrastCheck
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | `text.primary on node.fill` — human-readable, stable enough to assert on. |
| `kind` | `'text' \| 'selection' \| 'state' \| 'link' \| 'port' \| 'category'` |  | Broad bucket, so callers can enforce selectively. |
| `foreground` | `string` |  |  |
| `background` | `string` |  |  |
| `ratio?` | `number` |  | Undefined when a colour could not be parsed (system colour, gradient, …). |
| `required` | `number` |  | The WCAG minimum this pair is held to. |
| `passes` | `boolean` |  | `false` only when we could measure it AND it fell short. |
| `exempt?` | `boolean` |  | WCAG lets disabled/inactive controls off; reported, never enforced. |

### `ContrastReport`

```ts
interface ContrastReport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `string` |  |  |
| `checks` | `ContrastCheck[]` |  |  |
| `failures` | `ContrastCheck[]` |  | Non-exempt checks that failed. |
| `passes` | `boolean` |  | True when nothing enforceable failed. |

### `DeriveThemeOptions`

```ts
interface DeriveThemeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `Theme` |  | The theme to derive FROM (normally a hand-tuned light theme). |
| `mode` | `'dark' \| 'high-contrast'` |  | What to build: 'dark' — the dark counterpart (flip the surfaces, keep the hues) 'high-contrast' — same colour scheme, pushed to AAA text / strong strokes |
| `name?` | `string` |  | Name of the result. Defaults to `"<from> (Dark)"` / `"<from> (High Contrast)"`. |
| `textLevel?` | `number` |  | Text level the result is repaired to. Default AA; the HC themes use AAA. |

### `Hsl`

HSL — the space the light↔dark flip has to happen in (see below).

```ts
interface Hsl
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `h` | `number` |  | 0-360 |
| `s` | `number` |  | 0-1 |
| `l` | `number` |  | 0-1 |

### `Rgb`

sRGB channels, 0-255.

```ts
interface Rgb
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `r` | `number` |  |  |
| `g` | `number` |  |  |
| `b` | `number` |  |  |

### `StyleRule`

A single CSS rule in the shared stylesheet.

```ts
interface StyleRule
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selector` | `string` |  | Selector WITHOUT the instance scope (added by {@link generateBaseStyleSheet}). |
| `decls` | `Record<string, string>` |  | Declarations, in CSS property form (`stroke-width`, not `strokeWidth`). |

### `ThemeRef`

A reference to a theme token, usable anywhere a literal style value is. Opaque on purpose: build it with {@link themeRef}, read it with
{@link resolveThemeRef}.

```ts
interface ThemeRef
```

**Members**

- `readonly [THEME_REF_MARKER]: string`
- `readonly [THEME_REF_MARKER]: string`

### `ThemeSet`

The themes a renderer can switch BETWEEN. `light`/`dark` are required (they
are what `colorMode` selects); the high-contrast pair is optional and only
consulted when the user has actually asked for contrast.

```ts
interface ThemeSet
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `light` | `Theme` |  |  |
| `dark` | `Theme` |  |  |
| `highContrastLight?` | `Theme` |  |  |
| `highContrastDark?` | `Theme` |  |  |

### `ThemeVarBinding`

One token's binding: the custom property + how to read its value from a Theme.

```ts
interface ThemeVarBinding
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `cssVar` | `string` |  | CSS custom property name, e.g. `--grafloria-node-fill`. |
| `read` | `(theme: Theme) => string \| number` |  | Pull the raw value out of a Theme. |
| `unit?` | `'px'` |  | Appended when serializing a numeric value into CSS. |

<!-- source: grafloria-renderer-themes-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `CascadeLayer`

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

```ts
type CascadeLayer = (typeof CASCADE_ORDER)[number];
```

### `ColorMode`

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

The prop. `'system'` follows the OS and re-themes when it changes.

```ts
type ColorMode = 'light' | 'dark' | 'system';
```

### `NamedStyle`

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

A named style may carry node properties, link properties, or the ones they share.

```ts
type NamedStyle = Partial<NodeStyle> | Partial<LinkStyle>;
```

### `ThemeToken`

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

Every themed value the built-in stylesheet paints.

Naming: `<entity>[.<state>].<property>` — mirrors the CSS var it maps to, so
`node.selected.fill` ⇄ `--grafloria-node-selected-fill`.

```ts
type ThemeToken =

  | 'node.fill'
  | 'node.stroke'
  | 'node.strokeWidth'
  | 'node.selected.fill'
  | 'node.selected.stroke'
  | 'node.selected.strokeWidth'
  | 'node.highlighted.fill'
  | 'node.highlighted.stroke'
  | 'node.highlighted.strokeWidth'
  | 'node.hovered.fill'
  | 'node.hovered.stroke'
  | 'node.disabled.fill'
  | 'node.disabled.stroke'
  | 'node.disabled.opacity'
  | 'node.error.fill'
  | 'node.error.stroke'

  | 'link.stroke'
  | 'link.strokeWidth'
  | 'link.selected.stroke'
  | 'link.selected.strokeWidth'
  | 'link.highlighted.stroke'
  | 'link.highlighted.strokeWidth'
  | 'link.hovered.stroke'

  | 'label.fontFamily'
  | 'label.fontSize'
  | 'label.color'

  | 'port.fill'
  | 'port.strokeWidth'
  | 'port.input'
  | 'port.output'
  | 'port.bi'
  | 'port.emphasis.strokeWidth'
  | 'port.emphasis.opacity';
```

### `TokenBridge`

A mapping from a Grafloria token to a CSS value in the HOST's vocabulary.

The key is a theme token (`'node.fill'`, `'category.critical'`) — the same
grammar `themeRef()` uses, so there is one token namespace to learn. A raw
`--grafloria-*` custom property name is accepted too, for the odd variable a caller
wants to set directly.

The value is CSS, verbatim: `var(--card)`, `hsl(var(--primary))`,
`oklch(var(--accent))`, or a plain `#hex`. It is NOT resolved by us — the
browser does it, which is exactly why a host token that changes (a theme
toggle in the host app!) also changes the diagram, live and for free.

```ts
type TokenBridge = Partial<Record<ThemeToken, string>> & Record<string, string>;
```

<!-- source: grafloria-renderer-types.md -->

# Types

Import these from `@grafloria/renderer`.

## On their own pages

- [Interfaces B–T](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-interfaces-b-t): 31 interfaces, `BooleanPropertyDefinition` to `TextMetrics`.
- [Interfaces T–V](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-interfaces-t-v): 6 interfaces, `TextStyle` to `VNode`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-types): 5 types.
- [`ColorPalette`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-colorpalette): Color palette for theme
- [`ExportOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-exportoptions): Export options.
- [`IRenderer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-irenderer): Renderer interface — the contract for a DIAGRAM renderer: it turns the model
- [`PropertyDefinition`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-propertydefinition): Definition of a single property in a property schema
- [`PropertySchema`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-propertyschema): Complete property schema for a node type
- [`PropertyValidation`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-propertyvalidation): Validation rules for property values
- [`SVGRendererConfig`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-svgrendererconfig): SVG Renderer Configuration
- [`VNodeProps`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-types-vnodeprops): VNode properties supporting SVG attributes, styles, and event handlers

<!-- source: grafloria-renderer-types-interfaces-b-t.md -->

# Interfaces B–T

Import these from `@grafloria/renderer`.

## Interfaces

### `BooleanPropertyDefinition`

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

Boolean property definition

```ts
interface BooleanPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'boolean'` |  | Editor type to use for this property |
| `defaultValue?` | `boolean` |  | Default value if property is not set |

**Example**

```typescript
const prop: BooleanPropertyDefinition = {
  key: 'enabled',
  label: 'Enabled',
  editor: 'boolean',
  defaultValue: true
};
```

### `BoundingBox`

Bounding box result.

```ts
interface BoundingBox
```

**Properties**

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

### `CanvasRendererConfig`

Canvas Renderer Configuration

```ts
interface CanvasRendererConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enableHitDetection?` | `boolean` |  | Enable hit detection canvas Default: true |
| `hitCanvasScale?` | `number` |  | Scale factor for hit detection canvas Higher values = more accurate but slower Default: 1.0 |

### `ColorPropertyDefinition`

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

Color picker property definition

```ts
interface ColorPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'color'` |  | Editor type to use for this property |
| `defaultValue?` | `string` |  | Default value if property is not set |

**Example**

```typescript
const prop: ColorPropertyDefinition = {
  key: 'backgroundColor',
  label: 'Background Color',
  editor: 'color',
  defaultValue: '#FFFFFF'
};
```

### `ComplexPropertyCondition`

Complex condition combining multiple simple conditions

```ts
interface ComplexPropertyCondition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `and?` | `PropertyCondition[]` |  | All conditions must be true (AND logic) |
| `or?` | `PropertyCondition[]` |  | At least one condition must be true (OR logic) |

**Example**

 AND condition
```typescript
const condition: ComplexPropertyCondition = {
  and: [
    { property: 'enabled', operator: '==', value: true },
    { property: 'nodeCount', operator: '>', value: 10 }
  ]
};
```

**Example**

 OR condition
```typescript
const condition: ComplexPropertyCondition = {
  or: [
    { property: 'type', operator: '==', value: 'table' },
    { property: 'type', operator: '==', value: 'view' }
  ]
};
```

### `DatePropertyDefinition`

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

Date picker property definition

```ts
interface DatePropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'date'` |  | Editor type to use for this property |
| `defaultValue?` | `string \| Date` |  | Default value if property is not set |
| `validation?` | `{ required?: boolean; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: DatePropertyDefinition = {
  key: 'birthDate',
  label: 'Birth Date',
  editor: 'date',
  validation: { required: true }
};
```

### `DateTimePropertyDefinition`

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

DateTime picker property definition

```ts
interface DateTimePropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'datetime'` |  | Editor type to use for this property |
| `defaultValue?` | `string \| Date` |  | Default value if property is not set |
| `validation?` | `{ required?: boolean; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: DateTimePropertyDefinition = {
  key: 'createdAt',
  label: 'Created At',
  editor: 'datetime',
  defaultValue: new Date().toISOString()
};
```

### `Effects`

Effects theme (shadows, border radius, opacity)

```ts
interface Effects
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shadow` | `{ none: string; sm: string; md: string; lg: string; }` |  | Shadow definitions (CSS box-shadow values) |
| `borderRadius` | `{ none: number; sm: number; md: number; lg: number; full: number; }` |  | Border radius values (in pixels) |
| `opacity` | `{ disabled: number; ghost: number; translucent: number; }` |  | Opacity values (0-1) |

### `FilePropertyDefinition`

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

File upload property definition

```ts
interface FilePropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'file'` |  | Editor type to use for this property |
| `accept?` | `string` |  |  |
| `multiple?` | `boolean` |  |  |

**Example**

```typescript
const prop: FilePropertyDefinition = {
  key: 'avatar',
  label: 'Avatar Image',
  editor: 'file',
  accept: 'image/*',
  multiple: false
};
```

### `HighlightConnectedOptions`

How `highlightConnected` draws the selected nodes' lines. Every field is optional.

```ts
interface HighlightConnectedOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `depth?` | `number` |  | How far the highlight follows the graph from the selected nodes. `1` (the default) marks only the lines that touch them; `2` also the lines one node further upstream and downstream; `Infinity` traces every path in and out. |
| `stroke?` | `string` |  | The colour of a highlighted line. Default: the theme's primary text colour. |
| `strokeWidth?` | `number` |  | The width of a highlighted line. Default 2.5 (a line is 2). |
| `outgoing?` | `'dashed' \| 'solid'` |  | How a line going OUT of the selection is drawn. Default `'solid'`, like the lines coming in; `'dashed'` adds a direction cue. (A line crossing a card is dashed either way.) |
| `dimOpacity?` | `number` |  | Opacity of every other line while a node is selected. Default 0.4 — faded, still legible; `1` leaves them alone. |

### `JsonPropertyDefinition`

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

JSON editor property definition

```ts
interface JsonPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'json'` |  | Editor type to use for this property |
| `defaultValue?` | `any` |  | Default value if property is not set |

**Example**

```typescript
const prop: JsonPropertyDefinition = {
  key: 'metadata',
  label: 'Metadata',
  editor: 'json',
  defaultValue: { version: '1.0' }
};
```

### `LinkStyleTheme`

Link style from theme

```ts
interface LinkStyleTheme
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `stroke` | `string` |  |  |
| `strokeWidth` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `opacity` | `number` |  |  |

### `MultiSelectPropertyDefinition`

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

Multi-select property definition with options

```ts
interface MultiSelectPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'multiselect'` |  | Editor type to use for this property |
| `options` | `SelectOption[]` |  |  |
| `validation?` | `{ required?: boolean; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: MultiSelectPropertyDefinition = {
  key: 'tags',
  label: 'Tags',
  editor: 'multiselect',
  options: [
    { value: 'important', label: 'Important' },
    { value: 'urgent', label: 'Urgent' },
    { value: 'review', label: 'Needs Review' }
  ]
};
```

### `NodeStyleTheme`

Node style from theme

```ts
interface NodeStyleTheme
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill` | `string` |  |  |
| `stroke` | `string` |  |  |
| `strokeWidth` | `number` |  |  |
| `borderRadius` | `number` |  |  |
| `shadow` | `boolean` |  |  |
| `opacity` | `number` |  |  |
| `selection?` | `'both' \| 'border' \| 'ring'` |  | How a selected node shows it — 'both' (default), 'border' or 'ring'. |

### `NumberPropertyDefinition`

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

Number property definition with number-specific validation

```ts
interface NumberPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'number'` |  | Editor type to use for this property |
| `validation?` | `{ required?: boolean; min?: number; max?: number; step?: number; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: NumberPropertyDefinition = {
  key: 'port',
  label: 'Port Number',
  editor: 'number',
  validation: {
    required: true,
    min: 1,
    max: 65535,
    step: 1
  }
};
```

### `NumberScale`

A named numeric scale (see {@link Theme.numbers}). Values are unitless — they
are consumed as SVG lengths (`stroke-width`), which accept plain numbers.

```ts
interface NumberScale
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `hairline?` | `number` |  |  |
| `regular?` | `number` |  |  |
| `emphasis?` | `number` |  |  |
| `heavy?` | `number` |  |  |

### `PerformanceMetrics`

Performance metrics returned by renderer

```ts
interface PerformanceMetrics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'svg' \| 'canvas'` |  | Renderer mode |
| `nodeCount` | `number` |  | Number of nodes rendered |
| `linkCount` | `number` |  | Number of links rendered |
| `renderTime` | `number` |  | Last render time in milliseconds |
| `fps` | `number` |  | Current frames per second |
| `memoryUsage` | `number` |  | Estimated memory usage in bytes |

### `PortThemeConfig`

Port theme configuration

```ts
interface PortThemeConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` |  |  |
| `strokeWidth` | `number` |  |  |
| `colors` | `{ input: string; output: string; bi: string; }` |  |  |

### `PropertyCondition`

Simple condition for property visibility

```ts
interface PropertyCondition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `property` | `string` |  | Key of the property to check |
| `operator` | `ConditionOperator` |  | Comparison operator |
| `value` | `any` |  | Value to compare against |

**Example**

 Equality condition
```typescript
const condition: PropertyCondition = {
  property: 'useCustomColor',
  operator: '==',
  value: true
};
```

**Example**

 Comparison condition
```typescript
const condition: PropertyCondition = {
  property: 'nodeCount',
  operator: '>',
  value: 100
};
```

**Example**

 Contains condition
```typescript
const condition: PropertyCondition = {
  property: 'tags',
  operator: 'contains',
  value: 'important'
};
```

### `PropertyDisplayOptions`

Display options for property editors

```ts
interface PropertyDisplayOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `string` |  | Variant of the editor (e.g., 'toggle' for boolean) |
| `rows?` | `number` |  | Number of rows for textarea/json editors |
| `autoResize?` | `boolean` |  | Auto-resize for textarea |
| `showLabels?` | `boolean` |  | Show labels on slider (min/max) |

### `PropertyGroup`

Property group for organizing related properties

Groups allow properties to be organized into collapsible sections
in the UI. Each group has a name (used for referencing in property
definitions) and a label (displayed to the user).

```ts
interface PropertyGroup
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Unique group identifier (used in PropertyDefinition.group) |
| `label` | `string` |  | Display label shown in UI |
| `description?` | `string` |  | Optional description or help text |
| `collapsed?` | `boolean` |  | Initial collapse state (default: false/expanded) |
| `order?` | `number` |  | Display order (groups with lower order appear first) |
| `icon?` | `string` |  | Optional icon identifier |

**Example**

 Basic group
```typescript
const group: PropertyGroup = {
  name: 'appearance',
  label: 'Appearance'
};
```

**Example**

 Group with all options
```typescript
const group: PropertyGroup = {
  name: 'advanced',
  label: 'Advanced Settings',
  description: 'Advanced configuration options',
  collapsed: true,
  order: 10,
  icon: 'settings'
};
```

### `Rectangle`

Rectangle defined by position and size
Used for viewport queries and rendering bounds

```ts
interface Rectangle
```

**Properties**

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

### `RendererCapabilities`

Renderer capability flags for runtime feature detection.

```ts
interface RendererCapabilities
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `supportsHitTest` | `boolean` |  | Can perform hit testing (element at coordinate) |
| `supportsBatching` | `boolean` |  | Can batch multiple render operations |
| `supportsExport` | `boolean` |  | Can export as image/SVG |
| `supportsMeasurement` | `boolean` |  | Can measure text/elements accurately |
| `supportsForeignObject` | `boolean` |  | Can render foreignObject (HTML inside SVG) |
| `supportsFilters` | `boolean` |  | Can apply filters/effects |
| `supportsOffscreen` | `boolean` |  | Can render to an offscreen buffer |

### `SelectOption`

Select option for dropdown editors

```ts
interface SelectOption
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` |  | The value of the option |
| `label` | `string` |  | Display label for the option |
| `disabled?` | `boolean` |  | Whether this option is disabled |

### `SelectPropertyDefinition`

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

Select (dropdown) property definition with options

```ts
interface SelectPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'select'` |  | Editor type to use for this property |
| `options` | `SelectOption[]` |  |  |
| `validation?` | `{ required?: boolean; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: SelectPropertyDefinition = {
  key: 'nodeType',
  label: 'Node Type',
  editor: 'select',
  options: [
    { value: 'table', label: 'Table' },
    { value: 'view', label: 'View' },
    { value: 'procedure', label: 'Stored Procedure', disabled: true }
  ],
  validation: { required: true }
};
```

### `SemanticPalette`

The host's semantic colour vocabulary (see {@link Theme.categories}). Open-ended: the built-in themes ship the names below, and callers add theirs.

```ts
interface SemanticPalette
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `critical?` | `string` |  | Blocking / fatal — the strongest attention colour. |
| `warning?` | `string` |  | Non-blocking problem. |
| `success?` | `string` |  | Healthy / passing. |
| `info?` | `string` |  | Neutral information. |
| `neutral?` | `string` |  | De-emphasised / inactive. |
| `accent?` | `string` |  | The host's brand accent. |

### `SliderPropertyDefinition`

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

Slider (range) property definition

```ts
interface SliderPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'slider'` |  | Editor type to use for this property |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step?` | `number` |  |  |
| `defaultValue?` | `number` |  | Default value if property is not set |

**Example**

```typescript
const prop: SliderPropertyDefinition = {
  key: 'opacity',
  label: 'Opacity',
  editor: 'slider',
  min: 0,
  max: 100,
  step: 1,
  defaultValue: 100
};
```

### `Spacing`

Spacing theme (in pixels)

```ts
interface Spacing
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `xs` | `number` |  |  |
| `sm` | `number` |  |  |
| `md` | `number` |  |  |
| `lg` | `number` |  |  |
| `xl` | `number` |  |  |

### `StringPropertyDefinition`

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

String property definition with string-specific validation

```ts
interface StringPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'string'` |  | Editor type to use for this property |
| `validation?` | `{ required?: boolean; minLength?: number; maxLength?: number; pattern?: string; // Regex pattern }` |  | Validation rules for this property |

**Example**

```typescript
const prop: StringPropertyDefinition = {
  key: 'tableName',
  label: 'Table Name',
  editor: 'string',
  validation: {
    required: true,
    minLength: 3,
    maxLength: 50,
    pattern: '^[a-zA-Z][a-zA-Z0-9_]*$'
  }
};
```

### `TextAreaPropertyDefinition`

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

Textarea (multi-line text) property definition

```ts
interface TextAreaPropertyDefinition extends PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `editor` | `'textarea'` |  | Editor type to use for this property |
| `validation?` | `{ required?: boolean; minLength?: number; maxLength?: number; }` |  | Validation rules for this property |

**Example**

```typescript
const prop: TextAreaPropertyDefinition = {
  key: 'description',
  label: 'Description',
  editor: 'textarea',
  validation: {
    maxLength: 500
  }
};
```

### `TextMetrics`

Text measurement result.

```ts
interface TextMetrics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `baseline` | `number` |  |  |

<!-- source: grafloria-renderer-types-interfaces-t-v.md -->

# Interfaces T–V

Import these from `@grafloria/renderer`.

## Interfaces

### `TextStyle`

Text styling for measurement.

```ts
interface TextStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fontFamily?` | `string` |  |  |
| `fontSize?` | `number` |  |  |
| `fontWeight?` | `string \| number` |  |  |
| `fontStyle?` | `string` |  |  |
| `letterSpacing?` | `number` |  |  |
| `lineHeight?` | `number` |  |  |

### `Theme`

Complete theme definition
Supports both CSS Variables (SVG+HTML) and Programmatic (Canvas)

```ts
interface Theme
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Theme name (e.g., "Light", "Dark", "High Contrast") |
| `version` | `string` |  | Theme version |
| `colors` | `ColorPalette` |  | Color palette |
| `typography` | `Typography` |  | Typography settings |
| `spacing` | `Spacing` |  | Spacing scale |
| `effects` | `Effects` |  | Visual effects (shadows, border radius, opacity) |
| `nodes` | `{ default: NodeStyleTheme; [nodeType: string]: Partial<NodeStyleTheme>; }` |  | Node type defaults - default: Base styles for all nodes - [nodeType]: Type-specific overrides |
| `links` | `{ default: LinkStyleTheme; [linkType: string]: Partial<LinkStyleTheme>; }` |  | Link type defaults - default: Base styles for all links - [linkType]: Type-specific overrides |
| `ports` | `PortThemeConfig` |  | Port configuration |
| `categories?` | `SemanticPalette` |  | SEMANTIC / CATEGORY PALETTE — the caller's OWN vocabulary of colours. |
| `numbers?` | `NumberScale` |  | NAMED NUMERIC SCALE — the numeric analogue of {@link categories}. |

### `Typography`

Typography theme

```ts
interface Typography
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fontFamily` | `{ default: string; mono: string; }` |  | Font families |
| `fontSize` | `{ xs: number; sm: number; md: number; lg: number; xl: number; }` |  | Font sizes (in pixels) |
| `fontWeight` | `{ normal: number; medium: number; bold: number; }` |  | Font weights |
| `lineHeight` | `{ tight: number; normal: number; relaxed: number; }` |  | Line heights |

### `ValidationError`

Validation error returned from validation functions

```ts
interface ValidationError
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `string` |  | Human-readable error message |
| `code?` | `string` |  | Optional error code for programmatic handling |

**Example**

```typescript
const error: ValidationError = {
  message: 'Value must be positive',
  code: 'POSITIVE_VALUE_REQUIRED'
};
```

### `ValidationResult`

Result of running validation on a property value

```ts
interface ValidationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `valid` | `boolean` |  | Whether the value is valid |
| `errors` | `ValidationError[]` |  | Array of validation errors (empty if valid) |

**Example**

```typescript
const result: ValidationResult = {
  valid: false,
  errors: [{ message: 'Required field is missing' }]
};
```

### `VNode`

Virtual Node - Abstract representation of visual element
Framework-agnostic, serializable, diffable

Supports both SVG and Canvas rendering modes, as well as HTML content
via foreignObject for embedding rich components.

```ts
interface VNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `VNodeType` |  | Element type: 'svg', 'g', 'rect', 'circle', 'path', 'text', 'foreignObject', etc. |
| `props` | `VNodeProps` |  | Element properties (attributes, styles, event handlers) |
| `children?` | `VNode[]` |  | Optional children VNodes (for hierarchical structures) |
| `key?` | `string` |  | Optional unique key for diffing optimization Used by renderers to efficiently update only changed nodes |

<!-- source: grafloria-renderer-types-types.md -->

# Types

Import these from `@grafloria/renderer`.

## Types

### `ConditionOperator`

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

Comparison operators for property conditions

```ts
type ConditionOperator =
  | '=='
  | '!='
  | '>'
  | '<'
  | '>='
  | '<='
  | 'contains'
  | 'in'
  | 'notIn'
  | 'matches';
```

**Example**

```typescript
// Equality check
const condition: PropertyCondition = {
  property: 'type',
  operator: '==',
  value: 'table'
};
```

### `ExportFormat`

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

Export format types.

It is no longer absent. It IS a true vector PDF — paths stay paths and text stays text,
so it is selectable and searchable — written directly from the VNode tree, with no
dependency; see `export/pdf/` for how, and for the honest list of what a base-14-font
PDF cannot do. The glyph pipeline was sidestepped by using the fonts every PDF reader
already has, rather than embedding one.)

Because `IRenderer.export` is string-typed, `'pdf'` comes back as a
`data:application/pdf;base64,…` URL. `SVGRenderer.exportPdf()` hands you the bytes and
the fidelity warnings instead.

```ts
type ExportFormat = 'png' | 'svg' | 'jpeg' | 'webp' | 'pdf';
```

### `LinkConnection`

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

A line's part in the selection's neighbourhood, as `highlightConnected` draws it:
`'in'` ends at a selected node (or upstream of one), `'out'` starts at one (or
downstream), `'both'` runs between two, `'dim'` is every other line. Emitted as
`data-connected` on the line's group.

```ts
type LinkConnection = 'in' | 'out' | 'both' | 'dim';
```

### `PropertyEditorType`

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

Base property editor type (imported from editor-types to avoid circular dependency)

```ts
type PropertyEditorType =
  | 'string'
  | 'number'
  | 'boolean'
  | 'select'
  | 'multiselect'
  | 'color'
  | 'textarea'
  | 'json'
  | 'date'
  | 'datetime'
  | 'slider'
  | 'file';
```

### `VNodeType`

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

VNode element type

Discriminated union of all supported SVG and HTML element types. Using a union type enables better TypeScript type checking and autocomplete.

```ts
type VNodeType =
  | 'rect'
  | 'circle'
  | 'ellipse'
  | 'line'
  | 'polyline'
  | 'polygon'
  | 'path'
  | 'text'
  | 'g'
  | 'svg'
  | 'foreignObject'
  | 'div'
  | 'span'
  | string;
```

<!-- source: grafloria-renderer-types-colorpalette.md -->

# ColorPalette

Import it from `@grafloria/renderer`.

Color palette for theme

```ts
interface ColorPalette
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background` | `{ /** Main diagram background */ default: string; /** Node/surface background */ surface: string; /** Elevated surface (modals, popovers) */ elevated: string; }` |  | Background colors |
| `text` | `{ /** Primary text */ primary: string; /** Secondary/muted text */ secondary: string; /** Disabled text */ disabled: string; /** Inverse text (for dark backgrounds) */ inverse: string; }` |  | Text colors |
| `node` | `{ default: { fill: string; stroke: string; }; selected: { fill: string; stroke: string; }; /** Attention emphasis (independent of selection); selected wins when both. */ highlighted: { fill: string; stroke: string; }; hovered: { fill: string; stroke: string; }; disabled: { fill: string; stroke: string; }; error: { fill: string; stroke: string; }; }` |  | State-based node colors |
| `link` | `{ default: string; selected: string; /** Attention emphasis (independent of selection). */ highlighted: string; hovered: string; disabled: string; }` |  | State-based link colors |
| `port` | `{ input: string; output: string; bi: string; }` |  | Port colors by type |
| `primary` | `string` |  | Semantic colors |
| `secondary` | `string` |  |  |
| `success` | `string` |  |  |
| `warning` | `string` |  |  |
| `error` | `string` |  |  |
| `info` | `string` |  |  |

<!-- source: grafloria-renderer-types-exportoptions.md -->

# ExportOptions

Import it from `@grafloria/renderer`.

Export options.

The first three are the original contract. The rest were added when the seam
was actually implemented (`export/`), and every one of them is optional — the
zero-argument call `renderer.export()` produces a standalone, styles-inlined
SVG of the whole diagram.

```ts
interface ExportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `scale?` | `number` |  | Image scale (default: 1) |
| `quality?` | `number` |  | JPEG/WebP quality 0-1 (default: 0.92) |
| `backgroundColor?` | `string` |  | Background color (default: transparent) |
| `viewport?` | `Rectangle` |  | World-space rectangle to export. Default: the diagram's content bounds — i.e. the whole diagram, not whatever the user happens to be looking at. |
| `padding?` | `number` |  | Margin (world units) around the content bounds. Default 20. Ignored with an explicit `viewport`. |
| `foreignObject?` | `ForeignObjectMode` |  | How to serialize `<foreignObject>` (HTML-in-SVG) nodes. Default `'serialize'`. |
| `captureForeignObject?` | `(vnode: VNode) => string \| undefined` |  | Supply the live HTML mounted inside a foreignObject. The VNode tree does not contain it (the patcher treats those subtrees as opaque), so a headless exporter cannot know it — a browser-side caller can hand it back here. |
| `customNodes?` | `readonly CustomNodeCapture[]` |  | CUSTOM-NODE (HTML-layer) CONTENT to place into the export. |
| `htmlFallback?` | `HtmlFallbackMode` |  | How to export a custom node that could only be captured as HTML. Default `'foreignObject'`. |
| `customNodeTimeout?` | `number` |  | THE BOUND on waiting for an ASYNC custom-node painter, in milliseconds. Default 5000. |
| `assetFetcher?` | `AssetFetcher` |  | TIER 2 for EXTERNAL image URLs (`<img src="https://…">` inside a widget, a panel node's logo). `await export(…)` — every format — first tries the environment's own fetch, which succeeds for same-origin assets and for any server that allows CORS; when that is refused, THIS fetcher is consulted (route the URL through your own proxy, a service worker, an app cache); when both fail the reference is … |
| `resolvedAssets?` | `ReadonlyMap<string, string>` |  | PRE-RESOLVED external assets: URL → `data:` URI. Every `<image href>` in the export — the renderer's own tree (a panel node's image/icon) and widget captures alike — whose URL appears here is substituted with the supplied bytes, by a PURE, synchronous pass (`inlineAssets` in `export/assets.ts`). No network is touched. |
| `assetTimeout?` | `number` |  | Bound on fetching ONE external image, per tier, in milliseconds. Default 5000 — the same figure as {@link customNodeTimeout}, for the same reason: a dead URL must not hang a print job. On expiry the image degrades to the tier-3 warning. |
| `assetMaxBytes?` | `number` |  | Cap on one fetched image's size, in bytes. Default 5MB — a data: URI is ~33% bigger than the file it carries. Over the cap the image is refused with a warning; the cap is terminal (a proxy would return the same bytes, so tier 2 is not asked). |
| `onWarnings?` | `(warnings: string[]) => void` |  | FIDELITY REPORT. `IRenderer.export()` returns a bare string, so it has nowhere to put the caveats an export hit — and for years it simply threw them away, which is how a blank widget reaches a customer with no diagnostic anywhere. |
| `embedFontCss?` | `string` |  | CSS injected verbatim into the exported SVG's `<defs>`. The font seam: an `@font-face` with a `data:` URI `src` makes the file carry its own glyphs. We declare font families; we do not embed or subset fonts for you. |
| `rasterBackend?` | `RasterBackend` |  | Rasterizer for `png` / `jpeg` / `webp`. Defaults to a canvas-based backend when one exists (browser main thread or worker via OffscreenCanvas). In plain Node there is no SVG engine, so raster export THROWS unless you pass one (resvg-js / sharp / puppeteer). SVG export never needs this. |
| `scope?` | `ExportScope` |  | WHAT to export. |
| `includeIds?` | `Iterable<string>` |  | Export only these node/link ids. The tree is PRUNED to them, so an un-selected node's markup (and its labels) is not merely cropped out of view — it is not in the file. Overridden by `scope: 'selection'`, which reads the live selection. |
| `maxSize?` | `number` |  | Cap on the exported image's size per side, in px. Default 4000. |
| `minSize?` | `number` |  | Floor on the exported image's size per side, in px. Default 1. |
| `xmlDeclaration?` | `boolean` |  | Prepend the `<?xml …?>` prolog to an SVG export. Default false. |
| `embedModel?` | `boolean` |  | Carry the source model INSIDE the exported artifact, so it can be re-imported and edited losslessly (`importDiagram`). An SVG gets it in `<metadata>`; a PNG gets an `iTXt` chunk. |
| `embedModelCreatedAt?` | `string` |  | The embedded envelope's `createdAt`. Supply it to keep an `embedModel` export DETERMINISTIC — otherwise the envelope is stamped with the wall clock and two exports of the same diagram differ in their bytes. |
| `pdf?` | `PdfExportOptions` |  | Page size, orientation, margins and document metadata for `export('pdf')`. |
| `embedFonts?` | `FontSource[]` |  | Fonts to EMBED, as `@font-face` rules with base64 `data:` URIs — so the file renders in the right typeface on a machine that has never heard of it. |

<!-- source: grafloria-renderer-types-irenderer.md -->

# IRenderer

Import it from `@grafloria/renderer`.

Renderer interface — the contract for a DIAGRAM renderer: it turns the model
plus a viewport into a visual representation (a VNode tree in SVG mode).

This is the only renderer interface. A second `IRenderer` used to live in
`core/renderer.interface.ts` describing a different layer — a VNode → DOM
*consumer* (initialize/render/clear/destroy against a container) — together
with an unused stack (SVGRendererV2, a throwing Canvas stub, HybridRenderer,
RendererFactory, RendererStrategyManager). Nothing in production implemented
it: the real VNode → DOM layer is the patcher in `vnode/patch.ts`. The stack
is deleted; the useful vocabulary it defined is kept below, as OPTIONAL
members here, so capability detection / export / hit-testing / text
measurement have a home when a renderer actually implements them.

```ts
interface IRenderer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'svg' \| 'canvas'` |  | Renderer mode |
| `capabilities?` | `RendererCapabilities` |  | Optional: capability flags for runtime feature detection, so callers can ask instead of assuming (e.g. "can this renderer do foreignObject?"). |

**Members**

- `render(viewport: Rectangle, zoom: number): VNode | void` — Render diagram to visual representation
- `getPerformanceMetrics(): PerformanceMetrics` — Get performance metrics
- `dispose(): void` — Dispose renderer and clean up resources
- `hitTest?(x: number, y: number): VNode | null` — Optional: element at a coordinate (selection, hover, click routing).
- `measureText?(text: string, style: TextStyle): TextMetrics` — Optional: measure text for layout (wrapping, ellipsis, shape-fit). Implementations are expected to cache.
- `export?(format: ExportFormat, options?: ExportOptions): Promise<string>` — Optional: export the rendered diagram as an image or SVG string.

`'svg'` returns a STANDALONE, styles-inlined SVG document (no `var(--…)`, no
external references) — pure, deterministic and DOM-free, so it runs on a
server. The raster formats return a `data:` URL and need a rasterizer (see
{@link ExportOptions.rasterBackend}).

Implemented by `SVGRenderer` (see `export/`).

<!-- source: grafloria-renderer-types-propertydefinition.md -->

# PropertyDefinition

Import it from `@grafloria/renderer`.

Definition of a single property in a property schema

This is the core interface that defines how a property should be
edited in the UI. Each property definition specifies:
- What property key it maps to in the NodeModel
- How it should be displayed (label, description)
- What editor component to use
- Validation rules
- Conditional visibility
- Grouping and ordering

```ts
interface PropertyDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `key` | `string` |  | Property key in NodeModel (must match the property name) |
| `label` | `string` |  | Display label shown in UI |
| `editor` | `PropertyEditorType` |  | Editor type to use for this property |
| `defaultValue?` | `any` |  | Default value if property is not set |
| `description?` | `string` |  | Help text or tooltip description |
| `validation?` | `PropertyValidation` |  | Validation rules for this property |
| `condition?` | `PropertyCondition` |  | Conditional visibility based on other property values |
| `group?` | `string` |  | Group name for organizing properties (optional) |
| `order?` | `number` |  | Display order within group (default: definition order) |
| `display?` | `PropertyDisplayOptions` |  | Display options and hints for the editor |

**Example**

 Basic string property
```typescript
const prop: PropertyDefinition = {
  key: 'name',
  label: 'Name',
  editor: 'string',
  validation: { required: true, minLength: 3 }
};
```

**Example**

 Number property with validation
```typescript
const prop: PropertyDefinition = {
  key: 'port',
  label: 'Port',
  editor: 'number',
  validation: { min: 1, max: 65535 },
  defaultValue: 8080
};
```

**Example**

 Conditional property
```typescript
const prop: PropertyDefinition = {
  key: 'customColor',
  label: 'Custom Color',
  editor: 'color',
  condition: { property: 'useCustomColor', operator: '==', value: true }
};
```

<!-- source: grafloria-renderer-types-propertyschema.md -->

# PropertySchema

Import it from `@grafloria/renderer`.

Complete property schema for a node type

A property schema defines how all properties of a node type should
be edited in the UI. It includes:
- Property definitions (what to edit and how)
- Optional groups (for organization)
- Optional metadata (versioning, documentation)

```ts
interface PropertySchema
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `properties` | `PropertyDefinition[]` |  | List of property definitions |
| `groups?` | `PropertyGroup[]` |  | Optional property groups for organization |
| `metadata?` | `{ /** * Schema version (e.g., '1.0.0') */ version?: string; /** * Schema author or creator */ author?: string; /** * Description of what this schema is for */ description?: string; }` |  | Schema metadata |

**Example**

 Simple schema
```typescript
const schema: PropertySchema = {
  properties: [
    {
      key: 'name',
      label: 'Name',
      editor: 'string',
      validation: { required: true }
    },
    {
      key: 'enabled',
      label: 'Enabled',
      editor: 'boolean'
    }
  ]
};
```

**Example**

 Complete schema with groups
```typescript
const schema: PropertySchema = {
  properties: [
    {
      key: 'tableName',
      label: 'Table Name',
      editor: 'string',
      validation: { required: true },
      group: 'basic'
    },
    {
      key: 'columns',
      label: 'Columns',
      editor: 'json',
      group: 'schema'
    },
    {
      key: 'primaryKey',
      label: 'Primary Key',
      editor: 'select',
      options: [],
      group: 'schema'
    }
  ],
  groups: [
    { name: 'basic', label: 'Basic Information', order: 1 },
    { name: 'schema', label: 'Schema Definition', order: 2 }
  ],
  metadata: {
    version: '1.0.0',
    author: 'System',
    description: 'Property schema for database tables'
  }
};
```

<!-- source: grafloria-renderer-types-propertyvalidation.md -->

# PropertyValidation

Import it from `@grafloria/renderer`.

Validation rules for property values

```ts
interface PropertyValidation
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `required?` | `boolean` |  | Whether the property is required |
| `minLength?` | `number` |  | Minimum string length (for string properties) |
| `maxLength?` | `number` |  | Maximum string length (for string properties) |
| `pattern?` | `string` |  | Regular expression pattern (for string properties) |
| `min?` | `number` |  | Minimum value (for number properties) |
| `max?` | `number` |  | Maximum value (for number properties) |
| `step?` | `number` |  | Step increment (for number properties) |
| `integer?` | `boolean` |  | Whether the number must be an integer (for number properties) |
| `enum?` | `any[]` |  | Allowed values (for select/multiselect properties) |
| `options?` | `SelectOption[]` |  | Options for select/multiselect (alternative to enum with more control) |
| `jsonSchema?` | `any` |  | JSON Schema for validating JSON properties |
| `placeholder?` | `string` |  | Placeholder text for input fields |
| `prefix?` | `string` |  | Prefix text to display before input (e.g., "$" for currency) |
| `suffix?` | `string` |  | Suffix text to display after input (e.g., "px" for pixels) |
| `presets?` | `string[]` |  | Preset color values for color picker |
| `accept?` | `string` |  | Accepted file types (for file uploads) |
| `multiple?` | `boolean` |  | Allow multiple file selection |
| `maxSize?` | `number` |  | Maximum file size in bytes |
| `custom?` | `(value: any, allValues: Record<string, any>) => ValidationError \| null` |  | Custom validation function |

**Example**

 String validation
```typescript
const validation: PropertyValidation = {
  required: true,
  minLength: 3,
  maxLength: 50,
  pattern: '^[a-zA-Z]+$'
};
```

**Example**

 Number validation
```typescript
const validation: PropertyValidation = {
  required: true,
  min: 0,
  max: 100,
  step: 5
};
```

**Example**

 Custom validation
```typescript
const validation: PropertyValidation = {
  custom: (value, allValues) => {
    if (value < allValues.minValue) {
      return { message: 'Must be greater than minimum' };
    }
    return null;
  }
};
```

<!-- source: grafloria-renderer-types-svgrendererconfig.md -->

# SVGRendererConfig

Import it from `@grafloria/renderer`.

SVG Renderer Configuration

```ts
interface SVGRendererConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagramType?` | `string` |  | The diagram's KIND, used for `aria-roledescription` on the SVG root ("Flowchart diagram", "Sequence diagram"). Purely semantic: it changes what a screen reader calls the canvas, nothing about how it is drawn. Default: undefined → "Diagram". |
| `diagramLabel?` | `string` |  | A human title for this diagram, used as the head of the SVG root's accessible name ("Order flow, 12 nodes, 14 edges"). Default: undefined → "Diagram". |
| `enableCaching?` | `boolean` |  | Enable VNode caching for performance Default: true |
| `maxCacheSize?` | `number` |  | Maximum number of VNodes to cache Default: 1000 |
| `useCSSMode?` | `boolean` |  | Use CSS classes and variables for styling - true: Best for SVG+HTML with foreignObject (default) - false: Programmatic styles (Canvas-compatible) Default: true |
| `linkHitAreaWidth?` | `number` |  | Width (px) of the invisible hit-area stroke rendered under every link so thin lines are easy to click/hover. 0 disables it. Default: 12 |
| `smartConnectionPoints?` | `boolean` |  | Re-pick each link's connection sides dynamically from the nodes' relative positions (draw.io-style floating connections). Visible ports are the contract: when the node shows ports on the chosen side (visibility 'always' via the port → node → global chain) the link snaps to the closest one; with ports hidden the attachment floats along the shape's real outline … |
| `connectionPoint?` | `string` |  | . The diagram-wide CONNECTION-POINT STRATEGY, by registered name (`registerConnectionPoint`). Built-ins: `'port'` (the default — attach at the assigned port), `'smart'` (draw.io-style floating attachment) and `'boundary'` (attach on each node's outline, aimed at the other node). |
| `instanceId?` | `string` |  | Force this renderer's instance scope (`data-grafloria-instance`, and the id of its `<style>` block) instead of taking the next value from the per-process counter. |
| `parallelLinks?` | `boolean` |  | . Fan out PARALLEL links: two or more links between the same pair of nodes are pushed onto separate lanes instead of being drawn on top of one another. Self-loops (source node === target node) are always routed as loops regardless of this flag — a self-loop has no sensible un-looped rendering. |
| `parallelSpacing?` | `number` |  | Distance between adjacent lanes of a parallel bundle, in px. Per-link override: `LinkStyle.parallel.spacing`. Default: 16 |
| `channelNudging?` | `boolean` |  | . Channel nudging: orthogonal segments of DIFFERENT links that share a corridor (closer than ~4px — i.e. visually on top of each other) are separated onto parallel lanes, spaced by `parallelSpacing`, with lane ORDER chosen by each member's exit side so corridor-mates stop crossing at the corridor mouth. |
| `jumpOwnership?` | `'both' \| 'single'` |  | . Who draws the arc when two jump-drawing links cross: 'both' (legacy double bridge, default) or 'single' — exactly one deterministic owner per intersection (horizontal arcs over vertical; ties break on link id). See EdgeOptimizerOptions.jumpOwnership. |
| `globalRouting?` | `boolean` |  | . Route every edge against ONE shared penalty field instead of one at a time, so an edge pays for crossing another edge or crowding a corridor at ROUTING time and picks a different channel by itself — rather than being routed into a pile-up and then patched afterwards by fan-out, nudging and jump-overs. |
| `qualityGovernor?` | `boolean \| GovernorOptions` |  | . The ADAPTIVE QUALITY GOVERNOR. |
| `routeSolverPort?` | `SolverPort` |  | The port the global route solver runs on — a real `Worker`, typically `new Worker(new URL('...', import.meta.url))` whose body is `serveSolver(self)`. Omit and the solver runs INLINE on this thread: same protocol, same code, same answers, no parallelism. |
| `routeSolverOptions?` | `SolverOptions` |  | Penalty weights and pass count for the global solver. See SolverOptions. |
| `onRoutesRefined?` | `() => void` |  | Called when the global solver has produced routes better than the ones on screen. The host should schedule a re-render; the renderer cannot do it itself, because it does not own the frame loop. |
| `edgeOptimizer?` | `boolean` |  | . Run the diagram-wide edge optimizer: ONE incremental pass that computes jump-overs for every link and auto-places the labels that opted in via `LinkLabel.autoOffset`. |
| `colorMode?` | `ColorMode` |  | Styling & theming — Card "colorMode". |
| `themes?` | `ThemeSet` |  | The themes `colorMode` switches between. Defaults to the built-in LIGHT/DARK/HIGH_CONTRAST set. Only consulted when `colorMode` is set. |
| `tokenBridge?` | `TokenBridge` |  | Styling & theming — Card "design-token bridge". |
| `highlightConnected?` | `boolean \| HighlightConnectedOptions` |  | Select a node and its lines come forward: the lines coming INTO it and going OUT of it are drawn in the page's ink, and every other line fades back — the flow-editor look (Google's Opal draws a workflow this way). |

<!-- source: grafloria-renderer-types-vnodeprops.md -->

# VNodeProps

Import it from `@grafloria/renderer`.

VNode properties supporting SVG attributes, styles, and event handlers

```ts
interface VNodeProps
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x?` | `number` |  | X coordinate |
| `y?` | `number` |  | Y coordinate |
| `width?` | `number` |  | Width |
| `height?` | `number` |  | Height |
| `rx?` | `number` |  | Border radius X (rounded corners) |
| `ry?` | `number` |  | Border radius Y (rounded corners) |
| `cx?` | `number` |  | Circle center X |
| `cy?` | `number` |  | Circle center Y |
| `r?` | `number` |  | Circle radius |
| `x1?` | `number` |  | Line start X |
| `y1?` | `number` |  | Line start Y |
| `x2?` | `number` |  | Line end X |
| `y2?` | `number` |  | Line end Y |
| `d?` | `string` |  | SVG path data (d attribute) |
| `fill?` | `string` |  | Fill color |
| `stroke?` | `string` |  | Stroke color |
| `strokeWidth?` | `number` |  | Stroke width |
| `strokeDasharray?` | `string` |  | Stroke dash array (dashed lines) |
| `opacity?` | `number` |  | Opacity (0-1) |
| `transform?` | `string` |  | SVG transform attribute |
| `textContent?` | `string` |  | Text content |
| `fontSize?` | `number` |  | Font size (in pixels) |
| `fontFamily?` | `string` |  | Font family |
| `textAnchor?` | `'start' \| 'middle' \| 'end'` |  | Text anchor (alignment) |
| `className?` | `string` |  | CSS class names (space-separated) |
| `containerId?` | `string` |  | Container ID for foreignObject elements Used by ComponentRenderer to target the specific foreignObject for Angular component injection |
| `requiredExtensions?` | `string` |  | SVG foreignObject requiredExtensions attribute Specifies SVG extensions required for rendering |
| `xmlns?` | `string` |  | XML namespace (typically for XHTML in foreignObject) Example: 'http://www.w3.org/1999/xhtml' |
| `style?` | `Record<string, any> \| string` |  | Inline style: either a declaration map, or a raw CSS string. |
| `onClick?` | `(e: Event) => void` |  | Click event handler |
| `onMouseEnter?` | `(e: Event) => void` |  | Mouse enter event handler |
| `onMouseLeave?` | `(e: Event) => void` |  | Mouse leave event handler |
| `onMouseDown?` | `(e: Event) => void` |  | Mouse down event handler |

<!-- source: grafloria-renderer-utils.md -->

# Utils

Import these from `@grafloria/renderer`.

## Functions

### `applyNodePreset`

Apply a preset to a node

```ts
function applyNodePreset(node: NodeModel, preset: typeof AnimationPresets.NODE[keyof typeof AnimationPresets.NODE]): NodeModel
```

**Parameters**

- `node`: Node to apply preset to
- `preset`: Preset configuration

**Returns** Modified node (mutation)

### `applyWorkflowPreset`

Apply a workflow preset to a node

```ts
function applyWorkflowPreset(
  node: NodeModel,
  preset: typeof AnimationPresets.WORKFLOW[keyof typeof AnimationPresets.WORKFLOW]
): NodeModel
```

**Parameters**

- `node`: Node to apply preset to
- `preset`: Workflow preset configuration

**Returns** Modified node (mutation)

### `buildAnimationClass`

Build animation class string from individual parts

```ts
function buildAnimationClass(...parts: (string | undefined | null | false)[]): string
```

**Parameters**

- `parts`: Array of class name parts (filters out empty/undefined)

**Returns** Space-separated class string

### `calculateAnimationDuration`

Calculate animation duration based on speed setting

```ts
function calculateAnimationDuration(
  baseSpeed: 'slow' | 'normal' | 'fast' | undefined,
  baseDuration: number = 1
): number
```

**Parameters**

- `baseSpeed`: Base animation speed ('slow' | 'normal' | 'fast')
- `baseDuration`: Base duration in seconds (default: 1)

**Returns** Duration in seconds

### `cancelAnimFrame`

Cancel animation frame wrapper with fallback

```ts
function cancelAnimFrame(id: number): void
```

**Parameters**

- `id`: Request ID to cancel

### `canCoexist`

Check if two animations can coexist
Some animations can run simultaneously (e.g., border + status)

```ts
function canCoexist(a: AnimationDescriptor, b: AnimationDescriptor): boolean
```

### `createAnimationCustomProperties`

Create CSS custom properties object for animation

```ts
function createAnimationCustomProperties(options: {
  duration?: number;
  strokeWidth?: number;
  color?: string;
  glowColor?: string;
}): Record<string, string>
```

**Parameters**

- `options`: Animation options

**Returns** Object with CSS custom properties

### `createLinkAnimation`

Create link animation configuration

```ts
function createLinkAnimation(
  type: 'marching-ants' | 'flow' | 'pulse' | 'none',
  options: {
    speed?: 'slow' | 'normal' | 'fast';
    direction?: 'forward' | 'reverse';
    duration?: number;
  } = {}
): LinkAnimation
```

**Parameters**

- `type`: Animation type
- `options`: Additional options

**Returns** LinkAnimation object

### `createPriorityResolver`

Create a priority resolver with default configuration

```ts
function createPriorityResolver(
  config?: Partial<PriorityResolverConfig>
): AnimationPriorityResolver
```

### `debounce`

Debounce function for performance optimization
Useful for animation updates during resize/scroll

```ts
function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void
```

**Parameters**

- `func`: Function to debounce
- `wait`: Wait time in milliseconds

**Returns** Debounced function

### `generateGradientBorderCSS`

Generate dynamic CSS for gradient border animation

```ts
function generateGradientBorderCSS(colors: string[], duration: number = 3): string
```

**Parameters**

- `colors`: Array of gradient colors
- `duration`: Animation duration in seconds

**Returns** CSS string for gradient animation

### `getCoexistingAnimations`

Get all animations that can coexist together
Returns a set of compatible animations

```ts
function getCoexistingAnimations(
  animations: AnimationDescriptor[]
): AnimationDescriptor[]
```

### `getDefaultPriority`

Get default priority for an animation descriptor

```ts
function getDefaultPriority(descriptor: AnimationDescriptor): number
```

### `getLinkAnimationFromPreset`

Get link animation from a preset

```ts
function getLinkAnimationFromPreset(
  preset: typeof AnimationPresets.WORKFLOW[keyof typeof AnimationPresets.WORKFLOW] |
          typeof AnimationPresets.ETL[keyof typeof AnimationPresets.ETL]
): LinkAnimation
```

**Parameters**

- `preset`: Preset with link configuration

**Returns** Link animation configuration

### `getOptimalAnimationSettings`

Get optimal animation settings based on browser performance

```ts
function getOptimalAnimationSettings(): {
  maxAnimatedEdges: number;
  maxAnimatedNodes: number;
  preferredAnimationType: 'simple' | 'complex';
}
```

**Returns** Recommended animation settings

### `isValidAnimationType`

Validate animation type

```ts
function isValidAnimationType(
  type: any
): type is 'marching-ants' | 'flow' | 'pulse' | 'none'
```

**Parameters**

- `type`: Animation type to validate

**Returns** Whether the type is valid

### `isValidBorderAnimationType`

Validate border animation type

```ts
function isValidBorderAnimationType(
  type: any
): type is 'gradient' | 'pulse' | 'breathe' | 'shimmer' | 'none'
```

**Parameters**

- `type`: Border animation type to validate

**Returns** Whether the type is valid

### `isValidStatus`

Validate status type

```ts
function isValidStatus(
  status: any
): status is 'idle' | 'pending' | 'running' | 'completed' | 'error' | 'warning'
```

**Parameters**

- `status`: Status to validate

**Returns** Whether the status is valid

### `measureAnimationFPS`

Measure animation FPS (for debugging/performance monitoring)

```ts
function measureAnimationFPS(duration: number = 1000): Promise<number>
```

**Parameters**

- `duration`: Duration to measure in milliseconds

**Returns** Promise that resolves to average FPS

### `msToSeconds`

Convert animation duration from milliseconds to seconds

```ts
function msToSeconds(milliseconds: number): number
```

**Parameters**

- `milliseconds`: Duration in milliseconds

**Returns** Duration in seconds

### `prefersReducedMotion`

Check if user prefers reduced motion

```ts
function prefersReducedMotion(): boolean
```

**Returns** Whether user prefers reduced motion

### `requestAnimFrame`

Request animation frame wrapper with fallback

```ts
function requestAnimFrame(callback: () => void): number
```

**Parameters**

- `callback`: Function to call on next frame

**Returns** Request ID

### `resolveAnimationConflict`

Resolve conflict between multiple animations
Returns the animation with the highest priority

```ts
function resolveAnimationConflict(
  animations: AnimationDescriptor[]
): AnimationDescriptor | null
```

### `resolveEdgeAnimationConflict`

Resolve conflict between multiple edge animations
Returns the animation that should be displayed

```ts
function resolveEdgeAnimationConflict(
  animations: AnimationDescriptor[]
): AnimationDescriptor | null
```

### `resolveNodeAnimationConflict`

Resolve conflict between multiple node animations
Returns the animation that should be displayed

```ts
function resolveNodeAnimationConflict(
  animations: AnimationDescriptor[]
): AnimationDescriptor | null
```

### `secondsToMs`

Convert animation duration from seconds to milliseconds

```ts
function secondsToMs(seconds: number): number
```

**Parameters**

- `seconds`: Duration in seconds

**Returns** Duration in milliseconds

### `shouldSimplifyAnimations`

Check if animation should be simplified for performance

```ts
function shouldSimplifyAnimations(
  animationCount: number,
  performanceThreshold: number = 50
): boolean
```

**Parameters**

- `animationCount`: Number of currently animating elements
- `performanceThreshold`: Threshold for simplification (default: 50)

**Returns** Whether to simplify animations

### `supportsAnimations`

Check if browser supports CSS animations

```ts
function supportsAnimations(): boolean
```

**Returns** Whether CSS animations are supported

### `throttle`

Throttle function for performance optimization
Useful for animation updates during continuous events

```ts
function throttle<T extends (...args: any[]) => any>(
  func: T,
  limit: number
): (...args: Parameters<T>) => void
```

**Parameters**

- `func`: Function to throttle
- `limit`: Time limit in milliseconds

**Returns** Throttled function

## Classes

### `AnimationPriorityResolver`

Animation priority resolver
Advanced resolver with configuration support

```ts
class AnimationPriorityResolver
```

**Methods**

- `constructor(config: Partial<PriorityResolverConfig> = {})`
- `resolve(animations: AnimationDescriptor[]): AnimationDescriptor[]` — Resolve animations based on configuration
- `updateConfig(config: Partial<PriorityResolverConfig>): void` — Update configuration
- `getConfig(): Readonly<PriorityResolverConfig>` — Get current configuration

## Constants

### `AnimationColorSchemes`

Common color schemes for animations

```ts
const AnimationColorSchemes: { readonly BLUE: readonly ["#3498db", "#2980b9"]; readonly GREEN: readonly ["#27ae60", "#229954"]; readonly RED: readonly ["#e74c3c", "#c0392b"]; readonly ORANGE: readonly ["#f39c12", "#e67e22"]; readonly PURPLE: readonly ["#9b59b6", "#8e44ad"]; readonly TEAL: readonly ["#1abc9c", "#16a085"]; readonly YELLOW: readonly ["#f1c40f", "#f39c12"]; readonly GRADIENT_COOL: readonly ["#667eea", "#764ba2"]; readonly GRADIENT_WARM: readonly ["#f093fb", "#f5576c"]; readonly GRADIENT_OCEAN: readonly ["#4facfe", "#00f2fe"]; readonly GRADIENT_SUNSET: readonly ["#fa709a", …
```

### `AnimationPresets`

Preset configurations for common workflow states

```ts
const AnimationPresets: { readonly WORKFLOW: { readonly RUNNING: { readonly node: { readonly status: "running"; readonly animateStatus: true; readonly style: { readonly animatedBorder: true; readonly borderAnimationType: "pulse"; readonly borderAnimationSpeed: 1.5; }; }; readonly link: LinkAnimation; }; readonly PROCESSING: { readonly node: { readonly status: "running"; readonly animateStatus: true; readonly style: { readonly animatedBorder: true; readonly borderAnimationType: "gradient"; readonly borderAnimationSpeed: 2; readonly borderAnimationColors: readonly ["#667eea", "#764ba2"]; }; }; …
```

### `AnimationSpeeds`

Common animation speed values

```ts
const AnimationSpeeds: { readonly VERY_SLOW: 0.5; readonly SLOW: 1; readonly NORMAL: 1.5; readonly FAST: 2; readonly VERY_FAST: 3; }
```

## Interfaces

### `AnimationDescriptor`

Animation descriptor for conflict resolution

```ts
interface AnimationDescriptor
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `AnimationType` |  |  |
| `priority?` | `number` |  |  |
| `borderType?` | `'gradient' \| 'pulse' \| 'breathe' \| 'shimmer'` |  |  |
| `status?` | `'idle' \| 'pending' \| 'running' \| 'completed' \| 'error' \| 'warning'` |  |  |
| `edgeType?` | `'marching-ants' \| 'flow' \| 'pulse' \| 'dash-flow'` |  |  |
| `customName?` | `string` |  |  |
| `metadata?` | `Record<string, any>` |  |  |

### `PriorityResolverConfig`

Priority resolver configuration

```ts
interface PriorityResolverConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowCoexistence` | `boolean` |  | Allow multiple animations to coexist |
| `priorityOverrides?` | `Record<string, number>` |  | Custom priority overrides |
| `strictMode?` | `boolean` |  | Strict mode: throw error on conflicts instead of resolving |

## Types

### `AnimationType`

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

Animation types for priority resolution

```ts
type AnimationType =
  | 'border'
  | 'status'
  | 'edge'
  | 'hover'
  | 'selected'
  | 'custom';
```

## Enums

### `AnimationPriority`

Animation priority levels (higher number = higher priority)

```ts
enum AnimationPriority
```

**Members**

- `BORDER_GRADIENT = 10`
- `BORDER_SHIMMER = 15`
- `BORDER_BREATHE = 20`
- `HOVER_STATE = 30`
- `SELECTED_STATE = 35`
- `BORDER_PULSE = 40`
- `EDGE_MARCHING_ANTS = 50`
- `EDGE_FLOW = 55`
- `EDGE_PULSE = 60`
- `EDGE_DASH_FLOW = 65`
- `STATUS_PENDING = 70`
- `STATUS_RUNNING = 75`
- `STATUS_WARNING = 80`
- `STATUS_COMPLETED = 85`
- `STATUS_ERROR = 90`
- `USER_INTERACTION = 95`
- `CUSTOM_ANIMATION = 100`

<!-- source: grafloria-renderer-vnode.md -->

# Vnode

Import these from `@grafloria/renderer`.

## Functions

### `camelToKebab`

camelCase → kebab-case (`strokeWidth` → `stroke-width`).

```ts
function camelToKebab(str: string): string
```

### `createDomElement`

Build a fresh detached DOM tree for `vnode` using the default patcher.

```ts
function createDomElement(vnode: VNode, namespace: string = SVG_NS): Element
```

### `createForeignObject`

Create a foreignObject VNode

Creates a VNode representing an SVG foreignObject element, which allows
embedding HTML content inside SVG. Automatically generates a container ID
if not provided, and includes a default XHTML div wrapper.

```ts
function createForeignObject(options: ForeignObjectOptions): VNode
```

**Parameters**

- `options`: Configuration options for the foreignObject

**Returns** A VNode of type 'foreignObject'

**Example**

```typescript
const vnode = createForeignObject({
  nodeId: 'node-1',
  x: 10,
  y: 20,
  width: 200,
  height: 150
});
// Returns: { type: 'foreignObject', props: { x: 10, y: 20, ... }, children: [...] }
```

**Example**

 With custom container ID and children
```typescript
const vnode = createForeignObject({
  nodeId: 'node-1',
  x: 10,
  y: 20,
  width: 200,
  height: 150,
  containerId: 'my-custom-id',
  children: [
    { type: 'div', props: { className: 'custom-content' } }
  ]
});
```

### `getContainerId`

Get the container ID from a foreignObject VNode

Extracts the container ID from a foreignObject VNode's props. Returns undefined if the VNode is not a foreignObject or doesn't have a container ID.

```ts
function getContainerId(vnode: VNode): string | undefined
```

**Parameters**

- `vnode`: The VNode to extract the container ID from

**Returns** The container ID if the VNode is a foreignObject, undefined otherwise

**Example**

```typescript
const vnode = createForeignObject({
  nodeId: 'node-1',
  x: 0, y: 0, width: 100, height: 100
});

const containerId = getContainerId(vnode);
// Returns: 'fo-node-1-1'
```

**Example**

 Non-foreignObject returns undefined
```typescript
const rectNode = { type: 'rect', props: { ... } };
const containerId = getContainerId(rectNode);
// Returns: undefined
```

### `isForeignObject`

Check if a VNode is a foreignObject element

Type guard function that checks if the given VNode represents
a foreignObject element.

```ts
function isForeignObject(vnode: VNode): boolean
```

**Parameters**

- `vnode`: The VNode to check

**Returns** True if the VNode is a foreignObject, false otherwise

**Example**

```typescript
const foNode = createForeignObject({ ... });
const rectNode = { type: 'rect', props: { ... } };

isForeignObject(foNode);   // true
isForeignObject(rectNode); // false
```

### `isOpaqueVNode`

foreignObject subtrees embed live HTML (framework components, form controls,
media). They are OPAQUE to the diff: props are patched, children are left
exactly as they are. Diffing into them would wipe whatever was mounted there.

```ts
function isOpaqueVNode(vnode: VNode): boolean
```

### `reconcile`

Reconcile `vnode` into `container` using the default patcher.

```ts
function reconcile(container: Element, vnode: VNode): Element
```

### `serializeStyle`

Serialize a style prop. Accepts the object form the renderer emits
(`{ cursor: 'move' }`) as well as a plain string. Returns '' for empty/absent styles.

```ts
function serializeStyle(style: unknown): string
```

## Classes

### `ContainerIdGenerator`

Generate unique container IDs for foreignObject elements

This class provides static methods to generate and validate container IDs
used to link SVG foreignObject elements with their Angular component content.

```ts
class ContainerIdGenerator
```

**Methods**

- `static generate(nodeId: string): string` (static) — Generate a unique container ID for a foreignObject element
- `static isContainerId(id: string): boolean` (static) — Check if a given ID is a valid container ID

Container IDs must start with 'fo-' prefix. This is a lightweight check that only validates the prefix.
- `static getNodeId(containerId: string): string | null` (static) — Extract the node ID from a container ID

Parses a container ID and returns the original node ID. Container IDs must follow the format: `fo-{nodeId}-{counter}`
- `static reset(): void` (static) — Reset the internal counter to zero

This method is primarily for testing purposes to ensure
predictable ID generation in test suites.

### `VNodePatcher`

Keyed VNode → DOM reconciler.

```ts
const patcher = new VNodePatcher();
patcher.reconcile(container, vnodeTree);   // first call: mount
patcher.reconcile(container, nextTree);    // later calls: diff + patch in place
```

```ts
class VNodePatcher
```

**Methods**

- `constructor(options: VNodePatcherOptions = {})`
- `get stats(): Readonly<PatchStats>` — Work done during the most recent `reconcile()` call.
- `reconcile(container: Element, vnode: VNode): Element` — Diff `vnode` against whatever this patcher last rendered into `container`
and patch the existing DOM in place. First call (or a lost root) mounts a
fresh tree.
- `hydrate(container: Element, vnode: VNode): Element` — ADOPT the DOM already inside `container` as the materialization of `vnode`,
without creating, moving or removing a single node.

This is the client half of SSR hydration. The server emitted the
serialization of this exact VNode tree into the HTML; re-mounting it would
mean tearing that DOM down and rebuilding it — the "hydration flash" every
flow library ships with. Instead we simply register the existing root as our
mount, so the NEXT `reconcile()` diffs against `vnode` and touches only what
genuinely changed.

The adopt is only taken when the existing root plausibly IS this tree (same
tag name); otherwise we fall back to a normal mount, which is always correct
(just not flash-free). Assert with `stats`: a real hydration reports
`created: 0, removed: 0`.
- `getMountedElement(container: Element): Element | undefined` — The root element currently mounted in `container`, if any.
- `unmount(container: Element): void` — Remove the mounted tree and forget the container.
- `createElement(vnode: VNode, namespace: string = SVG_NS): Element` — Build a fresh detached DOM element (deep) for a VNode.
- `patchElement(el: Element, oldVNode: VNode, newVNode: VNode): Element` — Diff two VNodes onto an existing element.
- `patchProps( el: Element, oldProps: Record<string, any>, newProps: Record<string, any> ): void` — Apply a prop delta to an element (no children touched).

## Constants

### `defaultPatcher`

Process-wide default patcher — convenient for the common "one DOM, one tree"
case. Instantiate `VNodePatcher` directly for isolated instances.

```ts
const defaultPatcher: VNodePatcher
```

### `SVG_NS`

SVG namespace — everything outside a foreignObject is created here.

```ts
const SVG_NS: "http://www.w3.org/2000/svg"
```

### `XHTML_NS`

XHTML namespace — foreignObject children are HTML, not SVG.

```ts
const XHTML_NS: "http://www.w3.org/1999/xhtml"
```

## Interfaces

### `ForeignObjectOptions`

Options for creating a foreignObject VNode

```ts
interface ForeignObjectOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  | Node ID - used to generate container ID |
| `x` | `number` |  | X coordinate (top-left corner) |
| `y` | `number` |  | Y coordinate (top-left corner) |
| `width` | `number` |  | Width in pixels |
| `height` | `number` |  | Height in pixels |
| `containerId?` | `string` |  | Optional custom container ID If not provided, will be auto-generated using ContainerIdGenerator |
| `children?` | `VNode[]` |  | Optional children VNodes If not provided, creates a default XHTML div wrapper |
| `key?` | `string` |  | Optional key for React/Angular diffing optimization |

### `PatchStats`

Per-reconcile work counters. Reset at the top of every `reconcile()` call. Useful as a cheap regression guard: a steady-state frame should create ~0
elements ("no teardown-and-rebuild").

```ts
interface PatchStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `created` | `number` |  | DOM nodes created from scratch. |
| `reused` | `number` |  | DOM nodes reused in place (patched, not recreated). |
| `moved` | `number` |  | Reused DOM nodes that had to move to a new sibling index. |
| `removed` | `number` |  | DOM nodes removed because their VNode disappeared. |
| `skipped` | `number` |  | Subtrees skipped entirely because the VNode object was identical. |

### `VNodePatcherOptions`

Options for a patcher instance.

```ts
interface VNodePatcherOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `document?` | `Document` |  | Document used to create nodes. Defaults to the ambient `globalThis.document`. Pass one explicitly for headless / SSR / multi-document use. |

## Types

### `VNodeChild`

A child slot in a VNode tree. Strings/numbers materialise as text nodes.

```ts
type VNodeChild = VNode | string | number | null | undefined;
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.
- `toLocaleString(): string` — Returns a date converted to a string using the current locale.

<!-- source: grafloria-engine-overview.md -->

# @grafloria/engine

Headless diagram engine — graph model, commands and undo, layout engines (ELK, dagre, force, tree), Mermaid-compatible text format, collaboration op-log

## Install

```bash
npm install @grafloria/engine
```

## What it exports

- [Core](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core): 45 exports, including `ArchitectureGrid`, `ArchitectureLayoutOptions`, `ArchitectureLayoutResult`, `BulkSelectionOptions`
- [Collab](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-collab): 25 exports, including `ActorId`, `AddOp`, `applyEntitySet`, `applyOp`
- [Commands](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands): 64 exports, including `AddGroupCommand`, `AddLinkCommand`, `AddNodeCommand`, `AddPortCommand`
- [Comments](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-comments): 22 exports, including `AnchorSpec`, `CommentAnchor`, `CommentMessage`, `CommentRegisterTree`
- [Config](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-config): 10 exports, including `ConnectionLineStyle`, `ControlPointEditorConfig`, `DEFAULT_INTERACTION_CONFIG`, `DELIBERATE_MODE_CONFIG`
- [Dsl](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl): 116 exports, including `applyArchitectureModel`, `applyBlockGrid`, `ARCHITECTURE_ICONS`, `architectureModelToFlowchart`
- [Engine](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-engine): 8 exports, including `DiagramEngine`, `DiagramEngineConfig`, `DiagramMode`, `isValidDiagramMode`
- [Interaction](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-interaction): 24 exports, including `areSiblingLanes`, `clampBoxInto`, `CollapseOptions`, `CommandDispatcher`
- [Layout](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout): 177 exports, including `analyseGraphShape`, `ApplyLayoutConfig`, `assessLabelClearance`, `assessPortRespect`
- [Layout — Grid Pack](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-grid-pack): 12 exports, including `BesideSide`, `CachedCell`, `GridColumnLayout`, `GridLayoutCache`
- [Layout — Incremental](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-incremental): 11 exports, including `affectedRegion`, `alignToPrevious`, `constraintsForStrategy`, `IncrementalOptions`
- [Layout — Sugiyama](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-sugiyama): 11 exports, including `createLayeredLayout`, `inferDirection`, `LayeredLayoutOptions`, `LayoutDirection`
- [Models](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models): 45 exports, including `bumpMutationEpoch`, `ChangeEntry`, `CollapsedState`, `DEFAULT_GROUP_HEADER_HEIGHT`
- [Ports](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-ports): 47 exports, including `AnchorSide`, `ANY_PORT_TYPE`, `arePortDataTypesCompatible`, `buildDynamicPortCommands`
- [Routing](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-routing): 40 exports, including `AStarHeuristic`, `AStarOptions`, `AStarRouter`, `CostFunction`
- [Serialization](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-serialization): 41 exports, including `beginIncrementalCapture`, `canonicalStringify`, `checksumOf`, `DeserializedSubgraph`
- [State](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-state): 9 exports, including `ConnectionDragState`, `ConnectionStateManager`, `ConnectionValidator`, `DiagramState`
- [Sync](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync): 40 exports, including `ActorFrontier`, `Awareness`, `AwarenessChange`, `AwarenessMessage`
- [Template Library](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-template-library): 39 exports, including `Activity`, `BadgeLabel`, `BarChart`, `ButtonNode`
- [Templates](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-templates): 26 exports, including `builtInStencils`, `DataBindConfig`, `DragHandlerConfig`, `FlexDirection`
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types): 85 exports, including `Alignment`, `ALL_LOD_FEATURES`, `ArrowStyle`, `BoundingBox`
- [Utils](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-utils): 17 exports, including `boxesIntersect`, `clampToBox`, `createBoundingBox`, `deepClone`
- [Validation](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-validation): 10 exports, including `createConnectionGroupValidator`, `GroupTypeDefinition`, `isConnectionAllowedByGroup`, `LinkTypeDefinition`

<!-- source: grafloria-engine-core.md -->

# Core

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-classes): 9 classes.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-functions): 7 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-interfaces): 24 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-types): 1 types.
- [`ComponentAdapter`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-componentadapter): Framework-agnostic component adapter interface
- [`ForceDirectedLayoutAlgorithm`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-forcedirectedlayoutalgorithm): ForceDirectedLayoutAlgorithm
- [`HybridLayoutAlgorithm`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-hybridlayoutalgorithm): HybridLayoutAlgorithm
- [`SelectionManager`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-core-selectionmanager): SelectionManager provides advanced selection operations

<!-- source: grafloria-engine-core-classes.md -->

# Classes

Import these from `@grafloria/engine`.

## Classes

### `ClipboardManager`

ClipboardManager handles copy/paste operations for diagram entities

Features:
- Serializes selected entities to clipboard format
- Handles relationship preservation (links between copied nodes)
- Supports cross-diagram paste (ID remapping)
- Maintains clipboard history

```ts
class ClipboardManager
```

**Methods**

- `copy(data: { nodes: NodeModel[]; links: LinkModel[]; groups: GroupModel[]; sourceDiagramId?: string; }): void` — Copy entities to clipboard
- `get(): ClipboardData | null` — Get clipboard data
- `claimPasteSlot(): number` — Claim the next paste slot for the CURRENT clipboard payload (1-based).

Repeat-pasting the same copy must cascade — the clipboard's serialized
positions are frozen at copy time, so a constant default offset lands
every paste on the exact same pixels and "paste" appears to work only
once (live report). Each PasteCommand claims its slot once (stable
across redo); a new copy() resets the cascade.
- `hasData(): boolean` — Check if clipboard has data
- `clear(): void` — Clear clipboard
- `getHistory(): ClipboardData[]` — Get clipboard history
- `isFromDiagram(diagramId: string): boolean` — Check if clipboard contains nodes from a specific diagram
- `getStats(): { nodeCount: number; linkCount: number; groupCount: number; timestamp: number | null; }` — Get clipboard statistics

### `EventBus`

```ts
class EventBus
```

**Methods**

- `constructor()`
- `emit(event: string, data?: any): void` — Emit an event
- `on(pattern: string, handler: Function): () => void` — Subscribe to events
- `once(pattern: string, handler: Function): void` — Subscribe once
- `off(pattern: string, handler: Function): void` — Unsubscribe from events
- `removeAllListeners(pattern?: string): void` — Remove all listeners
- `onFiltered( event: string, filter: (data: any) => boolean, handler: Function ): () => void` — Filtered subscription
- `onMapped<T, R>( event: string, mapper: (data: T) => R, handler: (data: R) => void ): () => void` — Mapped subscription
- `onDebounced( event: string, delay: number, handler: Function ): () => void` — Debounced subscription
- `onThrottled( event: string, delay: number, handler: Function ): () => void` — Throttled subscription
- `batch(fn: () => void): void` — Batch events
- `suspend(): void` — Suspend event emission
- `resume(): void` — Resume event emission
- `startRecording(): void` — Start recording events
- `stopRecording(): EventLogEntry[]` — Stop recording
- `getEventLog(): ReadonlyArray<EventLogEntry>` — Get event log
- `clearEventLog(): void` — Clear event log
- `replay(events: EventLogEntry[]): void` — Replay events
- `listenerCount(event: string): number` — Get listener count
- `eventNames(): string[]` — Get all event names

### `GridLayoutAlgorithm`

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

```ts
class GridLayoutAlgorithm extends BaseLayoutAlgorithm
```

**Methods**

- `constructor(config?: LayoutConfiguration)`
- `getName(): string` — Get the name of the layout algorithm
- `getType(): 'grid'` — Get the type of the layout algorithm
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate placement for a single new node
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in grid pattern
- `override configure(config: LayoutConfiguration): void` — Configure grid-specific options
- `override canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Grid layout can always be applied

### `HierarchicalLayoutAlgorithm`

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

```ts
class HierarchicalLayoutAlgorithm extends BaseLayoutAlgorithm
```

**Methods**

- `constructor(config?: LayoutConfiguration)`
- `getName(): string` — Get the name of the layout algorithm
- `getType(): 'hierarchical'` — Get the type of the layout algorithm
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate placement for a single new node
For hierarchical layout, we'll place it near connected nodes
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes using Dagre
- `override configure(config: LayoutConfiguration): void` — Configure hierarchical-specific options
- `override canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Hierarchical layout works best on DAGs but can handle any graph

### `HtmlTemplateRenderer`

HTML Template Renderer
Framework-agnostic HTML template rendering with EventBus integration

Features:
- LemonadeJS template rendering
- Data binding from NodeModel.data
- Event handlers connected to EventBus
- Component mode support (pass-through for framework-specific rendering)
- Proper resource cleanup to prevent memory leaks

```ts
class HtmlTemplateRenderer
```

**Methods**

- `constructor(private eventBus: EventBus)`
- `render(config: HtmlConfig, node: NodeModel): RenderResult` — Render HTML configuration to result
- `disposeNode(nodeUuid: string): void` — Dispose resources for a specific node
- `dispose(): void` — Cleanup all renderer resources

### `LemonadeJSRenderer`

LemonadeJS Enhanced Renderer
Full LemonadeJS runtime with two-way binding

Features:
- Real LemonadeJS template rendering
- Two-way data binding (:bind)
- Reactive updates (automatic re-rendering on data changes)
- Event handlers (:click, :change, etc.)
- EventBus integration (all events flow through engine)
- Component mode support

```ts
class LemonadeJSRenderer
```

**Methods**

- `constructor(private eventBus: EventBus)`
- `render(config: HtmlConfig, node: NodeModel): LemonadeRenderResult` — Render HTML configuration to LemonadeJS element
- `disposeNode(nodeUuid: string): void` — Dispose resources for a specific node
- `dispose(): void` — Cleanup all renderer resources

### `MobilePerformanceService`

```ts
class MobilePerformanceService
```

**Methods**

- `static isMobileDevice(): boolean` (static) — Detect if running on mobile device
- `static isLowPowerDevice(): boolean` (static) — Detect if low-power device
- `initialize(customConfig?: Partial<MobilePerformanceConfig>)` — Initialize with auto-detection
- `throttle<T extends (...args: any[]) => any>( key: string, fn: T, wait: number = this.config.touchMoveThrottle ): (...args: Parameters<T>) => void` — Throttle function execution
- `getRenderQuality(): 'high' | 'medium' | 'low'` — Get recommended render quality based on device
- `shouldSkipRender(nodeCount: number): boolean` — Should skip rendering based on performance config
- `getConfig(): MobilePerformanceConfig` — Get configuration
- `updateConfig(config: Partial<MobilePerformanceConfig>)` — Update configuration

### `PerformanceMonitor`

```ts
class PerformanceMonitor
```

**Methods**

- `constructor(config: PerformanceConfig = {})`
- `measure<T>(name: string, fn: () => T | Promise<T>): T | Promise<T>` — Measure operation performance
- `setWarnThreshold(threshold: number): void` — Set warning threshold
- `getReport(): PerformanceReport` — Get performance report
- `clear(): void` — Clear all metrics

### `PluginManager`

```ts
class PluginManager
```

**Methods**

- `constructor( engine: any, eventBus: any, config: PluginManagerConfig = {} )`
- `register(plugin: Plugin, config: Record<string, any> = {}): void` — Register a plugin (without installing)
- `async install(pluginName: string): Promise<void>` — Install a plugin
- `async uninstall(pluginName: string): Promise<void>` — Uninstall a plugin
- `async activate(pluginName: string): Promise<void>` — Activate a plugin
- `async deactivate(pluginName: string): Promise<void>` — Deactivate a plugin
- `get(pluginName: string): Plugin | undefined` — Get plugin by name
- `has(pluginName: string): boolean` — Check if plugin is registered
- `isInstalled(pluginName: string): boolean` — Check if plugin is installed
- `isActive(pluginName: string): boolean` — Check if plugin is active
- `getState(pluginName: string): PluginState | undefined` — Get plugin state
- `list(): PluginMetadata[]` — List all registered plugins
- `listInstalled(): PluginMetadata[]` — List installed plugins
- `listActive(): PluginMetadata[]` — List active plugins
- `async unregister(pluginName: string): Promise<void>` — Unregister a plugin (removes from registry)
- `async installAll(): Promise<void>` — Install all registered plugins
- `async uninstallAll(): Promise<void>` — Uninstall all plugins
- `async clear(): Promise<void>` — Clear all plugins (uninstall and unregister)

<!-- source: grafloria-engine-core-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `debugLog`

Emit a diagnostic. No-op unless {@link setDebugLogging} turned it on.

```ts
function debugLog(...args: unknown[]): void
```

### `importDrawio`

Import a .drawio / mxGraph XML document.

Accepts plain `<mxGraphModel>` XML or a full `<mxfile>` (compressed or not). A multi-page file imports EVERY page: `diagram` is page 1 (back-compatible)
and `pages[]` — present only when the file has more than one `<diagram>` —
carries each page's own diagram, warnings, and (for a corrupt page) error. Never throws: unreadable input comes back as `{ error }`.

```ts
async function importDrawio(text: string): Promise<DrawioImportResult>
```

### `isComponentAdapter`

Type guard to check if an object implements ComponentAdapter

```ts
function isComponentAdapter(obj: any): obj is ComponentAdapter
```

**Parameters**

- `obj`: Object to check

**Returns** True if object implements ComponentAdapter interface

**Example**

```typescript
if (isComponentAdapter(obj)) {
  obj.registerComponent('test', TestComponent);
}
```

### `isDebugLogging`

Whether diagnostics are on — use this to guard an expensive call site.

```ts
function isDebugLogging(): boolean
```

### `layoutArchitecture`

Lay a diagram out as an architecture composition. Writes into the model.

```ts
function layoutArchitecture(diagram: DiagramModel, options: ArchitectureLayoutOptions = {}): ArchitectureLayoutResult
```

### `setDebugLogging`

Turn diagnostic logging on or off. Off by default, and off is the only state a
consumer ever sees unless they ask for otherwise.

```ts
function setDebugLogging(on: boolean): void
```

### `stripHtmlToText`

`value="<b>Start</b><br>here"` must become "Start here", not carry markup
into the label canon. Block/line-break boundaries turn into single spaces so
words do not fuse.

Entities are decoded a SECOND time here, after the tags are gone. The XML
reader already decoded one level — but with `html=1` (draw.io's default) the
value is an HTML FRAGMENT, so an author's literal `&` was double-encoded on
save (`&amp;amp;`) and one decode still leaves `&amp;` in the label.

```ts
function stripHtmlToText(value: string): string
```

<!-- source: grafloria-engine-core-interfaces.md -->

# Interfaces

Import these from `@grafloria/engine`.

## Interfaces

### `ArchitectureGrid`

A container laid out as an explicit grid (Mermaid block-beta): cells in reading order.

```ts
interface ArchitectureGrid
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Cells to a row; absent = all in one row. |
| `cells` | `Array<{ id?: string; span?: number }>` |  | A block (node or zone id) or a hole (no id), each `span` cells wide. |

### `ArchitectureLayoutOptions`

```ts
interface ArchitectureLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `string` |  | 'LR' (default: the diagram's own direction, else LR) or 'TB'. |
| `measureText?` | `MeasureText` |  | Measures a line of text; the default estimates (the engine has no canvas). |
| `margin?` | `number` |  | Space around the whole drawing. |
| `compact?` | `boolean` |  | Smaller boxes, tighter gaps — a block diagram's grid. Default: the diagram's `metadata.layoutCompact`. |

### `ArchitectureLayoutResult`

```ts
interface ArchitectureLayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodePositions` | `Map<string, { x: number; y: number }>` |  |  |
| `bounds` | `{ x: number; y: number; width: number; height: number }` |  |  |

### `BulkSelectionOptions`

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

Options for bulk selection

```ts
interface BulkSelectionOptions extends SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entityTypes?` | `('node' \| 'link' \| 'group')[]` |  | Entity types to include |

### `ClipboardData`

Clipboard data format for diagram entities

```ts
interface ClipboardData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `SerializedNode[]` |  |  |
| `links` | `SerializedLink[]` |  |  |
| `groups` | `SerializedGroup[]` |  |  |
| `timestamp` | `number` |  |  |
| `sourceDiagramId?` | `string` |  |  |
| `sourceDigramId?` | `string` |  |  |

### `ComponentAdapterWithMetadata`

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

Extended adapter interface with metadata support

Optional extension for adapters that support component metadata

```ts
interface ComponentAdapterWithMetadata extends ComponentAdapter
```

**Members**

- `registerComponentWithMetadata( nodeType: string, component: any, metadata: ComponentMetadata ): void` — Register component with metadata
- `getComponentMetadata(nodeType: string): ComponentMetadata | undefined` — Get metadata for registered component
- `getAllComponentMetadata(): Map<string, ComponentMetadata>` — Get all components with their metadata

### `ComponentMetadata`

Metadata for component registration

Optional metadata that can be associated with registered components

```ts
interface ComponentMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `displayName?` | `string` |  | Display name for component palette |
| `category?` | `string` |  | Category for grouping in palette (e.g., 'ERD', 'BPMN', 'Flowchart') |
| `icon?` | `string` |  | Icon identifier for palette |
| `description?` | `string` |  | Brief description of component |
| `tags?` | `string[]` |  | Tags for search/filtering |
| `defaultSize?` | `{ width: number; height: number }` |  | Default size for new nodes |
| `resizable?` | `boolean` |  | Whether component can be resized |
| `supportsPorts?` | `boolean` |  | Whether component supports ports |

### `ConnectedSelectionOptions`

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

Options for connected node selection

```ts
interface ConnectedSelectionOptions extends SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `'incoming' \| 'outgoing' \| 'both'` |  | Direction to follow links |
| `includeSelf?` | `boolean` |  | Whether to include the starting node |

### `DrawioImportResult`

```ts
interface DrawioImportResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram?` | `DiagramModel` |  | The imported diagram (page 1 of a multi-page file) — absent when `error` is set. |
| `warnings` | `string[]` |  | Every construct the import dropped or approximated, one NAMED entry each. Empty means the file mapped cleanly. For a multi-page file: page 1's warnings plus the file-level ones (including any later page's failure). |
| `error?` | `string` |  | Fatal: the text is not a readable .drawio document. Never thrown. |
| `pages?` | `DrawioPage[]` |  | Present ONLY when the file carries more than one `<diagram>` page. `diagram === pages[0].diagram`; every page imports independently. |

### `EventLogEntry`

```ts
interface EventLogEntry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timestamp` | `number` |  |  |
| `event` | `string` |  |  |
| `data` | `any` |  |  |
| `namespace` | `string` |  |  |
| `action` | `string` |  |  |

### `FilterSelectionOptions`

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

Options for filter-based selection

```ts
interface FilterSelectionOptions extends SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entityTypes?` | `('node' \| 'link' \| 'group')[]` |  | Entity types to filter |

### `LemonadeRenderResult`

LemonadeJS render result with DOM element

```ts
interface LemonadeRenderResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'template' \| 'component'` |  | Rendering mode used |
| `element?` | `HTMLElement` |  | Rendered DOM element (LemonadeJS element) |
| `html?` | `string` |  | Rendered HTML string (for compatibility) |
| `componentRef?` | `string` |  | Component reference (for component mode) |
| `className?` | `string` |  | CSS class names |
| `style?` | `Record<string, any>` |  | Inline styles |
| `eventHandlers` | `Record<string, (event: any) => void>` |  | Event handlers bound to EventBus |
| `bindings` | `Record<string, any>` |  | Data bindings (reactive with LemonadeJS) |
| `self?` | `any` |  | LemonadeJS self object (for reactivity) |
| `zIndex?` | `number` |  | Z-index for HTML layer |
| `pointerEvents` | `boolean` |  | Pointer events enabled |
| `nodeId` | `string` |  | Node ID |
| `nodeUuid` | `string` |  | Node UUID |

### `MobilePerformanceConfig`

```ts
interface MobilePerformanceConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enableThrottling` | `boolean` |  |  |
| `touchMoveThrottle` | `number` |  |  |
| `reducedRendering` | `boolean` |  |  |
| `maxVisibleNodes` | `number` |  |  |
| `lowPowerMode` | `boolean` |  |  |

### `ParsedEvent`

```ts
interface ParsedEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` |  |  |
| `action` | `string` |  |  |
| `full` | `string` |  |  |

### `PerformanceConfig`

```ts
interface PerformanceConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enableMonitoring?` | `boolean` |  |  |
| `enableProfiling?` | `boolean` |  |  |
| `warnThreshold?` | `number` |  |  |

### `PerformanceMetric`

```ts
interface PerformanceMetric
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` |  |  |
| `totalTime` | `number` |  |  |
| `averageTime` | `number` |  |  |
| `minTime` | `number` |  |  |
| `maxTime` | `number` |  |  |

### `PerformanceReport`

```ts
interface PerformanceReport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `metrics` | `Record<string, PerformanceMetric>` |  |  |
| `summary` | `{ totalOperations: number; averageTime: number; slowestOperation: string; fastestOperation: string; }` |  |  |

### `PluginManagerConfig`

```ts
interface PluginManagerConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoActivate?` | `boolean` |  |  |
| `strict?` | `boolean` |  |  |

### `PluginState`

```ts
interface PluginState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `plugin` | `Plugin` |  |  |
| `installed` | `boolean` |  |  |
| `active` | `boolean` |  |  |
| `config` | `Record<string, any>` |  |  |
| `error?` | `Error` |  |  |

### `RectSelectionOptions`

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

Options for rectangle selection

```ts
interface RectSelectionOptions extends SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `intersectionMode?` | `'intersect' \| 'contain'` |  | Intersection mode: 'intersect' or 'contain' |

### `RenderResult`

Render result containing rendered HTML and metadata

```ts
interface RenderResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'template' \| 'component'` |  | Rendering mode used |
| `html?` | `string` |  | Rendered HTML string (for template mode) |
| `componentRef?` | `string` |  | Component reference (for component mode) |
| `className?` | `string` |  | CSS class names |
| `style?` | `Record<string, any>` |  | Inline styles |
| `eventHandlers` | `Record<string, (event: any) => void>` |  | Event handlers bound to EventBus Maps event names to handler functions |
| `bindings` | `Record<string, any>` |  | Data bindings resolved from node data |
| `zIndex?` | `number` |  | Z-index for HTML layer |
| `pointerEvents` | `boolean` |  | Pointer events enabled |
| `nodeId` | `string` |  | Node ID (for event context) |
| `nodeUuid` | `string` |  | Node UUID (for event context) |

### `SelectionOptions`

Selection options for controlling selection behavior

```ts
interface SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `'replace' \| 'add' \| 'subtract' \| 'toggle'` |  | Mode for combining with existing selection |
| `silent?` | `boolean` |  | Whether to emit selection events |
| `maxDepth?` | `number` |  | Maximum depth for recursive operations (-1 = unlimited) |

### `TextFont`

How wide a run of text will draw — for a layout that sizes boxes to their
words. The engine has no canvas, so the default is an ESTIMATE from per-glyph
widths of a UI sans face, deliberately a little wide: a box a few pixels too
roomy looks fine, a box a few pixels too tight cuts its name to "…". A host
that can measure (the renderer, with a canvas) passes its own `measureText`.

```ts
interface TextFont
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` |  | px |
| `weight?` | `string \| number` |  |  |
| `family?` | `string` |  |  |
| `letterSpacing?` | `number` |  | px added after every character (CSS letter-spacing) |

### `TypeSelectionOptions`

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

Options for type-based selection

```ts
interface TypeSelectionOptions extends SelectionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `exact?` | `boolean` |  | Whether to match exact type or allow subtypes |

<!-- source: grafloria-engine-core-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `MeasureText`

```ts
type MeasureText = (text: string, font: TextFont) => number;
```

<!-- source: grafloria-engine-core-componentadapter.md -->

# ComponentAdapter

Import it from `@grafloria/engine`.

Framework-agnostic component adapter interface

Provides unified API for framework component systems

```ts
interface ComponentAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `framework` | `string` |  | Framework identifier (e.g., 'angular', 'react', 'vue') Used for debugging and framework detection |

**Members**

- `registerComponent(nodeType: string, component: any): void` — Register a framework component for a specific node type

Associates a component class/function with a node type string. When nodes of this type are rendered, this component will be instantiated.
- `hasComponent(nodeType: string): boolean` — Check if a component is registered for a node type
- `getComponent(nodeType: string): any | undefined` — Get registered component class for a node type
- `createComponentInstance(node: NodeModel, container: any): any` — Create component instance for a diagram node

Instantiates the registered component for the node's type and passes:
- Node data as inputs/props
- Node position (x, y)
- Node size (width, height) if available
- Any other node metadata
- `updateComponentInstance(instance: any, node: NodeModel): void` — Update component instance with new node data

Efficiently updates component inputs/props without recreating instance. Should trigger framework change detection/re-render.
- `destroyComponentInstance(instance: any): void` — Destroy component instance and clean up resources

Calls framework lifecycle hooks (ngOnDestroy, componentWillUnmount, etc.),
unsubscribes from events, and removes from DOM.

Should be idempotent - safe to call multiple times.
- `getRegisteredTypes(): string[]` — Get list of all registered node type identifiers

Useful for:
- Component palette UI (show available components)
- Validation (check if node type has component)
- Debugging (inspect registered components)
- `destroyAll?(): void` — Destroy all component instances (optional)

Convenience method to clean up all managed components at once. Useful when clearing diagram or unmounting renderer.
- `getActiveCount?(): number` — Get count of active component instances (optional)

Useful for:
- Debugging
- Performance monitoring
- Memory leak detection

<!-- source: grafloria-engine-core-forcedirectedlayoutalgorithm.md -->

# ForceDirectedLayoutAlgorithm

Import it from `@grafloria/engine`.

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

ForceDirectedLayoutAlgorithm

Physics-based layout where:
- Nodes repel each other (like magnets with same poles)
- Connected nodes attract each other (like springs)
- System settles into equilibrium over iterations

Best for:
- Network diagrams
- Social graphs
- Relationship visualizations
- Organic, natural-looking layouts

```ts
class ForceDirectedLayoutAlgorithm extends BaseLayoutAlgorithm implements ILayoutAlgorithm
```

**Methods**

- `constructor(options?: ForceDirectedOptions)`
- `getName(): string` — Get the name of the layout algorithm
- `getType(): 'force-directed'` — Get the type of the layout algorithm
- `override configure(config: LayoutConfiguration): void` — Configure the layout algorithm
- `override getConfiguration(): LayoutConfiguration` — Get current configuration
- `override canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Validate if this algorithm can be applied to the given diagram

For example:
- Hierarchical layout requires a DAG (no cycles)
- Force-directed works better with connected nodes
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node

This is called when a node is added to the diagram. The algorithm should return a position that:
- Doesn't overlap with existing nodes
- Follows the layout strategy
- Fits within the viewport (or is close to existing content)
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram

This is called when the user explicitly requests a re-layout (e.g., clicks "Re-Arrange" button). The algorithm should calculate new positions for ALL nodes.
- `onActivate(): void` — Called when the algorithm is activated
Use this to initialize any state or caches
- `onDeactivate(): void` — Called when the algorithm is deactivated
Use this to clean up state or caches

<!-- source: grafloria-engine-core-hybridlayoutalgorithm.md -->

# HybridLayoutAlgorithm

Import it from `@grafloria/engine`.

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

HybridLayoutAlgorithm

Intelligent layout algorithm that:
- Analyzes the diagram structure
- Detects patterns (grid, tree, network, sparse)
- Automatically selects the best algorithm
- Delegates to the chosen algorithm

Pattern Detection:
- Grid: Few or no edges, uniform structure
- Tree/Hierarchy: Acyclic, directional flow
- Network: Dense connections, cycles
- Sparse: Few nodes, simple connections

Best for:
- Dynamic diagrams where structure changes
- Mixed diagram types
- When user doesn't want to choose algorithm

```ts
class HybridLayoutAlgorithm extends BaseLayoutAlgorithm implements ILayoutAlgorithm
```

**Methods**

- `constructor(options?: HybridOptions)`
- `getName(): string` — Get the name of the layout algorithm
- `getType(): 'hybrid'` — Get the type of the layout algorithm
- `override configure(config: LayoutConfiguration): void` — Configure the layout algorithm
- `override getConfiguration(): LayoutConfiguration` — Get current configuration
- `override canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Validate if this algorithm can be applied to the given diagram

For example:
- Hierarchical layout requires a DAG (no cycles)
- Force-directed works better with connected nodes
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node

This is called when a node is added to the diagram. The algorithm should return a position that:
- Doesn't overlap with existing nodes
- Follows the layout strategy
- Fits within the viewport (or is close to existing content)
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram

This is called when the user explicitly requests a re-layout (e.g., clicks "Re-Arrange" button). The algorithm should calculate new positions for ALL nodes.
- `onActivate(): void` — Called when the algorithm is activated
Use this to initialize any state or caches
- `onDeactivate(): void` — Called when the algorithm is deactivated
Use this to clean up state or caches
- `getLastDetectedPattern(): DetectedPattern | undefined` — Get the last detected pattern (useful for debugging/UI)

<!-- source: grafloria-engine-core-selectionmanager.md -->

# SelectionManager

Import it from `@grafloria/engine`.

SelectionManager provides advanced selection operations

Implements 12 selection patterns from industry research:
- Hierarchical: children, descendants, ancestors, siblings, tree
- Graph: connected, connected component, path
- Group: group members, groups containing
- Filter: by type, by filter, in rectangle
- Bulk: select all, invert selection

```ts
class SelectionManager
```

**Methods**

- `constructor( diagram: DiagramModel | null, private store?: DiagramStore, private eventBus?: EventBus )`
- `setDiagram(diagram: DiagramModel | null): void` — Update diagram reference
- `selectChildren(nodeId: string, options: SelectionOptions = {}): string[]` — Select immediate children of a node
- `selectDescendants(nodeId: string, options: SelectionOptions = {}): string[]` — Select all descendants of a node (recursive)
- `selectAncestors(nodeId: string, options: SelectionOptions = {}): string[]` — Select all ancestors of a node (recursive)
- `selectSiblings(nodeId: string, options: SelectionOptions = {}): string[]` — Select all siblings of a node (nodes with same parent)
- `selectTree(nodeId: string, options: SelectionOptions = {}): string[]` — Select entire tree starting from a node (node + all descendants)
- `selectConnected(nodeId: string, options: ConnectedSelectionOptions = {}): string[]` — Select nodes directly connected to a node via links
- `selectConnectedComponent(nodeId: string, options: SelectionOptions = {}): string[]` — Select entire connected component (all nodes reachable from a node)
- `selectPath(fromNodeId: string, toNodeId: string, options: SelectionOptions = {}): string[]` — Select shortest path between two nodes
- `selectGroupMembers(groupId: string, options: SelectionOptions = {}): string[]` — Select all members of a group
- `selectGroupsContaining(nodeId: string, options: SelectionOptions = {}): string[]` — Select all groups that contain a specific node
- `selectByType(type: string, options: TypeSelectionOptions = {}): string[]` — Select all nodes of a specific type
- `selectByFilter( predicate: (node: NodeModel) => boolean, options: FilterSelectionOptions = {} ): string[]` — Select nodes matching a predicate function
- `selectInRectangle(rect: BoundingBox, options: RectSelectionOptions = {}): string[]` — Select all nodes within or intersecting a rectangle
- `selectAll(options: BulkSelectionOptions = {}): { nodes: string[]; links: string[]; groups: string[] }` — Select all entities in the diagram
- `invertSelection(options: BulkSelectionOptions = {}): { nodes: string[]; links: string[]; groups: string[] }` — Invert current selection

<!-- source: grafloria-engine-collab.md -->

# Collab

Import these from `@grafloria/engine`.

## On their own pages

- [`ReferentialIntegrity`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-collab-referentialintegrity): Holds the diagram to its one hard invariant, and buffers the ops that cannot be applied
- [`Replica`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-collab-replica): One peer.

## Functions

### `applyEntitySet`

Write one property register of an entity that is ALREADY RESOLVED.

Split out of applySet so that referential integrity can drive the identical write into
an entity it is holding OUTSIDE the diagram (a link quarantined because its endpoint
node is gone, see integrity.ts). Same mutators, same idempotence guard, same everything —
a quarantined entity that took a DIFFERENT write path would drift from a live one, and
that drift would only surface on resurrection, long after the cause.

```ts
function applyEntitySet(
  entity: Entity,
  path: string,
  value: OpValue | undefined
): boolean
```

### `applyOp`

Apply ONE op. Returns true if it changed anything.

A NO-OP IS NOT AN ERROR, and this is load-bearing rather than lenient. In a
distributed log you will legitimately receive:
  • a `set` on an entity a concurrent `remove` already deleted,
  • a `remove` for something already removed (duplicate delivery, or two peers
    deleting the same node),
  • an `add` for an id that already exists (the same op delivered twice). Every one of those is normal traffic, not corruption. Throwing on them would mean a
single duplicated packet takes down the session. So we IGNORE them and say so by
returning false — while still throwing loudly on an op that is genuinely malformed
(unknown kind, missing id), because that IS a bug and hiding it helps nobody.

```ts
function applyOp(diagram: DiagramModel, op: Op): boolean
```

### `compareOps`

TOTAL ORDER over ops. Every peer must sort the same log into the same sequence, or
"replay converges" is meaningless.

(clock, actor) is a total order because clocks are integers and actor ids are
distinct strings. The actor tiebreak is arbitrary — it does NOT mean the
lexicographically-larger actor is "righter" — but it is the same arbitrary answer
on every peer, which is the only thing required.

```ts
function compareOps(a: Op, b: Op): number
```

### `opId`

Identity of an op, for idempotent delivery: the same op received twice is one op.

```ts
function opId(op: Op): string
```

### `replay`

Replay an ordered log into a diagram.

Sorts defensively rather than trusting the caller: replay determinism is the property
every later card stands on, and it would be silly to lose it because someone handed us
an array in arrival order.

And it ENFORCES THE INVARIANT at the end, because a peer that joins by replaying
a log must arrive exactly where a peer that was in the room the whole time already is. If
integrity only ran in `Replica.receive()`, a log containing "delete a node that had links"
would replay into a document with a dangling link, and the newcomer would be the only one
holding it. One sweep, once, over the final state — the invariant is a function of that
state and of nothing on the way to it.

NOTE this is the DOCUMENT, not a live peer: the quarantine it builds is discarded with the
temporary registry. A peer that intends to go on editing should be seeded through
`Replica.receive(history)`, which keeps it — and can therefore still bring an orphaned
link back if someone undoes the delete.

```ts
function replay(diagram: DiagramModel, ops: readonly Op[]): number
```

## Classes

### `LamportClock`

A Lamport clock.

`tick()` for a local event. `observe(remoteClock)` on receipt, which jumps this
clock past anything the remote had seen — that is what makes the resulting order
respect causality across peers rather than merely within one.

```ts
class LamportClock
```

**Methods**

- `constructor(private readonly actor: ActorId, start = 0)`
- `tick(): number` — The next clock value for a local event.
- `observe(seen: number): void` — Fold in a clock we have just seen. After this, our next tick() is guaranteed to
be greater than `seen` — so any op we issue AFTER observing theirs sorts AFTER it,
which is exactly the causality guarantee.
- `peek(): number`
- `get actorId(): ActorId`

### `LwwRegistry`

Which write currently owns each register.

The key is (target, id, path) for a property, and (target, id, presence) for whether
the entity exists at all — because an add/remove race is the same kind of race as a
concurrent property write, and deserves the same machinery rather than a special case.

```ts
class LwwRegistry
```

**Methods**

- `admit(op: Op): boolean` — Should this op be applied?

False when a NEWER write already owns the register — the op is not late, it is
SUPERSEDED, and applying it would move the register backwards. This is the single
check that makes arrival-order application equal to total-order replay.

Records the stamp as a side effect when the answer is yes: an op that wins now owns
its register.
- `owner(op: Op): Stamp | undefined` — Who currently owns a register — for debugging, and for a UI that shows attribution.
- `presenceOf(target: Op['target'], id: string): Stamp | undefined` — The stamp that decided whether an entity exists. Undefined if never seen.
- `get size(): number`

### `OpApplyError`

Thrown only for a MALFORMED op — never for a merely-losing one.

```ts
class OpApplyError extends Error
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `message` | `string` |  |  |
| `stack?` | `string` |  |  |

**Methods**

- `constructor(message: string, readonly op: Op)`

### `OpCapture`

Watches a live diagram and emits an Op for every real edit.

Re-entrancy: while `applyRemote()` is running, capture is SUPPRESSED. Without that,
applying a peer's op would capture it as a local op and re-broadcast it, and the two
peers would ping-pong the same edit forever, each amplifying the other. This is the
single most important line in the file and it is three characters long.

```ts
class OpCapture
```

**Methods**

- `constructor( private readonly diagram: DiagramModel, options: OpCaptureOptions )`
- `get lamport(): LamportClock` — The Lamport clock this capture issues from — shared with the sync layer.
- `applyRemote(ops: readonly Op[], apply: (op: Op) => void): void` — Apply remote ops WITHOUT capturing them as local edits.

The clock observes each remote op first, so any op we issue after this sorts after
theirs. That is what makes the resulting order respect causality between peers and
not merely within one.
- `silently(fn: () => void): void` — Run `fn` with capture SUPPRESSED — the model mutations it makes emit no ops.

For work that is DERIVED rather than authored: referential integrity moving an
orphaned link out of the document and back again is a function of state that every
peer computes for itself, so broadcasting it would put a redundant op on the wire that
races with the ops it was derived from. Deriving it locally is not just cheaper, it is
the only thing that converges.

Re-entrant: nesting must not clear the flag early (integrity reconciles INSIDE
applyRemote), or a remote op's mutations would start echoing back mid-batch.
- `stop(): void`

### `OpLog`

An append-only, totally-ordered, de-duplicating op log.

Kept SORTED rather than merely appended, because "the order ops arrived in" is a
property of the network and "the order ops apply in" must not be.

```ts
class OpLog
```

**Methods**

- `append(op: Op): boolean` — Add an op. Returns false if it was already present.

Idempotence is not a nicety here: every real transport redelivers (a WebSocket
reconnect replays, a peer re-sends on timeout, two peers relay the same op to each
other). An op log that applied a duplicate `add` twice, or double-counted a move,
would diverge on nothing more exotic than a flaky wifi connection.
- `appendAll(ops: Iterable<Op>): Op[]`
- `has(op: Op): boolean`
- `toArray(): readonly Op[]` — The ops, in total order.
- `get size(): number`
- `since(clock: number): Op[]` — Ops strictly after `clock` — the tail a peer needs to catch up.
- `maxClock(): number` — The highest clock in the log — what a peer should observe on catch-up.

### `UndoStack`

A per-actor, supersession-aware undo/redo stack.

Owns no model state. It reads the LOG to decide what an undo should do, and applies the
result through the diagram so that capture mints a normal op for it.

```ts
class UndoStack
```

**Methods**

- `constructor( private readonly log: OpLog, private readonly actor: ActorId, private readonly apply: (op: Op) => void )`
- `get canUndo(): boolean`
- `get canRedo(): boolean`
- `get depth(): number` — Depth of the undo stack — one entry per user-visible step.
- `record(op: Op, before: OpBefore): void` — Record a local edit.

Ignored while replaying: the ops an undo emits are the undo, not new work to undo.
- `transact<T>(fn: () => T): T` — Group everything `fn` does into ONE undo step.

Without this, a gesture that touches four registers costs four Ctrl-Zs — and deleting
a node with three links (which the editor does as four ops) would take four. The
grouping is a LOCAL, UI-level concern: it changes what one keypress undoes, never what
is on the wire, and two peers may group differently without diverging.
- `undo(): Op[]` — Undo my last step. Returns the ops it emitted — empty if every part of it was already
superseded, which is a legitimate and silent outcome.

`apply` runs the inverse through the model with capture LIVE, so the resulting ops are
minted, logged, gated and broadcast exactly like any other local edit.
- `redo(): Op[]` — Redo the step undo last took back.

## Interfaces

### `AddOp`

Create an entity. Carries the full serialized form — an add has no prior state to diff against.

```ts
interface AddOp extends OpBase
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `op` | `'add'` |  |  |
| `target` | `Exclude<OpTarget, 'diagram'>` |  |  |
| `id` | `string` |  |  |
| `data` | `SerializedNode \| SerializedLink \| SerializedGroup \| SerializedStroke` |  |  |
| `clock` | `number` |  | Lamport clock. Causality, NOT wall time. Advances past every clock this actor has observed, so `caused-by` always implies a strictly greater clock. |
| `actor` | `ActorId` |  | Who. Also the deterministic tiebreak when two ops share a clock. |

### `OpCaptureOptions`

```ts
interface OpCaptureOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `ActorId` |  | Who this peer is. Must be unique across peers; used for the total-order tiebreak. |
| `onOp` | `(op: Op, before: OpBefore) => void` |  | Called for each captured op — hand it to a sync adapter, an autosave, a test. |
| `startClock?` | `number` |  | Resume a clock across sessions (e.g. from a persisted op-log tail). |

### `RemoveOp`

Remove an entity.

```ts
interface RemoveOp extends OpBase
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `op` | `'remove'` |  |  |
| `target` | `Exclude<OpTarget, 'diagram'>` |  |  |
| `id` | `string` |  |  |
| `clock` | `number` |  | Lamport clock. Causality, NOT wall time. Advances past every clock this actor has observed, so `caused-by` always implies a strictly greater clock. |
| `actor` | `ActorId` |  | Who. Also the deterministic tiebreak when two ops share a clock. |

### `ReplicaOptions`

```ts
interface ReplicaOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `ActorId` |  | This peer's identity. MUST be unique across peers — the total order depends on it. |
| `onLocalOp?` | `(op: Op) => void` |  | Called with each op this peer produces locally. Hand it to a transport. |
| `startClock?` | `number` |  | Resume the Lamport clock from a persisted tail. |

### `SetOp`

Write one property register. The unit of concurrency.

```ts
interface SetOp extends OpBase
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `op` | `'set'` |  |  |
| `target` | `OpTarget` |  |  |
| `id` | `string` |  | '' for the diagram itself, which is a singleton. |
| `path` | `OpPath` |  |  |
| `value?` | `OpValue` |  | The value the register now holds. ABSENT when the op is a clear. |
| `clear?` | `true` |  | Explicitly empty the register: the key is deleted, not set to anything. NOT null — null is a legitimate STORED value (a peer that stores null and a peer that cleared must not converge on the same document), so it cannot double as the clear sentinel. |
| `clock` | `number` |  | Lamport clock. Causality, NOT wall time. Advances past every clock this actor has observed, so `caused-by` always implies a strictly greater clock. |
| `actor` | `ActorId` |  | Who. Also the deterministic tiebreak when two ops share a clock. |

### `Stamp`

The stamp of the write that currently owns a register.

```ts
interface Stamp
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `clock` | `number` |  |  |
| `actor` | `ActorId` |  |  |

## Types

### `ActorId`

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

Who made the edit. Stable for the lifetime of a session; distinct per peer.

```ts
type ActorId = string;
```

### `Op`

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

```ts
type Op = AddOp | RemoveOp | SetOp;
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `clock` | `number` |  | Lamport clock. Causality, NOT wall time. Advances past every clock this actor has observed, so `caused-by` always implies a strictly greater clock. |
| `actor` | `ActorId` |  | Who. Also the deterministic tiebreak when two ops share a clock. |

### `OpBefore`

What the register held BEFORE the op overwrote it.

Needs it and nothing else does, so it is handed to the capture callback
ALONGSIDE the op rather than being put INSIDE it. An op is a wire format: it crosses a
network and a disk, it is broadcast to every peer, and a peer does not need — and must
not be trusted with — the sender's idea of the previous value. Undo is a LOCAL concern. Widening the op to carry it would have doubled the traffic to serve one machine.

```ts
type OpBefore =

  | { kind: 'value'; value: OpValue | undefined }

  | { kind: 'entity'; data: SerializedNode | SerializedLink | SerializedGroup }

  | { kind: 'none' };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `'value'` |  |  |

### `OpPath`

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

A property path. Dot-separated for nested registers: 'position', 'size',
'metadata.label', 'state.locked'.

THE PATH IS THE REGISTER KEY. Two concurrent writes to the SAME path conflict and
are resolved by last-writer-wins; two writes to DIFFERENT paths of the same entity
do not conflict at all and both survive. This is the whole point (see the header).

```ts
type OpPath = string;
```

### `OpTarget`

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

The entity kinds a diagram is made of, plus the diagram itself.

`stroke` joins the list. Ink is DOCUMENT CONTENT — two people drawing
on the same board must converge — so a stroke is a first-class op target, not annotation
smuggled through a diagram-level `set`. (It very nearly WAS: `trackChange('strokes', …)`
is a diagram-level change event, and without `stroke` in this union the capture layer's
fall-through emitted `set(diagram, strokes, <live StrokeModel>)` — a class instance on the
wire, claiming the whole collection. See capture.ts / apply-op.ts.)

```ts
type OpTarget = 'node' | 'link' | 'group' | 'stroke' | 'diagram';
```

### `OpValue`

JSON-safe value. Ops must survive a network hop and a disk round-trip.

```ts
type OpValue = null | boolean | number | string | OpValue[] | { [k: string]: OpValue };
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.
- `toLocaleString(): string` — Returns a date converted to a string using the current locale.

<!-- source: grafloria-engine-collab-referentialintegrity.md -->

# ReferentialIntegrity

Import it from `@grafloria/engine`.

Holds the diagram to its one hard invariant, and buffers the ops that cannot be applied
yet.

Drives the model directly. Its writes MUST NOT be captured as ops (they are derived, and
broadcasting them would race with the very ops they are derived from) — the Replica runs
every call into this class with capture suppressed.

```ts
class ReferentialIntegrity
```

**Methods**

- `constructor( private readonly diagram: DiagramModel, private readonly lww: LwwRegistry )`
- `get quarantined(): string[]` — Link ids currently held out of the document. Small; usually empty.
- `isHeld(id: string): boolean` — Is this link being held out of the document?
- `held(id: string): LinkModel | undefined` — The held instance, so a write can still reach a link that is out of the document.
- `release(id: string): void` — Force a held link back into the document, endpoints or no endpoints.

Only for undo: to UNDO the creation of a link that is currently quarantined, the link
has to be in the document for `removeLink()` to be a real mutation that capture can
mint an op from. Without this the undo silently does nothing, the link's presence
register still says "present", and resurrecting its node brings back a link the user
explicitly took back. The following reconcile() re-quarantines it if it is still
orphaned, so this is a keyhole, not a hole.
- `note(op: Op): void` — Keep the port map and the order watermark current with the ops that change structure.
- `divert(op: Op): boolean` — Can this op be applied to the document right now?

Returns `true` when the op was DIVERTED — written into a link this class is holding out
of the document — in which case the caller must not also hand it to applyOp.

A held link still takes its property writes, through the SAME mutators a live one uses. An entity that took a different write path in quarantine would drift from a live one, and
the drift would only surface on release, long after anything could point at the cause.
- `settle(op: Op): void` — The INCREMENTAL invariant check: only what THIS op could possibly have broken.

A full sweep after every local edit is O(links), and a local edit stream is n ops long, so
a bulk load — importing a document into a live session — was O(n²). Measured: 2,000 nodes
and 2,000 links took 8.5 SECONDS through a Replica, against ~90ms without one. Nothing
caught it, because no perf gate in this repo drives a Replica. That is the shape of defect
this codebase keeps shipping, and I very nearly shipped another one.

So each op pays only for what it can actually affect:

add node      → only a QUARANTINED link can become live. The quarantine is almost always
                  empty, so this is free. (A live link cannot break when a node ARRIVES.)
  add link      → that one link. O(1).
  remove link   → drop it from the quarantine. O(1).
  remove node   → live links attached to it can be orphaned. O(links) — but deleting a node
                  is a human action, not a loop.
  set ports     → same as removing a node: an endpoint may have vanished.
  set endpoints → that one link. O(1).

A bulk load is all adds, so it is linear again.
- `reconcile(): void` — Re-evaluate the invariant over the WHOLE document.

Once per BATCH of remote ops, and once at the end of a replay — where the invariant is a
function of the batch's final state, not of the path through it (a link orphaned mid-batch
and re-parented by the end of it was never really orphaned).
- `forget(op: Op): void` — Drop a link from quarantine for good — its presence register says it is gone.

<!-- source: grafloria-engine-collab-replica.md -->

# Replica

Import it from `@grafloria/engine`.

One peer.

Local edits to `diagram` are captured, appended to `log`, and handed to `onLocalOp`. Remote ops arrive at `receive()`, are de-duplicated, applied, and NOT echoed back.

```ts
class Replica
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `log` |  |  |  |

**Methods**

- `constructor( readonly diagram: DiagramModel, private readonly options: ReplicaOptions )`
- `get actor(): ActorId`
- `get clock(): number` — The clock to resume from, and the watermark a peer asks us to catch up past.
- `get quarantinedLinks(): string[]` — Links held out of the document because an endpoint node is missing. See integrity.ts.
- `get canUndo(): boolean`
- `get canRedo(): boolean`
- `receive(ops: readonly Op[]): Op[]` — Take ops from a peer.

Returns the ops that were actually NEW to us — which is what you forward to other
peers in a mesh, and which is exactly nothing when the same batch arrives twice.
- `undo(): Op[]` — UNDO MY LAST EDIT — not the last edit.

The per-actor property is structural: capture only ever sees LOCAL mutations (remote
ops are applied with capture suppressed), so nothing another peer did can be on this
stack to begin with. See undo.ts for what happens when my edit has already been
superseded by someone else's — the short version is that it does nothing, on purpose.
- `redo(): Op[]`
- `transact<T>(fn: () => T): T` — Group everything `fn` does into ONE undo step.

Deleting a node with three links is four ops and, without this, four presses of Ctrl-Z. Grouping is a LOCAL concern — it changes what one keypress takes back, never what goes
on the wire — so two peers may group differently and still converge.
- `history(): readonly Op[]` — Everything we know, in total order — the catch-up payload for a joining peer.
- `adopt(ops: readonly Op[]): void` — Adopt a persisted op-log tail whose EFFECTS ARE ALREADY IN THE MODEL.

This is `receive()`'s quiet twin, and the difference is the whole point. `receive()` is
for ops the model has not seen: it applies them. `adopt()` is for reopening a saved
document, where the snapshot ALREADY CONTAINS everything the ops did — so it seeds the
log (so a duplicate re-delivery is recognised), the LWW stamps (so a straggling older
write is still refused after a reload) and the repair index, and applies NOTHING.

Re-applying them would be harmless for content — the reducer's redundant-write guard
would drop every one — but it would bump every version counter and fire a full repaint
for a document that has not changed. Worse, it would make opening a file look like an
edit to anyone watching the model's change events.
- `dispose(): void`

<!-- source: grafloria-engine-commands.md -->

# Commands

Import these from `@grafloria/engine`.

## On their own pages

- [Classes A–R](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-classes-a-r): 27 classes, `AddGroupCommand` to `RemovePortCommand`.
- [Classes R–U](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-classes-r-u): 20 classes, `RemoveStrokesCommand` to `UpdateLinkStyleCommand`.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-functions): 2 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-interfaces): 10 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-types): 4 types.
- [`CutCommand`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-commands-cutcommand): CutCommand = {@link CopyCommand} + {@link DeleteSelectionCommand}, executed as

<!-- source: grafloria-engine-commands-classes-a-r.md -->

# Classes A–R

Import these from `@grafloria/engine`.

## Classes

### `AddGroupCommand`

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

```ts
class AddGroupCommand extends Command
```

**Methods**

- `constructor(private group: GroupModel)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `AddLinkCommand`

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

```ts
class AddLinkCommand extends Command
```

**Methods**

- `constructor(private link: LinkModel)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `AddNodeCommand`

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

```ts
class AddNodeCommand extends Command
```

**Methods**

- `constructor(private node: NodeModel)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `AddPortCommand`

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

```ts
class AddPortCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, port: PortModel )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override serialize(): SerializedCommand` — Serialize command

### `AddStrokeCommand`

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

```ts
class AddStrokeCommand extends Command
```

**Methods**

- `constructor(private readonly stroke: StrokeModel)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override serialize(): SerializedCommand` — Serialize command

### `AddToGroupCommand`

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

```ts
class AddToGroupCommand extends Command
```

**Methods**

- `constructor( private groupId: string, private entityId: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `AlignCommand`

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

Align the selected nodes to a shared edge or centre line.

```ts
class AlignCommand extends MultiNodeArrangeCommand
```

**Methods**

- `constructor(nodeIds: string[], private readonly edge: AlignEdge)`
- `override getDescription(): string` — Get description for UI
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command

### `BatchCommand`

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

```ts
class BatchCommand extends Command
```

**Methods**

- `constructor( name: string, private commands: Command[] )`
- `async execute(context: CommandContext): Promise<void>` — Execute the command
- `async undo(context: CommandContext): Promise<void>` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI
- `getCommands(): ReadonlyArray<Command>` — Get all commands in batch
- `addCommand(command: Command): void` — Add command to batch

### `BringNodeToFrontCommand`

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

Lift a node above every other node in the diagram.

```ts
class BringNodeToFrontCommand extends NodeZOrderCommand
```

**Methods**

- `constructor(nodeId: string)`
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone

### `CollapseGroupCommand`

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

```ts
class CollapseGroupCommand extends Command
```

**Methods**

- `constructor( private groupId: string, private options?: CollapseOptions )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `Command`

```ts
abstract class Command
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `timestamp` | `number` |  |  |

**Methods**

- `constructor(name: string)`
- `abstract execute(context: CommandContext): void | Promise<void>` — Execute the command
- `abstract undo(context: CommandContext): void | Promise<void>` — Undo the command
- `redo(context: CommandContext): void | Promise<void>` — Redo the command (default: re-execute)
- `canExecute(context: CommandContext): boolean` — Check if command can be executed
- `canUndo(context: CommandContext): boolean` — Check if command can be undone
- `isUndoable(): boolean` — Does this command belong on the undo stack AT ALL?

`canUndo(context)` is a state probe ("can I undo RIGHT NOW?") consulted at
undo time — many commands answer it from live diagram state. This is the
static declaration consulted at EXECUTE time: a non-mutating command
(Copy) answers false and never enters history. Recording one used to
poison the stack — undo() hit the entry, threw "Cannot undo command:
Copy", never decremented the index, and everything behind it became
permanently unreachable.
- `canMergeWith(other: Command): boolean` — Check if can merge with another command
- `mergeWith(other: Command): Command` — Merge with another command
- `abstract serialize(): SerializedCommand` — Serialize command
- `getDescription(): string` — Get description for UI

### `CommandManager`

```ts
class CommandManager
```

**Methods**

- `constructor( private context: CommandContext, private eventBus: EventBus = context.eventBus )`
- `async execute(command: Command): Promise<void>` — Execute a command
- `async undo(): Promise<void>` — Undo last command
- `async redo(): Promise<void>` — Redo command
- `beginBatch(): void` — Begin batch mode
- `async endBatch(name: string = 'Batch Operation'): Promise<void>` — End batch mode: commit the queued commands as ONE BatchCommand through the
normal execute() path — one history entry, one undo step (with
reverse-order undo), and the same strict-validation gate as any other
command. The old code looped executeCommand() directly, so a "batch"
mutated the diagram while building NO history at all.

Note BatchCommand's existing gate contract: its canExecute() checks every
queued command against the CURRENT (pre-batch) state, so a queue whose
later commands only become executable after earlier ones ran is refused
up front rather than applied halfway.
- `cancelBatch(): void` — Cancel batch
- `clear(): void` — Clear history
- `canUndo(): boolean` — Can undo
- `canRedo(): boolean` — Can redo
- `getHistory(): ReadonlyArray<CommandHistoryEntry>` — Get history
- `getUndoStack(): ReadonlyArray<Command>` — Get undo stack
- `getRedoStack(): ReadonlyArray<Command>` — Get redo stack
- `setMaxHistorySize(size: number): void` — Set max history size
- `setMergingEnabled(enabled: boolean): void` — Enable/disable merging
- `setMergingWindow(milliseconds: number): void` — Set merging window
- `updateContext(updates: Partial<CommandContext>): void` — Update command context

### `CopyCommand`

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

CopyCommand copies selected entities to clipboard

Features:
- Copies selected nodes
- Includes links between selected nodes
- Optionally includes groups containing selected nodes
- Non-destructive (doesn't modify diagram)

```ts
class CopyCommand extends Command
```

**Methods**

- `constructor( private clipboard: ClipboardManager, private options: { includeGroups?: boolean; includeLinks?: boolean; } = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override isUndoable(): boolean` — Does this command belong on the undo stack AT ALL?

`canUndo(context)` is a state probe ("can I undo RIGHT NOW?") consulted at
undo time — many commands answer it from live diagram state. This is the
static declaration consulted at EXECUTE time: a non-mutating command
(Copy) answers false and never enters history. Recording one used to
poison the stack — undo() hit the entry, threw "Cannot undo command:
Copy", never decremented the index, and everything behind it became
permanently unreachable.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `DeleteSelectionCommand`

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

DeleteSelectionCommand deletes selected entities from diagram

Features:
- Deletes selected nodes, links, and groups
- Recursively deletes child nodes
- Removes links connected to deleted nodes
- Removes nodes from groups they belong to
- Stores all deleted data for undo
- Supports undo/redo

```ts
class DeleteSelectionCommand extends Command
```

**Methods**

- `constructor( private options: { deleteChildren?: boolean; deleteLinks?: boolean; } = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override redo(context: CommandContext): void` — Redo re-applies the RECORDED deletion instead of re-running execute().

The default `Command.redo()` calls `execute()`, which reads the LIVE
selection — but `undo()` restores the entities WITHOUT restoring the
selection, so a redo would find an empty selection and throw
`No entities selected`. Redo therefore removes exactly the entities this
command removed the first time. The recorded arrays are left intact, so the
command can be undone again afterwards (undo/redo/undo/redo all work).
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `DistributeCommand`

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

Space the selected nodes with EQUAL GAPS along an axis; the two extreme
nodes stay put and the interior ones are redistributed between them.

```ts
class DistributeCommand extends MultiNodeArrangeCommand
```

**Methods**

- `constructor(nodeIds: string[], private readonly axis: DistributeAxis)`
- `override getDescription(): string` — Get description for UI
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command

### `DuplicateCommand`

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

DuplicateCommand duplicates selected entities in the diagram

Features:
- Generates new IDs for duplicated entities
- Remaps relationships (links, groups, hierarchy)
- Applies position offset
- Preserves all properties (transforms, layout configs, etc.)
- Supports undo/redo
- Similar to paste but operates directly on selection

```ts
class DuplicateCommand extends Command
```

**Methods**

- `constructor( private options: { offset?: Point; selectDuplicated?: boolean; } = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `ExpandGroupCommand`

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

```ts
class ExpandGroupCommand extends Command
```

**Methods**

- `constructor(private groupId: string)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `MacroCommand`

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

```ts
class MacroCommand extends Command
```

**Methods**

- `constructor(name: string)`
- `addStep(command: Command, delay?: number): void` — Add step to macro
- `addSteps(commands: Command[]): void` — Add multiple steps
- `async execute(context: CommandContext): Promise<void>` — Execute the command
- `async undo(context: CommandContext): Promise<void>` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI
- `getSteps(): ReadonlyArray<MacroStep>` — Get all steps in macro
- `clear(): void` — Clear all steps

### `MoveGroupCommand`

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

```ts
class MoveGroupCommand extends Command
```

**Methods**

- `constructor( private readonly nodeMoves: GroupNodeMove[], private readonly frameMoves: GroupFrameMove[] )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `isNoop(): boolean` — True when the gesture actually moved something (drop == press is a no-op).
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `MoveNodeCommand`

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

```ts
class MoveNodeCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, newPosition: Point, oldPosition?: Point, options: MoveNodeCommandOptions = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(other: Command): boolean` — Check if can merge with another command
- `override mergeWith(other: Command): Command` — Merge with another command
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `PasteCommand`

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

PasteCommand pastes entities from clipboard into diagram

Features:
- Generates new IDs for pasted entities
- Remaps relationships (links, groups, hierarchy)
- Applies position offset
- Preserves all properties (transforms, layout configs, etc.)
- Supports undo/redo

```ts
class PasteCommand extends Command
```

**Methods**

- `constructor( private clipboard: ClipboardManager, private options: { offset?: Point; selectPasted?: boolean; } = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `ReconnectLinkCommand`

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

```ts
class ReconnectLinkCommand extends Command
```

**Methods**

- `constructor( private linkId: string, private endpoint: LinkEndpoint, private newPortId: string, private newNodeId: string | undefined, private oldPortId: string, private oldNodeId: string | undefined )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override serialize(): SerializedCommand` — Serialize command

### `RemoveFromGroupCommand`

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

```ts
class RemoveFromGroupCommand extends Command
```

**Methods**

- `constructor( private groupId: string, private entityId: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `RemoveGroupCommand`

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

```ts
class RemoveGroupCommand extends Command
```

**Methods**

- `constructor(private groupId: string)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `RemoveLinkCommand`

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

```ts
class RemoveLinkCommand extends Command
```

**Methods**

- `constructor(private linkId: string)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `RemoveNodeCommand`

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

```ts
class RemoveNodeCommand extends Command
```

**Methods**

- `constructor(private nodeId: string)`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `RemovePortCommand`

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

```ts
class RemovePortCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, private portId: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override serialize(): SerializedCommand` — Serialize command

<!-- source: grafloria-engine-commands-classes-r-u.md -->

# Classes R–U

Import these from `@grafloria/engine`.

## Classes

### `RemoveStrokesCommand`

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

One eraser SWEEP — however many strokes it crossed — is ONE undo step.

```ts
class RemoveStrokesCommand extends Command
```

**Methods**

- `constructor(private readonly strokeIds: readonly string[])`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override serialize(): SerializedCommand` — Serialize command

### `ResizeNodeCommand`

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

```ts
class ResizeNodeCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, newSize: Size, oldSize?: Size )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(other: Command): boolean` — Check if can merge with another command
- `override mergeWith(other: Command): Command` — Merge with another command
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `RotateNodeCommand`

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

Rotate a node to an absolute angle (degrees), undoable.

Mirrors {@link ResizeNodeCommand }: `oldRotation` is captured on first execute
when the caller did not supply it, so a command built from a live gesture (the
model already sits at its final angle) still restores the pre-gesture angle.

```ts
class RotateNodeCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, newRotation: number, oldRotation?: number, options: RotateNodeCommandOptions = {} )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(other: Command): boolean` — Check if can merge with another command
- `override mergeWith(other: Command): Command` — Merge with another command
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SendNodeToBackCommand`

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

Drop a node behind every other node in the diagram.

```ts
class SendNodeToBackCommand extends NodeZOrderCommand
```

**Methods**

- `constructor(nodeId: string)`
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone

### `SetFlexItemCommand`

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

```ts
class SetFlexItemCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, private flexConfig: FlexItemConfig )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetGridItemCommand`

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

```ts
class SetGridItemCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, private gridConfig: GridItemConfig )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLayoutCommand`

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

```ts
class SetLayoutCommand extends Command
```

**Methods**

- `constructor( private groupId: string, private layoutType: 'flexbox' | 'grid', private layoutConfig: LayoutConfig )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLinkDisplayLabelCommand`

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

Set a link's display label — the `metadata.label` dialect — undoable.

Links carry TWO label dialects: the POSITIONED `labels[]` collection
({@link SetLinkLabelCommand } edits those) and the canonical display label
every spec input writes (`edges: [{ label: 'in stock' }]` →
`link.setLabel()` → `metadata.label`, painted at the path's midpoint by the
SVG renderer). The second dialect had no command at all, so the label a
demo/e2e/user actually SEES on an edge could not be edited undoably — the
in-place editor only knew `labels[]`, which that edge does not have. The exact twin of {@link SetNodeLabelCommand }, for the same reason.

```ts
class SetLinkDisplayLabelCommand extends Command
```

**Methods**

- `constructor( private linkId: string, newLabel: string, oldLabel?: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(): boolean` — One editor session = one undo step.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLinkLabelCommand`

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

Set the text of one of a link's labels, undoable.

This is that seam.

```ts
class SetLinkLabelCommand extends Command
```

**Methods**

- `constructor( private linkId: string, private labelIndex: number, newText: string, oldText?: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(): boolean` — One editor session = one undo step.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLinkLabelsCommand`

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

```ts
class SetLinkLabelsCommand extends Command
```

**Methods**

- `constructor( private readonly linkId: string, private readonly labels: LinkLabel[] )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLinkPathTypeCommand`

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

```ts
class SetLinkPathTypeCommand extends Command
```

**Methods**

- `constructor( private readonly linkId: string, private readonly pathType: LinkPathType )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetLinkPointsCommand`

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

Replace a link's `points` (its routed polyline, including any user waypoints),
undoable.

Waypoint editing — add / move / remove a vertex — used to mutate
`link.points` directly through {@link WaypointEditor }, which meant NONE of it
was undoable: Ctrl+Z after dragging a vertex did nothing (or, worse, rewound
some unrelated earlier command). Every vertex gesture now commits exactly one
of these at pointer-up.

`hasManualWaypoints` is part of the state being changed: the renderer only
preserves interior points when that metadata flag is set, so undoing back to a
2-point route must also clear it or the old vertices would be resurrected on
the next re-route.

```ts
class SetLinkPointsCommand extends Command
```

**Methods**

- `constructor( private linkId: string, newPoints: Point[], oldPoints?: Point[] )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(): boolean` — One vertex gesture = one undo step; never merge two of them.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetNodeDataCommand`

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

```ts
class SetNodeDataCommand extends Command
```

**Methods**

- `constructor( nodeId: string | readonly string[], private readonly data: Readonly<Record<string, unknown>> )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetNodeLabelCommand`

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

Set a node's label text, undoable.

A node's label lives in metadata under `label` (that is what
`SVGRenderer.renderNodeLabel` reads), so this command is the metadata write
plus the dirty flag the renderer needs to repaint. It exists because in-place
text editing must be ONE undo step like every other direct manipulation —
before this, nothing in the command layer could touch a label.

```ts
class SetNodeLabelCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, newLabel: string, oldLabel?: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(): boolean` — Never merge: each committed edit (one editor session) is one undo step.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetNodeShapeConfigCommand`

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

```ts
class SetNodeShapeConfigCommand extends Command
```

**Methods**

- `constructor( private readonly nodeId: string, private readonly patch: Readonly<Record<string, unknown>> )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetNodeStyleCommand`

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

```ts
class SetNodeStyleCommand extends Command
```

**Methods**

- `constructor( nodeId: string | readonly string[], private readonly style: Partial<NodeStyle> )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetNodeZIndexCommand`

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

Set a node's stacking index to an explicit value.

```ts
class SetNodeZIndexCommand extends NodeZOrderCommand
```

**Methods**

- `constructor(nodeId: string, private zIndex: number)`
- `override canMergeWith(other: Command): boolean` — Check if can merge with another command
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone

### `SetParentCommand`

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

```ts
class SetParentCommand extends Command
```

**Methods**

- `constructor( private nodeId: string, private newParentId?: string )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `SetStrokePointsCommand`

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

Replace an ink stroke's point list, undoable. The stroke-edit tool's commit:
a drag that translates a stroke ends in exactly ONE of these at pointer-up.

Mirrors {@link SetLinkPointsCommand }, minus the `hasManualWaypoints` bookkeeping
— a stroke's points are ALWAYS authored content (nothing re-routes them), so
there is no derived/manual flag to keep in step.

One gesture therefore puts
ONE op on the wire — never per-pointermove spam, never a class instance.

The FROM snapshot is taken from the model on first execute() when the caller
did not supply one — but the stroke-edit tool DOES supply it (the gesture-start
geometry), because by commit time a live-feedback path may already have the
model sitting at TO, and a FROM read then would make undo a no-op.

```ts
class SetStrokePointsCommand extends Command
```

**Methods**

- `constructor( private strokeId: string, newPoints: readonly StrokePoint[], oldPoints?: readonly StrokePoint[] )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override canMergeWith(): boolean` — One edit gesture = one undo step; never merge two of them.
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

### `UpdateLinkStyleCommand`

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

```ts
class UpdateLinkStyleCommand extends Command
```

**Methods**

- `constructor( private readonly linkId: string, private readonly style: Partial<LinkStyle> )`
- `override execute(context: CommandContext): void` — Execute the command
- `override undo(context: CommandContext): void` — Undo the command
- `override canExecute(context: CommandContext): boolean` — Check if command can be executed
- `override canUndo(context: CommandContext): boolean` — Check if command can be undone
- `override serialize(): SerializedCommand` — Serialize command
- `override getDescription(): string` — Get description for UI

<!-- source: grafloria-engine-commands-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `remapNodePortIds`

Re-assign fresh ids to every port on a freshly-cloned node.

Why this is needed: {@link NodeModel.fromJSON} restores each port with its
ORIGINAL serialized id, so a clone would otherwise share port ids with its
source node. Links reference the engine's nanoid port ids directly (they are
NOT `"nodeId:portName"` strings), and node lookup resolves a node by "which
node owns this port id" — duplicate port ids across nodes make that lookup
ambiguous and break pasted/duplicated links.

For each port this:
 - generates a new port id and records `oldPortId -> newPortId` in `portIdMap`
   so the caller can remap link endpoints,
 - points the port back at its new owning node,
 - rebuilds the node's ports Map (whose KEYS are the port ids) so lookups by
   id keep working.

```ts
function remapNodePortIds(
  node: NodeModel,
  newNodeId: string,
  portIdMap: Map<string, string>,
): void
```

**Parameters**

- `node`: the cloned node (mutated in place)
- `newNodeId`: the clone's node id (ports' `nodeId` is set to this)
- `portIdMap`: accumulates oldPortId -> newPortId across all cloned nodes

### `resolveLinkNodeIds`

Resolve the ids of the nodes a link is attached to.

WHY THIS EXISTS: a link's `sourcePortId`/`targetPortId` are PORT ids — engine
nanoids — NOT `"nodeId:portName"` strings. Commands that used
`portId.split(':')[0]` to get a node id therefore resolved nothing for links
created the production way (`diagram.connectNodes()` / the interactive connect
path), which silently:
  - made CopyCommand skip every link between the copied nodes, and
  - made DeleteSelectionCommand leave ORPHAN links behind when it deleted the
    nodes at both ends (`removeNode()` does not cascade to links).

Resolution order:
  1. the ids LinkModel caches (`sourceNodeId` / `targetNodeId`, backfilled by
     `addLink()` / `restoreLink()` from the port index),
  2. the diagram's O(1) port index (`getNodeByPortId`),
  3. the legacy `"nodeId:portName"` convention — still used by hand-built test
     links and older documents — but only when it names a node that actually
     exists.

```ts
function resolveLinkNodeIds(
  diagram: any,
  link: { sourcePortId: string; targetPortId: string; sourceNodeId?: string; targetNodeId?: string }
): { sourceNodeId?: string; targetNodeId?: string }
```

**Returns** the owning node ids; either may be `undefined` for a dangling endpoint.

<!-- source: grafloria-engine-commands-interfaces.md -->

# Interfaces

Import these from `@grafloria/engine`.

## Interfaces

### `CommandContext`

```ts
interface CommandContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `any` |  |  |
| `eventBus` | `any` |  |  |
| `store?` | `any` |  |  |
| `engine?` | `any` |  |  |

### `CommandHistoryEntry`

```ts
interface CommandHistoryEntry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `command` | `Command` |  |  |
| `timestamp` | `number` |  |  |
| `duration` | `number` |  |  |
| `success` | `boolean` |  | History only ever records commands that EXECUTED successfully, so this is always `true` and `error` is never set. Both fields survive purely for API compatibility — a command that throws (or fails strict validation) no longer enters history at all, because canUndo()/undo() never consulted these flags and would happily "undo" a mutation that never happened. |
| `error?` | `Error` |  |  |

### `CutCommandOptions`

```ts
interface CutCommandOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeGroups?` | `boolean` |  | Include groups containing selected nodes in the clipboard payload (default: false) |
| `includeLinks?` | `boolean` |  | Include links between copied nodes in the clipboard payload (default: true) |
| `deleteChildren?` | `boolean` |  | Delete child nodes recursively (default: true) |
| `deleteLinks?` | `boolean` |  | Delete links connected to the deleted nodes (default: true) |

### `GroupFrameMove`

One (nested) group frame's move.

```ts
interface GroupFrameMove
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `groupId` | `string` |  |  |
| `from` | `GroupFrameSnapshot` |  |  |
| `to` | `GroupFrameSnapshot` |  |  |

### `GroupFrameSnapshot`

A group frame's restorable geometry (matches GroupModel.restoreGeometry).

```ts
interface GroupFrameSnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `{ x: number; y: number }` |  |  |
| `size?` | `{ width: number; height: number; depth: number }` |  |  |
| `bounds?` | `{ x: number; y: number; width: number; height: number }` |  |  |

### `GroupNodeMove`

One member node's absolute move.

```ts
interface GroupNodeMove
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `from` | `Point` |  |  |
| `to` | `Point` |  |  |

### `MacroStep`

```ts
interface MacroStep
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `command` | `Command` |  |  |
| `delay?` | `number` |  |  |

### `MoveNodeCommandOptions`

```ts
interface MoveNodeCommandOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mergeable?` | `boolean` |  | Whether CommandManager may MERGE this move into the previous one for the same node (default: true, preserving the historic behaviour). |

### `RotateNodeCommandOptions`

```ts
interface RotateNodeCommandOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mergeable?` | `boolean` |  | Whether CommandManager may MERGE this rotation into the previous one for the same node (default: false). |

### `SerializedCommand`

```ts
interface SerializedCommand
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `timestamp` | `number` |  |  |
| `data` | `any` |  |  |

<!-- source: grafloria-engine-commands-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `AlignEdge`

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

```ts
type AlignEdge = 'left' | 'right' | 'top' | 'bottom' | 'center-x' | 'center-y';
```

### `DistributeAxis`

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

```ts
type DistributeAxis = 'horizontal' | 'vertical';
```

### `LinkEndpoint`

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

```ts
type LinkEndpoint = 'source' | 'target';
```

### `LinkPathType`

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

```ts
type LinkPathType = 'direct' | 'orthogonal' | 'smooth' | 'bezier';
```

<!-- source: grafloria-engine-commands-cutcommand.md -->

# CutCommand

Import it from `@grafloria/engine`.

Also has every member of `MacroCommand`, `Command`, listed on their own entries.

CutCommand = {@link CopyCommand} + {@link DeleteSelectionCommand}, executed as
ONE undoable step (a {@link MacroCommand}): the selection lands on the
clipboard and is removed from the diagram, and a single undo brings it back.

Two inherited behaviours had to be overridden — both are load-bearing:

1. `canUndo`. {@link MacroCommand.canUndo} is the AND of its steps, and
    {@link CopyCommand.canUndo} returns FALSE by design (a copy mutates
    nothing, so it has nothing to undo). The inherited implementation would
    therefore report a Cut as un-undoable and `CommandManager.undo()` would
    throw `Cannot undo command: Cut`. A cut is undoable exactly when its
    delete half is.

2. `redo`. The default redo re-runs `execute()`, which re-runs the COPY step
    — and copy reads the CURRENT selection. `undo()` restores the entities but
    NOT the selection, so that copy would throw `No nodes selected`. The
    clipboard already holds this cut's payload, so a redo is precisely
    "delete those same entities again", which the delete half can replay from
    its own recorded data.

```ts
class CutCommand extends MacroCommand
```

**Methods**

- `constructor(clipboard: ClipboardManager, options: CutCommandOptions = {})`
- `override canExecute(context: CommandContext): boolean` — A cut needs something to copy: CopyCommand has no link-only payload, so a
selection of links alone cannot be cut (it can still be deleted).
- `override canUndo(context: CommandContext): boolean` — See class docs (1): copy is non-undoable by design; the delete half decides.
- `override async redo(context: CommandContext): Promise<void>` — See class docs (2): replay the delete from its recorded data, never the copy.
- `override getDescription(): string` — Get description for UI

<!-- source: grafloria-engine-comments.md -->

# Comments

Import these from `@grafloria/engine`.

## On their own pages

- [`CommentStore`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-comments-commentstore)

## Functions

### `mentionIds`

Just the ids — what gets stored on the message register.

```ts
function mentionIds(body: string): string[]
```

### `mentionKey`

The idempotency key. Derived only from op-borne data — never from local state.

```ts
function mentionKey(threadId: string, messageId: string): string
```

### `messageKey`

The sort key of a message, as an opaque comparable string. Used by read-state.

```ts
function messageKey(m: CommentMessage): string
```

### `messageOrder`

THE TOTAL ORDER ON MESSAGES.

Every peer must list a thread's messages in the SAME order or two people reading the
same conversation read different conversations. `(createdAt, author, id)` is total
(ids are unique) and it is computed from data that travels IN the ops, so it is
identical on every peer and stable across replay.

It is wall time, and that is a deliberate, bounded concession. Wall time may not
decide MERGE — a skewed clock deciding which edit wins is silent data loss, which is
why the substrate uses Lamport clocks for that and why this function is not used for
anything but display order. Wall time deciding the ORDER OF A CHAT LIST is what every
messaging product on earth does, and its worst case is cosmetic: two messages sent
within the clock skew of each other may read in the wrong order. Nobody loses a
comment. (The alternative — a per-message Lamport stamp — is unavailable without
reaching into OpCapture's clock, and buying strict causal order for a chat list at
the price of a second way to mint stamps is a bad trade.)

```ts
function messageOrder(a: CommentMessage, b: CommentMessage): number
```

### `parseMentions`

Extract the mentions from a body. Pure, and total: never throws, never re-orders.

Deduplicated by id — mentioning Ada three times in one message is one notification, not
three, and that is a property of the DATA, not of the notifier's retry policy.

```ts
function parseMentions(body: string): MentionRef[]
```

## Classes

### `ReadState`

What THIS viewer has seen. Local. Never synced.

```ts
class ReadState
```

**Methods**

- `constructor(readonly viewer: string)`
- `markRead(threadId: string, messages: readonly CommentMessage[]): void` — Mark a thread read up to its newest message.

Takes the messages rather than a key so the caller cannot accidentally set a
watermark ahead of the messages it has actually seen — which would silently swallow
a message that is still in flight.
- `markUnread(threadId: string): void` — Explicitly mark unread again (a "mark as unread" affordance).
- `unreadCount(threadId: string, messages: readonly CommentMessage[]): number` — How many messages in this thread the viewer has not seen.

A message YOU wrote is never unread — you were there. A tombstoned message is never
unread either: a badge that says "1 unread" and opens onto "message deleted" is a
badge that has wasted someone's attention, which is the only currency a notification
has.
- `isRead(threadId: string, messages: readonly CommentMessage[]): boolean`
- `toJSON(): SerializedReadState`
- `static fromJSON(data: SerializedReadState): ReadState` (static)

## Interfaces

### `CommentMessage`

One message. ONE register — the rule that makes concurrent replies survive.

An edit rewrites the whole register (an edit IS a whole-body replacement, so nothing
is gained by splitting it). A delete rewrites it as a TOMBSTONE — `deleted: true`,
body cleared, author and createdAt kept — rather than removing the key, because
removing it would let a concurrent edit resurrect the message with no body, and
because the ordering of the surviving messages must not shift under a peer that has
not yet seen the delete.

```ts
interface CommentMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `author` | `string` |  |  |
| `body` | `string` |  |  |
| `createdAt` | `number` |  |  |
| `mentions?` | `string[]` |  | User ids extracted from the body at authoring time. Convergent, queryable. |
| `editedAt?` | `number` |  |  |
| `deleted?` | `boolean` |  |  |

### `CommentStoreOptions`

```ts
interface CommentStoreOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewer` | `string` |  | The PERSON at this peer. Not the actor/session id. |
| `idFactory?` | `() => string` |  | Deterministic ids for tests. Default: unique by construction (see `mintId`). |
| `now?` | `() => number` |  | Deterministic time for tests. Default: Date.now. |
| `notifier?` | `MentionNotifier` |  | The |
| `readState?` | `ReadState` |  | This viewer's unread watermarks — hand back what you persisted. |
| `labelOf?` | `(kind: 'node' \| 'link', id: string) => string \| undefined` |  | How to name an entity. Default: `metadata.label`, then `type`, then the id. |

### `CommentThreadHead`

Write-once thread identity. One register, so a thread appears whole or not at all.

```ts
interface CommentThreadHead
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `author` | `string` |  | The PERSON who started the thread (a user id, not a session/actor id). |
| `createdAt` | `number` |  | Wall-clock milliseconds, captured at authoring time and carried IN the op. |

### `CommentThreadStatus`

Resolve/reopen. ONE register, so the flag and its attribution can never split.

```ts
interface CommentThreadStatus
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `resolved` | `boolean` |  |  |
| `by` | `string` |  |  |
| `at` | `number` |  |  |

### `CommentThreadView`

A thread, assembled for reading: sorted messages, derived anchor, viewer's unread count.

```ts
interface CommentThreadView
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `author` | `string` |  |  |
| `createdAt` | `number` |  |  |
| `anchor` | `CommentAnchor` |  |  |
| `resolved` | `boolean` |  |  |
| `resolvedBy?` | `string` |  |  |
| `resolvedAt?` | `number` |  |  |
| `messages` | `CommentMessage[]` |  | Total order, identical on every peer. Tombstones included (flagged `deleted`). |
| `unread` | `number` |  | Messages this viewer has not seen, authored by someone else. LOCAL, never synced. |
| `resolvedAnchor` | `ResolvedAnchor` |  | Derived from the live diagram — see ResolvedAnchor. |

### `MentionEvent`

What a notifier is handed. Everything it needs, nothing it would have to guess.

`anchor` is in here on purpose: "Ada was mentioned" is useless; "Ada was mentioned in a
thread on the Payment gateway node" is a notification a human can act on without opening
the file.

```ts
interface MentionEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `key` | `string` |  | STABLE ACROSS PEERS AND ACROSS REPLAYS. Dedupe on this or send N copies. See header. |
| `diagramId` | `string` |  |  |
| `threadId` | `string` |  |  |
| `messageId` | `string` |  |  |
| `mentioned` | `string[]` |  | User ids. The host's directory turns these into people. |
| `author` | `string` |  | The user id of whoever wrote the message. |
| `body` | `string` |  |  |
| `anchor` | `CommentAnchor` |  |  |
| `createdAt` | `number` |  |  |
| `local` | `boolean` |  | True when this peer is the one that authored the message. |

### `MentionNotifier`

The seam. One method. The engine calls it; the host implements it.

```ts
interface MentionNotifier
```

**Members**

- `notify(event: MentionEvent): void`

### `MentionRef`

One

```ts
interface MentionRef
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The user id to notify. From `@[Name](id)` this is `id`; from `@handle` it is `handle`. |
| `display` | `string` |  | What was written on screen, for rendering the chip. |
| `raw` | `string` |  | The exact source text, so a renderer can replace it in place. |
| `index` | `number` |  | Character offset of `raw` in the body. |

### `ResolvedAnchor`

WHERE A THREAD'S PIN GOES, AND WHETHER ITS SUBJECT STILL EXISTS.

`attached` is DERIVED — computed from the live diagram on every read, never stored
and never synced. That is the single most important decision in this file, and it is
argued at length in comment-store.ts (`resolveAnchor`).

```ts
interface ResolvedAnchor
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `point` | `WorldPoint` |  | World coordinates for the pin. |
| `attached` | `boolean` |  | False ⇒ ORPHANED: the node/link this thread is about is not in the diagram. |
| `targetLabel` | `string` |  | The live label if attached; the snapshot taken at anchor time if not. |
| `targetKind` | `'node' \| 'link' \| 'region'` |  |  |
| `targetId?` | `string` |  |  |

### `SerializedReadState`

The serializable shape. Give this to the host to persist; hand it back on load.

```ts
interface SerializedReadState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewer` | `string` |  |  |
| `watermarks` | `Record<string, string>` |  | threadId → the messageKey of the newest message this viewer has seen. |

### `StoredThread`

The raw register tree as it sits on the model and in the serialized document.

```ts
interface StoredThread
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `head?` | `CommentThreadHead` |  |  |
| `anchor?` | `CommentAnchor` |  |  |
| `status?` | `CommentThreadStatus` |  |  |
| `messages?` | `Record<string, CommentMessage>` |  |  |

### `WorldPoint`

A point in WORLD space. Never screen space — see CommentAnchor.

```ts
interface WorldPoint
```

**Properties**

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

## Types

### `AnchorSpec`

What a caller asks for. The store fills in the obituary (fallback point + label).

```ts
type AnchorSpec =
  | { kind: 'node'; id: string }
  | { kind: 'link'; id: string }
  | { kind: 'region'; x: number; y: number; width?: number; height?: number };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `'node'` |  |  |

### `CommentAnchor`

WHAT A COMMENT IS ABOUT.

ANCHOR BY IDENTITY, NEVER BY COORDINATES — for anything that has an identity. A
comment pinned to (420, 180) is a comment about whatever happens to be at (420, 180)
*right now*, which after one auto-layout is a different node and a different meaning. The comment would still be there, still timestamped, still confidently wrong. So a
node/link anchor stores the ENTITY ID and derives its position from the live entity
every frame; move the node across the canvas and the pin comes with it, and not one
op is emitted to make that happen (position is derived, and derived state is never
synced — the same rule capture.ts applies to link routes).

A FREE-REGION anchor genuinely is coordinates, and they are WORLD coordinates. Screen
coordinates would make the pin's meaning depend on the reader's scroll position and
zoom — a note about the top-right corner of a subsystem would drift onto empty canvas
the moment anyone panned. World coordinates are invariant under pan and zoom by
construction, and the renderer draws them inside the viewBox, so the pin sticks to
the diagram rather than to the glass.

`fallback` and `targetLabel` are the ANCHOR'S OBITUARY: where the target was and what
it was called, captured at the moment the thread was created. They exist for exactly
one purpose — so that a thread whose target has been DELETED can still be shown, in
the right place, saying what it was about. See ResolvedAnchor.

```ts
type CommentAnchor =
  | {
      kind: 'node';

      id: string;

      fallback: WorldPoint;

      targetLabel?: string;
    }
  | {
      kind: 'link';
      id: string;
      fallback: WorldPoint;
      targetLabel?: string;
    }
  | {

      kind: 'region';
      x: number;
      y: number;
      width?: number;
      height?: number;
    };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `'node'` |  |  |

### `CommentRegisterTree`

```ts
type CommentRegisterTree = Record<string, StoredThread>;
```

<!-- source: grafloria-engine-comments-commentstore.md -->

# CommentStore

Import it from `@grafloria/engine`.

```ts
class CommentStore
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `readState` | `ReadState` |  |  |

**Methods**

- `constructor( readonly diagram: DiagramModel, options: CommentStoreOptions )`
- `createThread(spec: AnchorSpec, body: string): string` — Start a thread. Three ops: head, anchor, first message.

Three and not one, because `comments.<tid>` and `comments.<tid>.status` would be
OVERLAPPING registers — LWW cannot order two writes to different paths, so a
whole-thread write that arrived late would silently wipe a resolve. Prefix-free
leaves are the price of correctness under out-of-order delivery, and the fuzz test
asserts prefix-freedom rather than trusting me to remember it.
- `reply(threadId: string, body: string): string` — Add a message. ONE register — which is why a colleague's simultaneous reply lives.
- `editMessage(threadId: string, messageId: string, body: string): boolean` — Edit a message: rewrite its register whole.

Two people editing the same message concurrently is a genuine conflict on one
register and LWW picks one, deterministically, on every peer. That is the right
answer — an edit IS a whole-body replacement, so there is no finer cut that would
have saved both, and merging two rewrites of one sentence produces a sentence
neither person wrote.
- `deleteMessage(threadId: string, messageId: string): boolean` — Delete a message — TOMBSTONE, never key removal.

Removing the key would let a concurrent edit of the same message resurrect it from
the dead (the edit's register write auto-creates the path again), and it would shift
the ordering of the surviving messages on a peer that has not yet seen the delete. A tombstone keeps the author and the timestamp, so the conversation still reads in
the order it happened, with a hole where somebody withdrew something — which is what
actually occurred.
- `resolve(threadId: string): boolean`
- `reopen(threadId: string): boolean`
- `reanchor(threadId: string, spec: AnchorSpec): boolean` — Re-point a thread — the manual rescue for an orphan, and the only way to move one.
- `resolveAnchor(threadId: string, anchor: CommentAnchor): ResolvedAnchor` — WHERE THE PIN GOES, AND WHETHER ITS SUBJECT STILL EXISTS.

===========================================================================
WHAT HAPPENS TO A COMMENT WHEN SOMEBODY DELETES ITS NODE
===========================================================================

It survives. It becomes ORPHANED — visibly detached, still readable, still
replyable, still listed — and it never, under any circumstance, disappears.

Argued from the user's side, because that is the only side that matters here. A
thread is a conversation between PEOPLE. The node is merely what it was about. If
Ben deletes a box and that silently destroys the eight-message design argument Ada
and Chen had about it, then a routine edit has quietly deleted other people's work —
work they cannot recover, cannot see was lost, and were never asked about. Worse, the
comment is very often ABOUT the deletion ("why is this still here? we cut this in
March") — so the delete would destroy precisely the discussion that authorised it. There is no version of that trade that is worth a tidier canvas.

The inverse mistake is just as bad: keeping the pin attached to nothing, hovering at
the coordinates of a box that is gone. That is a lie with a timestamp on it. So the
orphan is DRAWN DIFFERENTLY, NAMED DIFFERENTLY ("detached"), and grouped separately
in the panel. The user is told, in the place they are looking, exactly what happened.

===========================================================================
AND WHY `attached` IS DERIVED RATHER THAN STORED — this is the subtle half
===========================================================================

The obvious implementation writes an `orphaned: true` flag when the node dies. It is
wrong three ways, and every one of them bites:

1. IT RACES. Marking a thread orphaned would be an OP, emitted by whichever peer
     noticed the delete first. Two peers notice, two ops. Worse, the flag now merges
     by LWW against a concurrent un-delete, and the flag can converge to a value that
     contradicts the diagram it is meant to describe: `orphaned: true` on a thread
     whose node is manifestly right there. Derived state cannot contradict its source. Stored state can, and eventually will.
  2. IT BREAKS UNDO. Ctrl-Z brings the node back. A stored flag would need a second
     op to un-orphan the thread, from some peer that thought to look, and until then
     the thread sits detached beside the node it is attached to. Derived, the thread
     RE-ATTACHES on the very next read, with zero ops and zero code.
  3. IT ASSUMES AN ANSWER THE CRDT CARD HAS NOT GIVEN YET. If they land on add-wins, a node this store had marked
     dead comes back. Deriving the state means BOTH answers are already handled and
     neither can be wrong: whatever the diagram says right now, the pin agrees with
     it. That is the only way to be robust to a decision that has not been made.

So: nothing is stored, nothing is broadcast, and `attached` is simply "is the entity
in the diagram, right now". The thread survives the delete BY NOT DEPENDING ON THE
ENTITY AT ALL.
- `thread(threadId: string): CommentThreadView | undefined` — Assemble a thread for reading.

INCOMPLETE THREADS ARE INVISIBLE, NOT BROKEN. A store that crashed on that would be broken by a packet reorder; a store
that rendered a half-thread would show a message from nobody, about nothing. So a
thread without a head or an anchor simply does not exist yet, and it appears — whole,
with every message that arrived early already in it — the moment its head lands. Nothing is dropped; the pieces just wait.
- `threads(options?: { includeResolved?: boolean }): CommentThreadView[]` — Every readable thread, in a stable order identical on every peer.
- `orphans(): CommentThreadView[]` — Threads whose subject is gone. Derived, every time. Never stored, never synced.
- `threadsFor(kind: 'node' | 'link', id: string): CommentThreadView[]` — Threads anchored to a given entity — attached ones only.
- `markRead(threadId: string): void`
- `markUnread(threadId: string): void`
- `totalUnread(): number` — Unread messages across every unresolved thread — the number a badge shows.
- `mentionsOfViewer(): CommentThreadView[]` — Threads that
- `onChange(cb: () => void): Unsub` — Fired whenever the comment DATA or this viewer's READ STATE changes.
- `dispose(): void`

<!-- source: grafloria-engine-config.md -->

# Config

Import these from `@grafloria/engine`.

## Constants

### `DEFAULT_INTERACTION_CONFIG`

Default interaction configuration
Optimized for modern diagramming workflows

```ts
const DEFAULT_INTERACTION_CONFIG: InteractionConfig
```

### `DELIBERATE_MODE_CONFIG`

Deliberate mode preset (safe workflow)

```ts
const DELIBERATE_MODE_CONFIG: Partial<InteractionConfig>
```

### `DIRECT_MODE_CONFIG`

Direct mode preset (fast workflow)

```ts
const DIRECT_MODE_CONFIG: Partial<InteractionConfig>
```

### `SMART_MODE_CONFIG`

Smart mode preset (Visio-style)

```ts
const SMART_MODE_CONFIG: Partial<InteractionConfig>
```

## Interfaces

### `ControlPointEditorConfig`

Control point editor configuration

```ts
interface ControlPointEditorConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `snapToGrid` | `boolean` |  | Snap control points to grid |
| `gridSize` | `number` |  | Grid size for snapping (in pixels) |
| `handleRadius` | `number` |  | Control point handle radius (in pixels) |
| `handleColor` | `string` |  | Control point handle color |
| `handleStrokeColor` | `string` |  | Control point handle stroke color |
| `controlLineColor` | `string` |  | Control line color (line from anchor to control point) |
| `controlLineWidth` | `number` |  | Control line stroke width |
| `controlLineDash` | `number[]` |  | Control line dash pattern (e.g., [5, 5] for dashed) |
| `clickDetectionRadius` | `number` |  | Maximum distance from control handle to detect click (in pixels) |
| `showControlLines` | `boolean` |  | Show control lines connecting anchors to control points |
| `symmetricControls` | `boolean` |  | Auto-generate symmetric control points (mirror on both sides) |

### `InteractionConfig`

Interaction configuration

```ts
interface InteractionConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `InteractionMode` |  | Interaction mode (direct, deliberate, smart) |
| `dragThreshold` | `number` |  | Movement threshold in screen pixels that separates a click from a drag. A pointer must travel farther than this from its down position before a gesture is treated as a drag (node move / marquee) rather than a click. This is what prevents a plain click from micro-jittering a node's position. Default: 4. |
| `portVisibility` | `PortVisibilityStrategy` |  | Port visibility strategy |
| `portHoverScaleFactor` | `number` |  | Port hover scale factor (e.g., 1.5 = 50% larger on hover) |
| `portDefaultRadius` | `number` |  | Port default radius in pixels |
| `snapToPortRadius` | `number` |  | Snap to port radius in pixels Connection will snap when mouse is within this distance |
| `showConnectionPreview` | `boolean` |  | Show connection preview line while dragging |
| `connectionLineStyle` | `ConnectionLineStyle` |  | Connection line style for preview |
| `enableLinkReconnection` | `boolean` |  | Enable link endpoint reconnection |
| `showLinkEndpointHandles` | `boolean` |  | Show endpoint handles on selected links |
| `enableSmartAutoConnect` | `boolean` |  | Enable smart mode nearest port auto-connect When enabled, dropping on node body connects to nearest port |
| `highlightValidTargets` | `boolean` |  | Highlight valid connection targets during drag |
| `animateConnectionPreview` | `boolean` |  | Show animated dots on connection preview |
| `enableWaypointEditing` | `boolean` |  | Enable waypoint editing on links Allow users to add/move/remove waypoints by clicking/dragging link paths |
| `showWaypointHandles` | `boolean` |  | Show waypoint handles on selected links |
| `waypointEditor?` | `WaypointEditorConfig` |  | Waypoint editor configuration |
| `enableControlPointEditing` | `boolean` |  | Enable control point editing on bezier curves Allow users to adjust bezier control points by dragging handles |
| `showControlPointHandles` | `boolean` |  | Show control point handles on selected bezier links |
| `controlPointEditor?` | `ControlPointEditorConfig` |  | Control point editor configuration |
| `enableGroupDrag` | `boolean` |  | (gap 1) — Drag a group's frame to move the whole subflow: the container and every member node (recursively through nested groups) translate by the same delta, committed as ONE undoable step. |
| `enableProximityConnect` | `boolean` |  | After a node drag, if one of its ports comes within `proximityConnectRadius` of a compatible port on another node, auto-create the link on drop (one undoable command). Drives the shipped `SnapController.findProximityConnection` from the LIVE drag path, not from host glue. Default false (opt-in). |
| `proximityConnectRadius` | `number` |  | (gap 2) — Auto-link radius in world units for {@link enableProximityConnect}. Defaults to `DEFAULT_SNAP_CONFIG`'s value when unset/0. |
| `enableHelperLines` | `boolean` |  | While dragging a single top-level node, snap it to sibling edge/centre alignments and equal spacing, and draw the guides as dashed overlay lines. The SnapController always could compute this; nothing drove it from a live drag until now. Default false (opt-in) so the stock drag feel is unchanged. |
| `enableGroupMembershipOnDrop` | `boolean` |  | T8/visio — Visio-style containment: dropping a node inside a container's frame REPARENTS it (and dropping it outside every container unembeds it), so it then moves with its container. |
| `enableInPlaceTextEdit` | `boolean` |  | T10/visio — double-click a node to edit its label in place. The editor (session + undoable commit) shipped in the renderer but was auto-wired ONLY in the Angular wrapper, so a vanilla / React / Vue embed got a `node:doubleclick` event and no caret. Default false (opt-in) so a host that already answers that event with its own editor keeps sole control. |
| `enableKeyboardNudge` | `boolean` |  | visio-depth — arrow keys NUDGE the selected node(s): 1 world unit per press, ×10 with Shift, committed through MoveNodeCommand so every nudge is undoable (and successive presses inside the CommandManager's merge window collapse to one undo entry). |
| `enableEasyConnect` | `boolean` |  | Make the whole node BODY a connection handle. A press on a node body (not over a specific port) starts a connection from the node's nearest/default port instead of a move. Default false (opt-in) so normal body-drag-to-move is preserved; when on, hold no modifier to connect and the configured {@link easyConnectModifier} (if any) still gates it. |
| `easyConnectModifier` | `'none' \| 'shift' \| 'alt' \| 'ctrl' \| 'meta'` |  | (gap 3) — Optional modifier that must be held for an easy-connect body press to start a connection (e.g. 'shift'). When 'none' (the default) any plain body press connects while {@link * enableEasyConnect} is on. Lets a host keep body-drag-to-move as the default gesture and gate connect behind a key. |

### `WaypointEditorConfig`

Waypoint editor configuration

```ts
interface WaypointEditorConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `snapToGrid` | `boolean` |  | Snap waypoints to grid |
| `gridSize` | `number` |  | Grid size for snapping (in pixels) |
| `removeOnDoubleClick` | `boolean` |  | Remove waypoint on double-click |
| `handleRadius` | `number` |  | Waypoint handle radius (in pixels) |
| `handleColor` | `string` |  | Waypoint handle color |
| `handleStrokeColor` | `string` |  | Waypoint handle stroke color |
| `minDistanceFromEndpoints` | `number` |  | Minimum distance from endpoints to add waypoint (in pixels) |
| `clickDetectionRadius` | `number` |  | Maximum distance from path to detect click (in pixels) |

## Enums

### `ConnectionLineStyle`

Connection line style for preview

```ts
enum ConnectionLineStyle
```

**Members**

- `STRAIGHT = 'straight'` — Straight line from port to mouse
- `BEZIER = 'bezier'` — Smooth bezier curve
- `STEP = 'step'` — Step function (orthogonal)

### `InteractionMode`

Interaction modes for node dragging and connection creation

```ts
enum InteractionMode
```

**Members**

- `DIRECT = 'direct'` — Direct Mode: Click+drag body=move immediately, drag port=connect
Fast workflow, industry standard
- `DELIBERATE = 'deliberate'` — Deliberate Mode: Must select node first, then drag to move
Safer workflow, prevents accidental moves
- `SMART = 'smart'` — Smart Mode (Visio-style): Hover reveals ports, intelligent auto-connect
Ports appear on hover, drop on body connects to nearest port

### `PortVisibilityStrategy`

Port visibility strategies

```ts
enum PortVisibilityStrategy
```

**Members**

- `ALWAYS = 'always'` — Ports always visible
Best for technical diagrams with few ports
- `ON_HOVER = 'on-hover'` — Ports visible only when hovering over node
Industry standard, reduces visual clutter
- `HIDDEN = 'hidden'` — Ports hidden - drag-to-connect disabled
For diagrams where connections are created programmatically

<!-- source: grafloria-engine-dsl.md -->

# Dsl

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-classes): 11 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-constants): 1 constants.
- [Enums](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-enums): 1 enums.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-functions): 33 functions.
- [Interfaces A–S](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-interfaces-a-s): 39 interfaces, `ASTNode` to `SubgraphNode`.
- [Interfaces S–U](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-interfaces-s-u): 7 interfaces, `SyncMetrics` to `UmlSpec`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-types): 22 types.
- [`DSL`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-dsl)
- [`LayoutApplicator`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-dsl-layoutapplicator)

<!-- source: grafloria-engine-dsl-classes.md -->

# Classes

Import these from `@grafloria/engine`.

## Classes

### `ASTTransformer`

```ts
class ASTTransformer
```

**Methods**

- `transform(ast: DiagramNode, options: TransformOptions = {}): DiagramModel` — Transform AST into DiagramModel
- `resetAutoPosition(startPosition: { x: number; y: number }): void` — Reset auto-positioning state

### `BidirectionalSync`

```ts
class BidirectionalSync
```

**Methods**

- `constructor(options: SyncOptions = {})`
- `initialize(diagram: DiagramModel, initialText?: string): void` — Initialize sync with diagram and initial text
- `onTextChange(newText: string): void` — Update text (called when user edits text)
- `markVisualEdit(): void` — Mark next changes as from visual editor
- `markTextEdit(): void` — Mark next changes as from text editor
- `getCurrentText(): string` — Get current text
- `getDiagram(): DiagramModel | undefined` — Get current diagram
- `getState(): Readonly<SyncState>` — Get sync state
- `onSync(callback: SyncCallback): () => void` — Add sync callback
- `pause(): void` — Pause sync
- `resume(): void` — Resume sync
- `forceSync(direction: 'text-to-visual' | 'visual-to-text'): void` — Force sync in specific direction
- `dispose(): void` — Dispose and cleanup

### `DiagramAnalyzer`

```ts
class DiagramAnalyzer
```

**Methods**

- `analyze(diagram: DiagramModel): DiagramAnalysis` — Analyze diagram structure

### `DSLFormatter`

```ts
class DSLFormatter
```

**Methods**

- `constructor(options: FormatterOptions = {})`
- `format(text: string): string` — Format DSL text
- `wrapLongLines(text: string): string` — Wrap long lines
- `normalizeWhitespace(text: string): string` — Normalize whitespace
- `removeComments(text: string): string` — Remove comments
- `addSectionHeaders(text: string): string` — Add section headers
- `prettyPrint(text: string, addHeaders: boolean = false): string` — Pretty print with all formatting options
- `minify(text: string): string` — Minify (remove all formatting)

### `DSLGenerator`

```ts
class DSLGenerator
```

**Methods**

- `constructor()`
- `generate(diagram: DiagramModel, options: GeneratorOptions = {}): string` — Generate DSL text from diagram

### `IntegratedSyncManager`

```ts
class IntegratedSyncManager
```

**Methods**

- `constructor(options: IntegratedSyncOptions = {})`
- `initialize(diagram: DiagramModel, initialText?: string): void` — Initialize with diagram and optional initial text
- `onTextEdit(newText: string): void` — Handle text editor changes
- `onVisualEdit(): void` — Handle visual editor changes
- `getText(): string` — Get current text
- `getDiagram(): DiagramModel | undefined` — Get current diagram
- `getStatus(): SyncStatus` — Get sync status
- `getMetrics(): SyncMetrics` — Get sync metrics
- `async applyLayout(presetId?: string): Promise<void>` — Apply layout to current diagram
- `suggestLayout(): LayoutSuggestion | null` — Get layout suggestion
- `onTextChange(callback: TextChangeCallback): () => void` — Subscribe to text changes
- `onDiagramChange(callback: DiagramChangeCallback): () => void` — Subscribe to diagram changes
- `onStatusChange(callback: StatusCallback): () => void` — Subscribe to status changes
- `pause(): void` — Pause sync
- `resume(): void` — Resume sync
- `forceSync(direction: 'text-to-visual' | 'visual-to-text'): void` — Force sync in specific direction
- `resetMetrics(): void` — Reset metrics
- `getFormattedStatus(): string` — Get formatted status string
- `getMetricsSummary(): string` — Get metrics summary
- `dispose(): void` — Dispose and cleanup

### `LayoutDetector`

```ts
class LayoutDetector
```

**Methods**

- `detect(diagram: DiagramModel, ast?: DiagramNode): LayoutSuggestion` — Detect optimal layout for a diagram

### `Lexer`

```ts
class Lexer
```

**Methods**

- `constructor(input: string)`
- `tokenize(): Token[]` — Tokenize the entire input

### `ParseError`

```ts
class ParseError extends Error
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `message` | `string` |  |  |
| `stack?` | `string` |  |  |

**Methods**

- `constructor( message: string, public token: Token, public line: number, public column: number )`

### `Parser`

```ts
class Parser
```

**Methods**

- `parse(tokens: Token[]): DiagramNode` — Parse tokens into an AST

### `SyncStateManager`

```ts
class SyncStateManager
```

**Methods**

- `startSync(direction: SyncDirection): void` — Mark sync as started
- `completeSync(direction: SyncDirection, duration: number): void` — Mark sync as completed
- `failSync(error: string): void` — Mark sync as failed
- `recordConflict( sources: [SyncDirection, SyncDirection], resolution: ConflictInfo['resolution'] ): void` — Record a conflict
- `getStatus(): Readonly<SyncStatus>` — Get current status
- `getMetrics(): Readonly<SyncMetrics>` — Get metrics
- `getConflicts(limit: number = 10): ConflictInfo[]` — Get recent conflicts
- `onStatusChange(callback: StatusChangeCallback): () => void` — Subscribe to status changes
- `resetMetrics(): void` — Reset metrics
- `getFormattedStatus(): string` — Get formatted status for display
- `getMetricsSummary(): string` — Get metrics summary

<!-- source: grafloria-engine-dsl-constants.md -->

# Constants

Import these from `@grafloria/engine`.

## Constants

### `ARCHITECTURE_ICONS`

Mermaid's built-in icons — drawn by Grafloria's own line icons.

```ts
const ARCHITECTURE_ICONS: readonly ["cloud", "database", "disk", "internet", "server"]
```

<!-- source: grafloria-engine-dsl-enums.md -->

# Enums

Import these from `@grafloria/engine`.

## Enums

### `TokenType`

Token Types for DSL Lexer

Defines all token types used in Mermaid-compatible diagram syntax

```ts
enum TokenType
```

**Members**

- `FLOWCHART = 'FLOWCHART'`
- `GRAPH = 'GRAPH'`
- `DIRECTION = 'DIRECTION'`
- `SUBGRAPH = 'SUBGRAPH'`
- `END = 'END'`
- `BPMN = 'BPMN'`
- `ERD = 'ERD'`
- `CLASSDIAAGRAM = 'CLASSDIAGRAM'`
- `TD = 'TD'`
- `TB = 'TB'`
- `BT = 'BT'`
- `RL = 'RL'`
- `LR = 'LR'`
- `SQUARE_OPEN = 'SQUARE_OPEN'`
- `SQUARE_CLOSE = 'SQUARE_CLOSE'`
- `ROUND_OPEN = 'ROUND_OPEN'`
- `ROUND_CLOSE = 'ROUND_CLOSE'`
- `STADIUM_OPEN = 'STADIUM_OPEN'`
- `STADIUM_CLOSE = 'STADIUM_CLOSE'`
- `SUBROUTINE_OPEN = 'SUBROUTINE_OPEN'`
- `SUBROUTINE_CLOSE = 'SUBROUTINE_CLOSE'`
- `CYLINDRICAL_OPEN = 'CYLINDRICAL_OPEN'`
- `CYLINDRICAL_CLOSE = 'CYLINDRICAL_CLOSE'`
- `CIRCLE_OPEN = 'CIRCLE_OPEN'`
- `CIRCLE_CLOSE = 'CIRCLE_CLOSE'`
- `ASYMMETRIC_OPEN = 'ASYMMETRIC_OPEN'`
- `ASYMMETRIC_CLOSE = 'ASYMMETRIC_CLOSE'`
- `RHOMBUS_OPEN = 'RHOMBUS_OPEN'`
- `RHOMBUS_CLOSE = 'RHOMBUS_CLOSE'`
- `HEXAGON_OPEN = 'HEXAGON_OPEN'`
- `HEXAGON_CLOSE = 'HEXAGON_CLOSE'`
- `TRAPEZOID_OPEN = 'TRAPEZOID_OPEN'`
- `TRAPEZOID_CLOSE = 'TRAPEZOID_CLOSE'`
- `ARROW = 'ARROW'`
- `LINE = 'LINE'`
- `DOTTED_ARROW = 'DOTTED_ARROW'`
- `DOTTED_LINE = 'DOTTED_LINE'`
- `THICK_ARROW = 'THICK_ARROW'`
- `THICK_LINE = 'THICK_LINE'`
- `BIDIRECTIONAL = 'BIDIRECTIONAL'`
- `CIRCLE_EDGE = 'CIRCLE_EDGE'`
- `CROSS_EDGE = 'CROSS_EDGE'`
- `IDENTIFIER = 'IDENTIFIER'`
- `STRING = 'STRING'`
- `NUMBER = 'NUMBER'`
- `COLON = 'COLON'`
- `TRIPLE_COLON = 'TRIPLE_COLON'`
- `SEMICOLON = 'SEMICOLON'`
- `COMMA = 'COMMA'`
- `PIPE = 'PIPE'`
- `AMPERSAND = 'AMPERSAND'`
- `AT = 'AT'`
- `NEWLINE = 'NEWLINE'`
- `WHITESPACE = 'WHITESPACE'`
- `COMMENT = 'COMMENT'`
- `EOF = 'EOF'`
- `UNKNOWN = 'UNKNOWN'`

<!-- source: grafloria-engine-dsl-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `applyArchitectureModel`

Put sides, arrows, icons, group frames and junctions on the model the flowchart pipeline built — and lay it out.

```ts
function applyArchitectureModel(diagram: DiagramModel, model: MermaidArchitectureModel): void
```

### `applyBlockGrid`

Put the grid on the model the flowchart pipeline built — `metadata.grid` on the
diagram and every nested block — mark it block-beta, and lay it out.

```ts
function applyBlockGrid(diagram: DiagramModel, model: MermaidBlockModel): void
```

### `architectureModelToFlowchart`

The same diagram as Grafloria flowchart text: a subgraph per group (nested), a node per service.

```ts
function architectureModelToFlowchart(model: MermaidArchitectureModel): string
```

### `blockModelToFlowchart`

The same diagram as Grafloria flowchart text: every block a node line, every nested block a subgraph.

```ts
function blockModelToFlowchart(model: MermaidBlockModel): string
```

### `classModelFromDiagram`

```ts
function classModelFromDiagram(diagram: DiagramModel): MermaidClassModel
```

### `classModelToDiagram`

```ts
function classModelToDiagram(model: MermaidClassModel): DiagramModel
```

### `createToken`

Helper to create tokens

```ts
function createToken(
  type: TokenType,
  value: string,
  line: number,
  column: number,
  startIndex: number,
  endIndex: number
): Token
```

### `erMarkers`

Map a parsed cardinality pair onto the kit's explicit marker pair.

```ts
function erMarkers(rel: MermaidErRelationship): { tail: ErCardinalityMarker; head: ErCardinalityMarker }
```

### `erModelFromDiagram`

Read the Mermaid ER model back off a DiagramModel (for generation).

```ts
function erModelFromDiagram(diagram: DiagramModel): MermaidErModel
```

### `erModelToDiagram`

Build a DiagramModel from a parsed ER model.

```ts
function erModelToDiagram(model: MermaidErModel): DiagramModel
```

### `erSpecFrom`

Project the Mermaid model onto the diagram kit's `erDiagram()` options.

```ts
function erSpecFrom(model: MermaidErModel): ErSpec
```

### `generateArchitectureFromDiagram`

Write an architecture-beta diagram back as architecture-beta: groups, services, junctions, sided edges.

```ts
function generateArchitectureFromDiagram(diagram: DiagramModel): string
```

### `generateBlockFromDiagram`

Write a block-beta diagram back as block-beta: its grid, its blocks as written, its edges and styles.

```ts
function generateBlockFromDiagram(diagram: DiagramModel): string
```

### `generateClassFromDiagram`

```ts
function generateClassFromDiagram(diagram: DiagramModel): string
```

### `generateErFromDiagram`

Generate an `erDiagram` body directly from a DiagramModel.

```ts
function generateErFromDiagram(diagram: DiagramModel): string
```

### `generateMermaidClass`

```ts
function generateMermaidClass(model: MermaidClassModel): string
```

### `generateMermaidEr`

Emit a valid Mermaid `erDiagram` body. Two rules here are not style choices —
both were found by running the export through real Mermaid 11.16 (the oracle):

- THE LABEL IS ALWAYS WRITTEN, AND ALWAYS QUOTED. It is not optional
   (`A ||--o{ B` is a parse error, so an unlabelled relationship needs `: ""`),
   and Mermaid's ER lexer treats `one`, `many`, `zero`, … as CARDINALITY
   keywords even in label position — `: one` fails, `: "one"` parses. Quoting
   unconditionally makes the whole reserved-word class disappear.
 - NO `id["alias"]` ENTITY ALIAS. We parse it (it is forward syntax), but
   Mermaid 11.16 rejects it, and emitting a body real Mermaid cannot read
   breaks the governing invariant. The display name rides in the `%%grafloria:`
   sidecar instead — Tier 3, exactly what it is for.

```ts
function generateMermaidEr(model: MermaidErModel): string
```

### `generateMermaidState`

Emit a valid `stateDiagram-v2` body. The scoped pseudo-states are collapsed
back to `[*]`, which is the only spelling Mermaid accepts — writing
`__start__` would export a body that renders as a real state called
"__start__", i.e. a different diagram.

```ts
function generateMermaidState(model: MermaidStateModel): string
```

### `generateStateFromDiagram`

```ts
function generateStateFromDiagram(diagram: DiagramModel): string
```

### `isClassDef`

```ts
function isClassDef(node: ASTNode): node is ClassDefNode
```

### `isEdgeDefinition`

```ts
function isEdgeDefinition(node: ASTNode): node is EdgeDefinitionNode
```

### `isNodeDefinition`

Type guard helpers

```ts
function isNodeDefinition(node: ASTNode): node is NodeDefinitionNode
```

### `isStyleNode`

```ts
function isStyleNode(node: ASTNode): node is StyleNode
```

### `isSubgraph`

```ts
function isSubgraph(node: ASTNode): node is SubgraphNode
```

### `parseMermaidArchitecture`

```ts
function parseMermaidArchitecture(text: string): MermaidArchitectureModel
```

### `parseMermaidBlock`

```ts
function parseMermaidBlock(text: string): MermaidBlockModel
```

### `parseMermaidClass`

Parse a `classDiagram` body. Unknown lines (`click`, `style`, `namespace`,
`callback`, future syntax) are skipped — never turned into a class.

```ts
function parseMermaidClass(text: string): MermaidClassModel
```

### `parseMermaidEr`

Parse an `erDiagram` body into the Mermaid-shaped model. Lines that are not
grammar (styling directives, future syntax) are SKIPPED, never nodified.

```ts
function parseMermaidEr(text: string): MermaidErModel
```

### `parseMermaidState`

Parse a state-diagram body. `stateDiagram` (v1) and `stateDiagram-v2` share
this grammar — v2 is a different LAYOUT engine in Mermaid, not a different
syntax, so refusing v1 would be arbitrary.

```ts
function parseMermaidState(text: string): MermaidStateModel
```

### `stateModelFromDiagram`

```ts
function stateModelFromDiagram(diagram: DiagramModel): MermaidStateModel
```

### `stateModelToDiagram`

```ts
function stateModelToDiagram(model: MermaidStateModel): DiagramModel
```

### `umlRelationKind`

Operator → (kit kind, whether the kit's ends are the REVERSE of Mermaid's),
derived from the grammar rather than enumerated. This reproduces the previous
17-row table exactly and covers the other 55 spellings for free.

```ts
function umlRelationKind(operator: string): { kind: UmlKind; reversed: boolean }
```

### `umlSpecFrom`

Project onto `umlDiagram()` options — this is where Mermaid's
arrowhead-first operators are flipped into the kit's from→to convention.

```ts
function umlSpecFrom(model: MermaidClassModel): UmlSpec
```

<!-- source: grafloria-engine-dsl-interfaces-a-s.md -->

# Interfaces A–S

Import these from `@grafloria/engine`.

## Interfaces

### `ASTNode`

Base AST Node

```ts
interface ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `location?` | `SourceLocation` |  |  |

### `ASTPosition`

```ts
interface Position
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `line` | `number` |  |  |
| `column` | `number` |  |  |
| `index` | `number` |  |  |

### `BlockGridSpec`

The grid a container carries for the architecture layout (`metadata.grid`).

```ts
interface BlockGridSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  |  |
| `cells` | `Array<{ id?: string; span: number }>` |  |  |

### `ClassDefNode`

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

Class definition: classDef className fill:#f9f

```ts
interface ClassDefNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'ClassDef'` |  |  |
| `className` | `string` |  |  |
| `properties` | `StyleProperties` |  |  |

### `ConflictInfo`

```ts
interface ConflictInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timestamp` | `Date` |  | Timestamp of conflict |
| `sources` | `[SyncDirection, SyncDirection]` |  | Conflicting edit sources |
| `resolution` | `'last-write-wins' \| 'user-choice' \| 'merge'` |  | Resolution strategy used |
| `resolved` | `boolean` |  | Was conflict resolved |

### `DiagramAnalysis`

```ts
interface DiagramAnalysis
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagramType` | `DiagramType` |  | Suggested diagram type |
| `direction` | `Direction` |  | Suggested direction |
| `nodeOrder` | `string[]` |  | Node ID to order mapping (for sequential output) |
| `nodeGroups` | `Map<string, string[]>` |  | Grouped nodes (for subgraphs) |
| `nodeMetadata` | `Map<string, { shape: string; hasCustomStyle: boolean; }>` |  | Node metadata |
| `linkMetadata` | `Map<string, { hasLabel: boolean; hasCustomStyle: boolean; }>` |  | Link metadata |
| `stats` | `{ nodeCount: number; linkCount: number; maxDepth: number; hasCycles: boolean; }` |  | Overall statistics |

### `DiagramCharacteristics`

```ts
interface DiagramCharacteristics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeCount` | `number` |  |  |
| `linkCount` | `number` |  |  |
| `hasCycles` | `boolean` |  |  |
| `maxDepth` | `number` |  |  |
| `averageDegree` | `number` |  |  |
| `maxDegree` | `number` |  |  |
| `isTree` | `boolean` |  |  |
| `isDAG` | `boolean` |  |  |
| `direction?` | `Direction` |  |  |
| `diagramType?` | `string` |  |  |

### `DiagramNode`

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

Root diagram node

```ts
interface DiagramNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Diagram'` |  |  |
| `diagramType` | `DiagramType` |  |  |
| `direction?` | `Direction` |  |  |
| `statements` | `StatementNode[]` |  |  |

### `DSLOptions`

```ts
interface DSLOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoLayout?` | `boolean` |  | Auto-apply layout after parsing |
| `transformOptions?` | `TransformOptions` |  | Transformation options |
| `debug?` | `boolean` |  | Enable debug logging |

### `EdgeDefinitionNode`

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

Edge/Link definition: A --> B

```ts
interface EdgeDefinitionNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'EdgeDefinition'` |  |  |
| `source` | `string` |  |  |
| `target` | `string` |  |  |
| `linkType` | `LinkType` |  |  |
| `label?` | `string` |  |  |
| `style?` | `StyleProperties` |  |  |
| `sourceShape?` | `NodeShape` |  | Source node shape if specified inline (e.g., A[Label] --> B) |
| `sourceLabel?` | `string` |  | Source node label if specified inline (e.g., A[Label] --> B) |
| `targetShape?` | `NodeShape` |  | Target node shape if specified inline (e.g., A --> B[Label]) |
| `targetLabel?` | `string` |  | Target node label if specified inline (e.g., A --> B[Label]) |

### `ErSpec`

```ts
interface ErSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `ErSpecEntity[]` |  |  |
| `relationships` | `ErSpecRelationship[]` |  |  |

### `FormatterOptions`

DSL Formatter - Formats DSL text for readability

Provides clean, consistent formatting for generated DSL text:
- Proper indentation
- Line wrapping
- Comment alignment
- Whitespace normalization

```ts
interface FormatterOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `indent?` | `string` |  | Indentation string (default: 2 spaces) |
| `maxLineLength?` | `number` |  | Maximum line length before wrapping |
| `preserveBlankLines?` | `boolean` |  | Preserve blank lines |
| `blankLineBeforeComments?` | `boolean` |  | Add blank line before comments |
| `alignComments?` | `boolean` |  | Align comments to column |

### `GeneratorOptions`

```ts
interface GeneratorOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeComments?` | `boolean` |  | Include comments in output |
| `includeStyles?` | `boolean` |  | Include style definitions |
| `format?` | `boolean` |  | Format output (uses DSLFormatter) |
| `preserveIds?` | `boolean` |  | Preserve node IDs from diagram |
| `includeSubgraphs?` | `boolean` |  | Generate subgraphs |
| `positions?` | `boolean` |  | Write `%%grafloria:at id x,y WxH` for every node and zone (see ExportTextOptions.positions). |

### `IntegratedSyncOptions`

```ts
interface IntegratedSyncOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `syncOptions?` | `SyncOptions` |  | Bidirectional sync options |
| `layoutOptions?` | `LayoutApplicatorOptions` |  | Layout applicator options |
| `autoLayoutOnTextChange?` | `boolean` |  | Enable auto-layout on text changes |
| `debug?` | `boolean` |  | Enable debug logging |

### `LayoutApplicationResult`

```ts
interface LayoutApplicationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `success` | `boolean` |  | Was layout applied successfully |
| `presetId?` | `string` |  | Layout preset that was applied |
| `confidence?` | `number` |  | Confidence of the layout selection |
| `reasoning?` | `string` |  | Reasoning for layout choice |
| `applyTime?` | `number` |  | Time taken to apply layout (ms) |
| `error?` | `string` |  | Error if layout failed |

### `LayoutApplicatorOptions`

```ts
interface LayoutApplicatorOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minConfidence?` | `number` |  | Minimum confidence threshold to auto-apply (0-1) |
| `debug?` | `boolean` |  | Enable debug logging |
| `customLayouts?` | `Map<string, LayoutConfiguration>` |  | Custom layout configurations |

### `LayoutSuggestion`

```ts
interface LayoutSuggestion
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `presetId` | `string` |  | Recommended layout preset ID |
| `confidence` | `number` |  | Confidence score (0-1) |
| `reasoning` | `string` |  | Reasoning for this suggestion |
| `alternatives?` | `string[]` |  | Alternative suggestions |

### `MermaidArchEdge`

```ts
interface MermaidArchEdge
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  |  |
| `fromSide` | `ArchSide` |  |  |
| `to` | `string` |  |  |
| `toSide` | `ArchSide` |  |  |
| `arrowFrom` | `boolean` |  |  |
| `arrowTo` | `boolean` |  |  |
| `label?` | `string` |  |  |
| `fromGroup?` | `boolean` |  | `{group}`: the line joins the GROUP the service is in, at its edge. |
| `toGroup?` | `boolean` |  |  |

### `MermaidArchGroup`

```ts
interface MermaidArchGroup
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `icon?` | `string` |  |  |
| `title?` | `string` |  |  |
| `parent?` | `string` |  |  |

### `MermaidArchitectureModel`

```ts
interface MermaidArchitectureModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` | `MermaidArchGroup[]` |  |  |
| `services` | `MermaidArchService[]` |  |  |
| `junctions` | `MermaidArchJunction[]` |  |  |
| `edges` | `MermaidArchEdge[]` |  |  |

### `MermaidArchJunction`

```ts
interface MermaidArchJunction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `parent?` | `string` |  |  |

### `MermaidBlockModel`

```ts
interface MermaidBlockModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Blocks to a row; undefined = `auto` (one row). |
| `cells` | `BlockCell[]` |  |  |
| `passthrough` | `string[]` |  | Lines the flowchart grammar reads as they are: edges, style, classDef, class, linkStyle, %%grafloria. |

### `MermaidClassDef`

```ts
interface MermaidClassDef
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  | Display name — `class Foo["Bar"]` label, else the id (generics included). |
| `stereotype?` | `string` |  | `<<interface>>` / `<<abstract>>` / `<<enum>>` / … |
| `generic?` | `string` |  | `class Square~Shape~` generic parameter. |
| `attributes` | `MermaidClassMember[]` |  |  |
| `methods` | `MermaidClassMember[]` |  |  |
| `cssClasses` | `string[]` |  | `:::css` style classes applied to the node. |

### `MermaidClassMember`

```ts
interface MermaidClassMember
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `raw` | `string` |  | The member exactly as written (minus the visibility marker's whitespace). |
| `visibility?` | `UmlVisibility` |  |  |
| `name` | `string` |  |  |
| `isMethod` | `boolean` |  |  |
| `classifier?` | `'$' \| '*'` |  | `$` (static) / `*` (abstract) classifier suffixes Mermaid supports. |

### `MermaidClassModel`

```ts
interface MermaidClassModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `MermaidClassDef[]` |  |  |
| `relationships` | `MermaidClassRelationship[]` |  |  |
| `direction?` | `string` |  |  |
| `notes` | `Array<{ for?: string; text: string }>` |  | `note "text"` / `note for X "text"` — kept so export does not drop them. |

### `MermaidClassRelationship`

```ts
interface MermaidClassRelationship
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  | Left operand, exactly as written. |
| `to` | `string` |  | Right operand, exactly as written. |
| `operator` | `UmlOperator` |  |  |
| `label?` | `string` |  |  |
| `multiplicity?` | `[string, string]` |  | Multiplicity as written: [left-of-operator, right-of-operator]. |

### `MermaidErAttribute`

```ts
interface MermaidErAttribute
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `name` | `string` |  |  |
| `keys` | `string[]` |  | PK / FK / UK, in source order. |
| `comment?` | `string` |  |  |

### `MermaidErEntity`

```ts
interface MermaidErEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The identifier used in relationships. |
| `name` | `string` |  | Display name — the `ENTITY["alias"]` alias when given, else the id. |
| `attributes` | `MermaidErAttribute[]` |  |  |

### `MermaidErModel`

```ts
interface MermaidErModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `MermaidErEntity[]` |  |  |
| `relationships` | `MermaidErRelationship[]` |  |  |
| `direction?` | `string` |  |  |

### `MermaidErRelationship`

```ts
interface MermaidErRelationship
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  | Left-hand entity id, exactly as written. |
| `to` | `string` |  | Right-hand entity id, exactly as written. |
| `left` | `ErLeftToken` |  |  |
| `right` | `ErRightToken` |  |  |
| `identifying` | `boolean` |  | `--` (identifying: the child cannot exist without the parent) vs `..` (non-identifying). Mermaid renders the latter dashed. |
| `label` | `string` |  |  |

### `MermaidStateModel`

```ts
interface MermaidStateModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `states` | `MermaidStateNode[]` |  |  |
| `transitions` | `MermaidStateTransition[]` |  |  |
| `direction?` | `string` |  |  |
| `notes` | `Array<{ position: string; target: string; text: string }>` |  |  |

### `MermaidStateNode`

```ts
interface MermaidStateNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |
| `kind` | `StateKind` |  |  |
| `parent?` | `string` |  | Composite parent id, when nested. For a region's children, the REGION id. |
| `composite?` | `boolean` |  | True when this state has its own `{ … }` body. |
| `concurrent?` | `boolean` |  | Composite whose body is split by `--` into concurrent regions. |
| `region?` | `boolean` |  | A synthetic orthogonal region of a `concurrent` composite. Not a state the author wrote — it exists so each region owns its own children and `[*]`, and it is re-emitted as a `--` separator, never as a nested state. |
| `direction?` | `string` |  | `direction` declared INSIDE this composite. Mermaid scopes it to the composite; hoisting it onto the diagram re-exported it at top level and silently re-oriented the WHOLE diagram. |
| `cssClass?` | `string` |  | The `:::cssClass` style hook, captured by NAME. Not applied and not re-emitted (state-level styling is an open gap), but it has to be parsed: `[*] --> A:::hot` used to read as a state `A` LABELLED `::hot`, and export then wrote `[*] --> A : ::hot` — a transition label the author never typed. |

### `MermaidStateTransition`

```ts
interface MermaidStateTransition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  |  |
| `to` | `string` |  |  |
| `label?` | `string` |  |  |

### `NodeDefinitionNode`

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

Node definition: A[Label]

```ts
interface NodeDefinitionNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'NodeDefinition'` |  |  |
| `id` | `string` |  |  |
| `label?` | `string` |  |  |
| `shape` | `NodeShape` |  |  |
| `style?` | `StyleProperties` |  |  |

### `ParseResult`

```ts
interface ParseResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `DiagramModel` |  | Generated diagram model |
| `ast` | `DiagramNode` |  | Abstract syntax tree |
| `tokens` | `Token[]` |  | Tokens from lexical analysis |
| `layoutSuggestion?` | `LayoutSuggestion` |  | Layout suggestion |
| `stats` | `{ nodeCount: number; linkCount: number; parseTime: number; }` |  | Parse statistics |

### `SourceLocation`

Source location in the original text

```ts
interface SourceLocation
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `Position` |  |  |
| `end` | `Position` |  |  |

### `StyleNode`

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

Style definition: style A fill:#f9f,stroke:#333

```ts
interface StyleNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Style'` |  |  |
| `targetId` | `string` |  |  |
| `properties` | `StyleProperties` |  |  |

### `StyleProperties`

Style properties

```ts
interface StyleProperties
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `color?` | `string` |  |  |

### `SubgraphNode`

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

Subgraph definition

```ts
interface SubgraphNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Subgraph'` |  |  |
| `id?` | `string` |  |  |
| `label?` | `string` |  |  |
| `direction?` | `Direction` |  |  |
| `statements` | `StatementNode[]` |  |  |

<!-- source: grafloria-engine-dsl-interfaces-s-u.md -->

# Interfaces S–U

Import these from `@grafloria/engine`.

## Interfaces

### `SyncMetrics`

```ts
interface SyncMetrics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `totalSyncs` | `number` |  | Total syncs performed |
| `textToVisual` | `number` |  | Text → Visual syncs |
| `visualToText` | `number` |  | Visual → Text syncs |
| `errors` | `number` |  | Sync errors |
| `conflicts` | `number` |  | Conflicts resolved |
| `averageSyncTime` | `number` |  | Average sync time (ms) |
| `sessionDuration` | `number` |  | Session duration (ms) |

### `SyncOptions`

```ts
interface SyncOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `debounceMs?` | `number` |  | Debounce delay in milliseconds (default: 300) |
| `debug?` | `boolean` |  | Enable debug logging |
| `autoLayout?` | `boolean` |  | Auto-apply layout after text changes |
| `generatorOptions?` | `GeneratorOptions` |  | Generator options for visual→text sync |
| `transformerOptions?` | `TransformOptions` |  | Transformer options for text→visual sync |

### `SyncState`

```ts
interface SyncState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  | Is sync currently active |
| `lastEditSource` | `EditSource` |  | Last edit source |
| `lastSyncDirection` | `SyncDirection` |  | Last sync direction |
| `syncing` | `boolean` |  | Sync in progress |
| `pendingCount` | `number` |  | Number of pending syncs |
| `stats` | `{ textToVisualCount: number; visualToTextCount: number; conflictsResolved: number; lastSyncTime: number; }` |  | Statistics |

### `SyncStatus`

```ts
interface SyncStatus
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `'idle' \| 'syncing' \| 'error' \| 'conflict'` |  | Current status |
| `message` | `string` |  | Status message |
| `lastSync?` | `Date` |  | Last sync timestamp |
| `lastSyncDuration?` | `number` |  | Last sync duration (ms) |
| `error?` | `string` |  | Error message if status is 'error' |

### `Token`

Represents a single token from the lexical analysis

```ts
interface Token
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `TokenType` |  |  |
| `value` | `string` |  |  |
| `line` | `number` |  |  |
| `column` | `number` |  |  |
| `startIndex` | `number` |  |  |
| `endIndex` | `number` |  |  |

### `TransformOptions`

```ts
interface TransformOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultNodeSize?` | `{ width: number; height: number }` |  | Default node size if not specified |
| `nodeSpacing?` | `number` |  | Spacing between auto-positioned nodes |
| `startPosition?` | `{ x: number; y: number }` |  | Starting position for auto-positioned nodes |
| `autoPosition?` | `boolean` |  | Auto-generate positions (true) or use default position for all (false) |
| `diagramName?` | `string` |  | Name for the generated diagram |

### `UmlSpec`

```ts
interface UmlSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `UmlSpecClass[]` |  |  |
| `relationships` | `UmlSpecRelationship[]` |  |  |

<!-- source: grafloria-engine-dsl-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `ArchSide`

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

```ts
type ArchSide = 'T' | 'B' | 'L' | 'R';
```

### `ASTDirection`

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

Abstract Syntax Tree (AST) Node Definitions

Represents the parsed structure of diagram DSL code

```ts
type Direction = 'TD' | 'TB' | 'BT' | 'RL' | 'LR';
```

### `BlockCell`

```ts
type BlockCell =

  | { kind: 'block'; id: string; token: string; span: number; raw?: string }
  | { kind: 'space'; span: number }

  | { kind: 'group'; id: string; span: number; columns?: number; cells: BlockCell[]; label?: string; labelToken?: string };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `'block'` |  |  |
| `span` | `number` |  |  |

### `DiagramChangeCallback`

```ts
type DiagramChangeCallback = (diagram: DiagramModel) => void;
```

### `DiagramType`

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

```ts
type DiagramType = 'flowchart' | 'bpmn' | 'erd' | 'classDiagram';
```

### `EditSource`

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

```ts
type EditSource = 'text' | 'visual' | 'none';
```

### `ErCardinalityMarker`

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

The renderer/kit marker vocabulary these tokens denote.

```ts
type ErCardinalityMarker = 'one' | 'zero-or-one' | 'zero-or-many' | 'one-or-many';
```

### `LinkType`

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

Link/Edge type mapping

```ts
type LinkType =
  | 'arrow'
  | 'line'
  | 'dotted-arrow'
  | 'dotted-line'
  | 'thick-arrow'
  | 'thick-line'
  | 'bidirectional'
  | 'circle-edge'
  | 'cross-edge';
```

### `MermaidArchService`

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

```ts
type MermaidArchService = MermaidArchGroup;
```

### `NodeShape`

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

Node shape type mapping to Mermaid syntax

```ts
type NodeShape =
  | 'text'
  | 'rectangle'
  | 'rounded-rectangle'
  | 'stadium'
  | 'subroutine'
  | 'cylindrical'
  | 'circle'
  | 'asymmetric'
  | 'rhombus'
  | 'hexagon'
  | 'trapezoid'
  | 'trapezoid-alt'
  | 'parallelogram'
  | 'parallelogram-alt';
```

### `StateKind`

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

```ts
type StateKind =
  | 'state' | 'start' | 'end' | 'choice' | 'fork' | 'join' | 'history' | 'deep-history';
```

### `StatementNode`

Also has every member of `NodeDefinitionNode`, `ASTNode`, listed on their own entries.

Statement types

```ts
type StatementNode =
  | NodeDefinitionNode
  | EdgeDefinitionNode
  | SubgraphNode
  | StyleNode
  | ClassDefNode
  | ClassApplicationNode
  | LinkStyleNode
  | ClickNode
  | GrafloriaDirectiveNode;
```

### `StatusCallback`

```ts
type StatusCallback = (status: SyncStatus) => void;
```

### `StatusChangeCallback`

```ts
type StatusChangeCallback = (status: SyncStatus) => void;
```

### `SyncCallback`

```ts
type SyncCallback = (direction: SyncDirection, success: boolean) => void;
```

### `SyncDirection`

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

```ts
type SyncDirection = 'text-to-visual' | 'visual-to-text' | 'none';
```

### `TextChangeCallback`

```ts
type TextChangeCallback = (text: string) => void;
```

### `UmlKind`

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

The diagram kit's relationship vocabulary.

```ts
type UmlKind =
  | 'inheritance' | 'realization' | 'association' | 'directed-association'
  | 'aggregation' | 'composition' | 'dependency';
```

### `UmlLeftMarker`

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

Mermaid's class relationship grammar is COMPOSITIONAL, not a fixed list:

relation := relationType? lineType relationType?

with `relationType` ∈ {`<|`/`|>` extension, `*` composition, `o` aggregation,
`<`/`>` dependency, `()` lollipop} and `lineType` ∈ {`--` solid, `..` dotted}. That is **72 legal spellings**, every one of which mermaid 11.16 accepts
(verified operator-by-operator against the real parser). The previous
hand-written table listed 17 of them, and a line using any of the other 55 —
`A <|--* B`, `A o--|> B`, the whole lollipop family — matched no rule at all,
so the line was skipped and BOTH classes vanished: an empty diagram, silently.

```ts
type UmlLeftMarker = '' | '<|' | '*' | 'o' | '<' | '()';
```

### `UmlLineType`

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

```ts
type UmlLineType = '--' | '..';
```

### `UmlOperator`

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

The literal Mermaid operator, kept so generation is not a guess.

```ts
type UmlOperator = `${UmlLeftMarker}${UmlLineType}${UmlRightMarker}`;
```

### `UmlRightMarker`

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

```ts
type UmlRightMarker = '' | '|>' | '*' | 'o' | '>' | '()';
```

<!-- source: grafloria-engine-dsl-dsl.md -->

# DSL

Import it from `@grafloria/engine`.

```ts
class DSL
```

**Methods**

- `constructor(options: DSLOptions = {})`
- `parse(text: string): DiagramModel` — Parse DSL text into a DiagramModel
- `parseDetailed(text: string): ParseResult` — Parse DSL text with detailed results
- `validate(text: string): { valid: boolean; errors: string[] }` — Validate DSL text without creating a diagram
- `suggestLayout(text: string): LayoutSuggestion | null` — Get layout suggestion for text without parsing fully
- `tokenize(text: string): Token[]` — Get token stream for debugging
- `parseToAST(text: string): DiagramNode` — Get AST for debugging
- `setOptions(options: Partial<DSLOptions>): void` — Set options
- `getOptions(): DSLOptions` — Get current options
- `generate(diagram: DiagramModel, options?: GeneratorOptions): string` — Generate DSL text from diagram
- `generateFormatted( diagram: DiagramModel, generatorOptions?: GeneratorOptions, formatterOptions?: FormatterOptions ): string` — Generate and format DSL text from diagram
- `generatePretty(diagram: DiagramModel, addHeaders: boolean = true): string` — Generate pretty-printed DSL text
- `format(text: string, options?: FormatterOptions): string` — Format DSL text
- `testRoundTrip(text: string): { success: boolean; originalNodes: number; originalLinks: number; regeneratedNodes: number; regeneratedLinks: number; generatedText: string; }` — Round-trip test: parse → generate → parse
Returns true if the round-trip preserves structure
- `parseERD(text: string): DiagramModel` — Parse ERD (Entity Relationship Diagram).
- `generateERD(diagram: DiagramModel): string` — Generate ERD DSL from diagram
- `parseBPMN(text: string): DiagramModel` — Parse BPMN (Business Process Model)
- `generateBPMN(diagram: DiagramModel): string` — Generate BPMN DSL from diagram
- `parseUML(text: string): DiagramModel` — Parse UML Class Diagram.

The scaffolding this replaces returned an EMPTY diagram for canonical
`classDiagram` input.
- `generateUML(diagram: DiagramModel): string` — Generate UML DSL from diagram

<!-- source: grafloria-engine-dsl-layoutapplicator.md -->

# LayoutApplicator

Import it from `@grafloria/engine`.

```ts
class LayoutApplicator
```

**Methods**

- `constructor(options: LayoutApplicatorOptions = {})`
- `async applyOptimalLayout( diagram: DiagramModel, ast?: DiagramNode ): Promise<LayoutApplicationResult>` — Detect and apply optimal layout
- `async applyLayoutPreset(diagram: DiagramModel, presetId: string): Promise<void>` — Apply a specific layout preset.

---------------------------------------------------------------------------
THIS METHOD DID NOTHING. THE ENTIRE PRESET LIBRARY WAS DEAD.
---------------------------------------------------------------------------

It used to build:

const config: LayoutConfiguration = {
      algorithm: preset.adapter === 'dagre' ? 'dagre' : 'elk',
      ...preset.options,           // rankdir, nodesep, 'elk.direction', …
    };
    await diagram.reLayout(config);

and every part of that was inert:

• `LayoutConfiguration` has no `algorithm` field at all. It has `type`, and
    the only legal values are 'grid' | 'force-directed' | 'hierarchical' |
    'hybrid' — 'dagre' and 'elk' are not among them.
  • `reLayout()` then OVERWRITES `type` with `this.currentAlgorithm.getType()`,
    the LayoutManager's single-node placement strategy. So the preset's chosen
    adapter was discarded before it was even mistyped.
  • `reLayout()` reads adapter options from `config.options` (nested). The
    preset's options were spread at the TOP level, so `rankdir`, `nodesep`,
    `ranker`, `elk.direction` — every knob the 17 presets exist to set — were
    never read by anything.

Net effect: "Org Chart (Compact)", "Workflow (Horizontal)" and
"Force-Directed (Tight)" all produced the SAME picture, whatever the
LayoutManager's current placement algorithm happened to be. The presets, the
detector that chooses between them, and the confidence threshold that gates
the choice were an elaborate no-op. This is the "config declared but never
consumed" shape, and it survived six waves because nothing tested it.
- `getLayoutRegistry(): LayoutRegistry` — The registry presets are applied through. Injectable, so a host that has
replaced a built-in layout (or registered its own) gets its version here too
rather than a second, private copy of the built-ins.
- `setLayoutRegistry(registry: LayoutRegistry): void`
- `async applyCustomLayout( diagram: DiagramModel, config: LayoutConfiguration ): Promise<LayoutApplicationResult>` — Apply layout with custom configuration
- `suggestLayout(diagram: DiagramModel, ast?: DiagramNode): LayoutSuggestion` — Get layout suggestion without applying
- `listPresets(): Array<{ id: string; name: string; category: string }>` — List all available presets
- `setMinConfidence(threshold: number): void` — Set minimum confidence threshold
- `addCustomLayout(id: string, config: LayoutConfiguration): void` — Add custom layout preset
- `removeCustomLayout(id: string): boolean` — Remove custom layout preset

<!-- source: grafloria-engine-engine.md -->

# Engine

Import these from `@grafloria/engine`.

## Functions

### `isValidDiagramMode`

Type guard to check if a string is a valid DiagramMode

```ts
function isValidDiagramMode(mode: string): mode is DiagramMode
```

## Classes

### `DiagramEngine`

```ts
class DiagramEngine
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `eventBus` | `EventBus` |  |  |
| `store` | `DiagramStore` |  |  |
| `commandManager` | `CommandManager` |  |  |
| `pluginManager` | `PluginManager` |  |  |
| `typeRegistry` | `TypeRegistry` |  |  |
| `validationEngine` | `ValidationEngine` |  |  |
| `serializer` | `DiagramSerializer` |  |  |
| `performanceMonitor` | `PerformanceMonitor` |  |  |
| `modeManager` | `ModeManager` |  |  |
| `clipboardManager` | `ClipboardManager` |  |  |
| `selectionManager` | `SelectionManager` |  |  |
| `routingEngine` | `RoutingEngine` |  |  |
| `templateRegistry` | `TemplateRegistry` |  |  |

**Methods**

- `constructor(config: DiagramEngineConfig = {})`
- `getDiagram(): DiagramModel | null` — Get current diagram
- `getConfig(): DiagramEngineConfig` — Get configuration
- `getInteractionConfig(): InteractionConfig` — Get interaction configuration
Returns the current interaction mode settings

A CACHED, FROZEN snapshot — not a fresh spread per call. This getter is on
the hottest paths in the product: the renderer consults it per port and per
link inside every frame, and the binder on every pointer event, so the old
`{ ...config }` allocated tens of thousands of full copies per second and
showed up as the single largest self-time in a 2,000-node drag profile
(~590ms of a 4.5s gesture — more than routing).

The spread existed to keep callers from mutating engine state; the freeze
keeps that promise the honest way. A caller that used to scribble on its
private copy now throws instead of silently diverging — which is the
correct outcome, because two callers sharing one snapshot must not see each
other's scribbles.
- `setInteractionConfig(config: Partial<InteractionConfig>): void` — Set interaction configuration
Updates interaction mode settings and emits event
- `getConnectionStateManager(): ConnectionStateManager` — Get connection state manager
Used for managing connection drag operations
- `getReconnectionPreview(): ReconnectionPreview | null` — Current endpoint-reconnection preview, or null when
no endpoint is being dragged. The renderer reads this to draw a ghost link.
- `setReconnectionPreview(preview: ReconnectionPreview | null): void` — Set (or clear, with null) the endpoint-reconnection
preview. Called by the interaction layer on start/move/end of an endpoint
drag. Does not emit — the interaction layer already triggers re-render.
- `getProximityPreview(): ProximityPreview | null` — The proximity-connect proposal the renderer draws as a live wire, or null.
- `setProximityPreview(preview: ProximityPreview | null): void` — Set (or clear, with null) the proximity-connect proposal. Does not emit —
the node drag that drives it already triggers re-renders.
- `getSnapGuides(): SnapGuideSegment[] | null` — The live snap-guide segments a node drag is showing, or null.
- `setSnapGuides(guides: SnapGuideSegment[] | null): void` — Set (or clear, with null) the live snap guides. Does not emit — the node
drag that drives them already triggers re-renders.
- `getRoutingEngine(): RoutingEngine` — Get routing engine
Used for calculating link paths with various algorithms
- `enableLiveRerouting(): void` — Enable live rerouting
Automatically updates link paths when nodes move or resize
- `disableLiveRerouting(): void` — Disable live rerouting
- `getLiveReroutingEngine(): LiveReroutingEngine | null` — Get live rerouting engine
- `setDiagram(diagram: DiagramModel | null): void` — Set diagram
- `createDiagram(name: string = 'Untitled'): DiagramModel` — Create new diagram
- `clearDiagram(): void` — Clear diagram
- `async addNode(config: { type: string; position: Point; size?: Size; data?: any; }): Promise<NodeModel>` — Add node (from config)
Add node (pre-created NodeModel)
Add node implementation
- `async addNode(node: NodeModel): Promise<NodeModel>` — Add node (from config)
Add node (pre-created NodeModel)
Add node implementation
- `async addNode(configOrNode: { type: string; position: Point; size?: Size; data?: any } | NodeModel): Promise<NodeModel>` — Add node (from config)
Add node (pre-created NodeModel)
Add node implementation
- `async removeNode(nodeId: string): Promise<void>` — Remove node

Async + awaited, mirroring removeGroup(). The execute() promise
used to float — a command failure became an unhandled rejection (fatal
under Node), and callers could not sequence on the removal completing.
- `async addLink(config: { sourcePortId: string; targetPortId: string; type?: string; data?: any; }): Promise<LinkModel>` — Add link
- `async removeLink(linkId: string): Promise<void>` — Remove link

Async + awaited, mirroring removeGroup() — see removeNode().
- `async addGroup(config: { name: string }): Promise<GroupModel>` — Add group
- `async removeGroup(groupId: string): Promise<void>` — Remove group
- `async addToGroup(groupId: string, entityId: string): Promise<void>` — Add entity to group
- `async removeFromGroup(groupId: string, entityId: string): Promise<void>` — Remove entity from group
- `async expandGroup(groupId: string): Promise<void>` — Expand group
- `async collapseGroup(groupId: string, options?: CollapseOptions): Promise<void>` — Collapse group
- `getGroup(groupId: string): GroupModel | undefined` — Get group by ID
- `getGroups(): GroupModel[]` — Get all groups
- `async setLayout( groupId: string, layoutType: 'flexbox' | 'grid', layoutConfig: LayoutConfig ): Promise<void>` — Set layout configuration on a group
- `async clearLayout(groupId: string): Promise<void>` — Clear layout configuration from a group
- `getLayout(groupId: string): { type: LayoutType; config?: LayoutConfig } | undefined` — Get layout configuration from a group
- `async setFlexItem(nodeId: string, flexConfig: FlexItemConfig): Promise<void>` — Set flex item configuration on a node
- `async setGridItem(nodeId: string, gridConfig: GridItemConfig): Promise<void>` — Set grid item configuration on a node
- `async copy(options?: { includeGroups?: boolean; includeLinks?: boolean }): Promise<void>` — Copy selected entities to clipboard
- `async paste(options?: { offset?: Point; selectPasted?: boolean }): Promise<void>` — Paste entities from clipboard
- `async duplicate(options?: { offset?: Point; selectDuplicated?: boolean }): Promise<void>` — Duplicate selected entities
- `async deleteSelection(options?: { deleteChildren?: boolean; deleteLinks?: boolean }): Promise<void>` — Delete selected entities
- `getClipboardData()` — Get clipboard data
- `hasClipboardData(): boolean` — Check if clipboard has data
- `clearClipboard(): void` — Clear clipboard
- `getClipboardStats()` — Get clipboard statistics
- `validateDiagram(options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult` — Validate the entire diagram
- `validateNode(nodeId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult` — Validate a specific node
- `validateLink(linkId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult` — Validate a specific link
- `validatePort(portId: string, nodeId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult` — Validate a specific port
- `validateLayout(groupId: string, options?: { strict?: boolean }): ValidationResult` — Validate layout configuration for a group
- `registerNodeType(definition: NodeTypeDefinition): void` — Register a node type definition
- `registerPortType(definition: PortTypeDefinition): void` — Register a port type definition
- `registerLinkType(definition: LinkTypeDefinition): void` — Register a link type definition
- `registerGroupType(definition: GroupTypeDefinition): void` — Register a group type definition
- `enableRealTimeValidation(): void` — Enable real-time validation
- `disableRealTimeValidation(): void` — Disable real-time validation
- `isRealTimeValidationEnabled(): boolean` — Check if real-time validation is enabled
- `selectNodes(nodeIds: string[]): void` — Select nodes
- `selectLinks(linkIds: string[]): void` — Select links
- `clearSelection(): void` — Clear selection
- `async undo(): Promise<void>` — Undo
- `async redo(): Promise<void>` — Redo
- `canUndo(): boolean` — Can undo
- `canRedo(): boolean` — Can redo
- `validate(): ValidationResult` — Validate diagram
- `serialize(): SerializedDiagram | null` — Serialize diagram (with mode)
- `deserialize(data: SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions): DiagramModel` — Deserialize diagram (with mode)
- `loadFromJSON( json: string | SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions ): DiagramModel` — Load diagram from JSON (with mode)
- `saveToJSON(): string | null` — Save diagram to JSON
- `async registerPlugin(plugin: Plugin): Promise<void>` — Register a plugin AND bring it to life.

`PluginManager.register()` only RECORDS a plugin; `install()` and
`activate()` are separate steps. Calling register alone — which both of
this engine's entry points used to do — left every plugin permanently
inert: its hooks never fired, though `getPlugin()` happily returned it.
"Register a plugin" can only sensibly mean "make it run", so this drives
the full lifecycle. A plugin that throws is reported and skipped rather
than taking the host down with it.
- `getPlugin(name: string): Plugin | undefined` — Get plugin
- `setViewport(viewport: Viewport): void` — Set viewport
- `setZoom(zoom: number): void` — Set zoom
- `getPerformanceReport(): PerformanceReport` — Get performance report
- `getMode(): DiagramMode` — Get current diagram mode
- `setMode(mode: DiagramMode): void` — Set diagram mode
- `isDesignerMode(): boolean` — Check if in designer mode
- `isRunningMode(): boolean` — Check if in running mode
- `isViewMode(): boolean` — Check if in view mode
- `isDebugMode(): boolean` — Check if in debug mode
- `isPresentationMode(): boolean` — Check if in presentation mode
- `isReadOnlyMode(): boolean` — Check if in read-only mode (any mode except designer)
- `addModeGuard(name: string, guard: ModeGuardFunction): void` — Add mode transition guard
- `removeModeGuard(name: string): void` — Remove mode transition guard
- `clearModeGuards(): void` — Clear all mode transition guards
- `configureModeViewport(mode: DiagramMode, settings: ModeViewportSettings): void` — Configure viewport settings for specific mode
- `getModeViewportSettings(mode: DiagramMode): ModeViewportSettings` — Get viewport settings for specific mode
- `getModeHistory(): ModeHistoryEntry[]` — Get mode history
- `clearModeHistory(): void` — Clear mode history
- `previousMode(): void` — Navigate to previous mode
- `nextMode(): void` — Navigate to next mode
- `pushMode(mode: DiagramMode): void` — Push mode onto stack (save current, switch to new)
- `popMode(): void` — Pop mode from stack (return to previous)
- `getModeAnalytics(): ModeAnalytics` — Get mode analytics
- `beforeModeChange(hook: ModeChangeHook): () => void` — Register before mode change hook
- `afterModeChange(hook: ModeChangeHook): () => void` — Register after mode change hook
- `getLinkBehaviorForMode(baseBehavior: Partial<{ deletable: boolean; selectable: boolean }>): { deletable: boolean; selectable: boolean; }` — Get link behavior adjusted for current mode
- `initialize(): void` — Initialize the engine
- `getStore(): DiagramStore` — Get the store
- `on(event: string, listener: (...args: any[]) => void): void` — Subscribe to events
- `off(event: string, listener: (...args: any[]) => void): void` — Unsubscribe from events
- `destroy(): void` — Destroy engine
- `refreshGroupObstacles(): void` — Reconcile the shared ObstacleMap with the
diagram's GROUP state, idempotently:

- a COLLAPSED group (with geometry) is ONE solid obstacle;
  - members hidden under a collapsed group (at any depth) are NOT obstacles
    — they are not visible, and routing around invisible things produces
    inexplicable detours;
  - expanding restores the members and removes the group block.

Runs on every group add/remove/collapse/expand. Public so the grouping
feature (which owns collapse SEMANTICS but not the ObstacleMap) can force a
reconcile after batch operations.
- `setLayoutService(service: { applyLayout(diagram: DiagramModel, config: any): Promise<any>; }): void` — Set layout service for diagram layouts
- `getLayoutRegistry(): LayoutRegistry` — The named-algorithm registry, with the built-ins already registered.

THE BUG THIS CLOSES: `applyLayout()` below requires `setLayoutService()` —
and NOTHING in the codebase ever called it (the only mention is a doc comment
in layout/index.ts). So dagre, ELK, force, spectral and community — thousands
of lines, several of them untested — were UNREACHABLE from the engine. That
is the whole "auto-layout is fragmented" finding. Layout now works out of the
box, with no setup call.
- `async layout( name: string = DEFAULT_LAYOUT_NAME, options: UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult>` — Lay out the whole diagram.

await engine.layout('dagre', { direction: 'LR' });

DETERMINISTIC and IDEMPOTENT: the same graph and seed produce byte-identical
coordinates, and running it twice changes nothing the second time. (The seed
defaults to a fixed constant, so an author who never thinks about seeds still
gets the same picture on every reload; randomness is opt-in.)

NOT to be confused with `DiagramModel.getLayoutManager()`, which answers a
DIFFERENT question — "where should this ONE newly-added node go?" — and is a
placement strategy, not a graph layout. The audit called them "two parallel
stacks" and asked for them to be merged; they are not parallel, and merging
them would force a single-node placer to pretend it can lay out a graph.
- `async layoutIncremental( options: IncrementalOptions & { name?: string } & UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult & { movement: MovementReport; tween: TweenPlan }>` — Mental-map-preserving incremental layout.

await engine.layoutIncremental({ changed: [newNode.id], budget: { maxPerNode: 60 } });

Mermaid re-renders the whole diagram from scratch on every edit and destroys the
user's spatial memory of their own diagram. This does the opposite:

Returns a tween PLAN rather than animating: the engine says where things go at
time t, the host drives t — which is what keeps this runnable in a worker, in
SSR and in a test.

ONE SEMANTIC, STATED PLAINLY. This runs the `layered` engine, because it is the
only one that honours anchors DURING coordinate assignment. If the diagram's
current positions came from a DIFFERENT engine, the first incremental pass
necessarily re-draws it — and that is not a bug to paper over: "move as little
as possible" is ill-posed across engines, because there is no meaningful small
move between two engines' idea of the same graph.
- `setLayoutPort(port?: LayoutPort): void` — Run layout off the main thread.

The engine does NOT construct the Worker — that would bake one bundler's URL
scheme into the engine, which is exactly what the old (never-instantiated)
`LayoutWorkerPool` did with its hardcoded `/assets/workers/layout.worker.js`. The caller builds the worker however its toolchain likes and hands it in:

const worker = new Worker(new URL('./layout.worker', import.meta.url),
                              { type: 'module' });
    engine.setLayoutPort(worker as unknown as LayoutPort);

Pass `undefined` to go back to running inline.
- `async applyLayout(config: { adapter: string | any; options?: any; animate?: boolean; animationDuration?: number; fit?: boolean; canvasDimensions?: { width: number; height: number }; }): Promise<{ nodePositions: Map<string, { x: number; y: number }>; bounds: { x: number; y: number; width: number; height: number }; metadata?: any; }>` — Apply layout to current diagram
- `async applyDagreLayout( options?: { rankdir?: 'TB' | 'BT' | 'LR' | 'RL'; align?: 'UL' | 'UR' | 'DL' | 'DR'; nodesep?: number; edgesep?: number; ranksep?: number; marginx?: number; marginy?: number; ranker?: 'network-simplex' | 'tight-tree' | 'longest-path'; }, canvasDimensions?: { width: number; height: number } ): Promise<any>` — Quick helper: Apply Dagre layout
- `async applyELKLayout( options?: { algorithm?: 'layered' | 'force' | 'stress' | 'mrtree' | 'radial' | 'disco'; 'elk.direction'?: 'RIGHT' | 'LEFT' | 'DOWN' | 'UP'; 'elk.spacing.nodeNode'?: number; [key: string]: any; }, canvasDimensions?: { width: number; height: number } ): Promise<any>` — Quick helper: Apply ELK layout
- `dispose(): void` — Cleanup and dispose of all resources
Should be called when the engine is no longer needed

## Interfaces

### `DiagramEngineConfig`

```ts
interface DiagramEngineConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `plugins?` | `Plugin[]` |  |  |
| `mode?` | `DiagramMode` |  |  |
| `performance?` | `{ enableMonitoring?: boolean; enableProfiling?: boolean; warnThreshold?: number; }` |  |  |
| `validation?` | `{ realTime?: boolean; strict?: boolean; }` |  |  |
| `history?` | `{ maxCommands?: number; maxSnapshots?: number; }` |  |  |
| `interaction?` | `Partial<InteractionConfig>` |  |  |

### `ModeChangeEvent`

Mode change event payload

```ts
interface ModeChangeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `previousMode` | `DiagramMode` |  |  |
| `currentMode` | `DiagramMode` |  |  |

### `ProximityPreview`

The port pair a proximity-connect DROP would link,
while a node drag is inside the radius. The renderer reads this to draw the
proposed wire itself — highlighting only the two ports left the proposal
nearly invisible (live report: "the wire isn't showing"). Same seam shape as
{@link ReconnectionPreview}: interaction layer writes, renderer reads,
cleared on drop/cancel.

```ts
interface ProximityPreview
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sourceNodeId` | `string` |  |  |
| `sourcePortId` | `string` |  |  |
| `targetNodeId` | `string` |  |  |
| `targetPortId` | `string` |  |  |

### `ReconnectionPreview`

Transient state for the endpoint-reconnection live
preview. Set by the interaction layer while an endpoint handle is being
dragged; read by the renderer to draw a ghost link from the stationary
endpoint to the cursor. Deliberately separate from {@link ConnectionStateManager}
(which owns NEW-link creation) so the two previews never double-render.

```ts
interface ReconnectionPreview
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `linkId` | `string` |  | Id of the link whose endpoint is being reconnected. |
| `endpoint` | `'source' \| 'target'` |  | Which endpoint the cursor is dragging (the OTHER end stays fixed). |
| `mousePoint` | `Point` |  | Current cursor position in world coordinates. |
| `isValid` | `boolean` |  | Whether the port/node currently under the cursor is a valid drop target. |

### `SnapGuideSegment`

One drawable snap-guide segment, in world coordinates. The interaction layer computes alignment / equal-spacing guides during a
node drag and publishes them here; the renderer draws them as dashed
overlay lines (spacing segments may carry a gap label). Cleared (null) when
the drag ends or nothing is within snapping distance.

```ts
interface SnapGuideSegment
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x1` | `number` |  |  |
| `y1` | `number` |  |  |
| `x2` | `number` |  |  |
| `y2` | `number` |  |  |
| `kind` | `'alignment' \| 'spacing'` |  |  |
| `label?` | `string` |  |  |

## Enums

### `DiagramMode`

Diagram mode enum - defines the operational mode of the diagram engine

```ts
enum DiagramMode
```

**Members**

- `DESIGNER = 'designer'` — Designer mode - Full editing capabilities (default)
- All node/link operations enabled
- Create, edit, delete, move, resize nodes
- Create and delete links
- `RUNNING = 'running'` — Running mode - Execution/simulation mode
- Editing disabled
- Nodes selectable for execution flow visualization
- No structural changes allowed
- `VIEW = 'view'` — View mode - Read-only viewing
- All editing disabled
- Nodes selectable for inspection
- Pure viewing experience
- `DEBUG = 'debug'` — Debug mode - Debugging mode
- Similar to running but with debug capabilities
- Breakpoints, step-through, inspection
- No structural changes allowed
- `PRESENTATION = 'presentation'` — Presentation mode - Clean presentation view
- All editing disabled
- Nodes selectable for navigation
- Clean UI without clutter

<!-- source: grafloria-engine-interaction.md -->

# Interaction

Import these from `@grafloria/engine`.

## Functions

### `areSiblingLanes`

True when `from` and `to` are two lanes of the same pool.

```ts
function areSiblingLanes(diagram: DiagramModel, from: GroupModel, to: GroupModel | undefined): boolean
```

### `clampBoxInto`

The top-left that keeps a `width`×`height` box inside `rect` while moving it
as little as possible. A box larger than the rect pins to its top-left.

```ts
function clampBoxInto(
  rect: GroupRect,
  x: number,
  y: number,
  width: number,
  height: number
): { x: number; y: number }
```

### `containingGroup`

The group that directly holds `nodeId` as a member, if any.

```ts
function containingGroup(diagram: DiagramModel, nodeId: string): GroupModel | undefined
```

### `laneAtPoint`

The lane whose band contains `point`, or undefined outside every lane.

```ts
function laneAtPoint(
  diagram: DiagramModel,
  pool: GroupModel,
  point: { x: number; y: number }
): GroupModel | undefined
```

### `lanesOfPool`

A pool's lanes in band order.

```ts
function lanesOfPool(diagram: DiagramModel, pool: GroupModel): GroupModel[]
```

### `matchesRule`

Evaluate a declarative rule against a node's `data`. Pure + serializable.

```ts
function matchesRule(rule: MembershipRule, node: NodeModel): boolean
```

### `memberConfinement`

The rectangle a dragged member must stay inside, or null when nothing
confines it. See the module note for the rule.

```ts
function memberConfinement(diagram: DiagramModel, nodeId: string): GroupRect | null
```

### `poolOfLane`

The pool a lane belongs to (its parent group with the pool role).

```ts
function poolOfLane(diagram: DiagramModel, lane: GroupModel): GroupModel | undefined
```

## Classes

### `GroupCollapseService`

```ts
class GroupCollapseService
```

**Methods**

- `constructor(private readonly diagram: DiagramModel)`
- `collapse(group: GroupModel, options?: CollapseOptions): void` — Collapse `group`: hide members, save layout, re-home boundary edges to an
aggregated proxy, and shrink the group to a placeholder. No-op if the group
is already collapsed. Members-less groups collapse "lightly" (flag only, no
placeholder) so trivial groups don't spawn stray nodes.
- `expand(group: GroupModel): void` — Expand `group` back to exactly its pre-collapse state using the snapshot on
the group. No-op if the group is not collapsed / has no snapshot.

### `GroupMembershipService`

```ts
class GroupMembershipService
```

**Methods**

- `constructor(options: GroupMembershipServiceOptions)`
- `refresh(): void` — Rebuild the spatial index from the diagram's current groups. Group counts
are small relative to nodes, so a full refresh per interaction is cheap and
always reflects freshly-dragged geometry.
- `hitTestGroup(point: Point, options?: HitTestOptions): GroupModel | undefined` — Hit-test a point against group rectangles using the spatial index and
return the innermost matching group (deepest nesting, then smallest area),
so a nested child wins over its parent. Returns undefined when the point is
outside every group.
- `getContainingGroup(entityId: string): GroupModel | undefined` — Return the first group that currently contains `entityId` as a direct
member, or undefined. (Membership check over the small group set — this is
not the spatial hit-test.)
- `updateHover(point: Point, options?: HitTestOptions): GroupModel | undefined` — Highlight the group under the cursor during a drag and clear any previously
hovered group. Returns the hovered group (or undefined). Drives the group's
'hover:changed' emitter so a renderer can outline the drop target.
- `clearHover(): void` — Clear any active hover highlight (call on drag-end / cancel).
- `planNodeDrop(nodeId: string, point: Point): DropResult` — Decide what a drop at `point` does to what contains `nodeId` — WITHOUT doing
it: the commands that leave the current group and/or join the one under the
point, in order. A host that records the drop as ONE undo step folds them
into the move's own command, runs it, then calls {@link finishDrop}. No
commands when the node stays where it is or the drop is vetoed (`rejected`:
a confining group, or the target's validation/cycle rules).
- `finishDrop(plan: DropResult): void` — After a planned drop's commands have run: refresh both groups' derived
bounds (one gained a member, one lost one) and clear the hover highlight.
- `async handleNodeDragEnd(nodeId: string, point: Point): Promise<DropResult>` — Handle a node drag-end at `point`: re-parent the node into the group under
the cursor, or unembed it when dropped outside every group. No-op when the
node is already in the target group. Rejected (no change) when the target
group's validation/cycle rules veto the node. Each command is dispatched on
its own — see {@link planNodeDrop} to record the drop as one step instead.

### `SemanticMembershipService`

```ts
class SemanticMembershipService
```

**Methods**

- `constructor(private readonly diagram: DiagramModel)`
- `register(group: GroupModel): () => void` — Start managing `group`'s auto-membership from its serialized
`membershipRule`. Runs an initial sweep and then keeps in sync reactively. No-op if the group has no rule. Returns a disposer that stops managing it.
- `dispose(): void` — Stop managing every group and detach all model listeners.
- `evaluateNode(node: NodeModel): void` — Re-evaluate a single node against every managed rule-group.
- `evaluateGroup(group: GroupModel): void` — Re-evaluate every node against one group's rule.

### `SwimlaneService`

```ts
class SwimlaneService
```

**Methods**

- `constructor(private readonly diagram: DiagramModel)`
- `createPool(options: CreatePoolOptions): Pool` — Create a pool group with N lane bands and tile them.
- `addLane(pool: GroupModel, spec: LaneSpec, atIndex?: number): GroupModel` — Add a lane to a pool (optionally at an index) and re-tile.
- `removeLane(pool: GroupModel, laneId: string): void` — Remove a lane from a pool and re-tile the survivors.
- `resizeLane(pool: GroupModel, laneId: string, crossSize: number): void` — Resize a lane along the cross axis by pinning its band (fixedSize) and
re-laying out the pool so siblings absorb the remaining space.
- `resizePool(pool: GroupModel, bounds: GroupRect): void` — Resize the whole pool and re-tile its lanes to the new frame.
- `getLanes(pool: GroupModel): GroupModel[]` — Lanes of a pool in band order.
- `isPool(group: GroupModel): boolean` — Is this group a pool?
- `isLane(group: GroupModel): boolean` — Is this group a lane?
- `reflow(pool: GroupModel): void` — Re-tile a pool's lanes into bands. fixedSize lanes take their pixel size;
the rest split the remaining cross-axis space by weight. Each lane frame is
set (drop-in hit-testing + drag constraints follow automatically).

## Constants

### `PROXY_LINK_GROUP_KEY`

Metadata key stamped on a re-homed proxy link.

```ts
const PROXY_LINK_GROUP_KEY: "__proxyForGroup"
```

### `PROXY_NODE_GROUP_KEY`

Metadata key stamped on a placeholder node so it can be recognised/filtered.

```ts
const PROXY_NODE_GROUP_KEY: "__collapsedGroupId"
```

## Interfaces

### `CollapseOptions`

```ts
interface CollapseOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `proxyLabel?` | `(info: ProxyLabelInfo) => string` |  | Label for each aggregated proxy link. Default: the aggregated edge count as a string when >1 (single crossings get no synthetic label). Return '' to suppress. |

### `CommandDispatcher`

Minimal command dispatcher contract (satisfied by CommandManager). Injecting
this keeps membership changes on the shared undo stack.

```ts
interface CommandDispatcher
```

**Members**

- `execute(command: Command): Promise<void> | void`

### `CreatePoolOptions`

```ts
interface CreatePoolOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  |  |
| `name` | `string` |  |  |
| `orientation` | `LaneOrientation` |  |  |
| `bounds` | `GroupRect` |  | Pool frame in world coords. |
| `lanes` | `LaneSpec[]` |  |  |
| `headerSize?` | `number` |  | Title-band thickness along the main-axis start (left for horizontal). |
| `laneHeaderSize?` | `number` |  | Reserve a header band inside each lane. Default 0. |

### `DropResult`

Outcome of a node drag-end reparent attempt.

```ts
interface DropResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `fromGroupId?` | `string` |  | Group the node left (if it was a member of one). |
| `toGroupId?` | `string` |  | Group the node joined (undefined when dropped outside all groups). |
| `commands` | `Command[]` |  | The membership commands, in order (empty when nothing changes). |
| `changed` | `boolean` |  | Whether membership actually changed. |
| `rejected` | `boolean` |  | A target group was under the cursor but rejected the node. |

### `GroupMembershipServiceOptions`

```ts
interface GroupMembershipServiceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `DiagramModel` |  |  |
| `dispatcher?` | `CommandDispatcher` |  | Dispatcher for undoable membership changes (typically a CommandManager). When omitted, commands are executed directly against the diagram (still correct, but not tracked for undo/redo). |
| `cellSize?` | `number` |  | Grid cell size for the group spatial index (default 100). |

### `HitTestOptions`

Options for a single hit-test.

```ts
interface HitTestOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `excludeGroupIds?` | `Set<string>` |  | Group ids to skip (e.g. the group being dragged + its descendants). |

### `LaneSpec`

```ts
interface LaneSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` |  | Optional explicit id (else generated). |
| `name` | `string` |  |  |
| `weight?` | `number` |  | Relative cross-axis size (default 1). |
| `fixedSize?` | `number` |  | Absolute cross-axis size (pins the band, overrides weight). |

### `Pool`

```ts
interface Pool
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pool` | `GroupModel` |  |  |
| `lanes` | `GroupModel[]` |  |  |

### `ProxyLabelInfo`

Info handed to a caller's proxy-label hook.

```ts
interface ProxyLabelInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `group` | `GroupModel` |  |  |
| `externalNodeId` | `string` |  |  |
| `direction` | `'out' \| 'in'` |  | 'out' = edges flow group→external; 'in' = external→group. |
| `count` | `number` |  | How many raw edges this proxy aggregates. |

## Types

### `LaneOrientation`

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

```ts
type LaneOrientation = 'horizontal' | 'vertical';
```

<!-- source: grafloria-engine-layout.md -->

# Layout

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-classes): 16 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-constants): 7 constants.
- [Functions A–S](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-functions-a-s): 43 functions, `analyseGraphShape` to `separateOverlappingNodes`.
- [Functions S–T](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-functions-s-t): 5 functions, `serializeGraph` to `treeLayout`.
- [Interfaces A–H](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-interfaces-a-h): 24 interfaces, `ApplyLayoutConfig` to `HybridOptions`.
- [Interfaces I–L](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-interfaces-i-l): 28 interfaces, `ILayoutAlgorithm` to `LayoutRoutingHints`.
- [Interfaces L–T](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-interfaces-l-t): 28 interfaces, `LayoutRun` to `TreeLayoutOptions`.
- [Interfaces U–U](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-interfaces-u-u): 1 interfaces, `UnifiedLayoutResult` to `UnifiedLayoutResult`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-types): 19 types.
- [`ELKLayoutOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-elklayoutoptions): ELK-specific layout options
- [`LayoutManager`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-layoutmanager): Layout Manager
- [`LayoutOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-layoutoptions): Base options for all layout adapters
- [`PortAwareLayoutManager`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-portawarelayoutmanager): Port-aware layout computation utilities
- [`SubgraphLayoutManager`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-subgraphlayoutmanager): Subgraph layout computation utilities
- [`UnifiedLayoutOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-layout-unifiedlayoutoptions): The one options schema. Adapter-specific knobs still ride in `options`, but

<!-- source: grafloria-engine-layout-classes.md -->

# Classes

Import these from `@grafloria/engine`.

## Classes

### `BaseLayoutAlgorithm`

Base abstract class for layout algorithms

Provides common functionality that all layout algorithms can use. Extend this class when implementing a new layout algorithm.

```ts
abstract class BaseLayoutAlgorithm implements ILayoutAlgorithm
```

**Methods**

- `constructor(config?: LayoutConfiguration)`
- `abstract getName(): string` — Get the name of the layout algorithm
- `abstract getType(): 'grid' | 'force-directed' | 'hierarchical' | 'hybrid'` — Get the type of the layout algorithm
- `abstract calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node

This is called when a node is added to the diagram. The algorithm should return a position that:
- Doesn't overlap with existing nodes
- Follows the layout strategy
- Fits within the viewport (or is close to existing content)
- `abstract reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram

This is called when the user explicitly requests a re-layout (e.g., clicks "Re-Arrange" button). The algorithm should calculate new positions for ALL nodes.
- `configure(config: LayoutConfiguration): void` — Configure the layout algorithm
- `getConfiguration(): LayoutConfiguration` — Get current configuration
- `canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Validate if this algorithm can be applied to the given diagram

For example:
- Hierarchical layout requires a DAG (no cycles)
- Force-directed works better with connected nodes

### `CommunityLayoutAdapter`

Community Detection Layout Adapter

Uses Louvain algorithm to detect communities and arranges them.

```ts
class CommunityLayoutAdapter implements LayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` |  | `'community'` | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Methods**

- `async apply( nodes: NodeModel[], links: LinkModel[], options: Partial<CommunityLayoutOptions> = {} ): Promise<LayoutResult>` — Apply community detection layout
- `async applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: any, layoutOptions?: Partial<CommunityLayoutOptions> ): Promise<LayoutResult & { incremental: any }>` — Apply incremental layout
- `validateOptions(options: Partial<CommunityLayoutOptions>): boolean` — Validate options

### `CompoundLayoutService`

```ts
class CompoundLayoutService
```

**Methods**

- `constructor( private readonly diagram: DiagramModel, private readonly options: CompoundLayoutOptions = {} )`
- `async layout(): Promise<CompoundLayoutResult>` — Run the compound layout over the whole diagram.

### `ConstraintManager`

Helper class for managing and applying layout constraints

```ts
class ConstraintManager
```

**Methods**

- `constructor(constraints?: LayoutConstraints)`
- `addConstraints(constraints: LayoutConstraints): void` — Add constraints to the manager
- `getConstraints(nodeId: string): NodeConstraint[]` — Get all constraints for a specific node
- `hasConstraints(nodeId: string): boolean` — Check if a node has any constraints
- `applyConstraints( nodeId: string, proposedPosition: Position, conflictResolution: 'priority' | 'first' | 'last' = 'priority' ): Position` — Apply constraints to a position, returning the constrained position
- `clear(): void` — Clear all constraints
- `removeConstraints(nodeId: string): void` — Remove constraints for a specific node
- `getConstrainedNodeCount(): number` — Get total number of constrained nodes
- `getConstrainedNodeIds(): string[]` — Get all constrained node IDs

### `DagreLayoutAdapter`

Dagre Layout Adapter

Provides hierarchical layout using the Dagre library. Converts between Grafloria's node/link model and Dagre's graph structure.

```ts
class DagreLayoutAdapter implements LayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` |  | `'dagre'` | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Methods**

- `async apply( nodes: NodeModel[], links: LinkModel[], options: Partial<DagreLayoutOptions> = {} ): Promise<LayoutResult>` — Apply Dagre layout to nodes and links
- `validateOptions(options: Partial<DagreLayoutOptions>): boolean` — Validate Dagre layout options
- `async applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: IncrementalLayoutOptions, layoutOptions?: Partial<DagreLayoutOptions> ): Promise<LayoutResult & { incremental: IncrementalLayoutResult }>` — Apply incremental layout - layout new nodes while preserving existing positions

### `EdgeBundlingManager`

Edge bundling computation utilities

```ts
class EdgeBundlingManager
```

**Methods**

- `static computeBundling( edges: EdgeInfo[], nodePositions: Map<string, Point2D>, portPositions: Map<string, Point2D>, options: EdgeBundlingOptions ): EdgeBundlingResult` (static) — Compute edge bundling for a set of edges

### `ELKLayoutAdapter`

ELK Layout Adapter

Provides advanced layout algorithms using the Eclipse Layout Kernel. Supports multiple algorithms with extensive configuration options.

```ts
class ELKLayoutAdapter implements LayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` |  | `'elk'` | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Methods**

- `async apply( nodes: NodeModel[], links: LinkModel[], options: Partial<ELKLayoutOptions> = {} ): Promise<LayoutResult>` — Apply ELK layout to nodes and links
- `validateOptions(options: Partial<ELKLayoutOptions>): boolean` — Validate ELK layout options
- `async applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: IncrementalLayoutOptions, layoutOptions?: Partial<ELKLayoutOptions> ): Promise<LayoutResult & { incremental: IncrementalLayoutResult }>` — Apply incremental layout - layout new nodes while preserving existing positions

### `ForceLayoutAdapter`

Force-Directed Layout Adapter

Implements Fruchterman-Reingold algorithm with Barnes-Hut optimization.

```ts
class ForceLayoutAdapter implements SteppableLayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` |  | `'force'` | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Methods**

- `createRun( nodes: NodeModel[], links: LinkModel[], options: Partial<ForceLayoutOptions> = {} ): LayoutRun` — The simulation, exposed one iteration at a time.

This is where the physics lives, and it is the ONLY place it lives: `apply()`
below is now just "drive this to convergence". Splitting the loop out (rather
than copying it into a worker-flavoured twin) is what keeps the off-thread
path honest — the worker and the main thread run the same arithmetic in the
same order, so they cannot drift.

Pure and synchronous: no clock, no DOM, and randomness only through the
seeded generator. Those three abstinences are the whole reason a worker run
and an inline run produce byte-identical coordinates.

`snapshot()` is meaningful after ANY number of steps, which is what makes a
cancelled force layout return the 200-iteration picture it already has
instead of throwing it away.
- `async apply( nodes: NodeModel[], links: LinkModel[], options: Partial<ForceLayoutOptions> = {} ): Promise<LayoutResult>` — Apply force-directed layout (run the simulation to convergence).
- `async applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: any, layoutOptions?: Partial<ForceLayoutOptions> ): Promise<LayoutResult & { incremental: any }>` — Apply incremental layout
- `validateOptions(options: Partial<ForceLayoutOptions>): boolean` — Validate options

### `IncrementalLayoutManager`

Helper class for managing incremental layouts

```ts
class IncrementalLayoutManager
```

**Methods**

- `static identifyNewNodes( nodes: NodeModel[], options: IncrementalLayoutOptions ): string[]` (static) — Identify new nodes that need to be laid out
- `static identifyExistingNodes( nodes: NodeModel[], newNodeIds: string[] ): string[]` (static) — Identify existing nodes that should be constrained
- `static generateConstraints( nodes: NodeModel[], options: IncrementalLayoutOptions ): LayoutConstraints` (static) — Generate constraints for incremental layout based on strategy
- `static calculateResult( nodes: NodeModel[], oldPositions: Map<string, { x: number; y: number }>, newNodeIds: string[], constraints: LayoutConstraints, strategy: IncrementalLayoutStrategy ): IncrementalLayoutResult` (static) — Calculate movement statistics after incremental layout

### `LayoutHistory`

Layout History Manager

Manages undo/redo stack for layout operations

```ts
class LayoutHistory
```

**Methods**

- `constructor(options: LayoutHistoryOptions = {})`
- `pushSnapshot( nodes: NodeModel[], description?: string, algorithm?: string, options?: any ): LayoutSnapshot` — Create and push a new snapshot
- `undo(): LayoutSnapshot | undefined` — Undo to previous snapshot
- `redo(): LayoutSnapshot | undefined` — Redo to next snapshot
- `canUndo(): boolean` — Check if undo is possible
- `canRedo(): boolean` — Check if redo is possible
- `getCurrentSnapshot(): LayoutSnapshot | undefined` — Get current snapshot
- `getAllSnapshots(): LayoutSnapshot[]` — Get all snapshots
- `getSnapshotById(id: string): LayoutSnapshot | undefined` — Get snapshot by ID
- `restoreSnapshot(id: string): LayoutSnapshot | undefined` — Restore a specific snapshot by ID
- `clear(): void` — Clear all history
- `size(): number` — Get history size
- `getCurrentIndex(): number` — Get current index in history
- `static applySnapshot(snapshot: LayoutSnapshot, nodes: NodeModel[]): number` (static) — Apply snapshot to nodes
- `exportToJSON(): string` — Export history to JSON
- `importFromJSON(json: string): boolean` — Import history from JSON
- `getStatistics(): { totalSnapshots: number; currentIndex: number; canUndo: boolean; canRedo: boolean; oldestTimestamp: number; newestTimestamp: number; averageInterval: number; }` — Get history statistics

### `LayoutHost`

The caller-side host.

Pass a real Worker (or anything satisfying `LayoutPort`) to run off-thread;
pass nothing to run inline on the same thread. Identical behaviour, no protocol
drift, because BOTH paths speak through `serveLayout`.

```ts
class LayoutHost
```

**Methods**

- `constructor(port?: LayoutPort, deps: ServeLayoutDeps = {})`
- `run( algorithm: string, graph: LayoutGraph, options: LayoutWireOptions = {}, runOptions: LayoutRunOptions = {} ): Promise<HostLayoutResult>`

### `LayoutPresets`

Predefined layout presets for common scenarios

```ts
class LayoutPresets
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `HIERARCHICAL` (static) | `LayoutPresetCategory` |  | Organizational/Hierarchical Layouts |
| `FLOW` (static) | `LayoutPresetCategory` |  | Process/Flow Layouts |
| `NETWORK` (static) | `LayoutPresetCategory` |  | Network/Graph Layouts |
| `ARCHITECTURE` (static) | `LayoutPresetCategory` |  | Architecture/System Layouts |
| `INTERACTIVE` (static) | `LayoutPresetCategory` |  | Interactive/Dashboard Layouts |

**Methods**

- `static getAllCategories(): LayoutPresetCategory[]` (static) — Get all preset categories
- `static getAllPresets(): LayoutPreset[]` (static) — Get all presets across all categories
- `static findPreset(id: string): LayoutPreset | undefined` (static) — Find preset by ID
- `static findPresetsByTag(tag: string): LayoutPreset[]` (static) — Find presets by tag
- `static findPresetsByAdapter(adapter: 'dagre' | 'elk'): LayoutPreset[]` (static) — Find presets by adapter type
- `static searchPresets(query: string): LayoutPreset[]` (static) — Search presets by name or description

### `LayoutQualityMetrics`

Layout Quality Metrics Calculator

```ts
class LayoutQualityMetrics
```

**Methods**

- `static assess( nodes: NodeModel[], links: LinkModel[], options: QualityAssessmentOptions = {} ): LayoutQualityResult` (static) — Assess the quality of a layout

### `LayoutRegistry`

The named-algorithm registry.

```ts
class LayoutRegistry
```

**Methods**

- `register(engine: RegisteredLayout): () => void`
- `get(name: string): RegisteredLayout | undefined`
- `has(name: string): boolean`
- `names(): string[]` — Registered names, sorted — a stable list is part of being deterministic.
- `adapters(): Record<string, LayoutAdapter>` — Name → adapter, for every registered engine that exposes one.

This is what nested (compound) layout resolves a container's algorithm
against — so `group.subgraphLayout = { algorithm: 'force' }` works, and so
does an algorithm an extension registered, rather than only the hard-coded
dagre|elk pair.

### `LayoutService`

Layout Service

Manages layout adapters and provides a unified API for applying layouts. Can be used as a singleton or instantiated per diagram.

```ts
class LayoutService
```

**Methods**

- `constructor()`
- `registerAdapter(adapter: LayoutAdapter): void` — Register a custom layout adapter
- `getAdapter(name: string): LayoutAdapter | undefined` — Get a registered adapter by name
- `getAdapterNames(): string[]` — Get all registered adapter names
- `async applyLayout(diagram: DiagramModel, config: ApplyLayoutConfig): Promise<LayoutResult>` — Apply layout to diagram

### `SpectralLayoutAdapter`

Spectral Layout Adapter

Uses eigendecomposition of graph Laplacian for optimal layout.

```ts
class SpectralLayoutAdapter implements LayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` |  | `'spectral'` | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Methods**

- `async apply( nodes: NodeModel[], links: LinkModel[], options: Partial<SpectralLayoutOptions> = {} ): Promise<LayoutResult>` — Apply spectral layout
- `async applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: any, layoutOptions?: Partial<SpectralLayoutOptions> ): Promise<LayoutResult & { incremental: any }>` — Apply incremental layout
- `validateOptions(options: Partial<SpectralLayoutOptions>): boolean` — Validate options

<!-- source: grafloria-engine-layout-constants.md -->

# Constants

Import these from `@grafloria/engine`.

## Constants

### `AUTO_LAYOUT_NAME`

The registered name of the auto-selecting layout.

```ts
const AUTO_LAYOUT_NAME: "auto"
```

### `BAKEOFF_NODE_LIMIT`

Above this many nodes the bake-off itself is the pathology: it runs EVERY
candidate engine on the full graph, so its runtime is the SUM of the field —
including whichever engine happens to hang at that scale (measured: 16s+ at
300 nodes, unbounded at 2,000). Past this limit the graph is classified
structurally and ONE engine is picked directly; the choice is still
deterministic and still explained in the selection report.

```ts
const BAKEOFF_NODE_LIMIT: 200
```

### `DEFAULT_LAYOUT_NAME`

The layout `engine.layout()` runs when the caller names none.

This is `'auto'`, not a fixed algorithm. A zero-config caller
gets a bake-off (see layout-auto-select.ts) rather than whichever algorithm
happened to be hard-coded, and can read back WHY it chose what it chose. Naming
it here rather than inline in DiagramEngine keeps the decision in one place —
a card that wants a different default (a Sugiyama, say) changes this constant
and nothing else.

```ts
const DEFAULT_LAYOUT_NAME: "auto"
```

### `DEFAULT_LAYOUT_SEED`

The seed used when a caller asks for a layout without naming one.

A FIXED default (not a time-derived one) is the whole point: an author who
never thinks about seeds still gets the same picture every time they open
their diagram. Randomness is opt-in, by passing a different seed.

```ts
const DEFAULT_LAYOUT_SEED: 24301
```

### `DEFAULT_NODE_HEIGHT`

```ts
const DEFAULT_NODE_HEIGHT: 50
```

### `DEFAULT_NODE_WIDTH`

Dagre's fallbacks, reused so every layout agrees on what an unsized node is.

```ts
const DEFAULT_NODE_WIDTH: 150
```

### `layoutService`

Singleton instance of LayoutService

Can be used across the application for convenience.

```ts
const layoutService: LayoutService
```

<!-- source: grafloria-engine-layout-functions-a-s.md -->

# Functions A–S

Import these from `@grafloria/engine`.

## Functions

### `analyseGraphShape`

```ts
function analyseGraphShape(nodes: NodeModel[], links: LinkModel[]): GraphShape
```

### `assessLabelClearance`

Would this layout's edge labels sit on top of a node?

Requirement 2 as a measurement. We are NOT placing labels here — the renderer's
edge optimizer does collision-aware placement at render time, and duplicating it
would be the exact mistake the card warns against. We ask the cheaper question a
LAYOUT can answer: if the label sat at its natural home (the midpoint of the
route the engine computed), would it land on a node? If yes, layout has not left
the optimizer enough room, and this layout is worse than one that did.

A layout with no labels is vacuously perfect.

```ts
function assessLabelClearance(
  nodes: NodeModel[],
  links: LinkModel[],
  result: LayoutResult
): LabelClearanceResult
```

### `assessPortRespect`

Does each edge actually leave (and enter) in the direction its port faces?

This is requirement 1 of the card as a measurement: "an edge leaving a `right`
port should not require the layout to place the target to the left". We check
the sign of the displacement along the port's facing axis. A right port whose
target sits to the left scores a violation.

Only AUTHOR-DECLARED ports are judged — the four auto-created default ports
carry no authorial intent, so an edge through them can go anywhere (see
port-label-bridge.ts). A graph with no declared ports is vacuously perfect,
which is the correct answer: there is nothing to respect.

```ts
function assessPortRespect(
  nodes: NodeModel[],
  links: LinkModel[],
  portInfos?: PortInfo[]
): PortRespectResult
```

### `autoSelectLayout`

Run the bake-off and keep the best layout.

IMPORTANT — this MUTATES node positions while it works: each candidate has to be
applied to the model before its quality can be measured (crossings are a
property of a drawn graph, not of a plan). The winner's positions are re-applied
at the end, so the model always lands on the layout we chose, never on the last
one we happened to try. `DiagramEngine.layout()` then commits them through
`setPosition()` as usual.

```ts
async function autoSelectLayout(
  diagram: DiagramModel,
  registry: LayoutRegistry,
  options: UnifiedLayoutOptions = {}
): Promise<AutoLayoutResult>
```

### `buildCandidates`

The candidate pool, in a FIXED order.

Auto-tuning lives here too: a candidate is an algorithm PLUS its knobs, so
`dagre TB` and `dagre LR` compete as separate candidates and the better
direction simply wins on score. That is the whole of "auto-tune" — no separate
tuning pass, just more candidates in the bake-off.

```ts
function buildCandidates(shape: GraphShape, registry: LayoutRegistry): LayoutCandidate[]
```

### `circularLayout`

Every node on one ring.

Nodes are ordered by a BFS from the lowest-id node rather than by id, because
a circle's readability is entirely about edge crossings and BFS order puts
neighbours next to each other. (Ordering by id would be equally deterministic
and much uglier — an arbitrary permutation guarantees chords across the whole
circle.)

The radius is derived from the nodes' own footprints, so a circular layout of
40 nodes does not stack them on top of each other the way a fixed radius does.

```ts
function circularLayout(
  nodes: NodeModel[],
  links: LinkModel[],
  options: CircularLayoutOptions = {}
): LayoutResult
```

### `countBends`

Total bend count across the routes the layout engine computed.

Bends are one of the four measures the card names, and they only became
measurable once the adapters stopped discarding their routing output. A layout
whose edges need fewer corners is easier to follow.

Returns undefined when the engine reported no routes — an ABSENT measurement,
not a zero. Scoring "0 bends" for an engine that simply never told us would
hand it a perfect score for saying nothing, which is how a metric quietly
becomes a lie.

```ts
function countBends(result: LayoutResult): number | undefined
```

### `createArchitectureLayout`

`architecture` — a composition, not a ranking: regions on a grid, boxes sized
to their words and aligned in rows, lines straight where boxes line up, bends
in the gutters. It writes sizes, zone frames, anchors and bends as well as
positions, so it runs inline (no adapter: nothing to ship to a worker) and
owns its containers.

```ts
function createArchitectureLayout(): RegisteredLayout
```

### `createAutoLayout`

The auto-selecting layout, as a registry engine.

It is registered under a name like any other layout — deliberately. It takes the registry
it lives in so its candidate pool is whatever is actually registered, including
layouts an extension host added after start-up.

```ts
function createAutoLayout(registry: LayoutRegistry): RegisteredLayout
```

### `createBuiltInLayoutAdapters`

The layouts that ship in the box.

ELK is included
even though it resolves asynchronously; the adapter already handles that.

```ts
function createBuiltInLayoutAdapters(): LayoutAdapter[]
```

### `createBuiltInLayoutFactories`

The same built-ins, as FACTORIES — construct one only when it is asked for.

It is a crash fix that
only a live run could have found. Constructing every adapter up-front means
constructing ELK, and `new ELKLayoutAdapter()` calls `new ElkConstructor()`,
which tries to spawn elkjs's OWN nested Worker. Inside a Web Worker that
throws `_Worker is not a constructor` — so the layout worker died on the line
that started it, before it had read a single message, and every request to it
hung forever.

Nothing caught it because in Node (where the unit tests live) elkjs constructs
happily. It reproduced the instant a real Worker ran in a real browser.

Laziness makes the worker pay only for the algorithm actually requested, so
asking for `force` no longer detonates on ELK's behalf.

```ts
function createBuiltInLayoutFactories(): Map<string, () => LayoutAdapter>
```

### `createDefaultLayoutRegistry`

The registry `engine.layout()` runs against.

Registration order is the override order, and it is deliberate:

`force` appears in
     both and the portfolio's wins, because it adds component packing and the
     shared options vocabulary: the difference between "we expose a force adapter"
     and "force is a first-class layout";
  3. LAYERED (Cards 1 & 5) — our own Sugiyama. The only engine that honours
     semantic constraints DURING ranking and ordering, which is why the
     mental-map/incremental path names it explicitly;
  4. AUTO — the scored bake-off. Registered last because it takes the
     registry, so its candidate pool is whatever is actually in it — including
     `layered`, and including anything an extension host adds after start-up.

```ts
function createDefaultLayoutRegistry(): LayoutRegistry
```

### `createLayout`

Turn a raw graph-layout function into a registered layout.

1. CANONICAL INPUT ORDER — sorted by id, so the same graph laid out
     after a save/load round-trip produces the same coordinates.
  2. COMPONENT PACKING — a disconnected graph is split, laid out
     component by component, and the boxes are packed. Implemented ONCE, here,
     rather than five times in five algorithms. It is a no-op for a connected
     graph, so it cannot regress an existing layout.

```ts
function createLayout(name: string, fn: GraphLayoutFn): RegisteredLayout
```

### `createLayoutRng`

mulberry32 — a small, fast, well-behaved 32-bit PRNG.

```ts
function createLayoutRng(seed: number = DEFAULT_LAYOUT_SEED): LayoutRng
```

### `createPortfolioLayouts`

```ts
function createPortfolioLayouts(): RegisteredLayout[]
```

### `declaredPorts`

Ports the author actually declared — the ones that may constrain a layout.

```ts
function declaredPorts(node: NodeModel): PortModel[]
```

### `deriveLabelBoxes`

Every label on a link, sized. Empty for the common unlabelled link.

```ts
function deriveLabelBoxes(link: LinkModel): LabelBox[]
```

### `derivePortInfos`

Only DECLARED ports are emitted (see the file header).

```ts
function derivePortInfos(nodes: NodeModel[]): PortInfo[]
```

### `estimateLabelBox`

The estimated content box of a single edge label, including its padding.

```ts
function estimateLabelBox(label: LinkLabel, linkId = ''): LabelBox
```

### `estimateLayering`

```ts
function estimateLayering(nodes: NodeModel[], links: LinkModel[]): LayeringEstimate
```

### `findConnectedComponents`

Split a graph into connected components.

Connectivity is UNDIRECTED — an edge joins its endpoints regardless of which
way it points. (A tree whose edges all point away from the root is still one
component; treating edges as directed would shatter it into leaves.)

Deterministic: nodes are visited in id order and each node's neighbours are
visited in id order, so the components — and the order they come back in —
depend only on the graph, never on insertion order.

```ts
function findConnectedComponents(
  nodes: readonly NodeModel[],
  links: readonly LinkModel[]
): GraphComponent[]
```

### `forceLayout`

```ts
function forceLayout(
  nodes: NodeModel[],
  links: LinkModel[],
  options: UnifiedLayoutOptions = {}
): Promise<LayoutResult>
```

### `fromAdapter`

Wrap a legacy `LayoutAdapter` (dagre/elk/force/spectral/community) as a
registry engine.

This is the adaptor that finally makes the orphaned stack reachable. It also
does the two things the old path never did:

1. CANONICAL INPUT ORDER — nodes and links are sorted by id before they
     reach the algorithm. A seeded PRNG alone does not give reproducibility:
     map iteration follows insertion order, so an authored diagram and the same
     diagram loaded from JSON feed the algorithm in different orders and
     diverge even with the same seed.

2. OPTION NORMALISATION — `direction`/`nodeSpacing`/`rankSpacing` are
     translated into whatever the adapter calls them.

```ts
function fromAdapter(adapter: LayoutAdapter): RegisteredLayout
```

### `gridLayout`

Row-major grid. Ignores links entirely — that is the point: a grid is what you
reach for when the edges are NOT the story (a palette of components, a set of
unconnected cards).

`direction` chooses the FILL ORDER of the same grid, not a different grid:
'TB' fills left-to-right then down, 'LR' fills top-to-bottom then across,
'BT'/'RL' mirror those.

```ts
function gridLayout(
  nodes: NodeModel[],
  _links: LinkModel[],
  options: GridLayoutPortfolioOptions = {}
): LayoutResult
```

### `hasDeclaredPorts`

Does this node carry author-declared ports? If not, layout may place it freely
and route through whichever of the four default sides suits the router.

```ts
function hasDeclaredPorts(node: NodeModel): boolean
```

### `inStableOrder`

Deterministic order for a set of entities.

The second half of reproducibility, and the half that is easy to forget: a
seeded PRNG only helps if the graph is CONSUMED in a stable order. Node maps
iterate in insertion order, which differs between an authored diagram and the
same diagram loaded from JSON — so two "identical" graphs could feed the same
seeded generator in different orders and still diverge.

Sorting by id makes the input canonical, which is what actually makes the
layout idempotent across a save/load round-trip.

```ts
function inStableOrder<T extends { id: string }>(items: readonly T[]): T[]
```

### `isDefaultPort`

Was this port invented by `NodeModel.initializeDefaultPorts()` rather than
declared by the author?

The model marks them (`setMetadata('default', true)`), which is the only
trustworthy signal — `explicitSide` is TRUE even for the default ports (they
are constructed with `side:`, and the PortModel constructor sets the flag), so
`explicitSide` cannot be used to tell an authored port from an invented one. That trap is exactly why this helper exists instead of an inline check.

```ts
function isDefaultPort(port: PortModel): boolean
```

### `isSteppable`

Can this adapter be pre-empted mid-run?

```ts
function isSteppable(
  adapter: LayoutAdapter
): adapter is SteppableLayoutAdapter
```

### `layoutArea`

The area of the layout's bounding box, in px². Smaller is tighter.

```ts
function layoutArea(result: LayoutResult): number
```

### `layoutWithComponentPacking`

Run a layout with component packing.

The wrapper every registered layout goes through. See the header: for a
CONNECTED graph this is a straight delegation (packing a single component is
the identity), so it cannot regress anything; for a disconnected one it is the
difference between a tidy row of trees and a pile.

```ts
async function layoutWithComponentPacking(
  name: string,
  fn: GraphLayoutFn,
  nodes: readonly NodeModel[],
  links: readonly LinkModel[],
  options: UnifiedLayoutOptions = {}
): Promise<LayoutResult>
```

### `linkLabelBox`

The single box that must fit on a link: the union of its labels' boxes.

```ts
function linkLabelBox(link: LinkModel): LabelBox | undefined
```

### `nodeSize`

A node's box, with the same defaults every layout in the portfolio uses.

```ts
function nodeSize(node: NodeModel): { width: number; height: number }
```

### `packAdapter`

Component-packing wrapper, preserving the algorithm underneath.

Object.create, not a spread: spreading a class instance copies only its OWN
properties, so `step()`/`snapshot()` — which live on the prototype — vanish,
`isSteppable()` goes false, and a long-running algorithm silently stops being
cancellable. Delegating through the prototype keeps it whole and overrides only
`apply`, which is the one thing packing needs to intercept.

```ts
function packAdapter(adapter: LayoutAdapter): LayoutAdapter
```

### `packBoxes`

Shelf packing, first-fit-decreasing-height.

Returns the top-left OFFSET for every box. Boxes are laid left-to-right into
a shelf; when the next box would overflow the target width a new shelf opens
below the tallest box on the current one.

```ts
function packBoxes(
  boxes: readonly PackBox[],
  options: PackingOptions = {}
): Map<string, { x: number; y: number }>
```

### `pickEngineForScale`

Pick the engine(s) for a graph too large to bake off, from its STRUCTURE.

Every branch below is backed by a measurement in layout-auto-select.perf.spec.ts
(times on the dev machine, generous CI caps in the spec):

tree            → portfolio `tree`: 19ms at n=2000 (vs dagre 702ms, layered 5.3s)
  DAG, narrow     → `layered`: 156ms at 900-mesh, 479ms at 2025-mesh,
                    132ms at a 2,000-deep chain — width is what hurts it, and
                    narrow ranks are exactly where dagre's depth pathology lives. DAG, wide+shallow → `dagre`: 1.3s at a 2,000-node sparse DAG whose ~1,000-wide
                    ranks are what kill layered. DAG, wide+deep  → `elk` layered: the moderate-everywhere engine.
  cyclic          → `force`: completes in well under a second at this scale;
                    hierarchical engines would first have to break the cycles.

Declared ports bump ELK (the only port-aware candidate) to the front for
hierarchical graphs — at this scale we cannot afford to MEASURE port respect
across a whole field, so we pick the engine built to honour it.

Returns undefined when none of the preferred engines is registered; the caller
then falls back to the (gated) bake-off rather than failing.

```ts
function pickEngineForScale(
  shape: GraphShape,
  nodes: NodeModel[],
  links: LinkModel[],
  registry: LayoutRegistry
): ScalePlan | undefined
```

### `pickRoot`

Choose the node a tree hangs from — or a radial layout centres on.

SOURCE FIRST (in-degree 0), hub second (highest degree).

hub → mid1 → leaf1, leaf2
    hub → mid2 → leaf3

the CEO ('hub') has degree 2 and the middle manager ('mid1') has degree 3. A
pure highest-degree rule centres the picture on the middle manager and hangs
the CEO off the side — the org chart drawn upside down. Sources win; the
degree rule is the fallback for a graph that HAS no source (a cycle, an
undirected network), which is exactly where "the hub" is the right answer.

Every tie breaks on the lowest id, so the root never depends on insertion order.

```ts
function pickRoot(
  ordered: readonly NodeModel[],
  inDegree: Map<string, number>,
  degree: Map<string, number>,
  rootId?: string
): string
```

### `radialLayout`

Concentric rings by BFS depth from a hub.

The wedge allocation is what makes it readable: each subtree gets an angular
slice PROPORTIONAL TO ITS LEAF COUNT, so a bushy branch is not crammed into the
same wedge as a single leaf. That is the classic radial-tree construction, and
it is crossing-free for trees.

Ring radii are grown to fit — a ring is pushed outward if the nodes on it would
not otherwise fit around its circumference, which is the failure mode of every
"radius = depth * constant" radial layout at depth 3 and beyond.

```ts
function radialLayout(
  nodes: NodeModel[],
  links: LinkModel[],
  options: RadialLayoutOptions = {}
): LayoutResult
```

### `removeOverlaps`

Separate overlapping nodes, in place, and return the corrected positions.

Deterministic: boxes are swept in (x, id) order, so the result is a pure
function of the input positions — never of a map's iteration order.

Returns the same Map instance for convenience.

```ts
function removeOverlaps(
  nodes: readonly NodeModel[],
  positions: Map<string, { x: number; y: number }>,
  options: OverlapRemovalOptions = {}
): Map<string, { x: number; y: number }>
```

### `reservedLabelSpace`

The space every labelled edge needs, as one summary — what a layout engine that
cannot take per-edge label boxes (force, spectral, …) uses to inflate its
spacing so labels have somewhere to live.

```ts
function reservedLabelSpace(links: LinkModel[]): { width: number; height: number }
```

### `resolvePortConstraint`

```ts
function resolvePortConstraint(
  node: NodeModel,
  mode: PortConstraintMode = 'auto'
): ElkPortConstraint
```

### `reviveGraph`

Rebuild live models from the wire format, on whichever thread we landed on.

The revived models are THROWAWAY: the algorithm mutates them, we read the
positions out of the result, and the engine commits those positions onto the
REAL nodes via `setPosition()` so the spatial index and the routing obstacle
map see the move. Nothing that happens to these copies escapes.

```ts
function reviveGraph(graph: LayoutGraph): {
  nodes: NodeModel[];
  links: LinkModel[];
}
```

### `runLayout`

Run a named layout against a diagram and COMMIT the result.

The single place positions are written back, shared by `DiagramEngine.layout()`
and by the preset applicator. `setPosition()` — never a raw write to
`node.position` — because the spatial index, the routing obstacle map and the
renderer all hang off the change event it emits.

```ts
async function runLayout(
  registry: LayoutRegistry,
  diagram: DiagramModel,
  name: string,
  options: UnifiedLayoutOptions = {}
): Promise<UnifiedLayoutResult>
```

### `separateOverlappingNodes`

THE OVERLAP PASS — one rule, one place, for every path that produces positions.

It lives outside the five algorithms for the same reason packing does: force and
community lay out DIMENSIONLESS POINTS and happily return boxes that intersect
(see overlap-removal.ts). For every layout that does not overlap — dagre, ELK,
tree, grid, circular, radial — it is a no-op, so it costs them one comparison
pass and nothing else.

WHY IT IS EXPORTED, which is the bug.

It used to be a closure inside `layoutWithComponentPacking`, reachable only from
`adapter.apply()`. But the layout HOST — the path `engine.layout()` actually
takes — does not call `apply()` for a steppable algorithm: it drives
`createRun()`/`step()`/`snapshot()` so the run can report progress and be
cancelled. `snapshot()` was returned RAW.

Force is the only steppable built-in. So the one algorithm that genuinely needs
overlap removal was the one algorithm that never got it, and
`engine.layout('force')` handed back overlapping node boxes — while every unit
test stayed green, because they all go through `apply()`.

A demo caught it in the first thirty seconds of being pointed at a real browser.

```ts
function separateOverlappingNodes(
  nodes: readonly NodeModel[],
  positions: Map<string, { x: number; y: number }>,
  options: UnifiedLayoutOptions = {}
): Map<string, { x: number; y: number }>
```

<!-- source: grafloria-engine-layout-functions-s-t.md -->

# Functions S–T

Import these from `@grafloria/engine`.

## Functions

### `serializeGraph`

Freeze a live graph into the wire format.

Emits nodes and links in CANONICAL (id-sorted) order — the same discipline
Established in `fromAdapter`. Determinism needs both halves: a seeded
PRNG *and* a stable input order.

```ts
function serializeGraph(nodes: NodeModel[], links: LinkModel[]): LayoutGraph
```

### `serveLayout`

Serve layout requests on a port. This IS the worker's message loop — call it
inside the worker script with `self`, or in a test with a fake port, or (see
`LayoutHost`) on the inline side of a loopback pair.

```ts
function serveLayout(port: LayoutServePort, deps: ServeLayoutDeps = {}): void
```

### `toElkPortSide`

```ts
function toElkPortSide(side: PortSide): ElkPortSide
```

### `translateOptions`

One vocabulary in, each engine's dialect out.

The adapters disagree about names for the same concept — dagre says `rankdir`,
`nodesep`, `ranksep`; ELK says `elk.direction` with words instead of letters.

Reusing this is what stops the nested
path from quietly forking the options schema.

```ts
function translateOptions(
  engine: string,
  options: UnifiedLayoutOptions
): Partial<LayoutOptions>
```

### `treeLayout`

Tree layout over one connected component.

Component packing (see component-packing.ts) is what turns this into a FOREST
layout: each tree is laid out here, alone, and the boxes are packed afterwards. That division is why a five-tree forest comes out as five tidy trees rather
than the pile dagre produces.

```ts
function treeLayout(
  nodes: NodeModel[],
  links: LinkModel[],
  options: TreeLayoutOptions = {}
): LayoutResult
```

<!-- source: grafloria-engine-layout-interfaces-a-h.md -->

# 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` |  |  |

<!-- source: grafloria-engine-layout-interfaces-i-l.md -->

# Interfaces I–L

Import these from `@grafloria/engine`.

## Interfaces

### `ILayoutAlgorithm`

```ts
interface ILayoutAlgorithm
```

**Members**

- `getName(): string` — Get the name of the layout algorithm
- `getType(): 'grid' | 'force-directed' | 'hierarchical' | 'hybrid'` — Get the type of the layout algorithm
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node

This is called when a node is added to the diagram. The algorithm should return a position that:
- Doesn't overlap with existing nodes
- Follows the layout strategy
- Fits within the viewport (or is close to existing content)
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram

This is called when the user explicitly requests a re-layout (e.g., clicks "Re-Arrange" button). The algorithm should calculate new positions for ALL nodes.
- `configure(config: LayoutConfiguration): void` — Configure the layout algorithm
- `getConfiguration(): LayoutConfiguration` — Get current configuration
- `canApply(diagram: DiagramModel): { valid: boolean; reason?: string }` — Validate if this algorithm can be applied to the given diagram

For example:
- Hierarchical layout requires a DAG (no cycles)
- Force-directed works better with connected nodes
- `onActivate?(): void` — Called when the algorithm is activated
Use this to initialize any state or caches
- `onDeactivate?(): void` — Called when the algorithm is deactivated
Use this to clean up state or caches

### `IncrementalLayoutOptions`

Options for incremental layout

```ts
interface IncrementalLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `strategy?` | `IncrementalLayoutStrategy` | `'pin-existing'` | Strategy to use for incremental layout |
| `newNodeIds?` | `string[]` |  | Nodes that are new (to be laid out) If not provided, nodes without valid positions are considered new |
| `anchorNodeIds?` | `string[]` |  | Anchor nodes that should never move (in addition to strategy constraints) These have highest priority |
| `maxShift?` | `number` |  | Maximum distance a non-anchor node can move (pixels) Only applies to 'minimal-shift' strategy |
| `proximityRadius?` | `number` | `200` | Radius around new nodes where existing nodes can be adjusted (pixels) Only applies to 'proximity-aware' strategy |
| `allowMinorAdjustments?` | `boolean` | `false` | Whether to allow slight adjustments to improve layout quality |
| `customConstraints?` | `LayoutConstraints` |  | Custom constraints to apply in addition to incremental constraints |

### `IncrementalLayoutResult`

Result of incremental layout operation

```ts
interface IncrementalLayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `movedNodeIds` | `string[]` |  | IDs of nodes that were moved during layout |
| `pinnedNodeIds` | `string[]` |  | IDs of nodes that were pinned/fixed |
| `newlyLaidOutNodeIds` | `string[]` |  | IDs of nodes that were newly laid out |
| `maxMovement` | `number` |  | Maximum distance any node moved (pixels) |
| `avgMovement` | `number` |  | Average distance nodes moved (pixels) |
| `strategy` | `IncrementalLayoutStrategy` |  | Strategy that was used |
| `autoConstraintCount` | `number` |  | Number of constraints that were auto-generated |

### `LabelBox`

The box an edge label needs. Layout's job is to reserve it; not to place it.

```ts
interface LabelBox
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The label this box belongs to. |
| `linkId` | `string` |  | The link the label rides on. |
| `text` | `string` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `LabelClearanceResult`

```ts
interface LabelClearanceResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `overlaps` | `number` |  | Label boxes that land on top of a node. |
| `judged` | `number` |  | Labelled links that could be judged. |
| `score` | `number` |  | 100 = no label box collides with any node. |
| `collidingLinks` | `string[]` |  | Which links' labels collided, for the report. |

### `LayeringEstimate`

Longest-path layering estimate for a DAG — the two numbers that predict which
hierarchical engine will choke (measured, not guessed; see the perf spec):

• dagre's pathology is DEPTH: a 2,000-rank chain never returns, while a
    2,000-node, ~1,000-wide tree takes ~700ms.
  • our layered (Sugiyama) engine's pathology is WIDTH: crossing minimisation
    over a ~1,000-node rank runs for tens of seconds, while a 45-wide,
    90-deep mesh takes ~480ms and a width-1, 2,000-deep chain ~130ms.

O(n + m) via Kahn's algorithm. Only meaningful when the graph is acyclic;
nodes left unranked by a cycle default to rank 0.

```ts
interface LayeringEstimate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `depth` | `number` |  | Number of layers a longest-path layering would produce. |
| `maxWidth` | `number` |  | Node count of the widest layer. |

### `LayoutAdapter`

Interface that all layout adapters must implement

```ts
interface LayoutAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Name of the layout adapter (e.g., 'dagre', 'elk') |

**Members**

- `apply( nodes: NodeModel[], links: LinkModel[], options?: Partial<LayoutOptions> ): Promise<LayoutResult>` — Apply layout to nodes and links
- `applyIncremental( nodes: NodeModel[], links: LinkModel[], incrementalOptions: IncrementalLayoutOptions, layoutOptions?: Partial<LayoutOptions> ): Promise<LayoutResult & { incremental: IncrementalLayoutResult }>` — Apply incremental layout - layout new nodes while preserving existing positions
- `validateOptions(options: Partial<LayoutOptions>): boolean` — Validate that options are valid for this adapter

### `LayoutCandidate`

```ts
interface LayoutCandidate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Registered layout name to run. |
| `options` | `UnifiedLayoutOptions` |  | Options to run it with. |
| `id` | `string` |  | A stable id for this candidate — name + tuning. Ties break on this. |
| `portAware` | `boolean` |  | Is this engine able to honour port sides? |

### `LayoutConfiguration`

Configuration for layout algorithms

```ts
interface LayoutConfiguration
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type?` | `LayoutAlgorithmType` |  | Algorithm type (optional when passed to reLayout, as it uses current algorithm) |
| `options?` | `GridLayoutOptions \| ForceDirectedOptions \| HierarchicalOptions \| HybridOptions` |  | Algorithm-specific options |
| `animate?` | `boolean` |  | Whether to animate layout changes |
| `animationDuration?` | `number` |  | Animation duration in ms |
| `viewport?` | `Rectangle` |  | Viewport for viewport-aware layout |
| `margins?` | `number` |  | Margins around content |
| `direction?` | `'TB' \| 'BT' \| 'LR' \| 'RL'` |  | Shorthand for hierarchical direction |

### `LayoutConstraints`

Collection of layout constraints to apply

```ts
interface LayoutConstraints
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `constraints` | `NodeConstraint[]` |  | Array of node constraints |
| `conflictResolution?` | `'priority' \| 'first' \| 'last'` |  | Strategy for handling conflicting constraints - 'priority': Use constraint priority to resolve conflicts - 'first': First constraint wins - 'last': Last constraint wins |

### `LayoutErrorMessage`

```ts
interface LayoutErrorMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'error'` |  |  |
| `message` | `string` |  |  |

### `LayoutGraph`

A whole graph, structured-clone-safe: no functions, no class instances.

```ts
interface LayoutGraph
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `LayoutGraphNode[]` |  |  |
| `links` | `LayoutGraphLink[]` |  |  |

### `LayoutGraphLink`

A link, as it crosses the boundary.

```ts
interface LayoutGraphLink
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `sourceNodeId?` | `string` |  |  |
| `targetNodeId?` | `string` |  |  |
| `sourcePortId?` | `string` |  |  |
| `targetPortId?` | `string` |  |  |

### `LayoutGraphNode`

A node, as it crosses the boundary: geometry + topology only.

```ts
interface LayoutGraphNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `string` |  |  |
| `position` | `{ x: number; y: number }` |  |  |
| `size` | `{ width: number; height: number }` |  |  |
| `parentId?` | `string` |  | Container membership — the nested-layout card needs it; harmless otherwise. |
| `positionMode?` | `'absolute' \| 'relative' \| 'layout'` |  | How `position` relates to the parent. Absent on pre-v3 payloads, which meant summation — i.e. 'relative'; the consumer below applies exactly that default. |
| `ports?` | `LayoutGraphPort[]` |  |  |

### `LayoutGraphPort`

A port, as it crosses the boundary. Ids are preserved — see above.

```ts
interface LayoutGraphPort
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `'input' \| 'output' \| 'bi'` |  |  |
| `side?` | `'left' \| 'right' \| 'top' \| 'bottom'` |  |  |
| `index?` | `number` |  | Order within a side — carried so multi-port sides revive in the same order. |
| `position?` | `{ x: number; y: number }` |  |  |

### `LayoutHistoryOptions`

Options for layout history management

```ts
interface LayoutHistoryOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `maxHistorySize?` | `number` |  | Maximum number of history entries to keep |
| `autoSnapshot?` | `boolean` |  | Whether to automatically create snapshots |
| `minSnapshotInterval?` | `number` |  | Minimum time between auto-snapshots (ms) |

### `LayoutPort`

The message-port surface the host needs — a real Worker satisfies it.

```ts
interface LayoutPort
```

**Properties**

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

**Members**

- `postMessage(msg: LayoutRequest): void`

### `LayoutPreset`

Layout preset configuration

```ts
interface LayoutPreset
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique identifier for the preset |
| `name` | `string` |  | Human-readable name |
| `description` | `string` |  | Description of when to use this preset |
| `adapter` | `'dagre' \| 'elk'` |  | Which adapter to use |
| `options` | `Partial<DagreLayoutOptions> \| Partial<ELKLayoutOptions>` |  | Layout options for the adapter |
| `constraints?` | `LayoutConstraints` |  | Optional pre-configured constraints |
| `incrementalOptions?` | `Partial<IncrementalLayoutOptions>` |  | Optional incremental layout settings |
| `tags?` | `string[]` |  | Tags for categorization |

### `LayoutPresetCategory`

Category of layout presets

```ts
interface LayoutPresetCategory
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Category name |
| `description` | `string` |  | Category description |
| `presets` | `LayoutPreset[]` |  | Presets in this category |

### `LayoutProgress`

```ts
interface LayoutProgress
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `progress` | `number` |  | 0..1. |
| `phase` | `string` |  |  |
| `iteration` | `number` |  |  |
| `totalIterations` | `number` |  |  |

### `LayoutProgressMessage`

```ts
interface LayoutProgressMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'progress'` |  |  |
| `progress` | `number` |  | 0..1. Monotonic. |
| `phase` | `string` |  |  |
| `iteration` | `number` |  |  |
| `totalIterations` | `number` |  |  |

### `LayoutQualityResult`

Overall layout quality assessment

```ts
interface LayoutQualityResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `overallScore` | `number` |  | Overall quality score (0-100) |
| `grade` | `'A' \| 'B' \| 'C' \| 'D' \| 'F'` |  | Quality grade (A, B, C, D, F) |
| `metrics` | `{ edgeCrossings: QualityMetric; nodeOverlap: QualityMetric; edgeLength: QualityMetric; nodeDistribution: QualityMetric; symmetry: QualityMetric; aspectRatio: QualityMetric; }` |  | Individual metrics |
| `topSuggestions` | `string[]` |  | Top suggestions for improvement |
| `timestamp` | `number` |  | Timestamp of assessment |

### `LayoutRequestCancel`

```ts
interface LayoutRequestCancel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'cancel'` |  |  |
| `target` | `number` |  | The seq of the run to cancel. |

### `LayoutRequestRun`

```ts
interface LayoutRequestRun
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'run'` |  |  |
| `algorithm` | `string` |  |  |
| `graph` | `LayoutGraph` |  |  |
| `options` | `LayoutWireOptions` |  |  |
| `timeBudgetMs?` | `number` |  | Stop and return the best-so-far once this many ms have elapsed. |
| `sliceMs?` | `number` |  | How long to compute before surrendering the thread so `cancel` can land. |
| `stopAfterIteration?` | `number` |  | Stop after exactly N iterations — a DETERMINISTIC pre-emption. |

### `LayoutResult`

Result of applying a layout algorithm

```ts
interface LayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `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 |
| `metadata?` | `{ algorithm: string; executionTime: number; [key: string]: any; }` |  | Additional metadata about the layout execution |
| `quality?` | `LayoutQualityResult` |  | Quality assessment of the layout (if calculateQuality was true) |
| `portAware?` | `PortAwareLayoutResult` |  | Port-aware layout result (if portAware was enabled) |
| `subgraph?` | `SubgraphLayoutResult` |  | Subgraph layout result (if subgraph was enabled) |
| `edgeBundling?` | `EdgeBundlingResult` |  | Edge bundling result (if edgeBundling was enabled) |
| `routing?` | `LayoutRoutingHints` |  | The port positions and edge routes the layout engine computed. Present when the engine produces them (ELK does); previously computed and discarded. |

### `LayoutResultMessage`

```ts
interface LayoutResultMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'result'` |  |  |
| `algorithm` | `string` |  |  |
| `positions` | `Array<[string, { x: number; y: number }]>` |  |  |
| `bounds` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `partial` | `boolean` |  | True when the run stopped early — the answer is the best-so-far, not the end. |
| `reason?` | `LayoutStopReason` |  |  |
| `iteration` | `number` |  |  |
| `totalIterations` | `number` |  |  |
| `metadata?` | `LayoutResult['metadata']` |  | Everything else the adapter reported, carried verbatim. |
| `quality?` | `LayoutResult['quality']` |  |  |
| `portAware?` | `LayoutResult['portAware']` |  |  |
| `subgraph?` | `LayoutResult['subgraph']` |  |  |
| `edgeBundling?` | `LayoutResult['edgeBundling']` |  |  |

### `LayoutRng`

A seeded, deterministic source of randomness.

```ts
interface LayoutRng
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seed` | `number` |  | The seed this generator was created with (so a result can report it). |

**Members**

- `next(): number` — Uniform in [0, 1).
- `between(min: number, max: number): number` — Uniform in [min, max).

### `LayoutRoutingHints`

What the layout engine worked out about EDGES and PORTS,
which until now was computed and then thrown in the bin.

ELK does genuine port-aware layered layout with orthogonal edge routing. The
old adapter read back `child.x` / `child.y` and NOTHING else — every port
position and every edge section ELK produced was discarded. These are those
results.

They are HINTS, deliberately. Layout's job
is to place nodes so a good route EXISTS and to say where it thinks that route
runs — not to draw it.

```ts
interface LayoutRoutingHints
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `portPositions` | `Map<string, { x: number; y: number; side: PortSide }>` |  | Absolute position of each declared port, as the layout engine placed it. |
| `edgeRoutes` | `Map<string, { start: Point; end: Point; bends: Point[] }>` |  | The route the layout engine found for each link: endpoints + bend points. |
| `labelSpace` | `Map<string, { width: number; height: number }>` |  | The box reserved for each labelled link (keyed by link id). |
| `orthogonal` | `boolean` |  | Whether the engine routed orthogonally. |

<!-- source: grafloria-engine-layout-interfaces-l-t.md -->

# 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 | Default | 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 | Default | Description |
| --- | --- | --- | --- |
| `chosen` | `string` |  | The candidate that won (its id, e.g. 'elk:layered:RIGHT'). |
| `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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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' }`. |

<!-- source: grafloria-engine-layout-interfaces-u-u.md -->

# Interfaces U–U

Import these from `@grafloria/engine`.

## Interfaces

### `UnifiedLayoutResult`

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

How a layout engine reports back.

```ts
interface UnifiedLayoutResult extends LayoutResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm` | `string` |  | The algorithm that actually ran. |
| `seed` | `number` |  | The seed used — so a pleasing random layout can be reproduced on demand. |
| `selection?` | `LayoutSelectionReport` |  | . Present when the AUTO layout ran: which algorithm it chose, why, and what every other candidate scored. An auto-selector that cannot show its working is a support ticket. |
| `partial` | `boolean` |  | True when the run was cut short (cancelled, or out of time budget) and this is the BEST-SO-FAR answer rather than a finished one. |
| `reason?` | `LayoutStopReason` |  | Why it stopped early, when it did. |
| `iteration` | `number` |  | Iterations actually completed. |
| `totalIterations` | `number` |  | Iterations the algorithm would have run, left alone. |

<!-- source: grafloria-engine-layout-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `CompoundAlgorithm`

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

Any registered layout name, or the built-in grid.

```ts
type CompoundAlgorithm = 'grid' | 'dagre' | 'elk' | (string & {});
```

### `ConstraintType`

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

Types of layout constraints that can be applied to nodes

```ts
type ConstraintType = 'pin' | 'fix-x' | 'fix-y' | 'boundary';
```

### `EdgeBundlingStrategy`

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

Bundling strategy

```ts
type EdgeBundlingStrategy = 'stub' | 'force-directed' | 'hierarchical' | 'none';
```

### `ELKAlgorithm`

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

ELK layout algorithms

```ts
type ELKAlgorithm =
  | 'layered'
  | 'force'
  | 'stress'
  | 'mrtree'
  | 'radial'
  | 'disco';
```

### `ElkPortConstraint`

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

```ts
type ElkPortConstraint = 'FREE' | 'FIXED_SIDE' | 'FIXED_ORDER' | 'FIXED_POS';
```

### `ElkPortSide`

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

ELK's compass vocabulary for a port side.

```ts
type ElkPortSide = 'NORTH' | 'EAST' | 'SOUTH' | 'WEST';
```

### `FlowDirection`

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

```ts
type FlowDirection = 'TB' | 'BT' | 'LR' | 'RL';
```

### `GraphLayoutFn`

The contract a layout must satisfy to be packable: nodes + links in, positions
out. Deliberately array-based (not DiagramModel-based) — a component is a
SUBSET of a diagram, and there is no such thing as a sub-DiagramModel.

```ts
type GraphLayoutFn = (
  nodes: NodeModel[],
  links: LinkModel[],
  options: UnifiedLayoutOptions
) => Promise<LayoutResult> | LayoutResult;
```

### `IncrementalLayoutStrategy`

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

Strategy for incremental layout

```ts
type IncrementalLayoutStrategy =
  | 'pin-existing'
  | 'fix-anchors'
  | 'proximity-aware'
  | 'minimal-shift';
```

### `LayoutAlgorithmType`

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

Layout algorithm types

```ts
type LayoutAlgorithmType = 'grid' | 'force-directed' | 'hierarchical' | 'hybrid';
```

### `LayoutEventType`

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

Layout event types

```ts
type LayoutEventType =
  | 'layout:started'
  | 'layout:completed'
  | 'layout:failed'
  | 'layout:algorithm-changed'
  | 'layout:node-placed';
```

### `LayoutMode`

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

Layout mode for automatic vs manual positioning

```ts
type LayoutMode = 'auto' | 'manual';
```

### `LayoutRequest`

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

```ts
type LayoutRequest = LayoutRequestRun | LayoutRequestCancel;
```

### `LayoutResponse`

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

```ts
type LayoutResponse =
  | LayoutProgressMessage
  | LayoutResultMessage
  | LayoutErrorMessage;
```

### `LayoutStopReason`

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

Why a run stopped early. Absent when it ran to completion.

```ts
type LayoutStopReason = 'cancelled' | 'timeout' | 'iteration-cap';
```

### `LayoutWireOptions`

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

Options as they cross the wire: the named ones, plus whatever adapter-specific
knobs the caller supplied (`iterations`, `repulsion`, `rankdir`, …). Anything
here must be structured-clone-safe — `stripNonClonable` enforces that at the
seam rather than trusting callers to.

```ts
type LayoutWireOptions = Partial<LayoutOptions> & Record<string, unknown>;
```

### `PortConstraintMode`

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

How much freedom does the layout engine have over this node's ports?

FREE        — no declared ports: put the edge wherever it routes best. FIXED_SIDE  — the author said which side; the engine may still reorder
                within that side to reduce crossings. FIXED_ORDER — side AND order are the author's. FIXED_POS   — the exact coordinates are the author's.

`'auto'` (the default) resolves per node: FIXED_SIDE when the node declares
ports, FREE when it does not. That is what makes port-awareness safe to leave
ON — it constrains only the nodes whose author asked for it.

```ts
type PortConstraintMode = 'auto' | 'free' | 'fixed-side' | 'fixed-order' | 'fixed-pos';
```

### `PortFlowDirection`

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

Port direction (input or output)

```ts
type PortFlowDirection = 'input' | 'output' | 'bidirectional';
```

### `PortSide`

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

Port side relative to node

```ts
type PortSide = 'left' | 'right' | 'top' | 'bottom';
```

<!-- source: grafloria-engine-layout-elklayoutoptions.md -->

# ELKLayoutOptions

Import it from `@grafloria/engine`.

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

ELK-specific layout options

```ts
interface ELKLayoutOptions extends LayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm` | `ELKAlgorithm` |  | ELK algorithm to use |
| `'elk.direction'?` | `'RIGHT' \| 'LEFT' \| 'DOWN' \| 'UP'` |  | Layout direction |
| `'elk.spacing.nodeNode'?` | `number` |  | Spacing between nodes |
| `'elk.spacing.edgeNode'?` | `number` |  | Spacing between edges and nodes |
| `'elk.spacing.edgeEdge'?` | `number` |  | Spacing between edges |
| `'elk.spacing.edgeLabel'?` | `number` |  | Spacing between an edge and its label |
| `'elk.layered.spacing.nodeNodeBetweenLayers'?` | `number` |  | Spacing between nodes in different layers |
| `'elk.layered.spacing.edgeNodeBetweenLayers'?` | `number` |  | Spacing between edges and nodes in different layers |
| `'elk.layered.nodePlacement.strategy'?` | `\| 'SIMPLE' \| 'INTERACTIVE' \| 'LINEAR_SEGMENTS' \| 'BRANDES_KOEPF' \| 'NETWORK_SIMPLEX'` |  | Node placement strategy for layered algorithm |
| `'elk.layered.crossingMinimization.strategy'?` | `'LAYER_SWEEP' \| 'INTERACTIVE'` |  | Crossing minimization strategy |
| `'elk.force.repulsion'?` | `number` |  | Repulsion force strength |
| `'elk.force.temperature'?` | `number` |  | Temperature for force algorithm |
| `'elk.force.iterations'?` | `number` |  | Number of iterations for force algorithm |
| `'elk.radial.radius'?` | `number` |  | Radius for radial layout |
| `'elk.radial.compaction'?` | `boolean` |  | Whether to compact radial layout |
| `hierarchyHandling?` | `'INCLUDE_CHILDREN' \| 'SEPARATE_CHILDREN'` |  | How to handle hierarchical graphs |
| `edgeRouting?` | `'ORTHOGONAL' \| 'POLYLINE' \| 'SPLINES'` |  | Edge routing style |
| `'elk.direction'?` | `'RIGHT' \| 'LEFT' \| 'DOWN' \| 'UP'` |  | Layout direction |
| `'elk.spacing.nodeNode'?` | `number` |  | Spacing between nodes |
| `'elk.spacing.edgeNode'?` | `number` |  | Spacing between edges and nodes |
| `'elk.spacing.edgeEdge'?` | `number` |  | Spacing between edges |
| `'elk.spacing.edgeLabel'?` | `number` |  | Spacing between an edge and its label |
| `'elk.layered.spacing.nodeNodeBetweenLayers'?` | `number` |  | Spacing between nodes in different layers |
| `'elk.layered.spacing.edgeNodeBetweenLayers'?` | `number` |  | Spacing between edges and nodes in different layers |
| `'elk.layered.nodePlacement.strategy'?` | `\| 'SIMPLE' \| 'INTERACTIVE' \| 'LINEAR_SEGMENTS' \| 'BRANDES_KOEPF' \| 'NETWORK_SIMPLEX'` |  | Node placement strategy for layered algorithm |
| `'elk.layered.crossingMinimization.strategy'?` | `'LAYER_SWEEP' \| 'INTERACTIVE'` |  | Crossing minimization strategy |
| `'elk.force.repulsion'?` | `number` |  | Repulsion force strength |
| `'elk.force.temperature'?` | `number` |  | Temperature for force algorithm |
| `'elk.force.iterations'?` | `number` |  | Number of iterations for force algorithm |
| `'elk.radial.radius'?` | `number` |  | Radius for radial layout |
| `'elk.radial.compaction'?` | `boolean` |  | Whether to compact radial layout |

<!-- source: grafloria-engine-layout-layoutmanager.md -->

# LayoutManager

Import it from `@grafloria/engine`.

Layout Manager

```ts
class LayoutManager
```

**Methods**

- `constructor(diagram: DiagramModel, initialAlgorithm: LayoutAlgorithmType = 'grid')`
- `registerAlgorithm(type: LayoutAlgorithmType, algorithm: ILayoutAlgorithm): void` — Register a layout algorithm
- `getAlgorithm(type: LayoutAlgorithmType): ILayoutAlgorithm | undefined` — Get registered algorithm
- `getAvailableAlgorithms(): LayoutAlgorithmType[]` — Get all registered algorithm types
- `setAlgorithm(type: LayoutAlgorithmType, config?: LayoutConfiguration): void` — Switch to a different layout algorithm
- `getCurrentAlgorithm(): ILayoutAlgorithm` — Get current layout algorithm
- `getCurrentAlgorithmType(): LayoutAlgorithmType` — Get current algorithm type
- `calculatePlacement( node: NodeModel, viewport: Rectangle, options?: Partial<PlacementOptions> ): PlacementResult` — Calculate placement for a new node
- `async reLayout(config?: LayoutConfiguration): Promise<void>` — Re-layout all nodes using current algorithm
Option 3: Supports animation and locked node constraints
- `selectOptimalPorts( sourceNode: NodeModel, targetNode: NodeModel, layoutContext?: { direction?: 'TB' | 'LR' | 'RL' | 'BT'; ranks?: Map<string, number>; } ): { sourcePort: any; targetPort: any } | undefined` — Select optimal ports based on layout-aware algorithm

Uses layout-aware analysis based on academic research:
- Considers layout direction (TB/LR/RL/BT)
- Classifies edges as forward/backward/cross relative to layout flow
- Uses hierarchical rank information when available
- Falls back to geometric analysis for non-hierarchical layouts

Algorithm based on "Drawing Layered Graphs with Port Constraints" (Spönemann et al., 2013)
- `optimizeConnections(layoutContext?: { direction?: 'TB' | 'LR' | 'RL' | 'BT'; ranks?: Map<string, number>; }): number` — Optimize all connections after layout

Reassigns ports for all links based on current node positions and layout context. This ensures connections look natural after layout algorithms reposition nodes.

Now public and layout-aware - uses hierarchical rank information when available
to apply academic research-based port assignment (Spönemann et al., 2013).
- `configure(config: LayoutConfiguration): void` — Configure current layout algorithm
- `getConfiguration(): LayoutConfiguration` — Get current configuration
- `on(eventType: string, callback: (event: DiagramLayoutEvent) => void): void` — Subscribe to layout events
- `off(eventType: string, callback: (event: DiagramLayoutEvent) => void): void` — Unsubscribe from layout events
- `dispose(): void` — Clean up resources

<!-- source: grafloria-engine-layout-layoutoptions.md -->

# LayoutOptions

Import it from `@grafloria/engine`.

Base options for all layout adapters

```ts
interface LayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seed?` | `number` |  | Seed for any algorithm that uses randomness (force, spectral, community). |
| `animate?` | `boolean` |  | Whether to animate to new positions |
| `animationDuration?` | `number` |  | Animation duration in milliseconds |
| `fit?` | `boolean` |  | Whether to fit viewport to content after layout |
| `padding?` | `number` |  | Padding around content when fitting |
| `constraints?` | `LayoutConstraints` |  | Layout constraints for pinning/fixing nodes |
| `calculateQuality?` | `boolean` |  | Whether to calculate quality metrics after layout |
| `canvasDimensions?` | `{ width: number; height: number }` |  | Canvas dimensions for quality assessment |
| `portAware?` | `PortAwareLayoutOptions` |  | Port-aware layout options |
| `subgraph?` | `SubgraphLayoutOptions` |  | Subgraph/group layout options |
| `edgeBundling?` | `EdgeBundlingOptions` |  | Edge bundling options |
| `portConstraints?` | `PortConstraintMode` |  | How much freedom the layout engine has over declared ports. `'auto'` (default): FIXED_SIDE for nodes with author-declared ports, FREE for the rest. So an edge leaving a `right` port will not force the layout to put the target on the left. |
| `labelAware?` | `boolean` |  | Reserve space for edge labels at LAYOUT time (default true). |
| `orthogonalRouting?` | `boolean` |  | Ask the layout engine for orthogonal edge routes (default true for ELK). |

<!-- source: grafloria-engine-layout-portawarelayoutmanager.md -->

# PortAwareLayoutManager

Import it from `@grafloria/engine`.

Port-aware layout computation utilities

```ts
class PortAwareLayoutManager
```

**Methods**

- `static assignPortSides( ports: PortInfo[], nodePositions: Map<string, { x: number; y: number }>, options: PortAwareLayoutOptions ): Map<string, PortSide>` (static) — Assign ports to sides of their parent nodes
- `static orderPorts( ports: PortInfo[], portAssignments: Map<string, PortSide>, nodePositions: Map<string, { x: number; y: number }>, links: Array<{ sourcePortId?: string; targetPortId?: string }>, options: PortAwareLayoutOptions ): Map<string, string[]>` (static) — Order ports on each node to minimize edge crossings
- `static calculatePortPositions( ports: PortInfo[], portAssignments: Map<string, PortSide>, portOrdering: Map<string, string[]>, nodeSizes: Map<string, { width: number; height: number }>, options: PortAwareLayoutOptions ): Map<string, { x: number; y: number; side: PortSide }>` (static) — Calculate physical port positions on nodes
- `static countEdgeCrossings( portPositions: Map<string, { x: number; y: number; side: PortSide }>, nodePositions: Map<string, { x: number; y: number }>, links: Array<{ sourcePortId?: string; targetPortId?: string }>, ports?: PortInfo[] ): number` (static) — Count edge crossings for a given port configuration.

`ports` is what makes the fix possible: it maps a port back to its node, so
the port's offset can be added to the node's origin. It is optional only for
source compatibility — without it we cannot resolve the frame, so we fall back
to the relative comparison rather than silently inventing a node position.
- `static computePortLayout( ports: PortInfo[], nodePositions: Map<string, { x: number; y: number }>, nodeSizes: Map<string, { width: number; height: number }>, links: Array<{ sourcePortId?: string; targetPortId?: string }>, options: PortAwareLayoutOptions ): PortAwareLayoutResult` (static) — Generate complete port-aware layout result

<!-- source: grafloria-engine-layout-subgraphlayoutmanager.md -->

# SubgraphLayoutManager

Import it from `@grafloria/engine`.

Subgraph layout computation utilities

```ts
class SubgraphLayoutManager
```

**Methods**

- `static buildGroupTree(groups: GroupInfo[]): GroupTreeNode[]` (static) — Build hierarchical tree of groups
- `static getGroupsAtDepth(roots: GroupTreeNode[], depth: number): GroupInfo[]` (static) — Get all groups at a specific depth level
- `static getMaxDepth(roots: GroupTreeNode[]): number` (static) — Get maximum depth of group tree
- `static getNodesInGroup( groupId: string, group: GroupInfo, allNodes: Array<{ id: string; [key: string]: any }>, options: SubgraphLayoutOptions ): Array<{ id: string; [key: string]: any }>` (static) — Filter nodes by group membership
- `static getLinksInGroup( group: GroupInfo, allLinks: Array<{ sourceNodeId: string; targetNodeId: string; [key: string]: any }>, options: SubgraphLayoutOptions ): Array<{ sourceNodeId: string; targetNodeId: string; [key: string]: any }>` (static) — Filter links within a group
- `static calculateGroupSize( group: GroupInfo, nodePositions: Map<string, { x: number; y: number }>, nodeSizes: Map<string, { width: number; height: number }>, options: SubgraphLayoutOptions ): { width: number; height: number }` (static) — Calculate group size based on its content
- `static getGroupPadding( group: GroupInfo, options: SubgraphLayoutOptions ): { top: number; right: number; bottom: number; left: number }` (static) — Get effective padding for a group
- `static positionGroups( groups: GroupInfo[], groupSizes: Map<string, { width: number; height: number }>, options: SubgraphLayoutOptions ): Map<string, { x: number; y: number }>` (static) — Position groups relative to each other
- `static translateToGroupCoordinates( nodePositions: Map<string, { x: number; y: number }>, group: GroupInfo, groupPosition: { x: number; y: number }, options: SubgraphLayoutOptions ): Map<string, { x: number; y: number }>` (static) — Translate node positions to group-local coordinates
- `static async layoutGroup( group: GroupInfo, allNodes: Array<{ id: string; [key: string]: any }>, allLinks: Array<{ sourceNodeId: string; targetNodeId: string; [key: string]: any }>, nodeSizes: Map<string, { width: number; height: number }>, layoutAdapter: any, options: SubgraphLayoutOptions ): Promise<{ nodePositions: Map<string, { x: number; y: number }>; bounds: { x: number; y: number; width: number; height: number }; }>` (static) — Apply layout to a single group
- `static async computeSubgraphLayout( groups: GroupInfo[], allNodes: Array<{ id: string; [key: string]: any }>, allLinks: Array<{ sourceNodeId: string; targetNodeId: string; [key: string]: any }>, nodeSizes: Map<string, { width: number; height: number }>, layoutAdapter: any, options: SubgraphLayoutOptions ): Promise<SubgraphLayoutResult>` (static) — Main subgraph layout computation

<!-- source: grafloria-engine-layout-unifiedlayoutoptions.md -->

# UnifiedLayoutOptions

Import it from `@grafloria/engine`.

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

The one options schema. Adapter-specific knobs still ride in `options`, but
everything that is common to all layouts is named here so callers do not have
to learn five different vocabularies.

```ts
interface UnifiedLayoutOptions extends Partial<LayoutOptions>, LayoutRunOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seed?` | `number` |  | Seed for any algorithm that uses randomness (force, spectral, community). Defaults to a FIXED constant — so an author who never thinks about seeds still gets the same picture every time. Randomness is opt-in. |
| `direction?` | `FlowDirection` |  | Primary flow direction, normalised across engines: dagre calls it `rankdir`, ELK calls it `elk.direction`, and the two disagree about spelling. Callers say `direction` and the registry translates. |
| `nodeSpacing?` | `number` |  | Space between nodes in the same rank/row. |
| `rankSpacing?` | `number` |  | Space between ranks/layers. |
| `nested?` | `boolean` |  | Lay groups out as CONTAINERS: each group's contents are arranged recursively (deepest first), the container is auto-sized to fit them, and the parent level then arranges containers as COMPOUND NODES — with edges that cross a container boundary induced onto the compound nodes so the containers land next to the things they actually connect to. |
| `containerPadding?` | `number` |  | Fallback inner padding for containers that carry no `padding` of their own. |
| `groupSpacing?` | `number` |  | Gap between compound units when a level falls back to the built-in grid. |
| `componentSpacing?` | `number` |  | Gap between packed disconnected components. Defaults to `nodeSpacing`. See component-packing.ts — this applies to EVERY layout, not just the new ones, because "lay out a forest and the trees land on top of each other" is an adapter-agnostic bug. |
| `aspectRatio?` | `number` |  | Target width/height of the packed result. 1.6 ≈ a landscape screen. |
| `removeOverlaps?` | `boolean` |  | Push nodes apart if the algorithm left them overlapping. Default true. |
| `columns?` | `number` |  | grid: number of columns. Defaults to ceil(sqrt(n)). |
| `rootId?` | `string` |  | tree/radial: the node to root the tree / centre the rings on. |
| `branchDirections?` | `Record<string, FlowDirection>` |  | tree: per-branch direction. The subtree rooted at each listed node flows its own way instead of the tree's `direction` — a mind map is `{ 'left-branch': 'RL', 'right-branch': 'LR' }`. |

<!-- source: grafloria-engine-layout-grid-pack.md -->

# Layout — Grid Pack

Import these from `@grafloria/engine`.

## Classes

### `GridPackEngine`

```ts
class GridPackEngine
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `float` | `boolean` |  |  |
| `maxRows?` | `number` |  | Row bound (see GridPackOptions.maxRows). Undefined = unbounded. Changed through {@link setBound}. |
| `capacity?` | `number` |  | Row capacity (see GridPackOptions.capacity). Undefined = unbounded. |

**Methods**

- `get columns(): number` — Live column count. Change it only through {@link setColumns}.
- `constructor(items: GridPackItem[] = [], options: GridPackOptions = {})`
- `getItems(): readonly GridPackItem[]`
- `getItem(id: string): GridPackItem | undefined`
- `rows(): number` — Content height in rows: max(y+h) over all items (0 when empty).
- `hasOverlaps(): boolean` — True when any two items overlap — the invariant every op must preserve.
- `add(item: GridPackItem): GridPackItem | null` — Add an item. An explicit legal position is honoured verbatim. When the
position collides — or the item asks for `autoPosition` — the tile
AUTO-POSITIONS: a row-major scan for the first
hole it fits, which is gridstack's `autoPosition` and NOT the same thing
as gravity (gravity climbs one column; a hole at (3,0) under an occupied
column is only reachable by the scan — the spec's first red proved it).
- `remove(id: string): void`
- `beginGesture(): void` — Begin a drag/resize gesture: fresh displaced-tile memory, and a full
snapshot so `cancelGesture` (Escape) can restore every tile (gridstack
`saveInitial` / `restoreInitial`).
- `endGesture(): void` — End a gesture: memory does NOT outlive it (E2, and the S4 swap lock).
- `cancelGesture(): void` — Escape: restore every tile to its gesture-start cell AND size, bring back
the tiles removed during the gesture, drop the ones added, and restore the
bound. Surviving tiles keep their object identity (a binder holds them).
- `setBound(rows: number): boolean` — Change the row bound — a container asking for rows on behalf of a child
(tile first, step 1). Refused below the current content. Inside a gesture
the change rides in the snapshot, so Escape gives the rows back.
- `moveCheck(id: string, x: number, y: number, options: MoveCheckOptions = {}): GridPackResult` — Try to put `id` at cell (x,y). Applies the full pipeline on acceptance:
swap (three shapes) | push-down (+skip below locked) → settle (teleport
memory + gravity). Refuses: out-of-gesture no-ops, cells intersecting a
locked tile (E4b), and collisions under the anti-jitter coverage gate. `{ gate: false }` (see {@link MoveCheckOptions}) is first-placement mode:
gate and swaps are skipped, push-down still applies, E4b still refuses.
- `resizeCheck(id: string, w: number, h: number, options: ResizeCheckOptions = {}): GridPackResult` — Resize `id` to w×h cells. Growth is CLAMPED so the tile never covers a
locked tile (E4b applied to size); displaced neighbours push + settle,
and return when the size shrinks back (E1/S2).
- `placeBeside(id: string, neighbourId: string, side: BesideSide, row?: number): PlaceBesideResult` — Put `id` NEXT TO `neighbourId` on `side`, at `row` (the pointer's row,
clamped to the neighbour's rows; the neighbour's own row by default) —
the one sideways primitive the tile-first drag model needs (step 1).

With room on that side the mover simply takes the cell. At the board's
edge the neighbour SHIFTS over by the mover's span and the mover takes the
edge — the fluid demo's side panel sits at the right edge and "after it"
was nowhere. With no room even shifted (a full-width neighbour), the mover
takes the cell and the neighbour goes DOWN under it, the way any tile
gives way. Top always pushes; bottom always places.

The mover steps off the board while the neighbour shifts: its own cell
must not be what refuses the shift (a chart as wide as the panel, lab
L94). Locked tiles refuse as everywhere; a bound rollback names itself.
- `setColumns(next: number, layout: GridColumnLayout = 'moveScale'): boolean` — Change the board's COLUMN COUNT — gridstack's `column(n, layout)`, and the
whole of responsive behaviour in one operation.

Three things happen, in this order:

1. THE LAYOUT WE ARE LEAVING IS CACHED under its own column count. This
    is the load-bearing step: without it, 12 → 1 → 12 would have to
    re-derive twelve columns from a one-column stack and every tile would
    come back full width.
 2. GROWING RESTORES FROM THE CACHE, per item. Items the cache knows come
    back at exactly the cells they had the last time the board was this
    wide; items it does not know (added while narrow) fall through to the
    scale rules below. Shrinking never restores — a narrower layout is
    always derived from where the board is NOW, which is what makes a
    gradual squeeze look natural.
 3. THE REMAINDER IS SCALED by `layout` (see {@link GridColumnLayout}),
    `columns === 1` forcing a single stack, and everything is re-placed in
    reading order so the result cannot overlap.

Returns true when the count actually changed.
- `saveLayout(): { columns: number; items: GridPackItem[] }` — The layout to PERSIST — gridstack's `save()`, which serialises from the
LARGEST cached column count rather than the live one. Saving while the
board is narrow (a phone) therefore saves the DESKTOP layout: the cells a
user authored at full width are the document, and the narrow arrangement
is a projection of it.

`h` is never cached because it does not depend on the column count, so it
always comes from the live item; items the widest cache does not know
(added while narrow) contribute their live cells, which are legal at any
count at least as wide.
- `cachedColumns(): number[]` — The column counts the cache currently holds a layout for (ascending).
- `getLayouts(): GridLayoutCache` — The cache as plain data — hand it to a rebuilt engine via {@link setLayouts}.
- `setLayouts(cache: GridLayoutCache): void` — Adopt a cache exported by {@link getLayouts}. The kit calls this after
rebuilding its engine from the model (`sync()`), which would otherwise
throw the wider layouts away on every undo, add or refresh.

## Interfaces

### `CachedCell`

One item's cached geometry at a column count. `h` is column-independent.

```ts
interface CachedCell
```

**Properties**

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

### `GridPackItem`

One tile, in integer grid cells.

```ts
interface GridPackItem
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `w` | `number` |  |  |
| `h` | `number` |  |  |
| `locked?` | `boolean` |  | Pinned: never pushed, never packed, refuses the mover outright (E4b). |
| `solid?` | `boolean` |  | SOLID (tile first, step 3): a container. Never pushed by a PASSING tile and never packed — a widget carried over it slides aside, so the board under the hand holds still and the container's zones stay reachable — but moved by INTENT: a mover that asks `pushSolid` (a moved section, a dock, a refused adoption), `placeBeside`, or a direct move of its own. |
| `minW?` | `number` |  | Per-item SIZE LIMITS in cells (gridstack's minW/maxW/minH/maxH). A resize clamps to them, and a column change scales a width only within them. They never move a tile: a push or a swap is not a resize. |
| `maxW?` | `number` |  |  |
| `minH?` | `number` |  |  |
| `maxH?` | `number` |  |  |
| `autoPosition?` | `boolean` |  | Ask add() to IGNORE x/y and scan row-major for the first free hole — gridstack's autoPosition (addWidget without coordinates). Distinct from gravity, which climbs one column: a hole at (3,0) under an occupied column is only reachable by the scan. Seeding/load honours explicit cells; palette-style adds pass this flag. |

### `GridPackOptions`

```ts
interface GridPackOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Column count of the board. Default 12. |
| `float?` | `boolean` |  | Float mode (gridstack `float: true`): tiles stay where placed and gaps are legal; gravity does not pack. Default false (gravity). |
| `maxRows?` | `number` |  | Row bound for a board whose DESIGN is a fixed strip (the nested KPI section: one row, always). Any op whose settled result would exceed it — a height resize, a width resize whose push spills a sibling down, a move displacing someone out of bounds — ROLLS BACK wholesale and reports `changed: false`; `add()` returns null when nothing can fit. |
| `capacity?` | `number` |  | Row CAPACITY of a board whose frame can hold only so many rows — the dashboard kit's bounded fit mode (a fit board never changes size; past its row floor it refuses rather than overflows). |

### `GridPackResult`

Result of a move/resize attempt.

```ts
interface GridPackResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `changed` | `boolean` |  | Whether the board accepted (and applied) the change. |
| `refusedBy?` | `GridPackRefusal` |  | Present on every refusal, absent on an accepted change. |

### `MoveCheckOptions`

Options for {@link GridPackEngine.moveCheck}.

```ts
interface MoveCheckOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `gate?` | `boolean` |  | The >50% anti-jitter coverage gate AND the swap heuristics it feeds. `gate: false` is the FIRST-PLACEMENT mode (a palette drag-in entering the board, or a dragged-out tile re-entering — gridstack's `dragInNode` behaviour): the cell is taken unconditionally — locked tiles still refuse (E4b), but any unlocked occupant is pushed down regardless of coverage, and no swap shape fires (an entering tile … |
| `pushSolid?` | `boolean` |  | Push SOLID tiles in the way as if they were plain — the mover means it (a moved section, a dock, a refused adoption). Default false. |

### `PlaceBesideResult`

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

Result of {@link GridPackEngine.placeBeside}.

```ts
interface PlaceBesideResult extends GridPackResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `how?` | `'placed' \| 'shifted' \| 'pushed'` |  | `placed`: the cell beside the neighbour was free (or only unlocked tiles were in it, pushed down); `shifted`: no room on that side of the board, the neighbour moved over by the mover's span and the mover took the edge; `pushed`: no room even shifted — the mover took the cell and the neighbour went down under it, the way any tile gives way. |

### `ResizeCheckOptions`

Options for {@link GridPackEngine.resizeCheck}.

```ts
interface ResizeCheckOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `pushSolid?` | `boolean` |  | Grow INTO solid tiles, pushing them, instead of clamping at them — a dock taking its band means it. Default false. |

## Types

### `BesideSide`

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

The side of a neighbour a tile is placed against.

```ts
type BesideSide = 'left' | 'right' | 'top' | 'bottom';
```

### `GridColumnLayout`

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

How a COLUMN-COUNT change re-lays the board out — gridstack's
`ColumnOptions`, recorded from its documented semantics:

'moveScale' (default) — scale both x and w by newColumns/oldColumns, so
               the board keeps its proportions at any width;
  'move'     — scale x only; widths survive verbatim (clamped to fit);
  'scale'    — scale w only; x survives verbatim (clamped to fit);
  'none'     — keep x and w exactly; clamp only what no longer fits.

Whatever the mode, `columns === 1` forces a SINGLE STACK (every tile x=0,
w=1) — the phone layout — and every mode re-places the result in reading
order afterwards, so the outcome can never overlap.

```ts
type GridColumnLayout = 'moveScale' | 'move' | 'scale' | 'none';
```

### `GridLayoutCache`

The PER-COLUMN LAYOUT CACHE, as plain data: column count → item id → cell. Exported/imported so a host that rebuilds its engine (the kit's `sync()`)
carries the wider layouts across the rebuild instead of losing them.

```ts
type GridLayoutCache = Record<number, Record<string, CachedCell>>;
```

### `GridPackRefusal`

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

Why a change was refused (tile first, step 1). A binder used to read
`changed:false` as "refused" when it also means "already there", and asked
the tile where it was instead; now every refusal names itself.

```ts
type GridPackRefusal = 'locked' | 'solid' | 'bound' | 'gate' | 'noop' | 'missing';
```

<!-- source: grafloria-engine-layout-incremental.md -->

# Layout — Incremental

Import these from `@grafloria/engine`.

## Functions

### `affectedRegion`

The nodes allowed to move: the changed set grown by `radius` hops.

This is what "re-run layout only in
the affected region" means concretely — and it is only possible because anchors
are now real: the layout works AROUND the frozen nodes instead of laying out over
them and being corrected afterwards.

```ts
function affectedRegion(
  diagram: DiagramModel,
  changed: string[],
  radius: number
): Set<string>
```

### `alignToPrevious`

The translation that minimises total squared displacement between two layouts.

For a pure translation the optimum is exactly the difference of the centroids of
the shared nodes — no search, no iteration. This is the single highest-value
function in the file: a layered layout is defined only up to translation, so a
new node widening rank 0 can shift the ENTIRE drawing sideways. Every node then
"moves" although the picture is unchanged, the movement budget blows, and a
naive implementation starts fighting its own layout with constraints. Align
first; constrain only what is left.

```ts
function alignToPrevious(next: Positions, previous: Positions): { positions: Positions; shift: { x: number; y: number } }
```

### `constraintsForStrategy`

Note what this does NOT do: it does not emit positions to be clamped afterwards. It emits ANCHORS, which the layered engine honours during coordinate assignment —
the whole reason the four scaffolded strategies never worked.

```ts
function constraintsForStrategy(
  diagram: DiagramModel,
  before: Positions,
  options: IncrementalOptions
): SemanticConstraints
```

### `measureMovement`

Measure how much the mental map was disturbed.

Only nodes that existed BEFORE count: a new node cannot "move", and including it
would flatter the numbers exactly when the layout is at its most disruptive.

```ts
function measureMovement(
  before: Positions,
  after: Positions,
  budget: MovementBudget | undefined,
  savedByAlignment = 0
): MovementReport
```

### `planTween`

```ts
function planTween(before: Positions, after: Positions): TweenPlan
```

## Interfaces

### `IncrementalOptions`

```ts
interface IncrementalOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `strategy?` | `IncrementalStrategy` |  |  |
| `changed?` | `string[]` |  | Node ids the user just added/edited. Everything else is "existing". |
| `radius?` | `number` |  | How far the disturbance is allowed to spread, in graph hops. Default 1. |
| `budget?` | `MovementBudget` |  |  |

### `MovementBudget`

```ts
interface MovementBudget
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `maxPerNode?` | `number` |  | No single node may move further than this. |
| `averagePerNode?` | `number` |  | The mean movement across all nodes that existed before. |

### `MovementReport`

```ts
interface MovementReport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `total` | `number` |  | Sum of the distances every pre-existing node travelled. |
| `average` | `number` |  |  |
| `max` | `number` |  |  |
| `moved` | `number` |  | How many pre-existing nodes moved at all (beyond a 0.5px epsilon). |
| `unmoved` | `number` |  | Of the pre-existing nodes, how many stayed exactly put. |
| `withinBudget` | `boolean` |  | Did we stay inside the caller's budget? |
| `savedByAlignment` | `number` |  | How much of the movement the centroid re-alignment removed. |

### `TweenPlan`

A tween plan: pure data, so the engine stays free of rAF/DOM/time.

The card asks for "an animated tweened transition from old to new positions
instead of snapping". The engine's job is to say WHERE things go at time t; the
host's job is to drive t. Keeping it that way is what lets the same code run in
a worker, in SSR, and in a test.

```ts
interface TweenPlan
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `movingIds` | `string[]` |  | Nodes that actually move — a host can skip the rest entirely. |

**Members**

- `at(t: number): Positions` — Positions at normalised time t ∈ [0, 1]. Eased.

## Types

### `IncrementalStrategy`

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

```ts
type IncrementalStrategy =

  | 'region'

  | 'pin-existing'

  | 'minimal-shift';
```

### `Positions`

```ts
type Positions = Map<string, { x: number; y: number }>;
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` |  |  |

**Members**

- `clear(): void`
- `delete(key: K): boolean`
- `forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void` — Executes a provided function once per each key/value pair in the Map, in insertion order.
- `get(key: K): V | undefined` — Returns a specified element from the Map object. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.
- `has(key: K): boolean`
- `set(key: K, value: V): this` — Adds a new element with a specified key and value to the Map. If an element with the same key already exists, the element will be updated.
- `entries(): MapIterator<[K, V]>` — Returns an iterable of key, value pairs for every entry in the map.
- `keys(): MapIterator<K>` — Returns an iterable of keys in the map
- `values(): MapIterator<V>` — Returns an iterable of values in the map
- `[Symbol.iterator](): MapIterator<[K, V]>` — Returns an iterable of entries in the map.
- `readonly [Symbol.toStringTag]: string`

<!-- source: grafloria-engine-layout-sugiyama.md -->

# Layout — Sugiyama

Import these from `@grafloria/engine`.

## Functions

### `createLayeredLayout`

```ts
function createLayeredLayout(name = 'layered'): RegisteredLayout
```

### `inferDirection`

DIRECTION INFERENCE — "TB for trees, LR for pipelines".

The heuristic, stated so it can be argued with: a graph that is deep and narrow
reads better across the page (a pipeline: A → B → C → D as a row, not a column),
and a graph that is wide and shallow reads better down it (a tree fans out). The threshold is the aspect of the LAYER structure, not of the node count.

```ts
function inferDirection(nodes: SugiyamaNode[], edges: SugiyamaEdge[]): LayoutDirection
```

### `sugiyama`

Lay out a graph in layers. Pure, deterministic, no DOM, no time, no randomness.

```ts
function sugiyama(
  nodes: SugiyamaNode[],
  edges: SugiyamaEdge[],
  options: SugiyamaOptions = {}
): SugiyamaResult
```

## Interfaces

### `LayeredLayoutOptions`

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

```ts
interface LayeredLayoutOptions extends UnifiedLayoutOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `semantic?` | `SemanticConstraints` |  | . Honoured DURING ranking/ordering — not clamped afterwards. |
| `iterations?` | `number` |  | Ordering/coordinate sweeps. |

### `SemanticConstraints`

's semantic constraints — honoured DURING the pipeline, not clamped after. Every one of these is a decision taken in ranking or ordering.

```ts
interface SemanticConstraints
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sameRank?` | `string[][]` |  | Groups of node ids that must share a rank/layer. Applied by contraction before ranking. |
| `order?` | `Array<[string, string]>` |  | `[a, b]` means a must come before b within its layer (left-of in TB, above in LR). |
| `keepTogether?` | `string[][]` |  | Node ids that must stay adjacent in the ordering — a cluster the sweeps may not split. |
| `anchors?` | `Record<string, { x?: number; y?: number }>` |  | Nodes pinned to a coordinate. Unlike the old clamp, everything else routes AROUND them. |

### `SugiyamaEdge`

```ts
interface SugiyamaEdge
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `source` | `string` |  |  |
| `target` | `string` |  |  |

### `SugiyamaNode`

```ts
interface SugiyamaNode
```

**Properties**

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

### `SugiyamaOptions`

```ts
interface SugiyamaOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction?` | `LayoutDirection` |  |  |
| `nodeSpacing?` | `number` |  | Gap between nodes in the same layer. |
| `rankSpacing?` | `number` |  | Gap between layers. |
| `constraints?` | `SemanticConstraints` |  |  |
| `iterations?` | `number` |  | Ordering sweeps. More = fewer crossings, diminishing fast. |
| `rng?` | `LayoutRng` |  |  |

### `SugiyamaResult`

```ts
interface SugiyamaResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `positions` | `Map<string, { x: number; y: number }>` |  |  |
| `ranks` | `Map<string, number>` |  |  |
| `bends` | `Map<string, Array<{ x: number; y: number }>>` |  | Bend points for edges that span more than one rank (the dummy chains). |
| `crossings` | `number` |  | Crossings in the final ordering — the headline quality number. |
| `stats` | `SugiyamaStats` |  | Deterministic work counters — regression tests bound these instead of wall clock. |

### `SugiyamaStats`

Work counters, filled on every run. They exist because "it got slow" is only
fixable when you can see WHERE the work went: a wide layer full of dummies made
the old transpose recount every inter-layer crossing twice per candidate swap
(O(width * E²) per pass), which is the difference between 40ms and being killed
at 25s on the same node count. The counters are pure functions of the input —
no wall clock — so CI can assert hard bounds without flaking.

```ts
interface SugiyamaStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dummyCount` | `number` |  |  |
| `layerCount` | `number` |  |  |
| `maxLayerWidth` | `number` |  |  |
| `transposePasses` | `number` |  | transpose() while-passes actually run (bounded by guard × ordering iterations). |
| `transposeSwapsEvaluated` | `number` |  | adjacent pairs considered for swapping, across all passes |
| `transposeSwapsApplied` | `number` |  | swaps that were kept because they reduced crossings |
| `crossingCountOps` | `number` |  | elements pushed through inversion counting in countCrossings, across the run |

## Types

### `LayoutDirection`

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

```ts
type LayoutDirection = 'TB' | 'BT' | 'LR' | 'RL';
```

<!-- source: grafloria-engine-models.md -->

# Models

Import these from `@grafloria/engine`.

## On their own pages

- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-constants): 6 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-functions): 6 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-interfaces): 17 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-types): 7 types.
- [`DetachedParentAnchor`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-detachedparentanchor): The LAST-KNOWN ANCHOR of a node the diagram has REMOVED.
- [`DiagramEntity`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-diagramentity)
- [`DiagramModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-diagrammodel)
- [`GroupModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-groupmodel)
- [`LinkModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-linkmodel)
- [`NodeModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-nodemodel)
- [`PortModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-portmodel)
- [`SerializedPort`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-serializedport)
- [`StrokeModel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-models-strokemodel): A freehand ink stroke: an ordered point list, a style, and an identity.

<!-- source: grafloria-engine-models-constants.md -->

# Constants

Import these from `@grafloria/engine`.

## Constants

### `DEFAULT_GROUP_HEADER_HEIGHT`

```ts
const DEFAULT_GROUP_HEADER_HEIGHT: 24
```

### `DEFAULT_GROUP_PADDING`

Defaults for groups AUTHORED in code (constructor path). A fitted frame needs
breathing room and a title band or its label lands under the first member. Loaded documents are exempt: restore assigns the stored values (padding
verbatim — possibly undefined, which getPadding() resolves to 0 — and
headerHeight number-or-0), so legacy geometry is byte-stable.

```ts
const DEFAULT_GROUP_PADDING: 16
```

### `DEFAULT_PORT_SNAP_RADIUS`

How near a port must be to a point for {@link DiagramModel.findNearestPort} to
consider it, in world units. Roughly a fingertip at 100% zoom.

```ts
const DEFAULT_PORT_SNAP_RADIUS: 24
```

### `DEFAULT_SIMPLIFY_EPSILON`

Douglas-Peucker tolerance, in WORLD units.

0.6 is tuned against real traces: below ~0.4 you keep the sensor jitter you were
trying to remove; above ~1.2 a deliberate small loop (the dot of an "i", a tick) starts
to visibly flatten. At 0.6 a 500-point scribble lands around 40-70 points and is
indistinguishable from the raw trace at 100% zoom.

It is world-space, so ink drawn while zoomed OUT is simplified more aggressively in
screen terms — which is right: you cannot see detail you did not draw.

```ts
const DEFAULT_SIMPLIFY_EPSILON: 0.6
```

### `DEFAULT_STROKE_STYLE`

```ts
const DEFAULT_STROKE_STYLE: StrokeStyle
```

### `LINK_LABEL_SLOT_POSITIONS`

Where each of the three edge label SLOTS sits
along the path.

Pulled IN from the endpoints on purpose: at exactly 0 and 1 a slot label would
land under the arrowhead and on top of the port. 0.12 / 0.88 clears both while
still reading as "at the start / at the end of this edge".

ONE definition, shared by the model (LinkModel.addLabel), the renderer
(LabelRenderer) and the edge optimizer — three places that must never disagree
about where a label actually is.

```ts
const LINK_LABEL_SLOT_POSITIONS: Record<'start' | 'center' | 'end', number>
```

<!-- source: grafloria-engine-models-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `bumpMutationEpoch`

Bump the epoch by hand, for a mutation that legitimately bypasses
`markDirty()` (in-place `points` rewrites, say). Prefer `markDirty()`.

```ts
function bumpMutationEpoch(): number
```

### `distanceToSegment`

Distance from `p` to the segment `a`→`b`. The primitive both hit-tests are built on.

```ts
function distanceToSegment(p: Point, a: Point, b: Point): number
```

### `getMutationEpoch`

Read the current mutation epoch. Cheap enough to call every frame.

```ts
function getMutationEpoch(): number
```

### `hasPressure`

True when the device gave us pressure worth keeping (i.e. it actually varies).

```ts
function hasPressure(points: readonly StrokePoint[]): boolean
```

### `linkLabelPosition`

The position along the path (0-1) a label resolves to.

`slot` WINS over `position`. Naming a slot is an explicit act; `position` is a
required field that most slot users only fill in to satisfy the type, so
letting it win would make `slot` silently do nothing.

```ts
function linkLabelPosition(
  label: Pick<LinkLabel, 'position' | 'slot'>
): number
```

### `segmentDistance`

Minimum distance between two SEGMENTS.

The eraser needs this and a point-test cannot replace it. A pointermove at 60Hz over
a fast flick lands samples 80px apart; testing only the sample POINTS lets the
eraser jump clean over a stroke it visibly swept through. So the eraser tests the
segment it travelled, not the points it happened to land on.

```ts
function segmentDistance(a1: Point, a2: Point, b1: Point, b2: Point): number
```

<!-- source: grafloria-engine-models-interfaces.md -->

# Interfaces

Import these from `@grafloria/engine`.

## Interfaces

### `ChangeEntry`

```ts
interface ChangeEntry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timestamp` | `number` |  |  |
| `property` | `string` |  |  |
| `oldValue` | `any` |  |  |
| `newValue` | `any` |  |  |

### `CollapsedState`

The reversible snapshot captured when a group collapses. Stored (serialized) on the group so a collapsed diagram round-trips and can
be expanded losslessly after a save/load — not just within one session.

```ts
interface CollapsedState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `proxyNodeId` | `string` |  | The hidden placeholder node that presents the group as a node endpoint. |
| `savedGeometry?` | `{ position: { x: number; y: number }; size?: { width: number; height: number; depth: number }; bounds?: GroupRect; }` |  | The group's exact geometry before it shrank (restored verbatim on expand). |
| `savedPositions` | `Record<string, { x: number; y: number }>` |  | Member (node) world positions at collapse time (restored on expand). |
| `hiddenNodes` | `Array<{ nodeId: string; prevVisible: boolean }>` |  | Members whose visibility we toggled, with their prior `visible` value. |
| `removedLinks` | `any[]` |  | Serialized links removed at collapse time (internal links + the parallel boundary links that were aggregated away). Re-created verbatim on expand. |
| `proxyLinks` | `Array<{ linkId: string; end: 'source' \| 'target'; originalPortId: string; originalNodeId?: string; aggregatedCount: number; }>` |  | Boundary links that SURVIVED as proxy links: one per (external endpoint) bundle, re-pointed to the placeholder node. Records the original endpoint so expand can restore it, plus how many raw edges it now represents. |

### `DiagramLoadOptions`

```ts
interface DiagramLoadOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `validate?` | `'off' \| 'warn' \| 'strict'` |  | Structural integrity policy for the incoming document: - 'off' (default) skip validation - 'warn' validate and console.warn a one-line summary with the report - 'strict' validate and throw DiagramValidationError on any error |

### `FitToContentsOptions`

Options for {@link GroupModel.fitToContents}.

```ts
interface FitToContentsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `GroupFitMode` |  | Override the group's stored {@link GroupModel.fitMode} for this call. |
| `deepRecursive?` | `boolean` |  | Deep-recursive fit: fit every descendant group first (deepest first) so a parent fits around already-fitted children. Requires a diagram. |

### `GroupRect`

A resolved rectangle (all four sides present).

```ts
interface GroupRect
```

**Properties**

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

### `LaneConfig`

Swimlanes & pools as a GENERIC banded group (not BPMN-named). A `pool` group tiles its child `lane` groups into bands along one axis; each
`lane` is an ordinary group (so drop-to-assign, membership, constraints all
reuse the existing machinery). This is intrinsic band config that round-trips.

```ts
interface LaneConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `role` | `'pool' \| 'lane'` |  | 'pool' owns the band grid; 'lane' is one band inside a pool. |
| `orientation` | `'horizontal' \| 'vertical'` |  | Band axis. 'horizontal' → lanes are rows stacked along Y (each spans the pool width). 'vertical' → lanes are columns along X (each spans the height). Set on the pool; lanes carry a copy for convenience. |
| `laneOrder?` | `string[]` |  | Pool only: ordered child lane group ids (band order). |
| `headerSize?` | `number` |  | Pool only: title-band thickness reserved along the main axis start (left for horizontal pools, top for vertical pools). |
| `weight?` | `number` |  | Lane only: relative cross-axis size when not fixed (default 1). |
| `fixedSize?` | `number` |  | Lane only: absolute cross-axis size (pins the band, overrides weight). |

### `MembershipLeaf`

```ts
interface MembershipLeaf
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `field` | `string` |  | Dot-free key looked up on the node's `data` map. |
| `op` | `'eq' \| 'ne' \| 'in' \| 'nin' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'exists' \| 'matches'` |  |  |
| `value?` | `unknown` |  | Comparison operand (array for in/nin; regex source string for matches). |

### `NearestPortHit`

What {@link DiagramModel.findNearestPort} found.

```ts
interface NearestPortHit
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `port` | `PortModel` |  |  |
| `node` | `NodeModel` |  |  |
| `distance` | `number` |  | Distance from the query point to the port, in world units. |

### `NearestPortOptions`

Options for {@link DiagramModel.findNearestPort}.

```ts
interface NearestPortOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `radius?` | `number` |  | Maximum distance, in world units (default {@link DEFAULT_PORT_SNAP_RADIUS}). |
| `filter?` | `(port: PortModel, node: NodeModel) => boolean` |  | Consider only the ports this accepts (e.g. valid targets for the dragged link). |
| `portPosition?` | `(port: PortModel, node: NodeModel) => Point` |  | Where a port actually IS. Defaults to the bounding-box edge midpoint. Callers inside a renderer must pass the SHAPE-AWARE resolver (`portWorldPosition`) — see the note on `findNearestPort`. |

### `SerializedDiagram`

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

```ts
interface SerializedDiagram extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `schemaVersion?` | `number` |  | Document schema version (shape of THIS payload), distinct from the per-entity mutation counter `version`. Absent on pre-versioning documents, which are treated as schemaVersion 1 and migrated on load. |
| `name` | `string` |  |  |
| `nodes` | `SerializedNode[]` |  |  |
| `links` | `SerializedLink[]` |  |  |
| `groups` | `SerializedGroup[]` |  |  |
| `strokes?` | `SerializedStroke[]` |  | Freehand ink. |
| `viewport` | `{ x: number; y: number; width: number; // Phase 0.5 - Viewport-aware layout height: number; // Phase 0.5 - Viewport-aware layout zoom: number; }` |  |  |
| `comments?` | `CommentRegisterTree` |  | Anchored comment threads. Document data, saved with the document — a comment that does not survive a save is a comment that does not exist. |

### `SerializedGroup`

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

```ts
interface SerializedGroup extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `members` | `string[]` |  |  |
| `isCollapsed` | `boolean` |  |  |
| `bounds?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `layoutType?` | `LayoutType` |  |  |
| `layoutConfig?` | `LayoutConfig` |  |  |
| `position?` | `{ x: number; y: number }` |  |  |
| `size?` | `{ width: number; height: number; depth: number }` |  |  |
| `parentGroupId?` | `string` |  |  |
| `padding?` | `GroupPadding` |  |  |
| `headerHeight?` | `number` |  |  |
| `zIndex?` | `number` |  |  |
| `fitMode?` | `GroupFitMode` |  |  |
| `constrainChildren?` | `boolean` |  |  |
| `collapsedState?` | `CollapsedState` |  |  |
| `subgraphLayout?` | `SubgraphGroupConfig` |  |  |
| `laneConfig?` | `LaneConfig` |  |  |
| `membershipRule?` | `MembershipRule` |  |  |
| `capacity?` | `number` |  |  |

### `SerializedLink`

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

```ts
interface SerializedLink extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sourcePortId` | `string` |  |  |
| `targetPortId` | `string` |  |  |
| `sourceNodeId?` | `string` |  |  |
| `targetNodeId?` | `string` |  |  |
| `pathType` | `'direct' \| 'orthogonal' \| 'smooth' \| 'bezier'` |  |  |
| `router?` | `LinkRouterName` |  | Explicit routing geometry; absent = derived from pathType. |
| `connector?` | `LinkConnectorName` |  | Explicit polyline rendering; absent = derived from pathType. |
| `points` | `Point[]` |  |  |
| `segments` | `PathSegment[]` |  |  |
| `labels` | `LinkLabel[]` |  |  |
| `state` | `'default' \| 'selected' \| 'hovered' \| 'highlighted'` |  |  |
| `style` | `Partial<LinkStyle>` |  |  |
| `data` | `Record<string, any>` |  |  |

### `SerializedNode`

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

```ts
interface SerializedNode extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `Point` |  |  |
| `size` | `Size` |  |  |
| `rotation` | `number` |  |  |
| `scale` | `Point` |  |  |
| `type` | `string` |  |  |
| `systemType?` | `string` |  |  |
| `definitionId?` | `string` |  |  |
| `parentId?` | `string` |  |  |
| `children` | `string[]` |  |  |
| `ports` | `SerializedPort[]` |  |  |
| `state` | `NodeState` |  |  |
| `behavior` | `NodeBehavior` |  |  |
| `style` | `Partial<NodeStyle>` |  |  |
| `data` | `Record<string, any>` |  |  |
| `positionMode?` | `PositioningMode` |  |  |
| `transformOrigin?` | `Point` |  |  |
| `zIndex?` | `number` |  | Model-level stacking order. OMITTED when the node never set one, so every document written before this field existed round-trips byte-for-byte and no schema migration is needed — absence means "unset", not 0. |
| `flexConfig?` | `FlexItemConfig` |  |  |
| `gridConfig?` | `GridItemConfig` |  |  |
| `portRenderingConfig?` | `any` |  |  |
| `dragHandlerConfig?` | `any` |  |  |
| `connectionGroup?` | `string` |  |  |

### `SerializedStroke`

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

```ts
interface SerializedStroke extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'stroke'` |  |  |
| `points` | `StrokePoint[]` |  |  |
| `style` | `StrokeStyle` |  |  |
| `label?` | `string` |  | An author-supplied name. THE ENTIRE ACCESSIBILITY STORY LIVES ON THIS FIELD — see the a11y note on the renderer's ink layer. Absent for anonymous ink, which is the normal case and is rendered `aria-hidden`. |

### `StrokePoint`

One sample from the pointer.

`pressure` is 0..1 and OPTIONAL — a mouse does not have any. It is stored only when
the device actually reported a varying one (see {@link hasPressure}), because a
field that is always 0.5 is noise on the wire and a lie in the model.

It is not decoration: the renderer builds a variable-width outline from it. A
pressure that does not change the picture would be exactly the "machinery wired to
nothing" this project has shipped in all nine previous waves.

```ts
interface StrokePoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `pressure?` | `number` |  | 0..1. Absent when the device did not report a meaningful one. |

### `StrokeStyle`

How the ink looks. Flat and JSON-safe — this crosses the wire as an op payload.

```ts
interface StrokeStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` |  | Any CSS colour. |
| `width` | `number` |  | Nominal width in WORLD units (so ink zooms with the diagram, like everything else). |
| `opacity?` | `number` |  | 0..1. Highlighter ink is translucent; a pen is not. |

### `SubgraphGroupConfig`

A group's own compound-layout configuration — the subset of
the GroupInfo layout contract that is intrinsic to the group and round-trips.

```ts
interface SubgraphGroupConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm?` | `'dagre' \| 'elk' \| 'grid' \| 'inherit' \| (string & {})` |  | Algorithm for THIS group's contents. 'inherit' uses the parent/default. |
| `fixed?` | `boolean` |  | Pinned: neither laid out internally nor moved by the parent layout. |
| `layoutOptions?` | `Record<string, unknown>` |  | Opaque options forwarded to the chosen layout adapter. |

<!-- source: grafloria-engine-models-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `GroupFitMode`

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

How {@link GroupModel.fitToContents} reconciles the freshly
computed content rectangle with the group's current rectangle.
- `exact`      — snap to the content rectangle (default).
- `grow-only`  — never shrink below the current rectangle (union).
- `shrink-only`— never grow beyond the current rectangle (intersection-ish).

```ts
type GroupFitMode = 'exact' | 'grow-only' | 'shrink-only';
```

### `GroupPadding`

Per-side padding (a scalar expands to all four sides).

```ts
type GroupPadding =
  | number
  | { top?: number; right?: number; bottom?: number; left?: number };
```

**Members**

- `toString(radix?: number): string` — Returns a string representation of an object.
- `valueOf(): number` — Returns the primitive value of the specified object.
- `toLocaleString(locales?: string | string[], options?: Intl.NumberFormatOptions): string` — Converts a number to a string by using the current or specified locale.

### `LinkConnectorName`

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

```ts
type LinkConnectorName =
  | 'straight'
  | 'rounded'
  | 'smooth'
  | 'bezier'
  | (string & {});
```

### `LinkRouterName`

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

. `pathType` conflated two independent choices:
WHERE the line goes (routing geometry) and HOW the polyline is drawn
(connector rendering). They are now two orthogonal, per-link, serializable
settings, with `pathType` kept as the back-compat shorthand that derives both
when the explicit fields are absent.

Router names resolve against the engine's RoutingEngine registry, so a custom
registered router is addressable per link by its registration name.

```ts
type LinkRouterName =
  | 'straight'
  | 'orthogonal'
  | 'manhattan'
  | 'avoid'
  | 'elk'
  | (string & {});
```

### `MembershipRule`

A SERIALIZABLE declarative membership predicate over a node's
`data` (never eval'd code). Leaves match one field with an operator; branches
compose with all/any/not. Kept intentionally small and closed so it round-
trips and can be reasoned about / edited as data.

```ts
type MembershipRule =
  | MembershipLeaf
  | { all: MembershipRule[] }
  | { any: MembershipRule[] }
  | { not: MembershipRule };
```

### `MemberValidation`

Predicate used to gate group membership. Return false to reject a candidate entity from joining the group.

```ts
type MemberValidation = (candidateId: string, group: GroupModel) => boolean;
```

**Parameters**

- `candidateId`: id of the node/group being added
- `group`: the group the candidate would join

### `PositioningMode`

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

Positioning mode
- absolute: Position relative to diagram origin (default, backward compatible)
- relative: Position relative to parent
- layout: Position managed by parent's layout algorithm (future)

```ts
type PositioningMode = 'absolute' | 'relative' | 'layout';
```

<!-- source: grafloria-engine-models-detachedparentanchor.md -->

# DetachedParentAnchor

Import it from `@grafloria/engine`.

The LAST-KNOWN ANCHOR of a node the diagram has REMOVED.

A removed parent leaves soft refs behind by design (children's `parentId`, group
`members`) — hard-clearing them would be irreversible under collab/undo, where the ref
dangling and later RE-RESOLVING is exactly what makes undo-of-parent-delete restore
children byte-identically (same argument as the link quarantine in collab/integrity.ts). The price of keeping the ref is that the position readers must TOLERATE it: without
help, a relative child whose parent stopped resolving read its raw offset as world
coordinates and visually JUMPED. This anchor is the help — everything the three parent
frame readers (getWorldPosition / getGlobalPosition / getGlobalTransformMatrix) need to
freeze an orphaned subtree exactly where the user last saw it. Captured by
DiagramModel.removeNode() at the moment of removal; DERIVED, session-local, never
serialized (a document loaded with a dangle has no anchor to freeze at — that is
DiagramValidator's case, and the readers keep their deterministic raw-offset fallback).

```ts
interface DetachedParentAnchor
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `world` | `Point` |  | getWorldPosition() at removal — the summed offset chain, world coords. |
| `global` | `Point` |  | getGlobalPosition() at removal — the transform-aware position. |
| `rotation` | `number` |  | Local rotation at removal (getGlobalPosition composes against the parent's LOCAL rotation). |
| `scale` | `Point` |  | Local scale at removal (same reason). |
| `matrix` | `TransformMatrix` |  | getGlobalTransformMatrix() at removal — for getGlobalBounds and friends. |

<!-- source: grafloria-engine-models-diagramentity.md -->

# DiagramEntity

Import it from `@grafloria/engine`.

```ts
abstract class DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `uuid` | `string` |  |  |
| `version` | `number` | `1` |  |
| `metadata` | `Map<string, any>` |  |  |

**Methods**

- `constructor(id?: string, uuid?: string)`
- `get isDirty(): boolean` — Check if entity has been modified since last render
- `markDirty(reason?: string): void` — Mark entity as dirty (needs re-render)
- `markClean(): void` — Mark entity as clean (rendered)
- `getDirtyReasons(): string[]` — Get reasons why entity is dirty
- `getDirtyTimestamp(): number | null` — Get timestamp when entity was marked dirty
- `beginBatch(): void` — Begin batch update
Delays dirty marking until batch ends
- `endBatch(): void` — End batch update
Marks dirty once if any changes occurred
- `isBatching(): boolean` — Check if currently in batch mode
- `reportRegisterWrite(property: string, oldValue: unknown, newValue: unknown): void` — REPORT A REGISTER WRITE THE COLLAB REDUCER JUST PERFORMED.

`trackChange()` is `protected`, and `applyOp` lives outside the class — so every
register the reducer wrote by plain field assignment (anything with no dedicated
mutator: a link's `style`, `flexConfig`, a group's `isCollapsed`, `layoutConfig`,
`bounds`, `parentId`, …) mutated the model WITHOUT passing the funnel.

That is not a cosmetic gap. `UndoStack.undo()` applies the inverse THROUGH THE MODEL
WITH CAPTURE LIVE and then reads back whatever capture minted. No trackChange means
no op, which means THE UNDO REACHES NOBODY. Measured before this existed:

link style   execute → 1 op   undo → 0 ops
    flexConfig   execute → 1 op   undo → 0 ops
    isCollapsed  execute → 1 op   undo → 0 ops
    position     execute → 1 op   undo → 1 op   ← a real mutator: always worked

The author's own document was correct every time — which is exactly why this
survived. It is the `UpdateLinkStyleCommand` defect (see style-undo.spec.ts) living
one layer down, in the reducer, and hitting every mutator-less register at once.

So the reducer gets a seam onto the funnel rather than a copy of it. There is still
ONE funnel; this is a door onto it, not a second source of truth.
- `on(event: string, handler: Function): () => void` — Subscribe to changes
- `onPropertyChange(property: string, handler: (data: any) => void): () => void` — Subscribe to property changes
- `getChangeLog(): ReadonlyArray<ChangeEntry>` — Get change history
- `clearChangeLog(): void` — Clear change history
- `getLabel(): string | undefined` — CANONICAL label read. `metadata.label` wins; legacy `data['label']` (on
subclasses that carry a data bag) is honoured as a fallback so pre-canon
documents and third-party writers still surface their labels everywhere —
rendering, a11y names, and Mermaid export alike.
- `setLabel(label: string): void` — CANONICAL label write. Writes `metadata.label` (tracked → dirty → repaint)
and mirrors into the legacy `data['label']` slot when the entity has a
data bag, so any reader still on the old field sees the same value. The
mirror is a shadow: metadata is authoritative on every read path.
- `setMetadata(key: string, value: any): void` — Set metadata value
- `getMetadata(key: string): any` — Get metadata value
- `deleteMetadata(key: string): void` — Remove metadata
- `abstract serialize(): SerializedEntity` — Serialize entity to JSON
- `isDisposed(): boolean` — Check if entity has been disposed
- `dispose(): void` — Dispose entity and clean up resources
Prevents memory leaks by:
- Removing all event listeners
- Clearing change log
- Clearing metadata
- Marking as disposed

<!-- source: grafloria-engine-models-diagrammodel.md -->

# DiagramModel

Import it from `@grafloria/engine`.

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

```ts
class DiagramModel extends DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `'Untitled Diagram'` |  |
| `nodes` | `Map<string, NodeModel>` |  |  |
| `links` | `Map<string, LinkModel>` |  |  |
| `groups` | `Map<string, GroupModel>` |  |  |
| `strokes` | `Map<string, StrokeModel>` |  | Freehand ink strokes. See StrokeModel for why these are not nodes. |
| `linkIntegrityOwner` | `'model' \| 'external'` | `'model'` | Who owns the invariant "a link whose node is gone is not a link"? |
| `viewport` |  |  |  |

**Methods**

- `get comments(): CommentRegisterTree` — The comment register tree. Read-only in spirit: write through writeCommentRegister. The landing pad for `applyOp`'s whole-tree write (remote ops, replay, load).

Coarse ON PURPOSE at this level: applyOp hands us the rebuilt tree, and all we owe
the world is "the comments changed". The FINE-grained registers — the thing that
decides whether two concurrent replies both survive — are cut in the OPS, not here
(see writeCommentRegister and comments/types.ts).
- `set comments(next: CommentRegisterTree)` — The comment register tree. Read-only in spirit: write through writeCommentRegister. The landing pad for `applyOp`'s whole-tree write (remote ops, replay, load).

Coarse ON PURPOSE at this level: applyOp hands us the rebuilt tree, and all we owe
the world is "the comments changed". The FINE-grained registers — the thing that
decides whether two concurrent replies both survive — are cut in the OPS, not here
(see writeCommentRegister and comments/types.ts).
- `writeCommentRegister(path: string, value: unknown): boolean` — Write ONE comment register — `t1.status`, `t1.messages.m3` — and nothing else.

This is the LOCAL authoring path, and the granularity here becomes the granularity
of the emitted op (OpCapture turns `trackChange('comments.t1.messages.m3')` into
`set(diagram, path='comments.t1.messages.m3')`), which becomes the granularity of
the LWW register, which is what decides whether your colleague's simultaneous reply
survives. The dotted path is not a convenience. It is the concurrency semantics.

Returns false when the write changes nothing — so a redundant resolve is not an op,
not a broadcast, and not a frame.
- `readCommentRegister(path: string): unknown` — Read one register. Returns undefined for any missing segment — never throws.
- `constructor( name?: string, options?: { lodConfig?: LODConfig; id?: string; uuid?: string } )`
- `refreshLinkBounds(link: LinkModel): void` — Re-index a link after its geometry changed WITHOUT a `change:points` event.

Renderers route links per frame and assign `link.points` directly (using
`setPoints()` would emit `change` → `link:changed` → another render, i.e. a
render loop). The spatial index therefore never hears about the routed path,
and its grid cells would keep pointing at the geometry the link had when it
was added. Call this after writing points directly.
- `isReadonly(): boolean` — Is this document locked against edits?
- `setReadonly(value: boolean): void` — Lock / unlock the document. Normally driven by `DiagramEngine.setMode()` —
VIEW and PRESENTATION lock, DESIGNER unlocks — so `DiagramMode` finally means
something. Can also be set directly for a host that has no mode concept.
- `blocksDocumentWrite(): boolean` — True when a document mutation must be refused right now.
- `inSystemWrite(): boolean` — True while a SYSTEM write is in flight. Read by the PER-NODE geometry lock
(`NodeState.locked`) so it exempts measured writes exactly as the document
lock does — see readonly-lock.ts.
- `runSystemWrite<T>(fn: () => T): T` — Run a SYSTEM write — a derived/measured value (auto-size, portal placement)
the engine needs in order to render the document as it already is. Permitted
even while locked. NOT reachable from user input; see readonly-lock.ts.
- `addNode(node: NodeModel): void`
- `removeNode(nodeId: string): NodeModel | undefined` — Remove node from diagram — AND every link attached to it.

It matters because EVERY removal path funnels through here:
  - `deleteSelected()` — what the Delete key calls;
  - `applyNodes()` — what `setNodes()` calls, so dropping a node from a React-shaped
    spec left the dangling links behind;
  - `RemoveNodeCommand`.

A link's endpoints are the invariant that makes it a link; a link to nowhere is not
a link. So the cascade belongs at the choke point, not at each of the three call
sites that would each have to remember it.

UNLESS someone better owns that invariant — see {@link linkIntegrityOwner}.
- `getLinksForNode(nodeId: string): LinkModel[]` — Every link with an endpoint on `nodeId` (either end, including a self-loop).

Resolved through the port index rather than the cached `sourceNodeId`/`targetNodeId`,
because those are a backfill that can be absent on a link built by hand.
- `restoreNode(data: any): NodeModel | undefined` — Restore node from serialized data
- `getNode(nodeId: string): NodeModel | undefined` — Get node by ID
- `getNodes(): NodeModel[]` — Get all nodes
- `getNodeByPortId(portId: string): NodeModel | undefined` — Get node that owns a specific port
Used for connection group validation and other port-based queries. O(1) via the portIndex (was an O(nodes×ports) linear scan).
- `getPortById(portId: string): PortModel | undefined` — Get the port model for a port id, O(1) via the portIndex. Companion to getNodeByPortId for callers that need the port itself.
- `getDetachedAnchor(nodeId: string): DetachedParentAnchor | undefined` — The last-known anchor of a REMOVED node, or undefined if the id is
live, was never here, or the anchor was wholesale-cleared. The tolerant readers in
NodeModel (getWorldPosition / getGlobalPosition / getGlobalTransformMatrix /
setGlobalPosition) resolve an unresolvable parent through this so orphaned relative
children freeze in place instead of jumping to their raw offsets. See
{@link detachedAnchors} and the design argument on {@link removeNode}.
- `clearNodes(): void` — Clear all nodes
- `addLink(link: LinkModel): void` — Add link to diagram
- `removeLink(linkId: string): LinkModel | undefined` — Remove link from diagram
- `restoreLink(data: any): LinkModel | undefined` — Restore link from serialized data
- `getLink(linkId: string): LinkModel | undefined` — Get link by ID
- `getLinks(): LinkModel[]` — Get all links
- `getLinksForPort(portId: string): LinkModel[]` — Get all links connected to a specific port
- `clearLinks(): void` — Clear all links
- `createSmartLink( sourceNode: NodeModel, targetNode: NodeModel, pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier' = 'smooth' ): LinkModel | undefined` — Create a smart link with automatic port selection

This high-level API simplifies link creation by:
- Automatically selecting optimal ports based on node geometry
- Creating the link with proper port connections
- Registering connections in port models
- Generating the initial path
- `connectNodes( sourceNode: NodeModel, targetNode: NodeModel, pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier' = 'smooth' ): boolean` — High-level API to connect two nodes

Convenience method that creates a smart link and returns success status. This is the simplest way to connect nodes.
- `getNodeConnections(node: NodeModel): { incoming: LinkModel[]; outgoing: LinkModel[]; all: LinkModel[]; }` — Get all connections for a node

Returns all links where the node is either source or target. Useful for querying node connectivity.
- `disconnectNodes(sourceNode: NodeModel, targetNode: NodeModel): number` — Disconnect two nodes

Removes all links between the specified nodes. Handles cleanup of port connections.
- `addGroup(group: GroupModel): void` — Add group
- `removeGroup(groupId: string): GroupModel | undefined` — Remove group
- `restoreGroup(data: any): GroupModel | undefined` — Restore group from serialized data
- `getGroup(groupId: string): GroupModel | undefined` — Get group by ID
- `getGroups(): GroupModel[]` — Get all groups
- `getGroupsInRenderOrder(): GroupModel[]` — Groups in deterministic back-to-front stacking order —
ascending `zIndex`, ties broken by Map insertion order (a STABLE sort keeps
it). This is the model-level z-order story that replaces "stacking == Map
insertion order" as the only determinant; a renderer paints groups in this
order (behind their members) instead of relying on iteration order.
- `getProxyNodeForGroup(groupId: string): NodeModel | undefined` — The placeholder "group-as-node" for a collapsed group, if
present. Placeholder nodes are ordinary NodeModels tagged with the group id
so callers can filter them out of exports / counts.
- `isProxyNode(node: NodeModel): boolean` — Is this node a collapsed-group placeholder?
- `clearGroups(): void` — Clear all groups
- `addStroke(stroke: StrokeModel): void`
- `removeStroke(strokeId: string): StrokeModel | undefined`
- `restoreStroke(data: SerializedStroke): StrokeModel | undefined`
- `getStroke(strokeId: string): StrokeModel | undefined`
- `getStrokes(): StrokeModel[]`
- `clearStrokes(): void`
- `getVisibleStrokes(viewport: Rectangle): StrokeModel[]` — Strokes whose bounds overlap `viewport`. The ink layer's culling query.
- `getStrokesAlongSegment(a: Point, b: Point, tolerance = 0): StrokeModel[]` — Every stroke the pointer swept across travelling `a`→`b`. THE ERASER'S QUERY.

Segment-based, not point-based: a fast flick puts 80px between two pointermove
samples, and an eraser that only tested the samples would jump clean over a stroke
it visibly wiped through. Ask what the pointer TRAVELLED THROUGH, not where it
happened to land.
- `getAncestors(groupId: string): GroupModel[]` — Get a group's ancestor chain (nearest parent first), walking parentGroupId
upward. Robust against malformed self/looping pointers.
- `getDescendants(groupId: string): GroupModel[]` — Get every group nested (directly or transitively) inside `groupId`. Breadth-first over the parentGroupId back-pointers.
- `getDepth(groupId: string): number` — Nesting depth of a group: number of ancestors (0 for a top-level group).
- `getSelectedNodes(): NodeModel[]` — Get all selected nodes
- `selectNode(node: NodeModel): void` — Select a single node (clears previous selection)
- `addToSelection(node: NodeModel): void` — Add node to selection (multi-select)
- `removeFromSelection(node: NodeModel): void` — Remove node from selection
- `toggleNodeSelection(node: NodeModel): void` — Toggle node selection (add if not selected, remove if selected)
- `clearSelection(): void` — Clear all selections
- `selectAll(): void` — Select all nodes
- `deleteSelected(): number` — Delete all selected nodes and their connected links
- `getNodeAtPosition(x: number, y: number): NodeModel | undefined` — Get node at position (for click detection)
Returns the topmost node at the given position
- `isPointCoveredAbove(x: number, y: number, nodeId: string): boolean` — Is (x, y) inside any node ABOVE `nodeId` in z-order?

Same z contract as {@link getNodeAtPosition} (array order, topmost last),
same shape-aware containment. This is the occlusion oracle for PORTS: a
port whose anchor a higher node covers must neither paint nor accept
input — pre-fix, an overlapped node's port glyphs floated on top of the
covering node's body, and its hidden ports still won the hover/press race
through it (live report from stacked pasted nodes).
- `lockSelected(): number` — Option 3: Lock/pin selected nodes
Locked nodes will not move during layout operations
- `unlockSelected(): number` — Option 3: Unlock selected nodes
- `getLockedNodes(): NodeModel[]` — Option 3: Get locked nodes
- `unlockAll(): number` — Option 3: Unlock all nodes
- `setViewport(x: number, y: number, width: number, height: number, zoom?: number): void` — Set viewport
- `getViewport(): { x: number; y: number; width: number; height: number; zoom: number }` — Get current viewport
- `pan(dx: number, dy: number): void` — Pan viewport
- `zoom(delta: number, center?: Point): void` — Zoom viewport (relative adjustment)
- `setZoom(level: number, center?: Point): void` — Set absolute zoom level
Pan/Zoom controls
- `fitToView(padding: number = 100): void` — Fit viewport to show all nodes (without changing zoom level)
Pan/Zoom controls
- `zoomToFit(targetWidth: number, targetHeight: number, padding: number = 100): void` — Fit viewport to show all nodes AND adjust zoom to fit screen
Pan/Zoom controls
- `clear(): void` — Clear all nodes, links, and groups
- `getVisibleNodes(viewport: Rectangle): NodeModel[]` — Get nodes visible in viewport
This enables viewport virtualization - only render visible nodes
- `getVisibleLinks(viewport: Rectangle): LinkModel[]` — Get links visible in viewport
This enables viewport virtualization - only render visible links
- `findNearestPort( point: Point, options?: NearestPortOptions ): NearestPortHit | null` — The nearest port to a world point, served BY THE SPATIAL INDEX.

. This is the query a link drag makes on every
pointermove, so it is the one query that must never be a scan: the existing
answer (`PortModel.findNearestPort`) could only search ONE node — the one the
pointer happened to be over — because searching more would have meant walking
every node in the diagram. The index turns "which port am I near" into a
bounded region query, so a drag can snap to a port it is merely NEAR, not one
it is already on top of, without paying O(nodes) sixty times a second.

`portPosition` is injectable because THE ENGINE DOES NOT KNOW WHERE PORTS ARE. Its default (`getAbsolutePosition`) walks the bounding box — edge midpoints,
blind to the silhouette and to how many ports share a side — while the
renderer draws them shape-aware (`portWorldPosition`).
- `getVisibleBounds(viewport: Rectangle): Rectangle | null` — Get bounding box of all visible entities
Useful for "fit to viewport" operations
- `getDirtyNodes(): NodeModel[]` — Get all dirty nodes
Returns nodes that need re-rendering
- `getDirtyLinks(): LinkModel[]` — Get all dirty links
Returns links that need re-rendering
- `getDirtyGroups(): GroupModel[]` — Get all dirty groups
Returns groups that need re-rendering
- `markAllClean(): void` — Mark all entities as clean
Call this after rendering to reset dirty flags
- `getDirtyCount(): number` — Get total count of dirty entities
Useful for monitoring render performance
- `getVisibleDirtyNodes(viewport: Rectangle): NodeModel[]` — Get visible dirty nodes
Combines viewport virtualization with dirty marking
Only returns nodes that are both visible AND need re-rendering
- `getVisibleDirtyLinks(viewport: Rectangle): LinkModel[]` — Get visible dirty links
Combines viewport virtualization with dirty marking
Only returns links that are both visible AND need re-rendering
- `getLODLevel(zoom: number): LODLevel` — Get LOD level based on zoom

Driven by the declarative {@link LODConfig}. Picks the
tier whose `minZoom` the zoom crosses — tiers are pre-sorted highest-first,
so the first match wins. With the default config this is exactly:
  zoom >= 1.0        -> 'high'
  0.5 <= zoom < 1.0  -> 'medium'
  zoom <  0.5        -> 'low'
- `shouldRender(feature: LODFeature, lod: LODLevel): boolean` — Single feature gate that reads the active LOD tier's
feature set. Renderers call this instead of hardcoding `lod === 'high'`
checks, so custom tiers work automatically.
- `getLODConfig(): LODConfig` — Get the current Level-of-Detail policy.
- `setLODConfig(config: LODConfig): void` — Replace the Level-of-Detail policy wholesale. Apps use this to define
their own tiers (names, breakpoints and feature sets).
- `registerLODTier(tier: LODTier): void` — Register (or replace, by name) a single LOD tier. Lets apps extend the
default policy with an extra tier without rebuilding the whole config.
- `getNodesWithLOD(viewport: Rectangle, zoom: number): EntityWithLOD<NodeModel>[]` — Get visible nodes with LOD information
Combines viewport virtualization with Level of Detail
- `getLinksWithLOD(viewport: Rectangle, zoom: number): EntityWithLOD<LinkModel>[]` — Get visible links with LOD information
Combines viewport virtualization with Level of Detail
- `shouldRenderLabels(lod: LODLevel): boolean` — Check if labels should be rendered at this LOD level
Now reads the LOD tier's feature set.
- `shouldRenderIcons(lod: LODLevel): boolean` — Check if icons should be rendered at this LOD level
Now reads the LOD tier's feature set.
- `shouldRenderBorders(lod: LODLevel): boolean` — Check if borders should be rendered at this LOD level
Now reads the LOD tier's feature set.
- `shouldRenderShadows(lod: LODLevel): boolean` — Check if shadows should be rendered at this LOD level
Now reads the LOD tier's feature set.
- `getLayoutManager(): LayoutManager` — Get the layout manager for this diagram
- `setLayoutAlgorithm(type: LayoutAlgorithmType, config?: LayoutConfiguration): void` — Set layout algorithm
- `getLayoutAlgorithm(): LayoutAlgorithmType` — Get current layout algorithm type
- `configureLayout(config: LayoutConfiguration): void` — Configure current layout algorithm
- `getLayoutConfiguration(): LayoutConfiguration` — Get layout configuration
- `setAutoLayout(enabled: boolean): void` — Enable or disable automatic layout for new nodes
When enabled, newly added nodes will be automatically positioned using the current layout algorithm
- `isAutoLayoutEnabled(): boolean` — Check if auto-layout is enabled
- `async reLayout(config?: LayoutConfiguration): Promise<void>` — Re-layout all nodes using current algorithm
This will recalculate positions for all nodes in the diagram
- `override endBatch(): void` — Override: End batch update mode
Fires accumulated events when all batches complete
- `serialize(): SerializedDiagram` — Serialize to JSON
- `reconcilePortConnections(): Array<{ linkId: string; portId: string; end: 'source' | 'target' }>` — Rebuild the derived port-connection registries from the diagram's links.

`PortModel.currentConnections` is DERIVED state (which links touch this
port). It is never serialized; instead it is reconstructed
deterministically here so `canConnect()` / `maxConnections` enforcement
survive save/load. Runs inside fromJSON, and is safe to re-run at any
time — existing registries are reset first, so the result is always
exactly the current links.

A self-loop (source === target port) registers once — the Set dedupes —
so it counts as ONE connection on that port.
- `applyIncremental(patch: DiagramIncremental): void` — Apply an incremental patch (see serialization/Incremental.ts) — the
receive side of toIncremental/apply. Added entities are installed through
the SAME unified restore path as document load (fully wired); modified
entities are updated IN PLACE so object identity is preserved for
renderers holding references; normal change events fire (an applied
patch IS a mutation, unlike a document load).
- `static fromJSON(data: SerializedDiagram, options?: DiagramLoadOptions): DiagramModel` (static) — Deserialize from JSON — THE document load path.

Contract: a loaded diagram behaves identically to an authored one. Every entity is installed through the same install* wiring as
interactive creation (diagram back-refs, spatial indices, port index,
change-forwarding listeners), port registries are reconciled, and the
document is migrated to the current schema first. The load itself is
NOT a user mutation: per-entity events queued during the restore are
dropped, the change log ends empty, and `version` reports the SAVED
counter — then a single 'diagram:loaded' event fires.
- `override dispose(): void` — Dispose diagram and all child entities
Prevents memory leaks by:
- Disposing all nodes, links, and groups
- Breaking circular references
- Clearing spatial indices
- Calling parent dispose()

<!-- source: grafloria-engine-models-groupmodel.md -->

# GroupModel

Import it from `@grafloria/engine`.

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

```ts
class GroupModel extends DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `members` | `Set<string>` |  |  |
| `isCollapsed` | `boolean` | `false` |  |
| `bounds?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `layoutType` | `LayoutType` | `'none'` |  |
| `layoutConfig?` | `LayoutConfig` |  |  |
| `position` | `{ x: number; y: number }` |  |  |
| `size?` | `{ width: number; height: number; depth: number }` |  |  |
| `parentGroupId?` | `string` |  |  |
| `memberValidation?` | `MemberValidation` |  |  |
| `isHovered` | `boolean` | `false` |  |
| `padding?` | `GroupPadding` |  |  |
| `headerHeight` |  |  |  |
| `zIndex` |  | `0` |  |
| `fitMode` | `GroupFitMode` | `'exact'` |  |
| `constrainChildren` |  | `false` |  |
| `collapsedState?` | `CollapsedState` |  |  |
| `subgraphLayout?` | `SubgraphGroupConfig` |  |  |
| `laneConfig?` | `LaneConfig` |  |  |
| `membershipRule?` | `MembershipRule` |  |  |
| `capacity?` | `number` |  |  |

**Methods**

- `constructor(config: { id?: string; name: string })`
- `canAddMember(candidateId: string, diagram?: DiagramModel): boolean` — Whether `candidateId` may legally join this group. Rejects self-membership, ancestor cycles (adding an ancestor group as a
member would create a containment loop), and candidates failing the
per-group `memberValidation` predicate. Node candidates only run the
predicate check (nodes can't form group cycles).
- `getWipState(): { count: number; capacity?: number; state: 'unlimited' | 'under' | 'full' | 'over' }` — WIP state for the capacity limit. 'under' = room to spare,
'full' = exactly at the limit (the visual warning threshold), 'over' = past
it (only reachable by lowering capacity below the current count). Returns
'unlimited' when no capacity is set.
- `isOverCapacity(): boolean` — True when at or beyond the capacity limit (warning state).
- `setCapacity(capacity: number | undefined): void` — Set (or clear) the capacity / WIP limit, tracked for undo/diff.
- `addMember(entityId: string, diagram?: DiagramModel): void` — Add member to group.

When the member is itself a group, this establishes containment by setting
the child's `parentGroupId` (detaching it from any previous parent), which
keeps the nesting tree consistent for getAncestors/getDescendants. Members
that would create a cycle or fail `memberValidation` are rejected (no-op).
- `removeMember(entityId: string, diagram?: DiagramModel): boolean` — Remove member from group. When the member is a group whose parent is this
group, its `parentGroupId` back-pointer is cleared so the nesting tree
stays consistent.
- `setParent(newParentId: string | undefined, diagram?: DiagramModel): boolean` — Reparent this group under `newParentId` (or detach when undefined),
keeping both the `parentGroupId` pointer and the parents' `members` sets
consistent. Rejects cycles (a group cannot be nested under one of its own
descendants) and returns false without mutating anything.
- `setHovered(hovered: boolean): void` — Set transient drag-hover highlight state and notify listeners. Renderers/canvas can subscribe to 'hover:changed' to outline a drop target.
- `expand(): void` — Expand the group
- `collapse(): void` — Collapse the group
- `setCollapsedState(state: CollapsedState | undefined): void` — Set (or clear) the reversible collapse snapshot. Tracked as a
change so the incremental diff-capture serializes it and undo/redo see it.
- `setLayout(type: 'flexbox', config: FlexboxLayoutConfig): void` — Set layout configuration
- `setLayout(type: 'grid', config: GridLayoutConfig): void` — Set layout configuration
- `setLayout(type: 'flexbox' | 'grid', config: LayoutConfig): void` — Set layout configuration
- `clearLayout(): void` — Clear layout configuration
- `getLayout(): { type: LayoutType; config?: LayoutConfig }` — Get layout configuration
- `hasLayout(): boolean` — Check if group has layout configured
- `getFlexboxLayout(): FlexboxLayoutConfig` — Get layout as flexbox config
- `getGridLayout(): GridLayoutConfig` — Get layout as grid config
- `calculateBounds(diagram: DiagramModel): void` — Calculate bounds from member nodes using global bounds
- `getPadding(): { top: number; right: number; bottom: number; left: number }` — Resolve {@link padding} to a full four-sided rectangle. `undefined` (the
author never said) resolves to {@link DEFAULT_GROUP_PADDING}; an explicit
value — including the 0 that loaders pin for legacy documents — is taken
as written.
- `getOuterBounds(): GroupRect` — The group's outer frame rectangle in world coordinates. Prefers explicit
geometry (position + size) and falls back to the derived member `bounds`,
matching how GroupMembershipService hit-tests a group.
- `getInnerBounds(): GroupRect` — The rectangle members must stay inside: the outer frame minus padding and
minus the header band (which is reserved at the top). Never returns a
negative width/height.
- `fitToContents(diagram?: DiagramModel, options?: FitToContentsOptions): void` — Auto-fit the group frame to its members' bounding box plus padding and the
header band. This is the real consumer of `padding`/`headerHeight` that
`calculateBounds` (a tight, padding-free box) never was.

Member groups contribute their own OUTER frame (so a parent fits around a
nested group's full extent, not just its raw member points). With
`deepRecursive`, descendant groups are fitted first (deepest first) so the
parent fits around already-fitted children.

The computed content rectangle is reconciled with the current frame per the
effective fit mode (grow-only / shrink-only / exact) and written to both
`position`/`size` (authoritative geometry) and `bounds` (hit-test rect). No-op with no positioned members (nothing to fit around).
- `setFrame(rect: GroupRect): void` — Write a world rectangle into the group's authoritative geometry
(position + size) and the derived hit-test `bounds`, keeping the existing
`depth` when present. Tracks a single 'bounds' change for undo/diff.
- `clampChildToExtent(nodeId: string, diagram?: DiagramModel): boolean` — Clamp a member node so it stays fully inside the group's inner extent. No-op unless `constrainChildren` is set and the node is a direct member. Returns true when the node was actually moved. Absolute-coordinate model:
this adjusts the node's world position directly.
- `restoreGeometry(geo: { position: { x: number; y: number }; size?: { width: number; height: number; depth: number }; bounds?: GroupRect; }): void` — Restore raw geometry (position + optional size + bounds)
captured before a collapse. Unlike setFrame this permits size === undefined
so a group that had no explicit frame is restored to exactly that.
- `setZIndex(z: number): void` — Set the group's stacking index (lower renders further back).
- `bringToFront(diagram?: DiagramModel): void` — Bring this group in front of every other group (highest zIndex + 1). Minimal z-order API — the renderer honors zIndex ordering.
- `sendToBack(diagram?: DiagramModel): void` — Send this group behind every other group (lowest zIndex - 1).
- `isAutoLayoutEnabled(): boolean` — Is push-driven reflow active for this container?

DEFAULT ON for any group that declares a layout — a container that says
"I am a 12-column grid" and then lets its children drift is not a layout
container. `metadata('autoLayout')` survives as the explicit override:
set it to `false` to freeze the children (useful while dragging, or for a
container whose positions are authored by hand). Setting it to `true`
remains valid and is now simply the default.
- `requestLayout(diagram?: DiagramModel): void` — THE push entry point: "something changed, reflow if you are supposed to."
Distinct from {@link applyLayout}, which is the unconditional PULL — an
explicit `applyLayout()` still works on an opted-out container.
- `applyLayout(diagram?: DiagramModel): void` — Apply layout to member nodes
Positions child nodes based on flex or grid layout configuration
- `serialize(): SerializedGroup` — Serialize to JSON
- `static fromJSON(data: SerializedGroup): GroupModel` (static) — Deserialize from JSON

<!-- source: grafloria-engine-models-linkmodel.md -->

# LinkModel

Import it from `@grafloria/engine`.

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

```ts
class LinkModel extends DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram?` | `DiagramModel` |  | . Back-reference to the owning diagram, set by `DiagramModel.installLink`. Without this, read-only would have been unenforceable on exactly the edits the interaction controller performs most. |
| `sourcePortId` | `string` |  |  |
| `targetPortId` | `string` |  |  |
| `sourceNodeId?` | `string` |  |  |
| `targetNodeId?` | `string` |  |  |
| `pathType` | `'direct' \| 'orthogonal' \| 'smooth' \| 'bezier'` | `'smooth'` |  |
| `router?` | `LinkRouterName` |  | WHERE the line goes. When unset, derived from pathType — see {@link effectiveRouter}. Setting it does NOT touch pathType, so legacy consumers keep working; the explicit field simply wins. |
| `connector?` | `LinkConnectorName` |  | HOW the polyline is drawn. Unset = derived from pathType. |
| `points` | `Point[]` | `[]` |  |
| `segments` | `PathSegment[]` | `[]` |  |
| `labels` | `LinkLabel[]` | `[]` |  |
| `state` | `'default' \| 'selected' \| 'hovered' \| 'highlighted'` | `'default'` |  |
| `style` | `Partial<LinkStyle>` | `{}` |  |
| `data` | `Record<string, any>` | `{}` |  |
| `isSourceEndpointSelected` | `boolean` | `false` | Whether source endpoint handle is selected Used for dragging endpoint to reconnect |
| `isTargetEndpointSelected` | `boolean` | `false` | Whether target endpoint handle is selected Used for dragging endpoint to reconnect |
| `DEFAULT_CURVATURE` (static) (not released yet) |  | `0.5` | The curve tightness of a smooth/bezier link. |

**Methods**

- `constructor( sourcePortId: string, targetPortId: string, pathType?: 'direct' | 'orthogonal' | 'smooth' | 'bezier' )`
- `isSelfLoop(): boolean` — Is this link a SELF-LOOP, i.e. do both
ends live on the same node?

Reads the cached owning-node ids, which `DiagramModel.installLink` backfills
for every link that reaches a diagram (including ones built with
`new LinkModel()` + `addLink`, which carry no ids of their own). A link that
has never been installed has no ids and is — correctly — not a self-loop as
far as anything can tell.

A self-loop between two DIFFERENT ports of the same node counts, and so does
one that starts and ends on the SAME port.
- `getNodePairKey(): string | null` — The unordered node pair this link connects, as a stable
key. UNORDERED on purpose: A→B and B→A are the same visual bundle and must
fan out together, or a bidirectional pair would draw both links on the same
centre line. Returns null when the owning nodes are unknown.
- `setSourcePort(portId: string, nodeId?: string): void` — Set source port
- `setTargetPort(portId: string, nodeId?: string): void` — Set target port
- `setPathType(pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier'): void` — Set path type
- `setRouter(router: LinkRouterName | undefined): void` — Set the routing geometry explicitly. Clears the cached route the
same way setPathType does — the old polyline belongs to the old router.
- `setConnector(connector: LinkConnectorName | undefined): void` — Set the polyline rendering explicitly. Pure re-render; the routed
points are still valid, so the cache is NOT cleared.
- `effectiveRouter(): LinkRouterName` — The router actually in force: the explicit field, else derived from
pathType exactly as the renderer always derived it (direct → straight,
orthogonal → orthogonal, smooth/bezier → straight-with-curved-rendering).
- `effectiveConnector(): LinkConnectorName` — The connector actually in force: the explicit field, else implied by an
explicitly axis-aligned ROUTER, else derived from pathType.

The router rung exists because `{ router: 'orthogonal' }` with the default
pathType used to draw a smooth SPLINE through Manhattan waypoints — the
route was orthogonal, the picture was wavy (the screenshot audit caught the
demo's own readout saying "orthogonal" over a curve). Asking for an
axis-aligned router IS asking for axis-aligned rendering; rounded corners
are that family's standard look. An explicit `connector` still overrides.
- `setPoints(points: Point[]): void` — Set points for custom path
- `addPoint(point: Point, index?: number): void` — Add point to path
- `removePoint(index: number): Point | undefined` — Remove point from path
- `generatePath( sourcePoint: Point, targetPoint: Point, sourceDirection?: 'left' | 'right' | 'top' | 'bottom', targetDirection?: 'left' | 'right' | 'top' | 'bottom' ): void` — Generate path based on type
- `getCurvature(): number`
- `addLabel( label: Partial<LinkLabel> & { text: string } & ( | { position: number } | { slot: NonNullable<LinkLabel['slot']> } ) ): void` — Add label

`position` is no longer required when the label names a
`slot` — and every other LinkLabel field (html, template, slot, autoOffset,
rotation…) is now carried through instead of being silently dropped. The old
body hand-copied five fields, so a label created here could not be an HTML
label, could not auto-rotate and could not opt into auto-placement.
- `removeLabel(labelId: string): LinkLabel | undefined` — Remove label by ID
- `removeLabelAt(index: number): LinkLabel | undefined` — Remove label by index
- `updateLabel(index: number, updates: Partial<LinkLabel>): void` — Update label by index
- `setLabels(labels: LinkLabel[]): void` — REPLACE the whole label collection — the write `addLabel`/`updateLabel` cannot express.

`SetLinkLabelsCommand` used to do this by assigning `link.labels` directly on BOTH
execute and undo. A plain field write does not pass `trackChange()` — the one funnel
collab captures from — so the command emitted ZERO ops in BOTH directions: authoring
a link's labels was invisible to every other peer, and so was taking it back. (The
`UpdateLinkStyleCommand` defect at least emitted one op on execute; this emitted none
at all.) `replaceStyle` is the same seam for the same reason.
- `override getLabel(): string | undefined` — Overloaded label read.

- `getLabel()` — no argument — is the CANONICAL display-label accessor
  inherited from DiagramEntity (metadata.label, with the legacy
  data['label'] fallback). It is what the DSL generator exports and what
  feeds the renderer's simple edge label (svg-renderer reads
  link.getMetadata('label')).
- `getLabel(labelId)` is the pre-existing lookup into the POSITIONED
  multi-label API (`labels: LinkLabel[]` / addLabel / updateLabel), a
  different feature that happens to share the verb. The overload keeps
  both callable without forking the canonical name.
- `override getLabel(labelId: string): LinkLabel | undefined` — Overloaded label read.

- `getLabel()` — no argument — is the CANONICAL display-label accessor
  inherited from DiagramEntity (metadata.label, with the legacy
  data['label'] fallback). It is what the DSL generator exports and what
  feeds the renderer's simple edge label (svg-renderer reads
  link.getMetadata('label')).
- `getLabel(labelId)` is the pre-existing lookup into the POSITIONED
  multi-label API (`labels: LinkLabel[]` / addLabel / updateLabel), a
  different feature that happens to share the verb. The overload keeps
  both callable without forking the canonical name.
- `override getLabel(labelId?: string): string | LinkLabel | undefined` — Overloaded label read.

- `getLabel()` — no argument — is the CANONICAL display-label accessor
  inherited from DiagramEntity (metadata.label, with the legacy
  data['label'] fallback). It is what the DSL generator exports and what
  feeds the renderer's simple edge label (svg-renderer reads
  link.getMetadata('label')).
- `getLabel(labelId)` is the pre-existing lookup into the POSITIONED
  multi-label API (`labels: LinkLabel[]` / addLabel / updateLabel), a
  different feature that happens to share the verb. The overload keeps
  both callable without forking the canonical name.
- `setState(state: 'default' | 'selected' | 'hovered' | 'highlighted'): void` — Set state
- `updateStyle(style: Partial<LinkStyle>): void` — Update style
- `replaceStyle(style: Partial<LinkStyle>): void` — REPLACE the whole style object — the write `updateStyle` cannot express.

`updateStyle` merges, so it can never REMOVE a key; restoring a snapshot has to
assign wholesale. `UpdateLinkStyleCommand.undo()` used to do that with a direct
field write (`link.style = restored`), which never passes `trackChange()` — the
single funnel collab captures from. Measured: execute emitted 1 op, undo emitted 0,
so every peer kept the styled link forever while the author saw it correctly
reverted. See collab/style-undo.spec.ts.
- `setData(key: string, value: any): void` — Set data property
- `getData(key: string): any` — Get data property
- `reconnectSource(newPortId: string, newNodeId?: string): void` — Reconnect source endpoint to new port
Used for link reconnection workflow
- `reconnectTarget(newPortId: string, newNodeId?: string): void` — Reconnect target endpoint to new port
Used for link reconnection workflow
- `getSourceEndpoint(): Point` — Get source endpoint position
Returns the first point in the path (source end)
- `getTargetEndpoint(): Point` — Get target endpoint position
Returns the last point in the path (target end)
- `selectSourceEndpoint(): void` — Select source endpoint handle
- `selectTargetEndpoint(): void` — Select target endpoint handle
- `deselectEndpoints(): void` — Deselect all endpoint handles
- `hasSelectedEndpoint(): boolean` — Check if any endpoint is selected
- `getPointAtPosition(t: number): Point | null` — Get point at position along link (0-1)
- `getTotalLength(): number` — Get total path length
- `getLength(): number` — Get path length (alias for getTotalLength for API consistency)
- `getTangentAt(t: number): Point | null` — Get tangent (direction vector) at position along path (0-1)
Returns normalized direction vector
- `getNormalAt(t: number): Point | null` — Get normal (perpendicular vector) at position along path (0-1)
Returns normalized perpendicular vector (90° counter-clockwise from tangent)
- `getClosestPoint(point: Point): { point: Point; distance: number; t: number } | null` — Get closest point on path to a given point
Returns the closest point, distance, and normalized position (t)
- `getAngleAt(t: number): number | null` — Get angle at position along path (0-1) in degrees
Useful for label rotation
- `override serialize(): SerializedLink` — Serialize to JSON
- `static fromJSON(data: SerializedLink): LinkModel` (static) — Deserialize from JSON

<!-- source: grafloria-engine-models-nodemodel.md -->

# NodeModel

Import it from `@grafloria/engine`.

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

```ts
class NodeModel extends DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram?` | `DiagramModel` |  |  |
| `position` | `Point` |  |  |
| `size` | `Size` |  |  |
| `rotation` | `number` | `0` |  |
| `scale` | `Point` |  |  |
| `positionMode` | `PositioningMode` | `'absolute'` |  |
| `transformOrigin` | `Point` |  |  |
| `zIndex?` | `number` |  | C — model-level stacking order (lower renders further back). |
| `flexConfig?` | `FlexItemConfig` |  |  |
| `gridConfig?` | `GridItemConfig` |  |  |
| `portRenderingConfig?` | `any` |  |  |
| `dragHandlerConfig?` | `any` |  |  |
| `connectionGroup?` | `string` |  |  |
| `type` | `string` |  |  |
| `systemType?` | `string` |  |  |
| `definitionId?` | `string` |  |  |
| `parentId?` | `string` |  |  |
| `children` | `Set<string>` |  |  |
| `depth` | `number` | `0` |  |
| `ports` | `Map<string, PortModel>` |  |  |
| `state` | `NodeState` |  |  |
| `behavior` | `NodeBehavior` |  |  |
| `style` | `Partial<NodeStyle>` | `{}` |  |
| `classes` | `Set<string>` |  |  |
| `data` | `Record<string, any>` | `{}` |  |
| `computed` | `Map<string, any>` |  |  |

**Methods**

- `constructor(config: { id?: string; type: string; position: Point; size?: Size; systemType?: string; definitionId?: string; })`
- `setPosition(x: number, y: number, z?: number): void` — Set position
- `move(dx: number, dy: number, dz?: number): void` — Move by delta
- `setSize(width: number, height: number, depth?: number): void` — Set size.

A node growing inside a
flex/grid container is a layout-invalidating event: its siblings have to move.

It notifies its LAYOUT CONTAINERS, and deliberately NOT the transform chain
`setPosition` uses: a parent's size does not move a relative child (the child's
offset is measured from the parent ORIGIN), so emitting `transform-propagated`
here would be noise that says something untrue.
- `resize(dw: number, dh: number, dd?: number): void` — Resize by delta
- `setRotation(degrees: number): void` — Set rotation
- `rotate(degrees: number): void` — Rotate by delta
- `setScale(x: number, y: number): void` — Set scale
- `addPort(port: PortModel): void` — Add port
- `removePort(portId: string): PortModel | undefined` — Remove port
- `getPort(portId: string): PortModel | undefined` — Get port by ID
- `getPorts(): PortModel[]` — Get all ports
- `getIncomingLinks(): import('./LinkModel').LinkModel[]` — Links arriving at this node (resolved through the owning diagram; empty
when the node isn't attached to a diagram yet)
- `getOutgoingLinks(): import('./LinkModel').LinkModel[]` — Links leaving this node (resolved through the owning diagram)
- `getPortsByType(type: 'input' | 'output' | 'bi'): PortModel[]` — Get ports by type
- `getPortBySide(side: 'top' | 'right' | 'bottom' | 'left'): PortModel | undefined` — Get port by side
Returns the first port found on the specified side
- `getPortsBySide(side: 'top' | 'right' | 'bottom' | 'left'): PortModel[]` — Get all ports on a specific side
Useful for nodes with multiple ports per side
- `getAvailablePorts(type?: 'input' | 'output' | 'bi'): PortModel[]` — Get available ports that can accept connections
- `getConnectedPorts(): PortModel[]` — Get ports that have active connections
- `setState(state: Partial<NodeState>): void` — Set state property
- `replaceState(state: Partial<NodeState>): void` — REPLACE the DOCUMENT half of `state`, keeping THIS viewer's own view half.

The write `setState` cannot express, and the collab reducer's write path.

## Why a merge was wrong

`state` is a value register: the op carries the whole (projected) object the author
now holds. Applying it with the merging `setState` meant a peer could GAIN a key and
never LOSE one — `NodeState.error`, `warning`, `status` and `animateStatus` are all
optional, so the author clears an error badge and every other peer keeps it FOREVER,
with no later edit able to correct it. Node `style` had exactly this defect and was
fixed with `replaceStyle`; this is the same fix for the register next to it.

## Why it is not a plain wholesale replace either

`selected` / `hovered` / `highlighted` / `focused` are facts about a VIEWER, not about
the document. Capture strips them (see collab/capture.ts — syncing them meant your
cursor lit up my node and your click deselected it), so an incoming register value
never carries them. Replacing wholesale would therefore BLANK the receiving user's own
selection on every remote state edit — reintroducing the very bug through the back
door. So: durable keys replaced wholesale, view keys taken from what this replica
already had.

## The read-only posture, deliberately UNCHANGED

This refuses outright while the document is locked, exactly like `setPosition`,
`setStyle` and `replaceStyle`.

• That filter exists so a LOCAL user can still select, hover and keyboard-navigate a
    presentation-mode diagram. It is about input, not about the wire.
  • It would be a no-op here anyway: capture strips the view keys, so an incoming
    `state` value contains none of the keys the filter admits — a locked replica
    already dropped remote state ops entirely, before this method existed. Behaviour
    is therefore identical, and `setState` is left untouched.
  • Making `state` the one register that DID reach a locked replica would be
    incoherent: a read-only replica currently applies no remote document write at all
    (verified — a locked peer ignores remote `position` and `style` too). That gap is
    real and systemic, and it belongs to the lock, not to this register.
- `setBehavior(behavior: Partial<NodeBehavior>): void` — Set behavior property
- `isSelected(): boolean` — Check if node is selected
- `setSelected(selected: boolean): void` — Set selection state
- `isHighlighted(): boolean` — Check if node is highlighted (attention state, independent of selection)
- `setHighlighted(highlighted: boolean): void` — Set highlight state (attention emphasis without selecting the node)
- `isSelectable(): boolean` — Check if node is selectable (based on behavior)
Note: Locked nodes are still selectable so users can unlock them
- `isDraggable(): boolean` — Check if node is draggable (based on behavior and state)
Note: Locked nodes cannot be dragged
- `setStyle(style: Partial<NodeStyle>): void` — Set style property
- `replaceStyle(style: Partial<NodeStyle>): void` — REPLACE the whole style object — the write `setStyle` cannot express.

`setStyle` merges, so it can add a key and overwrite a key but can never REMOVE
one. Restoring a snapshot therefore has to assign wholesale, and the obvious way to
do that — `node.style = snapshot` — is a plain field write that never passes
`trackChange()`. That funnel is what collab captures from, so the direct assignment
reaches the renderer (via markDirty) and reaches no other peer at all. That is not
hypothetical: it is exactly how an undone LINK style stayed applied on every peer
but the one that pressed Ctrl+Z. See collab/style-undo.spec.ts.

Undo paths must use this, not the field.
- `addClass(className: string): void` — Add CSS class
- `removeClass(className: string): void` — Remove CSS class
- `setClasses(classNames: string[]): void` — REPLACE the whole class collection.

`classes` is a `Set`, so it needs the same treatment `members` and `ports` needed: a
register whose in-memory form is a collection and whose wire form is an array must be
REBUILT on the receiving side, never assigned. The collab reducer writes it through
here.

A non-array is REFUSED rather than read as "no classes" — logs persisted before the
funnel fix carry a bare class name (the old addClass) or a bare `null` (the old
removeClass), and assigning either is what corrupted the Set in the first place.
- `setData(key: string, value: any): void` — Set data property
- `getData(key: string): any` — Get data property
- `setComputed(key: string, value: any): void` — Set computed property
- `getComputed(key: string): any` — Get computed property
- `getWorldPosition(): Point` — Get world position (absolute coordinates accounting for parent chain)
For nodes without parents, this is the same as position
For child nodes, this walks up the parent chain and accumulates offsets
- `getBoundingBox(): BoundingBox` — Get bounding box in world coordinates
For child nodes, this accounts for parent position
- `getCenter(): Point` — Get center point in world coordinates
- `containsPoint(point: Point): boolean` — Check if point is inside node
- `intersectsBounds(bounds: BoundingBox): boolean` — Check if intersects with bounding box
- `setParent(parentId: string | undefined): void` — Set parent
- `addChild(childId: string): void` — Add child
- `removeChild(childId: string): void` — Remove child
- `setChildren(childIds: string[]): void` — REPLACE the whole child collection. The collab reducer's write path.

Same contract as {@link setClasses}: a Set in memory, an array on the wire, rebuilt
rather than assigned, and a non-array refused so a pre-fix log degrades instead of
destroying the collection.

This maintains only its own half of the hierarchy, exactly as `addChild`/`removeChild`
do — the child's `parentId` is its own register with its own op.
- `setTransformOrigin(x: number, y: number): void` — Set transform origin
- `getAbsoluteTransformOrigin(): Point` — Get absolute transform origin in pixels
- `getLocalPosition(): Point` — Get local position
Returns the position property as-is
- `getGlobalPosition(): Point` — Get global position
In absolute mode: returns position as-is
In relative mode: transforms position by parent's hierarchy transform
- `setLocalPosition(x: number, y: number, z?: number): void` — Set local position
Sets position directly and switches to relative mode
- `setGlobalPosition(x: number, y: number, z?: number): void` — Set global position
Converts global coordinates to local if parent exists
- `getLocalTransformMatrix(): TransformMatrix` — Get local transform matrix
Composes translation, rotation, and scale relative to transform origin
- `getGlobalTransformMatrix(): TransformMatrix` — Get global transform matrix
In absolute mode: returns local matrix
In relative mode: composes parent's global matrix with local matrix
- `getGlobalBounds(): BoundingBox` — Get global bounding box
Calculates bounds by transforming all 4 corners through global matrix
- `getChildren(): NodeModel[]` — Get direct children nodes
- `getParent(): NodeModel | undefined` — Get parent node
Public version of getParentNode
- `getAncestors(): NodeModel[]` — Get all ancestor nodes up to root
Returns array with direct parent first, then grandparent, etc.
- `getDescendants(): NodeModel[]` — Get all descendant nodes recursively
- `getRoot(): NodeModel` — Get root node of hierarchy
Returns self if this is the root
- `getSiblings(): NodeModel[]` — Get sibling nodes (same parent, excluding self)
- `isAncestorOf(nodeId: string): boolean` — Check if this node is an ancestor of another node
- `getDepth(): number` — Get depth in hierarchy
Root nodes have depth 0, their children have depth 1, etc.
- `validateHierarchy(): boolean` — Validate hierarchy for circular references
- `updateHierarchyDepth(): void` — Update depth for this node and all descendants
Recalculates depth values based on current hierarchy
- `getAffectedByTransform(): NodeModel[]` — Get all nodes affected by transform changes
Returns this node plus all descendants in relative positioning mode
- `getEffectiveZIndex(): number` — The stacking index a renderer should paint by.

Precedence is explicit-model-field → legacy `style.zIndex` → 0. That ordering
is the whole compatibility story: diagrams that restacked via style keep
working untouched, and the moment a node states a model z-index it wins — so
`setZIndex(1)` on a node styled `zIndex: 4` does what it says instead of
silently losing to a stylesheet.
- `setZIndex(z: number | undefined): void` — Set the stacking index (lower renders further back). Tracked for undo/diff.
- `bringToFront(diagram?: DiagramModel): void` — Bring this node in front of every other node in the diagram. Falls back to a relative bump when the node is detached, exactly as
`GroupModel.bringToFront` does.
- `sendToBack(diagram?: DiagramModel): void` — Send this node behind every other node in the diagram.
- `setFlexItem(config: FlexItemConfig): void` — Set flexbox item configuration
- `clearFlexItem(): void` — Clear flexbox item configuration
- `getFlexItem(): FlexItemConfig | undefined` — Get flexbox item configuration
- `hasFlexItem(): boolean` — Check if node has flex item configuration
- `setGridItem(config: GridItemConfig): void` — Set grid item configuration
- `clearGridItem(): void` — Clear grid item configuration
- `getGridItem(): GridItemConfig | undefined` — Get grid item configuration
- `hasGridItem(): boolean` — Check if node has grid item configuration
- `setPortRenderingConfig(config: any): void` — Set port rendering configuration
- `getPortRenderingConfig(): any | undefined` — Get port rendering configuration
- `getPortRenderingMode(): 'svg' | 'html' | 'auto'` — Get port rendering mode
Auto-detects based on configuration and metadata
- `setDragHandlerConfig(config: any): void` — Set drag handler configuration
- `getDragHandlerConfig(): any | undefined` — Get drag handler configuration
- `isDragHandler(): boolean` — Check if this node is a drag handler
- `setConnectionGroup(group: string): void` — Set connection group
- `getConnectionGroup(): string | undefined` — Get connection group
- `serialize(): SerializedNode` — Serialize to JSON
- `static fromJSON(data: SerializedNode): NodeModel` (static) — Deserialize from JSON

<!-- source: grafloria-engine-models-portmodel.md -->

# PortModel

Import it from `@grafloria/engine`.

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

```ts
class PortModel extends DiagramEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` | `''` |  |
| `type` | `'input' \| 'output' \| 'bi'` |  |  |
| `systemType?` | `string` |  |  |
| `position` | `PortPosition` |  |  |
| `alignment` | `PortAlignment` |  |  |
| `offset` | `Point` |  |  |
| `index` | `number` | `0` |  |
| `maxConnections` | `number` |  |  |
| `currentConnections` | `Set<string>` |  |  |
| `allowedTypes` | `Set<string>` |  |  |
| `linkRoles` | `Map<string, 'source' \| 'target'>` |  | Which END of each attached link this port is — `linkId → 'source'\|'target'`. |
| `visible` | `boolean` | `true` |  |
| `style` | `Record<string, any>` | `{}` |  |
| `data` | `Record<string, any>` | `{}` |  |
| `group?` | `string` |  | Named port group. Its config is inherited; these fields override it. |
| `explicitSide` | `boolean` | `false` | Was the side actually declared by the author? A port that only says `group: 'in'` must inherit the GROUP's side — without this flag the constructor's `alignment.side = 'right'` default would silently win. |
| `shape?` | `PortShapeSpec` |  | Non-circle glyph: square / diamond / triangle / custom SVG path. |
| `label?` | `PortLabelSpec` |  | Port label + its layout mode. |
| `layout?` | `PortLayoutSpec` |  | Layout strategy override. Unset → the shape registry's anchor. |
| `fromSpot?` | `PortSpot` |  | Where a link leaves / lands on the glyph. |
| `toSpot?` | `PortSpot` |  |  |
| `spread?` | `PortSpreadSpec` |  | Spread multiple links along this port's edge instead of piling them. |
| `dataType?` | `string` |  | Declarative data type: drives link validity AND glyph colour. |
| `isConnectableStart?` | `boolean` |  | May a link START at this port? Unset → true. |
| `isConnectableEnd?` | `boolean` |  | May a link END at this port? Unset → true. |
| `fromMaxLinks?` | `number \| null` |  | Cap on OUTGOING links. null/unset → unlimited. |
| `toMaxLinks?` | `number \| null` |  | Cap on INCOMING links. null/unset → unlimited. |
| `allowSelfLink?` | `boolean` |  | Allow a link whose source node IS its target node. Unset → false. |
| `allowDuplicateLinks?` | `boolean` |  | Allow a second link between the same ordered port pair. Unset → true. |
| `dynamic?` | `boolean` |  | Spawned by the dynamic auto-port allocator rather than authored. |
| `renderingConfig?` | `any` |  |  |
| `isHovered` | `boolean` | `false` | Whether mouse is currently hovering over this port Used for visual feedback (scaling, highlighting) |
| `isHighlighted` | `boolean` | `false` | Whether this port is highlighted as a valid connection target Set during connection drag operations |
| `isValidTarget` | `boolean` | `false` | Whether this port is a valid target for current connection Set by ConnectionStateManager during drag |

**Methods**

- `constructor(config: { id?: string; type: 'input' | 'output' | 'bi'; systemType?: string; position?: PortPosition; alignment?: PortAlignment; side?: 'left' | 'right' | 'top' | 'bottom'; index?: number; maxConnections?: number; group?: string; shape?: PortShapeSpec; label?: PortLabelSpec; layout?: PortLayoutSpec; fromSpot?: PortSpot; toSpot?: PortSpot; spread?: PortSpreadSpec; style?: Record<string, any>; visible?: boolean; dataType?: string; isConnectableStart?: boolean; isConnectableEnd?: boolean; fromMaxLinks?: number | null; toMaxLinks?: number | null; allowSelfLink?: boolean; allowDuplicateLinks?: boolean; allowedTypes?: string[]; dynamic?: boolean; })`
- `get side(): 'left' | 'right' | 'top' | 'bottom'` — Get the side this port is on (convenience getter)
Set the side this port is on (convenience setter)
- `set side(value: 'left' | 'right' | 'top' | 'bottom')` — Get the side this port is on (convenience getter)
Set the side this port is on (convenience setter)
- `setPosition(position: PortPosition): void` — Set position
- `setAlignment(alignment: PortAlignment): void` — Set alignment
- `setOffset(offset: Point): void` — Set offset
- `addAllowedType(type: string): void` — Add allowed type
- `removeAllowedType(type: string): void` — Remove allowed type
- `isTypeAllowed(type: string): boolean` — Check if type is allowed
- `addConnection(linkId: string, role?: 'source' | 'target'): void` — Add connection
- `restoreConnection(linkId: string, role?: 'source' | 'target'): void` — Load-time reconcile: register a connection WITHOUT the maxConnections
guard or change tracking. The connection registry is derived state that
is rebuilt deterministically from the diagram's links on load — a
persisted graph may legitimately exceed a since-tightened maxConnections,
so enforcement applies to NEW interactive connections (addConnection),
never to reloading saved state.
- `removeConnection(linkId: string): void` — Remove connection
- `canConnect(): boolean` — Check if can accept more connections
- `getConnectionCount(): number` — Get connection count
- `getFromLinkCount(): number` — How many links LEAVE this port / how many ARRIVE at it.

A self-loop that both starts and ends here registers once in
`currentConnections` (the Set dedupes) but `linkRoles` can only hold one
role for it, so it is counted on whichever end was registered last. That is
acceptable — a port that allows self-links and also caps its directional
fan-out is pathological, and the TOTAL `maxConnections` cap still holds.
- `getToLinkCount(): number`
- `canConnectTo(targetPort: PortModel): boolean` — Check if this port (as the SOURCE) can connect to `targetPort` (as the
TARGET). Direction matters — this is not a symmetric predicate.

Rules:
- input can connect to output or bi
- output can connect to input or bi
- bi can connect to any

`isConnectableStart` on
the source, `isConnectableEnd` on the target, the per-direction
`fromMaxLinks`/`toMaxLinks` caps, the `allowedTypes` whitelist (which was
dead config — `isTypeAllowed` had no caller anywhere in the tree) and
`dataType` compatibility.

NOTE: this is the PORT-LOCAL rule. Rules that need the graph (self-links,
duplicate links, connection groups) live in `evaluatePortConnection()`,
which folds this in.
- `typeIdentity(): string` — The name this port answers to when another port's `allowedTypes` whitelist
is checked: its declared data type, else its systemType, else its direction.
- `getAbsolutePosition(nodeBounds: BoundingBox): Point` — Get absolute position relative to node
- `getEdgePosition(nodeBounds: BoundingBox): Point` — Get port position at node edge (for smart mode)
Returns the position at the edge midpoint based on alignment
- `static findNearestPort( point: Point, ports: Map<string, PortModel>, nodeBounds: BoundingBox ): PortModel | null` (static) — Find nearest port on a node to a given point
Used in smart mode for auto-connect to nearest port
- `getDistanceFromPoint(point: Point, nodeBounds: BoundingBox): number` — Calculate distance from point to this port
- `resetInteractionState(): void` — Reset interaction state
Called when connection drag ends or is cancelled
- `setRenderingConfig(config: any): void` — Set port rendering configuration from template
- `getRenderingConfig(): any | undefined` — Get port rendering configuration
- `getEffectiveVisibility( node: any, globalDefault?: 'always' | 'on-hover' | 'never' | 'hidden' ): 'always' | 'on-hover' | 'never' | 'hidden'` — Get effective visibility considering port and node configuration
Priority: port config > node metadata > default ('on-hover')
- `serialize(): SerializedPort` — Serialize to JSON
- `static fromJSON(data: SerializedPort): PortModel` (static) — Deserialize from JSON

<!-- source: grafloria-engine-models-serializedport.md -->

# SerializedPort

Import it from `@grafloria/engine`.

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

```ts
interface SerializedPort extends SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `type` | `'input' \| 'output' \| 'bi'` |  |  |
| `systemType?` | `string` |  |  |
| `position` | `PortPosition` |  |  |
| `alignment` | `PortAlignment` |  |  |
| `offset` | `Point` |  |  |
| `index` | `number` |  |  |
| `maxConnections` | `number \| null` |  |  |
| `allowedTypes` | `string[]` |  |  |
| `visible` | `boolean` |  |  |
| `style` | `Record<string, any>` |  |  |
| `data` | `Record<string, any>` |  |  |
| `renderingConfig?` | `any` |  |  |
| `group?` | `string` |  |  |
| `explicitSide?` | `boolean` |  | Was `side`/`alignment` explicitly declared (vs. inherited from a group)? |
| `shape?` | `PortShapeSpec` |  |  |
| `label?` | `PortLabelSpec` |  |  |
| `layout?` | `PortLayoutSpec` |  |  |
| `fromSpot?` | `PortSpot` |  |  |
| `toSpot?` | `PortSpot` |  |  |
| `spread?` | `PortSpreadSpec` |  |  |
| `dataType?` | `string` |  |  |
| `isConnectableStart?` | `boolean` |  |  |
| `isConnectableEnd?` | `boolean` |  |  |
| `fromMaxLinks?` | `number \| null` |  | null = unlimited (mirrors the `maxConnections` sentinel). |
| `toMaxLinks?` | `number \| null` |  |  |
| `allowSelfLink?` | `boolean` |  |  |
| `allowDuplicateLinks?` | `boolean` |  |  |
| `dynamic?` | `boolean` |  | True for ports spawned by the dynamic auto-port allocator. |

<!-- source: grafloria-engine-models-strokemodel.md -->

# StrokeModel

Import it from `@grafloria/engine`.

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

A freehand ink stroke: an ordered point list, a style, and an identity.

A first-class `DiagramEntity`, which is not a formality — it is what makes every
other gate in this wave close for free:
  • `trackChange()` → `markDirty()` → the GLOBAL MUTATION EPOCH, which is the thing
    both frame gates read (`svg-renderer.ts:795`, `create-diagram.ts:369`). A stroke
    that were a plain object would mutate the picture without moving the epoch, and
    both gates would skip the frame: you would draw and see nothing.
  • `on('change')` → `OpCapture` picks it up through the same funnel as everything
    else. No parallel bookkeeping to drift out of step.
  • `serialize()`/`dispose()`/`version` → the document contracts.

```ts
class StrokeModel extends DiagramEntity
```

**Methods**

- `constructor( points: readonly StrokePoint[] = [], style: StrokeStyle = DEFAULT_STROKE_STYLE, options: { id?: string; uuid?: string; label?: string } = {} )`
- `getPoints(): readonly StrokePoint[]`
- `setPoints(points: readonly StrokePoint[]): void` — Replace the geometry.

Emits `trackChange('points', …)` like any other register. NOTE that capture used
to drop EVERY `points` change on the floor (`DERIVED = new Set(['points'])`),
because on a LINK `points` is routed geometry that each peer recomputes for
itself. On a stroke `points` is the authored content itself. That set is now
scoped per target — see `collab/capture.ts`. Without that fix, editing a stroke's
geometry would silently fail to reach any other peer.
- `get pointCount(): number`
- `getBounds(): Rectangle` — Axis-aligned bounds, INFLATED by the stroke's own half-width (ink has girth).
- `hitTest(x: number, y: number, tolerance = 0): boolean` — Is `(x, y)` on the ink, within `tolerance` world units of it?
- `intersectsSegment(a: Point, b: Point, tolerance = 0): boolean` — Did a pointer travelling `a`→`b` sweep across this ink? THE ERASER'S QUESTION. Segment-vs-segment, not point-vs-segment — see {@link segmentDistance}.
- `getStyle(): Readonly<StrokeStyle>`
- `setStyle(style: Partial<StrokeStyle>): void`
- `replaceStyle(style: Partial<StrokeStyle>): void` — REPLACE the whole style object — the write `setStyle` cannot express, and the collab
reducer's write path.

`setStyle` MERGES, so applying a `style` op with it meant a peer could gain a key and
never lose one: the author clears an `opacity` and every other peer keeps the faded
stroke forever. `NodeModel.replaceStyle` is the same seam for the same reason, and a
plain field assignment is not a substitute — it would skip the `bounds` invalidation
below and leave the peer measuring the stroke at its old width.
- `override getLabel(): string | undefined` — The accessible name, when the author gave one. See the a11y note on the
ink layer. Overrides the DiagramEntity canon (metadata.label): a stroke's
label lives in its own serialized `label` property, not the metadata bag.
- `override setLabel(label: string | undefined): void` — CANONICAL label write. Writes `metadata.label` (tracked → dirty → repaint)
and mirrors into the legacy `data['label']` slot when the entity has a
data bag, so any reader still on the old field sees the same value. The
mirror is a shadow: metadata is authoritative on every read path.
- `serialize(): SerializedStroke` — Serialize entity to JSON
- `static fromJSON(data: SerializedStroke): StrokeModel` (static)
- `static fromRawPoints( raw: readonly StrokePoint[], style: StrokeStyle = DEFAULT_STROKE_STYLE, options: { id?: string; label?: string; epsilon?: number } = {} ): StrokeModel` (static) — Build a stroke from a RAW POINTER TRACE. This is the only constructor the draw tool
uses, and the simplification is not optional decoration.

A two-second scribble at 120Hz is ~240 samples, most of them a fraction of a pixel
apart. Persisting them all means a document that is mostly float noise, an op
payload that is kilobytes per line, and an SVG path the browser re-parses on every
frame. The brief's phrasing is exactly right: a 500-point stroke that serialises as
500 points is a bug.

Typical reduction on real ink is 85-95%.

IT PRESERVES PRESSURE, and that is a property of the algorithm rather than luck:
Douglas-Peucker SELECTS a subset of the input points (it returns the very objects it
was given — `PathSimplifier.ts:123`), it never interpolates new ones. So the
`pressure` riding on each retained sample rides through untouched. If it ever grows
an interpolating mode this breaks silently, so the spec pins it.

<!-- source: grafloria-engine-ports.md -->

# Ports

Import these from `@grafloria/engine`.

## On their own pages

- [`PortLayoutArgs`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-ports-portlayoutargs)

## Functions

### `arePortDataTypesCompatible`

Free-function facade over the singleton — what PortModel/validators import.

```ts
function arePortDataTypesCompatible(from: string | undefined, to: string | undefined): boolean
```

### `buildDynamicPortCommands`

The plan, as undoable commands. Empty array when nothing is due — so a caller
can drive this on every link change without polluting the undo stack.

```ts
function buildDynamicPortCommands(node: NodeModel, links?: LinkModel[]): Command[]
```

### `buildDynamicPortCommandsForDiagram`

Every node in the diagram that owes the allocator work.

```ts
function buildDynamicPortCommandsForDiagram(diagram: DiagramModel): Command[]
```

### `canConnectPortsWithRules`

Boolean facade for call sites that don't care WHY.

```ts
function canConnectPortsWithRules(
  source: PortModel,
  target: PortModel,
  context: ConnectionRuleContext = {}
): boolean
```

### `ensureSideAnchorPort`

The hidden port a side-anchor handle names — created once per node and
handle, then re-used (a re-applied spec must not grow a second one). Placed
as a FRACTION of the node box, so it stays on its side when the node resizes. Returns null when `handle` is not a side anchor.

```ts
function ensureSideAnchorPort(node: NodeModel, handle: string): string | null
```

### `evaluatePortConnection`

May a link be created FROM `source` TO `target`? Directional — swapping the
arguments is a different question and may well get a different answer.

```ts
function evaluatePortConnection(
  source: PortModel,
  target: PortModel,
  context: ConnectionRuleContext = {}
): ConnectionVerdict
```

### `findPortGroup`

Find the group a port belongs to: the node's own definitions first (most
specific), then the registry for the node's type.

```ts
function findPortGroup(
  port: PortModel,
  node: NodeModel | undefined
): PortGroupDefinition | undefined
```

### `getNodePortGroups`

Per-node group definitions, stored in node metadata so they serialize with the
diagram (a node can carry a one-off group without registering a node type).

```ts
function getNodePortGroups(node: NodeModel | undefined): Record<string, PortGroupDefinition>
```

### `isSideAnchorPort`

A port a side-anchor handle created (`<node>__right@36`).

```ts
function isSideAnchorPort(portId: string | undefined): boolean
```

### `parseSideAnchor`

`'right@36'` → `{ side: 'right', at: { px: 36 } }`; `'left@50%'` → `{ at: { pct: 50 } }`; anything else → null.

```ts
function parseSideAnchor(handle: string): { side: AnchorSide; at: { px?: number; pct?: number } } | null
```

### `planDynamicPorts`

What must change so every dynamic group on `node` offers exactly `spare` free
ports? Idempotent: run it on a settled node and it returns an empty plan.

A port is "free" when it carries no links. Only ports the allocator itself
spawned (`dynamic: true`) are ever REMOVED — an authored port the user simply
hasn't wired yet is not surplus, it is the design.

```ts
function planDynamicPorts(node: NodeModel, links?: LinkModel[]): DynamicPortPlan
```

### `portTypeColor`

Free-function facade over the singleton — what the renderer imports.

```ts
function portTypeColor(name: string | undefined): string | undefined
```

### `resolvePortConfig`

Fold a port's group into its own fields. THE resolution seam — the renderer,
the layout engine and the connection validator all read the result of this
function and never the raw port fields, so group inheritance can never
silently apply in one place and not another.

```ts
function resolvePortConfig(port: PortModel, node?: NodeModel): ResolvedPortConfig
```

### `setNodePortGroups`

```ts
function setNodePortGroups(node: NodeModel, groups: Record<string, PortGroupDefinition>): void
```

### `sideAnchorPortId`

The id of the port a side-anchor handle names on `nodeId`.

```ts
function sideAnchorPortId(nodeId: string, handle: string): string
```

## Classes

### `PortGroupRegistry`

Groups registered per node TYPE. A node type declares its port groups once
("the `and-gate` type has an `in` group and an `out` group"), and every node
of that type inherits them.

```ts
class PortGroupRegistry
```

**Methods**

- `register(nodeType: string, group: PortGroupDefinition): void`
- `registerAll(nodeType: string, groups: PortGroupDefinition[]): void`
- `get(nodeType: string, groupId: string): PortGroupDefinition | undefined`
- `getAll(nodeType: string): PortGroupDefinition[]`
- `unregister(nodeType: string, groupId?: string): void`
- `clear(): void`

### `PortTypeRegistry`

```ts
class PortTypeRegistry
```

**Methods**

- `register(definition: PortDataTypeDefinition): void`
- `registerAll(definitions: PortDataTypeDefinition[]): void`
- `get(name: string): PortDataTypeDefinition | undefined`
- `has(name: string): boolean`
- `unregister(name: string): void`
- `clear(): void`
- `isCompatible(from: string | undefined, to: string | undefined): boolean` — May a link carry `from` into `to`?

Compatibility is DIRECTIONAL on purpose: `int → float` is a widening that a
host may well allow while `float → int` is a lossy one it may not.
- `colorFor(name: string | undefined): string | undefined` — The glyph colour for a data type, if one was registered.

## Constants

### `ANY_PORT_TYPE`

The wildcard: a port typed `*` (or declared compatible with `*`) fits anything.

```ts
const ANY_PORT_TYPE: "*"
```

### `DEFAULT_PORT_GATING`

```ts
const DEFAULT_PORT_GATING: ResolvedPortGating
```

### `DEFAULT_PORT_LABEL_OFFSET`

```ts
const DEFAULT_PORT_LABEL_OFFSET: 6
```

### `DEFAULT_PORT_SPREAD_SPACING`

```ts
const DEFAULT_PORT_SPREAD_SPACING: 10
```

### `PORT_GROUPS_METADATA_KEY`

Node metadata key holding per-node group definitions.

```ts
const PORT_GROUPS_METADATA_KEY: "portGroups"
```

### `portGroupRegistry`

The process-wide registry. Hosts register node-type groups at bootstrap.

```ts
const portGroupRegistry: PortGroupRegistry
```

### `portTypeRegistry`

The process-wide registry. Hosts register their data types at bootstrap.

```ts
const portTypeRegistry: PortTypeRegistry
```

## Interfaces

### `ConnectionRuleContext`

```ts
interface ConnectionRuleContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sourceNode?` | `NodeModel` |  |  |
| `targetNode?` | `NodeModel` |  |  |
| `links?` | `LinkModel[]` |  | The diagram's links — needed for the duplicate-link rule. |
| `rejectDuplicatesByDefault?` | `boolean` |  | Reject a second link between the same ordered port pair EVEN when the ports allow duplicates. Proximity-connect passes this (auto-linking a duplicate on a drag-near is never what the user meant); the explicit connection drag does not, preserving its historical permissiveness. |
| `validators?` | `Array<(source: PortModel, target: PortModel) => boolean>` |  | Extra host rules (connection groups, ACLs…). Run last. |

### `ConnectionVerdict`

```ts
interface ConnectionVerdict
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` |  |  |
| `reason?` | `ConnectionRejectionReason` |  |  |
| `message?` | `string` |  | Human-readable, safe to surface in a tooltip / live region. |

### `DynamicPortPlan`

```ts
interface DynamicPortPlan
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `add` | `PortModel[]` |  | Ports to create, in order. |
| `remove` | `string[]` |  | Ids of surplus free ports to retire. |

### `DynamicPortSpec`

Dynamic auto-ports: keep a group topped up with free ports so the
user always has somewhere to drop the next link — the node-editor pattern
(Blender / Unreal / n8n).

```ts
interface DynamicPortSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `spare?` | `number` |  | How many UNCONNECTED ports the group must always offer. Default 1. |
| `max?` | `number` |  | Hard cap on total ports in the group. 0 (default) = uncapped. |
| `idPrefix?` | `string` |  | Id prefix for spawned ports. Default `<groupId>-`. |

### `PortDataTypeDefinition`

```ts
interface PortDataTypeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | The type's own name. |
| `compatibleWith?` | `string[]` |  | Types this one may ALSO connect to (beyond an exact name match). `'*'` means "compatible with everything" — the escape hatch for an `any` port. |
| `color?` | `string` |  | Affordance: the glyph colour for ports of this type. |

### `PortGatingSpec`

Directional connectability.

Every field is optional and every default reproduces the old behaviour:
  isConnectableStart/End = true, from/toMaxLinks = null (unlimited),
  allowSelfLink = false, allowDuplicateLinks = true.

```ts
interface PortGatingSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isConnectableStart?` | `boolean` |  | May a link START here? Default true. |
| `isConnectableEnd?` | `boolean` |  | May a link END here? Default true. |
| `fromMaxLinks?` | `number \| null` |  | Cap on OUTGOING links. null/undefined = unlimited. |
| `toMaxLinks?` | `number \| null` |  | Cap on INCOMING links. null/undefined = unlimited. |
| `maxConnections?` | `number \| null` |  | Cap on links in EITHER direction (the legacy knob). null = unlimited. |
| `allowSelfLink?` | `boolean` |  | Allow a link whose source node IS its target node. Default false. |
| `allowDuplicateLinks?` | `boolean` |  | Allow a SECOND link between the same ordered pair of ports. Default true. |
| `allowedTypes?` | `string[]` |  | Restrict which port data-types / system-types may attach. Empty = no restriction. |

### `PortGroupDefinition`

A named, reusable bundle of port config on a node type. Ports name their
group and override ONLY what differs — replacing the old
top/right/bottom/left-only `PortsConfig`, in which "eight typed inputs down
the left edge, each with a label" could not be said at all.

```ts
interface PortGroupDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `side?` | `PortEdge` |  | Default side for members that don't declare one. |
| `layout?` | `PortLayoutSpec` |  |  |
| `shape?` | `PortShapeSpec` |  |  |
| `style?` | `Record<string, unknown>` |  | Raw SVG presentation attributes merged onto the glyph (fill, stroke, …). |
| `label?` | `Partial<PortLabelSpec>` |  | Label defaults. Members supply/override `text`. |
| `visibility?` | `PortVisibilityMode` |  |  |
| `gating?` | `PortGatingSpec` |  |  |
| `type?` | `'input' \| 'output' \| 'bi'` |  | Default port direction (input/output/bi) for members. |
| `dataType?` | `string` |  |  |
| `fromSpot?` | `PortSpot` |  |  |
| `toSpot?` | `PortSpot` |  |  |
| `spread?` | `PortSpreadSpec` |  |  |
| `dynamic?` | `DynamicPortSpec` |  |  |

### `PortLabelSpec`

```ts
interface PortLabelSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` |  |  |
| `layout?` | `PortLabelLayout` |  | Default 'outside'. |
| `offset?` | `number` |  | Gap from the glyph EDGE (not its centre), in px. Default 6. |
| `angle?` | `number` |  | Extra rotation applied to the label, in degrees. Default 0. |
| `keepUpright?` | `boolean` |  | Auto-flip a label whose total rotation would leave it upside-down (\|angle\| > 90°) by adding 180°, so text always reads left-to-right. Default true. |
| `fontSize?` | `number` |  |  |
| `fontFamily?` | `string` |  |  |
| `fontWeight?` | `number \| string` |  |  |
| `color?` | `string` |  |  |
| `maxWidth?` | `number` |  | Wrap width for the shared text-block engine. |
| `className?` | `string` |  |  |
| `noNudge?` | `boolean` |  | Opt OUT of collision-aware nudging (see `port-label.ts`). Default false — i.e. crowded labels ARE nudged apart by default. |

### `PortLayoutSpec`

```ts
interface PortLayoutSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `strategy` | `PortLayoutStrategyName` |  |  |
| `args?` | `PortLayoutArgs` |  |  |

### `PortShapeSpec`

```ts
interface PortShapeSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `PortGlyphShape` |  |  |
| `size?` | `number` |  | Full width AND height of the glyph box, in px. For a circle this is the DIAMETER (so `size: 12` === the legacy `portDefaultRadius: 6`). Omit to inherit `InteractionConfig.portDefaultRadius * 2`. |
| `width?` | `number` |  | Non-square glyphs: override one axis. Falls back to `size`. |
| `height?` | `number` |  |  |
| `path?` | `string` |  | shape:'path' only — SVG path data, centred on (0,0) in a `size` box. |
| `rotation?` | `number` |  | Rotate the glyph about its own centre, in degrees. |

### `PortSpot`

```ts
interface PortSpot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spot` | `PortSpotName` |  |  |
| `direction?` | `PortEdge` |  | The direction a link LEAVES (fromSpot) or APPROACHES (toSpot) the port. Defaults to the port's side — i.e. the outward normal — which is what the orthogonal router has always been handed. |
| `distance?` | `number` |  | Push the attachment point this many px further along `direction`. |

### `PortSpreadSpec`

Spread N links landing on ONE port along that port's edge instead of piling
them all on the centre point.

(Byte-stability.)

```ts
interface PortSpreadSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `spacing?` | `number` |  | Gap between adjacent lanes, in px. Default 10. |
| `max?` | `number` |  | Cap the number of distinct lanes; links beyond the cap reuse the outermost lane. 0 (default) = uncapped. |

### `ResolvedPortConfig`

```ts
interface ResolvedPortConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `PortEdge` |  |  |
| `layout?` | `PortLayoutSpec` |  |  |
| `shape?` | `PortShapeSpec` |  |  |
| `style` | `Record<string, unknown>` |  |  |
| `label?` | `PortLabelSpec` |  |  |
| `visibility?` | `PortVisibilityMode` |  |  |
| `gating` | `ResolvedPortGating` |  |  |
| `dataType?` | `string` |  |  |
| `fromSpot?` | `PortSpot` |  |  |
| `toSpot?` | `PortSpot` |  |  |
| `spread?` | `PortSpreadSpec` |  |  |
| `dynamic?` | `DynamicPortSpec` |  |  |
| `groupId?` | `string` |  | The group this resolved from, if any. |

### `ResolvedPortGating`

Gating with every question ANSWERED — no `undefined` anywhere, because a
validator that has to ask "was this unset or set to false?" is a validator
with a bug waiting in it. `null` is the explicit "unlimited" for the caps.

```ts
interface ResolvedPortGating
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isConnectableStart` | `boolean` |  |  |
| `isConnectableEnd` | `boolean` |  |  |
| `allowSelfLink` | `boolean` |  |  |
| `allowDuplicateLinks` | `boolean` |  |  |
| `fromMaxLinks` | `number \| null` |  |  |
| `toMaxLinks` | `number \| null` |  |  |
| `maxConnections` | `number \| null` |  |  |
| `allowedTypes` | `string[]` |  |  |

## Types

### `AnchorSide`

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

```ts
type AnchorSide = 'top' | 'right' | 'bottom' | 'left';
```

### `ConnectionRejectionReason`

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

```ts
type ConnectionRejectionReason =
  | 'self-port'
  | 'self-link'
  | 'not-connectable-start'
  | 'not-connectable-end'
  | 'node-not-connectable'
  | 'direction'
  | 'data-type'
  | 'allowed-types'
  | 'max-connections'
  | 'from-max-links'
  | 'to-max-links'
  | 'duplicate-link'
  | 'connection-group'
  | 'custom';
```

### `PortEdge`

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

```ts
type PortEdge = 'left' | 'right' | 'top' | 'bottom';
```

### `PortGlyphShape`

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

The port's rendered marker.

`path` renders a caller-supplied SVG path (`PortShapeSpec.path`), authored in
a box of `size` centred on the port's anchor point.

```ts
type PortGlyphShape = 'circle' | 'square' | 'diamond' | 'triangle' | 'path';
```

### `PortLabelLayout`

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

Where a port's label sits relative to the glyph.

- `inside`     — pulled INTO the node body, opposite the port's outward normal.
- `outside`    — pushed AWAY from the node, along the outward normal (default).
- `orthogonal` — offset perpendicular to the outward normal (reads along the
                 edge, so a column of side ports doesn't stack labels on the
                 same line).
- `radial`     — offset along the ray from the node's centre through the port;
                 the layout that actually works on ellipse / circle nodes,
                 where "outward normal" and "away from centre" are the same
                 thing only at the four cardinal points.

```ts
type PortLabelLayout = 'inside' | 'outside' | 'orthogonal' | 'radial';
```

### `PortLayoutStrategyName`

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

Named port-layout strategies. Every other strategy is an explicit opt-in that overrides it.

```ts
type PortLayoutStrategyName =
  | 'shape'
  | 'absolute'
  | 'line'
  | 'sideLinear'
  | 'ellipse'
  | 'ellipseSpread';
```

### `PortSpotName`

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

A named point on the port's glyph box. `default` means "whatever the port's
side implies" — the outward-facing edge midpoint, which is the historical
attachment behaviour (the glyph CENTRE, since the legacy glyph had no box).

```ts
type PortSpotName =
  | 'default'
  | 'center'
  | 'top'
  | 'right'
  | 'bottom'
  | 'left'
  | 'topLeft'
  | 'topRight'
  | 'bottomLeft'
  | 'bottomRight';
```

### `PortVisibilityMode`

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

```ts
type PortVisibilityMode = 'always' | 'on-hover' | 'never' | 'hidden';
```

<!-- source: grafloria-engine-ports-portlayoutargs.md -->

# PortLayoutArgs

Import it from `@grafloria/engine`.

```ts
interface PortLayoutArgs
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x?` | `number` |  | Absolute position. Fractions of the node box by default; px when `units:'px'`. |
| `y?` | `number` |  |  |
| `units?` | `'fraction' \| 'px'` |  |  |
| `start?` | `{ x: number; y: number }` |  | Spread ports evenly from `start` to `end` (node-local px). |
| `end?` | `{ x: number; y: number }` |  |  |
| `step?` | `number` |  | Fixed spacing between consecutive ports, in px. When set, ports march from `start` toward `end` at this pitch instead of dividing the span evenly. |
| `padding?` | `number` |  | Inset from the corners of the edge, in px. Default 0. |
| `angle?` | `number` |  | Start angle in degrees (0° = +x axis, growing clockwise in screen space). |
| `sweep?` | `number` |  | Arc span in degrees. Default 360 (a full ring). |
| `radiusX?` | `number` |  | Radii, in px. Default: the node's half-extents (the inscribed ellipse). |
| `radiusY?` | `number` |  |  |
| `dx?` | `number` |  | Constant nudge applied after the strategy, in node-local px. |
| `dy?` | `number` |  |  |
| `compensateRotation?` | `boolean` |  | Counter-rotate the port about the node's centre by the node's own rotation, so a rotated node's ports keep their WORLD-space arrangement. Default false. |

<!-- source: grafloria-engine-routing.md -->

# Routing

Import these from `@grafloria/engine`.

## On their own pages

- [`PathSimplifier`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-routing-pathsimplifier): PathSimplifier provides algorithms for simplifying paths
- [`RoutingOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-routing-routingoptions): Routing options

## Functions

### `mergeObstacles`

Merge two obstacle sources into one array, collapsing entries that are the
SAME obstacle described twice.

This exists because `RoutingEngine.route()` unions its global ObstacleMap with
the request's obstacles, and the renderer's request repeats what the engine
already registered — so a 5,000-node diagram was handing the router a
9,998-entry obstacle array, and every one of those entries was scanned on
every collision test. Deduplication is keyed on id AND geometry, so two
entries that genuinely disagree about where an obstacle is are both kept:
the effective blocked region is unchanged.

```ts
function mergeObstacles(
  a: readonly Obstacle[],
  b: readonly Obstacle[]
): Obstacle[]
```

### `serveSolver`

Serve solver requests on a port. This IS the worker's message loop — call it
inside the worker script with `self`, or in a test with a fake port.

```ts
function serveSolver(port: {
  onmessage: ((ev: { data: SolverRequest }) => void) | null;
  postMessage(msg: SolverResponse): void;
}): void
```

## Classes

### `AStarRouter`

A* Pathfinding Router

```ts
class AStarRouter
```

**Methods**

- `constructor(obstacleMap: ObstacleMap, options: AStarOptions = {})`
- `getName(): string` — Get algorithm name
- `route(start: Point, end: Point): Point[]` — Find path from start to end using A* algorithm

### `DijkstraRouter`

Dijkstra's Shortest Path Router
Guarantees shortest path but may be slower than A* for long distances

```ts
class DijkstraRouter
```

**Methods**

- `constructor(obstacleMap: ObstacleMap, options: DijkstraOptions = {})`
- `getName(): string` — Get algorithm name
- `route(start: Point, end: Point): Point[]` — Find shortest path from start to end using Dijkstra's algorithm

### `GlobalRouteSolver`

```ts
class GlobalRouteSolver
```

**Methods**

- `constructor(options: SolverOptions = {})`
- `get stats(): Readonly<SolverStats>`
- `solve(edges: SolverEdge[], obstacles: Obstacle[]): Map<string, Point[]>` — Full solve. Deterministic: edges route in id order, every pass.
- `solveIncremental( changed: Array<{ edge: SolverEdge; removed?: boolean }>, obstacles?: Obstacle[] ): Map<string, Point[]>` — Re-solve after a change: `changed` edges re-route (removed ones pass with
`removed: true`), and so does every edge whose current route touches a cell
a changed edge occupied before or after. Everything else is served as-is.

### `LiveReroutingEngine`

LiveReroutingEngine automatically updates link paths when nodes move or resize.

Features:
- Throttled rerouting for performance (60fps by default)
- Batches multiple node movements
- Can be enabled/disabled
- Configurable throttle time

```ts
class LiveReroutingEngine
```

**Methods**

- `constructor(routingEngine: RoutingEngine, diagram: DiagramModel)`
- `enable(): void` — Enable live rerouting
- `disable(): void` — Disable live rerouting
- `setThrottle(ms: number): void` — Set throttle time in milliseconds
- `rerouteAll(): void` — Manually trigger reroute of all links in the diagram
Useful for manual refresh or after bulk operations
- `destroy(): void` — Clean up event listeners

**Example**

```typescript
const liveRerouting = new LiveReroutingEngine(routingEngine, diagram);
liveRerouting.enable();

// Links will automatically update when nodes move
node.setPosition({ x: 100, y: 100 });
```

### `ManhattanRouter`

```ts
class ManhattanRouter implements IRouter
```

**Methods**

- `getName(): string` — Get algorithm name
- `route(request: RouteRequest): RoutedPath | null` — Calculate a route from start to end
Can be synchronous or asynchronous (for algorithms like ELK.js)

### `ObstacleIndex`

```ts
class ObstacleIndex
```

**Methods**

- `constructor(obstacles: readonly Obstacle[], cellSize: number = DEFAULT_CELL_SIZE)`
- `get size(): number` — How many obstacles were indexed.
- `collides(px: number, py: number, margin: number): boolean` — Does the point, expanded by `margin`, touch any obstacle?

Byte-for-byte the predicate `OrthogonalRouter.collidesWithObstacles` used to
evaluate against the whole array — inclusive bounds and all.
- `queryBox(minX: number, minY: number, maxX: number, maxY: number): Obstacle[]` — Every obstacle whose rect could overlap the axis-aligned box — the candidate
set for a segment test. Conservative (a superset); the caller runs the exact
geometry test on what comes back.
- `all(): Obstacle[]` — Every indexed obstacle (deduplicated). Escape hatch for degenerate queries.

### `ObstacleMap`

ObstacleMap manages spatial indexing of obstacles for efficient queries
Uses a simple grid-based spatial index for O(1) lookups

```ts
class ObstacleMap
```

**Methods**

- `size(): number` — Get number of obstacles in the map
- `add(obstacle: Obstacle): void` — Add an obstacle to the map
- `remove(id: string): boolean` — Remove an obstacle from the map
- `get(id: string): Obstacle | undefined` — Get an obstacle by ID
- `update(obstacle: Obstacle): void` — Update an obstacle (remove and re-add to update spatial index)
- `clear(): void` — Clear all obstacles
- `queryRegion(region: Rectangle): Obstacle[]` — Query obstacles in a rectangular region
- `queryNearPoint(point: Point, radius: number): Obstacle[]` — Query obstacles near a point within a given radius
- `queryLine(start: Point, end: Point): Obstacle[]` — Query obstacles along a line segment
- `getObstacles(): Obstacle[]` — Get all obstacles as an array
- `isPointInside(point: Point, respectMargin = false): boolean` — Check if a point is inside any obstacle
- `doesLineIntersect(start: Point, end: Point, margin = 0): boolean` — Check if a line segment intersects any obstacle

### `ObstacleMapBuilder`

ObstacleMapBuilder creates ObstacleMap from DiagramModel
Uses global bounds to account for transforms and hierarchy

```ts
class ObstacleMapBuilder
```

**Methods**

- `static fromDiagram(diagram: DiagramModel, options: ObstacleMapOptions = {}): ObstacleMap` (static) — Build obstacle map from all nodes in diagram
- `static fromDiagramExcluding( diagram: DiagramModel, excludeIds: string[], options: ObstacleMapOptions = {} ): ObstacleMap` (static) — Build obstacle map excluding specific nodes
Useful for routing where source/target nodes should not be obstacles

### `OrthogonalRouter`

OrthogonalRouter creates paths with only 90-degree angles
Supports obstacle avoidance using A* on a grid

```ts
class OrthogonalRouter implements IRouter
```

**Methods**

- `getName(): string` — Get algorithm name
- `route(request: RouteRequest): RoutedPath | null` — Calculate a route from start to end
Can be synchronous or asynchronous (for algorithms like ELK.js)
- `static deriveExitSide(from: Point, toward: Point): 'left' | 'right' | 'top' | 'bottom'` (static) — The exit side a FLOATING anchor should use, derived from where the
other endpoint is — dominant axis first, ties break horizontal (matching
the midline fallback's own axis choice, so the derived route agrees with
what the undirected route would have preferred).

### `RoutingEngine`

RoutingEngine coordinates routing operations and manages obstacles

```ts
class RoutingEngine
```

**Methods**

- `constructor()`
- `registerRouter(name: string, router: IRouter): void` — Register a custom router
- `unregisterRouter(name: string): boolean` — Unregister a router
- `getAvailableAlgorithms(): string[]` — Get list of available routing algorithms
- `setDefaultAlgorithm(algorithm: RoutingAlgorithm): void` — Set default routing algorithm
- `getDefaultAlgorithm(): RoutingAlgorithm` — Get default algorithm
- `addObstacle(obstacle: Obstacle): void` — Add a global obstacle
- `removeObstacle(id: string): boolean` — Remove a global obstacle
- `updateObstacle(obstacle: Obstacle): void` — Update an existing obstacle's position/size
More efficient than remove + add
- `getObstacles(): Obstacle[]` — All registered obstacles — the map's own array accessor, passed through.
- `getObstacleCount(): number`
- `clearObstacles(): void` — Clear all global obstacles
- `clearCache(): void` — Clear route cache
- `route(request: RouteRequest): RoutedPath | null` — Route from start to end (synchronous version)
Throws error if algorithm is async (like ELK)
Use routeAsync() for async routers
- `async routeAsync(request: RouteRequest): Promise<RoutedPath | null>` — Route from start to end (async version)
Supports both sync and async routers like ELK.js
- `getStats(): { obstacleCount: number; routerCount: number; cacheSize: number; }` — Get routing engine statistics

### `SolverHost`

The caller-side host. Pass a real Worker (or anything satisfying SolverPort)
to run remote; pass nothing to run inline on the same thread — identical
behaviour, no protocol drift, because BOTH paths speak through serveSolver.

```ts
class SolverHost
```

**Methods**

- `constructor(port?: SolverPort)`
- `solve( edges: SolverEdge[], obstacles: Obstacle[], options?: SolverOptions ): Promise<{ routes: Map<string, Point[]>; stats: SolverStats }>`
- `solveIncremental( changed: Array<{ edge: SolverEdge; removed?: boolean }>, obstacles?: Obstacle[] ): Promise<{ routes: Map<string, Point[]>; stats: SolverStats }>`

### `StraightRouter`

StraightRouter creates a direct straight line from start to end

```ts
class StraightRouter implements IRouter
```

**Methods**

- `getName(): string` — Get algorithm name
- `route(request: RouteRequest): RoutedPath | null` — Calculate a route from start to end
Can be synchronous or asynchronous (for algorithms like ELK.js)

### `VisibilityGraphRouter`

Visibility Graph Router
Optimal for environments with few obstacles and open spaces
Creates graph of obstacle corners and finds shortest geometric path

```ts
class VisibilityGraphRouter
```

**Methods**

- `constructor(obstacleMap: ObstacleMap, options: VisibilityGraphOptions = {})`
- `getName(): string` — Get algorithm name
- `route(start: Point, end: Point): Point[]` — Find shortest geometric path using visibility graph

## Interfaces

### `AStarOptions`

Configuration options for A* router

```ts
interface AStarOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `heuristic?` | `AStarHeuristic` |  | Heuristic function to use (default: MANHATTAN) |
| `allowDiagonal?` | `boolean` |  | Allow diagonal movement (default: true) |
| `gridSize?` | `number` |  | Grid size for discretization (default: 5) |
| `smoothing?` | `boolean` |  | Enable path smoothing (default: true) |
| `obstacleMargin?` | `number` |  | Margin around obstacles (default: 5) |
| `maxIterations?` | `number` |  | Maximum iterations before giving up (default: 10000) |

### `DijkstraOptions`

Configuration options for Dijkstra router

```ts
interface DijkstraOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowDiagonal?` | `boolean` |  | Allow diagonal movement (default: true) |
| `gridSize?` | `number` |  | Grid size for discretization (default: 5) |
| `smoothing?` | `boolean` |  | Enable path smoothing (default: true) |
| `obstacleMargin?` | `number` |  | Margin around obstacles (default: 5) |
| `maxIterations?` | `number` |  | Maximum iterations before giving up (default: 10000) |

### `IRouter`

Interface for routing algorithms

```ts
interface IRouter
```

**Members**

- `route(request: RouteRequest): RoutedPath | null | Promise<RoutedPath | null>` — Calculate a route from start to end
Can be synchronous or asynchronous (for algorithms like ELK.js)
- `getName(): string` — Get algorithm name

### `Obstacle`

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

Obstacle in the routing space (usually a node)

```ts
interface Obstacle extends GeometryRectangle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique identifier |
| `margin?` | `number` |  | Optional padding/margin around obstacle |
| `kind?` | `'node' \| 'group'` |  | Containment. Obstacles are no longer a flat set — a group obstacle knows it is one, and a node obstacle can carry its containing group, so routers can treat "inside the same container" and "collapsed group = one solid block" as first-class facts. |
| `parentId?` | `string` |  | The containing group's id, when the obstacle lives inside one. |

### `ObstacleMapOptions`

```ts
interface ObstacleMapOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `margin?` | `number` |  | Margin to add around each obstacle |

### `RoutedPath`

A complete routed path

```ts
interface RoutedPath
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `RoutePoint[]` |  | Ordered points forming the path |
| `totalLength` | `number` |  | Total path length |
| `bendCount` | `number` |  | Number of bends/turns in the path |
| `cost?` | `number` |  | Optional cost of the path |
| `segments?` | `RouteSegment[]` |  | Route segments |

### `RoutePoint`

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

A point in the routing grid/space

```ts
interface RoutePoint extends Point
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `cost?` | `number` |  | Optional cost associated with this point |

### `RouteRequest`

Routing request

```ts
interface RouteRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `Point` |  | Start point |
| `end` | `Point` |  | End point |
| `obstacles?` | `Obstacle[]` |  | Obstacles to avoid |
| `options?` | `RoutingOptions` |  | Routing options |
| `sourceDirection?` | `PortDirection` |  | Direction the source port points (for orthogonal routing) |
| `targetDirection?` | `PortDirection` |  | Direction the target port points (for orthogonal routing) |
| `obstacleIndex?` | `ObstacleIndex` |  | A prebuilt spatial index over EXACTLY `obstacles`. |

### `RouteSegment`

A segment of a route path

```ts
interface RouteSegment
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `RoutePoint` |  |  |
| `end` | `RoutePoint` |  |  |
| `length` | `number` |  | Length of the segment |
| `angle` | `number` |  | Angle in degrees |

### `SolverEdge`

```ts
interface SolverEdge
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `start` | `Point` |  |  |
| `end` | `Point` |  |  |
| `sourceDirection?` | `Side` |  |  |
| `targetDirection?` | `Side` |  |  |
| `jetty?` | `number` |  | per-edge jetty override; defaults to the solver's gridSize |

### `SolverOptions`

```ts
interface SolverOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `gridSize?` | `number` |  |  |
| `obstacleMargin?` | `number` |  |  |
| `congestionPenalty?` | `number` |  | cost added per step through a cell occupied by K other edges: K × this |
| `crossingPenalty?` | `number` |  | cost added per step through a cell that another edge crosses PERPENDICULAR to this step |
| `passes?` | `number` |  | refinement passes over the whole edge set |
| `maxIterations?` | `number` |  | per-edge search budget (ManhattanRouter maxIterations) |
| `bendCost?` | `number` |  |  |

### `SolverPort`

The message port surface the host needs — a real Worker satisfies it.

```ts
interface SolverPort
```

**Properties**

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

**Members**

- `postMessage(msg: SolverRequest): void`

### `SolverRequestIncremental`

```ts
interface SolverRequestIncremental
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'incremental'` |  |  |
| `changed` | `Array<{ edge: SolverEdge; removed?: boolean }>` |  |  |
| `obstacles?` | `Obstacle[]` |  |  |

### `SolverRequestSolve`

```ts
interface SolverRequestSolve
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `kind` | `'solve'` |  |  |
| `edges` | `SolverEdge[]` |  |  |
| `obstacles` | `Obstacle[]` |  |  |
| `options?` | `SolverOptions` |  |  |

### `SolverResponse`

```ts
interface SolverResponse
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `number` |  |  |
| `routes` | `Array<[string, Point[]]>` |  |  |
| `stats` | `SolverStats` |  |  |

### `SolverStats`

```ts
interface SolverStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `edgesRouted` | `number` |  | edges routed in the last solve/solveIncremental call |
| `edgesReused` | `number` |  | edges served untouched from the previous solution |

### `VisibilityGraphOptions`

Configuration options for Visibility Graph router

```ts
interface VisibilityGraphOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `obstacleMargin?` | `number` |  | Margin around obstacles (default: 1) - corners placed outside obstacle bounds |

## Types

### `CostFunction`

Cost function for path evaluation

```ts
type CostFunction = (path: RoutedPath) => number;
```

### `HeuristicFunction`

Heuristic function for pathfinding

```ts
type HeuristicFunction = (a: Point, b: Point) => number;
```

### `PortDirection`

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

Port direction for routing algorithms that need to respect port orientation

```ts
type PortDirection = 'left' | 'right' | 'top' | 'bottom';
```

### `RoutingAlgorithm`

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

Routing algorithm type

```ts
type RoutingAlgorithm =
  | 'straight'
  | 'orthogonal'
  | 'manhattan'
  | 'elk'
  | 'a-star'
  | 'dijkstra'
  | 'visibility-graph'
  | 'custom';
```

### `SolverRequest`

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

```ts
type SolverRequest = SolverRequestSolve | SolverRequestIncremental;
```

## Enums

### `AStarHeuristic`

Heuristic functions for A* algorithm

```ts
enum AStarHeuristic
```

**Members**

- `MANHATTAN = 'manhattan'` — Manhattan distance (L1 norm) - best for grid-based movement
- `EUCLIDEAN = 'euclidean'` — Euclidean distance (L2 norm) - best for free movement
- `DIAGONAL = 'diagonal'` — Diagonal distance (Chebyshev/L∞ norm) - best for 8-directional movement

<!-- source: grafloria-engine-routing-pathsimplifier.md -->

# PathSimplifier

Import it from `@grafloria/engine`.

PathSimplifier provides algorithms for simplifying paths

Features:
- Douglas-Peucker algorithm for optimal simplification
- Collinear point removal for straight paths
- Perpendicular distance calculations
- Configurable tolerance (epsilon)

Use cases:
- Reduce waypoint count in routed paths
- Clean up paths with unnecessary intermediate points
- Optimize path storage and rendering performance
- Maintain path shape while reducing complexity

```ts
class PathSimplifier
```

**Methods**

- `simplify(points: Point[], epsilon: number = this.DEFAULT_EPSILON): Point[]` — Simplify a path using the Douglas-Peucker algorithm

This algorithm recursively divides the path and removes points
that are within epsilon distance from the line between endpoints.

Time complexity: O(n log n) average, O(n²) worst case
- `removeCollinearPoints(points: Point[], tolerance: number = 0.01): Point[]` — Remove collinear points from path

This is faster than Douglas-Peucker but less sophisticated. Only removes points that lie exactly (within tolerance) on the line
between their neighbors.

Time complexity: O(n)
- `arePointsCollinear( p1: Point, p2: Point, p3: Point, tolerance: number = 0.01 ): boolean` — Check if three points are collinear (lie on the same line)

Uses cross product to determine collinearity. If cross product is close to zero, points are collinear.
- `perpendicularDistance( point: Point, lineStart: Point, lineEnd: Point ): number` — Calculate perpendicular distance from point to line segment

Uses the formula:
distance = |((y2-y1)x0 - (x2-x1)y0 + x2*y1 - y2*x1)| / sqrt((y2-y1)² + (x2-x1)²)
- `calculatePathLength(points: Point[]): number` — Calculate total path length

Useful for comparing simplified vs original paths
- `getSimplificationStats(original: Point[], simplified: Point[])` — Get simplification statistics

**Example**

```typescript
const simplifier = new PathSimplifier();

// Remove collinear points (fastest)
const cleaned = simplifier.removeCollinearPoints(points);

// Douglas-Peucker simplification (optimal)
const simplified = simplifier.simplify(points, epsilon);
```

<!-- source: grafloria-engine-routing-routingoptions.md -->

# RoutingOptions

Import it from `@grafloria/engine`.

Routing options

```ts
interface RoutingOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `algorithm?` | `RoutingAlgorithm` |  | Algorithm to use |
| `avoidObstacles?` | `boolean` |  | Avoid obstacles |
| `gridSize?` | `number` |  | Grid cell size for grid-based algorithms |
| `obstacleMargin?` | `number` |  | Margin around obstacles |
| `minimizeBends?` | `boolean` |  | Minimize bends (for orthogonal) |
| `costs?` | `{ distance?: number; bends?: number; crossings?: number; }` |  | Cost weights |
| `maxIterations?` | `number` |  | Maximum iterations for pathfinding |
| `jetty?` | `number` |  | . Minimum port-anchor stub: the route must leave the source and enter the target PERPENDICULAR to the port side for at least this many px before the first bend. When set it also replaces the built-in 20px breathing-room offset, and a link with FLOATING (direction- less) anchors derives its exit sides from the relative geometry instead of taking the stub-less midline fallback. |
| `container?` | `GeometryRectangle` |  | Soft containment. When both endpoints live in the same group, the renderer passes that group's bounds here; grid routers charge `containerPenalty` per step OUTSIDE the container, so sibling edges stay within their container when an inside route exists — without making escape impossible when obstacles force it. |
| `containerPenalty?` | `number` |  | Extra cost per grid step outside `container`. Default: 2 × gridSize. |
| `simplifyPath?` | `boolean` |  | Simplify path to reduce waypoint count |
| `simplificationEpsilon?` | `number` |  | Simplification tolerance (epsilon) - higher values = more aggressive |

<!-- source: grafloria-engine-serialization.md -->

# Serialization

Import these from `@grafloria/engine`.

## Functions

### `beginIncrementalCapture`

Convenience: start watching a diagram for incremental commits.

```ts
function beginIncrementalCapture(diagram: DiagramModel): IncrementalCapture
```

### `canonicalStringify`

Deterministic JSON: object keys sorted recursively so the same logical
document always hashes identically, regardless of property insertion order. (Arrays keep their order — element order IS meaning in nodes/links.)

```ts
function canonicalStringify(value: unknown): string
```

### `checksumOf`

Integrity checksum of a document's canonical JSON.

```ts
function checksumOf(document: SerializedDiagram): string
```

### `deserializeSubgraphInto`

Install a subgraph into a live diagram through the unified restore path.

This is a USER MUTATION (unlike document load): entities are installed via
restore* so the normal node:added/link:added events fire for undo and
rendering, and port registries are reconciled at the end.

```ts
function deserializeSubgraphInto(
  diagram: DiagramModel,
  subgraph: SerializedSubgraph,
  options: DeserializeSubgraphOptions = {}
): DeserializedSubgraph
```

### `exportDiagramText`

Export a diagram as Mermaid-compatible text. With `lossless` (default) the
exact document travels in a `%%grafloria:document` comment, so importing this
text reproduces the diagram byte-for-byte (serialize-equality), while the
body stays renderable by any Mermaid consumer.

```ts
function exportDiagramText(
  diagram: DiagramModel,
  options: ExportTextOptions = {}
): string
```

### `getDiagramMigrations`

Registered migrations, in order (primarily for tests/diagnostics).

```ts
function getDiagramMigrations(): readonly DiagramMigration[]
```

### `importDiagramText`

Import diagram text. Sidecar-carrying text loads losslessly through the
unified JSON path; pure Mermaid text parses through the DSL (best effort —
the documented lossy boundary). See ImportTextOptions.prefer for who wins
when the body was hand-edited after export.

```ts
function importDiagramText(
  text: string,
  options: ImportTextOptions = {}
): ImportTextResult
```

### `isDiagramDocumentEnvelope`

```ts
function isDiagramDocumentEnvelope(value: unknown): value is DiagramDocumentEnvelope
```

### `registerDiagramMigration`

Register a document migration. Apps embedding the engine can register their
own steps when they extend the document shape.

```ts
function registerDiagramMigration(migration: DiagramMigration): void
```

### `runDiagramMigrations`

Upgrade a serialized document to DIAGRAM_SCHEMA_VERSION.

- A document with no `schemaVersion` is treated as v1.
- A document NEWER than the runtime throws (loading it would silently drop
  or mangle data written by a newer app — the caller must upgrade instead).
- A missing step in the chain throws (a partial upgrade is worse than none).

```ts
function runDiagramMigrations(
  data: SerializedDiagram,
  migrations: readonly DiagramMigration[] = registry
): SerializedDiagram
```

**Parameters**

- `migrations`: override the global registry (tests / embedders).

### `serializeSubgraph`

```ts
function serializeSubgraph(
  diagram: DiagramModel,
  selection: SubgraphSelection
): SerializedSubgraph
```

### `stripGrafloriaSidecar`

The body without any %%grafloria sidecar lines (what a human reads/edits).

```ts
function stripGrafloriaSidecar(text: string): string
```

### `unwrapDiagramDocument`

Accepts an enveloped document OR a legacy flat SerializedDiagram and
returns the inner document. When the envelope carries a checksum it is
verified (throws DiagramChecksumError on mismatch — an integrity failure
must never load silently).

```ts
function unwrapDiagramDocument(
  input: SerializedDiagram | DiagramDocumentEnvelope
): UnwrapResult
```

### `validateSerializedDiagram`

```ts
function validateSerializedDiagram(data: SerializedDiagram): DiagramValidationReport
```

### `wrapDiagramDocument`

```ts
function wrapDiagramDocument(
  document: SerializedDiagram,
  options: WrapOptions = {}
): DiagramDocumentEnvelope
```

## Classes

### `DiagramChecksumError`

```ts
class DiagramChecksumError extends Error
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `message` | `string` |  |  |
| `stack?` | `string` |  |  |

**Methods**

- `constructor( public readonly expected: string, public readonly actual: string )`

### `DiagramSerializer`

```ts
class DiagramSerializer
```

**Methods**

- `serialize(diagram: DiagramModel): SerializedDiagram` — Serialize diagram to plain object
- `serializeEnvelope(diagram: DiagramModel, options?: WrapOptions): DiagramDocumentEnvelope` — Serialize wrapped in the portable document envelope (generator identity,
createdAt, integrity checksum). The envelope is the recommended shape for
NEW persistence; deserialize() accepts both it and the legacy flat form.
- `deserialize( data: SerializedDiagram | DiagramDocumentEnvelope, options?: DiagramLoadOptions ): DiagramModel` — Deserialize diagram from plain object — accepts the enveloped document,
the legacy Serializer flat form, or a raw DiagramModel.serialize payload. Envelope checksums are verified (mismatch throws — corruption must never
load silently).

### `DiagramValidationError`

Thrown by strict-mode loads when the document has integrity errors.

```ts
class DiagramValidationError extends Error
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `message` | `string` |  |  |
| `stack?` | `string` |  |  |

**Methods**

- `constructor(public readonly report: DiagramValidationReport)`

### `IncrementalCapture`

Watches a live diagram and produces a DiagramIncremental per commit(). Continues capturing after commit (autosave-loop friendly) until stop().

```ts
class IncrementalCapture
```

**Methods**

- `constructor(private readonly diagram: DiagramModel)`
- `hasChanges(): boolean` — Anything captured since the window began?
- `commit(): DiagramIncremental | null` — Drain the window into a patch (null when nothing changed) and keep
capturing. Added/modified entities are serialized LIVE at commit time,
so intra-window churn costs nothing.
- `stop(): void` — Unsubscribe everything. The capture cannot be reused afterwards.

## Constants

### `DIAGRAM_ENVELOPE_FORMAT`

```ts
const DIAGRAM_ENVELOPE_FORMAT: "grafloria-diagram"
```

### `DIAGRAM_ENVELOPE_VERSION`

```ts
const DIAGRAM_ENVELOPE_VERSION: 1
```

### `DIAGRAM_SCHEMA_VERSION`

The schema version this engine writes.

History:
 - 1: implicit — documents written before schemaVersion existed
      (fromJSON bypassed the wired restore path; groups could carry a
      runtime 'diagram' metadata key).
 - 2: documents written by the unified load/save path. Structurally
      identical to v1 except: `schemaVersion` is stamped, `groups` is
      always present, and runtime-only metadata is never serialized.

```ts
const DIAGRAM_SCHEMA_VERSION: 3
```

### `GRAFLORIA_DOC_PREFIX`

```ts
const GRAFLORIA_DOC_PREFIX: "%%grafloria:document "
```

### `GRAFLORIA_HASH_PREFIX`

```ts
const GRAFLORIA_HASH_PREFIX: "%%grafloria:body-hash "
```

### `INCREMENTAL_FORMAT`

```ts
const INCREMENTAL_FORMAT: "grafloria-incremental"
```

### `SUBGRAPH_FORMAT`

```ts
const SUBGRAPH_FORMAT: "grafloria-subgraph"
```

## Interfaces

### `DeserializedSubgraph`

```ts
interface DeserializedSubgraph
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `NodeModel[]` |  |  |
| `links` | `LinkModel[]` |  |  |
| `groups` | `GroupModel[]` |  |  |
| `idMap` | `Map<string, string>` |  | oldId -> newId for nodes and groups (identity map when remapIds=false). |
| `portIdMap` | `Map<string, string>` |  | oldPortId -> newPortId (identity when remapIds=false). |

### `DeserializeSubgraphOptions`

```ts
interface DeserializeSubgraphOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `remapIds?` | `boolean` |  | Mint fresh ids/uuids for every entity (default true). Turn off only when importing into a diagram KNOWN not to contain the ids (e.g. template instantiation into an empty document where stable ids are wanted). |
| `offset?` | `Point` |  | Translate all node/group positions by this delta (paste-at-cursor). |

### `DiagramDocumentEnvelope`

```ts
interface DiagramDocumentEnvelope
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `typeof DIAGRAM_ENVELOPE_FORMAT` |  |  |
| `envelopeVersion` | `number` |  |  |
| `generator` | `string` |  | Writer identity, e.g. '@grafloria/engine'. |
| `generatorVersion` | `string` |  | Writer version — the document schemaVersion the writer targets. |
| `createdAt` | `string` |  | ISO-8601 creation timestamp. |
| `checksum?` | `string` |  | FNV-1a hash of the canonical JSON of `document` (see canonicalStringify). |
| `document` | `SerializedDiagram` |  |  |

### `DiagramIncremental`

```ts
interface DiagramIncremental
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `typeof INCREMENTAL_FORMAT` |  |  |
| `schemaVersion` | `number` |  |  |
| `baseVersion` | `number` |  | diagram.version at the moment the window began (ordering hint). |
| `targetVersion` | `number` |  | diagram.version at commit — apply converges the replica's counter to it. |
| `added` | `{ nodes: SerializedNode[]; links: SerializedLink[]; groups: SerializedGroup[]; strokes?: SerializedStroke[]; }` |  |  |
| `removed` | `{ nodes: string[]; links: string[]; groups: string[]; strokes?: string[] }` |  |  |
| `modified` | `{ nodes: SerializedNode[]; links: SerializedLink[]; groups: SerializedGroup[]; strokes?: SerializedStroke[]; }` |  |  |
| `diagram?` | `{ name?: string; viewport?: { x: number; y: number; width: number; height: number; zoom: number }; metadata?: Record<string, unknown>; }` |  |  |

### `DiagramMigration`

```ts
interface DiagramMigration
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `number` |  | Source schema version this migration upgrades FROM. |
| `to` | `number` |  | Target schema version (must be from + 1 — migrations run stepwise). |
| `description` | `string` |  | Human-readable summary shown in errors/logs. |

**Members**

- `migrate(data: SerializedDiagram): SerializedDiagram` — Pure upgrade: receives the document, returns the upgraded document.

### `DiagramValidationFinding`

```ts
interface DiagramValidationFinding
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `severity` | `'error' \| 'warning'` |  |  |
| `code` | `string` |  | Stable machine-readable code (e.g. 'duplicate-id', 'dangling-link-endpoint'). |
| `message` | `string` |  |  |
| `entityId?` | `string` |  | Id of the entity the finding is about, when applicable. |

### `DiagramValidationReport`

```ts
interface DiagramValidationReport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` |  |  |
| `errors` | `DiagramValidationFinding[]` |  |  |
| `warnings` | `DiagramValidationFinding[]` |  |  |

### `ExportTextOptions`

```ts
interface ExportTextOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `lossless?` | `boolean` |  | Append the lossless sidecar (default true). Without it the text is pure Mermaid and imports are best-effort DSL parses (the lossy boundary). |
| `positions?` | `boolean` |  | Write every node's and zone's exact position and size as `%%grafloria:at id x,y WxH` (default false). The sidecar already carries them; this is for a READABLE body that redraws the same picture on its own — the way an AI-drawn diagram is written for Grafloria. |

### `ImportTextOptions`

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

```ts
interface ImportTextOptions extends DiagramLoadOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `prefer?` | `'auto' \| 'sidecar' \| 'text'` |  | Which source wins when both exist: - 'auto' (default): the sidecar wins UNLESS the body hash shows the body was hand-edited after export — then the edited body wins. - 'sidecar': always load the sidecar document (ignore body edits). - 'text': always parse the body text (ignore the sidecar). |

### `ImportTextResult`

```ts
interface ImportTextResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `DiagramModel` |  |  |
| `source` | `'sidecar' \| 'text'` |  | Which source actually produced the model. |
| `bodyEdited` | `boolean` |  | True when a sidecar existed but the body had been hand-edited. |
| `sidecarMerged?` | `boolean` |  | True when a hand-edited body was applied ON TOP of the sidecar document — the edit took, and everything the grammar cannot express (positions, styles, ports, groups, viewport) survived from the sidecar. |
| `sidecarInvalid?` | `boolean` |  | True when a sidecar line existed but its JSON would not parse. |
| `unsupported?` | `string` |  | Set to the diagram-type name when the body is a Mermaid type we recognise but do not yet parse (sequenceDiagram, gantt, pie, …). The diagram is empty rather than a garbage flowchart. |

### `SerializedDiagramData`

Also has every member of `SerializedDiagram`, `SerializedEntity`, listed on their own entries.

```ts
interface SerializedDiagram extends Omit<DiagramSerializedData, 'version'>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `version` | `string` |  |  |
| `diagramVersion?` | `number` |  |  |
| `mode?` | `DiagramMode` |  |  |

### `SerializedSubgraph`

```ts
interface SerializedSubgraph
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `typeof SUBGRAPH_FORMAT` |  |  |
| `schemaVersion` | `number` |  |  |
| `sourceDiagramId?` | `string` |  |  |
| `nodes` | `SerializedNode[]` |  |  |
| `links` | `SerializedLink[]` |  |  |
| `groups` | `SerializedGroup[]` |  |  |
| `boundaryLinks` | `Array<{ linkId: string; insideEnd: 'source' \| 'target' }>` |  | Links that crossed the selection boundary and were therefore excluded. |

### `SubgraphSelection`

```ts
interface SubgraphSelection
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeIds` | `Iterable<string>` |  |  |
| `groupIds?` | `Iterable<string>` |  |  |

### `UnwrapResult`

```ts
interface UnwrapResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `document` | `SerializedDiagram` |  |  |
| `envelope?` | `DiagramDocumentEnvelope` |  | Present when the input was enveloped. |

### `WrapOptions`

```ts
interface WrapOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `generator?` | `string` |  |  |
| `generatorVersion?` | `string` |  |  |
| `checksum?` | `boolean` |  | Include an integrity checksum (default true). |
| `createdAt?` | `string` |  | Timestamp override (tests / deterministic exports). |

<!-- source: grafloria-engine-state.md -->

# State

Import these from `@grafloria/engine`.

## Classes

### `ConnectionStateManager`

Manages connection creation state during drag operations

```ts
class ConnectionStateManager
```

**Methods**

- `constructor(eventBus: EventBus, diagram: DiagramModel | null = null)`
- `setDiagram(diagram: DiagramModel | null): void` — Point the manager at the live diagram (DiagramEngine calls this on load).
- `startConnection(sourcePort: PortModel, startPoint: Point): void` — Start connection drag from a port
- `updateConnection(currentPoint: Point, hoveredPort?: PortModel): void` — Update connection drag position
- `completeConnection(targetPort: PortModel): { success: boolean; link?: LinkModel }` — Complete connection to target port
- `cancelConnection(): void` — Cancel connection
- `setValidTargets(nodeIds: Set<string>, portIds: Set<string>): void` — Set valid target ports (called by a host that wants to narrow the set
further than the rules do — e.g. a wizard that only permits one legal move).
- `addValidator(validator: ConnectionValidator): void` — Add a custom connection validator
- `removeValidator(validator: ConnectionValidator): void` — Remove a custom connection validator
- `clearValidators(): void` — Clear all custom validators
- `getState(): Readonly<ConnectionDragState>` — Get current state (read-only)
- `isConnecting(): boolean` — Check if currently connecting
- `getSourcePort(): PortModel | null` — Get source port (if connecting)
- `getTargetPort(): PortModel | null` — Get target port (if hovering over one)
- `getCurrentMousePosition(): Point | null` — Get current mouse position
- `isOverValidTarget(): boolean` — Check if hovering over valid target

### `DiagramStore`

```ts
class DiagramStore
```

**Methods**

- `constructor(initialState?: Partial<DiagramState>)`
- `getState(): Readonly<DiagramState>` — Get current state (immutable)
- `setState(updater: (state: DiagramState) => void): void` — Set state with change tracking
- `select<T>(path: string): T` — Get state value by path
- `get(path: string): any` — Get state value by path
- `set(path: string, value: any): void` — Set state value by path
- `subscribe(listener: StateListener): () => void` — Subscribe to all state changes
- `watch(path: string, listener: PathListener): () => void` — Subscribe to path changes
- `computed<T>(key: string, compute: (state: DiagramState) => T, deps?: string[]): T` — Computed value with memoization
- `batch(fn: () => void): void` — Batch multiple state updates
- `reset(initialState?: Partial<DiagramState>): void` — Reset to initial state
- `timeTravel(index: number): void` — Time travel to history index
- `getHistory(): ReadonlyArray<StateSnapshot>` — Get history
- `createSnapshot(): StateSnapshot` — Create snapshot
- `restoreSnapshot(snapshot: StateSnapshot): void` — Restore snapshot

## Interfaces

### `ConnectionDragState`

Connection drag state
Tracks the state of an in-progress connection being dragged

```ts
interface ConnectionDragState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isConnecting` | `boolean` |  | Whether a connection is currently being dragged |
| `sourcePort` | `PortModel \| null` |  | Source port where connection started |
| `targetPort` | `PortModel \| null` |  | Target port currently hovered (if any) |
| `currentMousePosition` | `Point \| null` |  | Current mouse position in world coordinates |
| `previewPath` | `Point[] \| null` |  | Preview path points (for rendering connection line) |
| `validTargetNodes` | `Set<string>` |  | Set of node IDs that can accept this connection |
| `validTargetPorts` | `Set<string>` |  | Set of port IDs that can accept this connection |
| `isOverValidTarget` | `boolean` |  | Whether current hover position is over a valid target |
| `invalidTargetPorts` | `Map<string, ConnectionRejectionReason>` |  | Every port the drag has REJECTED, and why. |
| `rejectionReason?` | `ConnectionRejectionReason` |  | Why the CURRENT hover was rejected (undefined when it is valid). |
| `rejectionMessage?` | `string` |  | Human-readable form of {@link rejectionReason}. |

### `DiagramState`

```ts
interface DiagramState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `DiagramModel \| null` |  |  |
| `selectedNodes` | `Set<string>` |  |  |
| `selectedLinks` | `Set<string>` |  |  |
| `hoveredElement` | `string \| null` |  |  |
| `focusedElement` | `string \| null` |  |  |
| `viewport` | `Viewport` |  |  |
| `zoom` | `number` |  |  |
| `gridEnabled` | `boolean` |  |  |
| `snapEnabled` | `boolean` |  |  |
| `activeTool` | `string` |  |  |
| `toolOptions` | `Record<string, any>` |  |  |
| `mode` | `'design' \| 'runtime' \| 'readonly'` |  |  |
| `locked` | `boolean` |  |  |
| `theme` | `'light' \| 'dark'` |  |  |
| `showMinimap` | `boolean` |  |  |
| `showToolbar` | `boolean` |  |  |
| `showProperties` | `boolean` |  |  |
| `renderStats` | `RenderStats` |  |  |
| `errors` | `Error[]` |  |  |
| `warnings` | `string[]` |  |  |

### `RenderStats`

```ts
interface RenderStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fps` | `number` |  |  |
| `renderTime` | `number` |  |  |
| `nodeCount` | `number` |  |  |
| `linkCount` | `number` |  |  |
| `visibleNodes` | `number` |  |  |
| `visibleLinks` | `number` |  |  |

### `StateSnapshot`

```ts
interface StateSnapshot
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timestamp` | `number` |  |  |
| `state` | `DiagramState` |  |  |
| `version` | `string` |  |  |

## Types

### `ConnectionValidator`

Connection validation function
Returns true if connection is allowed

```ts
type ConnectionValidator = (
  sourcePort: PortModel,
  targetPort: PortModel
) => boolean;
```

### `PathListener`

```ts
type PathListener = (value: any, oldValue: any) => void;
```

### `StateListener`

```ts
type StateListener = (state: DiagramState, changes: string[]) => void;
```

<!-- source: grafloria-engine-sync.md -->

# Sync

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-classes): 6 classes.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-functions): 5 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-interfaces): 21 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-types): 4 types.
- [`Awareness`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-awareness): The presence store for one peer: our own state, and everyone else's.
- [`CausalBuffer`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-causalbuffer): Holds ops whose entity has not been added yet, and releases them the instant it is.
- [`SyncAdapter`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-syncadapter): Binds one `Replica` to one `SyncTransport`.
- [`UnreliableHub`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-sync-unreliablehub): A `MemoryHub` with the network's malice put back.

<!-- source: grafloria-engine-sync-classes.md -->

# Classes

Import these from `@grafloria/engine`.

## Classes

### `BroadcastChannelTransport`

```ts
class BroadcastChannelTransport implements SyncTransport
```

**Methods**

- `constructor(private readonly options: BroadcastChannelTransportOptions)`
- `get status(): TransportStatus`
- `static isSupported(): boolean` (static) — True when this environment can actually do cross-tab sync.
- `connect(): void` — Open (or re-open) the channel. Idempotent.
- `send(message: SyncMessage): void` — Broadcast to the other peers. A no-op — NOT an error — while disconnected.
- `onMessage(handler: (m: SyncMessage) => void): Unsubscribe` — Inbound messages from other peers. Never our own.
- `onStatus(handler: (s: TransportStatus) => void): Unsubscribe` — Connection transitions. THE hook the whole reconnect story hangs on: the adapter
subscribes here and fires an anti-entropy round the moment it hears 'connected'
again. A transport that never reports its status can never be caught up.
- `disconnect(): void` — Simulates (and, on `pagehide`, effects) a drop. Re-`connect()` to come back.
- `close(): void` — Tear down for good.

### `MemoryHub`

A shared bus. One hub = one document = one "room".

```ts
class MemoryHub
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `traffic` | `Array<{ from: ActorId; message: SyncMessage }>` | `[]` | Every message that crossed the bus — the wire tap the tests assert against. |

**Methods**

- `connect(actor: ActorId): MemoryTransport`
- `deliver(from: MemoryTransport, message: SyncMessage): void` — Deliver to everyone EXCEPT the sender. A peer never hears its own echo.
- `detach(port: MemoryTransport): void`
- `get peerCount(): number`

### `MemoryTransport`

```ts
class MemoryTransport implements SyncTransport
```

**Methods**

- `constructor( private readonly hub: MemoryHub, readonly actor: ActorId )`
- `get status(): TransportStatus`
- `send(message: SyncMessage): void` — Broadcast to the other peers. A no-op — NOT an error — while disconnected.
- `accept(message: SyncMessage): void` — Inbound. Ignored while disconnected — a dropped peer hears nothing, by definition.
- `onMessage(handler: Handler): Unsubscribe` — Inbound messages from other peers. Never our own.
- `onStatus(handler: (s: TransportStatus) => void): Unsubscribe` — Connection transitions. THE hook the whole reconnect story hangs on: the adapter
subscribes here and fires an anti-entropy round the moment it hears 'connected'
again. A transport that never reports its status can never be caught up.
- `connect(): void` — Open (or re-open) the channel. Idempotent.
- `disconnect(): void` — Close the channel but stay re-openable — this is what a "drop" is.
- `close(): void` — Tear down for good.

### `OpBatcher`

Accumulates local ops and flushes them as one coalesced, correctly-ordered batch.

```ts
class OpBatcher
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `queued` |  | `0` | Ops that went in. |
| `sent` |  | `0` | Ops that went out. `queued - sent` is what coalescing saved. |
| `batches` |  | `0` | Flushes performed. |

**Methods**

- `constructor(private readonly options: OpBatcherOptions)`
- `get size(): number`
- `push(op: Op): void`
- `flush(): void` — Send whatever is queued, right now. Idempotent, and a no-op when empty.
- `discard(): void` — Drop the queue WITHOUT sending.

Used on disconnect, and it is safe for exactly one reason: the ops are already in the
local log, so the peer will get them from the next anti-entropy round. If they were
not, this would be a silent data-loss hatch.
- `dispose(): void`

### `VersionVector`

A peer's exact position in the shared history, per actor.

Fed ONLY with ops the log genuinely accepted (`Replica.receive()` returns exactly
those). Feed it a duplicate and `count` over-counts, which fakes a hole and triggers a
pointless repair — wasteful, not wrong, but the discipline is worth keeping.

```ts
class VersionVector
```

**Methods**

- `observe(op: Op): void` — Record ONE op we now hold. Must be genuinely new — see the class doc.
- `observeAll(ops: Iterable<Op>): void`
- `frontier(actor: ActorId): ActorFrontier`
- `get actorCount(): number`
- `toJSON(): VersionVectorJSON`
- `static fromOps(ops: Iterable<Op>): VersionVector` (static) — Rebuild from a log — used on resume-from-disk, and by the tests as an oracle.

### `WebSocketTransport`

```ts
class WebSocketTransport implements SyncTransport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `attempts` |  | `0` | Reconnect attempts made. Asserted on by the backoff test. |

**Methods**

- `constructor(private readonly options: WebSocketTransportOptions)`
- `get status(): TransportStatus`
- `connect(): void` — Open (or re-open) the channel. Idempotent.
- `send(message: SyncMessage): void` — Broadcast to the other peers. A no-op — NOT an error — while disconnected.
- `onMessage(handler: (m: SyncMessage) => void): Unsubscribe` — Inbound messages from other peers. Never our own.
- `onStatus(handler: (s: TransportStatus) => void): Unsubscribe` — Connection transitions. THE hook the whole reconnect story hangs on: the adapter
subscribes here and fires an anti-entropy round the moment it hears 'connected'
again. A transport that never reports its status can never be caught up.
- `disconnect(): void` — Close the channel but stay re-openable — this is what a "drop" is.
- `close(): void` — Tear down for good.

<!-- source: grafloria-engine-sync-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `coalesce`

Drop every `set` that a later `set` in the same batch overwrites.

A stable filter: elements are removed, never reordered. Exported because it is worth
testing on its own, and because it is the part that is easy to get wrong.

RETURNS THE DROPPED OPS TOO, AND THAT IS NOT A CONVENIENCE — IT IS LOAD-BEARING.

An op that is coalesced away is an op the sender HAS (it is in its log) and the receiver
will NEVER have. Anti-entropy compares frontiers derived from logs, so unless the sender
knows exactly which ops it deliberately withheld, its frontier says "I hold 20 ops" while
the peer holds 1 — a gap indistinguishable from a lost packet, which triggers a full
history REPAIR on the next sync round. And the round after. Forever, because the peer can
never obtain ops that will never be sent.

That is a silent O(history) resend after EVERY DRAG — the most common interaction there
is. See `SyncAdapter.suppressed`.

```ts
function coalesce(ops: readonly Op[]): { kept: Op[]; dropped: Op[] }
```

### `createSyncSession`

Build a Replica and a SyncAdapter, correctly wired to each other.

The wiring is one line and it is easy to forget, and forgetting it produces the exact
failure this codebase is famous for: everything green, every unit test passing, and not
one edit ever reaching the wire — because `onLocalOp` went nowhere.

```ts
function createSyncSession(
  diagram: DiagramModel,
  transport: SyncTransport,
  options: SyncSessionOptions
): SyncAdapter
```

### `deltaFor`

THE CATCH-UP DELTA: which of `ours` does a peer with frontier `remote` not have?

Two tiers, and the tier is chosen PER ACTOR:

FAST  — our digest of that actor's ops at-or-below the peer's `max` matches theirs. Their frontier is honest; send only the tail above `max`. REPAIR— it does not match. There is a hole somewhere below their max and neither of
          us can say where. Send everything we have from that actor and let their log
          de-duplicate. Over-sending is free. Under-sending loses the document.

Returns ops in TOTAL ORDER — so a receiver that applies them in array order applies an
`add` before the `set`s that depend on it, and the causal buffer has nothing to do.

```ts
function deltaFor(
  ours: readonly Op[],
  remote: VersionVectorJSON
): { ops: Op[]; repairedActors: ActorId[] }
```

### `isDocumentMessage`

True for the ONE message kind that is allowed to touch the durable log.

```ts
function isDocumentMessage(msg: SyncMessage): msg is OpsMessage
```

### `mulberry32`

Deterministic PRNG (mulberry32). A fuzz you cannot replay is an anecdote.

```ts
function mulberry32(seed: number): () => number
```

<!-- source: grafloria-engine-sync-interfaces.md -->

# Interfaces

Import these from `@grafloria/engine`.

## Interfaces

### `ActorFrontier`

What one peer holds from one actor. Three numbers; see the header for why not one.

```ts
interface ActorFrontier
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` |  | Highest clock seen from this actor. |
| `count` | `number` |  | How many of this actor's ops we hold. A hole below `max` shows up here. |
| `hash` | `number` |  | Order-independent fold of the clocks held. Catches a hole `count` cannot see. |

### `AwarenessChange`

```ts
interface AwarenessChange
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `added` | `ActorId[]` |  |  |
| `updated` | `ActorId[]` |  |  |
| `removed` | `ActorId[]` |  |  |

### `AwarenessMessage`

Ephemeral presence. NEVER reaches the op log. See the header.

```ts
interface AwarenessMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `t` | `'awareness'` |  |  |
| `from` | `ActorId` |  |  |
| `state` | `AwarenessState \| null` |  | null ⇒ this peer is gone (an explicit, immediate tombstone; the TTL is the backup). |
| `seq` | `number` |  | Per-peer sequence. Awareness is last-write-wins PER PEER, and a reordering transport will hand you an old cursor after a new one — without this, the cursor jumps backwards. It is not a Lamport clock: peers never compare each other's awareness, only their own successive samples. |

### `AwarenessOptions`

```ts
interface AwarenessOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `ActorId` |  |  |
| `timeoutMs?` | `number` |  | Drop a peer we have not heard from in this long. |
| `now?` | `() => number` |  | Wall clock — injectable so the expiry tests are not a race against real time. |

### `AwarenessState`

Anything a peer publishes about ITSELF that is not a document edit.

```ts
interface AwarenessState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  | Human name for the badge. |
| `color?` | `string` |  | CSS colour. Derived deterministically from the actor id when absent. |
| `cursor?` | `{ x: number; y: number } \| null` |  | Pointer position in WORLD coordinates — never screen: peers have different cameras. |
| `selection?` | `string[]` |  | Entity ids this peer has selected. |

### `BroadcastChannelLike`

The slice of the BroadcastChannel API we use — so a test can hand us a fake.

```ts
interface BroadcastChannelLike
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onmessage` | `((event: { data: unknown }) => void) \| null` |  |  |

**Members**

- `postMessage(data: unknown): void`
- `close(): void`

### `BroadcastChannelTransportOptions`

```ts
interface BroadcastChannelTransportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | The room. Every peer on the same name shares a document. Namespace it by doc id. |
| `actor` | `ActorId` |  |  |
| `create?` | `(name: string) => BroadcastChannelLike` |  | Injectable factory — the default reaches for the global. |

### `ByeMessage`

"I am leaving." Best-effort — the TTL is what actually guarantees cleanup.

```ts
interface ByeMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `t` | `'bye'` |  |  |
| `from` | `ActorId` |  |  |

### `CausalBufferOptions`

```ts
interface CausalBufferOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `maxPending?` | `number` |  | Hard cap on held ops. A malicious or badly broken peer must not be able to make us buffer without limit; past the cap we release the oldest held op anyway (it will apply as a no-op and be logged, which is exactly what would have happened before this file existed — degraded, but bounded, and counted so it is visible). |

### `CausalSplit`

Where an op sits: released to the replica, or waiting on a dependency.

```ts
interface CausalSplit
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ready` | `Op[]` |  | Ready NOW, in total order. Hand straight to `Replica.receive()`. |
| `held` | `number` |  | Newly held this round (diagnostics). |

### `HelloMessage`

"I have joined." Carries the sender's frontier so an existing peer can push the
newcomer the history it lacks WITHOUT the newcomer having to ask a second time.

```ts
interface HelloMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `t` | `'hello'` |  |  |
| `from` | `ActorId` |  |  |
| `vv` | `VersionVectorJSON` |  |  |
| `awareness?` | `AwarenessState` |  | The sender's presence, so peers see the badge on the join frame, not 5s later. |

### `OpBatcherOptions`

```ts
interface OpBatcherOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onFlush` | `(kept: Op[], dropped: Op[]) => void` |  | Where a flushed batch goes. Never called with an empty `kept`. |
| `intervalMs?` | `number` |  | How long to accumulate, in ms. 16 ≈ one frame: a drag's pointermoves collapse into one message per frame, which is the point. |
| `maxBatch?` | `number` |  | Flush immediately once the queue reaches this many ops, regardless of the timer. Backpressure: a scripted bulk import can emit ten thousand ops inside one tick, and an unbounded queue would hand the transport a single ten-megabyte frame. |
| `setTimer?` | `(cb: () => void, ms: number) => unknown` |  | Injectable timer, so tests are deterministic and Node/browser both work. |
| `clearTimer?` | `(handle: unknown) => void` |  |  |

### `OpsMessage`

A batch of document ops. The only message that reaches the op log.

```ts
interface OpsMessage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `t` | `'ops'` |  |  |
| `from` | `ActorId` |  |  |
| `ops` | `Op[]` |  |  |

### `PeerPresence`

Another peer, as far as we know.

```ts
interface PeerPresence
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `ActorId` |  |  |
| `state` | `AwarenessState` |  |  |
| `lastSeen` | `number` |  | Wall-clock ms of the last message from them. NOT a Lamport clock — see below. |
| `seq` | `number` |  | Their sequence number for `state`. Guards against a reordered cursor sample. |

### `SyncAdapterOptions`

```ts
interface SyncAdapterOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `batch?` | `Omit<OpBatcherOptions, 'onFlush'> \| false` |  | Batching. `false` sends every op the instant it happens — legal, and a bad idea. |
| `relay?` | `boolean` |  | Forward ops that were NEW to us on to our other peers. |
| `syncIntervalMs?` | `number` |  | Periodic anti-entropy, ms. 0 disables it (the tests drive `sync()` by hand). |
| `heartbeatMs?` | `number` |  | Re-publish our awareness this often so peers do not time us out while we sit still. |
| `awarenessThrottleMs?` | `number` |  | Minimum ms between awareness sends. 60Hz in, ~20Hz out. |
| `awarenessTimeoutMs?` | `number` |  | Drop a peer's presence after this long without a word. |
| `setTimer?` | `(cb: () => void, ms: number) => unknown` |  | Injectables, so every timing test is deterministic instead of a race. |
| `clearTimer?` | `(handle: unknown) => void` |  |  |
| `setInterval?` | `(cb: () => void, ms: number) => unknown` |  |  |
| `clearInterval?` | `(handle: unknown) => void` |  |  |
| `now?` | `() => number` |  |  |

### `SyncSessionOptions`

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

```ts
interface SyncSessionOptions extends SyncAdapterOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `actor` | `ActorId` |  |  |
| `startClock?` | `number` |  | Resume the Lamport clock from a persisted tail. |

### `SyncStats`

Counters. Every one of them is something a test asserts on, not decoration.

```ts
interface SyncStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `messagesSent` | `number` |  | Messages handed to the transport. |
| `messagesReceived` | `number` |  | Messages taken from the transport. |
| `opsSent` | `number` |  | Ops we put on the wire (post-coalescing). |
| `opsReceived` | `number` |  | Ops that arrived. |
| `opsDuplicate` | `number` |  | …of which the log had already seen: duplicate delivery, absorbed. |
| `opsHeld` | `number` |  | Ops currently HELD by the causal buffer, waiting for an `add`. |
| `syncsRequested` | `number` |  | Anti-entropy rounds we asked for. |
| `repairs` | `number` |  | Times a peer's frontier turned out to have a HOLE and we resent an actor's history. |
| `opsCoalesced` | `number` |  | Ops the batcher swallowed because a later write superseded them. |
| `reconnects` | `number` |  | Reconnects observed. |

### `SyncTransport`

A pipe that moves `SyncMessage`s between peers.

The delivery model is BROADCAST-TO-OTHERS: `send()` delivers to every other peer on
the channel and never echoes back to the sender. (A star topology through a server, a
BroadcastChannel between tabs, and a full WebRTC mesh all present this way; a
point-to-point transport presents itself as a channel with one other peer.)

```ts
interface SyncTransport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `TransportStatus` |  |  |

**Members**

- `send(message: SyncMessage): void` — Broadcast to the other peers. A no-op — NOT an error — while disconnected.
- `onMessage(handler: (message: SyncMessage) => void): Unsubscribe` — Inbound messages from other peers. Never our own.
- `onStatus(handler: (status: TransportStatus) => void): Unsubscribe` — Connection transitions. THE hook the whole reconnect story hangs on: the adapter
subscribes here and fires an anti-entropy round the moment it hears 'connected'
again. A transport that never reports its status can never be caught up.
- `connect(): void` — Open (or re-open) the channel. Idempotent.
- `disconnect(): void` — Close the channel but stay re-openable — this is what a "drop" is.
- `close(): void` — Tear down for good.

### `UnreliableOptions`

```ts
interface UnreliableOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `seed?` | `number` |  |  |
| `dropRate?` | `number` |  | P(message is simply never delivered). |
| `duplicateRate?` | `number` |  | P(message is delivered more than once). |
| `delayRate?` | `number` |  | P(message is held in flight instead of delivered now) — this is what reorders. |
| `maxDuplicates?` | `number` |  | Max extra copies when duplicating. |

### `WebSocketLike`

The standard WebSocket surface — satisfied by the browser global AND by `ws`.

```ts
interface WebSocketLike
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `readyState` | `number` |  |  |
| `onopen` | `((event?: unknown) => void) \| null` |  |  |
| `onmessage` | `((event: { data: unknown }) => void) \| null` |  |  |
| `onclose` | `((event?: unknown) => void) \| null` |  |  |
| `onerror` | `((event?: unknown) => void) \| null` |  |  |

**Members**

- `send(data: string): void`
- `close(code?: number, reason?: string): void`

### `WebSocketTransportOptions`

```ts
interface WebSocketTransportOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | `string` |  |  |
| `socketFactory?` | `(url: string) => WebSocketLike` |  | The constructor. Defaults to the global. `ws` satisfies this in Node. |
| `reconnect?` | `boolean` |  | Reconnect backoff. The first retry waits `reconnectBaseMs`, then doubles to a cap. |
| `reconnectBaseMs?` | `number` |  |  |
| `reconnectMaxMs?` | `number` |  |  |
| `setTimer?` | `(cb: () => void, ms: number) => unknown` |  | Injectable, so the backoff test does not take 30 seconds of wall clock. |
| `clearTimer?` | `(h: unknown) => void` |  |  |

<!-- source: grafloria-engine-sync-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `SyncMessage`

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

```ts
type SyncMessage =
  | HelloMessage
  | SyncMessage_
  | OpsMessage
  | AwarenessMessage
  | ByeMessage;
```

### `TransportStatus`

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

```ts
type TransportStatus = 'connected' | 'disconnected';
```

### `TransportUnsubscribe`

```ts
type Unsubscribe = () => void;
```

### `VersionVectorJSON`

```ts
type VersionVectorJSON = Record<ActorId, ActorFrontier>;
```

<!-- source: grafloria-engine-sync-awareness.md -->

# Awareness

Import it from `@grafloria/engine`.

The presence store for one peer: our own state, and everyone else's.

Deliberately transport-free. `SyncAdapter` wires it to a channel; a test wires it to
nothing and drives it directly. It never sees an Op, a Replica or an OpLog, and that
is not an accident — it is the containment.

---------------------------------------------------------------------------
WHY `lastSeen` IS A WALL CLOCK WHEN THE LOG WENT TO SUCH LENGTHS TO AVOID ONE
---------------------------------------------------------------------------
Because the question is different. The log asks "did A happen before B?", which a wall
clock cannot answer across machines (they disagree, and they run backwards). Expiry
asks "has it been 15 seconds since I last heard from Bob?" — measured entirely on MY
clock, about MY receipts, comparing my own `now()` to my own earlier `now()`. Bob's
clock is never consulted, so its wrongness cannot infect anything. Using a Lamport
clock for a TIMEOUT would be the actual mistake: it has no relationship to seconds.

```ts
class Awareness
```

**Methods**

- `constructor(private readonly options: AwarenessOptions)`
- `get actor(): ActorId`
- `getLocalState(): AwarenessState` — Our own published state, and the sequence a peer will LWW it by.
- `get localSeq(): number`
- `setLocalState(patch: Partial<AwarenessState>): boolean` — Merge a patch into our own state and bump the sequence.

Returns false when nothing actually changed — a mouse that has not moved must not
burn a sequence number, wake the throttle, or send a message. (A `mousemove` fires
on sub-pixel jitter and on scroll; without this guard an idle user with a resting
hand is a 60Hz broadcaster.)
- `applyRemote(actor: ActorId, state: AwarenessState | null, seq: number): AwarenessChange | null` — Take a peer's published state.

`seq` is the whole reason a reordered transport does not make a cursor jump
backwards: a sample older than the one we already hold is REFUSED, exactly as the LWW
gate refuses a superseded op. Same idea, one scope down, and no shared machinery
because the lifecycles have nothing in common.
- `remove(actor: ActorId): AwarenessChange | null` — An explicit `bye`, or a transport that told us the peer is gone.
- `prune(): AwarenessChange | null` — Drop peers we have not heard from inside the timeout.

THE GUARANTEE, as opposed to `bye`, which is merely the optimisation. A crashed tab,
a closed laptop, a killed process and a severed cable all send no `bye` whatsoever,
and every one of them must eventually stop showing a cursor.
- `getPeers(): PeerPresence[]` — Everyone but us.
- `getPeer(actor: ActorId): PeerPresence | undefined`
- `get peerCount(): number`
- `clearPeers(): AwarenessChange | null` — Everyone is gone (we disconnected — we can no longer vouch for anyone).
- `onChange(listener: (change: AwarenessChange) => void): () => void`

<!-- source: grafloria-engine-sync-causalbuffer.md -->

# CausalBuffer

Import it from `@grafloria/engine`.

Holds ops whose entity has not been added yet, and releases them the instant it is.

Sits BETWEEN the transport and the Replica. Nothing it holds has touched the log, the
clock or the LWW registry — which is the whole point: an op the replica has never seen
is an op that can still be applied later.

```ts
class CausalBuffer
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `overflowed` |  | `0` | Ops force-released because the buffer was full. Should be 0. Watch it. |

**Methods**

- `constructor( private readonly diagram: DiagramModel, options: CausalBufferOptions = {} )`
- `get pendingCount(): number`
- `noteLocal(op: Op): void` — WE created an entity. Record it — the transport will never tell us about it.

THE FUZZ FOUND THIS ONE, AND IT IS A PERMANENT HANG, NOT A HICCUP.

`known` was fed from exactly two places: entities on the diagram at construction, and
`add` ops that arrived from PEERS. A node the local user creates during the session is
in NEITHER — so as far as the buffer was concerned, an entity this peer invented did
not exist.

Now watch a peer edit it. Bob creates node X. Alice learns about it, drags it, and
sends `set(X, position)`. It arrives at Bob, whose buffer asks "have I seen an `add`
for X?", answers NO, and holds it — waiting for an `add(X)` that is never coming, from
anyone, ever. It cannot come: the only `add(X)` in existence is Bob's OWN, it is
already in Bob's log, and Alice's anti-entropy correctly concludes that Bob already
has it and never echoes it back.

So Bob's node freezes wherever it was when he made it, Alice watches it move, and the
two documents differ forever — over the single most ordinary interaction in a
collaborative editor: one person moving another person's node. On a healthy transport
it never fires (the `set` cannot overtake an `add` that was never sent), which is
exactly why it took a reordering channel to find it.

No drain is needed. A peer can only `set` an entity it has learned about, which means
our `add` had already reached it — so nothing can be waiting on an id at the moment we
create it. The registration alone closes the hole.
- `admit(incoming: readonly Op[]): CausalSplit` — Split an arriving batch into what can be applied now and what must wait — and fold in
anything that was already waiting and has just become releasable.
- `pending(): Op[]` — Everything we are still holding — for a status panel, and for the tests.

<!-- source: grafloria-engine-sync-syncadapter.md -->

# SyncAdapter

Import it from `@grafloria/engine`.

Binds one `Replica` to one `SyncTransport`.

The replica must be constructed with `onLocalOp` pointing at `adapter.publish` — use
{@link createSyncSession}, which does that wiring for you and cannot get it backwards.

```ts
class SyncAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `awareness` | `Awareness` |  |  |
| `stats` | `SyncStats` |  |  |

**Methods**

- `constructor( readonly replica: Replica, private readonly transport: SyncTransport, private readonly options: SyncAdapterOptions = {} )`
- `get actor(): ActorId`
- `get diagram(): DiagramModel`
- `get pendingOps(): Op[]` — Ops still waiting on an `add` that has not arrived. Should return to 0.
- `frontier(): VersionVectorJSON` — What we tell peers we have.

THE INVARIANT, and it is worth stating as one because it is the whole correctness
condition of this layer in a single line:

frontier() === VersionVector.fromOps(sharedHistory())     — ALWAYS.

SHARED history, not the local log — an op coalescing withheld is not part of the history
we share with anyone, and advertising it would make every peer chase a hole that can
never be filled. That distinction IS the bug documented on `sharedHistory()`.

The frontier is a CACHE of that summary, maintained incrementally so we do not rescan
the history on every sync. A cache that disagrees with its source is not a performance
detail; it is a peer lying to the network about what it holds. Claim too much and you
never receive the op you are missing (silent data loss); claim too little and every
round resends an actor's entire history (a silent O(history) amplifier on the flakiest
connections, which is precisely where you can least afford it).

`sync-adapter.spec.ts` asserts this equality after a full hostile session, which is what
makes it a checked invariant rather than a comment.
- `join(): void` — Announce ourselves and ask for what we are missing.

`hello` carries our frontier, so an existing peer can push us the history we lack
without a second round trip — a joining peer should see the document on the first
message, not the third.
- `leave(): void` — Say goodbye and stop. Best-effort — the peers' TTL is what actually guarantees it.
- `sync(): void` — An anti-entropy round: "here is my frontier; send me what I lack, and tell me yours."

Called on join, on RECONNECT, and (optionally) on a timer. The timer is not paranoia:
a transport that can drop a message can drop an op, and the ONLY thing that ever
repairs that is asking again.
- `flush(): void` — Push any queued local ops onto the wire now.
- `publish(op: Op): void` — Our own edits. Wired to `Replica.onLocalOp` — see {@link createSyncSession}.

The local op is ALREADY in our log and already applied (the Replica did both before
calling us). Our job is only to get it to the others, so a failure to send is not a
failure to edit — it is a divergence the next sync round will close.
- `sharedHistory(): Op[]` — THE LOG AS THE NETWORK SEES IT — our history, minus everything coalescing withheld.

---------------------------------------------------------------------------
THE BUG THIS EXISTS TO FIX, WHICH WAS MINE, AND WHICH ONLY THE BROWSER FOUND
---------------------------------------------------------------------------
A 20-frame drag puts ONE op on the wire and leaves TWENTY in the local log — that is
coalescing working exactly as designed, and the two peers' documents agree perfectly.

But anti-entropy compares FRONTIERS DERIVED FROM LOGS. So on the next sync round my
frontier said "I hold 20 ops from alice" and the peer's said "I hold 1", and the digest
— which cannot tell a withheld op from a lost one — declared a HOLE and repaired it by
resending my entire history. Measured: `opsSent` went from 1 to 21 on the first sync
after a single drag. And it never settles, because the peer can NEVER obtain the 19 ops
I have deliberately decided never to send. Every sync round, forever, for the rest of
the session, on the most common interaction in the product.

It is invisible to a convergence oracle — the document is perfectly correct throughout —
and it was invisible to my own frontier-invariant test, which flushed after every single
op and therefore never once coalesced anything while syncing. It took driving a real drag
through a real browser to compose the two.

THE FIX is a definition, not a patch: THE FRONTIER DESCRIBES THE SHARED LOG. An op we
chose never to transmit is not part of the history we share with anyone, so it is not in
our frontier and it is not in the catch-up delta we serve — to ANY peer, including one
that joins tomorrow. Every peer therefore holds the same shared set, every digest agrees,
and the fast path stays fast.
- `setAwareness(patch: Partial<AwarenessState>): void` — Publish our cursor / selection / name.

THROTTLED, not debounced. A debounce would send nothing at all while the mouse keeps
moving — the cursor would only appear once you stopped, which is the exact opposite
of the feature. A throttle sends the newest sample at a bounded rate and drops the
ones in between, which is precisely correct for a value where only the latest matters.
- `dispose(): void`

<!-- source: grafloria-engine-sync-unreliablehub.md -->

# UnreliableHub

Import it from `@grafloria/engine`.

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

A `MemoryHub` with the network's malice put back.

Same API, same adapters, same protocol — the ONLY difference is that this one behaves
like the internet. If the sync layer is correct, nothing above it needs to change; if
it is not, this is where you find out.

```ts
class UnreliableHub extends MemoryHub
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `faults` |  |  | What the network actually did. Asserted on — a fuzz whose faults never fired is a lie. |

**Methods**

- `constructor(options: UnreliableOptions = {})`
- `override deliver(from: MemoryTransport, message: SyncMessage): void` — Deliver to everyone EXCEPT the sender. A peer never hears its own echo.
- `step(fraction = 0.5): number` — Release some of the in-flight queue, in a RANDOM order.

The random order is the point. A FIFO flush would only ever produce late delivery, and
late-but-ordered is the easy case — the LWW gate handles it alone. Releasing out of
order is what lets a `set` land before its `add`, which is the case that used to be
unrecoverable and is the reason `CausalBuffer` exists.
- `heal(): void` — Stop breaking things. The network has recovered; from here on it is a plain, honest
bus. Anything still lost was lost DURING the storm, and anti-entropy — not the
transport — is what has to find it.
- `settle(): void` — Deliver everything still in flight.
- `get inFlightCount(): number`
- `override connect(actor: ActorId): MemoryTransport`

<!-- source: grafloria-engine-template-library.md -->

# Template Library

Import these from `@grafloria/engine`.

## Functions

### `createTemplateLibrary`

Create a new template library instance
Factory function for creating template library managers

```ts
function createTemplateLibrary(includeBuiltIn = true): TemplateLibraryManager
```

**Parameters**

- `includeBuiltIn`: Whether to include built-in templates (default: true)

**Returns** New template library manager instance

### `getAllTemplates`

Get all templates as an array

```ts
function getAllTemplates(): NodeTemplate[]
```

### `getTemplatesByCategory`

Get templates grouped by category

```ts
function getTemplatesByCategory(): Record<TemplateCategory, NodeTemplate[]>
```

### `getUnregisteredTemplates`

Check if templates are registered in a TemplateRegistry

```ts
function getUnregisteredTemplates(registry: TemplateRegistry): string[]
```

**Example**

```typescript
const missing = getUnregisteredTemplates(engine.templateRegistry);
if (missing.length > 0) {
  console.log('Missing templates:', missing);
  registerTemplateLibrary(engine.templateRegistry);
}
```

### `initializeTemplateLibrary`

Initialize a template library with all built-in templates

```ts
function initializeTemplateLibrary(manager?: TemplateLibraryManager): TemplateLibraryManager
```

**Parameters**

- `manager`: Library manager to populate (optional, creates new if not provided)

**Returns** Populated template library manager

### `registerCustomTemplate`

Create a custom template and register it

```ts
function registerCustomTemplate(
  template: NodeTemplate,
  category: TemplateCategory,
  tags: string[] = []
): void
```

### `registerTemplateLibrary`

Use this to make the template library available to NodeFactory:

```ts
function registerTemplateLibrary(registry: TemplateRegistry): number
```

**Returns** Number of templates registered

**Example**

```typescript
import { registerTemplateLibrary } from '@grafloria/engine';

// In your engine setup
const count = registerTemplateLibrary(engine.templateRegistry);
// count = 20 (number of templates registered)

// Now you can use templates with NodeFactory
const node = engine.nodeFactory.createFromTemplate(
  'user-avatar',
  { name: 'John', status: 'online' },
  { x: 100, y: 100 }
);
```

### `registerTemplatesByCategory`

Register templates from a specific category

```ts
function registerTemplatesByCategory(
  registry: TemplateRegistry,
  category: 'common' | 'workflow' | 'data-viz' | 'diagram' | 'erd'
): number
```

**Returns** Number of templates registered

**Example**

```typescript
// Only register workflow templates
const count = registerTemplatesByCategory(engine.templateRegistry, 'workflow');
// count = 7 (number of workflow templates)
```

### `registerTemplatesById`

Register specific templates by ID

```ts
function registerTemplatesById(
  registry: TemplateRegistry,
  templateIds: string[]
): TemplateRegistrationResult
```

**Returns** Registration result with counts and missing template IDs

**Example**

```typescript
// Only register specific templates
const result = registerTemplatesById(engine.templateRegistry, [
  'user-avatar',
  'card-node',
  'process-step'
]);
// result = { registered: 3, notFound: [], total: 3 }
```

## Constants

### `CommonTemplates`

Export all common templates

```ts
const CommonTemplates: { UserAvatar: NodeTemplate; CardNode: NodeTemplate; ButtonNode: NodeTemplate; InputField: NodeTemplate; BadgeLabel: NodeTemplate; IconNode: NodeTemplate; }
```

### `DataVizTemplates`

Export all data visualization templates

```ts
const DataVizTemplates: { MetricCard: NodeTemplate; Gauge: NodeTemplate; BarChart: NodeTemplate; DataTable: NodeTemplate; PieChart: NodeTemplate; StatCounter: NodeTemplate; ProgressBar: NodeTemplate; }
```

### `ERDTemplates`

Export all ERD templates

```ts
const ERDTemplates: { ERDTable: NodeTemplate; ERDField: NodeTemplate; ERDRelationship: NodeTemplate; ERDTableOptionA: NodeTemplate; ERDFieldOptionA: NodeTemplate; ERDTableContainerOptionB: NodeTemplate; ERDTableHeaderOptionB: NodeTemplate; ERDFieldOptionB: NodeTemplate; ERDTableRepeater: NodeTemplate; }
```

### `TemplateLibrary`

Global template library instance (backward compatible)
Uses lazy initialization via getter

```ts
const TemplateLibrary: TemplateLibraryManager
```

### `WorkflowTemplates`

Export all workflow templates

```ts
const WorkflowTemplates: { ProcessStep: NodeTemplate; DecisionNode: NodeTemplate; StartEvent: NodeTemplate; EndEvent: NodeTemplate; Subprocess: NodeTemplate; Gateway: NodeTemplate; Activity: NodeTemplate; }
```

## Interfaces

### `TemplateInfo`

Template metadata for discovery

```ts
interface TemplateInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `template` | `NodeTemplate` |  |  |
| `category` | `TemplateCategory` |  |  |
| `tags` | `string[]` |  |  |

## Types

### `TemplateCategory`

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

Template categories for organization

```ts
type TemplateCategory = 'common' | 'workflow' | 'data-viz' | 'diagram' | 'erd';
```

## Other exports

### `Activity`

```ts
Activity
```

### `BadgeLabel`

```ts
BadgeLabel
```

### `BarChart`

```ts
BarChart
```

### `ButtonNode`

```ts
ButtonNode
```

### `CardNode`

```ts
CardNode
```

### `DataTable`

```ts
DataTable
```

### `DecisionNode`

```ts
DecisionNode
```

### `EndEvent`

```ts
EndEvent
```

### `ERDField`

```ts
ERDField
```

### `ERDRelationship`

```ts
ERDRelationship
```

### `ERDTable`

```ts
ERDTable
```

### `Gateway`

```ts
Gateway
```

### `Gauge`

```ts
Gauge
```

### `IconNode`

```ts
IconNode
```

### `InputField`

```ts
InputField
```

### `MetricCard`

```ts
MetricCard
```

### `PieChart`

```ts
PieChart
```

### `ProcessStep`

```ts
ProcessStep
```

### `ProgressBar`

```ts
ProgressBar
```

### `StartEvent`

```ts
StartEvent
```

### `StatCounter`

```ts
StatCounter
```

### `Subprocess`

```ts
Subprocess
```

### `UserAvatar`

```ts
UserAvatar
```

<!-- source: grafloria-engine-templates.md -->

# Templates

Import these from `@grafloria/engine`.

## Functions

### `builtInStencils`

The stencils that ship with Grafloria — the 80 generated NOTATION masters
(flowchart / BPMN / UML / ERD), each a true silhouette the SVG canvas draws. Freshly built on each call so a caller can mutate the returned arrays without
corrupting the built-ins.

```ts
function builtInStencils(): Stencil[]
```

### `generatedTemplates`

All generated masters, deduped by id (the registry keys on id anyway).

```ts
function generatedTemplates(): NodeTemplate[]
```

### `getStencil`

Built-in stencils, by id.

```ts
function getStencil(id: string): Stencil | undefined
```

### `listStencils`

Alias of {@link builtInStencils} — the palette's "what can I show?" call.

```ts
function listStencils(): Stencil[]
```

### `registerGeneratedTemplates`

Register every generated master into `registry`. Returns the number
registered. Idempotent — re-registering an id overwrites in place.

```ts
function registerGeneratedTemplates(registry: TemplateRegistry): number
```

### `registerStencils`

Register every master of the given stencils (default: all built-ins) into a
{@link TemplateRegistry}, so `NodeFactory` can stamp any of them by id. Returns the number of masters registered.

```ts
function registerStencils(registry: TemplateRegistry, stencils: Stencil[] = builtInStencils()): number
```

## Classes

### `NodeFactory`

```ts
class NodeFactory
```

**Methods**

- `constructor( private templateRegistry: TemplateRegistry, private diagram: DiagramModel )`
- `createFromTemplate( templateId: string, data: Record<string, any>, position: { x: number; y: number } ): NodeModel` — Create node(s) from template

### `TemplateLoader`

```ts
class TemplateLoader
```

**Methods**

- `static fromJSON(json: string): NodeTemplate` (static) — Load template from JSON string
- `static fromObject(obj: any): NodeTemplate` (static) — Load template from object
- `static fromJSONArray(json: string): NodeTemplate[]` (static) — Load multiple templates from JSON array
- `static toJSON(template: NodeTemplate, pretty: boolean = true): string` (static) — Export template to JSON string
- `static toJSONArray(templates: NodeTemplate[], pretty: boolean = true): string` (static) — Export multiple templates to JSON array

### `TemplateRegistry`

```ts
class TemplateRegistry
```

**Methods**

- `constructor(private eventBus: EventBus)`
- `register(template: NodeTemplate): void` — Register a template
- `registerMany(templates: NodeTemplate[]): void` — Register multiple templates
- `unregister(templateId: string): boolean` — Unregister a template
- `get(id: string): NodeTemplate | undefined` — Get template by ID
- `getAll(): NodeTemplate[]` — Get all registered templates
- `getByCategory(category: string): NodeTemplate[]` — Get templates by category
- `search(query: string): NodeTemplate[]` — Search templates by name, description, or tags
- `getCategories(): string[]` — Get all unique categories (sorted)
- `has(templateId: string): boolean` — Check if template exists
- `count(): number` — Get template count
- `clear(): void` — Clear all templates
- `registerValidator(id: string, validator: ConnectionValidator): void` — Register custom connection validator
- `getValidator(id: string): ConnectionValidator | undefined` — Get connection validator

## Interfaces

### `DataBindConfig`

Data binding configuration

```ts
interface DataBindConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bindings?` | `Record<string, string>` |  |  |
| `condition?` | `string` |  |  |

### `DragHandlerConfig`

Drag handler configuration

```ts
interface DragHandlerConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `isDragHandler` | `boolean` |  |  |
| `dragChildren?` | `boolean` |  |  |
| `snapToGrid?` | `boolean` |  |  |
| `gridSize?` | `number` |  |  |

### `HtmlConfig`

HTML rendering configuration
Enhanced to support LemonadeJS templates for framework-agnostic rendering

```ts
interface HtmlConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode?` | `'component' \| 'template'` |  | Rendering mode - 'component': Reference to a framework-specific component (Angular, React, etc.) - 'template': LemonadeJS template string (framework-agnostic) |
| `component?` | `string` |  | Component reference (for mode='component') Used when integrating with framework-specific components |
| `template?` | `string` |  | LemonadeJS template string (for mode='template') HTML string with LemonadeJS binding syntax Example: '<div>{{data.name}}</div>' |
| `className?` | `string \| string[]` |  | CSS classes to apply |
| `style?` | `Record<string, any>` |  | Inline styles |
| `bindings?` | `Record<string, string>` |  | Data bindings (property mappings) Maps template variables to node data paths Example: { userName: 'data.user.name', count: 'data.items.length' } |
| `events?` | `Record<string, string>` |  | Event handlers Maps DOM events to engine event names Example: { click: 'node:clicked', input: 'node:valueChanged' } |
| `zIndex?` | `number` |  | Z-index for HTML layer positioning |
| `pointerEvents?` | `boolean` |  | Whether to enable pointer events If false, the HTML layer won't capture mouse events (pass-through to SVG) |

### `NodeStructureDefinition`

Node structure definition (recursive)

```ts
interface NodeStructureDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `role?` | `NodeRole` |  |  |
| `size?` | `{ width?: number \| string; height?: number \| string; minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number; }` |  |  |
| `shape?` | `ShapeConfig` |  | Shape configuration for SVG rendering Defines the geometric shape of the node If not specified, defaults to rectangle |
| `labelPlacement?` | `'inside' \| 'below'` |  | Where the node's caption paints. `'inside'` (default) centres it in the shape's inner rect; `'below'` paints it centred UNDER the silhouette — the Visio/BPMN convention for glyph-sized masters (event circles, gateway diamonds, connectors, fork/join bars) whose caption cannot fit inside. Carried to the node as `metadata.labelPlacement`; the renderer consumes it. |
| `layout?` | `LayoutConfig` |  |  |
| `ports?` | `PortsConfig` |  |  |
| `behavior?` | `{ draggable?: boolean; dragHandler?: DragHandlerConfig; selectable?: boolean; connectable?: boolean; resizable?: boolean; deletable?: boolean; }` |  |  |
| `connectionGroup?` | `string` |  |  |
| `connectionRestrictions?` | `{ allowedGroups?: string[]; disallowedGroups?: string[]; customValidatorId?: string; }` |  |  |
| `html?` | `HtmlConfig` |  |  |
| `dataBind?` | `DataBindConfig` |  |  |
| `className?` | `string` |  |  |
| `style?` | `Record<string, any>` |  |  |
| `children?` | `NodeStructureDefinition[]` |  |  |
| `repeater?` | `RepeaterConfig` |  |  |

### `NodeTemplate`

Node template definition

```ts
interface NodeTemplate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique template identifier |
| `version` | `string` |  | Template version (semver) |
| `meta` | `TemplateMetadata` |  | Template metadata |
| `structure` | `NodeStructureDefinition` |  | Root node structure |
| `dataSchema?` | `Record<string, any>` |  | Data schema for validation (JSON Schema) |
| `defaultData?` | `Record<string, any>` |  | Default data values |
| `styles?` | `Record<string, any>` |  | Style presets |

### `PortConfig`

Port configuration for a specific side

```ts
interface PortConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `visibility?` | `PortVisibility` |  |  |
| `type?` | `'input' \| 'output' \| 'bi'` |  |  |
| `maxConnections?` | `number` |  |  |

### `PortRenderingConfig`

Port rendering configuration

```ts
interface PortRenderingConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `PortRenderingMode` |  | Rendering mode: 'svg', 'html', or 'auto' |
| `size?` | `{ width: number; height: number; hoverScale?: number; }` |  | Port size |
| `html?` | `{ component?: string; className?: string \| string[]; style?: Record<string, any>; zIndex?: number; }` |  | HTML-specific configuration |
| `svg?` | `{ shape?: 'circle' \| 'rect' \| 'custom'; fill?: string; stroke?: string; strokeWidth?: number; }` |  | SVG-specific configuration |
| `visibility?` | `{ default?: PortVisibility; showOnNodeHover?: boolean; showOnNodeSelected?: boolean; }` |  | Visibility configuration |

### `PortsConfig`

```ts
interface PortsConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled?` | `boolean` |  |  |
| `defaultVisibility?` | `PortVisibility` |  |  |
| `rendering?` | `PortRenderingConfig` |  |  |
| `groups?` | `PortGroupSpec[]` |  | . When present, the four side slots below are not consulted. |
| `top?` | `PortConfig` |  |  |
| `right?` | `PortConfig` |  |  |
| `bottom?` | `PortConfig` |  |  |
| `left?` | `PortConfig` |  |  |

### `RepeaterConfig`

Repeater configuration for dynamic children

```ts
interface RepeaterConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataSource` | `string` |  |  |
| `itemTemplate` | `NodeStructureDefinition` |  |  |
| `keyField?` | `string` |  |  |

### `ShapeConfig`

Shape configuration for SVG node rendering
Defines the geometric shape of the node in the SVG layer

```ts
interface ShapeConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `ShapeType` |  | Shape type |
| `fill?` | `string` |  | Fill color (CSS color) |
| `stroke?` | `string` |  | Stroke color (CSS color) |
| `strokeWidth?` | `number` |  | Stroke width in pixels |
| `cornerRadius?` | `number` |  | Corner radius for rectangles (in pixels) |
| `opacity?` | `number` |  | Opacity (0-1) |

### `Stencil`

A named, categorized set of masters — one section of a stencil palette.

```ts
interface Stencil
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable id, e.g. `'bpmn'`. |
| `name` | `string` |  | Display name for the palette section, e.g. `'BPMN'`. |
| `description` | `string` |  | One-line description of what the set covers. |
| `masters` | `NodeTemplate[]` |  | The shape masters in this set. |

### `TemplateMetadata`

Template metadata

```ts
interface TemplateMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `description?` | `string` |  |  |
| `category` | `string` |  |  |
| `icon?` | `string` |  |  |
| `preview?` | `string` |  |  |
| `tags?` | `string[]` |  |  |
| `author?` | `string` |  |  |
| `license?` | `string` |  |  |

## Types

### `FlexDirection`

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

Flexbox direction

```ts
type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
```

### `NodeRole`

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

Node role in hierarchy

```ts
type NodeRole = 'container' | 'drag-handler' | 'content' | 'repeater';
```

### `PortRenderingMode`

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

Port rendering mode

```ts
type PortRenderingMode = 'svg' | 'html' | 'auto';
```

### `PortVisibility`

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

Port visibility strategy

```ts
type PortVisibility = 'always' | 'on-hover' | 'never';
```

### `ShapeType`

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

Shape type for SVG rendering.

The five originals (rect/circle/ellipse/diamond/hexagon) plus the extended
flowchart / BPMN / UML / ERD figure library. Every value here has a matching
ShapeDefinition in the renderer's shape registry (libs/renderer/src/svg/
shape-registry.ts); adding a shape means: register its geometry there and add
its name here. A few widely-used aliases (database, stadium, data …) are
included so callers can type the vocabulary they already know.

```ts
type ShapeType =

  | 'rect'
  | 'circle'
  | 'ellipse'
  | 'diamond'
  | 'hexagon'

  | 'parallelogram'
  | 'parallelogram-top'
  | 'trapezoid'
  | 'trapezoid-bottom'
  | 'triangle'
  | 'triangle-down'
  | 'package'
  | 'cube'
  | 'document'
  | 'cylinder'
  | 'cloud'
  | 'predefined-process'
  | 'component'
  | 'note'
  | 'terminal'
  | 'actor'

  | 'delay'
  | 'display'
  | 'summing-junction'
  | 'or-junction'
  | 'sync-bar'
  | 'double-rect'
  | 'double-diamond'
  | 'double-ellipse'

  | 'gateway-xor'
  | 'gateway-or'
  | 'gateway-and'
  | 'event-intermediate'
  | 'final-node'

  | 'database'
  | 'stadium'
  | 'data'
  | 'subroutine'
  | 'folder';
```

<!-- source: grafloria-engine-types.md -->

# Types

Import these from `@grafloria/engine`.

## On their own pages

- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-constants): 9 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-functions): 4 functions.
- [Interfaces B–R](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-interfaces-b-r): 40 interfaces, `BoundingBox` to `Rectangle`.
- [Interfaces S–V](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-interfaces-s-v): 16 interfaces, `SelectionEvent` to `ViewportEvent`.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-types): 11 types.
- [`ArrowStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-arrowstyle)
- [`createDefaultLODConfig`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-createdefaultlodconfig): Build the default 3-tier LOD policy.
- [`LinkLabel`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-linklabel)
- [`LinkStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-linkstyle)
- [`NodeStyle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-types-nodestyle)

<!-- source: grafloria-engine-types-constants.md -->

# Constants

Import these from `@grafloria/engine`.

## Constants

### `ALL_LOD_FEATURES`

Every feature, in a stable order. Handy for "render everything" tiers.

```ts
const ALL_LOD_FEATURES: readonly LODFeature[]
```

### `BPMNTypes`

BPMN node type identifiers

```ts
const BPMNTypes: { readonly TASK: "bpmn:task"; readonly USER_TASK: "bpmn:user-task"; readonly SERVICE_TASK: "bpmn:service-task"; readonly MANUAL_TASK: "bpmn:manual-task"; readonly BUSINESS_RULE_TASK: "bpmn:business-rule-task"; readonly SCRIPT_TASK: "bpmn:script-task"; readonly EXCLUSIVE_GATEWAY: "bpmn:exclusive-gateway"; readonly PARALLEL_GATEWAY: "bpmn:parallel-gateway"; readonly INCLUSIVE_GATEWAY: "bpmn:inclusive-gateway"; readonly START_EVENT: "bpmn:start-event"; readonly END_EVENT: "bpmn:end-event"; readonly INTERMEDIATE_EVENT: "bpmn:intermediate-event"; readonly MESSAGE_EVENT: …
```

### `DEFAULT_FLEXBOX_CONFIG`

Default flexbox configuration

```ts
const DEFAULT_FLEXBOX_CONFIG: FlexboxLayoutConfig
```

### `DEFAULT_GRID_CONFIG`

Default grid configuration

```ts
const DEFAULT_GRID_CONFIG: GridLayoutConfig
```

### `DiagramEventTypes`

```ts
const DiagramEventTypes: { readonly NODE_ADDED: "node:added"; readonly NODE_REMOVED: "node:removed"; readonly NODE_MOVED: "node:moved"; readonly NODE_RESIZED: "node:resized"; readonly NODE_SELECTED: "node:selected"; readonly NODE_DESELECTED: "node:deselected"; readonly NODE_UPDATED: "node:updated"; readonly NODE_PARENT_CHANGED: "node:parent-changed"; readonly LINK_ADDED: "link:added"; readonly LINK_REMOVED: "link:removed"; readonly LINK_UPDATED: "link:updated"; readonly LINK_SELECTED: "link:selected"; readonly LINK_DESELECTED: "link:deselected"; readonly LINK_POINT_ADDED: "link:point-added"; …
```

### `ERDTypes`

ERD node type identifiers

```ts
const ERDTypes: { readonly ENTITY: "erd:entity"; readonly WEAK_ENTITY: "erd:weak-entity"; readonly RELATIONSHIP: "erd:relationship"; readonly WEAK_RELATIONSHIP: "erd:weak-relationship"; readonly ISA_RELATIONSHIP: "erd:isa"; readonly ATTRIBUTE: "erd:attribute"; readonly KEY_ATTRIBUTE: "erd:key-attribute"; readonly MULTIVALUED_ATTRIBUTE: "erd:multivalued-attribute"; readonly DERIVED_ATTRIBUTE: "erd:derived-attribute"; readonly COMPOSITE_ATTRIBUTE: "erd:composite-attribute"; readonly ASSOCIATIVE_ENTITY: "erd:associative-entity"; readonly PARTIAL_KEY_ATTRIBUTE: "erd:partial-key"; readonly …
```

### `FlowchartTypes`

Flowchart node type identifiers

```ts
const FlowchartTypes: { readonly PROCESS: "flowchart:process"; readonly DECISION: "flowchart:decision"; readonly TERMINAL: "flowchart:terminal"; readonly DATA: "flowchart:data"; readonly DOCUMENT: "flowchart:document"; readonly CONNECTOR: "flowchart:connector"; readonly DELAY: "flowchart:delay"; readonly MANUAL_INPUT: "flowchart:manual-input"; readonly MANUAL_OPERATION: "flowchart:manual-operation"; readonly PREDEFINED_PROCESS: "flowchart:predefined-process"; readonly STORED_DATA: "flowchart:stored-data"; readonly DISPLAY: "flowchart:display"; readonly PREPARATION: "flowchart:preparation"; …
```

### `IDENTITY_MATRIX`

Identity matrix (no transformation)

```ts
const IDENTITY_MATRIX: TransformMatrix
```

### `UMLTypes`

UML node type identifiers

```ts
const UMLTypes: { readonly CLASS: "uml:class"; readonly INTERFACE: "uml:interface"; readonly ABSTRACT_CLASS: "uml:abstract-class"; readonly ENUM: "uml:enum"; readonly PACKAGE: "uml:package"; readonly COMPONENT: "uml:component"; readonly NODE: "uml:node"; readonly ACTOR: "uml:actor"; readonly USE_CASE: "uml:use-case"; readonly STATE: "uml:state"; readonly INITIAL_STATE: "uml:initial-state"; readonly FINAL_STATE: "uml:final-state"; readonly NOTE: "uml:note"; readonly ACTIVITY: "uml:activity"; readonly DECISION: "uml:decision"; readonly MERGE: "uml:merge"; readonly FORK: "uml:fork"; readonly …
```

<!-- source: grafloria-engine-types-functions.md -->

# Functions

Import these from `@grafloria/engine`.

## Functions

### `registerBPMNTypes`

Register all BPMN types with the type registry

```ts
function registerBPMNTypes(registry: TypeRegistry): void
```

### `registerERDTypes`

Register all ERD types with the type registry

```ts
function registerERDTypes(registry: TypeRegistry): void
```

### `registerFlowchartTypes`

Register all flowchart types with the type registry

```ts
function registerFlowchartTypes(registry: TypeRegistry): void
```

### `registerUMLTypes`

Register all UML types with the type registry

```ts
function registerUMLTypes(registry: TypeRegistry): void
```

<!-- source: grafloria-engine-types-interfaces-b-r.md -->

# Interfaces B–R

Import these from `@grafloria/engine`.

## Interfaces

### `BoundingBox`

```ts
interface BoundingBox
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `left` | `number` |  |  |
| `top` | `number` |  |  |
| `right` | `number` |  |  |
| `bottom` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `ClipboardEvent`

```ts
interface ClipboardEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeCount` | `number` |  |  |
| `linkCount` | `number` |  |  |
| `groupCount` | `number` |  |  |
| `operation` | `'copy' \| 'paste' \| 'duplicate'` |  |  |

### `CommandEvent`

```ts
interface CommandEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `commandName` | `string` |  |  |
| `commandId` | `string` |  |  |
| `success?` | `boolean` |  |  |
| `error?` | `string` |  |  |

### `DiagramEvent`

```ts
interface DiagramEvent<T = any>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `timestamp` | `number` |  |  |
| `data` | `T` |  |  |
| `source?` | `string` |  |  |
| `preventDefault?` | `() => void` |  |  |
| `stopPropagation?` | `() => void` |  |  |

### `EntityWithLOD`

Entity with Level of Detail information

```ts
interface EntityWithLOD<T>
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entity` | `T` |  |  |
| `lod` | `LODLevel` |  |  |

### `EventSubscription`

```ts
interface EventSubscription
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `unsubscribe` | `() => void` |  |  |

### `FlexboxLayoutConfig`

Flexbox container configuration
Maps directly to CSS Flexbox properties

```ts
interface FlexboxLayoutConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` |  | Main axis direction |
| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` |  | Whether items wrap to multiple lines |
| `justifyContent` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around' \| 'space-evenly'` |  | Main axis alignment |
| `alignItems` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Cross axis alignment |
| `alignContent` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around' \| 'stretch'` |  | Multi-line cross axis alignment |
| `gap` | `number \| { row: number; column: number }` |  | Gap between items (px) |
| `padding?` | `number \| { top: number; right: number; bottom: number; left: number }` |  | Padding inside container (px) |
| `columns?` | `number` |  | Column-based layout (like Bootstrap 12-column grid) |

### `FlexItemConfig`

Flexbox item configuration
Applied to nodes inside a flexbox container

```ts
interface FlexItemConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `order?` | `number` |  | Display order (default: 0) |
| `flexGrow?` | `number` |  | Growth factor (default: 0) |
| `flexShrink?` | `number` |  | Shrink factor (default: 1) |
| `flexBasis?` | `number \| 'auto'` |  | Base size before growing/shrinking (default: 'auto') |
| `alignSelf?` | `'auto' \| 'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Override container's align-items for this item |

### `GradientStop`

```ts
interface GradientStop
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `number` |  |  |
| `color` | `string` |  |  |
| `opacity?` | `number` |  |  |

### `GridItemConfig`

Grid item configuration
Applied to nodes inside a grid container

```ts
interface GridItemConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columnStart?` | `number \| 'auto'` |  | Starting column line (1-based or 'auto') |
| `columnEnd?` | `number \| 'auto'` |  | Ending column line (1-based or 'auto') |
| `rowStart?` | `number \| 'auto'` |  | Starting row line (1-based or 'auto') |
| `rowEnd?` | `number \| 'auto'` |  | Ending row line (1-based or 'auto') |
| `gridArea?` | `string` |  | Named grid area to place item in |
| `justifySelf?` | `'auto' \| 'start' \| 'center' \| 'end' \| 'stretch'` |  | Override container's justify-items for this item |
| `alignSelf?` | `'auto' \| 'start' \| 'center' \| 'end' \| 'stretch'` |  | Override container's align-items for this item |

### `GridLayoutConfig`

Grid container configuration
Maps directly to CSS Grid properties

```ts
interface GridLayoutConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `templateColumns` | `string` |  | Column track definitions (e.g., "repeat(3, 1fr)", "100px 200px auto") |
| `templateRows` | `string` |  | Row track definitions |
| `templateAreas?` | `string[]` |  | Named grid areas |
| `columnGap` | `number` |  | Gap between columns (px) |
| `rowGap` | `number` |  | Gap between rows (px) |
| `autoFlow` | `'row' \| 'column' \| 'dense'` |  | Auto-placement algorithm |
| `autoColumns?` | `string` |  | Auto-generated column size |
| `autoRows?` | `string` |  | Auto-generated row size |
| `justifyItems?` | `'start' \| 'center' \| 'end' \| 'stretch'` |  | Horizontal alignment of items within cells |
| `alignItems?` | `'start' \| 'center' \| 'end' \| 'stretch'` |  | Vertical alignment of items within cells |
| `justifyContent?` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around' \| 'space-evenly'` |  | Horizontal alignment of grid within container |
| `alignContent?` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around' \| 'space-evenly'` |  | Vertical alignment of grid within container |
| `padding?` | `number \| { top: number; right: number; bottom: number; left: number }` |  | Padding inside container (px) |

### `GroupEvent`

```ts
interface GroupEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `groupId` | `string` |  |  |
| `group?` | `any` |  |  |

### `JumpPointConfig`

```ts
interface JumpPointConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `size?` | `number` |  |  |
| `style?` | `'arc' \| 'gap' \| 'bridge'` |  |  |
| `detectMode?` | `'all' \| 'perpendicular' \| 'threshold'` |  |  |
| `threshold?` | `number` |  |  |

### `LabelStyle`

```ts
interface LabelStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fontSize?` | `number` |  |  |
| `fontFamily?` | `string` |  |  |
| `color?` | `string` |  |  |
| `background?` | `string` |  |  |
| `padding?` | `number` |  |  |
| `borderRadius?` | `number` |  |  |
| `fontWeight?` | `'normal' \| 'bold' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900'` |  |  |
| `fontStyle?` | `'normal' \| 'italic' \| 'oblique'` |  |  |
| `textDecoration?` | `'none' \| 'underline' \| 'overline' \| 'line-through'` |  |  |
| `border?` | `string` |  |  |
| `borderWidth?` | `number` |  |  |
| `shadow?` | `Shadow` |  |  |
| `opacity?` | `number` |  |  |
| `lineHeight?` | `number` |  |  |

### `LayoutEvent`

```ts
interface LayoutEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `groupId` | `string` |  |  |
| `type` | `'flexbox' \| 'grid' \| 'none'` |  |  |
| `config?` | `any` |  |  |

### `LinearGradient`

```ts
interface LinearGradient
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'linear'` |  |  |
| `x1` | `number` |  |  |
| `y1` | `number` |  |  |
| `x2` | `number` |  |  |
| `y2` | `number` |  |  |
| `stops` | `GradientStop[]` |  |  |

### `LinkAnimation`

```ts
interface LinkAnimation
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'marching-ants' \| 'flow' \| 'pulse' \| 'dash-flow' \| 'none'` |  |  |
| `duration?` | `number` |  |  |
| `dashOffset?` | `number` |  |  |
| `speed?` | `'slow' \| 'normal' \| 'fast'` |  |  |
| `direction?` | `'forward' \| 'reverse'` |  |  |

### `LinkEvent`

```ts
interface LinkEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `linkId` | `string` |  |  |
| `link?` | `any` |  |  |

### `LinkState`

```ts
interface LinkState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selected` | `boolean` |  |  |
| `hovered` | `boolean` |  |  |
| `highlighted` | `boolean` |  |  |
| `animated?` | `boolean` |  |  |

### `LODConfig`

A declarative, per-diagram Level-of-Detail policy. Replaces the hardcoded
zoom breakpoints and per-tier feature gates that used to live inside
DiagramModel.

```ts
interface LODConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tiers` | `LODTier[]` |  |  |

### `LODTier`

One rung of a Level-of-Detail policy.

```ts
interface LODTier
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Tier name — returned by `getLODLevel()` and used as the render LOD key. |
| `minZoom` | `number` |  | Inclusive lower zoom bound. The active tier for a given zoom is the highest-`minZoom` tier whose `minZoom <= zoom`. |
| `features` | `Set<LODFeature>` |  | The set of features that render at this tier. |

### `Marker`

```ts
interface Marker
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'arrow' \| 'circle' \| 'square' \| 'custom'` |  |  |
| `position` | `number` |  |  |
| `size?` | `number` |  |  |
| `color?` | `string` |  |  |

### `ModeEvent`

```ts
interface ModeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `'design' \| 'runtime' \| 'readonly'` |  |  |
| `previousMode?` | `'design' \| 'runtime' \| 'readonly'` |  |  |
| `reason?` | `string` |  |  |

### `NodeBehavior`

```ts
interface NodeBehavior
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selectable` | `boolean` |  |  |
| `draggable` | `boolean` |  |  |
| `resizable` | `boolean` |  |  |
| `rotatable` | `boolean` |  |  |
| `deletable` | `boolean` |  |  |
| `editable` | `boolean` |  |  |
| `connectable` | `boolean` |  |  |
| `groupable` | `boolean` |  |  |
| `cloneable` | `boolean` |  |  |
| `dragHandler?` | `{ isDragHandler: boolean; dragChildren?: boolean; }` |  |  |

### `NodeEvent`

```ts
interface NodeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `node?` | `any` |  |  |

### `NodeState`

```ts
interface NodeState
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` | `boolean` |  |  |
| `locked` | `boolean` |  |  |
| `selected` | `boolean` |  |  |
| `hovered` | `boolean` |  |  |
| `highlighted?` | `boolean` |  | Draw attention to the node without selecting it (search hits, traversal highlights, "related" emphasis). Independent of `selected`; when both are set, `selected` wins in the renderer's state precedence. |
| `focused` | `boolean` |  |  |
| `expanded` | `boolean` |  |  |
| `enabled` | `boolean` |  |  |
| `error?` | `string` |  |  |
| `warning?` | `string` |  |  |
| `status?` | `'idle' \| 'pending' \| 'running' \| 'completed' \| 'error' \| 'warning'` |  |  |
| `animateStatus?` | `boolean` |  |  |

### `ParallelLinkConfig`

Auto-separation of PARALLEL links (two or more links between
the same pair of nodes). Without it, ERD / BPMN / state-machine diagrams stack
every relationship between the same two entities on top of each other.

The links in a pair are fanned out symmetrically around the un-separated
route: with 2 links and spacing 16 the offsets are -8 and +8; with 3 they are
-16, 0, +16. Direction of the fan is the left/right normal of the source →
target vector, so both directions of a bidirectional pair fan consistently.

```ts
interface ParallelLinkConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled?` | `boolean` |  | Turn separation off for this link (it stays on the un-separated route). |
| `spacing?` | `number` |  | Distance between adjacent links in the group, in px. Default 16. |
| `offset?` | `number` |  | Extra offset added on top of the computed fan offset (px, signed). Lets an author nudge one member of a bundle without touching the others. |

### `Path`

```ts
interface Path
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `Point[]` |  |  |
| `segments` | `PathSegment[]` |  |  |

### `PathSegment`

```ts
interface PathSegment
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'move' \| 'line' \| 'curve' \| 'arc'` |  |  |
| `from` | `Point` |  |  |
| `to` | `Point` |  |  |
| `control1?` | `Point` |  |  |
| `control2?` | `Point` |  |  |
| `radius?` | `number` |  |  |

### `Pattern`

```ts
interface Pattern
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'dots' \| 'lines' \| 'grid' \| 'hatch' \| 'crosshatch'` |  |  |
| `color?` | `string` |  |  |
| `backgroundColor?` | `string` |  |  |
| `size?` | `number` |  |  |
| `spacing?` | `number` |  |  |

### `Plugin`

```ts
interface Plugin
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `metadata` | `PluginMetadata` |  |  |

**Members**

- `install(context: PluginContext): void | Promise<void>`
- `uninstall?(context: PluginContext): void | Promise<void>`
- `onActivate?(context: PluginContext): void`
- `onDeactivate?(context: PluginContext): void`

### `PluginConfig`

```ts
interface PluginConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` |  |  |
| `config?` | `Record<string, any>` |  |  |

### `PluginContext`

```ts
interface PluginContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` | `any` |  |  |
| `eventBus` | `any` |  |  |
| `config` | `Record<string, any>` |  |  |

### `PluginMetadata`

```ts
interface PluginMetadata
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `version` | `string` |  |  |
| `author?` | `string` |  |  |
| `description?` | `string` |  |  |
| `dependencies?` | `string[]` |  |  |

### `PluginRegistry`

```ts
interface PluginRegistry
```

**Members**

- `register(plugin: Plugin): void`
- `unregister(pluginName: string): void`
- `get(pluginName: string): Plugin | undefined`
- `has(pluginName: string): boolean`
- `list(): PluginMetadata[]`

### `Point`

```ts
interface Point
```

**Properties**

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

### `PortAlignment`

```ts
interface PortAlignment
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` |  |  |
| `offset` | `number` |  |  |

### `PortPosition`

```ts
interface PortPosition
```

**Properties**

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

### `RadialGradient`

```ts
interface RadialGradient
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'radial'` |  |  |
| `cx` | `number` |  |  |
| `cy` | `number` |  |  |
| `r` | `number` |  |  |
| `stops` | `GradientStop[]` |  |  |

### `Rectangle`

Rectangle defined by position and size
Used for viewport queries and spatial indexing

```ts
interface Rectangle
```

**Properties**

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

<!-- source: grafloria-engine-types-interfaces-s-v.md -->

# Interfaces S–V

Import these from `@grafloria/engine`.

## Interfaces

### `SelectionEvent`

```ts
interface SelectionEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `string[]` |  |  |
| `links?` | `string[]` |  |  |
| `groups?` | `string[]` |  |  |
| `source?` | `'user' \| 'api' \| 'pattern'` |  |  |
| `pattern?` | `string` |  |  |

### `SelfLoopConfig`

SELF-LOOP geometry (source node === target node). The loop
leaves the source port, bulges away from the node body and re-enters at the
target port. Several self-loops on the same node nest concentrically
(`size + i * spacing`), so each keeps its own label slot.

```ts
interface SelfLoopConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `number` |  | How far the loop bulges away from the node body (px). Default 40. |
| `width?` | `number` |  | Lateral span of the loop along the node's side (px). Only used when the source and target attachment points coincide (or nearly do) — the two ends are spread by this much so the loop has a body. Default = `size`. |
| `spacing?` | `number` |  | Extra size added per additional self-loop on the same node (px). Default 18. |
| `side?` | `'auto' \| 'top' \| 'right' \| 'bottom' \| 'left'` |  | Force the side the loop bulges out of. `'auto'` (default) uses the source port's own side. |

### `SerializedEntity`

```ts
interface SerializedEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `uuid` | `string` |  |  |
| `type` | `string` |  |  |
| `version` | `number` |  |  |
| `metadata` | `Record<string, any>` |  |  |

### `SerializedFlexItemConfig`

Serialized flex item configuration

```ts
interface SerializedFlexItemConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `order?` | `number` |  |  |
| `flexGrow?` | `number` |  |  |
| `flexShrink?` | `number` |  |  |
| `flexBasis?` | `number \| 'auto'` |  |  |
| `alignSelf?` | `string` |  |  |

### `SerializedGridItemConfig`

Serialized grid item configuration

```ts
interface SerializedGridItemConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columnStart?` | `number \| 'auto'` |  |  |
| `columnEnd?` | `number \| 'auto'` |  |  |
| `rowStart?` | `number \| 'auto'` |  |  |
| `rowEnd?` | `number \| 'auto'` |  |  |
| `gridArea?` | `string` |  |  |
| `justifySelf?` | `string` |  |  |
| `alignSelf?` | `string` |  |  |

### `SerializedLayoutConfig`

Serialized layout configuration

```ts
interface SerializedLayoutConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `LayoutType` |  |  |
| `config?` | `LayoutConfig` |  |  |

### `Shadow`

```ts
interface Shadow
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `offsetX` | `number` |  |  |
| `offsetY` | `number` |  |  |
| `blur` | `number` |  |  |
| `color` | `string` |  |  |

### `Size`

```ts
interface Size
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `depth?` | `number` |  |  |

### `Transform`

```ts
interface Transform
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `Point` |  |  |
| `rotation` | `number` |  |  |
| `scale` | `Point` |  |  |
| `origin` | `Point` |  |  |

### `TransformMatrix`

2D Affine Transform Matrix
Represents: translate, rotate, scale, skew
CSS-compatible format: matrix(a, b, c, d, e, f)

Matrix structure:
| a  c  e |
| b  d  f |
| 0  0  1 |

Where:
- a, d: Scale X and Y (also affected by rotation/skew)
- b, c: Rotation and skew components
- e, f: Translation X and Y

```ts
interface TransformMatrix
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `a` | `number` |  |  |
| `b` | `number` |  |  |
| `c` | `number` |  |  |
| `d` | `number` |  |  |
| `e` | `number` |  |  |
| `f` | `number` |  |  |

### `ValidationError`

```ts
interface ValidationError
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` |  |  |
| `message` | `string` |  |  |
| `code` | `string` |  |  |
| `severity` | `'error'` |  |  |

### `ValidationEvent`

```ts
interface ValidationEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'diagram' \| 'node' \| 'link' \| 'port' \| 'group'` |  |  |
| `entityId?` | `string` |  |  |
| `result?` | `any` |  |  |
| `timestamp?` | `number` |  |  |

### `ValidationResult`

```ts
interface ValidationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `valid` | `boolean` |  |  |
| `errors` | `ValidationError[]` |  |  |
| `warnings` | `ValidationWarning[]` |  |  |

### `ValidationWarning`

```ts
interface ValidationWarning
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `string` |  |  |
| `message` | `string` |  |  |
| `code` | `string` |  |  |
| `severity` | `'warning'` |  |  |

### `Viewport`

```ts
interface Viewport
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `zoom` | `number` |  |  |
| `rotation` | `number` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |

### `ViewportEvent`

```ts
interface ViewportEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `zoom?` | `number` |  |  |
| `position?` | `{ x: number; y: number }` |  |  |
| `settings?` | `any` |  |  |

<!-- source: grafloria-engine-types-types.md -->

# Types

Import these from `@grafloria/engine`.

## Types

### `Alignment`

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

```ts
type Alignment = 'left' | 'right' | 'top' | 'bottom' | 'center';
```

### `DiagramEventType`

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

```ts
type DiagramEventType = typeof DiagramEventTypes[keyof typeof DiagramEventTypes];
```

### `Direction`

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

```ts
type Direction = 'horizontal' | 'vertical' | 'both';
```

### `EventHandler`

```ts
type EventHandler<T = any> = (event: DiagramEvent<T>) => void;
```

### `LayoutConfig`

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

Union type for all layout configurations

```ts
type LayoutConfig = FlexboxLayoutConfig | GridLayoutConfig;
```

### `LayoutType`

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

Layout type for containers

```ts
type LayoutType = 'none' | 'flexbox' | 'grid';
```

### `LinkLabelSlot`

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

The three label SLOTS along an edge (ngx-vflow ships exactly
these). A slot is shorthand for a `position`: start = 0.12, center = 0.5,
end = 0.88 — pulled off the very endpoints so a slot label never sits under
an arrowhead. An explicit `position` still wins.

```ts
type LinkLabelSlot = 'start' | 'center' | 'end';
```

### `LODFeature`

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

A visual feature that a {@link LODTier} may gate on. Renderers ask
`diagram.shouldRender(feature, lod)` instead of hardcoding zoom breakpoints.

THE ECONOMIC FEATURES. Everything above the divider gates a
DECORATION: dropping it removes a few attributes or a child VNode at the very
end of the pipeline, and the work that produced them ran anyway. That made LOD
cosmetic, not economic: a 10k-node zoom-out frame took 63 SECONDS because the
renderer was still routing every edge around every obstacle to place lines
whose detours were sub-pixel on screen.

The three below gate WORK, not paint. They are what makes a far-zoom frame
actually cheap, and they are the reason `LODFeature` is worth having at all.

```ts
type LODFeature =

  | 'labels'
  | 'icons'
  | 'borders'
  | 'shadows'
  | 'ports'
  | 'decorations'
  | 'handles'

  | 'routing'

  | 'link-detail'

  | 'gradients';
```

### `LODLevel`

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

Level of Detail tier name.

Widened from the fixed `'high' | 'medium' | 'low'` union to
`string` so apps can register their own tiers through {@link LODConfig}. The
three built-in tiers keep those exact names, so every historical
`lod === 'high'` / `lod !== 'low'` style check keeps working unchanged.

```ts
type LODLevel = string;
```

### `NodeSelectionLook`

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

How a selected node shows it is selected.
- `'both'` (default): the body takes the theme's selected colours AND a ring
  is drawn 3px outside it.
- `'border'`: only the node's own border changes (the selected colour, 2px);
  its fill stays and no ring is drawn — the card look.
- `'ring'`: only the ring; the body keeps its own paint.

```ts
type NodeSelectionLook = 'both' | 'border' | 'ring';
```

### `RoutingStrategy`

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

```ts
type RoutingStrategy = 'direct' | 'orthogonal' | 'smooth' | 'smart';
```

<!-- source: grafloria-engine-types-arrowstyle.md -->

# ArrowStyle

Import it from `@grafloria/engine`.

```ts
interface ArrowStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'none' \| 'arrow' \| 'circle' \| 'square' \| 'diamond' // Phase 4: ERD-specific arrows \| 'crow-foot' // ERD many relationship (⋈) \| 'one' // ERD one relationship (\|) \| 'zero-or-one' // ERD optional relationship (O\|) \| 'zero-or-many' // ERD optional many (O⋈) \| 'one-or-many' // ERD mandatory many (\|⋈) // Phase 4: UML-specific arrows \| 'hollow-diamond' // UML aggregation (◇) \| 'filled-diamond' // UML composition (◆) \| 'generalization' // UML inheritance (△) \| 'open-arrow' // UML dependency/realization (⊳) \| 'double-arrow' // Bidirectional (⇄) // Phase 4: Additional arrows \| 'cross' // X mark \| 'bar' // Perpendicular line (⊥) \| 'dot' // Simple dot \| 'oval' // Oval shape // Wave 4 (Edges & links) — Card 5: half-arrowheads (Mermaid 11.13) \| 'half-arrow-left' // Only the left barb (relative to direction of travel) \| 'half-arrow-right' // Only the right barb // Wave 4 — Card 5: author-defined marker. Either `path` (raw SVG path data, // drawn in the marker's local frame with the tip toward +x) or `marker` // (the name of a marker registered with `registerMarker` in @grafloria/renderer). \| 'custom' // …and any other registered marker name. Keeps literal autocompletion for // the built-ins while letting `registerMarker('my-thing', …)` be used by // name, so the catalogue is no longer a closed enum. \| (string & {})` |  |  |
| `size` | `number` |  |  |
| `filled` | `boolean` |  |  |
| `width?` | `number` |  |  |
| `offset?` | `number` |  |  |
| `color?` | `string` |  |  |
| `path?` | `string` |  | Raw SVG path data for a `type: 'custom'` marker. Drawn in the marker's LOCAL frame: the origin is the anchor the renderer pulls back from the endpoint, +x is the direction of travel. Scale it yourself (or read `size` when you build the string). |
| `marker?` | `string` |  | Name of a marker registered via `registerMarker`. Set it with `type: 'custom'` (or simply put the registered name in `type`). |
| `tipOffset?` | `number` |  | Distance from the custom marker's local origin to its visual TIP, in the +x direction. The renderer pulls the marker back from the path endpoint by exactly this much so the tip lands on the port. Registered markers supply their own default; this overrides it. Default 0 for an unregistered `path` marker (i.e. the tip is at the origin). |

<!-- source: grafloria-engine-types-createdefaultlodconfig.md -->

# createDefaultLODConfig

Import it from `@grafloria/engine`.

Build the default 3-tier LOD policy.

```
  zoom >= 1.0        -> 'high'   (everything)
  0.5 <= zoom < 1.0  -> 'medium' (labels, borders, ports, decorations, handles,
                                  + routing, link-detail, gradients)
  zoom <  0.5        -> 'low'    (nothing — plain rects and direct lines)
```

THE MEDIUM/LOW BREAKPOINT MOVED, 0.2 → 0.5, and that is the
behaviour change in this wave.

The old boundary made 'medium' span 0.2–1.0 with a near-full feature set, so a
diagram at 0.25 zoom — the zoom fit-to-content lands on for anything large —
still measured every label, drew every port, and routed every edge around every
obstacle. It was the far view that was expensive: 63 SECONDS for one 10k-node
frame, against 124ms for the near view. LOD had breakpoints but no economics.

Each breakpoint is now set where the DETAIL STOPS BEING LEGIBLE, not where it
stops being cheap — the theme's 12px label is 6px at 0.5 zoom and 3px at 0.25,
and a port glyph is under a pixel. Zooms in [0.5, 1.0) render exactly as they
always have. [0.2, 0.5) is 'sketch': text and chrome go (they are unreadable),
the graph's SHAPE stays (it is not). Below 0.2, everything goes.

Cost is deliberately NOT a factor in these numbers, because it cannot be: the
same zoom is cheap for 30 nodes and ruinous for 10,000, and a constant chosen
here would either tax the small diagram or fail to save the large one. That is
the quality governor's job — it measures the frame and steps the tier down on
the scenes and machines that need it. Perception picks the tier; measurement
decides whether you can afford it.

Fresh `Set`s are created per call so no two diagrams share mutable state.

```ts
function createDefaultLODConfig(): LODConfig
```

<!-- source: grafloria-engine-types-linklabel.md -->

# LinkLabel

Import it from `@grafloria/engine`.

```ts
interface LinkLabel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `text` | `string` |  |  |
| `position` | `number` |  |  |
| `offset` | `Point` |  |  |
| `style?` | `LabelStyle` |  |  |
| `rotation?` | `'auto' \| number` |  |  |
| `rotationOffset?` | `number` |  |  |
| `keepUpright?` | `boolean` |  |  |
| `textAnchor?` | `'start' \| 'middle' \| 'end'` |  |  |
| `textBaseline?` | `'top' \| 'middle' \| 'bottom'` |  |  |
| `textWrap?` | `boolean` |  |  |
| `maxWidth?` | `number` |  |  |
| `autoOffset?` | `boolean` |  | Auto-position this label so it does not overlap nodes, other labels or links. Handled by the diagram-wide edge optimizer: `offset` is the label's PREFERRED placement and the optimizer searches outward from it only when it collides. |
| `segmentIndex?` | `number` |  |  |
| `slot?` | `LinkLabelSlot` |  | One of the three edge slots. Shorthand for `position`; ignored when the label carries an explicit `position` (see LinkLabelSlot). |
| `html?` | `string` |  | Render this label as ARBITRARY HTML inside a `foreignObject` instead of SVG text. The string is injected verbatim, so it is the author's job to keep it trusted/escaped — exactly like any `innerHTML` seam. |
| `template?` | `string` |  | Name of a label template registered with `registerLabelTemplate` (@grafloria/renderer). The template returns VNodes, so it can emit SVG or a `foreignObject` full of HTML. Wins over `html`. |
| `width?` | `number` |  | Width of the HTML/template label's box (px). Default 120. |
| `height?` | `number` |  | Height of the HTML/template label's box (px). Default 28. |

<!-- source: grafloria-engine-types-linkstyle.md -->

# LinkStyle

Import it from `@grafloria/engine`.

```ts
interface LinkStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `className?` | `string` |  | Extra CSS class(es) put verbatim on the rendered path, alongside `diagram-link` and the state classes. Host-CSS hook; never read back. |
| `styleClass?` | `string` |  | Name(s) of NAMED STYLES to apply — the classDef / linkStyle equivalent. Space-separated (later names win). See NodeStyle.styleClass; identical cascade: theme < type-default < named-class < element-inline < state. |
| `stroke?` | `string \| LinearGradient \| RadialGradient \| Pattern` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `opacity?` | `number` |  |  |
| `arrowHead?` | `ArrowStyle` |  |  |
| `arrowTail?` | `ArrowStyle` |  |  |
| `curvature?` | `number` |  | Smooth/bezier curve TIGHTNESS, as a multiplier of the endpoint distance for the control-point offset. Default `0.5` (unchanged legacy behaviour); `0` collapses the curve onto its chord, larger values bulge harder. Honoured by both LinkModel.generateSmoothPath and the SVG renderer's control-point maths, so a link looks the same however its path was produced. |
| `jetty?` | `number` |  | . Minimum port-anchor stub (px): the route leaves the source and enters the target perpendicular to the port side for at least this length before the first bend — GUARANTEED, not best-effort (the router enforces it on whichever routing branch produced the path). Unset = the legacy 20px best-effort stub, byte-for-byte. |
| `cornerRadius?` | `number` |  | PER-LINK orthogonal corner radius (px). Defaults to the renderer's built-ins (5px for `orthogonal`, 12px for the rounded fallback a `smooth` detour falls back to). `0` gives hard 90° corners. |
| `jumpPoints?` | `JumpPointConfig` |  |  |
| `parallel?` | `ParallelLinkConfig` |  | How THIS link behaves when it is one of several links between the same pair of nodes. Per-link override of the renderer-wide `parallelLinks` config. |
| `selfLoop?` | `SelfLoopConfig` |  | How THIS link is drawn when it is a SELF-LOOP (source node === target node). Ignored on ordinary links. |
| `template?` | `string` |  | Name of a registered LINK TEMPLATE (`registerLinkTemplate` in |
| `gradient?` | `LinearGradient \| RadialGradient` |  |  |
| `pattern?` | `Pattern` |  |  |
| `shadow?` | `Shadow` |  |  |
| `animation?` | `LinkAnimation` |  |  |
| `markers?` | `Marker[]` |  |  |

<!-- source: grafloria-engine-types-nodestyle.md -->

# NodeStyle

Import it from `@grafloria/engine`.

```ts
interface NodeStyle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shape?` | `string` |  |  |
| `selection?` | `NodeSelectionLook` |  | How this node shows it is selected — see {@link NodeSelectionLook}. A style property like any other: set it per node, in a named style, per node type (`theme.nodes[type]`) or theme-wide (`theme.nodes.default`). |
| `className?` | `string` |  | Extra CSS class(es) put verbatim on the rendered element, alongside `diagram-node` and the state classes. Purely a hook for host CSS — the renderer never reads it back (React Flow's "className on every element"). |
| `styleClass?` | `string` |  | Name(s) of NAMED STYLES to apply — the classDef / linkStyle equivalent. Space-separated (`'critical dashed'`, later names win). Defined with `defineStyle(name, style)` and resolved by the renderer's cascade: theme < type-default < named-class < element-inline < state so an own property on this style object always beats the named style. |
| `fill?` | `string \| LinearGradient \| RadialGradient \| Pattern` |  |  |
| `stroke?` | `string \| LinearGradient \| RadialGradient \| Pattern` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `opacity?` | `number` |  |  |
| `shadow?` | `boolean \| Shadow` |  |  |
| `borderRadius?` | `number` |  |  |
| `fontSize?` | `number` |  |  |
| `fontFamily?` | `string` |  |  |
| `fontWeight?` | `string` |  |  |
| `fontStyle?` | `string` |  |  |
| `textDecoration?` | `string` |  |  |
| `color?` | `string` |  |  |
| `padding?` | `number` |  |  |
| `zIndex?` | `number` |  |  |
| `animatedBorder?` | `boolean` |  |  |
| `borderAnimationType?` | `'gradient' \| 'pulse' \| 'breathe' \| 'shimmer' \| 'none'` |  |  |
| `borderAnimationSpeed?` | `number` |  |  |
| `borderAnimationColors?` | `string[]` |  |  |

<!-- source: grafloria-engine-utils.md -->

# Utils

Import these from `@grafloria/engine`.

## Functions

### `boxesIntersect`

Check if two bounding boxes intersect

```ts
function boxesIntersect(box1: BoundingBox, box2: BoundingBox): boolean
```

### `clampToBox`

Clamp point to bounding box

```ts
function clampToBox(point: Point, box: BoundingBox): Point
```

### `createBoundingBox`

Create bounding box from position and size

```ts
function createBoundingBox(
  position: Point,
  size: Size
): BoundingBox
```

### `deepClone`

Deep clone an object with circular reference handling
Handles dates, arrays, maps, sets, plain objects, and circular references

```ts
function deepClone<T>(value: T, visited: WeakMap<any, any> = new WeakMap()): T
```

### `deepEqual`

Check if two values are deeply equal

```ts
function deepEqual(a: any, b: any): boolean
```

### `distance`

Calculate distance between two points

```ts
function distance(p1: Point, p2: Point): number
```

### `expandBox`

Expand bounding box by margin

```ts
function expandBox(box: BoundingBox, margin: number): BoundingBox
```

### `generateId`

Generate a short unique ID (12 characters)
Used for internal references

```ts
function generateId(): string
```

### `generatePrefixedId`

Generate a prefixed ID

```ts
function generatePrefixedId(prefix: string): string
```

### `generateUUID`

Generate a UUID
Used for persistent identifiers

```ts
function generateUUID(): string
```

### `isPointInShape`

Determine if a point is inside a shape
Returns true if point (px, py) is within the shape defined by bounds and shapeConfig

Shape-aware hit detection for accurate mouse interactions

```ts
function isPointInShape(
  px: number,
  py: number,
  bounds: BoundingBox,
  shapeConfig?: ShapeConfig
): boolean
```

### `isValidId`

Validate if string is a valid ID format

```ts
function isValidId(id: string): boolean
```

### `isValidUUID`

Validate if string is a valid UUID format

```ts
function isValidUUID(uuid: string): boolean
```

### `midpoint`

Calculate midpoint between two points

```ts
function midpoint(p1: Point, p2: Point): Point
```

### `pointInBox`

Check if point is inside bounding box

```ts
function pointInBox(point: Point, box: BoundingBox): boolean
```

### `rotatePoint`

Rotate point around origin

```ts
function rotatePoint(
  point: Point,
  origin: Point,
  angle: number
): Point
```

### `scalePoint`

Scale point from origin

```ts
function scalePoint(
  point: Point,
  origin: Point,
  scale: Point
): Point
```

<!-- source: grafloria-engine-validation.md -->

# Validation

Import these from `@grafloria/engine`.

## Functions

### `createConnectionGroupValidator`

Creates a connection validator that enforces connection group restrictions

Rules:
- Nodes in the same connection group can connect to each other
- Nodes with no connection group can connect to any node
- Nodes in different connection groups cannot connect

Usage:
```typescript
const validator = createConnectionGroupValidator(engine);
connectionStateManager.addValidator(validator);
```

```ts
function createConnectionGroupValidator(engine: DiagramEngine)
```

### `isConnectionAllowedByGroup`

Check if a connection between two ports is allowed based on connection groups
This is a standalone function that doesn't require a validator to be registered

```ts
function isConnectionAllowedByGroup(
  sourcePort: PortModel,
  targetPort: PortModel,
  engine: DiagramEngine
): boolean
```

## Classes

### `TypeRegistry`

```ts
class TypeRegistry
```

**Methods**

- `registerNodeType(definition: NodeTypeDefinition): void` — Register a node type
- `registerPortType(definition: PortTypeDefinition): void` — Register a port type
- `registerLinkType(definition: LinkTypeDefinition): void` — Register a link type
- `registerGroupType(definition: GroupTypeDefinition): void` — Register a group type
- `unregisterNodeType(type: string): boolean` — Unregister a node type
- `unregisterPortType(type: string): boolean` — Unregister a port type
- `unregisterLinkType(type: string): boolean` — Unregister a link type
- `unregisterGroupType(type: string): boolean` — Unregister a group type
- `getNodeType(type: string): NodeTypeDefinition | undefined` — Get node type definition
- `getPortType(type: string): PortTypeDefinition | undefined` — Get port type definition
- `getLinkType(type: string): LinkTypeDefinition | undefined` — Get link type definition
- `getGroupType(type: string): GroupTypeDefinition | undefined` — Get group type definition
- `hasNodeType(type: string): boolean` — Check if node type exists
- `hasPortType(type: string): boolean` — Check if port type exists
- `hasLinkType(type: string): boolean` — Check if link type exists
- `hasGroupType(type: string): boolean` — Check if group type exists
- `listNodeTypes(): NodeTypeDefinition[]` — List all node types
- `listPortTypes(): PortTypeDefinition[]` — List all port types
- `listLinkTypes(): LinkTypeDefinition[]` — List all link types
- `listGroupTypes(): GroupTypeDefinition[]` — List all group types
- `clear(): void` — Clear all registered types
- `getStats(): { nodeTypes: number; portTypes: number; linkTypes: number; groupTypes: number; }` — Get type statistics
- `resolveNodeType(type: string): NodeTypeDefinition` — Resolve a node type with all inherited properties
- `getNodeTypesByCategory(category: string): NodeTypeDefinition[]` — Get all node types in a category
- `getNodeTypesByFamily(family: string): NodeTypeDefinition[]` — Get all node types in a family
- `getNodeTypesByTag(tag: string): NodeTypeDefinition[]` — Get all node types with a specific tag
- `getNodeTypesByTemplate(templateId: string): NodeTypeDefinition[]` — Get all node types using a specific template
Includes types that inherit template ID from parent

### `ValidationEngine`

```ts
class ValidationEngine
```

**Methods**

- `constructor(typeRegistry: TypeRegistry, eventBus?: EventBus)`
- `enableRealTimeValidation(): void` — Enable real-time validation
- `disableRealTimeValidation(): void` — Disable real-time validation
- `isRealTimeValidationEnabled(): boolean` — Check if real-time validation is enabled
- `validateDiagram( diagram: DiagramModel, options: ValidationOptions = {} ): ValidationResult` — Validate entire diagram
- `validateNode( node: NodeModel, options: ValidationOptions = {} ): ValidationResult` — Validate a node
- `validatePort( port: PortModel, node: NodeModel, options: ValidationOptions = {} ): ValidationResult` — Validate a port
- `validateLink( link: LinkModel, diagram: DiagramModel, options: ValidationOptions = {} ): ValidationResult` — Validate a link
- `validateHierarchy( node: NodeModel, diagram: DiagramModel, options: ValidationOptions = {} ): ValidationResult` — Validate node hierarchy
- `validateGroup( group: GroupModel, diagram: DiagramModel, options: ValidationOptions = {} ): ValidationResult` — Validate group
- `validateLayout( group: GroupModel, diagram: DiagramModel, options: ValidationOptions = {} ): ValidationResult` — Validate layout configuration
- `addRule( entityType: 'diagram' | 'node' | 'port' | 'link', rule: ValidationRule ): void` — Add custom validation rule
- `clearRules(entityType: 'diagram' | 'node' | 'port' | 'link'): void` — Remove all custom rules for an entity type
- `clearAllRules(): void` — Clear all custom rules
- `getRulesCount(entityType?: 'diagram' | 'node' | 'port' | 'link'): number` — Get custom rules count

## Interfaces

### `GroupTypeDefinition`

```ts
interface GroupTypeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `label` | `string` |  |  |
| `description?` | `string` |  |  |
| `allowedMemberTypes?` | `string[]` |  |  |
| `allowedLinkTypes?` | `string[]` |  |  |
| `minMembers?` | `number` |  |  |
| `maxMembers?` | `number` |  |  |
| `canNest?` | `boolean` |  |  |
| `allowedLayoutTypes?` | `('flexbox' \| 'grid')[]` |  |  |
| `requireLayout?` | `boolean` |  |  |
| `validator?` | `(group: any) => ValidationResult` |  |  |

### `LinkTypeDefinition`

```ts
interface LinkTypeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `label` | `string` |  |  |
| `description?` | `string` |  |  |
| `allowedSourcePortTypes?` | `string[]` |  |  |
| `allowedTargetPortTypes?` | `string[]` |  |  |
| `validator?` | `(link: any) => ValidationResult` |  |  |

### `NodeTypeDefinition`

```ts
interface NodeTypeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `label?` | `string` |  |  |
| `description?` | `string` |  |  |
| `defaultData?` | `Record<string, any>` |  |  |
| `allowedPortTypes?` | `string[]` |  |  |
| `minPorts?` | `number` |  |  |
| `maxPorts?` | `number` |  |  |
| `validator?` | `(node: any) => ValidationResult` |  |  |
| `extends?` | `string` |  |  |
| `category?` | `string` |  |  |
| `family?` | `string` |  |  |
| `tags?` | `string[]` |  |  |
| `defaultBehavior?` | `Partial<NodeBehavior>` |  |  |
| `defaultStyle?` | `Partial<NodeStyle>` |  |  |
| `defaultSize?` | `Partial<Size>` |  |  |
| `allowedChildTypes?` | `string[]` |  |  |
| `allowedParentTypes?` | `string[]` |  |  |
| `maxChildren?` | `number` |  |  |
| `maxDepth?` | `number` |  |  |
| `canBeRoot?` | `boolean` |  |  |
| `templateId?` | `string` |  |  |
| `defaultPortRendering?` | `any` |  |  |

### `PortTypeDefinition`

```ts
interface PortTypeDefinition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `label` | `string` |  |  |
| `description?` | `string` |  |  |
| `direction` | `'input' \| 'output' \| 'bi'` |  |  |
| `maxConnections?` | `number` |  |  |
| `allowedLinkTypes?` | `string[]` |  |  |
| `validator?` | `(port: any) => ValidationResult` |  |  |

### `ValidationOptions`

```ts
interface ValidationOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `validateTypes?` | `boolean` |  |  |
| `validateConnections?` | `boolean` |  |  |
| `validatePorts?` | `boolean` |  |  |
| `strict?` | `boolean` |  |  |

## Types

### `ValidationRule`

```ts
type ValidationRule<T = any> = (entity: T) => ValidationResult;
```

<!-- source: grafloria-element-overview.md -->

# @grafloria/element

Web component, dashboard kit and UML/ERD kits for Grafloria — diagrams and dashboards in any framework or none. Grafloria is an MIT diagram and dashboard engine for JavaScript.

## Install

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
```

It expects these alongside it:

- `@grafloria/engine` ^0.3.16
- `@grafloria/renderer` ^0.4.15

## What it exports

- [Core](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-core): 20 exports, including `defineGrafloriaFlow`, `DiagramSpec`, `fromDocument`, `FromDocumentOptions`
- [Dashboard Kit](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit): 65 exports, including `BarWidgetData`, `bindDashboardGrid`, `boardHeightFor`, `buildCommitCommands`
- [Diagram Kit](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit): 53 exports, including `addColumnAt`, `assignTiers`, `bindCardEditing`, `bindJoinGuidance`
- [Stencil Kit](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-stencil-kit): 9 exports, including `bindShapeDataPanel`, `bindStencilPalette`, `ensureStencilKitStyles`, `ShapeDataPanelApi`

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-overview): `activeRegistryScope`, `actorColor`, `actorInitials`, `AddWaypointResult`, `Adjacency`, `AlignmentGuide`, `ALWAYS_SAFE_MODE`, `analyseTopology`, `AnchorContext`, `AnchorFn`, `AnchorResult`, `ANCHORS` and 967 more
- From [@grafloria/engine](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-engine-overview): `Activity`, `ActorFrontier`, `ActorId`, `AddGroupCommand`, `AddLinkCommand`, `AddNodeCommand`, `AddOp`, `AddPortCommand`, `AddStrokeCommand`, `AddToGroupCommand`, `affectedRegion`, `AlignCommand` and 914 more

<!-- source: grafloria-element-core.md -->

# Core

Import these from `@grafloria/element`.

## Functions

### `defineGrafloriaFlow`

Register the element. Idempotent, and safe to call on the server (where
`customElements` does not exist) — which is what lets a bundle be imported
from an SSR entry point without a `typeof window` dance at every call site.

```ts
function defineGrafloriaFlow(tagName = 'grafloria-flow'): void
```

### `fromDocument`

Turn a saved document back into something `render()` can mount.

```ts
const json = JSON.stringify(new DiagramSerializer().serialize(api.getModel()));
// …later, in a fresh page:
render(fromDocument(json), host);
```

Accepts the flat serializer form, the portable envelope, or the JSON string
of either.

```ts
function fromDocument(
  document: SavedDiagram,
  options: FromDocumentOptions = {}
): LoadedDiagramSpec
```

### `getNodeType`

```ts
function getNodeType(type: string): NodeTypeRenderer | undefined
```

### `hasNodeType`

```ts
function hasNodeType(type: string): boolean
```

### `registeredNodeTypes`

Every registered type name.

```ts
function registeredNodeTypes(): string[]
```

### `registerNodeType`

Register (or replace) a node type globally.

```ts
function registerNodeType(type: string, renderer: NodeTypeRenderer): void
```

### `render`

Mount `spec` into `target` and return the live instance.

`target` may be an element or a CSS selector. Custom nodes (`custom: true`)
are rendered by the types registered with {@link registerNodeType}.

SCOPE, stated plainly: `spec` is data (an object or its JSON), not a Mermaid-
style text DSL. The engine does have a DSL, but wiring it in is a separate
card — `render()` is the embedding surface, not a parser.

```ts
function render(
  spec: RenderSpec,
  target: HTMLElement | string,
  options: RenderOptions = {}
): DiagramInstance
```

### `renderFromTemplate`

Render a node from a slotted `<template data-node-type="...">`.

Clones the template's content into `element` and substitutes `node.data` into
every `[data-field="key"]` descendant's text. Values are written with
`textContent`, never `innerHTML`: a diagram's `data` is frequently
user-supplied, and a template engine that injected raw HTML here would be an
XSS vector in every host that embeds us.

```ts
function renderFromTemplate(
  template: HTMLTemplateElement,
  node: NodeModel,
  element: HTMLElement
): void
```

### `renderStatic`

Server-side render. Re-exported so the tiny API is self-contained.

```ts
function renderStatic(options: StaticRenderOptions = {}): StaticRenderResult
```

### `unregisterNodeType`

Drop a registration (mostly for tests).

```ts
function unregisterNodeType(type: string): void
```

## Classes

### `GrafloriaFlowElement`

Also has every member of `HTMLElement`, `Element`, `Node`, `ARIAMixin`, `GlobalEventHandlers`, listed on their own entries.

```ts
class GrafloriaFlowElement extends HTMLElementBase
```

Use it as `<grafloria-flow>` in a template.

**Props**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` |  |  |  |
| `edges?` |  |  |  |
| `theme?` |  |  |  |
| `fit-view` |  |  |  |
| `readonly?` |  |  |  |
| `zoom?` |  |  |  |
| `min-zoom` |  |  |  |
| `max-zoom` |  |  |  |
| `pan?` |  |  |  |
| `wheel-zoom` |  |  |  |
| `highlight-connected` |  |  |  |

**Events**

- `grafloria-ready`
- `grafloria-nodes-change`
- `grafloria-edges-change`
- `grafloria-selection-change`
- `grafloria-connect`
- `grafloria-node-click`
- `grafloria-edge-click`
- `grafloria-viewport-change`

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nextElementSibling` | `Element \| null` |  | Returns the first following sibling that is an element, and null otherwise. |
| `previousElementSibling` | `Element \| null` |  | Returns the first preceding sibling that is an element, and null otherwise. |
| `childElementCount` | `number` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/childElementCount) |
| `children` | `HTMLCollection` |  | Returns the child elements. |
| `firstElementChild` | `Element \| null` |  | Returns the first child that is an element, and null otherwise. |
| `lastElementChild` | `Element \| null` |  | Returns the last child that is an element, and null otherwise. |
| `assignedSlot` | `HTMLSlotElement \| null` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/assignedSlot) |
| `attributeStyleMap` | `StylePropertyMap` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/attributeStyleMap) |
| `contentEditable` | `string` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/contentEditable) |
| `enterKeyHint` | `string` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/enterKeyHint) |
| `inputMode` | `string` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/inputMode) |
| `isContentEditable` | `boolean` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/isContentEditable) |
| `autofocus` | `boolean` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/autofocus) |
| `dataset` | `DOMStringMap` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dataset) |
| `nonce?` | `string` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/nonce) |
| `tabIndex` | `number` |  | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/tabIndex) |

**Methods**

- `static get observedAttributes(): string[]` (static)
- `get nodes(): NodeSpec[]`
- `set nodes(value: NodeSpec[])`
- `get edges(): EdgeSpec[]`
- `set edges(value: EdgeSpec[])`
- `get diagram(): DiagramInstance | null` — The headless instance — the escape hatch to everything else.
- `connectedCallback(): void`
- `disconnectedCallback(): void`
- `attributeChangedCallback(name: string, previous: string | null, next: string | null): void`
- `fitView(padding?: number): void`
- `dispatchEvent(event: Event): boolean` — The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent)
- `animate(keyframes: Keyframe[] | PropertyIndexedKeyframes | null, options?: number | KeyframeAnimationOptions): Animation` — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/animate)
- `getAnimations(options?: GetAnimationsOptions): Animation[]` — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAnimations)
- `after(...nodes: (Node | string)[]): void` — Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/after)
- `before(...nodes: (Node | string)[]): void` — Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/before)
- `remove(): void` — Removes node.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/remove)
- `replaceWith(...nodes: (Node | string)[]): void` — Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/replaceWith)
- `append(...nodes: (Node | string)[]): void` — Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/append)
- `prepend(...nodes: (Node | string)[]): void` — Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/prepend)
- `querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null` — Returns the first element that is a descendant of node that matches selectors.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/querySelector)
- `querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>` — Returns all element descendants of node that match selectors.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll)
- `replaceChildren(...nodes: (Node | string)[]): void` — Replace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/replaceChildren)
- `blur(): void` — [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/blur)
- `focus(options?: FocusOptions): void` — [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/focus)

## Constants

### `Grafloria`

The namespace object, for `import { Grafloria }` and for `<script>` globals.

```ts
const Grafloria: { render: (spec: RenderSpec, target: string | HTMLElement, options?: RenderOptions) => DiagramInstance; renderStatic: (options?: StaticRenderOptions) => StaticRenderResult; registerNodeType: (type: string, renderer: NodeTypeRenderer) => void; registeredNodeTypes: () => string[]; define: (tagName?: string) => void; }
```

### `GRAFLORIA_EVENTS`

Events emitted on the element. All bubble and cross shadow boundaries.

```ts
const GRAFLORIA_EVENTS: { readonly ready: "grafloria-ready"; readonly nodesChange: "grafloria-nodes-change"; readonly edgesChange: "grafloria-edges-change"; readonly selectionChange: "grafloria-selection-change"; readonly connect: "grafloria-connect"; readonly nodeClick: "grafloria-node-click"; readonly edgeClick: "grafloria-edge-click"; readonly viewportChange: "grafloria-viewport-change"; }
```

## Interfaces

### `DiagramSpec`

What `Grafloria.render()` accepts: an object spec, or the JSON string of one.

```ts
interface DiagramSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes?` | `NodeSpec[]` |  |  |
| `edges?` | `EdgeSpec[]` |  |  |
| `groups?` | `GroupSpec[]` |  | Zones around some boxes, each with its own frame and caption. See `GroupSpec`. |
| `layout?` | `'architecture'` |  | `'architecture'`: compose the drawing — zones as regions, boxes sized to their words in rows, straight lines where boxes line up. Positions are not needed. |

### `FromDocumentOptions`

```ts
interface FromDocumentOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `renderWidget?` | `WidgetRenderer` |  | The app's own widget painter — the same function it passed to `dashboard({ renderWidget })`. A board authored with a custom painter must be RELOADED with it, or the reload silently drops the app's chrome. |
| `renderCustomNode?` | `(node: NodeModel, host: HTMLElement) => void` |  | Full override of the custom-node painter. Outranks everything. |
| `interactive?` | `boolean` |  | Re-attach kit interaction wiring (row selection, in-canvas editing, the dashboard grid binder). Default true — a loaded diagram should behave like the one that was saved. Pass false for a read-only viewer. |

### `LoadedDiagramSpec`

What {@link fromDocument} returns: a `render()` spec, plus the way back in.

```ts
interface LoadedDiagramSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `NodeModel[]` |  |  |
| `edges` | `LinkModel[]` |  |  |
| `renderCustomNode` | `(node: NodeModel, host: HTMLElement) => void` |  |  |
| `finalize` | `(api: unknown) => void` |  |  |
| `model` | `DiagramModel` |  | The deserialized model — the escape hatch, available before any render. |
| `boards` | `Map<string, DashboardGridHandle>` |  | Live grid binders for the boards `finalize()` re-attached, keyed by group id. Empty for a document that is not a dashboard. |
| `handle` | `DashboardHandle` |  | The dashboard toolbar handle over the reloaded board(s) — the SAME `DashboardHandle` `dashboard()` returns, built by the one shared builder so it cannot drift from the authoring surface: addWidget/showView/setSizing/ setColumns/toJSON/exportIds and the widget handles, all live on the reload. |
| `renderOptions?` | `{ minZoom?: number; maxZoom?: number }` |  | Instance options the loaded spec asks `render()` to apply (a fluid board pins zoom). |

## Types

### `NodeTypeRenderer`

Fills `element` with the visual for `node`. Called once per mounted node.

```ts
type NodeTypeRenderer = (node: NodeModel, element: HTMLElement) => void;
```

### `RenderOptions`

Also has every member of `CreateDiagramOptions`, `DomEventBinderOptions`, listed on their own entries.

```ts
type RenderOptions = Omit<CreateDiagramOptions, 'nodes' | 'edges'>;
```

### `RenderSpec`

```ts
type RenderSpec = DiagramSpec | DashboardSpec | KitDiagramSpec | string;
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.

### `SavedDiagram`

Anything `DiagramSerializer.deserialize()` accepts, or the JSON string of it.

```ts
type SavedDiagram =
  | SerializedDiagramData
  | DiagramDocumentEnvelope
  | Record<string, unknown>
  | string;
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.

<!-- source: grafloria-element-dashboard-kit.md -->

# Dashboard Kit

Import these from `@grafloria/element`.

## On their own pages

- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-constants): 16 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-functions): 19 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-interfaces): 18 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-types): 4 types.
- [`DashboardGridHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardgridhandle)
- [`DashboardGridOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardgridoptions)
- [`DashboardHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardhandle): The typed façade — the `erTable`/`umlClass` equivalent for dashboards.
- [`DashboardOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardoptions)
- [`DashboardWidgetSpec`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-dashboardwidgetspec): A widget, declared as data.
- [`SectionCaptionOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-sectioncaptionoptions)
- [`TabsOptions`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-tabsoptions): TAB CONTAINERS — a container whose children are PAGES, one visible at a
- [`WidgetHandle`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-dashboard-kit-widgethandle): One widget's OO surface (mirrors ErTable/UmlClass).

<!-- source: grafloria-element-dashboard-kit-constants.md -->

# Constants

Import these from `@grafloria/element`.

## Constants

### `BUILT_IN_WIDGET_KINDS`

The kinds `defaultWidgetRenderer` knows; anything else gets the placeholder.

```ts
const BUILT_IN_WIDGET_KINDS: readonly ["kpi", "line", "bar", "donut", "funnel", "table"]
```

### `CAPTION_HEIGHT`

```ts
const CAPTION_HEIGHT: 28
```

### `CAPTION_HEIGHT_SUBTITLE`

```ts
const CAPTION_HEIGHT_SUBTITLE: 44
```

### `CAPTION_HEIGHT_TIGHT`

```ts
const CAPTION_HEIGHT_TIGHT: 22
```

### `CAPTION_PASS_THROUGH`

```ts
const CAPTION_PASS_THROUGH: "button, a, input, select, textarea, [data-axdb-pass]"
```

### `DASHBOARD_KIT_CSS`

The kit stylesheet as text — for a host that bundles its own CSS, and for the styling spec.

```ts
const DASHBOARD_KIT_CSS: "\n/* ===== reflow glide (armed on the html layer for the whole gesture) ===== */\n.grafloria-html-layer.axdb-glide > .grafloria-node-host {\n  transition: left .28s cubic-bezier(.2, 0, .2, 1), top .28s cubic-bezier(.2, 0, .2, 1),\n              width .28s cubic-bezier(.2, 0, .2, 1), height .28s cubic-bezier(.2, 0, .2, 1);\n}\n\n/* Motion is a preference (WCAG 2.3.3): no glide for those who asked for none. */\n@media (prefers-reduced-motion: reduce) {\n  .grafloria-html-layer.axdb-glide > .grafloria-node-host { transition: none; }\n}\n\n/* ===== keyboard focus: the …
```

### `DASHBOARD_KIT_STYLE_ID`

Dashboard-kit stylesheet — injected once, on first `bindDashboardGrid`.

Everything is prefixed `axdb-` and scoped under `.grafloria-html-layer`, so
binding the kit can never restyle a host's own DOM. Four jobs:

- GLIDE: the reflow transition (the pattern from commit 180a27974) that
   makes displaced tiles slide to their new slot while a gesture is live. The kit arms `.axdb-glide` on the html layer for the WHOLE gesture, so
   every accepted moveCheck/resizeCheck animates the neighbours.
 - GHOST: the held tile is transition-EXEMPT (it must track the pointer
   1:1), floats above everything, and dims + lifts like the prototype's
   `.tile.drag`. When a drag leaves the board (drag-out-to-remove) the
   ghost dims further as the "release deletes" affordance.
 - PLACEHOLDER: the dashed slab that always shows the exact drop result
   (the prototype's `#ph`). It JUMPS — never animates — so it is always
   truthful about the engine's current cell.
 - RESIZE HANDLE: a corner affordance INSIDE each widget card, bottom-right,
   radius-matched via `--axdb-rs-radius`, revealed on hover. The binder
   injects it into each member host and re-injects if the host repaints
   (pages own their card innerHTML).

```ts
const DASHBOARD_KIT_STYLE_ID: "grafloria-dashboard-kit-styles"
```

### `defaultWidgetRenderer`

Paint `widget` into `host` by its `kind` — `dashboard()`'s default
`renderWidget`, and the composable base for your own.

An unknown (or absent) kind falls back to the titled placeholder frame, so a
board of not-yet-implemented widgets still lays out and is still testable. Never throws: bad data paints an empty state.

```ts
const defaultWidgetRenderer: WidgetRenderer
```

### `renderBarWidget`

`{ bars: [{label, value}] }` — columns, value above, category below.

```ts
const renderBarWidget: WidgetRenderer
```

### `renderDonutWidget`

`{ slices: [{label, value, color?}], centerLabel? }` — ring + legend.

```ts
const renderDonutWidget: WidgetRenderer
```

### `renderFunnelWidget`

`{ stages: [{label, value}] }` — centred bars scaled against the widest stage.

```ts
const renderFunnelWidget: WidgetRenderer
```

### `renderKpiWidget`

`{ label, value, delta?, spark? }` — headline number + change + sparkline.

```ts
const renderKpiWidget: WidgetRenderer
```

### `renderLineWidget`

`{ series, labels? }` — area under the first series, a line per series.

```ts
const renderLineWidget: WidgetRenderer
```

### `renderTableWidget`

`{ columns, rows }` — plain rows; numeric cells right-align themselves.

```ts
const renderTableWidget: WidgetRenderer
```

### `TAB_DRAG_THRESHOLD`

Travel, in px, that turns a press on a tab from a click into a drag. VS Code
uses the platform drag threshold; 4 px is the same order and keeps a shaky
click a click.

```ts
const TAB_DRAG_THRESHOLD: 4
```

### `TAB_STRIP_HEIGHT`

```ts
const TAB_STRIP_HEIGHT: 30
```

<!-- source: grafloria-element-dashboard-kit-functions.md -->

# Functions

Import these from `@grafloria/element`.

## Functions

### `bindDashboardGrid`

```ts
function bindDashboardGrid(
  api: DashboardGridApi,
  group: GroupModel,
  options: DashboardGridOptions = {}
): DashboardGridHandle
```

### `boardHeightFor`

The board frame height the mode implies for `rows` rows.

```ts
function boardHeightFor(g: DashboardGridGeometry, rows: number): number
```

### `buildCommitCommands`

```ts
function buildCommitCommands(deltas: TileDelta[]): Command[]
```

### `captionBandHeight`

The band's height for a section of `sectionH` px: the authored height (or
the tier), CLAMPED so the children always keep `CAPTION_MIN_CONTENT` px. A
one-row section used to hand its whole 34 px to a 22 px band and paint a
12 px sliver of a child.

```ts
function captionBandHeight(c: SectionCaptionOptions, sectionH: number): number
```

### `captionReserve`

Pixels the nested board's frame gives up at the top: the band plus its
vertical margins. A TAB reserves too — it is a narrower band, not a header
hanging over whatever the parent board put above the section (the stress
page had one lying across a chart's legend, and one clipped off the top of
the canvas). Only `show: 'hover'` reserves nothing: it is an overlay by
definition, and it paints opaque so the content beneath stays readable.

```ts
function captionReserve(c: SectionCaptionOptions | null, ctx: { static: boolean; sectionH: number }): number
```

### `cellFromGridItem`

GridItemConfig → engine cells, or null when the config carries no usable
placement (absent, or 'auto' lines). `fallback` fills spans a partial
config omits — the first-adoption path uses metadata `columnSpan` there.

```ts
function cellFromGridItem(
  gi: GridItemConfig | undefined,
  fallback?: { w?: number; h?: number }
): CellRect | null
```

### `cellToRect`

Project integer cells into a world rectangle inside `frame`.

RTL mirrors about the board's vertical centre line: the distance from the
board's RIGHT padding edge to the tile's RIGHT edge equals what the LTR
distance from the left padding edge to the tile's LEFT edge would be. Only
the x term changes — rows, heights and spans are direction-agnostic.

```ts
function cellToRect(
  cell: CellRect,
  frame: WorldRect,
  g: DashboardGridGeometry,
  rows: number
): WorldRect
```

### `columnUnitFor`

Width of one column cell for a board `width` px wide.

```ts
function columnUnitFor(g: DashboardGridGeometry, width: number): number
```

### `dashboard`

```ts
function dashboard(options: DashboardOptions): DashboardSpec
```

### `ensureDashboardKitStyles`

Idempotently inject the kit stylesheet (safe to call per binder).

```ts
function ensureDashboardKitStyles(doc?: Document): void
```

### `gridItemFromCell`

Engine cells → the GridItemConfig that persists them.

```ts
function gridItemFromCell(cell: CellRect): GridItemConfig
```

### `normalizeCaption`

The caption as options, or null when there is none. `title` fills the text.

```ts
function normalizeCaption(c: SectionCaption | undefined, title?: string): SectionCaptionOptions | null
```

### `paintCaptionBand`

Paint the band: geometry (inline, so the reserve and the pixels agree),
classes for alignment and mode, CSS variables for typography and box, and
the default content — icon, text, subtitle, ⓘ, actions. With `render` the
content is yours: the band is handed over empty and keeps its press rules.

```ts
function paintCaptionBand(
  band: HTMLElement,
  c: SectionCaptionOptions,
  ctx: { rtl: boolean; static: boolean; sectionH: number; render?: (host: HTMLElement) => void; onAction?: (actionId: string) => void }
): void
```

### `paintTabStrip`

```ts
function paintTabStrip(
  strip: HTMLElement,
  pages: TabPage[],
  activeId: string,
  o: TabsOptions | undefined,
  rtl: boolean,
  onPick: (id: string) => void,
  onSelectContainer?: (e: PointerEvent) => void,
  /**
   * The tab is the PAGE's drag handle, as it is in VS Code: press one and
   * travel, and the whole page leaves — not the widget under the pointer,
   * which used to be the only way to drag anything out and left the tab
   * behind pointing at an empty page.
   */
  onDrag?: (pageId: string, ev: PointerEvent) => boolean
): void
```

### `pointToCell`

The cell whose slot a tile TOP-LEFT at world (x, y) is closest to — the
prototype's margin-adjusted midpoint rounding (`round(L / cellPitch)`). Clamping to the board is the ENGINE's job (moveCheck clamps), not ours.

`spanW` is the tile's COLUMN SPAN and is used only when `g.rtl`: mirrored,
the cell is decided by the tile's RIGHT edge (its leading edge), so the
span is what converts the given left edge into it. LTR ignores it entirely,
which is why every existing call site keeps its exact behaviour. Getting
this wrong is the classic RTL drag bug — the tile lands a span away from
the placeholder — so the e2e battery asserts drop-on-placeholder in RTL.

```ts
function pointToCell(
  x: number,
  y: number,
  frame: WorldRect,
  g: DashboardGridGeometry,
  rows: number,
  spanW = 1
): { x: number; y: number }
```

### `rowHeightFor`

Row height for a board currently `rows` rows tall (both modes).

```ts
function rowHeightFor(g: DashboardGridGeometry, rows: number): number
```

### `sizeToSpan`

The integer span a fluid pixel size rounds to — the prototype's
`round((W + margin) / cellPitch)`, floored at 1×1.

```ts
function sizeToSpan(
  widthPx: number,
  heightPx: number,
  frame: WorldRect,
  g: DashboardGridGeometry,
  rows: number
): { w: number; h: number }
```

### `tabStripKey`

Paint the strip. Repainted only when its identity changes (the pages, the
active one, the options, RTL) so a page switch is a class toggle, not a
rebuild — and so a `click` listener survives between switches.

```ts
function tabStripKey(pages: TabPage[], activeId: string, o: TabsOptions | undefined, rtl: boolean): string
```

### `tabStripReserve`

Pixels the pages give up at the top of the container: nothing for a hidden strip, never under 18 for a visible one.

```ts
function tabStripReserve(o: TabsOptions | undefined, pageCount: number): number
```

<!-- source: grafloria-element-dashboard-kit-interfaces.md -->

# Interfaces

Import these from `@grafloria/element`.

## Interfaces

### `BarWidgetData`

`kind: 'bar'` — categorical columns.

```ts
interface BarWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bars?` | `Array<{ label?: string; value?: number }>` |  |  |

### `CellRect`

One tile in integer board cells — the shape `GridPackEngine` speaks.

```ts
interface CellRect
```

**Properties**

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

### `DashboardGridApi`

The slice of a DiagramInstance the binder needs (structural, test-friendly).

```ts
interface DashboardGridApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |
| `viewport?` | `{ clientToWorld( clientX: number, clientY: number, rect: { left: number; top: number; width: number; height: number } ): { x: number; y: number }; }` |  |  |

**Members**

- `getModel(): DiagramModel`
- `getEngine(): { commandManager: { execute(cmd: Command): Promise<unknown> | unknown } }`
- `render(): void`
- `renderNow(): void`

### `DashboardGridGeometry`

```ts
interface DashboardGridGeometry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `number` |  | Column count of the board (default 12). |
| `gap` | `number` |  | Gap between cells, px. |
| `padding` | `number` |  | Padding between the board frame and the outermost cells, px. |
| `sizing` | `'fit' \| 'grow'` |  |  |
| `baseRowHeight` | `number` |  | Row height in 'grow' mode, px. |
| `minRowHeight` | `number` |  | Floor for the derived 'fit' row height, px. |
| `designHeight` | `number` |  | The board's design height — 'fit' keeps it, 'grow' never shrinks below it. |
| `rtl?` | `boolean` |  | RIGHT-TO-LEFT boards. The MODEL is direction-agnostic — cell x=0 is always "the first column" and every rule in `GridPackEngine` (push, swap, gravity, the anti-jitter gate) is written in cells, so none of it changes. ONLY this module's pixel mapping mirrors: x=0 renders at the board's RIGHT edge and columns run leftwards. |

### `DashboardSpec`

What `dashboard()` returns — a render spec plus the runtime handle.

```ts
interface DashboardSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `Array<Record<string, unknown>>` |  |  |
| `edges` | `Array<Record<string, unknown>>` |  |  |
| `renderCustomNode` | `(node: unknown, host: HTMLElement) => void` |  |  |
| `finalize` | `(api: unknown) => void` |  |  |
| `handle` | `DashboardHandle` |  | Live handle, populated by finalize(). |
| `renderOptions?` | `{ minZoom?: number; maxZoom?: number }` |  | Instance options the spec asks `render()` to apply — a fluid board pins the zoom range to 1 so the layout can never become a scaled picture. |

### `DashboardViewSpec`

One board. Multiple views are the tab pattern: only one is on-camera.

```ts
interface DashboardViewSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name?` | `string` |  |  |
| `widgets` | `DashboardWidgetSpec[]` |  |  |
| `columns?` | `number` |  | Per-view overrides of the dashboard-level geometry. |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `layout?` | `'grid' \| 'split'` |  | Per-view layout (default: the dashboard-level `layout`). `toJSON()` writes it per view. |
| `tree?` | `SplitNode \| null` |  | SPLIT layout only: the authored splitter tree (see `layout`). Omit it and the tree is derived from the widgets' cells, so a grid-authored view keeps its proportions when it opens as a split board. `toJSON()` writes it back. |

### `DonutWidgetData`

`kind: 'donut'` — parts of a whole, with a legend and a centre figure.

```ts
interface DonutWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `slices?` | `Array<{ label?: string; value?: number; color?: string }>` |  |  |
| `centerLabel?` | `string` |  | Centre figure (default: the compacted total). |
| `centerCaption?` | `string` |  | Caption under the centre figure (default 'total'). |

### `DragGripOptions`

A painted grip: the only drag zone, placed along the card's top edge.

```ts
interface DragGripOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `grip` | `true` |  |  |
| `position?` | `'left' \| 'center' \| 'right'` |  | Where along the top edge. Default 'left'. |
| `placement?` | `'inside' \| 'outside'` |  | In the header band, or a tab above the card. Default 'inside'. |

### `FunnelWidgetData`

`kind: 'funnel'` — ordered stages, each bar scaled against the first.

```ts
interface FunnelWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `stages?` | `Array<{ label?: string; value?: number }>` |  |  |

### `KpiWidgetData`

`kind: 'kpi'` — one headline number, an optional change, an optional trend.

```ts
interface KpiWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` |  | Small caption above the number (falls back to `widget.title`). |
| `value?` | `string \| number` |  | The headline — pre-formatted by you, so units/currency stay yours. |
| `delta?` | `number` |  | Signed percentage change. Positive paints up/green, negative down/red. |
| `deltaLabel?` | `string` |  | Caption after the delta (default 'vs previous'). |
| `spark?` | `number[]` |  | Sparkline values, oldest → newest. Fewer than 2 points draws nothing. |

### `LineSeries`

One named line of a `kind: 'line'` chart.

```ts
interface LineSeries
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  |  |
| `values` | `number[]` |  |  |

### `LineWidgetData`

`kind: 'line'` — one or many series over a shared x axis (area + line).

```ts
interface LineWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `series?` | `number[] \| LineSeries[]` |  | A bare `number[]` is the single-series shorthand. |
| `labels?` | `string[]` |  | X-axis tick labels, positionally matched to the values. |

### `SectionCaptionAction`

SECTION CAPTIONS — the header a section (container widget) may carry,
painted by the kit on the slab overlay it already owns.

Three things only the kit can do for a section header, and this module is
where they are decided: RESERVE the pixels (`captionReserve` — the nested
board's frame starts below the band, so no child may take it), PAINT it
(`paintCaptionBand` — one DOM shape, one set of CSS variables, one theme),
and ROUTE its presses (`captionPassThrough` — a button or an input in the
band is content, everything else is the band, which selects the section). Persistence is the container's business: the caption rides on the group's
`containerWidget` metadata beside `layout` and `sizing`, and `toJSON()`
writes it back.

Plan and defaults: documentation/api-architecture/section-caption-plan.html.

```ts
interface SectionCaptionAction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  | Accessible name; painted as the glyph when there is no `icon`. |
| `icon?` | `string` |  | A glyph (emoji or short text). |
| `title?` | `string` |  | Tooltip; default: the label. |
| `disabled?` | `boolean` |  |  |

### `SectionCaptionFont`

```ts
interface SectionCaptionFont
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `number` |  |  |
| `weight?` | `number \| string` |  |  |
| `family?` | `string` |  |  |
| `color?` | `string` |  |  |
| `transform?` | `'none' \| 'uppercase'` |  |  |

### `TableWidgetData`

`kind: 'table'` — plain rows. Numbers right-align on their own.

```ts
interface TableWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `string[]` |  |  |
| `rows?` | `Array<Array<string \| number>>` |  |  |

### `TabPage`

```ts
interface TabPage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |

### `TileDelta`

```ts
interface TileDelta
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `locked?` | `boolean` |  |  |
| `isGroup?` | `boolean` |  | Group members (layout slabs) get cells-only commands — never Move/Resize. |
| `cellBefore` | `CellRect` |  |  |
| `cellAfter` | `CellRect` |  |  |
| `posBefore` | `{ x: number; y: number }` |  |  |
| `posAfter` | `{ x: number; y: number }` |  |  |
| `sizeBefore` | `{ width: number; height: number; depth?: number }` |  |  |
| `sizeAfter` | `{ width: number; height: number; depth?: number }` |  |  |

### `WorldRect`

A world-space rectangle (the group frame, or a projected tile).

```ts
interface WorldRect
```

**Properties**

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

<!-- source: grafloria-element-dashboard-kit-types.md -->

# Types

Import these from `@grafloria/element`.

## Types

### `DashboardSnapshot`

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

A whole board as plain data: every `DashboardOptions` field except the
function seams. `dashboard({ ...snapshot, renderWidget })` rebuilds it.

Typed as an Omit rather than a hand-written twin on purpose — a field added
to `DashboardOptions` then joins the snapshot automatically instead of being
silently dropped, which is the exact failure this type exists to end.

```ts
type DashboardSnapshot = Omit<
  DashboardOptions,
  'renderWidget' | 'onLayoutChange' | 'views'
> & { views: DashboardViewSpec[] };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views` | `DashboardViewSpec[]` |  |  |

### `DragHandleOption`

```ts
type DragHandleOption = boolean | string | DragGripOptions;
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.

### `SectionCaption`

`false`/absent: no band. `true`: the title. A string: that text.

```ts
type SectionCaption = false | true | string | SectionCaptionOptions;
```

**Members**

- `toString(): string` — Returns a string representation of a string.
- `valueOf(): string` — Returns the primitive value of the specified object.

### `WidgetRenderer`

The signature every renderer here (and `renderWidget`) satisfies.

```ts
type WidgetRenderer = (widget: DashboardWidgetSpec, host: HTMLElement) => void;
```

<!-- source: grafloria-element-dashboard-kit-dashboardgridhandle.md -->

# DashboardGridHandle

Import it from `@grafloria/element`.

```ts
interface DashboardGridHandle
```

**Members**

- `sync(): void` — Rebuild the engine from the group's members + their cells, re-project pixels.
- `setSizing(mode: 'fit' | 'grow'): void`
- `getSizing(): 'fit' | 'grow'`
- `setFloat(on: boolean): void` — Engine float mode, live (the prototype's second toggle): ON — tiles stay
exactly where placed, vertical gaps are legal; OFF — gravity re-packs
upward immediately.
- `getFloat(): boolean`
- `setColumns(n: number, layout?: GridColumnLayout, opts?: { responsive?: boolean }): boolean` — Change the COLUMN COUNT live (gridstack's `column(n, layout)`), through the
engine's per-column layout cache: shrinking caches the layout it leaves,
growing back restores it. Returns true when the count actually changed.

Calling this directly PINS the count — it switches the responsive
evaluator off, so a board under an explicit count is not fought by its own
width observer. `setColumns(n, layout, { responsive: true })` is the
evaluator's own path back.
- `getColumns(): number`
- `setRtl(on: boolean): void` — RTL mirroring, live. Cells never change — only the pixels.
- `getRtl(): boolean`
- `setStatic(on: boolean): void` — Static mode, live: pointer gestures off (and handles gone) or back on.
- `getStatic(): boolean`
- `setDragHandle(v: DragHandleOption): void` — Drag-handle mode, live: `true` = the caption strip, a selector = your own handle, `{ grip: true, … }` = a painted grip, `false` = the whole card.
- `getDragHandle(): DragHandleOption`
- `focusWidget(id: string): boolean` — Move keyboard focus to a member (the roving tabindex lands on it). The
host takes DOM focus when it exists; returns false for a non-member.
- `getFocusedWidget(): string | undefined` — The member the roving tabindex currently rests on.
- `selectWidget(id: string | undefined): boolean` — SELECT a member without moving keyboard focus — what a mouse press does
(the renderer cancels the press's default, so a click never focuses the
host). `undefined` clears. False for a non-member.
- `getSelectedWidget(): string | undefined` — The selected member: the one wearing the ring and, in grip mode, the grip.
- `saveLayout(): { columns: number; cells: Map<string, CellRect> }` — The layout to PERSIST — from the engine's LARGEST cached column count, so
saving while the board is narrow still saves the wide layout the user
authored (gridstack's `save()` semantics).
- `metrics(): { columns: number; maxColumns: number; rtl: boolean; responsive: boolean; fluid: boolean; static: boolean; dragHandle: DragHandleOption; capacity: number | undefined; gap: number; padding: number; sizing: 'fit' | 'grow'; rows: number; rowHeight: number; columnUnit: number; boardHeight: number; frame: WorldRect; }` — Live board metrics (mapping inputs + derived row height / rows).
- `willItFit(w: number, h: number): boolean` — Would a w×h tile fit on the board as it is now (gridstack's `willItFit`)? Always true on an unbounded board; on a bounded fit board this is what
`addWidget()` asks before creating anything.
- `cellOf(id: string): CellRect | undefined` — The engine's cell record for a member (undefined when not a member).
- `cellRectOf(id: string): WorldRect | undefined` — World rect the member's current cells project to.
- `planRemoval(id: string): Command[]` — Commands that reconcile the survivors after removing `id` — fold into the remove batch.
- `moveTo(id: string, x: number, y: number): Promise<boolean>` — Programmatic single-step gestures — the demo asserts' deterministic hook. Same pipeline as a pointer gesture, committed as ONE BatchCommand.
- `resizeTo(id: string, w: number, h: number): Promise<boolean>`
- `beginPaletteDrag( node: NodeModel, spec: { w: number; h: number; chip?: HTMLElement }, event: PointerEvent ): void` — Palette drag-in: `node` is a DETACHED widget node (not yet in the model). A chip follows the cursor; entering the board places the node's item in
the engine (first placement skips the anti-jitter gate, as gridstack's
drag-in does) and the normal live-push loop takes over. Release inside →
`onDropIn`; release outside / Escape → aborted, nothing committed.
- `dispose(): void`

<!-- source: grafloria-element-dashboard-kit-dashboardgridoptions.md -->

# DashboardGridOptions

Import it from `@grafloria/element`.

```ts
interface DashboardGridOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Column count (default 12). With `responsive`, the starting/maximum count. |
| `rtl?` | `boolean` |  | RIGHT-TO-LEFT board. Cells are unchanged — x=0 is still the first column — but it renders at the board's RIGHT edge and columns run leftwards. Purely a pixel-mapping concern: the engine, the cells and every saved layout are direction-agnostic. |
| `responsive?` | `DashboardResponsiveOptions` |  | Derive the column count from the board's width (see the interface). |
| `onColumnsChange?` | `(columns: number, previous: number) => void` |  | Fires after a responsive (or programmatic) column-count change. |
| `gap?` | `number` |  | Gap between cells, px (default 12). |
| `padding?` | `number` |  | Board padding, px (default = gap). |
| `sizing?` | `'fit' \| 'grow'` |  | Sizing mode (default 'fit' — the user decision recorded in the plan). |
| `baseRowHeight?` | `number` |  | 'grow' row height, px (default 110). |
| `minRowHeight?` | `number` |  | 'fit' row-height floor, px (default 28). |
| `designHeight?` | `number` |  | The board's design height (default: the group's height at bind time). 'fit' pins the frame to it; 'grow' never shrinks the frame below it. |
| `float?` | `boolean` |  | Engine float mode (default false → gravity packs upward). |
| `maxRows?` | `number` |  | Engine row bound (see GridPackOptions.maxRows). A nested strip like the KPI section passes 1: its DESIGN is one row, so height growth and pushes that would spill a sibling downward are refused (siblings shift along the row instead), and the strip can never be squeezed. |
| `escalate?` | `boolean` |  | Nested boards only. `true` (default): a child pulled clearly past the bound GROWS the container's slab in the parent (height escalation). `false`: the pane is the bound — the pull is refused where it stands, the container's `sizing: 'fit'`. |
| `dragOut?` | `'remove' \| 'cancel'` |  | What dragging a tile OUT of the board means (default 'cancel' — the tile snaps back on release). 'remove' dims the ghost outside the board and a release outside calls `onRemoveRequest` — deletion stays on the page's atomic command path. |
| `removeZone?` | `(screen: { x: number; y: number }, world: { x: number; y: number }) => boolean` |  | With dragOut:'remove', restrict deletion to an EXPLICIT drop zone (the page passes "over the palette" — gridstack web2's trash semantics). Outside the zone a release snaps home instead: a 60px overshoot past the frame edge must never destroy a widget (live parity review — the plan prototype clamps at its edges and cannot delete at all). |
| `onRemoveRequest?` | `(nodeId: string, displaced: Command[]) => void \| Promise<void>` |  | Page hook for drag-out removal: execute ONE undoable batch that removes `nodeId` AND applies `displaced` (the survivors' cell commits, so undo restores the exact board). |
| `onDropIn?` | `(node: NodeModel, cell: CellRect, displaced: Command[], target: { boardId: string }) => void \| Promise<void>` |  | Page hook for palette drag-in release: add `node` (already carrying `cell` in its gridItem) to `target.boardId` — this view, or a page or section the chip was dropped into (tile first, step 4a) — through the page's command path, folding `displaced` into the same batch. |
| `onMemberLeaving?` | `(memberId: string) => Command[]` |  | A member is about to LEAVE this board through a gesture (moved into another board, made a tab of its own). Answers the commands that follow it in the same batch — a tab page emptied by the move closes. |
| `onMemberMoving?` | `(memberId: string, fromBoardId: string, toBoardId: string) => Command[]` |  | A member CONTAINER is moving from this board to another by a gesture (tile first, 4b-ii). Answers the commands that carry the host's own bookkeeping for it — the spec entry, the registry — in the same batch. |
| `tabDrop?` | `TabDropHooks` |  | A widget dragged over a tab STRIP becomes a new tab there: the hooks that hit-test, mark and commit it. |
| `onGesture?` | `(e: { type: 'commit' \| 'cancel' \| 'remove' \| 'drop-in'; kind: 'move' \| 'resize' \| 'palette'; nodeId: string; changed: boolean; }) => void` |  | Fires after commits/cancels/removals so the page can refocus/refit/flash. |
| `onSelect?` | `(id: string \| undefined) => void` |  | The selection on this board changed: the selected member — a widget or a SECTION (container) — or undefined. |
| `renderCaption?` | `(sectionId: string, host: HTMLElement) => void` |  | SECTION CAPTIONS (0.4.22). Paint a member section's caption band yourself: the band is handed over empty, sized and themed, and keeps its press rules. Default: the kit's icon · text · subtitle · ⓘ · actions. |
| `onCaptionAction?` | `(sectionId: string, actionId: string) => void` |  | A press on a caption action button (see `SectionCaptionOptions.actions`). |
| `resizeHandles?` | `boolean` |  |  |
| `fluid?` | `boolean` |  | FLUID board: the group's frame follows the CANVAS CONTAINER — width always, and height too in 'fit' — so the dashboard is laid out at real CSS pixels like every other grid library, never as a picture the camera scales (review D1: a 900-px viewport drew 30-px KPI figures at 18 px). The binder owns the ResizeObserver; `sync()` re-reads the container as well. |
| `overflow?` | `'bounded' \| 'scroll'` |  | What FIT mode does past its row floor. 'bounded' (default): the design height is a CAPACITY — a drop, resize or add that would need one row too many is refused (the engine's `capacity`), visibly, at design time. 'scroll': no bound; the frame extends to hold the rows at the floor height so nothing paints outside it, and the canvas pans. |
| `static?` | `boolean` |  | STATIC board (gridstack's `staticGrid`): the pointer can neither drag nor resize and no handles are injected; the API (moveTo/resizeTo, adds, undo) still works. The viewer's mode — see `setStatic` for the live switch. |
| `nesting?` | `number` |  | NESTING POLICY (tile first, step 2): the deepest board a DROP may enter, counting a view as 0 — a widget into a section is 1, into a section inside a tab page is 2. Deeper containers are opaque to a drag: the pointer over them means a cell on their parent board (or beside them). Unbounded by default. |
| `dragHandle?` | `DragHandleOption` |  | DRAG HANDLE (DevExpress drags an item by its caption; gridstack's `handle`). `true` — the CAPTION STRIP is the handle (the header shows grip dots); a selector string — your own element inside the host; a `{ grip: true }` object — a dedicated GRIP the kit paints, positioned left / center / right and, for the top edge, `inside` the header band or `outside` as a tab above the card (the DevExpress … |
| `squeeze?` | `boolean` |  | FIT AND THE ROW FLOOR. `true` (default): a bounded fit board holds as many rows as fit at `minRowHeight` — a gesture that needs another row SQUEEZES every row toward the floor, and is refused only when even that is not enough. |

<!-- source: grafloria-element-dashboard-kit-dashboardhandle.md -->

# DashboardHandle

Import it from `@grafloria/element`.

The typed façade — the `erTable`/`umlClass` equivalent for dashboards.

```ts
interface DashboardHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views` | `string[]` |  | The view ids, in declaration order. |
| `activeView` | `string` |  | The currently shown view id. |

**Members**

- `showView(id: string): void` — Show a view (the others park off-camera) and frame it.
- `widget(id: string): WidgetHandle | undefined` — A widget handle by id (undefined when unknown).
- `focusWidget(id: string): boolean` — SELECT a widget and move keyboard focus to it — what a press on the widget
does. The selected widget shows its painted grip (`dragHandle: { grip }`)
and a quiet ring; a void click clears. False when the id is unknown.
- `selectWidget(id: string | undefined): boolean` — SELECT a widget WITHOUT moving keyboard focus — the ring and the grip,
nothing else; what a mouse press does. `undefined` clears the selection
on every view. False when the id is unknown.
- `getSelectedWidget(): string | undefined` — The selected widget, if any (across views: only the on-camera one can be).
- `widgetsOf(viewId?: string): WidgetHandle[]` — Every widget handle of a view (default: the active one).
- `setLayout(layout: 'grid' | 'split', viewId?: string): void` — Switch a view (default: the active one) between the cell grid and the
split tree, live and keeping the picture: cells → tree by guillotine cuts,
tree → cells by snapping to the columns. Persisted on the board, so a
saved document reopens in the layout it was left in.
- `getLayout(viewId?: string): 'grid' | 'split' | 'tabs'` — A container built with `layout: 'tabs'` reports 'tabs'; views never do.
- `setCaption(id: string, caption: SectionCaption): boolean` — Set a SECTION's caption live — `false` removes it, `true` is the title, a
string or the options. Repaints the band, gives the reserve back or takes
it, persists on the section, one undo step. False for anything that is
not a container.
- `getCaption(id: string): SectionCaption | undefined` — The caption as authored or last set; undefined when the section has none.
- `activateTab(containerId: string, pageId: string): boolean` — Show a PAGE of a tab container (`layout: 'tabs'`). False when the
container or the page is not one. Persisted, so a saved board reopens on
the page it was left on.
- `getActiveTab(containerId: string): string | undefined` — The page showing in a tab container.
- `moveToTab(widgetId: string, containerId: string, index?: number): Promise<boolean>` — Move a WIDGET into `containerId` as a NEW TAB at `index` (default: the
end): the widget becomes the only member of a fresh page named by its
title, and that page the active tab — what dropping a widget on a strip
does. One undoable step; the board it left re-packs, and a page it
emptied closes.
- `moveTab(containerId: string, pageId: string, index: number): boolean` — Reorder a page along its container's strip. One undoable step; the order is saved with the container.
- `setSizing(mode: 'fit' | 'grow'): void` — Live sizing/float switches — the two prototype toggles.
- `getSizing(): 'fit' | 'grow'`
- `setFloat(on: boolean): void`
- `getFloat(): boolean`
- `setColumns(n: number, layout?: GridColumnLayout, viewId?: string): void` — Set the COLUMN COUNT of every board (or one view), live. Goes through the
engine's per-column layout cache, so shrinking then growing back restores
the wide layout rather than re-deriving it. An explicit call PINS the
count — the width-driven `responsive` evaluator stops overriding it.
- `getColumns(viewId?: string): number` — The LIVE column count of a view (default: the active one).
- `setRtl(on: boolean): void` — RTL mirroring, live — pixels only, cells never change.
- `getRtl(): boolean`
- `setStatic(on: boolean): void` — Static (read-only for the pointer) mode, live — the viewer/designer switch.
- `getStatic(): boolean`
- `setDragHandle(v: DragHandleOption): void` — Drag-handle mode, live, every view: `true` = the caption strip, a selector = your own handle, `{ grip: true, … }` = a painted grip, `false` = the whole card.
- `getDragHandle(): DragHandleOption`
- `addWidget(spec: DashboardWidgetSpec, viewId?: string, opts?: { displaced?: Command[] }): WidgetHandle | undefined` — Add a widget to a view. CREATES the node (you do not pre-build one), wires
its metadata, and commits node + membership as ONE undoable step. Auto-positions when the spec names no cell. `opts.displaced`: the
commands a palette drop handed `onDropIn` for the tiles the placeholder
pushed aside — folded into the same step, so the widget lands on the cell
the drop showed and undo puts the pushed tiles back with it. Left out,
the board is re-read from the model and the push is forgotten: the new
widget then auto-positions into whatever hole is left (Quantia's "lands
on the cell it was aimed at", element 0.4.54).
- `refresh(): void` — Re-read every board from the model — call after undo/redo, or any
out-of-band mutation, so the grid and the projection agree again.
- `fit(viewId?: string): void` — Re-frame the camera on a view (default: the active one).
- `metrics(viewId?: string): ReturnType<DashboardGridHandle['metrics']> | undefined` — Live geometry of a view's board (columns, gap, rows, rowHeight, frame…).
- `toJSON(): DashboardSnapshot` — The whole board as plain data — feed it straight back to `dashboard()`:

```ts
dashboard({ ...handle.toJSON(), renderWidget });   // a true round trip
```

Everything `DashboardOptions` takes EXCEPT the function seams
(`renderWidget`, `onLayoutChange`), which cannot be written to a file and
must be supplied again on the way back in.

Values are read from the LIVE board, not from the authored literal, so a
mode or column count the user changed after mount is what you get back.

This used to return only `views`, which made the round-trip claim true of
the layout and false of the board: a board authored `grow` at a 10-column,
6px-gap geometry reloaded as a 12-column `fit` one. It is also what
`JSON.stringify(handle)` calls, so the partial answer was a permanent
footgun in a save API rather than merely an omission.
- `exportIds(viewId?: string): Set<string>` — The node ids ONE view occupies — pass straight to `includeIds` to export
just that board:

```ts
api.export('pdf', { includeIds: handle.exportIds() });
```

WHY THIS EXISTS. Tabs park the inactive views far off-camera, which is
invisible on screen and ruinous on export: `export()` frames the whole
MODEL, so a two-view board writes a ~21,000px document that is almost
entirely empty — with no warning, because nothing is technically wrong. Scoping was always possible; knowing WHAT to scope to was not.

The set includes the view's GROUP as well as its widgets. Rolling this by
hand from `toJSON()` looks equivalent and is not — it drops the group, and
the widgets export without the frame they sit in.
- `binderOf(viewId?: string): DashboardGridHandle | undefined` — THE DOCUMENTED ESCAPE HATCH: the view's own `bindDashboardGrid` handle
(default: the active view). Reach for it only for what this façade does
not cover yet — palette drag-in (`beginPaletteDrag`), board `metrics()`,
`cellRectOf`, `planRemoval`, and re-`sync()` after an external undo. Every
call site is a named gap in this API, not a normal way to drive a board.
- `dispose(): void`

<!-- source: grafloria-element-dashboard-kit-dashboardoptions.md -->

# DashboardOptions

Import it from `@grafloria/element`.

```ts
interface DashboardOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Column count for every view (default 12). |
| `gap?` | `number` |  | Gap between widgets AND the board padding, px (default 8). |
| `sizing?` | `'fit' \| 'grow'` |  | Sizing mode. 'grow': rows keep `rowHeight` and the board extends downward — the default on a FLUID board, and what every grid library does: dragging one tile never resizes another. 'fit': the board keeps its height and rows squeeze so everything stays on one screen (bounded, see `overflow`) — the default on a FIXED board, and the choice for a designer who wants the whole dashboard visible at once. |
| `layout?` | `'grid' \| 'split'` |  | HOW THE BOARD IS LAID OUT (the DevExpress question, decided 6 Sep 2026). 'grid' (the default): the cell grid — columns, spans, push, gravity, the gridstack model. |
| `rowHeight?` | `number` |  | Row height in 'grow' mode, px (default 130). |
| `width?` | `number` |  | Board size, px (default 1180 × 660). |
| `height?` | `number` |  |  |
| `float?` | `boolean` |  | Engine float mode (default false → gravity packs upward). |
| `mode?` | `'fluid' \| 'fixed'` |  | DIAGRAM OR LAYOUT — the one switch (decision of 2026-09-06). |
| `overflow?` | `'bounded' \| 'scroll'` |  | FIT MEANS BOUNDED. In 'fit' the board never changes size; widgets do. Past the row floor the design height is a CAPACITY: a drop, resize or `addWidget()` that would need one row too many is refused (the placeholder stays put, the palette chip dims, `addWidget` returns undefined) — at design time, instead of tiles painted past the frame. |
| `static?` | `boolean` |  | STATIC board (gridstack's `staticGrid`): no drag, no resize, no handles — the viewer's mode. The API (moveTo, resize, addWidget, undo) still works, so a designer/viewer pair is one flag apart. Live: `handle.setStatic()`. |
| `nesting?` | `number` |  | The deepest board a drop may enter (a view is 0; unbounded by default). See the grid binder's `nesting`. |
| `dragHandle?` | `DragHandleOption` |  | DRAG HANDLE — DevExpress drags an item by its caption. `true`: the caption strip is the only handle (the header shows grip dots); a selector string: your own element inside the card; `{ grip: true, position, placement }`: a painted grip, left / center / right along the top edge, `inside` the header band or `outside` as a tab above the card; off (default): the whole card. |
| `squeeze?` | `boolean` |  | FIT AND THE ROW FLOOR. `true` (default): a bounded fit board squeezes its rows toward `minRowHeight` before refusing growth. `false`: rows freeze at the height they have now — a gesture that needs a row the frame does not hold is refused outright and no other tile shrinks. See the grid binder's `squeeze` for the exact rule. |
| `rtl?` | `boolean` |  | RIGHT-TO-LEFT boards: column x=0 renders at the RIGHT edge and columns run leftwards. Cells are untouched — the same `widgets` array describes the same layout in both directions, and a layout saved in one renders mirrored in the other with identical cells. |
| `responsive?` | `DashboardResponsiveOptions` |  | RESPONSIVE COLUMN COUNT: derive the live count from each board's width. `{ columnWidth: 100 }` gives one column per ~100px (capped by `columns`); `{ breakpoints: [{ w: 480, c: 1 }, { w: 900, c: 6 }] }` names the steps. |
| `views?` | `DashboardViewSpec[]` |  | One view, or many (the tab pattern). Mutually exclusive with `widgets`. |
| `widgets?` | `DashboardWidgetSpec[]` |  | Shorthand for a single unnamed view. |
| `renderWidget?` | `(widget: DashboardWidgetSpec, host: HTMLElement) => void` |  | Paint a widget into its host element. Called once per widget when it mounts (the host is reused across re-renders, so this is not a per-frame hook). Omit for a titled placeholder frame. |
| `onSelect?` | `(id: string \| undefined, viewId: string) => void` |  | The selection changed on a board: the selected id — a widget or a SECTION (container) — or undefined when cleared, and the view it belongs to. A press on a section's empty band selects the section. |
| `renderCaption?` | `(widget: DashboardWidgetSpec, host: HTMLElement) => void` |  | Paint a section's caption band yourself (the escape hatch `renderWidget` is for cards): the band arrives empty, sized and themed, and keeps its press rules — a press on it selects the section, a pass-through element (a button, an input, `[data-axdb-pass]`) reaches your content. |
| `onCaptionAction?` | `(sectionId: string, actionId: string, viewId: string) => void` |  | A press on a caption action (`caption.actions`): the section, the action id, the view. |
| `onTabChange?` | `(containerId: string, pageId: string, viewId: string) => void` |  | A tab container switched pages: the container, the page now showing, the view. |
| `onLayoutChange?` | `(viewId: string, widgets: DashboardWidgetSpec[]) => void` |  | Fires after any committed gesture, with the view whose layout changed. |
| `binder?` | `Partial<DashboardGridOptions>` |  | Extra binder options, merged last (escape hatch to the layer below). |

<!-- source: grafloria-element-dashboard-kit-dashboardwidgetspec.md -->

# DashboardWidgetSpec

Import it from `@grafloria/element`.

A widget, declared as data.

```ts
interface DashboardWidgetSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `kind?` | `string` |  | Free-form kind string handed back to `renderWidget` (e.g. 'kpi', 'line'). |
| `span?` | `number` |  | Column span (default 3) and row span (default 1). |
| `rows?` | `number` |  |  |
| `x?` | `number` |  | Explicit cell. Omit and widgets flow in declaration order, wrapping at the column count — the common case needs no coordinates at all. |
| `y?` | `number` |  |  |
| `pinned?` | `boolean` |  | Pinned: never pushed, refuses the mover, survives every reflow. |
| `limits?` | `{ minSpan?: number; maxSpan?: number; minRows?: number; maxRows?: number }` |  | SIZE LIMITS in cells (gridstack's minW/maxW/minH/maxH). A resize — by hand, by the API, or by a column change scaling widths — clamps to them. `maxRows` here is the WIDGET's row limit; a container's inner row count is its own `maxRows` field one level up, which is why these live in `limits`. |
| `movable?` | `boolean` |  | May the user drag it? Default true. The API can always move it. |
| `resizable?` | `boolean` |  | May the user resize it? Default true (no handle when false). The API can always resize it. |
| `data?` | `Record<string, unknown>` |  | Your payload — passed straight back to `renderWidget`. |
| `title?` | `string` |  | Optional title used by the built-in fallback renderer. |
| `widgets?` | `DashboardWidgetSpec[]` |  | CONTAINMENT. A widget carrying `widgets` is a CONTAINER: it mounts as a member group (a locked slab in its parent's grid, exactly like a view's board one level down) with its own nested pack grid bound on it. Children lay out inside its frame; dragging a tile across the boundary adopts it live in either direction, and one undo restores the whole gesture. |
| `columns?` | `number` |  | Container only: column count of the INNER grid (default: the parent board's column count). |
| `maxRows?` | `number` |  | Container only: the inner grid's designed row count. A child resized past it ESCALATES — the container's slab grows a row in the parent board (the ratchet), instead of the child overflowing the frame. Default: the row extent of the declared children. |
| `layout?` | `'grid' \| 'split' \| 'tabs'` |  | Container only: the inner board's layout, exactly as a view's. `'grid'` (default) packs the children in cells; `'split'` is a splitter tree that always covers the pane. Switch live with `setLayout(mode, containerId)`; `toJSON()` writes it per container. |
| `active?` | `string` |  | TAB CONTAINER (`layout: 'tabs'`). Every child that carries `widgets` is a PAGE: one is visible at a time, and a strip of tabs across the top switches between them (DevExpress' Tab Container; VS Code's editor area is a split of these). `active` is the page showing, persisted by `toJSON()`; `tabs` styles the strip. |
| `tabs?` | `TabsOptions` |  |  |
| `caption?` | `SectionCaption` |  | Container only: a CAPTION painted by the kit on the section's slab — `true` for the title, a string, or the full options (subtitle, description, icon, position, alignment, typography, box, show, actions, pass-through, className). Reserved inside the frame, selectable, themed, persisted by `toJSON()`; live through `setCaption()`. Default: none. |
| `tree?` | `SplitNode \| null` |  | Container only, split layout: the authored splitter tree. Omit it and the tree is derived from the children's cells. `toJSON()` writes it back. |
| `sizing?` | `'fit' \| 'grow'` |  | Container only: what a pull past the pane's rows does. `'grow'` (default): the container's slab grows a row in the parent — the ratchet above. `'fit'`: the pane is the bound — a child that needs a row the pane does not hold is refused where it stands, and nothing outside the pane moves. |

<!-- source: grafloria-element-dashboard-kit-sectioncaptionoptions.md -->

# SectionCaptionOptions

Import it from `@grafloria/element`.

```ts
interface SectionCaptionOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text?` | `string` |  | Default: the container's `title`. |
| `subtitle?` | `string` |  | A muted second line; the band grows to 44 px. |
| `description?` | `string` |  | An ⓘ after the text: tooltip and the section's accessible description. |
| `icon?` | `string` |  | A glyph before the text (emoji or short text). |
| `position?` | `'inside' \| 'tab'` |  | 'inside' (default): a band across the top of the frame. 'tab': the same band sized to its text, a label chip at the leading corner. BOTH reserve their height inside the SECTION's own cell — a header that hangs over the neighbour above is the overlap bug this feature exists to end. |
| `align?` | `'start' \| 'center' \| 'end'` |  | Horizontal alignment (default 'start', mirrored on RTL). |
| `valign?` | `'top' \| 'center' \| 'bottom'` |  | Vertical alignment within the band (default 'center'). |
| `height?` | `number` |  | Band height, px (default 28; 44 with a subtitle). |
| `font?` | `SectionCaptionFont` |  |  |
| `padding?` | `number \| [number, number]` |  | Inside the band: px, or [vertical, horizontal] (default [0, 10]). |
| `margin?` | `number \| [number, number]` |  | Between the band and the frame: px, or [vertical, horizontal] (default 0). Adds to the reserve. |
| `background?` | `string` |  | Band fill (default: the theme's). |
| `border?` | `string` |  | The band's bottom rule, a CSS border value (default none). |
| `show?` | `'always' \| 'design' \| 'hover'` |  | 'always' (default); 'design' is not painted (nor reserved) under static; 'hover' overlays the content, nothing reserved. |
| `actions?` | `SectionCaptionAction[]` |  | Buttons at the end of the band; a press fires `onCaptionAction` and never selects. |
| `passThrough?` | `string` |  | Presses inside descendants matching this selector are content, never the band's. |
| `className?` | `string` |  | Your class on the band. |

<!-- source: grafloria-element-dashboard-kit-tabsoptions.md -->

# TabsOptions

Import it from `@grafloria/element`.

TAB CONTAINERS — a container whose children are PAGES, one visible at a
time, with a strip of tabs across its top. DevExpress ships this as its Tab
Container; VS Code's editor area is a split of them.

This module owns the strip: its height, its geometry and its DOM. Who is
active, where the pages sit and what a press means are the container's
business (dashboard.ts), exactly as the caption band's press routing is the
binder's.

```ts
interface TabsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `inset?` | `number` |  | Pixels between the frame and the pages — left, right, bottom, and below the strip (0.4.43). The cards of a page sit INSIDE the container's tinted frame, so two cards under one tab read as one panel; a border on the cell alone ran exactly where the cards' own borders were. Default 8; 0 puts the pages edge to edge, the look before 0.4.43. |
| `position?` | `'top'` |  | Where the strip sits. Only 'top' today; 'bottom' \| 'start' \| 'end' follow. |
| `align?` | `'start' \| 'center' \| 'end'` |  | Along the strip (default 'start', mirrored on RTL). |
| `stretch?` | `boolean` |  | Tabs share the strip's width equally. |
| `height?` | `number` |  | Strip height, px (default 30). |
| `className?` | `string` |  | Your class on the strip, for per-container theming. |
| `hidden?` | `boolean` |  | No strip at all (0.4.83) — DevExpress's tab container with ShowCaption="false". Nothing is reserved for it (the pages fill the frame, less `inset`) and nothing is on screen: no element, so no paint, no tab stop and nothing to press. Pages are switched from code — `handle.activateTab()`, `getActiveTab()` and `onTabChange` work as with a visible strip. |

<!-- source: grafloria-element-dashboard-kit-widgethandle.md -->

# WidgetHandle

Import it from `@grafloria/element`.

One widget's OO surface (mirrors ErTable/UmlClass).

```ts
interface WidgetHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `viewId` | `string` |  |  |
| `node` | `NodeModel \| undefined` |  |  |
| `spec` | `DashboardWidgetSpec` |  | The DECLARED spec — read it back (title/kind/data) without a side map. |
| `cell` | `{ x: number; y: number; w: number; h: number } \| undefined` |  | Current cell, as data. |
| `rect` | `{ x: number; y: number; width: number; height: number } \| undefined` |  | The world rect the current cell projects to. |
| `pinned` | `boolean` |  |  |

**Members**

- `resize(span: number, rows: number): Promise<boolean>` — Resize in CELLS. Resolves TRUE when the board accepted it.
- `moveTo(x: number, y: number): Promise<boolean>` — Move to a cell. Resolves TRUE when the board accepted it.
- `pin(on?: boolean): void` — Pin / unpin (a pinned widget refuses the mover and never gets pushed).
- `bringToFront(): void` — Raise / lower — one undoable step each (mirrors the toolbar commands).
- `sendToBack(): void`
- `remove(displaced?: unknown[]): void` — Remove it — ONE undoable step including the survivors' re-pack. `displaced` accepts the commands a drag-out gesture already computed;
omit it and the handle plans them itself.
- `update(patch: Partial<Pick<DashboardWidgetSpec, 'data' | 'title' | 'kind'>>): void` — Replace the widget's `data` (and optionally title) and repaint.
- `repaint(): void` — Repaint through `renderWidget` (after your data changed).

<!-- source: grafloria-element-diagram-kit.md -->

# Diagram Kit

Import these from `@grafloria/element`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-classes): 6 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-constants): 4 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-functions): 22 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-interfaces): 15 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-types): 5 types.
- [`JoinColumn`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-element-diagram-kit-joincolumn): Join guidance — live "which column should I join to?" scoring + tinting for

<!-- source: grafloria-element-diagram-kit-classes.md -->

# Classes

Import these from `@grafloria/element`.

## Classes

### `CardHandle`

```ts
abstract class CardHandle
```

**Methods**

- `constructor( protected readonly api: HandleApi, readonly id: string )`
- `get exists(): boolean`
- `get node(): unknown` — Escape hatch to the underlying NodeModel (typed loosely on purpose).
- `get width(): number`
- `get height(): number`
- `abstract get name(): string`
- `abstract rename(name: string): Promise<boolean>` — Rename the card title — one undoable step.
- `abstract resize(size: { width?: number; height?: number }): Promise<boolean>` — Resize the card — one undoable step (kit body scrolls when capped).
- `select(): void`
- `async undo(): Promise<void>`
- `async redo(): Promise<void>`
- `onRowSelect( cb: (e: { field: ErField | null; selected: RowRef | null }) => void ): () => void` — Row-selection events for THIS card only (the kit's `axk:row-select`,
filtered). ER cards resolve the selection to a typed {@link ErField} when
possible. Returns an unbind function.

### `ErColumnList`

The columns collection of an {@link ErTable}. Iterable of {@link ErField}.

```ts
class ErColumnList implements Iterable<ErField>
```

**Methods**

- `constructor(private readonly table: ErTable)`
- `get length(): number`
- `names(): string[]`
- `at(index: number): ErField | undefined`
- `get(name: string): ErField | undefined`
- `[Symbol.iterator](): Iterator<ErField>`
- `add(column: ErColumn, opts: { at?: number } = {}): Promise<boolean>`
- `removeAt(index: number): Promise<boolean>`
- `renameAt(index: number, name: string): Promise<boolean>`
- `patchAt(index: number, patch: Partial<ErColumn>): Promise<boolean>`
- `move(from: number, to: number): Promise<boolean>`
- `[Symbol.iterator](): Iterator<ErField>`

### `ErField`

A column of an {@link ErTable} — itself just (table, name): stateless.

```ts
class ErField
```

**Methods**

- `constructor( readonly table: ErTable, private readonly columnName: string )`
- `get exists(): boolean`
- `get name(): string`
- `get index(): number`
- `get type(): string | undefined`
- `get pk(): boolean`
- `get fk(): boolean`
- `rename(name: string): Promise<boolean>` — Rename — the field port keeps its id, so attached edges stay glued.
- `setType(type: string): Promise<boolean>`
- `setKeys(keys: { pk?: boolean; fk?: boolean }): Promise<boolean>`
- `remove(): Promise<boolean>` — Remove this column (its ports and attached edges are dropped).

### `ErTable`

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

```ts
class ErTable extends CardHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` |  |  |  |

**Methods**

- `get spec(): ErEntitySpec` — A deep COPY of the stored entity spec — never a live reference.
- `get name(): string`
- `rename(name: string): Promise<boolean>` — Rename the card title — one undoable step.
- `resize(size: { width?: number; height?: number }): Promise<boolean>` — Resize the card — one undoable step (kit body scrolls when capped).
- `update(delta: Parameters<typeof updateEntity>[2]): Promise<boolean>` — The raw delta path — everything above funnels through here.

### `UmlClass`

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

```ts
class UmlClass extends CardHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `attributes` |  |  |  |
| `methods` |  |  |  |

**Methods**

- `get spec(): UmlClassSpec` — A deep COPY of the stored class spec — never a live reference.
- `get name(): string`
- `get abstract(): boolean`
- `get stereotype(): string | undefined`
- `rename(name: string): Promise<boolean>` — Rename the card title — one undoable step.
- `resize(size: { width?: number; height?: number }): Promise<boolean>` — Resize the card — one undoable step (kit body scrolls when capped).
- `setAbstract(abstract: boolean): Promise<boolean>`
- `setStereotype(stereotype: string | undefined): Promise<boolean>`
- `update(delta: Parameters<typeof updateClass>[2]): Promise<boolean>`

### `UmlMemberList`

attributes / methods of a {@link UmlClass} (members are plain strings).

```ts
class UmlMemberList
```

**Methods**

- `constructor( private readonly cls: UmlClass, private readonly kind: 'attributes' | 'methods' )`
- `list(): string[]`
- `get length(): number`
- `at(index: number): string | undefined`
- `add(member: string, opts: { at?: number } = {}): Promise<boolean>`
- `removeAt(index: number): Promise<boolean>`
- `renameAt(index: number, member: string): Promise<boolean>`

<!-- source: grafloria-element-diagram-kit-constants.md -->

# Constants

Import these from `@grafloria/element`.

## Constants

### `DIAGRAM_KIT_STYLE_ID`

Diagram-kit stylesheet — injected once, on first use of any kit builder.

Everything is prefixed `axk-` and the selection overrides are scoped with
`:has(...)` to kit cards only, so embedding the kit can never restyle a
host's own nodes. The rules encode the lessons the diagrams/* demos learned
the hard way:
 - the card fills the node and draws the ONLY border (the node's own rect is
   hidden by the builders, and suppressed again on selection because the
   theme paints `.selected` with an accent stroke that overrides inline
   transparency);
 - the default `.selection-highlight` outline (a dashed rect a few px
   OUTSIDE the node) reads as a second floating box around a bordered card —
   the kit hides it and rings the card itself instead.

```ts
const DIAGRAM_KIT_STYLE_ID: "grafloria-diagram-kit-styles"
```

### `ER_HEAD_H`

```ts
const ER_HEAD_H: 28
```

### `ER_ROW_H`

Row height / header height of the entity card — sizing is derived from these.

```ts
const ER_ROW_H: 25
```

### `JOIN_GUIDANCE_STYLE_ID`

```ts
const JOIN_GUIDANCE_STYLE_ID: "grafloria-join-guidance-styles"
```

<!-- source: grafloria-element-diagram-kit-functions.md -->

# Functions

Import these from `@grafloria/element`.

## Functions

### `addColumnAt`

Append a column (immutably) — returns the new column array.

```ts
function addColumnAt(columns: ErColumn[], column: ErColumn, at = columns.length): ErColumn[]
```

### `assignTiers`

Tier every candidate score at once: the FIRST candidate holding the maximum
score is `top` when that maximum is >= 2 — exactly one gold row per drag.

```ts
function assignTiers(scores: number[]): MatchTier[]
```

### `bindCardEditing`

Wire the editing gestures onto a kit container. Idempotent per container
(a re-bind disposes the previous one), matching `bindRowInteractions`.

```ts
function bindCardEditing(api: EditApi): CardEditingHandle
```

### `bindJoinGuidance`

Bind live join guidance to a diagram instance. Listens to the engine's
connection lifecycle; while a drag is live, every kit-card row on every
other table wears its tier class (and the best one its "★ BEST" chip), and
the matching port glyphs glow via a generated stylesheet. Everything clears
when the drag ends, however it ends.

```ts
function bindJoinGuidance(api: JoinGuidanceApi, options: JoinGuidanceOptions = {}): JoinGuidanceHandle
```

### `ensureDiagramKitStyles`

Inject the kit stylesheet once. Safe to call repeatedly and in SSR.

```ts
function ensureDiagramKitStyles(doc: Document | undefined = typeof document !== 'undefined' ? document : undefined): void
```

### `ensureJoinGuidanceStyles`

Inject the guidance tint stylesheet once. Safe to call repeatedly / in SSR.

```ts
function ensureJoinGuidanceStyles(
  doc: Document | undefined = typeof document !== 'undefined' ? document : undefined
): void
```

### `erDiagram`

Build a render() spec for an ER diagram.

Entities become HTML table cards; relationships become orthogonal edges with
crow's-foot cardinality. A `TABLE.column` end pins the edge to that row via
an absolute-layout port (the FK→PK look). Two edges landing on the same
column are automatically spread apart.

```ts
function erDiagram(options: ErDiagramOptions): {
  nodes: Array<Record<string, unknown>>;
  edges: Array<Record<string, unknown>>;
  finalize: (api: unknown) => void;
}
```

### `erRowCenterY`

Node-local y of a row's centre (the +1 offsets past the card's top border).

```ts
function erRowCenterY(rowIndex: number): number
```

### `erTable`

Typed handle for a kit ER table. Throws for unknown ids / non-kit nodes.

```ts
function erTable(api: HandleApi, id: string): ErTable
```

### `erTables`

Every kit ER table in the diagram, as handles.

```ts
function erTables(api: HandleApi): ErTable[]
```

### `matchColumns`

Match old columns to new columns for port reconciliation. Returns a map from
OLD index → NEW index; an old index absent from the map is a REMOVED column
(its pinned ports and their edges are dropped).

Three passes, most-certain first, so a single edit is always read the way a
human means it:
  1. object identity — reorder / add / remove that preserved references;
  2. name — a retype (same name, new object) or a rebuilt array;
  3. positional remainder — the leftovers matched in order, which is exactly
     what a rename is (one old + one new in the same slot). Without pass 3 a
     rename reads as remove+add and the edge is severed.

```ts
function matchColumns(oldCols: ErColumn[], newCols: ErColumn[]): Map<number, number>
```

### `matchTier`

Per-score tier (rank-free half; `assignTiers` promotes the single best to `top`).

```ts
function matchTier(score: number): Exclude<MatchTier, 'top'>
```

### `removeColumnAt`

Remove the column at `index` — returns the new column array.

```ts
function removeColumnAt(columns: ErColumn[], index: number): ErColumn[]
```

### `renameColumnAt`

Rename the column at `index` — returns a new array with a NEW object there.

```ts
function renameColumnAt(columns: ErColumn[], index: number, name: string): ErColumn[]
```

### `rowIndexFromY`

Inverse of {@link erRowCenterY}: which column row a pinned port sits on.

```ts
function rowIndexFromY(y: number): number
```

### `scoreMatch`

Score a candidate join between two columns. Pure; the exact production
logic. Higher is better; 0 means "no reason to join these".

```ts
function scoreMatch(a: JoinEnd, b: JoinEnd): 0 | 1 | 2 | 3
```

### `singularize`

Naive English singular — enough for schema names (orders, categories, statuses).

```ts
function singularize(word: string): string
```

### `umlClass`

Typed handle for a kit UML class. Throws for unknown ids / non-kit nodes.

```ts
function umlClass(api: HandleApi, id: string): UmlClass
```

### `umlClasses`

Every kit UML class in the diagram, as handles.

```ts
function umlClasses(api: HandleApi): UmlClass[]
```

### `umlDiagram`

Build a render() spec for a UML class diagram. Call `spec.finalize(api)`
after render() — multiplicity chips are positioned labels, which only the
live model's `link.addLabel` can express.

```ts
function umlDiagram(options: UmlDiagramOptions): {
  nodes: Array<Record<string, unknown>>;
  edges: Array<Record<string, unknown>>;
  finalize: (api: unknown) => void;
}
```

### `updateClass`

Edit a rendered UML class in place. `delta` may change the name, stereotype,
abstract flag, attributes, methods, and width/height. One undoable step.

```ts
function updateClass(api: KitApi, classId: string, delta: UmlClassDelta): Promise<boolean>
```

### `updateEntity`

Edit a rendered ER table in place. `delta` may change the name, the column
list (add / remove / reorder / rename / retype), and the width/height. Field
ports and their edges are reconciled so the diagram stays correct, as ONE
undoable step.

```ts
function updateEntity(api: KitApi, entityId: string, delta: ErEntityDelta): Promise<boolean>
```

**Returns** whether the node existed and the edit was applied.

<!-- source: grafloria-element-diagram-kit-interfaces.md -->

# Interfaces

Import these from `@grafloria/element`.

## Interfaces

### `CardEditingHandle`

```ts
interface CardEditingHandle
```

**Members**

- `dispose(): void`

### `ErColumn`

```ts
interface ErColumn
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `type?` | `string` |  |  |
| `pk?` | `boolean` |  |  |
| `fk?` | `boolean` |  |  |

### `ErDiagramOptions`

```ts
interface ErDiagramOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `ErEntitySpec[]` |  |  |
| `relationships?` | `ErRelationshipSpec[]` |  |  |
| `rowSelection?` | `boolean` |  | Rows are selectable by default: click a column to select it (painted with .axk-row-selected; axk:row-click / axk:row-select CustomEvents fire on the container). Set false to opt out. |
| `editable?` | `boolean` |  | In-canvas editing (opt-in, default false — read-only diagrams are unchanged). When true the card grows editing chrome: double-click the header to rename the table, double-click a column name to rename it, an "add column" affordance and a per-row delete control. Every change routes through {@link updateEntity } as ONE undoable step. |

### `ErEntityDelta`

What an ER table edit can change. Omitted fields are left as they were.

```ts
interface ErEntityDelta
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `columns?` | `ErColumn[]` |  | The NEW full column list. Survivors are matched to the old columns to move their ports (object identity → name → positional remainder), so a rename, a retype, a reorder, an insert and a delete are all understood without the caller preserving object references. See {@link matchColumns}. |

### `ErEntitySpec`

```ts
interface ErEntitySpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name?` | `string` |  | Header text. Defaults to the id. |
| `columns` | `ErColumn[]` |  |  |
| `position?` | `{ x: number; y: number }` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  | Fixed card height. When smaller than the computed height the column list SCROLLS (the kit body is overflow-y:auto, and the canvas yields the wheel to it). Omit for auto-height from the column count. |

### `ErRelationshipSpec`

```ts
interface ErRelationshipSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  | Entity id, or `ENTITY.column` to attach at that column's row. |
| `to` | `string` |  |  |
| `label?` | `string` |  |  |
| `cardinality?` | `ErCardinality \| { tail: string; head: string }` |  | Named cardinality (default one-to-many) or explicit marker types. |
| `fromSide?` | `ErSide` |  |  |
| `toSide?` | `ErSide` |  |  |
| `color?` | `string` |  |  |
| `id?` | `string` |  |  |

### `HandleApi`

The slice of DiagramInstance the handles need (same shape update.ts uses).

```ts
interface HandleApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |

**Members**

- `getModel(): { getNode(id: string): | { getMetadata?(key: string): unknown; size: { width: number; height: number }; state?: { selected?: boolean }; } | undefined; selectNode?(node: unknown): void; }`
- `getEngine?(): { undo(): Promise<void> | void; redo(): Promise<void> | void } | undefined`
- `renderNow?(): void`

### `JoinEnd`

One end of a candidate join: a table (node) and one of its columns.

```ts
interface JoinEnd
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `table` | `string` |  |  |
| `column` | `JoinColumn` |  |  |

### `JoinGuidanceApi`

The slice of DiagramInstance the binding needs (matches HandleApi's shape).

```ts
interface JoinGuidanceApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |

**Members**

- `getModel(): { getNode(id: string): NodeLike | undefined; getNodes?(): NodeLike[]; }`
- `getEngine?(): | { eventBus?: { on(event: string, handler: (data: unknown) => void): () => void } } | undefined`

### `JoinGuidanceHandle`

```ts
interface JoinGuidanceHandle
```

**Members**

- `activeTiers(): Map<string, Map<number, MatchTier>>` — nodeId → rowIndex → tier for the drag in progress (empty when idle).
- `dispose(): void`

### `JoinGuidanceOptions`

```ts
interface JoinGuidanceOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `resolvePort?` | `(portId: string, nodeId: string \| undefined) => { nodeId: string; column: string } \| null` |  | Resolve a PORT id to its table column. The default understands both the ER kit's convention (`TABLE__col__side__n`) and the query-builder dot convention (`table.col-in` / `table.col-out`), checked against the node's actual `kitEntity` columns so an ambiguous name never mis-resolves. |
| `chipText?` | `string` |  | Text of the gold chip on the best row. Default `'★ BEST'`. |
| `portCss?` | `(tier: MatchTier, selector: string) => string` |  | Extra per-tier CSS for the target columns' PORT glyphs, injected per drag. Default paints the production glows (gold/green/blue drop-shadows). |

### `UmlClassDelta`

What a UML class edit can change.

```ts
interface UmlClassDelta
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  |  |
| `stereotype?` | `string` |  |  |
| `abstract?` | `boolean` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `attributes?` | `string[]` |  |  |
| `methods?` | `string[]` |  |  |

### `UmlClassSpec`

```ts
interface UmlClassSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name?` | `string` |  | Displayed name. Defaults to the id. |
| `stereotype?` | `string` |  | Renders as «stereotype» above the name (e.g. 'interface', 'abstract', 'enum'). |
| `abstract?` | `boolean` |  | Italicises the name (also set automatically for stereotype 'abstract'/'interface'). |
| `attributes?` | `string[]` |  |  |
| `methods?` | `string[]` |  |  |
| `position?` | `{ x: number; y: number }` |  |  |
| `width?` | `number` |  |  |
| `height?` | `number` |  | Fixed card height — smaller than the content makes the compartments scroll. |

### `UmlDiagramOptions`

```ts
interface UmlDiagramOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `UmlClassSpec[]` |  |  |
| `relationships?` | `UmlRelationshipSpec[]` |  |  |
| `rowSelection?` | `boolean` |  | Members are selectable by default: click one to select it (painted with .axk-row-selected; axk:row-click / axk:row-select CustomEvents fire on the container). Set false to opt out. |
| `editable?` | `boolean` |  | In-canvas editing (opt-in, default false). When true: double-click the class name to rename it, double-click a member to rename it, an "add" affordance per compartment and a per-member delete control — all routed through {@link updateClass } as one undoable step. |

### `UmlRelationshipSpec`

```ts
interface UmlRelationshipSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  |  |
| `to` | `string` |  |  |
| `kind?` | `UmlRelationKind` |  | Default 'association'. |
| `label?` | `string` |  |  |
| `multiplicity?` | `[string, string]` |  | Multiplicity / role chips at the [from, to] ends (e.g. ['0..*', '1']). |
| `fromSide?` | `UmlSide` |  |  |
| `toSide?` | `UmlSide` |  |  |
| `id?` | `string` |  |  |

<!-- source: grafloria-element-diagram-kit-types.md -->

# Types

Import these from `@grafloria/element`.

## Types

### `ErCardinality`

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

```ts
type ErCardinality =
  | 'one-to-many'
  | 'one-to-one'
  | 'many-to-many'
  | 'one-to-zero-or-many'
  | 'one-to-one-or-many';
```

### `ErSide`

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

```ts
type ErSide = 'left' | 'right' | 'top' | 'bottom';
```

### `MatchTier`

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

```ts
type MatchTier = 'top' | 'good' | 'ok' | 'none';
```

### `UmlRelationKind`

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

```ts
type UmlRelationKind =
  | 'inheritance'
  | 'realization'
  | 'association'
  | 'directed-association'
  | 'aggregation'
  | 'composition'
  | 'dependency';
```

### `UmlSide`

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

```ts
type UmlSide = 'left' | 'right' | 'top' | 'bottom';
```

<!-- source: grafloria-element-diagram-kit-joincolumn.md -->

# JoinColumn

Import it from `@grafloria/element`.

Join guidance — live "which column should I join to?" scoring + tinting for
kit table cards, the feature a visual query builder is actually about.

Ported verbatim from a production BI tool's Query Studio (the scoring is ~55
pure lines there too). While a connection drag is in progress, every column
on every OTHER table is scored against the drag's source column and its card
row is tinted by tier:

score 3 — PK↔FK naming convention: `orders.customer_id` ↔ `customers.id`
            (`<singular(table)>_id` on one end, `id` on the other), or exact
            FK column-name equality across tables;
  score 2 — a PK flag on one end and an FK flag on the other;
  score 1 — same column name, or both names end in "id";
  score 0 — same table, or nothing.

Tiers: the single best candidate scoring >= 2 is `top` (gold, "★ BEST"),
every other >= 2 is `good` (green), 1 is `ok` (blue), 0 is `none` (dimmed). The SOURCE table is never tinted, and every tint clears when the drag ends —
complete, cancelled or escaped.

Split the same way the rest of the kit is:
  - `scoreMatch` / `matchTier` / `assignTiers` / `singularize` are PURE
    (unit-specced in the element suite);
  - `bindJoinGuidance(api)` is the runtime: it listens to the engine's own
    connection lifecycle events (`connection:start` / `:complete` /
    `:cancel`) and paints tier classes onto the kit's `.axk-row` elements.

Row tints go on as DOM classes — the renderer's foreignObject subtrees are
patch-opaque, so classes survive the per-frame VNode patch. Port tints go in
as a generated per-drag <style> element keyed by `data-port-id`: port glyphs
ARE re-patched every frame, so a class added to the SVG element would be
wiped mid-drag, while a stylesheet wins the cascade and survives.

```ts
interface JoinColumn
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  |  |
| `pk?` | `boolean` |  |  |
| `fk?` | `boolean` |  |  |

<!-- source: grafloria-element-stencil-kit.md -->

# Stencil Kit

Import these from `@grafloria/element`.

## Functions

### `bindShapeDataPanel`

Bind a shape-data panel into `host`. It follows the diagram's selection:
nodes, edges and multi-selections each get their own sections; nothing
selected shows the empty message.

```ts
function bindShapeDataPanel(
  api: ShapeDataPanelApi,
  host: HTMLElement,
  options: ShapeDataPanelOptions = {}
): ShapeDataPanelHandle
```

### `bindStencilPalette`

Build a stencil palette in `palette` that drops masters onto `canvas`.

```ts
function bindStencilPalette(
  api: StencilPaletteApi,
  hosts: { palette: HTMLElement; canvas: HTMLElement },
  options: StencilPaletteOptions = {}
): StencilPaletteHandle
```

**Parameters**

- `api`: the diagram instance (engine + model + viewport)
- `hosts`: `palette`: where the list renders · `canvas`: the drop target (the element the diagram is mounted in)

### `ensureStencilKitStyles`

Inject the palette stylesheet once per document.

```ts
function ensureStencilKitStyles(doc: Document = document): void
```

## Interfaces

### `ShapeDataPanelApi`

```ts
interface ShapeDataPanelApi
```

**Members**

- `getEngine(): any`
- `getModel(): any`
- `on(event: string, handler: (payload: any) => void): () => void`

### `ShapeDataPanelHandle`

```ts
interface ShapeDataPanelHandle
```

**Members**

- `refresh(): void` — Re-read the selection and rebuild the fields.
- `destroy(): void`

### `ShapeDataPanelOptions`

```ts
interface ShapeDataPanelOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title?` | `string` |  | Heading above the fields (default "Shape data"). |
| `emptyText?` | `string` |  | Shown when nothing (or more than one thing) is selected. |
| `onEdit?` | `(info: { nodeId: string; key: string; value: unknown }) => void` |  | Called after an edit commits. |

### `StencilPaletteApi`

The bits of a diagram instance the palette needs (kept structural so any
host — element, React, Vue — satisfies it without importing a class).

```ts
interface StencilPaletteApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `viewport` | `{ clientToWorld(x: number, y: number, rect: { left: number; top: number; width: number; height: number }): { x: number; y: number } }` |  |  |

**Members**

- `getEngine(): any`
- `getModel(): any`

### `StencilPaletteHandle`

```ts
interface StencilPaletteHandle
```

**Members**

- `setSearch(query: string): void` — Filter the list programmatically (same as typing in the search box).
- `place(masterId: string, world: { x: number; y: number }): Promise<string | null>` — Place a master at a WORLD point without dragging (keyboard / test path).
- `destroy(): void` — Remove listeners and the palette DOM.

### `StencilPaletteOptions`

```ts
interface StencilPaletteOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `stencils?` | `Stencil[]` |  | Sections to show (default: every built-in stencil). |
| `search?` | `boolean` |  | Show the search box (default true). |
| `collapsed?` | `string[]` |  | Stencil ids to render collapsed initially (default: all but the first). |
| `data?` | `(master: NodeTemplate) => Record<string, unknown>` |  | Data merged into every placed master (e.g. a default label). |
| `onPlace?` | `(info: { master: NodeTemplate; nodeId: string; x: number; y: number }) => void` |  | Called after a master is placed on the canvas. |
| `notationTheme?` | `Record<string, { fill?: string; stroke?: string }>` |  | Restyle the shapes per stencil WITHOUT editing any master — the seam that makes stencil colour a host/theme decision instead of baked template data. Keyed by stencil id (`flowchart`, `bpmn`, `uml`, `erd`); each entry overrides the master's own `fill` / `stroke`. Pass `'theme'` for a value to take it from the live theme instead of a literal. |
| `htmlLayer?` | `boolean` |  | Opt a placed master INTO `useHTMLLayer`. Only set this when the host really runs an HTML layer that paints `node.data._html` — with the plain SVG renderer the flag makes the node render as an empty group. |

<!-- source: grafloria-angular-overview.md -->

# @grafloria/angular

Angular components for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, native in Angular.

## Install

```bash
npm install @grafloria/angular @angular/common @angular/core @angular/forms @angular/platform-browser @grafloria/engine @grafloria/renderer rxjs @grafloria/element
```

It expects these alongside it:

- `@angular/common` ^18.1.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0
- `@angular/core` ^18.1.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0
- `@angular/forms` ^18.1.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0
- `@angular/platform-browser` ^18.1.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0
- `@grafloria/engine` ^0.3.18
- `@grafloria/renderer` ^0.4.0
- `rxjs` ^7.8.0
- `@grafloria/element` ^0.4.3

## What it exports

- [Core](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-core): 9 exports, including `AngularComponentAdapter`, `GRAFLORIA_CONFIG`, `GrafloriaConfig`, `GrafloriaHandleDirective`
- [Components](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components): 67 exports, including `AnimationPreset`, `AutoToolbarDirective`, `clamp01`, `ClosestHit`
- [Interaction](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-interaction): 17 exports, including `buildMarqueeRect`, `directionToIntersectionMode`, `HitKind`, `HitTestResult`
- [Services](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services): 37 exports, including `AngularAnimationService`, `AnimationCallback`, `AnimationConfig`, `AnimationStats`

## Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

- From [@grafloria/renderer](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-renderer-overview): `LinkPartHit`

<!-- source: grafloria-angular-core.md -->

# Core

Import these from `@grafloria/angular`.

## Functions

### `provideGrafloria`

The modern Angular configuration idiom:

```ts
bootstrapApplication(AppComponent, {
  providers: [provideGrafloria({ theme: DARK_THEME })],
});
```

```ts
function provideGrafloria(config: GrafloriaConfig): EnvironmentProviders
```

## Classes

### `AngularComponentAdapter`

Angular implementation of ComponentAdapter interface

Thin wrapper around ComponentRendererService that implements
framework-agnostic ComponentAdapter interface.

```ts
@Injectable({ providedIn: 'root' })
export class AngularComponentAdapter implements ComponentAdapter
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `framework` |  | `'angular'` | Framework identifier |

**Methods**

- `constructor(private componentRenderer: ComponentRendererService)`
- `registerComponent(nodeType: string, component: Type<any>): void` — Register Angular component for node type
- `hasComponent(nodeType: string): boolean` — Check if component is registered for node type
- `getComponent(nodeType: string): Type<any> | undefined` — Get registered component class
- `createComponentInstance(node: NodeModel, container: ViewContainerRef): ComponentRef<any>` — Create Angular component instance for node

Converts NodeModel to component inputs:
- Spreads node.data as inputs
- Passes positionX, positionY
- Passes nodeData (full node data object)
- `updateComponentInstance(instance: ComponentRef<any>, node: NodeModel): void` — Update component instance with new node data
- `destroyComponentInstance(instance: ComponentRef<any>): void` — Destroy component instance
- `getRegisteredTypes(): string[]` — Get list of all registered node types
- `destroyAll(): void` — Destroy all component instances
- `getActiveCount(): number` — Get count of active component instances

### `GrafloriaHandleDirective`

Directive to mark HTML elements as connection handles (React Flow style)

Usage:
```html
<div grafloriaHandle="source" handleId="output-1" handlePosition="right">
  Connect Here
</div>
```

The directive automatically:
- Registers the handle with HandleRegistryService on init
- Unregisters on destroy
- Allows DOM-based position queries for connections

Hybrid HTML+SVG Rendering

```ts
@Directive({
  selector: '[grafloriaHandle]',
  standalone: true,
})
export class GrafloriaHandleDirective implements AfterViewInit, OnDestroy
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `grafloriaHandle` | `'source' \| 'target'` |  | Handle type: 'source' (output) or 'target' (input) Required. |
| `handleId?` | `string` |  | Unique handle ID within the node If not provided, will be auto-generated |
| `handlePosition?` | `'top' \| 'right' \| 'bottom' \| 'left'` |  | Handle position relative to node Affects how connections are drawn |

**Methods**

- `ngAfterViewInit(): void`
- `ngOnDestroy(): void`

### `GrafloriaNodeDefDirective`

Declarative, Angular-native custom nodes — the template idiom:

```html
<grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges">
  <ng-template grafloriaNode="card" let-node let-data="data">
    <div class="card">
      <h4>{{ data['title'] }}</h4>
      <p>{{ data['subtitle'] }}</p>
    </div>
  </ng-template>
</grafloria-diagram-canvas>
```

A node whose `type` matches a template is rendered by THAT template in the
HTML layer — full Angular change detection, pipes, directives, and bindings,
no string micro-templates and no component registry required. In controlled
mode the canvas flags matching specs as `custom` automatically, so declaring
the template is the whole integration.

`grafloriaNode` with no value (`<ng-template grafloriaNode>`) is the
wildcard: it renders any HTML-layer node whose type has no exact template.

```ts
@Directive({ selector: 'ng-template[grafloriaNode]' })
export class GrafloriaNodeDefDirective
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` |  |  | Node `type` this template renders; empty string = wildcard fallback. |
| `templateRef` |  |  |  |

**Methods**

- `static ngTemplateContextGuard( _dir: GrafloriaNodeDefDirective, ctx: unknown ): ctx is GrafloriaNodeTemplateContext` (static)

### `ResponsiveCanvasDirective`

```ts
@Directive({
  selector: '[grafloriaResponsiveCanvas]',
  standalone: true,
})
export class ResponsiveCanvasDirective implements OnInit, OnDestroy, OnChanges
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` | `IResponsiveCanvasEngine` |  |  |
| `maintainZoom` |  | `true` |  |
| `maintainCenter` |  | `true` |  |
| `enabled` |  | `true` |  |
| `autoEnable` |  | `true` |  |

**Methods**

- `constructor(private el: ElementRef<HTMLElement>)`
- `ngOnInit()`
- `ngOnChanges(changes: any)`
- `enable()` — Enable responsive behavior
- `disable()` — Disable responsive behavior
- `toggle()` — Toggle responsive behavior on/off
- `isEnabled(): boolean` — Check if responsive behavior is enabled
- `triggerResize()` — Manually trigger a resize operation
- `ngOnDestroy()`

## Constants

### `GRAFLORIA_CONFIG`

```ts
const GRAFLORIA_CONFIG: any
```

## Interfaces

### `GrafloriaConfig`

Application-wide Grafloria defaults, set once at bootstrap. Explicit inputs
on a specific `<grafloria-diagram-canvas>` always win over these.

```ts
interface GrafloriaConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme?` | `Theme` |  | Default theme for every canvas that does not bind `[theme]` itself. |

### `GrafloriaNodeTemplateContext`

Template context for `<ng-template grafloriaNode>` custom-node templates.

`$implicit` is the live model, so `let-node` gives templates the full
NodeModel surface; `data` is the free-form user payload for the common case.

```ts
interface GrafloriaNodeTemplateContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `$implicit` | `NodeModel \| GroupModel` |  |  |
| `engine` | `DiagramEngine \| undefined` |  |  |
| `data` | `Record<string, unknown>` |  |  |

### `IResponsiveCanvasEngine`

```ts
interface IResponsiveCanvasEngine
```

**Members**

- `getCanvas?(): HTMLElement | null`
- `getZoom(): number`
- `setZoom?(zoom: number): void`
- `getPan(): { x: number; y: number }`
- `setPan(x: number, y: number): void`
- `repaint?(): void`

<!-- source: grafloria-angular-components.md -->

# Components

Import these from `@grafloria/angular`.

## On their own pages

- [Classes](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-classes): 5 classes.
- [Constants](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-constants): 1 constants.
- [Functions](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-functions): 30 functions.
- [Interfaces](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interfaces): 18 interfaces.
- [Types](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-types): 6 types.
- [`DiagramCanvasComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-diagramcanvascomponent): DiagramCanvasComponent
- [`GrafloriaDashboardComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-grafloriadashboardcomponent): `<grafloria-dashboard>` — the dashboard kit, the Angular way.
- [`InteractionConfigPanelComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-interactionconfigpanelcomponent): InteractionConfigPanelComponent
- [`LinkToolbarComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-linktoolbarcomponent): Card B — a floating, PATH-ANCHORED action layer.
- [`NodeToolbarComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-nodetoolbarcomponent): NodeToolbar Component
- [`PropertyPanelComponent`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-propertypanelcomponent): Property panel component for editing diagram node properties. Displays editable properties based on PropertySchema.
- [`RenderedLinkPath`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-components-renderedlinkpath): Card B — the RENDERED route of a link.

<!-- source: grafloria-angular-components-classes.md -->

# Classes

Import these from `@grafloria/angular`.

## Classes

### `AutoToolbarDirective`

AutoToolbarDirective

Automatically shows/hides node toolbars based on node selection. Apply this directive to the diagram canvas container to enable automatic toolbar management.

```ts
@Directive({
  selector: '[grafloriaAutoToolbar]',
  standalone: true,
})
export class AutoToolbarDirective implements OnInit, OnDestroy
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` | `DiagramEngine` |  |  |
| `viewport` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `zoom` | `number` | `1.0` |  |
| `toolbarPosition` | `ToolbarPosition` | `'top'` |  |
| `toolbarAlignment` | `ToolbarAlignment` | `'center'` |  |
| `toolbarActions` | `ToolbarAction[]` | `[]` |  |
| `toolbarTemplate?` | `TemplateRef<any>` |  |  |
| `toolbarOffset?` | `number` |  |  |

**Methods**

- `constructor( private toolbarService: NodeToolbarService, private viewContainerRef: ViewContainerRef, private elementRef: ElementRef<HTMLElement>, private environmentInjector: EnvironmentInjector )`
- `ngOnInit()`
- `ngOnDestroy()`
- `updateViewport(viewport: { x: number; y: number; width: number; height: number })` — Update viewport (to be called when viewport changes)
- `updateZoom(zoom: number)` — Update zoom (to be called when zoom changes)

**Example**

```html
<div grafloriaAutoToolbar
     [engine]="diagramEngine"
     [viewport]="viewport"
     [zoom]="zoom"
     [toolbarPosition]="'top'"
     [toolbarActions]="actions">
  <grafloria-diagram-canvas [engine]="engine"></grafloria-diagram-canvas>
</div>
```

### `GrafloriaCommentPanelComponent`

`<grafloria-comment-panel>` — the conversation UI for a comment store:
thread list, unread markers, selection. Feed it the canvas's store:

```html
<grafloria-diagram-canvas #canvas [comments]="true" … />
<grafloria-comment-panel [store]="canvas.getCommentStore()"
                         (threadSelect)="focus($event)" />
```

```ts
@Component({
  selector: 'grafloria-comment-panel',
  template: '',
  styles: [':host { display: block; }'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GrafloriaCommentPanelComponent implements AfterViewInit, OnDestroy
```

Use it as `<grafloria-comment-panel>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` | `CommentStore` |  |  |
| `options?` | `CommentPanelOptions` |  |  |

**Outputs**

- `threadSelect` — The selected thread id, or null when dismissed.

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `store` |  |  |  |
| `options` |  |  |  |
| `threadSelect` |  |  | The selected thread id, or null when dismissed. |

**Methods**

- `ngAfterViewInit(): void`
- `select(threadId: string | null): void` — Programmatic selection (e.g. from a pin click).
- `ngOnDestroy(): void`

### `GrafloriaDiagramComponent`

`<grafloria-diagram>` — the generic kit host. Any kit spec renders:

```ts
spec = erDiagram({ entities, relationships });        // or umlDiagram({...}),
```
```html
<grafloria-diagram [spec]="spec" (ready)="instance = $event" />
```

One component for every present and future kit — because every kit speaks
the same contract: a spec with nodes/edges/renderCustomNode/finalize that
`render()` mounts in one call.

```ts
@Component({
  selector: 'grafloria-diagram',
  template: '',
  styles: [':host { display: block; position: relative; }'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GrafloriaDiagramComponent implements AfterViewInit, OnChanges, OnDestroy
```

Use it as `<grafloria-diagram>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RenderSpec` |  | Any kit spec — `erDiagram(...)`, `umlDiagram(...)`, `dashboard(...)`, or DSL text. |
| `options?` | `RenderOptions` |  | Options passed through to the underlying `createDiagram`. |

**Outputs**

- `ready` — The live DiagramInstance after mount.

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` |  |  | Any kit spec — `erDiagram(...)`, `umlDiagram(...)`, `dashboard(...)`, or DSL text. |
| `options` |  |  | Options passed through to the underlying `createDiagram`. |
| `ready` |  |  | The live DiagramInstance after mount. |

**Methods**

- `ngAfterViewInit(): void`
- `ngOnChanges(changes: SimpleChanges): void` — A CHANGED spec or options replaces the diagram; an equal new one does not.
- `getInstance(): DiagramInstance | undefined`
- `ngOnDestroy(): void`

### `GrafloriaWidgetDefDirective`

Declarative dashboard widgets — the node-template idiom applied to boards:

```html
<grafloria-dashboard [views]="views">
  <ng-template grafloriaWidget="orders" let-widget let-data="data">
    <app-orders-card [orders]="data['orders']" />
  </ng-template>
</grafloria-dashboard>
```

A widget whose `kind` matches a template renders through it — full Angular
change detection, components, pipes, and event handlers. Kinds without a
template fall back to the kit's built-in painters
(kpi / line / bar / donut / funnel / table). `grafloriaWidget` with no value
is the wildcard for any kind without an exact template.

```ts
@Directive({ selector: 'ng-template[grafloriaWidget]' })
export class GrafloriaWidgetDefDirective
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` |  |  | Widget `kind` this template renders; empty string = wildcard fallback. |
| `templateRef` |  |  |  |

**Methods**

- `static ngTemplateContextGuard( _dir: GrafloriaWidgetDefDirective, ctx: unknown ): ctx is GrafloriaWidgetTemplateContext` (static)

### `NodeToolbarService`

NodeToolbarService

Manages the lifecycle of node toolbars in the diagram. Provides methods to show, hide, and update toolbars programmatically.

```ts
@Injectable({ providedIn: 'root' })
export class NodeToolbarService
```

**Methods**

- `setViewContainer(vcr: ViewContainerRef)` — Set the view container for creating toolbars
- `setEnvironmentInjector(injector: EnvironmentInjector)` — Set the environment injector for creating components
- `setCanvasElement(element: HTMLElement)` — Set global canvas element for all toolbars
- `setViewport(viewport: { x: number; y: number; width: number; height: number })` — Set global viewport for all toolbars
- `setZoom(zoom: number)` — Set global zoom for all toolbars
- `show( node: NodeModel, engine: DiagramEngine, config: ToolbarConfig = {} ): ComponentRef<NodeToolbarComponent>` — Show toolbar for a node
- `hide(nodeId: string)` — Hide toolbar for a node
- `hideAll()` — Hide all toolbars
- `get(nodeId: string): ComponentRef<NodeToolbarComponent> | undefined` — Get toolbar for a node
- `isShown(nodeId: string): boolean` — Check if toolbar is shown for a node
- `updatePosition(nodeId: string)` — Update toolbar position for a node
- `updateAllPositions()` — Update positions for all toolbars
- `updateConfig(nodeId: string, config: Partial<ToolbarConfig>)` — Update toolbar configuration
- `getCount(): number` — Get the number of active toolbars
- `getAll(): ComponentRef<NodeToolbarComponent>[]` — Get all toolbar component references

**Example**

```typescript
constructor(private toolbarService: NodeToolbarService) {}

ngOnInit() {
  this.toolbarService.setViewContainer(this.viewContainerRef);
}

showToolbar(node: NodeModel) {
  this.toolbarService.show(node, this.engine, {
    position: 'top',
    actions: this.actions
  });
}
```

<!-- source: grafloria-angular-components-constants.md -->

# Constants

Import these from `@grafloria/angular`.

## Constants

### `TOOLBAR_PRESETS`

Preset registry for easy access

```ts
const TOOLBAR_PRESETS: { readonly minimal: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly standard: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly full: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly erd: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly workflow: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly mindMap: (engine: DiagramEngine, onEdit?: (node: any) => void) => NodeToolbarConfig; readonly …
```

<!-- source: grafloria-angular-components-functions.md -->

# Functions

Import these from `@grafloria/angular`.

## Functions

### `clamp01`

```ts
function clamp01(t: number): number
```

### `closestOnPolyline`

```ts
function closestOnPolyline(points: Point[], target: Point): ClosestHit | null
```

### `createAddConnectionAction`

Create action to add connection from this node
Enables connection mode starting from this node

```ts
function createAddConnectionAction(engine: DiagramEngine): ToolbarAction
```

### `createAllActions`

Helper to create all actions including advanced ones
Returns the full set of available toolbar actions

```ts
function createAllActions(
  engine: DiagramEngine,
  onEdit?: (node: NodeModel) => void
): ToolbarAction[]
```

### `createBringToFrontAction`

Create action to bring node to front
Sets node z-index to a high value

```ts
function createBringToFrontAction(engine: DiagramEngine): ToolbarAction
```

### `createCompactPreset`

Compact Preset
Minimal vertical toolbar for tight spaces

```ts
function createCompactPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createContextMenuPreset`

Context Menu Preset
Right-click context menu style

```ts
function createContextMenuPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createDefaultLinkActions`

The two built-ins, in the order they read best on the toolbar.

```ts
function createDefaultLinkActions(engine: DiagramEngine): LinkToolbarAction[]
```

### `createDeleteAction`

Create standard delete action
Removes the node from the diagram

```ts
function createDeleteAction(engine: DiagramEngine): ToolbarAction
```

### `createDeleteLinkAction`

Delete the link. Routed through RemoveLinkCommand so it lands on the undo
stack (diagram.removeLink() alone is NOT undoable).

```ts
function createDeleteLinkAction(engine: DiagramEngine): LinkToolbarAction
```

### `createDuplicateAction`

Create standard duplicate action
Creates a copy of the node with the same type and data

```ts
function createDuplicateAction(engine: DiagramEngine): ToolbarAction
```

### `createEditAction`

Create standard edit action
Triggers a custom edit callback

```ts
function createEditAction(onEdit: (node: NodeModel) => void): ToolbarAction
```

### `createERDPreset`

ERD (Entity-Relationship Diagram) Preset
Optimized for database schema design

```ts
function createERDPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createFullPreset`

Full Preset
Complete set of actions including z-order manipulation

```ts
function createFullPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createInsertNodeAction`

Insert a node ON the edge: the link is split at the toolbar's anchor and the
new node is spliced in between the two halves.

```ts
function createInsertNodeAction(
  engine: DiagramEngine,
  options: InsertNodeOnEdgeOptions = {}
): LinkToolbarAction
```

### `createKanbanPreset`

Kanban Preset
Optimized for kanban board cards

```ts
function createKanbanPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createLockAction`

Create action to lock/unlock node
Toggles the locked state of the node

```ts
function createLockAction(): ToolbarAction
```

### `createMindMapPreset`

Mind Map Preset
Optimized for hierarchical mind mapping

```ts
function createMindMapPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createMinimalPreset`

Minimal Preset
Basic actions for simple diagrams

```ts
function createMinimalPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createSendToBackAction`

Create action to send node to back
Sets node z-index to 0 or minimum value

```ts
function createSendToBackAction(engine: DiagramEngine): ToolbarAction
```

### `createStandardActions`

Helper to create all standard actions
Returns an array of commonly used toolbar actions

```ts
function createStandardActions(
  engine: DiagramEngine,
  onEdit?: (node: NodeModel) => void
): ToolbarAction[]
```

### `createStandardPreset`

Standard Preset
Comprehensive set of actions for general-purpose diagrams

```ts
function createStandardPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `createWorkflowPreset`

Workflow Preset
Optimized for process flow diagrams

```ts
function createWorkflowPreset(engine: DiagramEngine, onEdit?: (node: any) => void): NodeToolbarConfig
```

### `getToolbarPreset`

Get a preset by name

```ts
function getToolbarPreset(
  name: ToolbarPresetName,
  engine: DiagramEngine,
  onEdit?: (node: any) => void
): NodeToolbarConfig
```

### `insertNodeOnEdge`

Split a link around a new node, as ONE undoable step.

The whole splice is wrapped in a MacroCommand — remove the old link, add the
node, add the two halves — so a single Ctrl+Z restores the original edge
exactly (MacroCommand undoes its steps in reverse).

MANUAL WAYPOINTS ARE RESPECTED: a hand-routed link keeps its shape. The
waypoints upstream of the split stay on the first half, the downstream ones
move to the second, and each half is re-flagged `hasManualWaypoints` only if
it actually inherited any (otherwise it auto-routes, as a fresh link should).

```ts
async function insertNodeOnEdge(
  engine: DiagramEngine,
  link: LinkModel,
  t: number,
  point: Point,
  tangent?: Point,
  options: InsertNodeOnEdgeOptions = {}
): Promise<{ nodeId: string; sourceLinkId: string; targetLinkId: string } | null>
```

**Returns** the ids of the created node and links, or null if the split was impossible.

### `pointAtFraction`

Arc-length interpolation along a polyline (NOT index interpolation).

```ts
function pointAtFraction(points: Point[], t: number): Point | null
```

### `polylineLength`

```ts
function polylineLength(points: Point[]): number
```

### `portSidesForTangent`

Which sides of the inserted node the two halves connect to, from the edge's
direction of travel: a rightward edge enters on the LEFT and leaves on the
RIGHT, a downward edge enters on TOP and leaves at the BOTTOM, etc.

```ts
function portSidesForTangent(tangent?: Point): {
  entry: 'left' | 'right' | 'top' | 'bottom';
  exit: 'left' | 'right' | 'top' | 'bottom';
}
```

### `splitPolylineAt`

Split a polyline at fraction `t`, keeping every interior vertex on the
correct side. This is what lets insert-node-on-edge RESPECT MANUAL
WAYPOINTS: the waypoints before the split stay on the upstream link, the
ones after it move to the downstream link.

```ts
function splitPolylineAt(
  points: Point[],
  t: number
): { before: Point[]; after: Point[]; point: Point } | null
```

### `tangentAtFraction`

Unit direction of travel at fraction `t`.

```ts
function tangentAtFraction(points: Point[], t: number): Point | null
```

<!-- source: grafloria-angular-components-interfaces.md -->

# Interfaces

Import these from `@grafloria/angular`.

## Interfaces

### `ClosestHit`

```ts
interface ClosestHit
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `t` | `number` |  | Fraction along the path, 0-1. |
| `point` | `Point` |  |  |
| `distance` | `number` |  |  |

### `GrafloriaCollabOptions`

The uniform collab contract every Grafloria wrapper shares.

```ts
interface GrafloriaCollabOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `transport` | `SyncTransport` |  |  |
| `actor` | `string` |  |  |
| `presence?` | `boolean \| BindPresenceOptions` |  | Live cursors + remote selection outlines. `true` for defaults. |

### `GrafloriaLayoutRequest`

Request shape for the declarative `[layout]` input / `applyLayout()`.

```ts
interface GrafloriaLayoutRequest
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Registry layout name: 'elk' \| 'dagre' \| 'force' \| 'tree' \| 'grid' \| 'auto' \| … |
| `options?` | `Record<string, unknown>` |  |  |

### `GrafloriaWidgetTemplateContext`

Template context for `<ng-template grafloriaWidget>` widget templates.

```ts
interface GrafloriaWidgetTemplateContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `$implicit` | `DashboardWidgetSpec` |  |  |
| `data` | `Record<string, unknown>` |  |  |

### `InsertNodeOnEdgeOptions`

```ts
interface InsertNodeOnEdgeOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeType?` | `string` |  | Type of the node dropped onto the edge (default `'basic'`). |
| `size?` | `{ width: number; height: number }` |  | Size of the inserted node (default 100×50). |
| `data?` | `Record<string, any>` |  | Seed data/label for the new node. |
| `label?` | `string` |  | Label written to the node's `label` metadata (what most shapes render). |
| `configure?` | `(node: NodeModel) => void` |  | Hook to customise the node before it is committed (set style, ports, …). |

### `LinkActionContext`

Card B — what a link-toolbar button is handed.

Unlike a node action (which only needs the node), an edge action needs to
know WHERE on the edge it was invoked: "insert node here" is meaningless
without the split point.

```ts
interface LinkActionContext
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  |  |
| `engine` | `DiagramEngine` |  |  |
| `t` | `number` |  | Fraction along the RENDERED path where the toolbar sits (0-1). |
| `point` | `Point` |  | World-space point at `t` — i.e. exactly under the button the user pressed. |
| `tangent?` | `Point` |  | Unit direction of travel at `t`; decides which sides an inserted node connects on. |

### `LinkToolbarAction`

Mirrors node-toolbar's ToolbarAction, retyped around LinkActionContext. (Same shape, same rendering contract, same keyboard handling.)

```ts
interface LinkToolbarAction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |
| `icon?` | `string` |  |  |
| `tooltip?` | `string` |  |  |
| `disabled?` | `boolean` |  |  |
| `hidden?` | `boolean` |  |  |
| `visible?` | `(ctx: LinkActionContext) => boolean` |  |  |
| `onClick` | `(ctx: LinkActionContext) => void` |  |  |
| `group?` | `string` |  |  |
| `shortcut?` | `string` |  |  |

### `NodeToolbarConfig`

Comprehensive configuration object for NodeToolbar

```ts
interface NodeToolbarConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position?` | `ToolbarPosition` |  |  |
| `alignment?` | `ToolbarAlignment` |  |  |
| `offset?` | `number` |  |  |
| `actions?` | `ToolbarAction[]` |  |  |
| `actionGroups?` | `ToolbarActionGroup[]` |  |  |
| `template?` | `TemplateRef<any>` |  |  |
| `style?` | `ToolbarStyleConfig` |  |  |
| `animation?` | `ToolbarAnimationConfig` |  |  |
| `behavior?` | `ToolbarBehaviorConfig` |  |  |
| `ariaLabel?` | `string` |  |  |
| `positioningStrategy?` | `PositioningStrategy` |  |  |

### `Point`

```ts
interface Point
```

**Properties**

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

### `PropertyPanelChangeEvent`

Property panel change event (UI-level event).

```ts
interface PropertyPanelChangeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `PropertyDiagramNode[]` |  |  |
| `property` | `string` |  |  |
| `value` | `any` |  |  |

### `SaveEvent`

Save event.

```ts
interface SaveEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `PropertyDiagramNode[]` |  |  |
| `changes` | `Record<string, any>` |  |  |

### `ToolbarAction`

```ts
interface ToolbarAction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |
| `icon?` | `string` |  |  |
| `tooltip?` | `string` |  |  |
| `disabled?` | `boolean` |  |  |
| `hidden?` | `boolean` |  |  |
| `visible?` | `(node: NodeModel) => boolean` |  |  |
| `onClick` | `(node: NodeModel) => void` |  |  |
| `group?` | `string` |  |  |
| `shortcut?` | `string` |  |  |

### `ToolbarActionGroup`

Toolbar Action Group
Organizes actions into logical groups with visual separators

```ts
interface ToolbarActionGroup
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label?` | `string` |  |  |
| `actions` | `ToolbarAction[]` |  |  |
| `separator?` | `'before' \| 'after' \| 'both' \| 'none'` |  |  |

### `ToolbarAnimationConfig`

```ts
interface ToolbarAnimationConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled?` | `boolean` |  |  |
| `duration?` | `string` |  |  |
| `easing?` | `string` |  |  |
| `preset?` | `AnimationPreset` |  |  |

### `ToolbarBehaviorConfig`

```ts
interface ToolbarBehaviorConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoHide?` | `boolean` |  |  |
| `closeOnClickOutside?` | `boolean` |  |  |
| `followNode?` | `boolean` |  |  |
| `enableKeyboardNav?` | `boolean` |  |  |
| `hideOnMultiSelect?` | `boolean` |  |  |
| `showAs?` | `'toolbar' \| 'contextMenu' \| 'both'` |  |  |
| `contextMenuTrigger?` | `'rightClick' \| 'longPress' \| 'both'` |  |  |

### `ToolbarConfig`

```ts
interface ToolbarConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position?` | `ToolbarPosition` |  |  |
| `alignment?` | `ToolbarAlignment` |  |  |
| `actions?` | `ToolbarAction[]` |  |  |
| `template?` | `TemplateRef<any>` |  |  |
| `offset?` | `number` |  |  |
| `canvasElement?` | `HTMLElement` |  |  |
| `viewport?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `zoom?` | `number` |  |  |
| `behavior?` | `ToolbarBehaviorConfig` |  |  |
| `style?` | `ToolbarStyleConfig` |  |  |

### `ToolbarStyleConfig`

```ts
interface ToolbarStyleConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `backgroundColor?` | `string` |  |  |
| `borderColor?` | `string` |  |  |
| `borderRadius?` | `string` |  |  |
| `boxShadow?` | `string` |  |  |
| `padding?` | `string` |  |  |
| `zIndex?` | `number` |  |  |
| `transitionDuration?` | `string` |  |  |

### `ValidationErrorEvent`

Validation error event.

```ts
interface ValidationErrorEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `property` | `string` |  |  |
| `errors` | `string[]` |  |  |

<!-- source: grafloria-angular-components-types.md -->

# Types

Import these from `@grafloria/angular`.

## Types

### `AnimationPreset`

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

Animation preset

```ts
type AnimationPreset = 'none' | 'fade' | 'slide' | 'scale' | 'bounce';
```

### `EffectiveToolbarConfig`

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

Effective configuration type with all required properties except template

```ts
type EffectiveToolbarConfig = Required<Omit<NodeToolbarConfig, 'template'>> & { template?: TemplateRef<any> };
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `template?` | `TemplateRef<any>` |  |  |

### `PositioningStrategy`

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

Positioning strategy
- auto: Smart positioning with boundary detection (default)
- fixed: Fixed position relative to node, no boundary detection
- follow: Follow node in real-time as it moves
- sticky: Stick to viewport edge when node scrolls off-screen

```ts
type PositioningStrategy = 'auto' | 'fixed' | 'follow' | 'sticky';
```

### `ToolbarAlignment`

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

```ts
type ToolbarAlignment = 'start' | 'center' | 'end';
```

### `ToolbarPosition`

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

```ts
type ToolbarPosition = 'top' | 'bottom' | 'left' | 'right';
```

### `ToolbarPresetName`

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

```ts
type ToolbarPresetName = keyof typeof TOOLBAR_PRESETS;
```

<!-- source: grafloria-angular-components-diagramcanvascomponent.md -->

# DiagramCanvasComponent

Import it from `@grafloria/angular`.

DiagramCanvasComponent

Standalone, OnPush, **signal-based** Angular canvas over the framework-agnostic
`SVGRenderer` + engine. A thin shell on purpose: every decision it makes is
delegated down into `@grafloria/renderer` (`InteractionController`, `SVGRenderer`,
`applyNodes`/`applyEdges`) or `@grafloria/engine` (commands, `IncrementalCapture`).

Inputs are `input()` / `model()` signals, outputs are `output()`: **no NgZone
dependency, no EventEmitter**, so the component runs under
`provideZonelessChangeDetection()`. Everything the *template* binds is a signal
(`marquee`, `htmlNodes`, `htmlLayerTransform`, `linkToolbarTarget`) — that is
what lets the zoneless scheduler see a change with no zone tick. The SVG layer
is painted imperatively (VNode → DOM patcher) and never went through change
detection at all.

`viewport` and `zoom` are `model()` signals because the canvas WRITES them (pan,
cursor-anchored zoom, fit-to-content), so `[(zoom)]` / `[(viewport)]` round-trip. `zoomChanged` / `viewportChanged` are kept alongside for backwards compatibility
(`viewportChanged` emits the VISIBLE world rect — the viewBox — whereas the
`model`'s `viewportChange` emits the camera rect the `viewport` input IS).

Two modes, both supported:

- **Uncontrolled (legacy):** bind `[engine]` and mutate the engine yourself. Unchanged behaviour.
- **Controlled:** bind `[(nodes)]` / `[(edges)]` — the same `NodeSpec` /
  `EdgeSpec` data the React wrapper and `<grafloria-flow>` take. They are reconciled
  against the live model by `applyNodes` / `applyEdges` **from `@grafloria/renderer`**
  (the shared reconciler — Angular does not get a second diff algorithm), and
  model mutations come back out as `nodesChange` / `edgesChange` (the next array
  — Angular's two-way contract) plus `modelChange` (a `DiagramIncremental`:
  precisely which entities were added / removed / modified — GoJS's
  `IncrementalData`). `[skipModelUpdate]="true"` suspends the inbound half
  (GoJS's `skipsDiagramUpdate`).

```ts
@Component({
    selector: 'grafloria-diagram-canvas',
    imports: [CommonModule, HtmlNodeRendererDirective, GrafloriaHandleDirective, LinkToolbarComponent],
    templateUrl: './diagram-canvas.component.html',
    styleUrls: ['./diagram-canvas.component.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DiagramCanvasComponent implements AfterViewInit, OnDestroy
```

Use it as `<grafloria-diagram-canvas>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine?` | `DiagramEngine \| undefined` |  | Diagram engine instance. Optional: in controlled mode (`nodes`/`edges` bound) |
| `nodes?` | `readonly (NodeSpec \| NodeModel)[] \| undefined` |  | Controlled node data — the shared `NodeSpec` shape. `undefined` = Two-way: also emits its change. |
| `edges?` | `readonly (EdgeSpec \| LinkModel)[] \| undefined` |  | Controlled edge data. Two-way: `[(edges)]`. Two-way: also emits its change. |
| `skipModelUpdate?` |  |  | Suspend the INBOUND half of the controlled binding (GoJS's |
| `viewport?` | `Rectangle` |  | Camera rectangle. Two-way: `[(viewport)]` (the canvas pans/zooms it). Two-way: also emits its change. |
| `zoom?` |  |  | Zoom level. Two-way: `[(zoom)]` (the canvas writes it on wheel/fit/keys). Two-way: also emits its change. |
| `theme?` | `Theme \| undefined` |  | Theme configuration. |
| `collab?` | `GrafloriaCollabOptions \| undefined` |  | Real-time collaboration: a transport (BroadcastChannelTransport, |
| `comments?` | `boolean \| CommentStore \| undefined` |  | Anchored comment threads. `true` creates a store (viewer 'local'); pass a |
| `plugins?` | `boolean \| CanvasPluginOptions \| undefined` |  | `[plugins]="true"` mounts minimap + zoom/fit controls + background grid |
| `layout?` | `string \| GrafloriaLayoutRequest \| undefined` |  | Declarative auto-layout: `[layout]="'elk'"` or |
| `colorMode?` | `ColorMode \| undefined` |  | Card "colorMode". |
| `themes?` | `ThemeSet \| undefined` |  | The themes `colorMode` chooses between. Defaults to the built-in set. |
| `tokenBridge?` | `TokenBridge \| undefined` |  | Card "design-token bridge". |
| `rendererConfig?` | `Partial<SVGRendererConfig>` |  | Extra SVGRenderer options (e.g. smartConnectionPoints, linkHitAreaWidth). Merged over the component defaults; changing it recreates the renderer. |
| `enableMouseWheelZoom?` |  |  | Enable ctrl/⌘ + wheel zoom. |
| `enablePan?` |  |  | Enable pan (middle-drag, space-drag, wheel-scroll). |
| `zoomSensitivity?` |  |  | Relative zoom step per wheel notch / keyboard zoom. |
| `minZoom?` |  |  | Minimum zoom level. |
| `maxZoom?` |  |  | Maximum zoom level. |
| `enableLinkToolbar?` |  |  | Show the floating edge toolbar on link hover/selection. |
| `linkToolbarActions?` | `LinkToolbarAction[] \| undefined` |  | Buttons on the edge toolbar. Defaults to delete + insert-node-on-edge. |
| `linkToolbarAnchor?` |  |  | Fraction along the link the toolbar is glued to (0.5 = midpoint). |
| `enableSelectionTools?` |  |  | Resize/rotate handles, Halo, link endpoint + vertex tools. |
| `enableSnapping?` |  |  | Alignment snaplines, equal spacing, grid snap, keep-in-bounds. |
| `enableProximityConnect?` |  |  | Drop a node near a compatible port → auto-link it. |
| `enableKeyboardNavigation?` |  |  | Tab/arrow focus, nudge, keyboard connect, ARIA announcements. |
| `canvasBounds?` | `Rectangle \| null` |  | Keep-in-bounds for dragging. A signal input, not |
| `enableInPlaceEditing?` |  |  | Double-click a node to edit its label in place. |
| `highlighterConfig?` | `boolean \| Partial<HighlighterConfig>` |  | Hover / selection / validation / connect-target overlay decorations (the |

**Outputs**

- `nodesChange`
- `edgesChange`
- `viewportChange`
- `zoomChange`
- `collabReady` — The live SyncAdapter, right after `join()`.
- `layoutDone` — Fires after each declarative or imperative layout completes.
- `viewportChanged` — The VISIBLE world rect (the SVG viewBox) after a pan/zoom. NOT the same as the
- `zoomChanged` — Zoom after a pan/zoom gesture. (`zoomChange` is the two-way twin.)
- `modelChange` — The incremental patch describing what the MODEL just changed — added /

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` |  |  | Diagram engine instance. Optional: in controlled mode (`nodes`/`edges` bound) the canvas creates and owns one if you do not supply it. |
| `nodes` |  |  | Controlled node data — the shared `NodeSpec` shape. `undefined` = uncontrolled: the engine's node set is left alone. Two-way: `[(nodes)]`. |
| `edges` |  |  | Controlled edge data. Two-way: `[(edges)]`. |
| `skipModelUpdate` |  |  | Suspend the INBOUND half of the controlled binding (GoJS's `skipsDiagramUpdate`): incoming `nodes`/`edges` are not pushed into the model while this is true. Flipping it back to false re-syncs immediately. Outbound emissions are unaffected. |
| `viewport` |  |  | Camera rectangle. Two-way: `[(viewport)]` (the canvas pans/zooms it). |
| `zoom` |  |  | Zoom level. Two-way: `[(zoom)]` (the canvas writes it on wheel/fit/keys). |
| `theme` |  |  | Theme configuration. |
| `effectiveTheme` |  |  | The theme the canvas actually renders with (see `theme` for precedence). |
| `nodeDefMap` |  |  | type → template; '' is the wildcard fallback for HTML-layer nodes. |
| `collab` |  |  | Real-time collaboration: a transport (BroadcastChannelTransport, WebSocketTransport, MemoryTransport, …) + actor id — the canvas joins a CRDT sync session once the diagram exists and leaves on destroy. Fixed for the life of the canvas. |
| `collabReady` |  |  | The live SyncAdapter, right after `join()`. |
| `comments` |  |  | Anchored comment threads. `true` creates a store (viewer 'local'); pass a `CommentStore` to share one. Pins render inside the SVG via the overlay. |
| `plugins` |  |  | `[plugins]="true"` mounts minimap + zoom/fit controls + background grid with defaults; an object picks and configures them. The plugins drive and follow the SAME camera as `[(zoom)]`/`[(viewport)]` via a persistent two-way-synced ViewportController. |
| `layout` |  |  | Declarative auto-layout: `[layout]="'elk'"` or `[layout]="{ name: 'auto', options: { spacing: 60 } }"` — any name in the engine's layout registry (elk, dagre, force, tree, grid, auto, …). |
| `layoutDone` |  |  | Fires after each declarative or imperative layout completes. |
| `colorMode` |  |  | Card "colorMode". |
| `themes` |  |  | The themes `colorMode` chooses between. Defaults to the built-in set. |
| `tokenBridge` |  |  | Card "design-token bridge". |
| `rendererConfig` |  |  | Extra SVGRenderer options (e.g. smartConnectionPoints, linkHitAreaWidth). Merged over the component defaults; changing it recreates the renderer. |
| `enableMouseWheelZoom` |  |  | Enable ctrl/⌘ + wheel zoom. |
| `enablePan` |  |  | Enable pan (middle-drag, space-drag, wheel-scroll). |
| `zoomSensitivity` |  |  | Relative zoom step per wheel notch / keyboard zoom. |
| `minZoom` |  |  | Minimum zoom level. |
| `maxZoom` |  |  | Maximum zoom level. |
| `viewportChanged` |  |  | The VISIBLE world rect (the SVG viewBox) after a pan/zoom. NOT the same as the `viewport` model's `viewportChange`, which emits the camera rect. |
| `zoomChanged` |  |  | Zoom after a pan/zoom gesture. (`zoomChange` is the two-way twin.) |
| `modelChange` |  |  | The incremental patch describing what the MODEL just changed — added / removed / modified nodes, links and groups (GoJS `IncrementalData`). Produced by the engine's `IncrementalCapture`, so it replays exactly. Emitted for engine-originated changes only: a change you pushed in through `[nodes]` / `[edges]` is not echoed back at you. |
| `activeEngine` |  |  | The engine actually in use: the bound one, else the one we own. |
| `enableLinkToolbar` |  |  | Show the floating edge toolbar on link hover/selection. |
| `linkToolbarActions` |  |  | Buttons on the edge toolbar. Defaults to delete + insert-node-on-edge. |
| `linkToolbarAnchor` |  |  | Fraction along the link the toolbar is glued to (0.5 = midpoint). |
| `linkToolbarTarget` |  |  | Link the edge toolbar is currently attached to (null = no toolbar). |
| `enableSelectionTools` |  |  | Resize/rotate handles, Halo, link endpoint + vertex tools. |
| `enableSnapping` |  |  | Alignment snaplines, equal spacing, grid snap, keep-in-bounds. |
| `enableProximityConnect` |  |  | Drop a node near a compatible port → auto-link it. |
| `enableKeyboardNavigation` |  |  | Tab/arrow focus, nudge, keyboard connect, ARIA announcements. |
| `canvasBounds` |  |  | Keep-in-bounds for dragging. A signal input, not |
| `enableInPlaceEditing` |  |  | Double-click a node to edit its label in place. |
| `highlighterConfig` |  |  | Hover / selection / validation / connect-target overlay decorations (the `.grafloria-highlighter-*` layer). `false` hides all kinds — no host CSS required. `true` (default) shows all. Pass a partial {@link HighlighterConfig} to toggle individual kinds or padding. |
| `toolLayer` | `SelectionToolLayer` |  | Live tool layer for the current selection (template-bound). |
| `highlighters` | `Highlighter[]` | `[]` | Hover / selection / validation / drop-target decorations (template-bound). |
| `alignmentGuides` | `AlignmentGuide[]` | `[]` | Live alignment snaplines + equal-spacing guides during a drag/resize. |
| `spacingGuides` | `SpacingGuide[]` | `[]` |  |
| `focusRing` | `FocusRing \| null` | `null` | The visible focus ring (keyboard focus ≠ selection). |
| `liveMessage` |  | `''` | Text of the ARIA live region. |
| `livePoliteness` | `'polite' \| 'assertive'` | `'polite'` |  |
| `containerRef` | `ElementRef<HTMLDivElement>` |  | Main container reference |
| `svgLayerRef` | `ElementRef<HTMLDivElement>` |  | SVG layer reference |
| `htmlLayerRef` | `ElementRef<HTMLDivElement>` |  | HTML layer reference |
| `marquee` |  |  | Live marquee overlay rectangle in SCREEN px (relative to the container), or null when no marquee is active. Bound by the template's SVG overlay. |
| `htmlLayerTransform` |  |  | HTML layer transform Synced with viewport to keep HTML nodes aligned with SVG |
| `htmlNodes` |  |  | HTML nodes to render (DECLARATIVE APPROACH - React Flow style) Exposed as a public property for template binding |

**Methods**

- `nodeTemplateFor(node: any): TemplateRef<GrafloriaNodeTemplateContext> | null`
- `nodeTemplateContext(node: any): GrafloriaNodeTemplateContext`
- `getCommentStore(): CommentStore | null` — The live comment store, when `[comments]` is enabled.
- `viewportController(): ViewportController | undefined` — The live viewport controller — the world↔screen transform this canvas is
painting with. Use it to anchor HTML overlays (floating toolbars, badges,
callouts) to world coordinates: `viewportController().worldToClient(x, y,
hostRect)` returns client pixels, and `onChange` fires on every pan/zoom so
the overlay can re-anchor. Same instance the minimap/controls plugins drive,
so overlays and plugins stay in lockstep. Returns undefined only before the
view initialises.
- `async applyLayout(request?: string | GrafloriaLayoutRequest): Promise<unknown | undefined>` — Re-run the bound layout, or run any registry layout imperatively.
- `exportDiagram(format: 'svg' | 'png' | 'jpeg' | 'webp' | 'pdf' = 'svg', options: any = {}): Promise<string>` — Async export — the full pipeline, including async custom-node capture.
- `exportSvg(options: any = {}): any` — Synchronous SVG string export.
- `exportPdf(options: any = {}): any` — Synchronous vector-PDF export.
- `snapshot(): SerializedDiagram | null` — Serialize the current diagram — feed the result back to `loadSnapshot`.
- `loadSnapshot(data: SerializedDiagram): void` — Restore a `snapshot()`-ed document by reconciling INTO the live diagram —
`applyNodes`/`applyEdges` are full reconcilers, so removals happen and the
renderer, listeners, and plugins stay attached to the same model.
- `exportText(options?: unknown): string` — Mermaid-compatible text export (lossless sidecar by default).
- `loadText(text: string, options?: unknown): unknown` — Parse Mermaid-compatible text (sidecar-aware) and reconcile it into the
live diagram — same mechanics as `loadSnapshot`.
- `get effectiveLinkToolbarActions(): LinkToolbarAction[]`
- `onLinkToolbarPointerOver(isOver: boolean): void`
- `constructor()`
- `ngAfterViewInit(): void`
- `ngOnDestroy(): void`
- `flushModelChange(): void` — Force the pending outbound emission to happen NOW (tests, imperative hosts).
- `get overlayViewBox(): string` — viewBox for the world-space overlay <svg> — identical to the renderer's.
- `get overlayStroke(): number` — Stroke width that stays 1 CSS px in a world-space overlay.
- `handleSide(handle: ToolHandle): number` — Square side of a tool handle in world units (constant on screen).
- `get overlayFontSize(): number` — Font size for overlay glyphs/labels, constant on screen.
- `toolGlyph(handle: ToolHandle): string` — Glyph drawn inside a click-tool button.
- `get toolFrameTransform(): string | null` — SVG transform that rotates the selection frame with a rotated node.
- `highlighterTransform(h: Highlighter): string | null` — Rotation transform for one highlighter box (rotated nodes).
- `pointsAttr(points?: Point[]): string` — Polyline `points` attribute for a link highlighter / focus ring.
- `spacingLabelX(segment: { x1: number; x2: number }): number` — Midpoint of a spacing segment (where its distance label is drawn).
- `spacingLabelY(segment: { y1: number; y2: number }): number`
- `undo(): Promise<void>` — Undo the last command (Ctrl/Cmd+Z).
- `redo(): Promise<void>` — Redo the last undone command (Ctrl/Cmd+Shift+Z or Ctrl+Y).
- `copySelection(): Promise<void>` — Copy the selection to the clipboard (Ctrl/Cmd+C).
- `cutSelection(): Promise<void>` — Cut the selection: clipboard + delete, as ONE undo step (Ctrl/Cmd+X).
- `deleteSelection(): Promise<void>` — Delete the selection as ONE undo step (Delete / Backspace).
- `pasteClipboard(): Promise<void>` — Paste the clipboard, dropping it under the cursor (Ctrl/Cmd+V).

PasteCommand's `offset` is a DELTA added to every pasted node's stored
position, so "paste at the cursor" = cursor − centre of the copied bbox. With
no known cursor (never moved over the canvas) we fall back to a small nudge so
repeated pastes still stack visibly instead of landing on top of the source.

The pasted link endpoints stay valid because PasteCommand re-ids every port
via remapNodePortIds() and remaps the links through that map (verified by
CutCommand.spec + ClipboardCommands.spec).
- `scheduleRender(): void` — The ONE coalescing entry point for every re-render.

Marks the canvas dirty and queues a SINGLE requestAnimationFrame. Any
number of scheduleRender() calls in the same tick collapse into one frame,
so a burst of engine events (node:changed ×N, a drag's mousemoves, several
- `getPerformanceMetrics(): { fps: number; frameTime: number; droppedFrames: number; sampleCount: number; }` — Real render-loop metrics, computed from the ring buffers
(replaces any hardcoded/estimated FPS).
- fps:          rolling frames-per-second across the last N painted frames
- frameTime:    average render duration (ms) over the same window
- droppedFrames: cumulative frames whose render blew the ~60fps budget
- sampleCount:  number of frames currently in the window
- `@HostListener('window:keyup', ['$event']) onKeyUp(event: KeyboardEvent): void` — Handle keyup to exit pan mode (Space key)
- `@HostListener('wheel', ['$event']) onWheel(event: WheelEvent): void` — Wheel: ctrl/⌘ (and trackpad pinch, which the browser reports as ctrl+wheel)
ZOOMS at the cursor; a plain wheel SCROLLS the canvas (shift → horizontal). This is the Figma/Miro/VS Code convention — the previous behaviour zoomed on
every wheel event around the viewport CENTRE, which is the "feels wrong"
competitors were compared against.
- `zoomAtClient(targetZoom: number, clientX: number, clientY: number): void` — Zoom to `targetZoom` keeping the world point under (clientX, clientY) pinned
to that same screen pixel.

DERIVATION against the center-anchored convention (see the block above
calculateActualViewport). With `s` the cursor's screen offset from the canvas'
LEFT edge, `W` the canvas px width and `c = viewport.x + W/2` the world-space
centre (which is what the viewBox is anchored on):

world(s) = c + (s − W/2) / zoom

Pinning world(s) across z0 → z1 means solving for the new centre c₁:

c₁ = world − (s − W/2) / z₁
  ⇒ viewport.x₁ = world − (s − W/2)/z₁ − W/2

(`W` does not change with zoom, so the centre is the only free variable.)
Zooming at the exact canvas centre leaves viewport.x/y untouched — which is
precisely the old behaviour, now a special case rather than the only one.
- `zoomBy(factor: number): void` — Zoom keeping the canvas centre fixed (keyboard zoom, toolbar buttons).
- `zoomIn(): void` — Ctrl/⌘ + '='
- `zoomOut(): void` — Ctrl/⌘ + '-'
- `resetZoom(): void` — Ctrl/⌘ + '0' — back to 100%, canvas centre unchanged.
- `fitToContent(padding = 40): void` — Fit every node in the diagram into view (Shift+1). Picks the largest zoom (within [minZoom, maxZoom]) at which the content's
bounding box fits inside the canvas with `padding` screen px to spare, then
centres the viewport on that box.
- `zoomToSelection(padding = 40): void` — Fit the CURRENT SELECTION into view (Shift+2); falls back to everything.
- `@HostListener('pointerdown', ['$event']) onPointerDown(event: PointerEvent): void` — Pointer events — the primary pipeline (mouse, pen AND touch), mirroring
DomEventBinder.onPointerDown/Move/Up/Cancel. Touch forks to the shared
gesture controller; mouse/pen falls through to the existing ladder
(a PointerEvent IS a MouseEvent, so the methods take it as-is).
- `@HostListener('pointermove', ['$event']) onPointerMove(event: PointerEvent): void`
- `@HostListener('pointerup', ['$event']) onPointerUp(event: PointerEvent): void`
- `@HostListener('pointercancel', ['$event']) onPointerCancel(event: PointerEvent): void`
- `@HostListener('contextmenu', ['$event']) onContextMenu(event: MouseEvent): void` — The native context menu: on touch the long-press already produced our own
gesture, so the OS menu would sit on top of the canvas mid-interaction.
- `@HostListener('mousedown', ['$event']) onCompatMouseDown(event: MouseEvent): void`
- `@HostListener('mousemove', ['$event']) onCompatMouseMove(event: MouseEvent): void`
- `@HostListener('mouseup', ['$event']) onCompatMouseUp(event: MouseEvent): void`
- `onMouseDown(event: MouseEvent): void` — Handle mouse down for panning and node selection
Supports:
- Left click: Select/drag nodes
- Ctrl + Left click: Multi-select
- Middle mouse button: Pan
- Space + Left click: Pan
- `onMouseMove(event: MouseEvent): void` — Handle mouse move for panning, node dragging, and hover
- `onMouseUp(event: MouseEvent): void` — Handle mouse up to stop panning, node dragging, and connections
- `@HostListener('mouseleave') onCompatMouseLeave(): void` — mouseleave stays UN-gated on `sawPointerEvent` (mirrors DomEventBinder: its
cleanup is idempotent and there is no pointerleave twin wired), but it must
never abort a live TOUCH gesture — the touch resize path drives the SAME
SelectionToolsController this handler cancels.
- `onMouseLeave(): void` — Handle mouse leave to stop panning and node dragging
- `@HostListener('dblclick', ['$event']) onDoubleClick(event: MouseEvent): void` — Double-click on a link.
- On a label: open an inline text editor in place.
- On the link body: insert a waypoint at the double-clicked point.
- `worldToScreen(worldX: number, worldY: number): { screenX: number; screenY: number }` — Inverse of {@link clientToWorld}: world → canvas-local screen px. Exposed (public) because it is the invariant the cursor-anchored zoom is
defined by, and the zoom tests assert on it.
- `@HostListener('window:keydown', ['$event']) onKeyDown(event: KeyboardEvent): void` — Handle keyboard events (Option 1: Node Interaction)
- Space: Pan mode cursor
- Delete/Backspace: Delete selection (undoable)
- Escape: Clear selection
- Ctrl+A: Select all

- Ctrl/⌘+Z undo, Ctrl/⌘+Shift+Z or Ctrl+Y redo
- Ctrl/⌘+X / +C / +V cut / copy / paste-at-cursor
- Ctrl/⌘ +'=' / '-' / '0' zoom in / out / reset; Shift+1 fit, Shift+2 fit selection
- `getAbsoluteX(node: any): number` — Get absolute X position for a node (including parent offset and transforms)
CRITICAL FIX: Use getWorldPosition() for simple cases, getGlobalPosition() for transforms
This properly handles rotation, scale, and nested hierarchies
- `getAbsoluteY(node: any): number` — Get absolute Y position for a node (including parent offset and transforms)
CRITICAL FIX: Use getWorldPosition() for simple cases, getGlobalPosition() for transforms
This properly handles rotation, scale, and nested hierarchies
- `getNodeX(node: any): number` — Get node X position for HTML rendering — in WORLD units.

The HTML layer's transform is
`translate(−viewBox.origin·zoom) scale(zoom)`, so a child positioned at its
world coordinate lands at (world − origin)·zoom — byte-for-byte the SVG map. The old `/ zoom` cancelled the layer's scale, which pinned HTML nodes to a
zoom-independent offset while the SVG around them scaled: the desync.
- `getNodeY(node: any): number` — Get node Y position for HTML rendering — in WORLD units (see getNodeX).
- `shouldRenderPort(port: PortModel, node: NodeModel): boolean` — Check if a port should be rendered as an HTML handle
Respects port visibility settings and template configuration
- `getPortPosition(port: PortModel, node: NodeModel, axis: 'top' | 'left'): string` — Get port position CSS value for top or left
CRITICAL FIX: Use shape-aware positioning from getPortPositionForShape()
This ensures HTML ports align with SVG ports for all shape types

**Example**

```html
<!-- uncontrolled -->
<grafloria-diagram-canvas [engine]="engine" [(zoom)]="zoom" />

<!-- controlled -->
<grafloria-diagram-canvas
  [(nodes)]="nodes"
  [(edges)]="edges"
  (modelChange)="persist($event)" />
```

<!-- source: grafloria-angular-components-grafloriadashboardcomponent.md -->

# GrafloriaDashboardComponent

Import it from `@grafloria/angular`.

`<grafloria-dashboard>` — the dashboard kit, the Angular way.

The kit is DATA-FIRST: `[views]` (or `[widgets]` for a single unnamed view)
declare the whole board, the kit wires the pack grid, gestures, and undo. This component adds the Angular idioms on top:

```html
<grafloria-dashboard [views]="views" [(activeView)]="tab"
    (ready)="handle = $event" (layoutChange)="persist($event)">
  <ng-template grafloriaWidget="orders" let-data="data">…</ng-template>
</grafloria-dashboard>
```

`snapshot()` returns `toJSON()` — feed it back to `[views]`/`[options]` to
rebuild the identical board (the kit's round-trip contract).

```ts
@Component({
  selector: 'grafloria-dashboard',
  template: '',
  styles: [':host { display: block; position: relative; }'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GrafloriaDashboardComponent implements AfterViewInit, OnDestroy
```

Use it as `<grafloria-dashboard>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views?` | `DashboardViewSpec[] \| undefined` |  | Multi-view (tabbed) board. Mutually exclusive with `widgets`. |
| `widgets?` | `DashboardWidgetSpec[] \| undefined` |  | Single-view shorthand. |
| `options?` | `Partial<DashboardOptions>` |  | Board options: columns, gap, sizing, rtl, responsive, binder… |
| `activeView?` | `string \| undefined` |  | Two-way active view id — the tab pattern. Two-way: also emits its change. |
| `layout?` | `'grid' \| 'split' \| undefined` |  | LIVE SWITCHES — the toolbar toggles as inputs: applied at mount (over |
| `sizing?` | `'fit' \| 'grow' \| undefined` |  |  |
| `static?` | `boolean \| undefined` |  | Static board: the viewer's mode — no drag, no resize, no handles. |

**Outputs**

- `activeViewChange`
- `ready` — The typed DashboardHandle, once the board is live.
- `layoutChange` — Mirrors the kit's committed gestures (drag, resize, add, remove).

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `views` |  |  | Multi-view (tabbed) board. Mutually exclusive with `widgets`. |
| `widgets` |  |  | Single-view shorthand. |
| `options` |  |  | Board options: columns, gap, sizing, rtl, responsive, binder… |
| `activeView` |  |  | Two-way active view id — the tab pattern. |
| `layout` |  |  | LIVE SWITCHES — the toolbar toggles as inputs: applied at mount (over `[options]`) and, when they change, through the handle (`setLayout` / `setSizing` / `setStatic`), never by remounting. 'split' is the DevExpress splitter tree; 'grid' the cell grid. |
| `sizing` |  |  |  |
| `static` |  |  | Static board: the viewer's mode — no drag, no resize, no handles. |
| `ready` |  |  | The typed DashboardHandle, once the board is live. |
| `layoutChange` |  |  | Mirrors the kit's committed gestures (drag, resize, add, remove). |

**Methods**

- `constructor()`
- `ngAfterViewInit(): void`
- `getHandle(): DashboardHandle | undefined` — The live handle (undefined before the first paint).
- `snapshot(): DashboardSnapshot | null` — `toJSON()` — the whole board as plain data, ready to feed back in.
- `ngOnDestroy(): void`

<!-- source: grafloria-angular-components-interactionconfigpanelcomponent.md -->

# InteractionConfigPanelComponent

Import it from `@grafloria/angular`.

InteractionConfigPanelComponent

Configuration UI panel for interaction mode settings. Allows users to customize interaction behavior at runtime.

```ts
@Component({
    selector: 'grafloria-interaction-config-panel',
    imports: [CommonModule, FormsModule],
    templateUrl: './interaction-config-panel.component.html',
    styleUrls: ['./interaction-config-panel.component.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InteractionConfigPanelComponent implements OnInit, OnChanges
```

Use it as `<grafloria-interaction-config-panel>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine?` | `DiagramEngine` |  | Diagram engine instance (required) |
| `expanded?` |  |  | Whether the panel is expanded by default |
| `title?` |  |  | Panel title |
| `showAdvanced?` |  |  | Show advanced settings |

**Outputs**

- `configChanged` — Emit config changes

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `engine` | `DiagramEngine` |  | Diagram engine instance (required) |
| `expanded` |  | `false` | Whether the panel is expanded by default |
| `title` |  | `'Interaction Settings'` | Panel title |
| `showAdvanced` |  | `true` | Show advanced settings |
| `configChanged` |  |  | Emit config changes |
| `config` | `InteractionConfig` |  | Current configuration (local copy) |
| `isCollapsed` |  | `true` | Panel collapsed state |
| `isAdvancedCollapsed` |  | `true` | Advanced settings collapsed state |
| `interactionModes` |  |  | Interaction mode options |
| `portVisibilityOptions` |  |  | Port visibility options |
| `connectionLineStyles` |  |  | Connection line style options |

**Methods**

- `ngOnInit(): void`
- `ngOnChanges(changes: SimpleChanges): void`
- `loadConfig(): void` — Load current configuration from engine
- `toggleCollapse(): void` — Toggle panel collapsed state
- `toggleAdvanced(): void` — Toggle advanced settings collapsed state
- `onModeChange(mode: string): void` — Handle interaction mode change
- `onPortVisibilityChange(visibility: string): void` — Handle port visibility change
- `onConnectionLineStyleChange(style: string): void` — Handle connection line style change
- `onPortRadiusChange(radius: number): void` — Handle port radius change
- `onPortHoverScaleChange(scale: number): void` — Handle port hover scale factor change
- `onSnapRadiusChange(radius: number): void` — Handle snap radius change
- `onToggleChange(key: keyof InteractionConfig, value: boolean): void` — Handle toggle changes
- `resetToDefaults(): void` — Reset to default configuration
- `getModeDescription(): string` — Get description for current mode
- `getPortVisibilityDescription(): string` — Get description for current port visibility
- `getConnectionLineStyleDescription(): string` — Get description for current connection line style

**Example**

```html
<grafloria-interaction-config-panel
  [engine]="diagramEngine"
  [expanded]="true"
  (configChanged)="onConfigChange($event)">
</grafloria-interaction-config-panel>
```

<!-- source: grafloria-angular-components-linktoolbarcomponent.md -->

# LinkToolbarComponent

Import it from `@grafloria/angular`.

Card B — a floating, PATH-ANCHORED action layer.

Mirrors NodeToolbarComponent, but an edge has no bounding box to hang off:
it is anchored to a FRACTION along the link (default the midpoint) and lifted
off the stroke along the path NORMAL, so it never sits on top of the line it
acts on. It re-anchors itself whenever the route changes — pan, zoom, a node
drag that reroutes the edge, a waypoint edit.

Geometry comes from RenderedLinkPath (the drawn <path>, or the per-frame
point polyline), never from LinkModel.segments — see that file for why.

```ts
@Component({
  selector: 'grafloria-link-toolbar',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div
      #toolbar
      class="grafloria-link-toolbar"
      role="toolbar"
      [attr.aria-label]="ariaLabel"
      [attr.aria-hidden]="!isVisible"
      [attr.data-link-id]="link?.id"
      [class.visible]="isVisible"
      [class.animated]="animation?.enabled !== false"
      [style.transform]="transform"
      [style.opacity]="isVisible ? 1 : 0"
      [style.pointer-events]="isVisible ? 'all' : 'none'"
      [style.--toolbar-bg]="styleConfig?.backgroundColor"
      [style.--toolbar-border]="styleConfig?.borderColor"
      [style.--toolbar-radius]="styleConfig?.borderRadius"
      [style.--toolbar-shadow]="styleConfig?.boxShadow"
      [style.--toolbar-padding]="styleConfig?.padding"
      [style.--toolbar-z]="styleConfig?.zIndex"
      [style.--toolbar-transition]="animation?.duration || '0.15s'"
      (mouseenter)="onPointerEnter()"
      (mouseleave)="onPointerLeave()"
      (keydown)="handleKeyDown($event)"
    >
      @if (!customTemplate) {
        <div class="toolbar-content" role="group">
          @for (action of visibleActions; track action.id; let idx = $index) {
            <button
              type="button"
              class="toolbar-button"
              [attr.aria-label]="action.tooltip || action.label"
              [attr.aria-disabled]="action.disabled"
              [attr.data-action-id]="action.id"
              [attr.tabindex]="idx === focusedActionIndex ? 0 : -1"
              [disabled]="action.disabled"
              [title]="action.tooltip || action.label"
              (click)="handleActionClick(action, $event)"
              (focus)="focusedActionIndex = idx"
            >
              @if (action.icon) {
                <i [class]="action.icon" aria-hidden="true"></i>
              }
              <span>{{ action.label }}</span>
            </button>
          }
        </div>
      }

      @if (customTemplate) {
        <ng-container
          *ngTemplateOutlet="customTemplate; context: { $implicit: link, actions: visibleActions, context: actionContext }">
        </ng-container>
      }
    </div>
  `,
  styles: [`
    .grafloria-link-toolbar {
      position: absolute;
      top: 0;
      left: 0;
      display: flex;
      gap: 4px;
      background: var(--toolbar-bg, var(--grafloria-toolbar-bg, white));
      border: 1px solid var(--toolbar-border, var(--grafloria-toolbar-border, #e2e8f0));
      border-radius: var(--toolbar-radius, var(--grafloria-toolbar-radius, 8px));
      box-shadow: var(--toolbar-shadow, var(--grafloria-toolbar-shadow, 0 4px 6px rgba(0, 0, 0, 0.1)));
      padding: var(--toolbar-padding, var(--grafloria-toolbar-padding, 2px));
      z-index: var(--toolbar-z, var(--grafloria-toolbar-z, 1000));
      outline: none;
      white-space: nowrap;
    }

    .grafloria-link-toolbar.animated {
      transition: opacity var(--toolbar-transition, 0.15s) ease;
    }

    .grafloria-link-toolbar:focus-within {
      outline: 2px solid var(--grafloria-focus-color, #667eea);
      outline-offset: 2px;
    }

    .toolbar-content {
      display: flex;
      gap: 2px;
    }

    .toolbar-button {
      display: flex;
      align-items: center;
      gap: 4px;
      padding: 4px 8px;
      background: transparent;
      border: none;
      border-radius: 4px;
      cursor: pointer;
      font-size: 12px;
      line-height: 1.4;
      color: var(--grafloria-toolbar-text, #334155);
      transition: background-color 0.15s ease;
      white-space: nowrap;
    }

    .toolbar-button:hover:not(:disabled) {
      background: var(--grafloria-toolbar-hover, #f1f5f9);
    }

    .toolbar-button:active:not(:disabled) {
      background: var(--grafloria-toolbar-active, #e2e8f0);
    }

    .toolbar-button:focus {
      outline: 2px solid var(--grafloria-focus-color, #667eea);
      outline-offset: -2px;
    }

    .toolbar-button:disabled,
    …
```

Use it as `<grafloria-link-toolbar>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link?` | `LinkModel` |  | The link this toolbar acts on. |
| `engine?` | `DiagramEngine` |  |  |
| `canvasElement?` | `HTMLElement` |  | Canvas container the toolbar is positioned inside (and measured against). |
| `viewport?` | `{ x: number; y: number; width: number; height: number }` |  | Same viewport/zoom the canvas renders with — the screen-space fallback. |
| `zoom?` |  |  |  |
| `anchor?` |  |  | Fraction along the path to glue the toolbar to (0 = source, 1 = target). |
| `offset?` |  |  | Screen-px lift along the path normal, so the buttons clear the stroke. |
| `actions?` | `LinkToolbarAction[]` |  |  |
| `customTemplate?` | `TemplateRef<any>` |  |  |
| `visible?` |  |  |  |
| `styleConfig?` | `ToolbarStyleConfig` |  |  |
| `animation?` | `ToolbarAnimationConfig` |  |  |
| `ariaLabel?` |  |  |  |

**Outputs**

- `actionClicked`
- `positionUpdated`
- `pointerOverChange` — Emits while the pointer is over the toolbar — lets the host keep it alive

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `link` | `LinkModel` |  | The link this toolbar acts on. |
| `engine` | `DiagramEngine` |  |  |
| `canvasElement?` | `HTMLElement` |  | Canvas container the toolbar is positioned inside (and measured against). |
| `viewport` | `{ x: number; y: number; width: number; height: number }` |  | Same viewport/zoom the canvas renders with — the screen-space fallback. |
| `zoom` |  | `1.0` |  |
| `anchor` |  | `0.5` | Fraction along the path to glue the toolbar to (0 = source, 1 = target). |
| `offset` |  | `22` | Screen-px lift along the path normal, so the buttons clear the stroke. |
| `actions` | `LinkToolbarAction[]` | `[]` |  |
| `customTemplate?` | `TemplateRef<any>` |  |  |
| `visible` |  | `true` |  |
| `styleConfig?` | `ToolbarStyleConfig` |  |  |
| `animation?` | `ToolbarAnimationConfig` |  |  |
| `ariaLabel` |  | `'Link actions'` |  |
| `actionClicked` |  |  |  |
| `positionUpdated` |  |  |  |
| `pointerOverChange` |  |  | Emits while the pointer is over the toolbar — lets the host keep it alive when the pointer leaves the link itself to reach for a button. |
| `toolbarRef?` | `ElementRef<HTMLDivElement>` |  |  |
| `isVisible` |  | `false` |  |
| `transform` |  | `''` |  |
| `focusedActionIndex` |  | `0` |  |

**Methods**

- `constructor(private cdr: ChangeDetectorRef, private host: ElementRef<HTMLElement>)`
- `ngOnInit(): void`
- `ngOnChanges(changes: SimpleChanges): void`
- `ngOnDestroy(): void`
- `get visibleActions(): LinkToolbarAction[]`
- `get actionContext(): LinkActionContext | null` — What every button is handed: the link, WHERE on it, and in which direction.
- `handleActionClick(action: LinkToolbarAction, event?: Event): void`
- `handleKeyDown(event: KeyboardEvent): void`
- `onPointerEnter(): void`
- `onPointerLeave(): void`
- `updatePosition(): void` — Re-anchor to the CURRENT rendered route.

Runs the whole chain: rendered path → point + normal at `anchor` → screen
px → centred, normal-offset transform. Any missing link in that chain hides
the toolbar rather than parking it at (0, 0).

**Example**

```html
<grafloria-link-toolbar
  [link]="hoveredLink" [engine]="engine"
  [viewport]="viewport" [zoom]="zoom" [anchor]="0.5">
</grafloria-link-toolbar>
```

<!-- source: grafloria-angular-components-nodetoolbarcomponent.md -->

# NodeToolbarComponent

Import it from `@grafloria/angular`.

NodeToolbar Component

A floating toolbar that attaches to nodes and provides contextual actions. The toolbar automatically positions itself relative to the node and updates
its position when the node moves, the canvas zooms/pans, or the window resizes.

Features:
- Smart positioning with boundary detection
- Keyboard navigation and accessibility (WCAG 2.1 Level AA)
- Custom styling with CSS variables
- Error boundaries for robust operation
- Configuration object pattern

```ts
@Component({
    selector: 'grafloria-node-toolbar',
    imports: [CommonModule],
    template: `
    <div
      #toolbar
      class="grafloria-node-toolbar"
      role="toolbar"
      [attr.aria-label]="effectiveConfig.ariaLabel || 'Node actions'"
      [attr.aria-hidden]="!isVisible"
      [class.visible]="isVisible"
      [class.animated]="effectiveConfig.animation?.enabled !== false"
      [attr.data-animation-preset]="effectiveConfig.animation?.preset || 'fade'"
      [style.transform]="transform"
      [style.opacity]="isVisible ? 1 : 0"
      [style.--toolbar-bg]="effectiveConfig.style?.backgroundColor"
      [style.--toolbar-border]="effectiveConfig.style?.borderColor"
      [style.--toolbar-radius]="effectiveConfig.style?.borderRadius"
      [style.--toolbar-shadow]="effectiveConfig.style?.boxShadow"
      [style.--toolbar-padding]="effectiveConfig.style?.padding"
      [style.--toolbar-z]="effectiveConfig.style?.zIndex"
      [style.--toolbar-transition]="effectiveConfig.animation?.duration || '0.2s'"
      [attr.data-position]="effectiveConfig.position"
      (keydown)="handleKeyDown($event)"
    >
      <!-- Default toolbar content (Phase 2: Supports groups) -->
      @if (!effectiveConfig.template) {
        <div class="toolbar-content" role="group">
          @for (group of effectiveGroups; track group.id; let groupIdx = $index) {
            <!-- Group label (optional) -->
            @if (group.label && useGroupedLayout) {
              <div class="toolbar-group-label">{{ group.label }}</div>
            }

            <!-- Before separator -->
            @if (groupIdx > 0 && (group.separator === 'before' || group.separator === 'both')) {
              <div class="toolbar-separator" role="separator"></div>
            }

            <!-- Group actions -->
            @for (action of group.actions; track action.id; let idx = $index) {
              <button
                #actionButton
                type="button"
                role="button"
                class="toolbar-button"
                [attr.aria-label]="action.tooltip || action.label"
                [attr.aria-disabled]="action.disabled"
                [attr.data-action-id]="action.id"
                [attr.data-group-id]="group.id"
                [attr.tabindex]="calculateTabIndex(groupIdx, idx)"
                [disabled]="action.disabled"
                [title]="action.tooltip || action.label"
                (click)="handleActionClick(action)"
                (focus)="onActionFocus(groupIdx, idx)"
              >
                @if (action.icon) {
                  <i [class]="action.icon" aria-hidden="true"></i>
                }
                <span>{{ action.label }}</span>
              </button>
            }

            <!-- After separator -->
            @if (groupIdx < effectiveGroups.length - 1 && (group.separator === 'after' || group.separator === 'both')) {
              <div class="toolbar-separator" role="separator"></div>
            }
          }
        </div>
      }

      <!-- Custom template content -->
      @if (effectiveConfig.template) {
        <ng-container *ngTemplateOutlet="effectiveConfig.template; context: { $implicit: node, actions: visibleActions, config: effectiveConfig }">
        </ng-container>
      }
    </div>
  `,
    styles: [`
    .grafloria-node-toolbar {
      position: absolute;
      background: var(--toolbar-bg, var(--grafloria-toolbar-bg, white));
      border: 1px solid var(--toolbar-border, var(--grafloria-toolbar-border, #e2e8f0));
      border-radius: var(--toolbar-radius, var(--grafloria-toolbar-radius, 8px));
      box-shadow: var(--toolbar-shadow, var(--grafloria-toolbar-shadow, 0 4px 6px rgba(0, 0, 0, 0.1)));
      padding: var(--toolbar-padding, var(--grafloria-toolbar-padding, 4px));
      display: flex;
      gap: 4px;
      z-index: var(--toolbar-z, var(--grafloria-toolbar-z, 1000));
      transition: opacity var(--toolbar-transition, 0.2s) ease;
      pointer-events: all;
  …
```

Use it as `<grafloria-node-toolbar>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node?` | `NodeModel` |  |  |
| `engine?` | `DiagramEngine` |  |  |
| `canvasElement?` | `HTMLElement` |  |  |
| `viewport?` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `zoom?` | `number` |  |  |
| `position?` | `ToolbarPosition` |  |  |
| `alignment?` | `ToolbarAlignment` |  |  |
| `offset?` | `number` |  |  |
| `actions?` | `ToolbarAction[]` |  |  |
| `customTemplate?` | `TemplateRef<any>` |  |  |
| `visible?` | `boolean` |  |  |
| `styleConfig?` | `ToolbarStyleConfig` |  |  |
| `enableAnimation?` | `boolean` |  |  |
| `autoHide?` | `boolean` |  |  |
| `config?` | `NodeToolbarConfig` |  |  |

**Outputs**

- `actionClicked`
- `visibilityChanged`
- `positionUpdated`

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `node` | `NodeModel` |  |  |
| `engine` | `DiagramEngine` |  |  |
| `canvasElement?` | `HTMLElement` |  |  |
| `viewport` | `{ x: number; y: number; width: number; height: number }` |  |  |
| `zoom` | `number` | `1.0` |  |
| `position` | `ToolbarPosition` | `'top'` |  |
| `alignment` | `ToolbarAlignment` | `'center'` |  |
| `offset` | `number` | `8` |  |
| `actions` | `ToolbarAction[]` | `[]` |  |
| `customTemplate?` | `TemplateRef<any>` |  |  |
| `visible` | `boolean` | `true` |  |
| `styleConfig?` | `ToolbarStyleConfig` |  |  |
| `enableAnimation` | `boolean` | `true` |  |
| `autoHide` | `boolean` | `false` |  |
| `config?` | `NodeToolbarConfig` |  |  |
| `actionClicked` |  |  |  |
| `visibilityChanged` |  |  |  |
| `positionUpdated` |  |  |  |
| `toolbarRef?` | `ElementRef<HTMLDivElement>` |  |  |
| `isVisible` |  | `false` |  |
| `transform` |  | `''` |  |
| `focusedActionIndex` |  | `0` |  |

**Methods**

- `constructor(private cdr: ChangeDetectorRef, private elementRef: ElementRef)`
- `get effectiveConfig(): EffectiveToolbarConfig` — Effective configuration merging individual inputs with config object
- `get visibleActions(): ToolbarAction[]` — Get visible actions based on visibility conditions
- `get effectiveGroups(): ToolbarActionGroup[]` — Get effective action groups
If actionGroups are provided, use them. Otherwise, convert flat actions into a single group.
- `get useGroupedLayout(): boolean` — Check if using grouped layout
- `ngOnInit()`
- `ngOnChanges(changes: SimpleChanges)`
- `ngOnDestroy()`
- `updatePosition()` — Update toolbar position with error handling
- `handleActionClick(action: ToolbarAction)` — Handle action click
- `handleKeyDown(event: KeyboardEvent)` — Handle keyboard navigation
- `onActionFocus(groupIdx: number, actionIdx: number)` — Handle action focus
- `calculateTabIndex(groupIdx: number, actionIdx: number): number` — Calculate tabindex for group-aware navigation
- `show()` — Show toolbar
- `hide()` — Hide toolbar
- `toggle()` — Toggle visibility

**Example**

```html
<grafloria-node-toolbar
  [node]="selectedNode"
  [engine]="diagramEngine"
  [config]="toolbarConfig">
</grafloria-node-toolbar>
```

<!-- source: grafloria-angular-components-propertypanelcomponent.md -->

# PropertyPanelComponent

Import it from `@grafloria/angular`.

Property panel component for editing diagram node properties. Displays editable properties based on PropertySchema.

Features:
- Schema-driven dynamic rendering
- Multi-node editing with mixed value detection
- Validation with inline error display
- Conditional property visibility
- Collapsible property groups
- Immediate and deferred update modes
- Responsive design
- WCAG 2.1 Level AA accessible

```ts
@Component({
    selector: 'diagram-property-panel',
    imports: [CommonModule, PropertyEditorComponent],
    templateUrl: './property-panel.component.html',
    styleUrls: ['./property-panel.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PropertyPanelComponent implements OnInit, OnDestroy
```

Use it as `<diagram-property-panel>` in a template.

**Inputs**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `updateMode?` | `'immediate' \| 'deferred'` |  | Update mode: 'immediate' or 'deferred'. |
| `showHeader?` |  |  | Show header section with node info. |
| `showActions?` |  |  | Show actions menu (delete, duplicate, etc.). |
| `collapsibleGroups?` |  |  | Enable collapsible groups. |
| `headerTemplate?` | `TemplateRef<any>` |  | Custom header template. |
| `emptyStateTemplate?` | `TemplateRef<any>` |  | Custom empty state template. |
| `groupHeaderTemplate?` | `TemplateRef<any>` |  | Custom group header template. |

**Outputs**

- `propertyChanged` — Emitted when property value changes.
- `validationError` — Emitted when validation error occurs.
- `save` — Emitted when Save button clicked (deferred mode).
- `cancel` — Emitted when Cancel button clicked (deferred mode).

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `updateMode` | `'immediate' \| 'deferred'` | `'immediate'` | Update mode: 'immediate' or 'deferred'. - immediate: Changes applied on every keystroke - deferred: Changes applied only when Save button clicked |
| `showHeader` |  | `true` | Show header section with node info. |
| `showActions` |  | `false` | Show actions menu (delete, duplicate, etc.). |
| `collapsibleGroups` |  | `true` | Enable collapsible groups. |
| `headerTemplate?` | `TemplateRef<any>` |  | Custom header template. |
| `emptyStateTemplate?` | `TemplateRef<any>` |  | Custom empty state template. |
| `groupHeaderTemplate?` | `TemplateRef<any>` |  | Custom group header template. |
| `propertyChanged` |  |  | Emitted when property value changes. |
| `validationError` |  |  | Emitted when validation error occurs. |
| `save` |  |  | Emitted when Save button clicked (deferred mode). |
| `cancel` |  |  | Emitted when Cancel button clicked (deferred mode). |
| `schema` | `PropertySchema \| null` | `null` |  |
| `propertyGroups` | `Map<string, PropertyDefinition[]>` |  |  |
| `expandedGroups` |  |  |  |
| `propertyValues` |  |  |  |
| `propertyErrors` |  |  |  |
| `isDirty` |  | `false` |  |

**Methods**

- `@Input() set selectedNodes(nodes: PropertyDiagramNode | PropertyDiagramNode[] | null)` — Selected node(s) to edit. Can be single node or array for multi-node editing.
- `get selectedNodes(): PropertyDiagramNode[]` — Selected node(s) to edit. Can be single node or array for multi-node editing.
- `constructor( private propertyPanelService: PropertyPanelService, private changeDetectorRef: ChangeDetectorRef )`
- `ngOnInit(): void`
- `ngOnDestroy(): void`
- `onPropertyChange(property: PropertyDefinition, newValue: any): void` — Handle property value change.
- `isPropertyVisible(property: PropertyDefinition): boolean` — Check if property should be visible.
- `hasMixedValues(property: PropertyDefinition): boolean` — Check if property has mixed values (multi-node editing).
- `getPropertyValue(property: PropertyDefinition): any` — Get property value or placeholder.
- `getPropertyErrors(property: PropertyDefinition): string[]` — Get validation errors for property.
- `toggleGroup(groupName: string): void` — Toggle group expand/collapse.
- `isGroupExpanded(groupName: string): boolean` — Check if group is expanded.
- `onSave(): void` — Save changes (deferred mode).
- `onCancel(): void` — Cancel changes (deferred mode).
- `trackByGroupName(index: number, entry: { key: string; value: PropertyDefinition[] }): string` — Track by function for property groups (performance optimization).
- `trackByPropertyKey(index: number, property: PropertyDefinition): string` — Track by function for properties (performance optimization).

**Example**

```html
<diagram-property-panel
  [selectedNodes]="selectedNodes"
  [updateMode]="'immediate'"
  [showHeader]="true"
  (propertyChanged)="onPropertyChange($event)">
</diagram-property-panel>
```

<!-- source: grafloria-angular-components-renderedlinkpath.md -->

# RenderedLinkPath

Import it from `@grafloria/angular`.

Card B — the RENDERED route of a link.

THE GOTCHA THIS TYPE EXISTS FOR
-------------------------------
`LinkModel.getPointAtPosition()` walks `link.segments` whenever they are
non-empty. But the SVG renderer NEVER writes `segments`: every frame it
assigns the freshly-routed polyline straight onto `link.points`
(`syncLinkPoints`, deliberately bypassing `setPoints()` to avoid a
re-render loop). `segments` therefore keeps whatever `generatePath()` last
left there — geometry from before the node moved, before the detour, before
the reroute. Anchoring a toolbar to it makes the toolbar drift OFF the line.

So this class reads, in order of truth:

1. THE RENDERED <path> ELEMENT. The renderer tags each link group with
     `data-link-id`, so the browser's own path measurement
     (getTotalLength / getPointAtLength) can be used. This is the literal
     drawn curve: bezier bulge, rounded corners and jump arcs included.
  2. `link.points` — the polyline the renderer synced THIS frame. Exact for
     orthogonal/direct links, a chord approximation for a curve. Used in
     jsdom (no SVG geometry API) and before the first paint.

`link.segments` is never consulted.

```ts
class RenderedLinkPath
```

**Methods**

- `static forLink(link: LinkModel, root?: Element | null): RenderedLinkPath` (static) — Resolve a link's rendered route.
- `get isDomMeasured(): boolean` — True when measuring the real drawn path rather than the point polyline.
- `get isValid(): boolean` — False when the link has no usable geometry at all (nothing to anchor to).
- `get length(): number`
- `pointAt(t: number): Point | null` — Point at fraction `t` (0-1) along the rendered path.
- `normalAt(t: number): Point | null` — Unit normal at `t` — the tangent rotated 90° CCW, matching
`LinkModel.getNormalAt`. Used to lift the toolbar OFF the line.
- `tangentAt(t: number): Point | null` — Unit tangent at `t` (direction of travel).
- `closestTo(point: Point, samples = 100): ClosestHit | null` — Closest point on the rendered path to an arbitrary world point — the
"where did the user click on this edge" query behind insert-node-on-edge.
- `toPolyline(): Point[]` — The polyline this path was resolved from (never `link.segments`).

<!-- source: grafloria-angular-interaction.md -->

# Interaction

Import these from `@grafloria/angular`.

## Functions

### `buildMarqueeRect`

Build the world-space rect spanned by two points.

```ts
function buildMarqueeRect(
  down: ToolPointerEvent,
  current: ToolPointerEvent,
): MarqueeRect
```

### `directionToIntersectionMode`

Map drag direction → membership test. Left→right (or straight down) = `contain` (fully enclosed), right→left =
`intersect` (touched) — the Sketch / Figma convention.

```ts
function directionToIntersectionMode(
  downWorldX: number,
  currentWorldX: number,
): IntersectionMode
```

### `modifiersToSelectionMode`

Map modifier keys → selection combine mode. Shift → add, Cmd/Ctrl → toggle, Alt → subtract, none → replace. Precedence when several are held: shift > meta/ctrl > alt.

```ts
function modifiersToSelectionMode(m: ToolModifiers): SelectionMode
```

## Classes

### `ToolManager`

```ts
class ToolManager
```

**Methods**

- `constructor( private hitTest: SceneHitTester, private actions: ToolActions, private config: ToolManagerConfig, )`
- `setConfig(patch: Partial<ToolManagerConfig>): void` — Patch config (e.g. when the engine's interaction mode / threshold changes).
- `get activeTool(): ToolId | null` — The tool that has actually committed for the current gesture, else null.
- `get armedTool(): ToolId | null` — The tool armed on down (may still be pending the threshold), else null.
- `get hasGesture(): boolean` — True while a gesture is in flight (between down and up/cancel).
- `pointerDown(event: ToolPointerEvent, hit?: HitTestResult): void` — Begin a gesture: hit-test once and choose the single tool that will own it. Drag tools are armed but not committed until the threshold is crossed.
- `pointerMove(event: ToolPointerEvent): void` — Continue a gesture. Promotes an armed drag tool to committed once the
pointer crosses the threshold, then forwards the move to the active tool.
- `pointerUp(event: ToolPointerEvent): void` — End a gesture, firing the active tool's end hook.
- `pointerCancel(event: ToolPointerEvent): void` — Abort a gesture (pointercancel / mouseleave).

## Interfaces

### `HitTestResult`

```ts
interface HitTestResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `HitKind` |  |  |
| `nodeId?` | `string` |  | Owning node id for `node` / `port` hits. |
| `nodeWasSelected?` | `boolean` |  | Whether the hit node was already selected BEFORE this pointerdown. MUST be captured before any on-down selection mutation — it is the sole input to DELIBERATE-mode drag gating. |
| `payload?` | `unknown` |  | Opaque hook for the actions layer (e.g. the port/link reference). |

### `MarqueeRect`

World-space rectangle, shaped to match the engine's `BoundingBox`.

```ts
interface MarqueeRect
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `left` | `number` |  |  |
| `top` | `number` |  |  |
| `right` | `number` |  |  |
| `bottom` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |

### `MarqueeSelection`

Fully-resolved marquee query handed to the actions layer each move.

```ts
interface MarqueeSelection
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `rect` | `MarqueeRect` |  |  |
| `intersectionMode` | `IntersectionMode` |  |  |
| `selectionMode` | `SelectionMode` |  |  |

### `ToolActions`

Side-effect sink. Every method is OPTIONAL so a host can wire only the tools
it owns (the canvas keeps pan / link-draw in their existing branches for now
and implements just the node-drag + marquee actions). The manager still
arbitrates all five so the model — and its tests — stay complete.

```ts
interface ToolActions
```

**Members**

- `beginNodeDrag?(hit: HitTestResult, down: ToolPointerEvent): void`
- `updateNodeDrag?(current: ToolPointerEvent, down: ToolPointerEvent): void`
- `endNodeDrag?(current: ToolPointerEvent): void`
- `beginMarquee?(down: ToolPointerEvent): void`
- `updateMarquee?( selection: MarqueeSelection, current: ToolPointerEvent, down: ToolPointerEvent, ): void`
- `endMarquee?(current: ToolPointerEvent): void`
- `beginLinkDraw?(hit: HitTestResult, down: ToolPointerEvent): void`
- `updateLinkDraw?(current: ToolPointerEvent): void`
- `endLinkDraw?(current: ToolPointerEvent): void`
- `beginPan?(down: ToolPointerEvent): void`
- `updatePan?(current: ToolPointerEvent): void`
- `endPan?(current: ToolPointerEvent): void`

### `ToolManagerConfig`

```ts
interface ToolManagerConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `ToolInteractionMode` |  |  |
| `dragThreshold` | `number` |  | Screen-px movement before a drag tool commits. |

### `ToolModifiers`

Keyboard modifier snapshot carried by every event.

```ts
interface ToolModifiers
```

**Properties**

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

### `ToolPointerEvent`

Minimal pointer event the tools consume. Built per-event by the canvas'
`toToolEvent()` from the native MouseEvent/PointerEvent.

```ts
interface ToolPointerEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'down' \| 'move' \| 'up' \| 'cancel'` |  |  |
| `worldX` | `number` |  | World-space X (viewBox / zoom applied). |
| `worldY` | `number` |  | World-space Y. |
| `screenX` | `number` |  | Element-local screen X in CSS px — used for the drag threshold. |
| `screenY` | `number` |  | Element-local screen Y in CSS px. |
| `button` | `number` |  | Button whose state changed (0 = left, 1 = middle, -1 = pure move). |
| `buttons` | `number` |  | Bitmask of pressed buttons. |
| `modifiers` | `ToolModifiers` |  |  |

## Types

### `HitKind`

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

What sits under the pointer at down-time.

```ts
type HitKind = 'node' | 'port' | 'link' | 'empty';
```

### `IntersectionMode`

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

How a marquee decides membership (derived from drag direction).

```ts
type IntersectionMode = 'contain' | 'intersect';
```

### `SceneHitTester`

Injected scene query — returns what is under a world-space point.

```ts
type SceneHitTester = (worldX: number, worldY: number) => HitTestResult;
```

### `SelectionMode`

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

How a marquee combines with the existing selection (derived from modifiers).

```ts
type SelectionMode = 'replace' | 'add' | 'subtract' | 'toggle';
```

### `ToolId`

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

The five canvas tools. Exactly one is ever active per gesture.

```ts
type ToolId = 'select' | 'node-drag' | 'link-draw' | 'marquee' | 'pan';
```

### `ToolInteractionMode`

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

Interaction mode string (matches the engine's `InteractionMode` enum values).

```ts
type ToolInteractionMode = 'direct' | 'deliberate' | 'smart';
```

<!-- source: grafloria-angular-services.md -->

# Services

Import these from `@grafloria/angular`.

## On their own pages

- [`AngularAnimationService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-angularanimationservice): Angular-injectable Animation Service
- [`BreakpointManagerService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-breakpointmanagerservice): BreakpointManager Service
- [`ComponentRendererService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-componentrendererservice): Service for rendering Angular components inside SVG foreignObject elements. Manages component lifecycle, inputs/outputs, and container management.
- [`ExecutionTrackerService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-executiontrackerservice): ExecutionTracker Service
- [`ModeManagerService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-modemanagerservice): Angular service wrapper for engine ModeManager. Provides reactive API using RxJS observables.
- [`PropertyPanelService`](https://bench-grafloria-6l.atloria.app/p/bench-grafloria-6l-dqcsEdUbfS/developer/grafloria-angular-services-propertypanelservice): Core service for managing property schemas and property values. Acts as bridge between property panel UI and diagram engine.

## Classes

### `HandleRegistryService`

Service to track HTML handles and query their DOM positions
Similar to React Flow's handle detection system

Hybrid HTML+SVG Rendering

This service:
- Tracks all HTML handles registered via GrafloriaHandleDirective
- Queries DOM positions using getBoundingClientRect() like React Flow
- Provides handle bounds for connection drawing
- Enables hit testing for connection drag operations

SHAPE AWARENESS:
This service queries actual DOM positions, so it automatically supports all shape types
(rect, circle, ellipse, diamond, hexagon) as long as the handles are positioned correctly
in the template. Handle positioning is done by diagram-canvas.component.ts using
getPortPositionForShape() which provides shape-aware positioning.

```ts
@Injectable({ providedIn: 'root' })
export class HandleRegistryService
```

**Methods**

- `registerHandle(nodeId: string, handle: HTMLHandle): void` — Register a handle for a node
Called by GrafloriaHandleDirective on init
- `unregisterHandle(nodeId: string, handleId: string): void` — Unregister a handle
Called by GrafloriaHandleDirective on destroy
- `getHandles(nodeId: string): HTMLHandle[]` — Get all handles for a node
- `getHandleBounds( nodeId: string, handleId: string, zoom: number = 1 ): HandleBounds | null` — Get bounds for a specific handle (React Flow style)
Queries DOM using getBoundingClientRect()
- `getAllHandleBounds(zoom: number = 1): Map<string, HandleBounds[]>` — Get bounds for all handles in the diagram
Used for connection drag operations
- `getHandleAtPoint( screenX: number, screenY: number, zoom: number = 1 ): { nodeId: string; handleId: string; handle: HTMLHandle } | null` — Find handle at screen coordinates (for hit testing)
- `getStats(): { nodeCount: number; handleCount: number }` — Get count of registered nodes and handles
Useful for debugging
- `clear(): void` — Clear all registered handles
Useful for cleanup/reset

### `InteractionHandlerService`

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

InteractionHandlerService

Angular binding for {@link InteractionController} — and nothing else.

ALL of the interaction logic (port hover, connection dragging, link
reconnection, inline label repositioning, waypoint and control-point editing)
now lives in the framework-agnostic {@link InteractionController} in
`@grafloria/renderer`, so React / Vue / web-component wrappers get it for free. This class exists purely to make that controller injectable; it adds no
behaviour and overrides no methods.

## The separation this encodes

- **WHAT changed** → the controller. Its handlers are pure w.r.t. Angular and
  return a boolean meaning "a re-render is warranted".
- **TELL THE FRAMEWORK TO RENDER** → the caller. `DiagramCanvasComponent`
  turns those booleans into `cdr.markForCheck()` / `scheduleRender()`.

The controller therefore never imports Angular, never holds a
`ChangeDetectorRef`, and is instantiated with a plain `new` in the e2e
harness. Do not add Angular-aware behaviour here: put logic in the controller
and change detection in the component.

```ts
@Injectable({
  providedIn: 'root',
})
export class InteractionHandlerService extends InteractionController
```

**Methods**

- `constructor()`

See also: InteractionController — the real implementation (and its full API).

### `PropertyEditorRegistryService`

Registry service for property editor components.

This service manages all property editor components (both built-in and custom). It provides a centralized way to register and retrieve editor components by type.

Built-in editors are automatically registered on service initialization:
- string, number, boolean, select, multiselect, color, slider,
  textarea, date, datetime, file, json

Custom editors can be registered using the `registerEditor` method.

```ts
@Injectable({
  providedIn: 'root',
})
export class PropertyEditorRegistryService
```

**Methods**

- `constructor()`
- `registerEditor(type: string, component: Type<any>): void` — Register a custom editor component.

This method allows you to register custom property editor components
or override built-in editors. If an editor with the same type already
exists, it will be overwritten.
- `getEditor(type: string): Type<any> | null` — Get the editor component class for a given type.
- `hasEditor(type: string): boolean` — Check if an editor is registered for a given type.
- `getEditorTypes(): string[]` — Get all registered editor types.

**Example**

```typescript
// Register a custom editor

### `SimulationEngineService`

SimulationEngine Service

High-performance animation engine for diagram simulations. Runs at 60 FPS using requestAnimationFrame.

Features:
- 60 FPS animation loop
- Frame rate monitoring
- Delta time tracking
- Multiple animation callbacks
- Pause/resume support
- Performance stats

```ts
@Injectable({ providedIn: 'root' })
export class SimulationEngineService implements OnDestroy
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `state$` |  |  | Observable of simulation state. |
| `stats$` |  |  | Observable of animation stats (updated every second). |

**Methods**

- `constructor(private ngZone: NgZone)`
- `ngOnDestroy(): void`
- `configure(config: AnimationConfig): void` — Configure simulation engine.
- `start(): void` — Start simulation.
- `stop(): void` — Stop simulation.
- `pause(): void` — Pause simulation.
- `resume(): void` — Resume simulation.
- `isRunning(): boolean` — Check if simulation is running.
- `isPaused(): boolean` — Check if simulation is paused.
- `reset(): void` — Reset simulation timing.
- `registerAnimation(callback: AnimationCallback): () => void` — Register animation callback. Callback is called every frame with delta time.
- `clearAnimations(): void` — Clear all animation callbacks.
- `getAnimationCount(): number` — Get number of registered animations.
- `getStats(): AnimationStats` — Get current animation stats.

**Example**

```typescript
constructor(
  private simulationEngine: SimulationEngineService
) {}

ngOnInit() {
  // Register animation callback
  const unsubscribe = this.simulationEngine.registerAnimation((deltaTime, elapsedTime) => {
    // Update node positions, animations, etc.
    this.updateNodePositions(deltaTime);
  });

  // Start simulation
  this.simulationEngine.start();
}

ngOnDestroy() {
  this.simulationEngine.stop();
}
```

### `VNodeRendererService`

VNodeRendererService

Angular-facing wrapper around the framework-agnostic VNode → DOM patcher
(`VNodePatcher` in `@grafloria/renderer`). This service holds NO rendering logic
of its own: the diff/patch rules live in one place so the Angular canvas, the
e2e harness and any headless consumer all materialize VNodes identically.

`render()` used to wipe the container (`innerHTML = ''`) and rebuild the whole
DOM on every frame, which destroyed focus, text selection, running CSS
animations and anything mounted inside a `<foreignObject>`. It now reconciles:
existing DOM elements are reused, reordered by key, and only genuinely-changed
attributes are written.

```ts
@Injectable({
  providedIn: 'root',
})
export class VNodeRendererService
```

**Methods**

- `render(vnode: VNode, container: HTMLElement): void` — Render (or re-render) a VNode tree into a container, reusing the DOM that is
already there. This is the hot path — it runs once per frame.
- `reconcile(container: HTMLElement, vnode: VNode): Element` — Reconcile a VNode tree into a container and hand back the root element. Same as {@link render}, for callers that want the element.
- `renderVNode(vnode: VNode): Element` — Build a fresh, detached DOM element for a VNode (deep). Used for one-shot materialization; `render()` is what you want for a canvas.
- `updateVNode(element: Element, oldVNode: VNode, newVNode: VNode): void` — Diff two VNodes onto an existing element: props AND children. (The old implementation only diffed props and left a "TODO: handle children"
behind — children are now reconciled by key.)
- `unmount(container: HTMLElement): void` — Remove the tree this service mounted in `container` and forget it.
- `getLastPatchStats(): Readonly<PatchStats>` — Work done by the last `render()` — created / reused / moved / removed /
skipped node counts. A steady-state frame should create ~nothing.

## Interfaces

### `AnimationConfig`

Animation configuration

```ts
interface AnimationConfig
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fps?` | `number` |  | Target FPS (default: 60) |
| `maxDeltaTime?` | `number` |  | Max delta time cap in ms (prevents spiral of death) |
| `autoStart?` | `boolean` |  | Whether to auto-start (default: false) |

### `AnimationStats`

Animation frame stats

```ts
interface AnimationStats
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fps` | `number` |  | Current FPS |
| `avgFps` | `number` |  | Average FPS |
| `frameCount` | `number` |  | Frame count |
| `elapsedTime` | `number` |  | Total elapsed time in ms |
| `deltaTime` | `number` |  | Last frame delta time in ms |

### `Breakpoint`

Breakpoint definition

```ts
interface Breakpoint
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique breakpoint ID |
| `nodeId` | `string` |  | Node ID where breakpoint is set |
| `type` | `BreakpointType` |  | Breakpoint type |
| `enabled` | `boolean` |  | Whether breakpoint is enabled |
| `condition?` | `BreakpointCondition` |  | Condition for conditional breakpoints |
| `conditionExpression?` | `string` |  | Condition expression (for display) |
| `hitCount` | `number` |  | Hit count (how many times breakpoint was hit) |
| `createdAt` | `number` |  | Creation timestamp |
| `metadata?` | `Record<string, any>` |  | Metadata |

### `BreakpointHitEvent`

Breakpoint hit event

```ts
interface BreakpointHitEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `breakpoint` | `Breakpoint` |  | Breakpoint that was hit |
| `nodeId` | `string` |  | Node ID |
| `context` | `any` |  | Execution context at breakpoint |
| `timestamp` | `number` |  | Timestamp |

### `ComponentBounds`

Component bounds for foreignObject.

```ts
interface ComponentBounds
```

**Properties**

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

### `ComponentUpdate`

Component update for batch operations.

```ts
interface ComponentUpdate
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId` | `string` |  |  |
| `inputs` | `Record<string, any>` |  |  |

### `DiagramNode`

Mock DiagramNode interface (temporary - should come from

```ts
interface DiagramNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `string` |  |  |
| `getMetadata?` | `() => Record<string, any>` |  |  |

### `ExecutionSession`

Execution session record

```ts
interface ExecutionSession
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Session ID |
| `startTime` | `number` |  | Session start timestamp |
| `endTime` | `number \| null` |  | Session end timestamp (null if still running) |
| `duration` | `number \| null` |  | Session duration in ms (null if still running) |
| `state` | `ExecutionState` |  | Session state |
| `steps` | `ExecutionStep[]` |  | Execution steps |
| `currentStepIndex` | `number` |  | Current step index |
| `metadata?` | `Record<string, any>` |  | Session metadata |

### `ExecutionStep`

Execution step record

```ts
interface ExecutionStep
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Step ID |
| `nodeId` | `string` |  | Node ID being executed |
| `nodeType` | `string` |  | Node type |
| `startTime` | `number` |  | Step start timestamp |
| `endTime` | `number \| null` |  | Step end timestamp (null if still running) |
| `duration` | `number \| null` |  | Step duration in ms (null if still running) |
| `status` | `'pending' \| 'running' \| 'completed' \| 'error' \| 'skipped'` |  | Step status |
| `input?` | `any` |  | Input data |
| `output?` | `any` |  | Output data |
| `error?` | `{ message: string; code?: string; stack?: string; }` |  | Error details (if status is error) |
| `metadata?` | `Record<string, any>` |  | Step metadata |

### `HandleBounds`

Handle bounds (calculated from DOM)
Used for connection drawing and hit testing

```ts
interface HandleBounds
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `'source' \| 'target'` |  |  |
| `nodeId` | `string` |  |  |
| `position` | `'top' \| 'right' \| 'bottom' \| 'left'` |  |  |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |
| `absoluteX?` | `number` |  |  |
| `absoluteY?` | `number` |  |  |

### `HTMLHandle`

HTML Handle metadata (stored in registry)

```ts
interface HTMLHandle
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `'source' \| 'target'` |  |  |
| `position` | `'top' \| 'right' \| 'bottom' \| 'left'` |  |  |
| `element` | `HTMLElement` |  |  |

### `ModeAnalytics`

Mode analytics data

```ts
interface ModeAnalytics
```

### `ModeChangeEvent`

Mode change event

```ts
interface ModeChangeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `previousMode` | `DiagramMode` |  |  |
| `currentMode` | `DiagramMode` |  |  |

### `ModeGuardResult`

Mode guard function result

```ts
interface ModeGuardResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowed` | `boolean` |  |  |
| `reason?` | `string` |  |  |

### `ModeHistoryEntry`

Mode history entry

```ts
interface ModeHistoryEntry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `DiagramMode` |  |  |
| `timestamp` | `number` |  |  |
| `duration` | `number \| null` |  |  |

### `ModeViewportSettings`

Viewport settings for a specific mode

```ts
interface ModeViewportSettings
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `allowZoom?` | `boolean` |  |  |
| `allowPan?` | `boolean` |  |  |
| `minZoom?` | `number` |  |  |
| `maxZoom?` | `number` |  |  |
| `centerOnLoad?` | `boolean` |  |  |
| `fitToScreen?` | `boolean` |  |  |
| `followNode?` | `string` |  |  |
| `autoCenter?` | `boolean` |  |  |
| `resetOnEnter?` | `boolean` |  |  |

### `PropertyChangeEvent`

Property change event

```ts
interface PropertyChangeEvent
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeId?` | `string` |  | Node ID (single node change) |
| `nodeIds?` | `string[]` |  | Node IDs (bulk change) |
| `propertyKey` | `string` |  | Property key that changed |
| `oldValue?` | `any` |  | Old value (single node change) |
| `newValue` | `any` |  | New value |
| `timestamp` | `number` |  | Timestamp of change |

### `PropertyDiagramNode`

Diagram node interface for property management
Simplified interface to work with any node type that has data storage

```ts
interface PropertyDiagramNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `type` | `string` |  |  |
| `label?` | `string` |  | Optional human-readable label shown in the panel header (falls back to id) |
| `data` | `Record<string, any>` |  |  |

### `RenderComponentOptions`

Options for rendering a component.

```ts
interface RenderComponentOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `inputs?` | `Record<string, any>` |  | Initial input values |
| `outputHandlers?` | `Record<string, (event: any) => void>` |  | Output event handlers |

## Types

### `AnimationCallback`

Animation callback function

```ts
type AnimationCallback = (deltaTime: number, elapsedTime: number) => void;
```

### `BreakpointCondition`

Breakpoint condition function

```ts
type BreakpointCondition = (context: any) => boolean;
```

### `ModeChangeHook`

Mode change hook function

```ts
type ModeChangeHook = (
  previousMode: DiagramMode,
  nextMode: DiagramMode,
  context?: any
) => void | false;
```

### `ModeGuardFunction`

Mode transition guard function

```ts
type ModeGuardFunction = (
  previousMode: DiagramMode,
  nextMode: DiagramMode
) => ModeGuardResult;
```

## Enums

### `BreakpointType`

Breakpoint type

```ts
enum BreakpointType
```

**Members**

- `BEFORE = 'before'` — Break before node execution
- `AFTER = 'after'` — Break after node execution
- `CONDITIONAL = 'conditional'` — Break on condition

### `ExecutionState`

Execution state for workflow/process execution

```ts
enum ExecutionState
```

**Members**

- `IDLE = 'idle'`
- `RUNNING = 'running'`
- `PAUSED = 'paused'`
- `COMPLETED = 'completed'`
- `ERROR = 'error'`

### `SimulationState`

Simulation state

```ts
enum SimulationState
```

**Members**

- `IDLE = 'idle'`
- `RUNNING = 'running'`
- `PAUSED = 'paused'`

<!-- source: grafloria-angular-services-angularanimationservice.md -->

# AngularAnimationService

Import it from `@grafloria/angular`.

Angular-injectable Animation Service

This service wraps the framework-agnostic AnimationService and provides:
- Angular dependency injection
- Automatic cleanup on destroy
- Convenient preset application methods
- Reactive configuration updates

```ts
@Injectable({
  providedIn: 'root'
})
export class AngularAnimationService implements OnDestroy
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `presets` |  |  | Export presets for easy access |

**Methods**

- `constructor()`
- `setEnabled(enabled: boolean): void` — Enable or disable all animations globally
- `getConfig(): Readonly<AnimationConfig>` — Get current configuration
- `updateConfig(config: Partial<AnimationConfig>): void` — Update configuration (partial update)
- `getEdgeAnimationClass(link: LinkModel): string` — Get animation CSS classes for an edge (link)
- `getNodeAnimationClass(node: NodeModel, useSVGVariant: boolean = false): string` — Get animation CSS classes for a node
- `getAnimationDuration(baseDuration: number): number` — Calculate animation duration with speed multiplier applied
- `pauseAllAnimations(): void` — Pause all animations (for debugging or screenshots)
- `resumeAllAnimations(): void` — Resume all animations
- `onConfigChange(listener: (config: AnimationConfig) => void): () => void` — Add listener for configuration changes
- `resetConfig(): void` — Reset configuration to defaults
- `injectCSS(): void` — Inject animation CSS into the document
- `removeCSS(): void` — Remove injected animation CSS from the document
- `isCSSInjected(): boolean` — Check if CSS has been injected
- `applyNodePreset( node: NodeModel, preset: typeof AnimationPresets.NODE[keyof typeof AnimationPresets.NODE] ): NodeModel` — Apply a node preset to a node
Convenient wrapper that modifies the node in place
- `applyWorkflowPreset( node: NodeModel, preset: typeof AnimationPresets.WORKFLOW[keyof typeof AnimationPresets.WORKFLOW] | typeof AnimationPresets.ETL[keyof typeof AnimationPresets.ETL] | typeof AnimationPresets.MONITORING[keyof typeof AnimationPresets.MONITORING] ): NodeModel` — Apply a workflow preset to a node
Convenient wrapper that modifies the node in place
- `getLinkAnimationFromPreset( preset: typeof AnimationPresets.WORKFLOW[keyof typeof AnimationPresets.WORKFLOW] | typeof AnimationPresets.ETL[keyof typeof AnimationPresets.ETL] | typeof AnimationPresets.DATA_FLOW[keyof typeof AnimationPresets.DATA_FLOW] | typeof AnimationPresets.CONNECTION[keyof typeof AnimationPresets.CONNECTION] ): any` — Get link animation from a preset
Returns the LinkAnimation configuration from a preset
- `applyPresetToNodes( nodes: NodeModel[], preset: typeof AnimationPresets.NODE[keyof typeof AnimationPresets.NODE] ): void` — Apply animation to multiple nodes at once
Convenient batch operation
- `applyWorkflowPresetToNodes( nodes: NodeModel[], preset: typeof AnimationPresets.WORKFLOW[keyof typeof AnimationPresets.WORKFLOW] | typeof AnimationPresets.ETL[keyof typeof AnimationPresets.ETL] | typeof AnimationPresets.MONITORING[keyof typeof AnimationPresets.MONITORING] ): void` — Apply workflow preset to multiple nodes at once
Convenient batch operation
- `applyLinkPresetToLinks( links: LinkModel[], preset: typeof AnimationPresets.DATA_FLOW[keyof typeof AnimationPresets.DATA_FLOW] | typeof AnimationPresets.CONNECTION[keyof typeof AnimationPresets.CONNECTION] ): void` — Apply link animation preset to multiple links at once
Convenient batch operation
- `ngOnDestroy(): void` — Angular lifecycle: Clean up on destroy

<!-- source: grafloria-angular-services-breakpointmanagerservice.md -->

# BreakpointManagerService

Import it from `@grafloria/angular`.

BreakpointManager Service

Manages breakpoints for debugging diagram execution.

Features:
- Set/remove breakpoints on nodes
- Conditional breakpoints
- Enable/disable breakpoints
- Hit count tracking
- Breakpoint hit notifications

```ts
@Injectable({ providedIn: 'root' })
export class BreakpointManagerService
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `breakpoints$` |  |  | Observable of all breakpoints. Emits whenever breakpoints change. |
| `breakpointHit$` |  |  | Observable of breakpoint hit events. Emits when a breakpoint is hit during execution. |

**Methods**

- `addBreakpoint( nodeId: string, type: BreakpointType, condition?: BreakpointCondition, conditionExpression?: string, metadata?: Record<string, any> ): Breakpoint` — Add breakpoint to node.
- `removeBreakpoint(breakpointId: string): boolean` — Remove breakpoint by ID.
- `removeBreakpointsForNode(nodeId: string): number` — Remove all breakpoints for node.
- `clearBreakpoints(): void` — Remove all breakpoints.
- `enableBreakpoint(breakpointId: string): void` — Enable breakpoint.
- `disableBreakpoint(breakpointId: string): void` — Disable breakpoint.
- `toggleBreakpoint(breakpointId: string): void` — Toggle breakpoint enabled/disabled.
- `getBreakpoint(breakpointId: string): Breakpoint | null` — Get breakpoint by ID.
- `getAllBreakpoints(): Breakpoint[]` — Get all breakpoints.
- `getBreakpointsForNode(nodeId: string): Breakpoint[]` — Get breakpoints for node.
- `hasBreakpoint(nodeId: string, type?: BreakpointType): boolean` — Check if node has breakpoint.
- `getBreakpointCount(): number` — Get breakpoint count.
- `getEnabledBreakpointCount(): number` — Get enabled breakpoint count.
- `shouldBreak(nodeId: string, type: BreakpointType, context?: any): boolean` — Check if breakpoint should hit at node. Call this during execution before/after node execution.
- `triggerBreakpointHit(breakpointId: string, context?: any): void` — Manually trigger breakpoint hit. Useful for testing or custom breakpoint logic.
- `resetHitCount(breakpointId: string): void` — Reset hit count for breakpoint.
- `resetAllHitCounts(): void` — Reset hit counts for all breakpoints.
- `getStats(): { total: number; enabled: number; disabled: number; byType: Record<BreakpointType, number>; totalHits: number; }` — Get breakpoint statistics.

**Example**

```typescript
constructor(
  private breakpointManager: BreakpointManagerService
) {}

setDebugBreakpoint(nodeId: string) {
  // Set breakpoint before node execution
  const breakpoint = this.breakpointManager.addBreakpoint(
    nodeId,
    BreakpointType.BEFORE
  );

  // Listen for hits
  this.breakpointManager.breakpointHit$.subscribe(event => {
    console.log('Breakpoint hit:', event.nodeId);
    // Pause execution, show debugger, etc.
  });
}

setConditionalBreakpoint(nodeId: string) {
  // Set conditional breakpoint
  this.breakpointManager.addBreakpoint(
    nodeId,
    BreakpointType.CONDITIONAL,
    (context) => context.value > 100,
    'value > 100'
  );
}
```

<!-- source: grafloria-angular-services-componentrendererservice.md -->

# ComponentRendererService

Import it from `@grafloria/angular`.

Service for rendering Angular components inside SVG foreignObject elements. Manages component lifecycle, inputs/outputs, and container management.

```ts
@Injectable({ providedIn: 'root' })
export class ComponentRendererService
```

**Methods**

- `constructor( private injector: Injector, private applicationRef: ApplicationRef )`
- `registerComponent(nodeType: string, component: Type<any>): void` — Register an Angular component for a node type. Component will be rendered inside foreignObject when node is displayed.
- `unregisterComponent(nodeType: string): void` — Unregister a component for a node type. No-op if the type was never registered. Enables override/replace flows
(register a new component for an existing type) without loosening the
strict duplicate check in {@link registerComponent}.
- `hasComponent(nodeType: string): boolean` — Check if component is registered for node type.
- `getRegisteredComponent(nodeType: string): Type<any> | null` — Get registered component class for node type.
- `renderComponent( node: DiagramNode, viewContainerRef: ViewContainerRef, options?: RenderComponentOptions ): ComponentRef<any>` — Render a component for a diagram node. Creates component instance, passes inputs, subscribes to outputs.
- `updateComponent(nodeId: string, inputs: Record<string, any>): void` — Update component inputs without recreating component. More efficient than destroy + render.
- `destroyComponent(nodeId: string): void` — Destroy a component and clean up resources. Calls ngOnDestroy, unsubscribes, removes from DOM.
- `getComponent<T = any>(nodeId: string): ComponentRef<T> | null` — Get component reference for a node. Allows programmatic access to component instance.
- `getContainerId(nodeId: string): string | null` — Get foreignObject container ID for a node.
- `createForeignObjectVNode( node: DiagramNode, bounds: ComponentBounds ): VNode` — Create foreignObject VNode for a component. Used by rendering pipeline to embed component in SVG.
- `batchUpdate(updates: ComponentUpdate[]): void` — Batch update multiple components. More efficient than individual updates.
- `destroyAll(): void` — Destroy all components. Called when diagram is cleared or component unmounted.
- `getActiveCount(): number` — Get count of active component instances. Useful for debugging and performance monitoring.
- `getRegisteredTypes(): string[]` — Get list of all registered node types. Useful for component palette UI and validation.

**Example**

```typescript
// Register a component
componentRenderer.registerComponent('ERD.TABLE', ErdTableComponent);

// Render a component
const componentRef = componentRenderer.renderComponent(
  node,
  viewContainerRef,
  { inputs: { tableName: 'users', columns: [...] } }
);

// Update component
componentRenderer.updateComponent(node.id, { tableName: 'products' });

// Destroy component
componentRenderer.destroyComponent(node.id);
```

<!-- source: grafloria-angular-services-executiontrackerservice.md -->

# ExecutionTrackerService

Import it from `@grafloria/angular`.

ExecutionTracker Service

Tracks workflow/process execution with history. Useful for debugging, replay, and analytics.

Features:
- Execution session tracking
- Step-by-step execution history
- Current execution state
- Performance metrics
- Replay capability

```ts
@Injectable({ providedIn: 'root' })
export class ExecutionTrackerService
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `currentSession$` |  |  | Observable of current execution session. Emits null when no session is active. |
| `executionState$` |  |  | Observable of current execution state. |

**Methods**

- `startSession(metadata?: Record<string, any>): string` — Start new execution session.
- `completeSession(sessionId: string): void` — Complete execution session.
- `pauseSession(sessionId: string): void` — Pause execution session.
- `resumeSession(sessionId: string): void` — Resume execution session.
- `failSession(sessionId: string, error: { message: string; code?: string; stack?: string }): void` — Fail execution session with error.
- `getSession(sessionId: string): ExecutionSession | null` — Get execution session by ID.
- `getCurrentSession(): ExecutionSession | null` — Get current execution session.
- `getAllSessions(): ExecutionSession[]` — Get all execution sessions.
- `clearSessions(): void` — Clear all execution sessions.
- `startStep(sessionId: string, nodeId: string, nodeType: string, input?: any): string` — Start execution step.
- `completeStep(stepId: string, output?: any): void` — Complete execution step.
- `failStep(stepId: string, error: { message: string; code?: string; stack?: string }): void` — Fail execution step with error.
- `skipStep(stepId: string): void` — Skip execution step.
- `getStep(stepId: string): ExecutionStep | null` — Get execution step by ID.
- `getSteps(sessionId: string): ExecutionStep[]` — Get all steps for session.
- `getSessionStats(sessionId: string): { totalSteps: number; completedSteps: number; errorSteps: number; skippedSteps: number; avgStepDuration: number; totalDuration: number; } | null` — Get execution statistics for session.

**Example**

```typescript
constructor(private executionTracker: ExecutionTrackerService) {}

startWorkflow() {
  const sessionId = this.executionTracker.startSession();

  // Track each step
  const stepId = this.executionTracker.startStep(sessionId, 'node-1', 'task');
  // ... execute node logic ...
  this.executionTracker.completeStep(stepId, { result: 'success' });

  // Complete session
  this.executionTracker.completeSession(sessionId);
}
```

<!-- source: grafloria-angular-services-modemanagerservice.md -->

# ModeManagerService

Import it from `@grafloria/angular`.

Angular service wrapper for engine ModeManager. Provides reactive API using RxJS observables.

Features:
- Reactive mode state (BehaviorSubject)
- Mode transition guards
- Mode history tracking
- Mode-specific viewport settings
- Before/after hooks
- Mode analytics

```ts
@Injectable({ providedIn: 'root' })
export class ModeManagerService implements OnDestroy
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode$` |  |  | Observable of current diagram mode. Emits whenever mode changes. |
| `modeChanged$` |  |  | Observable of mode change events. Emits { previousMode, currentMode } on every mode change. |

**Methods**

- `ngOnDestroy(): void`
- `getMode(): DiagramMode` — Get current diagram mode.
- `setMode(mode: DiagramMode): void` — Set diagram mode. Mode change may be blocked by guards.
- `isDesignerMode(): boolean` — Check if in designer mode.
- `isRunningMode(): boolean` — Check if in running mode.
- `isViewMode(): boolean` — Check if in view mode.
- `isDebugMode(): boolean` — Check if in debug mode.
- `isPresentationMode(): boolean` — Check if in presentation mode.
- `isReadOnlyMode(): boolean` — Check if in read-only mode (any mode except designer).
- `addModeGuard(name: string, guard: ModeGuardFunction): void` — Add mode transition guard. Guards can prevent mode changes based on custom logic.
- `removeModeGuard(name: string): void` — Remove mode transition guard.
- `clearModeGuards(): void` — Clear all mode transition guards.
- `configureModeViewport(mode: DiagramMode, settings: ModeViewportSettings): void` — Configure viewport settings for specific mode.
- `getModeViewportSettings(mode: DiagramMode): ModeViewportSettings` — Get viewport settings for specific mode.
- `getModeHistory(): ModeHistoryEntry[]` — Get mode history. Returns array of mode entries with timestamps and durations.
- `clearModeHistory(): void` — Clear mode history (keeps current mode only).
- `previousMode(): void` — Navigate to previous mode in history.
- `nextMode(): void` — Navigate to next mode in history.
- `pushMode(mode: DiagramMode): void` — Push current mode onto stack and switch to new mode. Useful for temporary mode switches.
- `popMode(): void` — Pop mode from stack and return to previous mode.
- `getModeAnalytics(): ModeAnalytics` — Get mode analytics (time spent in each mode).
- `beforeModeChange(hook: ModeChangeHook): () => void` — Register before mode change hook. Hook can prevent mode change by returning false.
- `afterModeChange(hook: ModeChangeHook): () => void` — Register after mode change hook.

**Example**

```typescript
constructor(private modeManager: ModeManagerService) {}

ngOnInit() {
  // Subscribe to mode changes
  this.modeManager.mode$.subscribe(mode => {
    console.log('Current mode:', mode);
  });

  // Switch to running mode
  this.modeManager.setMode(DiagramMode.RUNNING);
}
```

<!-- source: grafloria-angular-services-propertypanelservice.md -->

# PropertyPanelService

Import it from `@grafloria/angular`.

Core service for managing property schemas and property values. Acts as bridge between property panel UI and diagram engine.

```ts
@Injectable({ providedIn: 'root' })
export class PropertyPanelService
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `propertyChanged$` |  |  | Observable that emits when any property changes. Can be filtered by node ID or property key. |

**Methods**

- `registerSchema(nodeType: string, schema: PropertySchema): void` — Register a property schema for a node type.
- `registerSchemaFromJSON(nodeType: string, schemaJson: string): void` — Register schema from JSON string. Enables loading schemas from database or config files.
- `extendSchema( nodeType: string, parentType: string, overrides: Partial<PropertySchema> ): void` — Extend an existing schema to create a specialized type. Child inherits all parent properties and can override or add new ones.
- `getSchema(nodeType: string): PropertySchema | null` — Get property schema for a node type. Returns fully resolved schema (including inherited properties).
- `hasSchema(nodeType: string): boolean` — Check if schema is registered for node type.
- `getAllTypes(): string[]` — Get list of all registered node types.
- `unregisterSchema(nodeType: string): boolean` — Unregister the schema for a node type. Since {@link registerSchema} rejects duplicates, this is the only way to
replace a schema (e.g. hot-reloading schemas from a config source).
- `clearSchemas(): void` — Remove all registered schemas. Useful when tearing down a diagram context or isolating test state.
- `getPropertyValue(node: PropertyDiagramNode, propertyKey: string): any` — Get property value from a node. Supports nested property paths (e.g., 'style.fill.color').
- `setPropertyValue(node: PropertyDiagramNode, propertyKey: string, value: any): any` — Set property value on a node. Validates value against schema before setting.
- `setPropertyValues( nodes: PropertyDiagramNode[], propertyKey: string, value: any ): string[]` — Set property value on multiple nodes simultaneously. Validates once and applies to all nodes. Rolls back all changes if any validation fails.
- `validateProperty(value: any, property: PropertyDefinition): ValidationResult` — Validate a property value against its definition.
- `isPropertyVisible(node: PropertyDiagramNode, property: PropertyDefinition): boolean` — Check if property is visible based on condition. Evaluates condition expression against current node properties.
- `applyDefaults(node: PropertyDiagramNode, schema: PropertySchema): void` — Apply default values from schema to node. Only sets properties that are currently undefined.
- `getPropertyGroups(schema: PropertySchema): Map<string, PropertyDefinition[]>` — Get properties organized by groups. Properties without group go to 'General' group.
- `getPropertyChangesForNode(nodeId: string): Observable<PropertyChangeEvent>` — Filter property change events by node ID.
- `getPropertyChangesForKey(propertyKey: string): Observable<PropertyChangeEvent>` — Filter property change events by property key.