# Grafloria

<!-- source: introduction.md -->

# Introduction

Grafloria is an MIT diagram and dashboard engine for JavaScript. Use it when you build flowcharts, workflow editors, UML or ER diagrams, or boards of draggable, resizable widgets. Its JavaScript surface and native Angular, React, Vue and Qwik bindings share one headless core, one document format and one undo stack.

## Choose your packages

Start with the package for your framework, or the element package for framework-free embedding. The engine owns the graph and behavior; the renderer supplies the visual layer.

| Package | What you use it for | Install in your project |
| --- | --- | --- |
| [`@grafloria/engine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-overview) | Headless graph models, commands and undo, layout, diagram text and collaboration. | `npm install @grafloria/engine` |
| [`@grafloria/renderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-overview) | SVG rendering, interaction, theming, accessibility and SVG, PNG or vector PDF export. | `npm install @grafloria/renderer @grafloria/engine` |
| [`@grafloria/element`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-overview) | The `<grafloria-flow>` custom element and dashboard, UML and ER kits, with or without a framework. | `npm install @grafloria/element @grafloria/engine @grafloria/renderer` |
| [`@grafloria/dashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-dashboard) | Dashboard layouts with grid or splitter arrangements, undo, nesting and persistence. | `npm install @grafloria/dashboard @grafloria/element@^0.4.9 @grafloria/engine@^0.3.0 @grafloria/renderer@^0.4.0` |
| [`@grafloria/react`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) | React components, hooks and component-based custom nodes. | `npm install @grafloria/react @grafloria/engine @grafloria/renderer @grafloria/element react react-dom` |
| [`@grafloria/vue`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) | Vue 3 components, `v-model` bindings and slot-based custom nodes. | `npm install @grafloria/vue @grafloria/engine @grafloria/renderer @grafloria/element vue` |
| [`@grafloria/angular`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-overview) | Angular components, directives and services. | `npm install @grafloria/angular @grafloria/engine @grafloria/renderer @grafloria/element @angular/common @angular/core @angular/forms @angular/platform-browser rxjs` |
| [`@grafloria/qwik`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) | Qwik components, QRL callbacks, custom nodes and resumable server rendering. | `npm install @grafloria/qwik @grafloria/engine @grafloria/renderer @grafloria/element @builder.io/qwik` |

The standalone dashboard package at version `0.1.0` declares older peer ranges than the current framework packages. Its install line selects those ranges. For dashboards in a current framework project, start with that framework's binding and the dashboard kit in the element package.

## Take your quick start

Choose your stack to install the binding and mount a sized canvas with two connected nodes:

- [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start): embed without a framework and keep the live instance for updates and cleanup.
- [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start): use controlled node and edge state and an initialization ref.
- [Vue quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-quick-start): use typed data, `v-model` bindings and an initialization callback.
- [Angular quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-quick-start): use a standalone canvas, two-way model bindings and view-child access.
- [Qwik quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-quick-start): use serializable signals, QRL change callbacks and initialization access.

To explore before installing, open the [live demo gallery](https://grafloria.com/demos/) or the [fluid dashboard demo](https://grafloria.com/demos/dashboard/fluid-board.html).

## Find your task

### Concepts

Start with [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works), then follow [specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models), [instance lifetime](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle), [state and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow), [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history), and [documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) to understand how your binding, live graph and saved document fit together.

### Guides

The task guides cover shared capabilities; use the framework guides below for binding-specific state and content.

- **Edit the graph:** [edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes), [validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections), [route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges), [configure gestures](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/configure-editing-gestures), and [add editor controls](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/add-editor-controls) to turn the canvas into an editor.
- **Layout and containment:** [lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) and [group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes) to arrange graphs and give zones, containers and swimlanes real membership.
- **Appearance:** [theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) and [highlight and animate state](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/highlight-and-animate-state) to adopt your design system and show graph state without changing graph structure.
- **Diagram editors:** build a [workflow editor](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-workflow-editor), [database model editor](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-database-models), [UML class editor](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-uml-classes), or [stencil editor](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-stencil-editor) using shipped capabilities.
- **Dashboards:** [build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) and [arrange dashboard containers](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/arrange-dashboard-containers) to manage widgets, responsive layouts, nested sections and tabs.
- **Collaboration:** [synchronize editors](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/synchronize-editors) and [share presence and comments](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/share-presence-and-comments) to connect peers and add shared cursors and discussion.
- **Saving and export:** [save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents), [import diagram text and files](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/import-diagram-text-and-files), and [export images and documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/export-images-and-documents) to persist the live graph and exchange editable or rendered results.
- **Whiteboarding and extensions:** [draw and edit ink](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/draw-and-edit-ink), [tune large-graph rendering](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/tune-large-graph-rendering), [extend rendered geometry](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/extend-rendered-geometry), and [extend layout execution](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/extend-layout-execution) when you need ink tools, rendering controls or capabilities beyond the built-ins.

### Framework guides

- **JavaScript:** [elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content) covers embedding choices, DOM events, custom renderers and framework-free lifecycle.
- **React:** [state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions) and [custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content) cover controlled ownership, instance access, portals and widget components.
- **Vue:** [state and composables](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-state-and-composables) and [slots and widgets](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-slots-and-widgets) cover refs, providers, reactive content and dashboard views.
- **Angular:** [state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling) and [templates and handles](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-templates-and-handles) cover model bindings, incremental patches, editor services, node templates and connection handles.
- **Qwik:** [state and resumption](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-state-and-resumption) and [custom content and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-custom-content-and-kits) cover QRL boundaries, serializable state and custom content across Qwik containers.

### API reference

Use the package reference links in the package table to look up exports and signatures. For the live canvas facade, start with [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance): it provides rendering and spec updates, `getModel()` for data queries, and `getEngine()` for engine access. The [Qwik Vite reference](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik-vite) covers that package's Vite entry point.

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

# JavaScript quick start

Render a 400px-high canvas with two connected nodes, keep its instance for later calls, and clean it up when you close the editor.

Grafloria's framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior.

## Prerequisites

Use a browser project with an HTML entry point and an ESM bundler. No UI framework is required. This example uses Vite and TypeScript for typed specs; it runs in the browser, not Node.

`@grafloria/element` 0.5.0 requires `@grafloria/engine` `^0.4.0` and `@grafloria/renderer` `^0.5.0` as peers. In your project directory, install all three packages and the example's development tools:

```bash
npm install @grafloria/element@0.5.0 @grafloria/engine@^0.4.0 @grafloria/renderer@^0.5.0
npm install --save-dev vite typescript
```

## 1. Give the canvas a size

Create `index.html` at your project root. The canvas has a resolved height before the diagram mounts. The button closes the editor; it does not run during setup.

```html title="index.html"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Grafloria quick start</title>
  </head>
  <body>
    <section id="editor">
      <button id="close-editor" type="button">Close diagram</button>
      <p id="status" role="status"></p>
      <div id="canvas" style="width: 100%; height: 400px;"></div>
    </section>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

For other sizing arrangements, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

## 2. Mount two connected nodes

Call [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) with the spec first, the target second, and instance options third. It mounts the diagram and returns a live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance).

Create `src/main.ts`, the entry file. Type the data with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec), and use the shipped [`LIGHT_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants). The edge names the nodes by their ids; its handles pin the connection to the right side of Ingest and the left side of Publish. Omit `ports` to use the nodes' four default ports.

```ts title="src/main.ts"
import { render } from '@grafloria/element';
import { LIGHT_THEME } from '@grafloria/renderer';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const container = document.getElementById('canvas');
const editor = document.getElementById('editor');
const closeControl = document.getElementById('close-editor');
const status = document.getElementById('status');

if (!container || !editor || !closeControl || !status) {
  throw new Error('The editor elements are missing');
}
container.style.height = '400px';
container.style.width = '100%';
const closeButton = document.createElement('button');
closeButton.id = 'close-editor';
closeButton.type = 'button';
closeButton.textContent = 'Close diagram';
closeControl.replaceWith(closeButton);
editor.append(closeButton, status, container);

  const nodes: NodeSpec[] = [
    {
      id: 'a',
      position: { x: 60, y: 80 },
      size: { width: 180, height: 80 },
      label: 'Ingest',
    },
    {
      id: 'b',
      position: { x: 380, y: 80 },
      size: { width: 180, height: 80 },
      label: 'Publish',
    },
  ];
  const edges: EdgeSpec[] = [
    {
      id: 'e1',
      source: 'a',
      target: 'b',
      sourceHandle: 'right',
      targetHandle: 'left',
    },
  ];

const api = render({ nodes, edges }, container, {
    theme: LIGHT_THEME,
    fitView: true,
  });
const model = api.getModel();
status.textContent = `${model.getNodes().length} nodes connected by ${model.getLinks().length} edge`;

closeButton.addEventListener('click', () => {
  api.dispose();
  editor.remove();
}, { once: true });
```

`fitView: true` frames the content on mount. The nodes render side by side with a line between them.

![Look for the edge from Ingest to Publish, with the Close diagram button and model counts above the canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/868c6fde3e07406665ec2ec9aaa36015.png)

Pass data to `render()`: an object spec or its JSON string, not Mermaid text. To import text instead, see [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

## 3. Keep the instance and clean up on close

The entry file keeps the returned instance in `api`, queries its live data for the status, and calls `dispose()` from the close handler before removing the editor.

`getModel()` returns the live [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel), not a copy of your input specs. Use the instance for rendering operations such as `fitView()`; use `getEngine()` to reach the [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) for commands, layout, and validation. See [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) for the next instance operations.

On close, `dispose()` detaches interaction listeners, stops scheduled rendering, disconnects resize observation, and removes the diagram's DOM. In an application with route or component lifecycle hooks, put that call in the editor's unmount hook instead.

Start the development server from your project directory:

```bash
npx vite
```

Open the local URL Vite prints. You have a sized diagram containing Ingest and Publish, their connecting edge, a status showing the mounted model's counts, and a Close diagram button. Closing removes the editor and releases the instance.

## Where next

- Explore the [live JavaScript demos](https://grafloria.com/demos/) and their source tabs.
- Add HTML node content with [JavaScript elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).
- Add editing actions with [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).
- Learn the relationship between specs, models, and the engine in [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works).

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

# React quick start

Mount a controlled canvas with two connected nodes, and keep its instance in a ref for a Fit view button.

Framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior.

## Prerequisites

Use a browser-based React project with TypeScript and JSX configured, React and React DOM 17, 18 or 19 (18 or 19 for the mounting code below), and the binding's `@grafloria/element` `^0.5.0` peer; see [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start#prerequisites) for the shared engine and renderer prerequisites.

## 1. Install the binding and its peers

Run this in your application's directory:

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

## 2. Create the controlled canvas

Render [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow) with typed [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) data. The edge's `source` and `target` identify the two nodes.

[`useNodesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#usenodesstate) and [`useEdgesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useedgesstate) each return a three-element tuple: the specs, a state setter and a canvas change handler. Pass the third element to the corresponding change prop to mirror canvas edits into React state.

Store the [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) received by `onInit` in a React ref. The button calls `fitView()` on that mounted instance to frame the content; the `fitView` prop also frames it at startup. `plugins` adds the shipped minimap, zoom/fit controls and background grid.

```tsx title="src/App.tsx"
import { useRef } from 'react';
import {
  GrafloriaFlow,
  useNodesState,
  useEdgesState,
} from '@grafloria/react';
import type {
  DiagramInstance,
  NodeSpec,
  EdgeSpec,
} from '@grafloria/react';

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

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

export default function App() {
  const instanceRef = useRef<DiagramInstance | null>(null);
  const [nodes, , onNodesChange] = useNodesState(initialNodes);
  const [edges, , onEdgesChange] = useEdgesState(initialEdges);

  return (
    <main>
      <button
        type="button"
        onClick={() => instanceRef.current?.fitView()}
      >
        Fit view
      </button>
      <div style={{ width: '100%', height: 400 }}>
        <GrafloriaFlow
          nodes={nodes}
          edges={edges}
          onNodesChange={onNodesChange}
          onEdgesChange={onEdgesChange}
          onInit={(instance) => { instanceRef.current = instance; }}
          fitView
          plugins
        />
      </div>
    </main>
  );
}
```

![Ingest connects to Publish across the dotted canvas. Look for the Fit view button above it, zoom/fit controls at the lower left and the minimap at the lower right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/41e1adc1ca007ff858e4a059892bebbc.png)

The canvas occupies the 400-pixel-high wrapper. For other sizing arrangements, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

### Keep the controlled return path wired

Passing controlled `nodes` without `onNodesChange` lets stale React state overwrite user edits. Pass the hook's third element, not its `setNodes` setter: the callback receives live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) objects, while the setter accepts `NodeSpec[]` or a state updater. The hook converts those live models back to specs. The second tuple element is omitted in this sample because it does not make application-originated edits.

`onInit` runs after the instance is created. The binding disposes that instance when the flow unmounts; do not dispose it after initialization.

## 3. Mount the app

For a React 18 or 19 client entry, render `App` into your HTML root element:

```tsx title="src/main.tsx"
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.getElementById('root');
if (!container) throw new Error('Missing #root element');

createRoot(container).render(<App />);
```

Use the HTML entry structure from [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start#1-give-the-canvas-a-size), replacing its editor markup and script with the React root and TSX entry:

```html title="index.html"
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
```

This HTML entry fits a Vite React TypeScript project. If your framework already mounts `App`, keep its entry point instead.

Start your application's development server and open it in the browser. You now have Ingest and Publish nodes joined by an edge, with a Fit view button above the canvas. Drag a node to move it; the change handler mirrors the edit into React state. Pan or zoom, then click Fit view to frame both nodes again.

## Where next

- Try the [live React starter](https://stackblitz.com/github/grafloria/grafloria/tree/main/starters/react?file=src/main.jsx), or explore the [React demo gallery](https://grafloria.com/demos-react/).
- Read [React: state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions) for application updates and subscriptions.
- Use [React: custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content) to render your own node components.
- Read [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) for instance ownership beyond this component.

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

# Vue quick start

Mount a Vue canvas with two connected nodes, keep its specs in typed refs, and capture the mounted instance through `@init`.

Framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior.

## Prerequisites

Use a browser-based Vue TypeScript project with single-file component support. This example assumes your project has an `npm run dev` script, as a Vite Vue project does.

The Vue binding's peer dependencies are Vue `^3.4.0`, engine `^0.4.0`, renderer `^0.5.0`, and element `^0.5.0`.

## 1. Install the binding and its peers

Run this in your project:

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

You now have the Vue component and the shared engine and renderer packages it uses.

## 2. Mount a controlled canvas

Replace `src/App.vue` with this Vue single-file component, supplying [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow) through refs typed with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec); see the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start#2-create-the-controlled-canvas) for the shared canvas and endpoint setup.

`v-model:nodes` and `v-model:edges` supply the controlled props and write the component's emitted spec updates back into your refs. The `init` event supplies the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). Keep it in a `shallowRef` and call `fitView()` to frame the content.

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

const nodes = ref<NodeSpec[]>([
  {
    id: 'a',
    position: { x: 60, y: 80 },
    size: { width: 180, height: 80 },
    label: 'Ingest',
  },
  {
    id: 'b',
    position: { x: 380, y: 80 },
    size: { width: 180, height: 80 },
    label: 'Publish',
  },
]);
const edges = ref<EdgeSpec[]>([
  { id: 'e1', source: 'a', target: 'b' },
]);
const instance = shallowRef<DiagramInstance | null>(null);

function onInit(api: DiagramInstance): void {
  instance.value = api;
  api.fitView();
}
</script>

<template>
  <p role="status">{{ instance ? 'Canvas ready' : 'Mounting canvas' }}</p>
  <div style="height: 400px">
    <GrafloriaFlow
      v-model:nodes="nodes"
      v-model:edges="edges"
      :plugins="true"
      @init="onInit"
    />
  </div>
</template>
```

You get an **Ingest** node connected to a **Publish** node. `:plugins="true"` adds the shipped minimap, zoom/fit controls, and background grid; the component loads these plugins lazily. No stylesheet import is needed.

![Look for the arrow from Ingest to Publish, the zoom/fit controls at the lower left, and the minimap at the lower right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/8573079d35ab4529eefec47ba14a4a81.png)

For a self-contained canvas whose data the instance owns, use `:default-nodes` and `:default-edges` instead of the two `v-model` bindings. Those defaults seed the instance once at mount. For more on the return path and composables, see [Vue: state and composables](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-state-and-composables).

## 3. Open the editor

Start your project's development server and open the local URL it prints:

```bash
npm run dev
```

Look for **Canvas ready**, the two labelled nodes, and their connecting edge. Drag a node to move it; use the canvas controls to zoom or fit the view. The Vue component disposes its instance and plugins when it unmounts—do not dispose the instance in `onInit`.

Explore the [live Vue demos](https://grafloria.com/demos-vue/) for running examples with Vue SFC source.

## Replacing externally edited specs

Ordinary controlled updates reconcile into existing live objects rather than remounting the canvas. A full replacement with reused ids needs a different sequence.

> **Known issue:** Replacing specs with reused node ids can retain old ports and metadata: the existing-node update path does not rebuild ports or remove omitted metadata. Until it is fixed, clear edges and nodes, await `nextTick()`, then apply the replacement.

The intended direct assignments are `nodes.value = importedNodes` and `edges.value = importedEdges`. For a fresh import, use this helper instead; pass the refs from your component and the imported spec arrays. It leaves the replacement diagram on the mounted canvas.

```ts title="src/replace-specs.ts"
import { nextTick, type Ref } from 'vue';
import type { NodeSpec, EdgeSpec } from '@grafloria/vue';

export async function replaceSpecs(
  nodes: Ref<NodeSpec[]>,
  edges: Ref<EdgeSpec[]>,
  importedNodes: NodeSpec[],
  importedEdges: EdgeSpec[],
): Promise<void> {
  edges.value = [];
  nodes.value = [];
  await nextTick();
  nodes.value = importedNodes;
  edges.value = importedEdges;
  await nextTick();
}
```

The first `nextTick()` lets the empty lists reconcile before you apply the replacement. Without that boundary, Vue batches the assignments and the watchers see only the final lists.

## Where next

You now have a sized, controlled Vue canvas and access to its mounted instance.

- [Vue: slots and widgets](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-slots-and-widgets) explains custom node content.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) explains the instance's renderer and engine access.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) covers persistence beyond framework specs.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) covers container sizing and visual configuration.

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

# Angular quick start

Mount a standalone Angular canvas with two connected nodes, two-way data bindings and a button that frames the diagram through `viewChild`.

Framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior.

## Prerequisites

Use an existing standalone Angular CLI application. The binding supports Angular 18.1, 19, 20, 21 and 22, with RxJS `^7.8.0`. Keep `@angular/common`, `@angular/core`, `@angular/forms` and `@angular/platform-browser` on the same Angular version as your application. This sample runs in the browser.

## 1. Install the binding

Run this in your application's directory:

```bash
npm install @grafloria/angular@0.14.0 @grafloria/renderer@0.5.0 @grafloria/engine@0.4.0 @grafloria/element@0.5.0 rxjs@^7.8.0
```

You get the Angular component and its engine, renderer and element peers. Import [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) into your standalone component; the canvas needs no library stylesheet import, NgModule or provider.

## 2. Define the flow and mount the canvas

Replace `src/app/app.component.ts` with the following component. Describe the initial data with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec). The binding accepts both specs and live models, so use [`NodeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#nodeinput) and [`EdgeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#edgeinput) for the two-way signals, matching the canvas's readonly, optional collection types.

```ts title="src/app/app.component.ts"
import { Component, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type {
  EdgeInput,
  EdgeSpec,
  NodeInput,
  NodeSpec,
} from '@grafloria/renderer';

const initialNodes: NodeSpec[] = [
  {
    id: 'a',
    position: { x: 60, y: 80 },
    size: { width: 180, height: 80 },
    label: 'Ingest',
  },
  {
    id: 'b',
    position: { x: 380, y: 80 },
    size: { width: 180, height: 80 },
    label: 'Publish',
  },
];
const initialEdges: EdgeSpec[] = [
  { id: 'e1', source: 'a', target: 'b' },
];

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="fit()">Fit diagram</button>
    <grafloria-diagram-canvas
      [(nodes)]="nodes"
      [(edges)]="edges"
      [plugins]="true"
      style="display:block; width:100%; height:400px"
    />
  `,
})
export class AppComponent {
  readonly nodes = signal<readonly NodeInput[] | undefined>(initialNodes);
  readonly edges = signal<readonly EdgeInput[] | undefined>(initialEdges);
  readonly canvas = viewChild.required(DiagramCanvasComponent);

  fit(): void {
    this.canvas().fitToContent(40);
  }
}
```

![Look at the arrow from Ingest to Publish, the Fit diagram button above the dotted canvas, the zoom/fit controls at bottom left and the minimap at bottom right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/44c320c4bdf4977c74f2b2f07fde3fdc.png)

The canvas shows **Ingest** on the left, **Publish** on the right and an edge between them. `[plugins]="true"` adds the shipped minimap, zoom/fit controls and background grid; you do not need to build those controls yourself. The component has an explicit 400-pixel height; see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) for container sizing.

`[(nodes)]` and `[(edges)]` form the controlled return path. The canvas reconciles incoming arrays into its live model, then writes new spec arrays back through the model signals when the model changes. Dragging a node therefore updates your application state, not only the rendered box. You do not need separate change handlers for these two-way bindings.

The `canvas` query gives you the mounted component. Click **Fit diagram** to call `fitToContent(40)`: it centers the content and chooses a zoom that leaves 40 screen pixels of padding. The method returns `void`. For engine access, `this.canvas().activeEngine()` returns the bound engine or the canvas-owned engine; make engine-touching setup calls in `ngAfterViewInit`, not the constructor.

## 3. Bootstrap and run

Use this browser entry point to mount `AppComponent` on the application's `<app-root>` element:

```ts title="src/main.ts"
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent).catch((error: Error) => {
  console.error(error);
});
```

Start your application:

```bash
ng serve
```

Open the local URL printed by the Angular CLI. Drag **Ingest**, then click **Fit diagram** to bring both nodes back into view. The component cleans up its plugins and rendering resources when Angular destroys it; this controlled sample does not require a manual disposal call.

You now have a sized canvas, two connected nodes, application state that receives diagram edits and imperative access through Angular's view query.

## Where next

Try the [live Angular starter](https://stackblitz.com/github/grafloria/grafloria/tree/main/starters/angular?file=src/app/app.component.ts), or open the [Angular demo gallery](https://grafloria.com/demos-angular/).

- [Angular: state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling) covers signals and component methods beyond this first canvas.
- [Angular: templates and handles](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-templates-and-handles) replaces the built-in node appearance with Angular templates.
- [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) arranges nodes automatically.
- [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works) explains specs, live models and the engine.

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

# Qwik quick start

Mount a 400-pixel-high diagram with two connected nodes, keep edits in serializable signals, and use the live instance from a Fit view button.

Framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior.

## Prerequisites

Use an existing Qwik 1.x application with `@builder.io/qwik` satisfying `^1.5.0` and `@grafloria/element` satisfying `^0.5.0`; see the [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start) for the shared engine and renderer prerequisites.

Keep your application's Qwik Vite configuration: no Grafloria-specific Vite plugin is required. This example runs in a server-rendered Qwik City application; the binding creates its live diagram in a browser-only task at document ready.

## 1. Install the binding and its peers

Run this in your application directory:

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

The Qwik package re-exports the shared spec types, so the component and its data types use one import site.

## 2. Mount a controlled canvas

Bind Qwik signals to [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) rather than React state; see the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start) for the shared [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) canvas setup.

The signals contain only plain data. Both change callbacks are QRLs created with Qwik's `$()`: they return the edited specs to the signals bound to `nodes` and `edges`.

`onInit$` gives you the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). Keep it in a signal marked with `noSerialize()` rather than asking Qwik to serialize a live renderer. The button uses that instance's `fitView()` to frame the content.

```tsx title="src/routes/index.tsx"
import { $, component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import {
  GrafloriaFlow,
  type DiagramInstance,
  type EdgeSpec,
  type NodeSpec,
} from '@grafloria/qwik';

export default component$(() => {
  const nodes = useSignal<NodeSpec[]>([
    {
      id: 'extract',
      position: { x: 80, y: 120 },
      size: { width: 180, height: 72 },
      label: 'Extract',
    },
    {
      id: 'load',
      position: { x: 380, y: 120 },
      size: { width: 180, height: 72 },
      label: 'Load',
    },
  ]);
  const edges = useSignal<EdgeSpec[]>([
    {
      id: 'extract-load',
      source: 'extract',
      target: 'load',
      sourceHandle: 'right',
      targetHandle: 'left',
    },
  ]);
  const instance = useSignal<NoSerialize<DiagramInstance>>();

  return (
    <section>
      <button
        type="button"
        disabled={!instance.value}
        onClick$={() => instance.value?.fitView(40)}
      >
        Fit view
      </button>
      <GrafloriaFlow
        nodes={nodes.value}
        edges={edges.value}
        fitView
        onNodesChange$={$((next: NodeSpec[]) => {
          nodes.value = next;
        })}
        onEdgesChange$={$((next: EdgeSpec[]) => {
          edges.value = next;
        })}
        onInit$={$((diagram: DiagramInstance) => {
          instance.value = noSerialize(diagram);
        })}
        style={{ height: '400px' }}
      />
    </section>
  );
});
```

The canvas draws Extract and Load side by side, with an edge from Extract's right port to Load's left port. `fitView` frames the initial content. The Fit view button stays disabled until `onInit$` supplies the instance.

![Extract and Load appear side by side with a right-pointing connecting arrow. The Fit view button sits above the canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/716c8c7fa06f395860eebb304430000e.png)

## 3. Run and edit the diagram

Start your Qwik application's development server:

```bash
npm run dev
```

Open the address printed by your application. Drag either node and use Fit view to frame the diagram again. The binding projects node and edge change events into specs for your callbacks; changes to the controlled arrays feed back into the mounted instance through `setNodes()` and `setEdges()`.

You now have a sized, editable canvas, controlled node and edge state, and instance access for your own controls. The binding disposes its diagram and removes its event subscriptions on unmount; do not dispose it in `onInit$`.

## Choose the state owner

Keep `nodes`, `edges`, and their change callbacks when your application owns the specs. For an uncontrolled canvas, use `defaultNodes` and `defaultEdges` instead: they seed the diagram at mount, rather than supplying ongoing controlled updates.

For more on serializable state and live objects, see [Qwik: state and resumption](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-state-and-resumption). For canvas sizing, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

## Where next

- Try the [live Qwik demos](https://grafloria.com/demos-qwik/) and inspect their source.
- Read [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) for controlled editing.
- Use [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) for instance access and teardown.
- Continue to [Qwik: custom content and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-custom-content-and-kits) for custom node components.

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

# How Grafloria works

Grafloria is a diagram engine whose framework bindings share one headless model, so your choice of framework changes how you bind data—not what the diagram means.

The five ideas below explain where to put data, edits, persistence and drawing code.

```mermaid
flowchart LR
  A["Application specs"] --> B["Binding / DiagramInstance"]
  B --> C["Live model: document data"]
  D["Engine: commands and history"] --> C
  C --> E["Renderer: geometry and pixels"]
  C --> F["Shared serialized document"]
  C --> B
  B --> A
```

## 1. Specs describe intent; live models hold data

Framework bindings convert plain specs into live models; the examples below trace those specs through reconciliation, command-backed edits and serialization—see the [introduction](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/introduction) for the API entry points.

This browser example uses [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) to mount two connected nodes. Its return value is the same instance facade the bindings expose. Install the packages in your own browser project:

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

Use [`RenderSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#renderspec) to check the input. `graph.ts` declares the data and a mounting function; your browser entry point calls it with a sized container.

```ts title="graph.ts"
import { render, type RenderSpec } from '@grafloria/element';

export const spec = {
  nodes: [
    { id: 'intake', label: 'Intake', position: { x: 60, y: 80 },
      size: { width: 120, height: 48 } },
    { id: 'review', label: 'Review', position: { x: 280, y: 80 },
      size: { width: 120, height: 48 } },
  ],
  edges: [{ id: 'next', source: 'intake', target: 'review' }],
} satisfies RenderSpec;

export function mountGraph(host: HTMLElement) {
  return render(spec, host);
}
```

```ts title="main.ts"
import { mountGraph } from './graph';

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

console.log(instance.getModel().getNode('intake'));
```

You see Intake connected to Review. The query returns the live node, not the input spec. For the full distinction, read [Specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models); for mounting and cleanup, read [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle).

The remaining browser entry files call the same mounting function. Run each separately alongside `graph.ts`.

## 2. Pick a state owner

Uncontrolled defaults seed the instance once; the instance owns subsequent edits. Controlled inputs make your application the state owner and require a return path for changes. Reconciliation updates existing spec-backed models by id rather than remounting the diagram, preserving live identity and leaving selection alone when you omit `selected`.

This sample changes Review's position through the instance's spec surface. The node moves down, and the identity assertion checks that the existing live object remains in use.

```ts title="reconcile.ts"
import { mountGraph, spec } from './graph';

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

const before = instance.getModel().getNode('review');
instance.setNodes(spec.nodes.map(node =>
  node.id === 'review'
    ? { ...node, position: { x: 280, y: 180 } }
    : node
));
instance.renderNow();
console.assert(before === instance.getModel().getNode('review'));
```

In a controlled component, connect both directions using the binding's own idiom:

| Binding | Input and change return path |
| --- | --- |
| React [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) | `nodes` / `edges` with `onNodesChange` / `onEdgesChange`; the state hooks convert live models back to specs. |
| Vue [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) | `v-model:nodes` / `v-model:edges` write changes back to your refs. |
| Qwik [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) | `nodes` / `edges` with `onNodesChange$` / `onEdgesChange$` return spec arrays. |
| Angular [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent) | `[(nodes)]` / `[(edges)]` round-trip through model signals. |

See [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) for this loop, and the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start) for the controlled-state wiring.

### React

Render the same two-node graph with uncontrolled defaults; the canvas owns subsequent edits. Type the arrays with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec).

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

```tsx title="Editor.tsx"
import { GrafloriaFlow } from '@grafloria/react';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { spec } from './graph';

const nodes: NodeSpec[] = spec.nodes;
const edges: EdgeSpec[] = spec.edges;

export default function Editor() {
  return <div style={{ height: '400px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
  </div>;
}
```

### Vue

The Vue component seeds the same graph with plain specs.

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

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

const nodes: NodeSpec[] = spec.nodes;
const edges: EdgeSpec[] = spec.edges;
</script>

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

### Qwik

The Qwik component passes serializable spec data, not a live instance.

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

```tsx title="Editor.tsx"
import { component$ } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { spec } from './graph';

const nodes: NodeSpec[] = spec.nodes;
const edges: EdgeSpec[] = spec.edges;

export default component$(() => (
  <div style={{ height: '400px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
  </div>
));
```

### Angular

Angular's two-way bindings keep application arrays in sync with edits to the same graph. Type component data with the library's `NodeSpec` and `EdgeSpec` types.

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

```ts title="editor.component.ts"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { spec } from './graph';

@Component({
  selector: 'app-editor',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class EditorComponent {
  nodes: readonly NodeSpec[] = spec.nodes;
  edges: readonly EdgeSpec[] = spec.edges;
}
```

## 3. Loading and editing are different intents

Setup writes directly to the model; user-facing edits become commands on the engine's history stack. Built-in gestures follow that second path: one drag is one undo step, not one step per position update.

Use engine methods that execute commands for your toolbar actions. Here, clicking **Add task** adds a labelled node and returns its live model. The engine's `addNode()` implementation constructs and executes a shipped add-node command, so the edit joins the same history as gestures.

```ts title="edit.ts"
import { mountGraph } from './graph';

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

const button = document.createElement('button');
button.textContent = 'Add task';
document.body.prepend(button);
let nextY = 180;

button.onclick = async () => {
  const y = nextY;
  nextY += 70;
  const node = await instance.getEngine().addNode({
    type: 'task',
    position: { x: 60, y },
    size: { width: 120, height: 48 },
    data: { label: 'New task' },
  });
  instance.renderNow();
  console.log(node);
};
```

For domain actions that need several mutations, execute command objects through `commandManager.execute()` rather than treating model writes as edits. Controlled bindings feed the reverted models back to application state after undo. Read [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) for command composition and history controls.

## 4. The document is the API

Save the live model in the shared serialization format, not a framework's projection of it. The versioned document carries nodes—including their ports—links, groups and viewport. It is the common representation for persistence and collaboration.

This sample adds a **Save document** button. Click it after editing to see JSON from the current live model in the page, including its `schemaVersion`.

```ts title="save.ts"
import { mountGraph } from './graph';

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

const button = document.createElement('button');
button.textContent = 'Save document';
const output = document.createElement('pre');
document.body.prepend(button);
document.body.append(output);

button.onclick = () => {
  const document = instance.getModel().serialize();
  const camera = instance.viewport.getState();
  output.textContent = JSON.stringify({ document, camera }, null, 2);
};
```

> **Known issue:** Serializing the model alone does not save the mounted canvas's current pan and zoom: camera changes do not update `DiagramModel.viewport`, and mounting a restored document does not apply its saved camera. Until it is fixed, save `instance.viewport.getState()` separately, as above, and after mounting restore it with `instance.viewport.setViewport(camera.viewport)` and `instance.viewport.setZoom(camera.zoom)`.

Kits follow the same model: ordinary nodes and edges plus a wiring step that attaches behavior to the mounted instance. Loading a document restores saved structure and reattaches built-in kit behavior; your application's custom painters still belong to your application. See [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for kit mounting, and [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for restoration.

## 5. Geometry is intent, not pixels

Declare what connects and how it routes; let the engine and renderer compute geometry as nodes move. In `EdgeSpec`, `router` says where the line goes, `connector` says how it is drawn, and `waypoints` constrain its bends. Endpoints can name nodes without pinning specific ports.

Groups also express intent: [`GroupSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#groupspec) names real children, not merely a rectangle behind them. This sample replaces the connection with an orthogonal route and puts both nodes in one fitted group. You see a group around Intake and Review with a right-angled connection between them.

```ts title="geometry.ts"
import { mountGraph, spec } from './graph';

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

instance.setNodes(spec.nodes.map(node =>
  node.id === 'review'
    ? { ...node, position: { x: 280, y: 180 } }
    : node
));
instance.setEdges([{
  id: 'next', source: 'intake', target: 'review',
  type: 'orthogonal',
}]);
instance.setGroups([{
  id: 'order', label: 'Order flow',
  children: ['intake', 'review'], padding: 30,
}]);
instance.renderNow();
```

For custom nodes, your component or renderer paints the inside of an engine-positioned HTML host. It does not take over dragging, selection, ports or connections. Continue with [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges), [Group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes), or [JavaScript: elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).

## See it running

Try the [live interaction demos](https://grafloria.com/demos/#interaction): drag a node, then undo the gesture. The [demo source](https://github.com/grafloria/grafloria/tree/main/demos) shows the same engine underneath the bindings.

<!-- source: specs-and-live-models.md -->

# Specs and live models

A spec is plain data that describes your diagram's intent; a live model is the identity-bearing object that holds that data while the diagram runs.

Follow a spec update through reconciliation to see what changes and which live objects retain their identity; see [Introduction](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/introduction) for the model, engine and instance entry points.

## From intent to live objects

The shared input layer converts specs into models and reconciles subsequent spec lists against those models. You do not need to construct engine objects to describe a flow.

```mermaid
flowchart LR
  S["Plain specs"] --> B["Framework binding or renderer instance"]
  B --> M["Live diagram model"]
  E["Engine: commands, layout, validation"] --> M
  M --> R["Renderer: visible geometry"]
  B --> R
```

| Intent you supply | Live object | What it holds |
| --- | --- | --- |
| [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) | [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel) | Type, position, size, payload, metadata and ports |
| [`PortSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-portspec) | [`PortModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-portmodel) | Direction, side, glyph, data type and connection constraints |
| [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) | [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel) | Endpoints, routing, connector, labels and bends |
| [`GroupSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance) | [`GroupModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-groupmodel) | Membership and frame geometry |

Give nodes and edges explicit, stable `id` values when you intend to update them. For a plain spec with an existing id, reconciliation updates the existing object rather than constructing another one. Entries without ids receive `node-<index>` or `edge-<index>` ids, so their identity depends on their position in the list.

## Payload and metadata have different jobs

Put application payload in `data`, such as an order status or domain identifier. Put diagram-adjacent settings in `metadata`. The node's top-level `label`, `sublabel` and `shape` fields are conveniences for `metadata.label`, `metadata.sublabel` and `metadata.shape`; they are not writes to `data`.

On the node update path, a supplied `data` object replaces the payload dictionary. Metadata entries are applied by key. An omitted `position` leaves an existing node where it is, and an omitted `selected` leaves the user's selection alone.

## Describe a flow, then query its live identity

Run this module in the browser. It creates a sized container and mounts the flow with [`render()`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core). It supplies two boxes, a labeled connection and a fitted zone, then changes the first box's label without replacing its live node.

Install the packages the module imports:

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

```ts title="configure-flow.ts"
import { render } from '@grafloria/element';
import type {
  EdgeSpec,
  GroupSpec,
  NodeSpec,
  PortSpec,
} from '@grafloria/renderer';

export function configureFlow() {
  const output: PortSpec = {
    id: 'intake-out', side: 'right', type: 'output',
  };
  const input: PortSpec = {
    id: 'review-in', side: 'left', type: 'input',
  };
  const nodes: NodeSpec[] = [
    {
      id: 'intake', label: 'Intake',
      position: { x: 80, y: 100 },
      size: { width: 150, height: 60 },
      data: { orderId: 'order-42', status: 'received' },
      metadata: { domain: 'orders' },
      ports: [output],
    },
    {
      id: 'review', label: 'Review',
      position: { x: 360, y: 100 },
      size: { width: 150, height: 60 },
      ports: [input],
    },
  ];
  const edges: EdgeSpec[] = [{
    id: 'handoff', source: 'intake', target: 'review',
    sourceHandle: 'intake-out', targetHandle: 'review-in',
    type: 'orthogonal', label: 'submit',
  }];
  const groups: GroupSpec[] = [{
    id: 'stage', label: 'Order processing',
    children: ['intake', 'review'], padding: 30,
    style: { fill: '#f3f4f6', stroke: '#d7dbe0' },
  }];

  const container = document.createElement('div');
  container.style.height = '400px';
  document.body.appendChild(container);
  const instance = render({ nodes, edges, groups }, container);

  const model = instance.getModel();
  const intakeBefore = model.getNode('intake');
  instance.setNodes(nodes.map(node =>
    node.id === 'intake' ? { ...node, label: 'Received' } : node
  ));
  instance.fitView();

  return {
    sameNode: intakeBefore !== undefined &&
      intakeBefore === model.getNode('intake'),
    outputPort: model.getPortById('intake-out'),
    handoff: model.getLink('handoff'),
    intakeIsMember: model.getGroup('stage')?.members.has('intake') ?? false,
  };
}

const result = configureFlow();
console.log(result);
```

![Received connects to Review through the submit arrow inside the Order processing zone.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/89bdcc2c9adf882e959bb22ce19e4eb8.png)

The container has a height of `400px`. The resulting diagram shows **Received** connected to **Review** inside **Order processing**. The returned `sameNode` is `true`; `outputPort` and `handoff` are live objects, and `intakeIsMember` is `true`. The setters return `void`; query the model when you need the objects they created.

These setters reconcile whole lists, not individual patches: an omitted node or link is removed. Removing a group through `setGroups()` keeps its boxes. For user-facing edits that belong on the undo stack, use [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) rather than treating reconciliation as an editing command.

## Geometry is intent, not a drawing instruction

Omit `ports` to get four deterministic bidirectional ports: top, right, bottom and left. Their ids use `<nodeId>__<side>`. Supply a port list when you need named endpoints, as the sample does. A handle pins an edge to a port; a bare side such as `'right'` also resolves to a port on that side.

In the sample, named handles resolve the edge spec to live ports, and the returned `handoff` exposes the resulting live link; see [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works) for endpoint and geometry intent. See [route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) and the [live edge demos](https://grafloria.com/demos/#edges).

A group is membership, not merely a rectangle behind nodes. Its `children` become members. `bounds` pins the frame; without it, reconciliation fits the frame around the children using `padding` (default `20`). Members travel with their group. See [group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes) and the [live group demos](https://grafloria.com/demos/#grouping).

## Specs are not the persistence format

The instance also accepts live nodes and links: [`NodeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance) is `NodeSpec | NodeModel`, and [`EdgeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance) is `EdgeSpec | LinkModel`. The repository's Mermaid viewer passes parsed nodes, links and groups directly to the renderer instead of reducing them to a smaller spec projection.

Save the live model in the shared, versioned document format, not a framework's projection. Read [documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for that boundary, and [state and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) for returning edits to controlled application state.

<!-- source: instance-and-lifecycle.md -->

# Instance and lifecycle

A [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance) is the live, renderer-level facade for one mounted diagram: it lets you update specs and pixels without rebuilding the editor.

Framework bindings are thin skins over one headless model. Specs describe your intent, live models hold the data, and the engine owns behavior. Keep the instance for the lifetime of its mounted host; update that instance, then dispose it when the host unmounts.

## One instance, three responsibilities

Instance access stays tied to the mounted diagram, not disconnected copies; see the [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start) for how to access its model and engine.

```mermaid
flowchart TD
  H["Mounted host or framework binding"] --> I["DiagramInstance"]
  S["New specs"] --> R["Reconcile by id"]
  R --> M["Live DiagramModel"]
  I -->|"getModel()"| M
  I -->|"getEngine()"| E["DiagramEngine: behavior"]
  E --> M
  M --> P["Queued repaint"]
  I -->|"renderNow()"| F["Synchronous repaint"]
  H -->|"Unmount"| D["dispose()"]
```

[`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) returns the instance in a browser application. React exposes it through `onInit`, and Vue through `@init`. Those are entry points to the same renderer-level surface, not separate diagram implementations.

In React, the binding mounts the instance in an effect and keeps callback props in a ref. New inline callbacks do not recreate it. For controlled and uncontrolled inputs, follow the [Qwik quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-quick-start); [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) covers the change-event return path.

## Reconciliation changes data, not the mount

Pass a complete next node list to `setNodes()` and a complete next edge list to `setEdges()`. With plain specs, existing ids update their live objects, new ids create objects, and missing ids remove objects. This preserves object identity rather than remounting the diagram. Omit `selected` to leave the user's selection alone.

The input types are [`NodeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec). Nodes can also be live models: a different live model supplied under an existing id replaces that model. Attached links survive only when the replacement has the same port id or a port on the same side; otherwise they are removed. Plain-spec reconciliation and live-model replacement are different paths; see [Specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models).

For externally edited imports with reused ids, follow the import guidance in the [Vue quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-quick-start).

## See updates on a mounted instance

This browser sample renders two connected nodes. **Reconcile** changes their labels and positions through specs. **Move together** moves both live models down in one batch. **Close** disposes the diagram and removes its host.

Install the packages the sample imports in your own browser TypeScript project:

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

```ts title="main.ts"
import { render } from '@grafloria/element';
import type { DiagramInstance, EdgeSpec, NodeInput } from '@grafloria/renderer';

function mountEditor(parent: HTMLElement): () => void {
  const panel = document.createElement('section');
  const controls = document.createElement('div');
  const host = document.createElement('div');
  host.style.height = '400px';
  panel.append(controls, host);
  parent.append(panel);

  const nodes = [
    { id: 'draft', label: 'Draft', position: { x: 80, y: 80 },
      size: { width: 140, height: 60 } },
    { id: 'review', label: 'Review', position: { x: 320, y: 80 },
      size: { width: 140, height: 60 } },
  ] satisfies NodeInput[];
  const edges: EdgeSpec[] = [
    { id: 'workflow', source: 'draft', target: 'review' },
  ];
  const instance: DiagramInstance = render({ nodes, edges }, host);

  const reconcile = document.createElement('button');
  reconcile.textContent = 'Reconcile';
  reconcile.onclick = () => {
    const nextNodes: NodeInput[] = [
      { id: 'draft', label: 'Draft updated', position: { x: 80, y: 140 },
        size: { width: 140, height: 60 } },
      { id: 'review', label: 'Review updated', position: { x: 320, y: 140 },
        size: { width: 140, height: 60 } },
    ];
    instance.setNodes(nextNodes);
    instance.setEdges(edges);
  };

  const move = document.createElement('button');
  move.textContent = 'Move together';
  move.onclick = () => {
    instance.batchUpdate((model) => {
      for (const node of model.getNodes()) {
        node.setPosition(node.position.x, node.position.y + 30);
      }
    });
  };

  const close = document.createElement('button');
  close.textContent = 'Close';
  const unmount = () => {
    reconcile.onclick = null;
    move.onclick = null;
    close.onclick = null;
    instance.dispose();
    panel.remove();
  };
  close.onclick = unmount;
  controls.append(reconcile, move, close);
  return unmount;
}

mountEditor(document.body);
```

The initial canvas shows Draft connected to Review from left to right, beneath the Reconcile, Move together, and Close controls.

The reconciliation calls schedule painting themselves. The batch follows the library's own example: mutate the models supplied to the callback rather than building an unrelated model. These are direct model updates; use commands for user-facing edits that need history, as described in [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

For an interactive example of instance access and engine behavior, open the [live drag-and-undo demo](https://grafloria.com/demos-react/#/interaction/drag-undo).

## Queued painting versus synchronous painting

Model mutation and painting have different timing. A setter updates the live data before the queued frame draws it. Choose the painting method according to what your next statement needs:

| Method | Returns | What you get |
| --- | --- | --- |
| `render()` | `void` | A queued repaint; repeated requests before the frame runs coalesce. |
| `renderNow()` | `void` | A synchronous repaint that cancels the pending frame and bypasses idle skipping. Use it before measuring changed diagram DOM. |
| `batchUpdate(mutate)` | `void` | Immediate mutations inside the callback, batched model events, and a queued repaint. It does not paint synchronously. |

Keep the batch callback synchronous. If you need to measure after a batch, call `renderNow()` after `batchUpdate()` returns. Nested batches remain batched, and a throwing callback does not leave the model stuck in batch mode.

## Dispose at unmount

In a plain browser host, call `dispose()` from the host's unmount or close handler, as above. Disposal detaches interaction handlers, cancels scheduled painting, disconnects the resize observer, removes listeners and custom-node hosts, and removes the diagram's DOM. Repeated disposal is a no-op.

The React binding performs disposal in its effect cleanup; let the binding own that teardown rather than disposing immediately after `onInit`. If you supply an external engine, instance disposal leaves that engine alive: its owner is responsible for destroying it.

For a flat cross-layer facade, [`createDiagramApi`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions) wraps an existing instance; it is not another mount. Continue with [React: state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions) for framework instance access, [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) for engine layout, or [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for persistence from the live model.

<!-- source: state-and-event-flow.md -->

# State and event flow

State ownership determines whether Grafloria keeps edits in its live model or returns them to your application so controlled inputs stay in sync.

The framework bindings are thin skins over one headless model: specs describe your intent, live models hold the data, and the engine owns behavior. You choose the owner separately for nodes, edges and, where supported, groups.

## Choose the state owner

| Input | Owner | What happens after mounting |
| --- | --- | --- |
| `defaultNodes`, `defaultEdges`, `defaultGroups` | The instance | Defaults seed the collections once. Changing a default later does not reconcile the collection. |
| `nodes`, `edges` | Your application | Updated inputs reconcile into the live model; change callbacks or two-way bindings return canvas edits. |
| `groups` | Your application supplies the group collection | Updated inputs reconcile group membership and frames. There is no corresponding group-change callback in the flow bindings. |

React, Vue and Qwik expose these default and controlled inputs. For an uncontrolled Angular canvas, leave `nodes` and `edges` unbound and pass an engine through `[engine]`. Its canvas has no `groups` or `defaultGroups` input.

Choose defaults for a self-contained canvas. Choose controlled inputs when an inspector or other application UI needs to mirror edits. Controlled specs reconcile into existing models rather than remounting the canvas. Stable node ids keep live identity; omitting `selected` leaves the current selection alone.

```mermaid
flowchart LR
  A["Application specs"] -->|"Controlled inputs"| B["Reconcile live models"]
  D["Defaults at mount"] --> B
  B --> C["Engine and renderer"]
  C -->|"User edits"| B
  B -->|"Change callback or model write"| A
```

Groups are zones with real membership, not a second list of nodes. A [`GroupSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#groupspec) names members through `children`; without `bounds`, its frame fits those members with padding. You can also pass a live [`GroupModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-groupmodel#groupmodel). Removing a group through `setGroups()` keeps its nodes. For group-edit persistence, read the live document rather than expecting a group-change callback; see [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

## Close the return path in your binding

These examples render two connected boxes and a selection count. Drag a box, release it, then select a box or the edge: the application mirrors the node and edge collections and displays the selected counts. React, Vue and Qwik also seed a zone through `defaultGroups`; the zone remains instance-owned.

Use the shared [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) vocabulary in each framework. Put this file beside the component you choose:

```ts title="graph.ts"
import type { NodeSpec, EdgeSpec, GroupSpec } from '@grafloria/renderer';

export const initialNodes: NodeSpec[] = [
  { id: 'a', label: 'Input', position: { x: 80, y: 100 },
    size: { width: 140, height: 70 } },
  { id: 'b', label: 'Output', position: { x: 320, y: 100 },
    size: { width: 140, height: 70 } },
];
export const initialEdges: EdgeSpec[] = [
  { id: 'ab', source: 'a', target: 'b' },
];
export const initialGroups: GroupSpec[] = [
  { id: 'pipeline', label: 'Pipeline', children: ['a', 'b'], padding: 40 },
];
```

### React

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow) calls `onNodesChange` with live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) objects and `onEdgesChange` with live [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel) objects. [`useNodesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#usenodesstate) and [`useEdgesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useedgesstate) convert those models back to specs. Their third tuple elements close the return path; their second elements are application state setters.

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

```tsx title="Editor.tsx"
import { useState } from 'react';
import { GrafloriaFlow, useNodesState, useEdgesState } from '@grafloria/react';
import { initialNodes, initialEdges, initialGroups } from './graph';

export default function Editor() {
  const [nodes, , onNodesChange] = useNodesState(initialNodes);
  const [edges, , onEdgesChange] = useEdgesState(initialEdges);
  const [selection, setSelection] = useState('0 nodes, 0 edges');

  return (
    <section>
      <p>Selected: {selection}</p>
      <GrafloriaFlow
        nodes={nodes} edges={edges} defaultGroups={initialGroups}
        onNodesChange={onNodesChange} onEdgesChange={onEdgesChange}
        onSelectionChange={({ nodes: pickedNodes, edges: pickedEdges }) =>
          setSelection(`${pickedNodes.length} nodes, ${pickedEdges.length} edges`)}
        style={{ height: 400 }}
      />
    </section>
  );
}
```

![Input connects to Output inside the Pipeline zone. The selection count starts at 0 nodes, 0 edges.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/102cf410caecc0fc6f1a1bd50bcf96dc.png)

Keep controlled arrays in state: React's inbound effects depend on their references. For the stale-state pitfall and the full hook contract, see [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start) and [React: state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions).

### Vue

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow) emits spec arrays through `update:nodes` and `update:edges`; `v-model` writes them into your refs. The `selection-change` event returns the selected live models, not a spec projection.

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

```vue title="Editor.vue"
<script setup lang="ts">
import { ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { initialNodes, initialEdges, initialGroups } from './graph';

const nodes = ref<NodeSpec[]>(initialNodes);
const edges = ref<EdgeSpec[]>(initialEdges);
const selection = ref('0 nodes, 0 edges');
</script>

<template>
  <section>
    <p>Selected: {{ selection }}</p>
    <GrafloriaFlow
      v-model:nodes="nodes" v-model:edges="edges"
      :default-groups="initialGroups"
      @selection-change="selection = `${$event.nodes.length} nodes, ${$event.edges.length} edges`"
      style="height: 400px"
    />
  </section>
</template>
```

Vue accepts replacement arrays and in-place changes and skips reapplying its own emitted arrays. See [Vue: state and composables](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-state-and-composables) for the reactive update paths.

### Qwik

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) projects live models to specs before invoking `onNodesChange$` and `onEdgesChange$`. Store those arrays in signals. The selection callback below stores only a string, not its live-model payload.

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

```tsx title="Editor.tsx"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { initialNodes, initialEdges, initialGroups } from './graph';

export default component$(() => {
  const nodes = useSignal<NodeSpec[]>(initialNodes);
  const edges = useSignal<EdgeSpec[]>(initialEdges);
  const selection = useSignal('0 nodes, 0 edges');

  return (
    <section>
      <p>Selected: {selection.value}</p>
      <GrafloriaFlow
        nodes={nodes.value} edges={edges.value} defaultGroups={initialGroups}
        onNodesChange$={(next) => { nodes.value = next; }}
        onEdgesChange$={(next) => { edges.value = next; }}
        onSelectionChange$={(change) => {
          selection.value = `${change.nodes.length} nodes, ${change.edges.length} edges`;
        }}
        style={{ height: '400px' }}
      />
    </section>
  );
});
```

See [Qwik: state and resumption](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-state-and-resumption) for storing and reaching a browser-only instance.

### Angular

[`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) exposes `nodes` and `edges` as two-way model signals. Its input types also accept live models, so use those declared unions for your signals. [`SelectionChange`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interfaces#selectionchange) contains the selected nodes and edges after the change.

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

```ts title="editor.component.ts"
import { Component, signal } from '@angular/core';
import { DiagramCanvasComponent, type SelectionChange } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import type { NodeModel, LinkModel } from '@grafloria/engine';
import { initialNodes, initialEdges } from './graph';

@Component({
  selector: 'app-editor',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <p>Selected: {{ selection() }}</p>
    <grafloria-diagram-canvas
      [(nodes)]="nodes" [(edges)]="edges"
      (selectionChange)="onSelection($event)"
      style="display:block; height:400px" />
  `,
})
export class EditorComponent {
  readonly nodes = signal<readonly (NodeSpec | NodeModel)[] | undefined>(initialNodes);
  readonly edges = signal<readonly (EdgeSpec | LinkModel)[] | undefined>(initialEdges);
  readonly selection = signal('0 nodes, 0 edges');

  onSelection(change: SelectionChange): void {
    this.selection.set(`${change.nodes.length} nodes, ${change.edges.length} edges`);
  }
}
```

![Input and Output are connected by an arrow, without a group frame. The selection count reads 0 nodes, 0 edges.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3c196653c74e554742dbeaea3ccc2f34.png)

Alongside the next-array outputs, `(modelChange)` emits an incremental patch of added, removed and modified entities, including groups. Inbound `nodes` and `edges` writes are not echoed as patches. `[skipModelUpdate]="true"` suspends inbound reconciliation while outbound emissions continue. See [Angular: state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling) for persistence and component methods.

## Learn the complete instance event map

[`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) exposes `on()` for the complete [`DiagramEventMap`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#diagrameventmap). Use your binding's events first; use the instance when it does not expose the event you need. `on()` returns an unsubscribe function; invoke it when your subscriber unmounts. `off()` removes a handler by identity.

| Event | Payload | What you receive |
| --- | --- | --- |
| `nodes:change` | `{ nodes: NodeModel[] }` | The current node collection, not a per-node delta. |
| `edges:change` | `{ edges: LinkModel[] }` | The current link collection. |
| `selection:change` | `{ nodes: NodeModel[]; edges: LinkModel[] }` | The selected nodes and edges after the change. |
| `connect` | `{ link: LinkModel }` | The added link; the model's link-add handler emits this, including programmatic additions. |
| `reconnect` | `{ link: LinkModel; endpoint: 'source' \| 'target' }` | The link and endpoint after a successful reconnection gesture. |
| `node:click` | `{ node: NodeModel; world: { x: number; y: number } }` | The clicked node and diagram coordinates. |
| `node:doubleclick` | `{ node: NodeModel; world: { x: number; y: number } }` | The double-clicked node and diagram coordinates. |
| `edge:click` | `{ edge: LinkModel; world: { x: number; y: number } }` | The clicked edge and diagram coordinates. |
| `viewport:change` | `{ viewport: Rectangle; zoom: number }` | The camera rectangle and zoom. |
| `ready` | `void` | A one-shot notification queued on a microtask after the initial paint. |

[`Rectangle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-b-s#rectangle) is the viewport rectangle type. The flow callbacks also expose initialization, layout completion and collaboration readiness; these are binding hooks, not extra names in `DiagramEventMap`.

React uses `onSelectionChange`, `onConnect`, `onNodeClick` and `onEdgeClick`; Vue uses `@selection-change`, `@connect`, `@node-click` and `@edge-click`; Qwik uses their `$` callback equivalents. Angular exposes `(selectionChange)` but no matching click or connect output on this canvas.

## Changes are not a per-frame state stream

In the shared instance, `node:changed` and `link:changed` schedule repainting without emitting collection-change events. Adds, removals and clears emit collections. The built-in node drag emits `nodes:change` after a moved drag ends; it does not send a new spec array on each pointer move. Selection has its own event and does not require rewriting the document collection.

Treat React, Vue and Qwik state as a mirror that catches up at edit boundaries, not as the animation clock. An arbitrary direct model mutation can repaint without triggering their collection callbacks. For user-facing edits and history, use the command path described in [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

Angular has a distinct outbound implementation: it captures model mutations and coalesces a burst into a microtask before emitting `modelChange` and the bound arrays. Do not assume its emissions share the instance's drag-commit timing, or that one array event equals one undo step.

For interaction feedback while drawing a connection, see [Configure editing gestures](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/configure-editing-gestures). Watch the [live connection-event demo](https://grafloria.com/demos/interaction/connection-events.html) for the connection lifecycle rather than treating collection changes as pointer-move events.

## Related

- [Specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models): the data carried in each direction.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle): instance access and subscription cleanup.
- [Group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes): membership and frames.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents): persistence beyond framework projections.

<!-- source: commands-and-history.md -->

# Commands and history

A command represents an undoable edit, so gestures and application actions can share the engine's history instead of maintaining separate undo stacks.

Loading and editing are different intents: setup mutates the live model directly; user-facing edits execute commands. The framework binding renders that model, while the engine owns execution and history.

## Two intents, one live model

Use [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel#diagrammodel) for setup and [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine) for editing:

| Intent | API | Result |
| --- | --- | --- |
| Seed a document | `diagram.addNode(node)` | Adds the node without recording a history entry. |
| Add a node on the user's behalf | `await engine.addNode(node)` | Executes the shipped add-node command and returns the live node. |
| Execute an explicit edit | `await engine.commandManager.execute(command)` | Executes and validates the command before recording an undoable entry. |
| Reverse or replay an edit | `await engine.undo()` / `await engine.redo()` | Changes the same model the canvas renders. |

```mermaid
flowchart LR
  Setup["Setup / import"] --> Model["Live diagram model"]
  Gesture["Canvas gesture"] --> Commands["Engine commands"]
  Action["Application action"] --> Commands
  Commands --> Model
  Commands --> History["One history stack"]
  History --> Reverse["Undo / redo"]
  Reverse --> Model
  Model --> Binding["Framework binding"]
  Binding --> Canvas["Rendered canvas"]
  Binding --> State["Controlled application state"]
```

Direct model additions are not recorded in history. Use an engine editing method or execute a command when a toolbar action must be undoable.

[`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) has no `undo()` or `redo()`: reach history through `instance.getEngine().undo()` and `instance.getEngine().redo()`. For a flat instance facade, [`createDiagramApi`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#creatediagramapi) exposes asynchronous `execute()`, `undo()` and `redo()` and requests a repaint after each call.

## Bundle an application action into one undo step

Use the shipped [`AddNodeCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r#addnodecommand) rather than implementing node addition yourself. Wrap independent additions in [`BatchCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r#batchcommand) when they form one user action. The batch executes its children in order and undoes them in reverse order.

This browser example mounts Angular's [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) with an engine, following its uncontrolled binding. It starts with a single node labelled **Loaded**. Select **Add pair** to add **Review** and **Ship** together; select **Undo** to remove both in one step. The loaded node remains. Drag a node, then undo: the drag joins that same history.

Install the 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
```

Construct the data with [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel). Replace your root component with this file:

```ts title="app.component.ts"
import { Component, OnDestroy, signal } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { AddNodeCommand, BatchCommand, DiagramEngine, NodeModel } from '@grafloria/engine';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button [disabled]="busy()" (click)="addPair()">Add pair</button>
    <button [disabled]="busy()" (click)="undo(canvas)">Undo</button>
    <button [disabled]="busy()" (click)="redo(canvas)">Redo</button>
    <p role="status">{{ status() }}</p>
    <grafloria-diagram-canvas #canvas [engine]="engine"
      style="display:block; height:400px" />
  `,
})
export class AppComponent implements OnDestroy {
  readonly engine = new DiagramEngine();
  readonly busy = signal(false);
  readonly status = signal('Loaded is setup data, not an undo step.');
  private nextPair = 0;

  constructor() {
    const diagram = this.engine.createDiagram('History example');
    const loaded = this.makeNode('loaded', 'Loaded', 60, 60);
    diagram.addNode(loaded);
  }

  private makeNode(id: string, label: string, x: number, y: number): NodeModel {
    const node = new NodeModel({
      id,
      type: 'default',
      position: { x, y },
      size: { width: 140, height: 50 },
    });
    node.setData('label', label);
    return node;
  }

  async addPair(): Promise<void> {
    const pair = ++this.nextPair;
    const y = 140 + (pair - 1) * 70;
    const review = this.makeNode(`review-${pair}`, 'Review', 60, y);
    const ship = this.makeNode(`ship-${pair}`, 'Ship', 260, y);
    await this.run(() => this.engine.commandManager.execute(
      new BatchCommand('Add review and ship', [
        new AddNodeCommand(review),
        new AddNodeCommand(ship),
      ]),
    ));
  }

  async undo(canvas: DiagramCanvasComponent): Promise<void> {
    await this.run(() => canvas.undo());
  }

  async redo(canvas: DiagramCanvasComponent): Promise<void> {
    await this.run(() => canvas.redo());
  }

  private async run(action: () => Promise<void>): Promise<void> {
    if (this.busy()) return;
    this.busy.set(true);
    try {
      await action();
      this.status.set(
        `Can undo: ${this.engine.canUndo()}; can redo: ${this.engine.canRedo()}`,
      );
    } catch (error) {
      this.status.set(error instanceof Error ? error.message : 'Command failed.');
    } finally {
      this.busy.set(false);
    }
  }

  ngOnDestroy(): void {
    this.engine.dispose();
  }
}
```

The canvas's `undo()` and `redo()` methods delegate to its active engine and schedule rendering. The status text reports history availability after a toolbar operation; it is not a subscription to every gesture. Use `engine.canUndo()` and `engine.canRedo()` to drive availability in your own controls.

Batching history is different from batching rendering. `instance.batchUpdate()` applies model mutations as one frame; it does not turn direct model writes into undoable commands.

## Await execution and handle refusal

[`Command`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r#command) permits both synchronous and asynchronous `execute()` and `undo()` implementations. Its default `redo()` re-executes the command. The command manager awaits these operations, so await execution before reading the resulting model or issuing a dependent edit. `execute()`, `undo()` and `redo()` on the manager return `Promise<void>`, not a success flag.

History contains only successfully executed, validated commands that declare themselves undoable through `isUndoable()`. Refusal leaves no new entry:

- If `canExecute(context)` returns `false`, execution rejects before applying the command. For example, `AddNodeCommand` refuses an id already in the diagram. Catch the rejection and report it to the user.
- With real-time validation enabled and strict validation configured, an invalid result is undone and execution rejects. The failed command does not enter history.
- A read-only document refuses execution without throwing; the manager emits `command:refused` and returns. Promise resolution alone therefore does not prove that an edit occurred.

A batch checks every child's `canExecute()` against the pre-batch state. Do not put an action in a batch if it becomes executable only after an earlier child runs. The pair above works because both node ids are absent before execution.

## Keep application state on the same history

An undo changes the engine's live models, not a separate framework snapshot. In controlled mode, the binding returns those changes to your application: Angular writes through `[(nodes)]` and `[(edges)]`; Vue updates `v-model:nodes`; React calls `onNodesChange`.

Keep that return path connected rather than maintaining another undo stack over your specs. See [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) for controlled bindings and [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) for instance ownership.

For a gesture-driven example, open the [live interaction demos](https://grafloria.com/demos/#interaction), drag a node, then press ⌘Z or Ctrl+Z. One drag is one undo step, not one step per position update.

## Related

- [Specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models) explains the data commands mutate.
- [Add editor controls](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/add-editor-controls) connects application controls to editing.
- [Synchronize editors](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/synchronize-editors) covers sharing document changes between peers.

<!-- source: documents-and-kits.md -->

# Documents and kits

A document is Grafloria's versioned, shared representation of a diagram; a kit turns domain data into specs plus the wiring that makes those specs interactive.

The document is the API: save the live model, not a framework's projection of it. Framework bindings are thin skins over that model, so the persistence boundary does not depend on which binding draws the canvas.

## How the parts fit together

```mermaid
flowchart LR
  Data["Domain data"] --> Kit["Kit builder"]
  Kit --> Spec["Specs + finalize"]
  Spec --> Mount["Mounted instance"]
  Mount --> Save["Serialize live model"]
  Save --> Document["Shared document"]
  Document --> Load["fromDocument()"]
  Load --> Spec
```

[`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) mounts a spec and returns a [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). It invokes the spec's `finalize` after creating the instance. That ordering matters: a kit can declare nodes and edges before mounting, but row interactions, positioned labels and dashboard grid bindings need the live instance.

[`erDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#erdiagram) builds table cards with column-level ports. [`umlDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#umldiagram) builds class cards; its finalization adds multiplicity labels. [`dashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-functions#dashboard) builds widgets and wires their boards. Pass the whole returned spec to the host rather than extracting only its `nodes` and `edges`.

## Save data, restore runtime behavior

[`DiagramSerializer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization#diagramserializer) provides two persistence shapes:

| Shape | What you get | Use |
| --- | --- | --- |
| `serialize(model)` | A flat object with serializer format `version` and the model's `diagramVersion` | Existing flat-format storage |
| `serializeEnvelope(model)` | A portable envelope containing the document, writer identity, creation time and an integrity checksum | New persistence |

The inner document has a `schemaVersion` separate from the model's mutation counter. Loading runs schema migrations; an envelope checksum mismatch throws instead of silently loading altered data.

The [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel#diagrammodel) serializes nodes, links, groups, metadata and viewport, plus ink and comments when present. [`fromDocument`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#fromdocument) accepts either persistence shape or its JSON string. It returns a [`LoadedDiagramSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#loadeddiagramspec) containing live models, not rebuilt spec projections. Its finalization restores groups and ink and reattaches ER/UML interaction wiring and dashboard binders. Its widget painter uses the same shipped renderer as the dashboard authoring path.

Functions do not travel in JSON. Supply your application widget painter again through `fromDocument`'s `renderWidget` option. A loaded dashboard also lacks the runtime `responsive` configuration; it starts with the saved column count. See [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for the distinction between documents and framework spec projections.

### A mounted document round trip

Run this in a browser project. The first canvas shows Customer and Order table cards joined at their `id` and `customer_id` rows; the second opens the saved document with the same cards and field-port connection.

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

Use this small kit builder in the examples below. Its return value is typed by the library's builder rather than a handwritten copy of its spec type.

```ts title="schema.ts"
import { erDiagram } from '@grafloria/element';

export function buildSchema() {
  return erDiagram({
    entities: [
      { id: 'CUSTOMER', name: 'Customer', position: { x: 40, y: 60 }, columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'email', type: 'varchar' },
      ] },
      { id: 'ORDER', name: 'Order', position: { x: 360, y: 60 }, columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'customer_id', type: 'int', fk: true },
      ] },
    ],
    relationships: [{ from: 'ORDER.customer_id', to: 'CUSTOMER.id' }],
  });
}
```

> **Known issue:** `render(fromDocument(json), host)` installs the loaded entities into a new model but does not adopt the saved diagram identity, diagram-level metadata, comments or viewport. Until it is fixed, attach the loaded model to an engine and pass its camera values explicitly when mounting.

The workaround still uses `render` for mounting and kit finalization. [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine) is needed here only to retain the entire deserialized model, rather than transferring its entities into a fresh one.

> **Known issue:** Panning and zooming the mounted canvas do not update `model.viewport`. Until it is fixed, copy the instance camera into the model immediately before serialization, as `saveDocument()` does below. Call it again whenever you save after a camera change.

```ts title="main.ts"
import { render, fromDocument } from '@grafloria/element';
import { DiagramEngine, DiagramSerializer } from '@grafloria/engine';
import { buildSchema } from './schema';

const originalHost = document.createElement('div');
const reopenedHost = document.createElement('div');
for (const host of [originalHost, reopenedHost]) {
  host.style.height = '400px';
  document.body.appendChild(host);
}

const original = render(buildSchema(), originalHost);
const serializer = new DiagramSerializer();
export function saveDocument() {
  const model = original.getModel();
  model.viewport = {
    ...original.viewport.getViewport(),
    zoom: original.viewport.getZoom(),
  };
  return JSON.stringify(serializer.serializeEnvelope(model));
}
const json = saveDocument();
const loaded = fromDocument(json);
const engine = new DiagramEngine();
engine.setDiagram(loaded.model);
const reopened = render(loaded, reopenedHost, {
  engine,
  viewport: { x: loaded.model.viewport.x, y: loaded.model.viewport.y },
  zoom: loaded.model.viewport.zoom,
});

// Call when your application removes these canvases.
export function unmount() {
  reopened.dispose();
  original.dispose();
  reopenedHost.remove();
  originalHost.remove();
}
```

![Customer and Order table cards with their field-port connection on the original and reopened canvases.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/8f8382a48c2da78208bfc9693ed024b7.png)

This saves document data, not an undo stack or a serialized renderer. The loader reconstructs the kit's runtime wiring after mounting.

## The same kit contract in each binding

Each host below renders the same two table cards from `schema.ts` and runs their finalization through `render`. Start in your framework project; install the binding you use in addition to the shared packages above.

### React

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadiagram) for the complete kit spec. The component disposes its instance on unmount.

```bash
npm install @grafloria/react react react-dom
```

```tsx title="SchemaView.tsx"
import { GrafloriaDiagram } from '@grafloria/react';
import { buildSchema } from './schema';

const spec = buildSchema();

export default function SchemaView() {
  return <div style={{ height: '400px' }}><GrafloriaDiagram spec={spec} /></div>;
}
```

![React renders Customer and Order cards with PK and FK rows joined by a connection.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/be27f1ec56a544029199bbad11ba90a9.png)

### Vue

Pass the spec to Vue's [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadiagram). Its `ready` event provides the mounted instance when you need to serialize it.

```bash
npm install @grafloria/vue vue
```

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

const spec = buildSchema();
</script>

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

Vue renders Customer and Order cards with their column types and field-port connection.

### Angular

[`GrafloriaDiagramComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#grafloriadiagramcomponent) is the generic kit host, not a canvas assembled from projected node arrays. Its `ready` output provides the live instance.

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

```ts title="schema-view.component.ts"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { buildSchema } from './schema';

@Component({
  selector: 'app-schema-view',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: '<grafloria-diagram [spec]="spec" style="height:400px" />',
})
export class SchemaViewComponent {
  readonly spec = buildSchema();
}
```

Angular renders Customer and Order table cards connected at their rows.

### Qwik

Qwik's [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadiagram) builds the kit in the browser through `spec$`. Do not put function-bearing kit specs in resumable state. The builder runs once per mount; change the component `key` when new schema data needs a fresh build.

```bash
npm install @grafloria/qwik @builder.io/qwik
```

```tsx title="schema-view.tsx"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { buildSchema } from './schema';

export default component$(() => {
  const schemaVersion = useSignal(1);
  const instance = useSignal<NoSerialize<DiagramInstance>>();

  return (
    <GrafloriaDiagram
      key={schemaVersion.value}
      spec$={() => buildSchema()}
      onReady$={(ready) => { instance.value = noSerialize(ready); }}
      style={{ height: '400px' }}
    />
  );
});
```

Qwik renders Customer and Order table cards with PK and FK badges and a connection.

Create live transports and stores in `useVisibleTask$` and retain them with `noSerialize()`, as with the instance above. A [`CommentStore`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-comments#commentstore) holds subscribers, not resumable data. On [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow), a live collaboration object likewise needs `noSerialize()`; plain node and edge data do not. See [Qwik: custom content and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-custom-content-and-kits) for browser-side kit construction.

## Mermaid is a body plus a sidecar

`instance.exportText()` returns Mermaid-compatible text with a `%%grafloria:document` comment by default. Mermaid ignores that comment; Grafloria reads the document inside it. This preserves data that the Mermaid body cannot express, including exact geometry and styling.

The sidecar deliberately excludes selected, hovered and focused entity state and derived link polylines. User-authored manual bends remain. “Lossless” here means document intent, not every viewer's transient state or every routed pixel.

The following browser sample uses a [`DiagramSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#diagramspec) to mount a labeled connection, exports its text, then loads it into a second canvas. You see Start connected to Finish on both canvases.

```ts title="text-round-trip.ts"
import { render, type DiagramSpec } from '@grafloria/element';

const spec: DiagramSpec = {
  nodes: [
    { id: 'start', label: 'Start', position: { x: 40, y: 80 } },
    { id: 'finish', label: 'Finish', position: { x: 340, y: 80 } },
  ],
  edges: [{ id: 'route', source: 'start', target: 'finish', label: 'next' }],
};
const firstHost = document.createElement('div');
const secondHost = document.createElement('div');
for (const host of [firstHost, secondHost]) {
  host.style.height = '400px';
  document.body.appendChild(host);
}
const first = render(spec, firstHost);
const text = first.exportText();
const second = render(spec, secondHost);
const result = second.loadText(text);
console.log(result.source, result.bodyEdited, result.sidecarInvalid);

export function unmount() {
  second.dispose();
  first.dispose();
  secondHost.remove();
  firstHost.remove();
}
```

![Both canvases show Start connected to Finish by an arrow labeled next.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4e46898c885b232a73d861d427ead8e5.png)

`loadText()` returns an [`ImportTextResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization#importtextresult) and reconciles into the existing model, preserving its listeners and plugins. In the default `prefer: 'auto'` mode, an unchanged body uses the sidecar; an edited body applies structure and labels on top of the sidecar data. Invalid sidecar JSON sets `sidecarInvalid` and falls back to parsing the body. Unsupported or invalid diagram text makes `loadText()` throw before changing the canvas.

`loadText()` is an entity reconciliation path, not a whole-document camera or comment restoration path. Use the document loader above when opening a complete saved document. See [Import diagram text and files](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/import-diagram-text-and-files) for format selection and parse results.

## Dashboard snapshots are a domain format

A dashboard combines geometry, widget state, and persistence/history in one document. A widget's kind, payload and grid cell describe the same live board that gestures edit; you do not maintain a second widget registry beside the layout.

The dashboard handle's `toJSON()` returns dashboard authoring data that `dashboard()` accepts again. It reads live cells and membership, including nested containers, rather than the original widget arrays. Unlike a generic framework spec projection, it is a supported domain round trip. Unlike the shared diagram document, it describes dashboard options, views and widgets rather than arbitrary diagram entities.

This browser sample renders the shipped KPI widget twice: once from authoring data and once from the mounted board's snapshot. No custom widget painter is needed.

```ts title="dashboard-round-trip.ts"
import { dashboard, render } from '@grafloria/element';

const firstHost = document.createElement('div');
const secondHost = document.createElement('div');
for (const host of [firstHost, secondHost]) {
  host.style.height = '400px';
  document.body.appendChild(host);
}
const spec = dashboard({
  columns: 4,
  widgets: [{
    id: 'revenue', kind: 'kpi', span: 2,
    data: { label: 'Revenue', value: '$6.8M', delta: 12.4 },
  }],
});
const first = render(spec, firstHost);
const saved = spec.handle.toJSON();
const restoredSpec = dashboard(saved);
const second = render(restoredSpec, secondHost);

export function unmount() {
  second.dispose();
  first.dispose();
  secondHost.remove();
  firstHost.remove();
}
```

![Original and restored Revenue KPI cards each show $6.8M and a green 12.4% comparison.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/00cb2d812acd12e0111a1c0f66e7672f.png)

The snapshot omits the `renderWidget` and `onLayoutChange` function seams; supply them again when rebuilding a board that uses them. Use `DiagramSerializer` instead when saving the shared diagram document, and `fromDocument` to regain both its live models and its dashboard handle.

## Explore next

- [Live ER diagram](https://grafloria.com/demos/diagrams/table-er.html) — table cards and relationships from domain data.
- [Live UML diagram](https://grafloria.com/demos/diagrams/class-uml.html) — class compartments and relationship markers.
- [Live dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html) — widgets, board geometry and editing together.
- [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) and [Arrange dashboard containers](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/arrange-dashboard-containers) — author and edit boards.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) — persistence procedures and projection boundaries.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) — how user-facing edits join the history stack.

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

# Edit nodes

Use an external inspector when your application needs to edit a node without putting every control inside the canvas. The examples below render a fixed-size node and a content-sized node, then let you edit a target by `nodeId`, add and delete nodes, and undo committed payload changes.

Specs describe intent; live models hold data. Use the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) to get the model and engine. Loading and editing are different intents: tracked model setters update live data, while commands put user-facing changes on the history stack.

## 1. Share the data and inspector

Create `inspector.ts` in your browser application's source directory. The framework examples in the next step import this file.

The data uses [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec). `fixed` starts at 200 × 80; `auto` starts at 60 × 36 and fits its longer label through `metadata.sizing.auto`.

The inspector uses the mounted [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine). `addNode()` returns the live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) and executes the shipped [`AddNodeCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r#addnodecommand); `removeNode()` executes [`RemoveNodeCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r#removenodecommand). You do not need to construct those commands yourself.

For payload commits, execute the shipped [`SetNodeDataCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-r-u#setnodedatacommand). This is the command surface for an inspector edit: it changes only the supplied data keys and restores those keys on undo.

```ts title="inspector.ts"
import { NodeModel, SetNodeDataCommand, type DiagramEngine } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const initialNodes: NodeSpec[] = [
  {
    id: 'fixed', position: { x: 80, y: 80 },
    size: { width: 200, height: 80 }, label: 'Draft',
    data: { note: 'Review pending' },
  },
  {
    id: 'auto', position: { x: 80, y: 230 },
    size: { width: 60, height: 36 },
    label: 'This node fits its longer label',
    metadata: { sizing: { auto: true, padding: 10 } },
    data: { note: 'Content-sized' },
  },
];
export const initialEdges: EdgeSpec[] = [
  { id: 'connection', source: 'fixed', target: 'auto' },
];

let nextNodeId = 0;

export function mountInspector(
  host: HTMLElement,
  engine: DiagramEngine,
  repaint: () => void,
): () => void {
  engine.setInteractionConfig({ enableInPlaceTextEdit: true });
  const abort = new AbortController();
  const panel = document.createElement('div');
  panel.style.cssText = 'display:flex;flex-wrap:wrap;gap:12px;padding:12px;font:14px sans-serif';
  host.append(panel);

  function field(caption: string, value: string, type = 'text'): HTMLInputElement {
    const label = document.createElement('label');
    label.append(`${caption} `);
    const input = document.createElement('input');
    input.type = type;
    input.value = value;
    input.style.width = type === 'number' ? '70px' : '160px';
    label.append(input);
    panel.append(label);
    return input;
  }

  const target = field('nodeId', 'fixed');
  const label = field('Label (live)', 'Draft');
  const note = field('Note', 'Review pending');
  const width = field('Width', '200', 'number');
  const height = field('Height', '80', 'number');
  width.min = height.min = '1';
  const status = document.createElement('output');
  panel.append(status);

  function node(): NodeModel | undefined {
    return engine.getDiagram()?.getNode(target.value);
  }

  function refresh(): void {
    const current = node();
    if (!current) {
      status.textContent = 'Target not found';
      return;
    }
    label.value = current.getLabel() ?? '';
    note.value = typeof current.data.note === 'string' ? current.data.note : '';
    width.value = String(current.size.width);
    height.value = String(current.size.height);
    status.textContent = `Current note: ${note.value}`;
  }

  function button(caption: string, action: () => Promise<void>): void {
    const control = document.createElement('button');
    control.type = 'button';
    control.textContent = caption;
    control.addEventListener('click', () => {
      void action().then(() => {
        repaint();
        refresh();
      }).catch((error: Error) => { status.textContent = error.message; });
    }, { signal: abort.signal });
    panel.append(control);
  }

  target.addEventListener('input', refresh, { signal: abort.signal });
  label.addEventListener('input', () => {
    node()?.setMetadata('label', label.value);
    repaint();
  }, { signal: abort.signal });

  const resize = () => {
    const w = Number(width.value);
    const h = Number(height.value);
    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
      node()?.setSize(w, h);
      repaint();
    }
  };
  width.addEventListener('input', resize, { signal: abort.signal });
  height.addEventListener('input', resize, { signal: abort.signal });

  button('Apply note', async () => {
    if (!node()) throw new Error('Choose an existing nodeId');
    await engine.commandManager.execute(
      new SetNodeDataCommand(target.value, { note: note.value }),
    );
  });
  button('Add', async () => {
    let id: string;
    do { id = `inspector-node-${++nextNodeId}`; }
    while (engine.getDiagram()?.getNode(id));
    const added = new NodeModel({
      id, type: 'rect',
      position: { x: 420, y: 80 }, size: { width: 180, height: 80 },
    });
    added.setMetadata('label', 'New node');
    const live = await engine.addNode(added);
    target.value = live.id;
  });
  button('Delete target', async () => {
    if (!node()) throw new Error('Choose an existing nodeId');
    await engine.removeNode(target.value);
  });
  button('Undo', async () => { await engine.undo(); });
  button('Redo', async () => { await engine.redo(); });
  refresh();

  return () => {
    abort.abort();
    panel.remove();
  };
}
```

The label and dimension fields are **live, non-history updates**. The Note field is a draft until you press **Apply note**; that button records one undoable payload edit. Add and delete also enter history. For undoable label editing, use the canvas's in-place editor described below rather than the live label field.

## 2. Mount the canvas in your framework

Install the packages for your framework in your own project.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

JavaScript mounts with [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render). Angular uses [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) and its `activeEngine()`. React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow), Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow), and Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) hand you the instance through their initialization callback or event.

Each sample mounts the same inspector above a 400-pixel canvas. The React, Vue and Qwik samples use uncontrolled defaults so the live instance owns edits. Angular uses two-way node and edge bindings so model changes return to application state.

:::code-group
```ts title="JavaScript"
// main.ts — run in the browser; call the returned cleanup when removing this view.
import { render } from '@grafloria/element';
import { initialNodes, initialEdges, mountInspector } from './inspector';

export function mountNodeEditor(parent: HTMLElement): () => void {
  const inspector = document.createElement('div');
  const canvas = document.createElement('div');
  canvas.style.height = '400px';
  parent.append(inspector, canvas);
  const instance = render({ nodes: initialNodes, edges: initialEdges }, canvas);
  const removeInspector = mountInspector(
    inspector, instance.getEngine(), () => instance.renderNow(),
  );
  return () => {
    removeInspector();
    instance.dispose();
    inspector.remove();
    canvas.remove();
  };
}

const root = document.createElement('div');
document.body.append(root);
export const unmountNodeEditor = mountNodeEditor(root);
```
```ts title="Angular"
// node-editor.component.ts
import { AfterViewInit, Component, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { initialNodes, initialEdges, mountInspector } from './inspector';

@Component({
  selector: 'app-node-editor',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div #inspector></div>
    <grafloria-diagram-canvas
      [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:400px" />
  `,
})
export class NodeEditorComponent implements AfterViewInit, OnDestroy {
  nodes: ReturnType<DiagramCanvasComponent['nodes']> = initialNodes;
  edges: ReturnType<DiagramCanvasComponent['edges']> = initialEdges;
  canvas = viewChild.required(DiagramCanvasComponent);
  inspector = viewChild.required<ElementRef<HTMLDivElement>>('inspector');
  private removeInspector?: () => void;

  ngAfterViewInit(): void {
    const canvas = this.canvas();
    const engine = canvas.activeEngine();
    if (!engine) return;
    this.removeInspector = mountInspector(
      this.inspector().nativeElement, engine, () => canvas.scheduleRender(),
    );
  }
  ngOnDestroy(): void { this.removeInspector?.(); }
}
```
```tsx title="Qwik"
// node-editor.tsx
import { component$, $, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { initialNodes, initialEdges, mountInspector } from './inspector';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const inspector = useSignal<HTMLDivElement>();

  useVisibleTask$(({ track, cleanup }) => {
    const api = track(() => instance.value);
    const host = inspector.value;
    if (!api || !host) return;
    cleanup(mountInspector(host, api.getEngine(), () => api.renderNow()));
  });

  return <>
    <div ref={inspector} />
    <div style={{ height: '400px' }}>
      <GrafloriaFlow defaultNodes={initialNodes} defaultEdges={initialEdges}
        onInit$={$((api: DiagramInstance) => { instance.value = noSerialize(api); })} />
    </div>
  </>;
});
```
```tsx title="React"
// NodeEditor.tsx
import { useEffect, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { initialNodes, initialEdges, mountInspector } from './inspector';

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

  function onInit(api: DiagramInstance): void {
    instance.current = api;
    removeInspector.current?.();
    if (inspector.current) {
      removeInspector.current = mountInspector(
        inspector.current, api.getEngine(), () => api.renderNow(),
      );
    }
  }
  useEffect(() => () => { removeInspector.current?.(); }, []);

  return <>
    <div ref={inspector} />
    <div style={{ height: 400 }}>
      <GrafloriaFlow defaultNodes={initialNodes} defaultEdges={initialEdges} onInit={onInit} />
    </div>
  </>;
}
```
```vue title="Vue"
<!-- NodeEditor.vue -->
<script setup lang="ts">
import { shallowRef, onUnmounted } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { initialNodes, initialEdges, mountInspector } from './inspector';

const inspector = shallowRef<HTMLDivElement>();
const instance = shallowRef<DiagramInstance>();
let removeInspector: (() => void) | undefined;
function onInit(api: DiagramInstance): void {
  instance.value = api;
  removeInspector?.();
  if (inspector.value) {
    removeInspector = mountInspector(
      inspector.value, api.getEngine(), () => api.renderNow(),
    );
  }
}
onUnmounted(() => { removeInspector?.(); });
</script>

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

## 3. Edit the target and test history

The JavaScript view starts with the inspector targeting Draft and an edge leading to the wider content-sized node.

![JavaScript inspector above Draft and the connected content-sized node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c85f76f3cbe887b58b082a4e7e2d97dc.png)

Angular, Qwik, React and Vue render the same initial nodes and the inspector's Apply note, Add, Delete target, Undo and Redo controls.

![Angular inspector targeting fixed, with the two connected nodes below.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/5439724aabab52b5f7ed588b0ab2f928.png)

1. Keep `nodeId` set to `fixed`. Type in **Label (live)**: the canvas text follows the input. Change Width or Height: the box changes size through `setSize()`.
2. Change Note and press **Apply note**. The Current note output shows the committed payload. Press Undo to restore the previous note, then Redo to reapply it. Payload data is separate from the display label; changing `note` does not replace the node's label.
3. Press Add. A new node appears to the right, and the inspector targets its generated id. Press Delete target to remove it. Undo restores it. Look up the node again by id after undo rather than retaining a model reference: deletion undo reconstructs models.
4. Set `nodeId` to `auto`. Lengthen its label: content-aware sizing grows it during rendering when the text needs more room. With this unconstrained node, manually enlarging the box survives subsequent renders; shortening the label does not shrink it.

Removing a node also removes its connected links and descendants; undo restores them. `removeNode()` rejects if the target does not exist, which the inspector reports instead of silently ignoring it.

### Commit labels in place

The shared inspector setup enables `enableInPlaceTextEdit` through `setInteractionConfig()`. Double-click a node to open the shipped label editor. Enter or blur commits the rename through a command; Escape cancels it. Undo and Redo then act on that rename. Angular also enables its in-place editing input by default.

For an external Rename action on an instance, call `beginLabelEdit({ type: 'node', nodeId: 'fixed' })`. It returns whether an editor opens; a missing, non-editable or read-only target returns `false`. An optional `{ seed: 'R' }` second argument starts with replacement text instead of selecting the existing label.

See the live [in-place label editing demo](https://grafloria.com/demos/nodes/edit-label.html) to try Enter, blur and Escape.

## Options that matter

| Option | Type | Default | What it does |
|---|---|---|---|
| `NodeSpec.id` | `string` | Optional | Gives your inspector a stable target for model lookup and commands. |
| `NodeSpec.label` | `string` | Optional | Supplies `metadata.label`, the display label. |
| `NodeSpec.data` | Payload record | Optional | Carries application data separately from the label. |
| `NodeSpec.size` | `{ width: number; height: number }` | Optional | Declares the box dimensions. |
| `metadata.sizing.auto` | `boolean` | Off unless `true` | Enables content-aware fitting during rendering. |
| `metadata.sizing.padding` | `number` | `8` | Adds padding around measured label content. |
| `metadata.sizing.minWidth`, `minHeight` | `number` | No per-node constraint | Sets lower bounds for content sizing and interactive resizing. |
| `metadata.sizing.maxWidth`, `maxHeight` | `number` | No per-node constraint | Sets upper bounds; `maxWidth` also supplies the label's wrap width during measurement. |

## Pitfalls

- Use tracked setters such as `setMetadata()`, `setData()` and `setSize()`, not raw assignments to live fields. Setters notify the model's change tracking. They do not themselves create history entries; use a command for a committed inspector action.
- `metadata.label` takes precedence over a legacy `data.label`. A payload command that writes `data.label` does not rename a node with a canonical label; use the label editor for that task.
- With auto-sizing enabled, the renderer grows the current dimensions to accommodate content, subject to sizing constraints. A manual enlargement of the unconstrained `auto` node remains; a manual reduction can grow again if the label needs more room.
- For controlled inputs, keep the framework's change-event return path. See the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start) and [Vue quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-quick-start).
- For engine history, explicit layout after edits, and repainting custom HTML content, see [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history), [lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram), and [JavaScript elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).

## Live demos and related guides

- [Updating nodes](https://grafloria.com/demos/nodes/updating-nodes.html): live label, background and width controls. [Source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/nodes/updating-nodes.html).
- [Auto-sizing](https://grafloria.com/demos/nodes/auto-sizing.html): compare a content-sized node with a fixed-size control.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents): persist the live document rather than a framework projection.

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

# Validate port connections

Use declared ports when your editor needs named inputs and outputs rather than interchangeable attachment points. The example renders a number pipeline, `A → B → C`, plus a string input. Number ports paint blue; the string port paints purple. Matching types connect, full inputs refuse another wire, and a cycle validator prevents `C → A`.

Ports decide where links attach and which connections are legal: declare them in specs, let the engine enforce the rules, and let the renderer draw the glyphs.

## 1. Declare the ports and their rules

In your browser application's source directory, create `ports.ts`. All five bindings below import this file. Use the library's [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`PortSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-portspec) vocabulary rather than constructing live ports yourself. [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) names the ports used by the initial pipeline through `sourceHandle` and `targetHandle`.

The two inputs on B inherit a square glyph, inside labels, and an evenly spaced left-edge column from `metadata.portGroups.inputs`. Each member supplies its own id and label text. A and C use diamond outputs. The setup function receives the mounted [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) so the cycle rule queries its current diagram.

> **Known issue:** Declaring `type: 'input'` or `type: 'output'` alone does not enforce start-only/end-only direction: the connection rule rejects equal non-`bi` types, but does not reject an input-to-output wire. Until it is fixed, also set `gating.isConnectableStart: false` on inputs and `gating.isConnectableEnd: false` on outputs, as below.

```ts title="ports.ts"
import { portTypeRegistry, type DiagramEngine } from '@grafloria/engine';
import {
  registerConnectionValidator,
  type NodeSpec,
  type PortSpec,
  type EdgeSpec,
  type DiagramInstance,
} from '@grafloria/renderer';

function input(id: string, dataType: string): PortSpec {
  return {
    id, side: 'left', type: 'input', dataType,
    shape: { shape: 'square', size: 12 },
    label: { text: dataType, layout: 'inside' },
    gating: { isConnectableStart: false, toMaxLinks: 1 },
  };
}

function output(id: string): PortSpec {
  return {
    id, side: 'right', type: 'output', dataType: 'number',
    shape: { shape: 'diamond', size: 14 },
    label: { text: 'out', layout: 'inside' },
    gating: { isConnectableEnd: false },
  };
}

export const nodes: NodeSpec[] = [
  {
    id: 'a', label: 'A', position: { x: 60, y: 100 },
    size: { width: 150, height: 100 },
    ports: [input('a-in', 'number'), output('a-out')],
  },
  {
    id: 'b', label: 'B', position: { x: 290, y: 100 },
    size: { width: 150, height: 100 },
    metadata: {
      portGroups: {
        inputs: {
          id: 'inputs', side: 'left',
          shape: { shape: 'square', size: 12 },
          label: { layout: 'inside' },
          layout: { strategy: 'sideLinear', args: { padding: 10 } },
        },
      },
    },
    ports: [
      {
        id: 'b-x', group: 'inputs', type: 'input', dataType: 'number',
        label: { text: 'x' },
        gating: { isConnectableStart: false, toMaxLinks: 1 },
      },
      {
        id: 'b-y', group: 'inputs', type: 'input', dataType: 'number',
        label: { text: 'y' },
        gating: { isConnectableStart: false, toMaxLinks: 1 },
      },
      output('b-out'),
    ],
  },
  {
    id: 'c', label: 'C', position: { x: 520, y: 100 },
    size: { width: 150, height: 100 },
    ports: [input('c-in', 'number'), output('c-out')],
  },
  {
    id: 's', label: 'String input', position: { x: 520, y: 290 },
    size: { width: 150, height: 100 },
    ports: [input('s-in', 'string')],
  },
];

export const edges: EdgeSpec[] = [
  {
    id: 'ab', source: 'a', target: 'b',
    sourceHandle: 'a-out', targetHandle: 'b-x',
  },
  {
    id: 'bc', source: 'b', target: 'c',
    sourceHandle: 'b-out', targetHandle: 'c-in',
  },
];

export function installPortRules(engine: DiagramEngine): () => void {
  engine.setInteractionConfig({ enableLinkReconnection: false });
  portTypeRegistry.registerAll([
    { name: 'number', color: '#2563eb', compatibleWith: ['number'] },
    { name: 'string', color: '#9333ea', compatibleWith: ['string'] },
  ]);

  const model = engine.getDiagram();
  if (!model) throw new Error('Mount the canvas before installing port rules.');

  return registerConnectionValidator(({ sourceNode, targetNode }) => {
    // The registry is global. Apply this rule only to this mounted model.
    if (model.getNode(sourceNode.id) !== sourceNode ||
        model.getNode(targetNode.id) !== targetNode) return true;

    const seen = new Set<string>();
    const stack = [targetNode.id];
    while (stack.length > 0) {
      const current = stack.pop()!;
      if (current === sourceNode.id) return 'Refused: would create a cycle';
      if (seen.has(current)) continue;
      seen.add(current);

      for (const edge of model.getLinks()) {
        const from = model.getNodeByPortId(edge.sourcePortId)?.id;
        const to = model.getNodeByPortId(edge.targetPortId)?.id;
        if (from === current && to !== undefined) stack.push(to);
      }
    }
    return true;
  });
}

export function configurePorts(instance: DiagramInstance): () => void {
  const dispose = installPortRules(instance.getEngine());
  instance.renderNow();
  return dispose;
}
```

[`portTypeRegistry`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-ports) supplies both the type palette and compatibility rules. Identical type names match; an untyped endpoint imposes no type restriction. `compatibleWith` permits additional target types in the source-to-target direction—it does not automatically permit the reverse conversion.

[`registerConnectionValidator`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions) returns a disposer. Its callback receives both nodes and both ports for new connections. Return `true` to allow the candidate, or `false` or a reason string to veto it. Every registered validator must pass for a new connection.

> **Known issue:** Endpoint reconnection does not invoke registered validators, despite the callback type's optional `link` field intended for that task. Until it is fixed, disable endpoint reconnection with `engine.setInteractionConfig({ enableLinkReconnection: false })`, as `installPortRules()` does, so reconnection cannot bypass the cycle rule.

The cycle rule traverses the mounted instance's live links, not the initial `edges` array. It rejects a proposed edge when its target already reaches its source. Moving the boxes does not change that graph rule.

## 2. Mount the same editor in your framework

Choose one installation command for your existing project:

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

Add `configurePorts()` (or `installPortRules()` in Angular) to apply the type colors and cycle rule to this editor; see [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) for mounting and ready callbacks.

Each wrapper has a resolved height. Ports stay visible through `interaction.portVisibility` in JavaScript, React, Vue and Qwik. The Angular sample keeps the default hover visibility. Keep the returned validator disposer until unmount; the framework binding owns its canvas teardown.

:::code-group
```ts title="JavaScript"
// main.ts
import { render } from '@grafloria/element';
import { nodes, edges, configurePorts } from './ports';

export function mountPorts(container: HTMLElement): () => void {
  container.style.height = '460px';
  const instance = render(
    { nodes, edges }, container,
    { interaction: { portVisibility: 'always' } },
  );
  const disposeRules = configurePorts(instance);
  return () => {
    disposeRules();
    instance.dispose();
  };
}

const container = document.createElement('div');
document.body.append(container);
export const unmountPorts = mountPorts(container);
// Call unmountPorts() when your host removes this view.
```
```tsx title="React"
// App.tsx
import { useCallback, useEffect, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, configurePorts } from './ports';

export default function App() {
  const instanceRef = useRef<DiagramInstance | null>(null);
  useEffect(() => {
    const instance = instanceRef.current;
    if (!instance) return;
    return configurePorts(instance);
  }, []);
  const onInit = useCallback((instance: DiagramInstance) => {
    instanceRef.current = instance;
  }, []);
  return (
    <div style={{ height: '460px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        interaction={{ portVisibility: 'always' }} onInit={onInit} />
    </div>
  );
}
```
```vue title="Vue"
<!-- App.vue -->
<script setup lang="ts">
import { onBeforeUnmount } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, configurePorts } from './ports';

let disposeRules: (() => void) | undefined;
function onInit(instance: DiagramInstance) {
  disposeRules?.();
  disposeRules = configurePorts(instance);
}
onBeforeUnmount(() => disposeRules?.());
</script>

<template>
  <div style="height:460px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
      :interaction="{ portVisibility: 'always' }" @init="onInit" />
  </div>
</template>
```
```tsx title="Qwik"
// App.tsx
import {
  component$, noSerialize, useSignal, useVisibleTask$,
  type NoSerialize,
} from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, configurePorts } from './ports';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  useVisibleTask$(({ track, cleanup }) => {
    const mounted = track(() => instance.value);
    if (!mounted) return;
    const disposeRules = configurePorts(mounted);
    cleanup(disposeRules);
  });
  return (
    <div style={{ height: '460px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        interaction={{ portVisibility: 'always' }}
        onInit$={(mounted: DiagramInstance) => {
          instance.value = noSerialize(mounted);
        }} />
    </div>
  );
});
```
```ts title="Angular"
// app.component.ts
import { Component, viewChild, type AfterViewInit, type OnDestroy } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, installPortRules } from './ports';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:460px" />
  `,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = structuredClone(nodes);
  edges: EdgeSpec[] = structuredClone(edges);
  private disposeRules: (() => void) | undefined;

  ngAfterViewInit(): void {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    this.disposeRules = installPortRules(engine);
    this.canvas().scheduleRender();
  }

  ngOnDestroy(): void {
    this.disposeRules?.();
  }
}
```
:::

The JavaScript canvas starts with A → B → C and a separate purple string input.

![JavaScript: two wires connect A, B and C; blue square inputs and diamond outputs stay visible.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/13c8320171e2a24f4374dbd673631522.png)

The React canvas displays the same initial pipeline.

![React: A → B → C appears above the separate String input node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f2c8f04406e795cb82f9511e74dca53a.png)

The Qwik canvas displays the blue number ports and purple string port.

![Qwik: the number pipeline has two wires, while String input remains unconnected.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4a50e70d7e77ad1e8127d9a5c735fb07.png)

Qwik registers the types and validator in a browser visible task, after the ready callback supplies the instance. The live instance stays in `noSerialize()` state rather than entering the server's serialized state.

## 3. Try the connection rules

The initial canvas contains two wires. Test each layer by dragging from the diamond output on A:

1. Drop on B's `y` input. A number-to-number wire appears, and that input becomes full.
2. Try that same input again. No second wire appears; the one incoming-link cap is per port, not per node.
3. Drop on the purple input of String input. No wire appears because `number` cannot flow into `string`.
4. Drag from C's output to A's input. No wire appears: A already reaches C, so the proposed edge closes a cycle.

To use hover ports instead, omit the `interaction` prop/options in JavaScript, React, Vue and Qwik. Angular already uses hover ports in this sample. Hovering a node then reveals its ports. For container sizing, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

## Options that matter

Use the built-in glyphs and port layouts before registering custom geometry. These options belong to each port unless noted otherwise.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `shape.shape` | `'circle' \| 'square' \| 'diamond' \| 'triangle' \| 'path'` | `'circle'` | Selects the glyph; `path` needs SVG path data in `shape.path`. |
| `shape.size` | `number` | Twice `portDefaultRadius` | Sets the glyph box width and height; for circles, this is the diameter. |
| `label.layout` | `'inside' \| 'outside' \| 'orthogonal' \| 'radial'` | `'outside'` | Places text toward the body, away from it, across the normal, or radially from the node center. |
| `label.offset` | `number` | `6` | Sets the gap from the glyph edge in pixels. |
| `layout.strategy` | `'shape' \| 'absolute' \| 'line' \| 'sideLinear' \| 'ellipse' \| 'ellipseSpread'` | Shape anchor | Uses the shape silhouette, a fixed point, a segment, an edge column, or an ellipse arrangement. |
| `group` | `string` | Unset | Inherits configuration from the named group in `metadata.portGroups`; port-level layout, shape and label fields override it. |
| `dataType` | `string` | Unset | Names the data-flow type used for color and compatibility. |
| `gating.isConnectableStart`, `gating.isConnectableEnd` | `boolean` | `true` | Permit or veto the corresponding end of a proposed wire. |
| `gating.fromMaxLinks`, `gating.toMaxLinks` | `number \| null` | Unlimited | Cap outgoing or incoming links separately. |
| `maxConnections` | `number` | Unlimited | Caps all connections on this port. |
| `gating.allowedTypes` | `string[]` | No restriction | Requires the opposite port's data type or system type to appear in the list. |
| `gating.allowSelfLink` | `boolean` | `false` | Permits a same-node link only when both endpoints allow it. |
| `gating.allowDuplicateLinks` | `boolean` | `true` | When false on either endpoint, rejects another link between the same two ports, including the reverse direction. |
| `interaction.portVisibility` | `'always' \| 'on-hover' \| 'hidden'` | `'on-hover'` | Controls canvas-wide port visibility; hidden ports disable drag-to-connect. |

For many-port nodes, `sideLinear` spaces ports along an edge, `line` spaces them along `args.start` → `args.end` in node-local pixels, and `ellipseSpread` fans them around the inscribed ellipse. The port arrangement travels with the node. [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) covers the wires attached to those ports.

## Clean up global validators

Connection validators are process-global, not per canvas. Keep each registration's disposer and call it on unmount, as the samples do. The identity check in the cycle callback limits its rule to the intended live model; the disposer removes the registration itself.

Use [`clearConnectionValidators`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions) only when you intend a clean slate for the whole process. It removes every registered validator, including registrations owned by other canvases. Do not substitute it for disposing one view's rule.

## Live demos and related pages

- [Typed ports](https://grafloria.com/demos/ports/typed-ports.html): compare matching and mismatched types.
- [Port groups and layouts](https://grafloria.com/demos/ports/port-groups-and-layouts.html): compare columns, segments and rings.
- [Connection limit](https://grafloria.com/demos/nodes/connection-limit.html): try a second wire on a full port.
- [Preventing cycles](https://grafloria.com/demos/interaction/preventing-cycles.html) and its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/interaction/preventing-cycles.html): follow directed reachability through live links.
- [Specs and live models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/specs-and-live-models): understand the data queried by the cycle callback.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle): own a mounted instance and its teardown.

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

# Route and label edges

Use routing, labels and endpoint markers when a diagram needs to distinguish a connection from a crossing, or several relationships between the same nodes. The example below draws a right-angle detour around an obstacle, two crossing wires with a jump-over, three separate parallel lanes, and a self-loop outside its node.

An edge stores intent; the renderer turns that intent into geometry as nodes move. Describe connections with [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) rather than calculating SVG paths yourself.

## 1. Describe the routes and their labels

Create `edge-data.ts` in your browser application. The [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) arrays provide actual endpoints and an obstacle. Every edge has a stable id so you can identify the corresponding live link later.

The first edge pins its endpoints halfway down the right and left sides. Its `router` chooses the route; its `connector` rounds the bends. The label sits above the line, the source carries a circle, and the target carries an arrow.

```ts title="edge-data.ts"
import type { EdgeSpec, NodeSpec, SVGRendererConfig } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'a', label: 'A', position: { x: 40, y: 100 }, size: { width: 110, height: 60 } },
  { id: 'b', label: 'B', position: { x: 750, y: 100 }, size: { width: 110, height: 60 } },
  { id: 'wall', label: 'Obstacle', position: { x: 400, y: 60 }, size: { width: 120, height: 140 } },
  { id: 'c', label: 'C', position: { x: 40, y: 270 }, size: { width: 110, height: 44 } },
  { id: 'd', label: 'D', position: { x: 750, y: 270 }, size: { width: 110, height: 44 } },
  { id: 'e', label: 'E', position: { x: 40, y: 430 }, size: { width: 110, height: 44 } },
  { id: 'f', label: 'F', position: { x: 750, y: 430 }, size: { width: 110, height: 44 } },
  { id: 'g', label: 'G', position: { x: 40, y: 560 }, size: { width: 110, height: 60 } },
  { id: 'h', label: 'H', position: { x: 480, y: 560 }, size: { width: 110, height: 60 } },
  { id: 'self', label: 'Self', position: { x: 750, y: 560 }, size: { width: 110, height: 60 } },
];

export const edges: EdgeSpec[] = [
  {
    id: 'detour', source: 'a', target: 'b',
    sourceHandle: 'right@50%', targetHandle: 'left@50%',
    type: 'orthogonal', router: 'orthogonal', connector: 'rounded',
    label: 'depends on', labelPlacement: 'above',
    labelStyle: { color: '#15803d', fontSize: 12 },
    style: {
      stroke: '#15803d', strokeWidth: 2,
      arrowTail: { type: 'circle', size: 6, filled: true },
      arrowHead: { type: 'arrow', size: 10, filled: true },
    },
  },
  {
    id: 'cf', source: 'c', target: 'f', type: 'direct',
    sourceHandle: 'right', targetHandle: 'left',
    style: { jumpPoints: { enabled: true, size: 10, detectMode: 'all' } },
  },
  {
    id: 'ed', source: 'e', target: 'd', type: 'direct',
    sourceHandle: 'right', targetHandle: 'left',
    style: { jumpPoints: { enabled: true, size: 10, detectMode: 'all' } },
  },
  { id: 'p1', source: 'g', target: 'h', type: 'direct', label: 'request' },
  { id: 'p2', source: 'g', target: 'h', type: 'direct', label: 'response' },
  { id: 'p3', source: 'g', target: 'h', type: 'direct', label: 'audit' },
  {
    id: 'loop', source: 'self', target: 'self', label: 'retry',
    style: { selfLoop: { side: 'top', size: 40 } },
  },
];

export const rendererConfig: Partial<SVGRendererConfig> = {
  parallelLinks: true,
  parallelSpacing: 24,
  jumpOwnership: 'single',
};
```

[`SVGRendererConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-svgrendererconfig#svgrendererconfig) controls the whole diagram's lane spacing and crossing ownership. `jumpOwnership: 'single'` gives each crossing one hop even though both crossing edges enable jump points.

## 2. Mount the diagram

Choose your framework's tab and place its file beside `edge-data.ts`. Install that tab's packages in your application:

```bash
# JavaScript
npm install @grafloria/element @grafloria/engine @grafloria/renderer

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

# Qwik
npm install @grafloria/qwik @grafloria/engine @grafloria/renderer @builder.io/qwik @grafloria/element

# React
npm install @grafloria/react @grafloria/engine @grafloria/renderer react react-dom @grafloria/element

# Vue
npm install @grafloria/vue @grafloria/engine @grafloria/renderer vue @grafloria/element
```

For JavaScript, [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) mounts the spec and returns a live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). The JavaScript tab uses TypeScript in `main.ts` and creates its container in the browser.

For Angular, render [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) in `app.component.ts`; its two-way bindings return node and edge edits to your arrays. For Qwik, React and Vue, render the binding's component: [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow), [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow), or [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow), respectively. These tabs seed an uncontrolled instance with `defaultNodes` and `defaultEdges`.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, rendererConfig } from './edge-data';

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

const instance = render({ nodes, edges }, container, {
  renderer: rendererConfig,
});
instance.fitView();
```
```ts title="Angular"
import { AfterViewInit, Component, ViewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, rendererConfig } from './edge-data';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      [rendererConfig]="rendererConfig"
      style="display:block; height:700px" />
  `,
})
export class AppComponent implements AfterViewInit {
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  rendererConfig = rendererConfig;
  @ViewChild(DiagramCanvasComponent) canvas?: DiagramCanvasComponent;

  ngAfterViewInit(): void {
    requestAnimationFrame(() => this.canvas?.fitToContent());
  }
}
```
```tsx title="Qwik"
import { component$ } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { nodes, edges, rendererConfig } from './edge-data';

export default component$(() => (
  <div style={{ height: '700px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
      rendererConfig={rendererConfig} fitView />
  </div>
));
```
```tsx title="React"
import { GrafloriaFlow } from '@grafloria/react';
import { nodes, edges, rendererConfig } from './edge-data';

export default function App() {
  return (
    <div style={{ height: '700px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        rendererConfig={rendererConfig} fitView />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import { nodes, edges, rendererConfig } from './edge-data';
</script>

<template>
  <div style="height:700px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
      :renderer-config="rendererConfig" fit-view />
  </div>
</template>
```
:::

![JavaScript: the green A → B route passes below Obstacle, with a crossing hop, three labeled G → H lanes and a retry loop above Self.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f759742d29597fc92d6a48fd8d8227af.png)

Angular draws the same connections in its canvas.

![Angular: a labeled green detour, a hop at the diagonal crossing, three parallel lanes and the Self retry loop.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6cf4585d3939d76c009470f5a1a193d7.png)

Qwik renders the seeded edge specs.

![Qwik: the obstacle detour, crossing hop, request, response and audit lanes, and retry loop.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/05f8b7b9c57bb5267daab051038bb49d.png)

React renders the same edge geometry.

Vue renders the routes and labels from the shared data.

Follow A → B around the obstacle, then inspect the middle crossing: the hop distinguishes two unrelated wires from a junction. At the bottom, G → H has three individually selectable lanes, and Self → Self leaves the node body before returning. Drag the obstacle or an endpoint node to see the routes update.

## Choose the geometry

`type` is a shorthand for the line's shape. Explicit `router` and `connector` fields let you choose its path and its drawing independently.

| `type` | Router when omitted | Connector when omitted and no explicit router is set |
| --- | --- | --- |
| `direct` | `straight` | `straight` |
| `smooth` | `straight` | `smooth` |
| `orthogonal` | `orthogonal` | `rounded` |
| `bezier` | `straight` | `bezier` |

An explicit `orthogonal`, `manhattan`, `avoid` or `elk` router implies a `rounded` connector unless you name a connector yourself. Use `straight` for sharp polyline bends, `rounded` for rounded corners, or `smooth` / `bezier` for curved drawing.

| Router | What you get |
| --- | --- |
| `straight` | A direct route between endpoints. |
| `orthogonal` | Right-angle segments respecting port exit directions; the sample detours around the obstacle. |
| `manhattan` | Grid-based right-angle routing with turn minimization. |
| `avoid` | Obstacle-avoiding routing through the built-in A* router. |
| `elk` | The synchronous renderer currently substitutes `orthogonal`. |

> **Known issue:** `router: 'elk'` does not produce ELK routing through the mounted renderer: ELK routing is async-only, and this rendering path substitutes `orthogonal`. Until it is fixed, request `router: 'orthogonal'` explicitly, as the sample does; use `router: 'avoid'` when you want the built-in A* obstacle router.

For node placement by ELK, see [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram).

## Choose attachments, labels and markers

Use handles when a connection must stay at a particular port or position on a box. Omit both handles to let the attachment follow the real port on the side facing its partner. For true perimeter floating, set the edge's `metadata` to `{ connectionPoint: 'smart' }`; this permits attachment along the outline rather than only at a port.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `sourceHandle`, `targetHandle` | `string` | Port-facing when neither is named | Pin to a port id, side name, or point along a side. `right@36` is 36 px down the right side; `bottom@138` is 138 px from its left end; `left@50%` is halfway down. |
| `waypoints` | Point array | No supplied bends | Supply interior bends in world coordinates; endpoints stay attached to ports. |
| `labelPlacement` | `'on' \| 'above' \| 'below'` | `'on'` | Draw a label chip on the line, or text off the line without a box unless its style requests a background. |
| `labelStyle` | Label style | No override | Set the label's own color, font size, weight, family or background. |
| `style.arrowHead` | Arrow style | Filled arrow, size `10` | Choose the target marker. Supply `type`, `size` and `filled`. |
| `style.arrowTail` | Arrow style | No source marker | Choose the source marker with the same fields. |
| `parallelLinks` | `boolean` | `true` | Fan links between the same unordered pair of nodes into separate lanes, including reverse-direction links. |
| `parallelSpacing` | `number` | `16` | Set adjacent parallel-lane spacing in pixels. |
| `jumpOwnership` | `'both' \| 'single'` | `'both'` | Choose whether both jump-enabled links or one link draws a crossing hop. |
| `style.jumpPoints.enabled` | `boolean` | Not enabled without configuration | Enable crossing decorations on that edge. |
| `style.jumpPoints.size` | `number` | `10` | Set the jump size in pixels. |
| `style.selfLoop.size` | `number` | `40` | Set how far a self-loop bulges outside its node. |
| `style.selfLoop.side` | `'auto' \| 'top' \| 'right' \| 'bottom' \| 'left'` | `'auto'` | Choose the loop's side; automatic uses its source port's side. |

Endpoint markers include `arrow`, `circle`, `square` and `diamond`, plus ER markers such as `crow-foot` and `zero-or-many`, and UML markers such as `generalization` and `hollow-diamond`. Set `type: 'none'` to suppress an endpoint marker. Use the shipped shapes before registering your own geometry.

For more than one label on a link, obtain its live [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel) through `instance.getModel().getLink(id)`. `addLabel({ text: 'condition', position: 0.25 })` adds text a quarter of the way along its path; call `instance.renderNow()` after setup mutations to repaint. A fractional label position follows the route instead of remaining at an absolute canvas coordinate.

## Pitfalls

- A connection-point strategy that accepts the edge owns both endpoints before per-end `metadata.sourceAnchor` / `metadata.targetAnchor` are considered. Do not combine a floating strategy with per-end anchors expecting the anchors to take precedence.
- `above` and `below` are relative to the run's direction: on a vertical run, `above` places text to its left.
- Changing a live link's router through `setRouter()` clears its cached points and manual-waypoint flag. Changing `setConnector()` leaves routed points intact. Choose the router before adding bends you need to keep.
- Jump points do not replace a two-point smooth or bezier curve with a chord-based hop. Use direct or right-angle crossing wires, as above, when you need jump-overs.
- For user-facing edits that belong in undo history, follow [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history), rather than treating setup model mutations as commands.

## Live demos and related tasks

- [Edge routing](https://grafloria.com/demos/edges/edge-routing.html): drag or remove the obstacle and inspect the detour.
- [Edge labels](https://grafloria.com/demos/edges/edge-labels.html): drag a label along its edge, then move an endpoint.
- [Parallel links and self-loops](https://grafloria.com/demos/edges/parallel-links-and-self-loops.html): inspect separate lanes and the outside loop.
- [Jump-overs](https://grafloria.com/demos/edges/jump-overs.html): move the crossing and watch its hop follow.

See [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections) for allowed connections, [Configure editing gestures](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/configure-editing-gestures) for interaction settings, and [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for preserving the live document.

<!-- source: configure-editing-gestures.md -->

# Configure editing gestures

Use interaction settings to choose how users connect nodes, reconnect endpoints and bend wires without writing pointer handlers. In the React example pictured below, A connects to B and C sits below B: reconnect the wire to C, switch to bend editing, or copy and duplicate a selected node. The engine owns these edits; framework bindings expose the mounted canvas and its change events.

## 1. Define the editing policy

In your browser application, create this shared file. The data uses the library's [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) types. The policy checks its fields against [`InteractionConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-config).

[`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) exposes the commands used by the buttons. `copy()`, `paste()` and `duplicate()` return `Promise<void>`, not new specs. Read the edited graph through the mounted canvas, or use the binding's change events.

```ts title="editing.ts"
import type { DiagramEngine, InteractionConfig } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'a', label: 'A', position: { x: 80, y: 160 }, size: { width: 120, height: 60 } },
  { id: 'b', label: 'B', position: { x: 480, y: 80 }, size: { width: 120, height: 60 } },
  { id: 'c', label: 'C', position: { x: 480, y: 300 }, size: { width: 120, height: 60 } },
];

export const edges: EdgeSpec[] = [
  { id: 'ab', source: 'a', target: 'b', sourceHandle: 'right',
    targetHandle: 'left', type: 'direct' },
];

export const interaction = {
  dragThreshold: 8,
  enableLinkReconnection: true,
  showLinkEndpointHandles: true,
  enableWaypointEditing: false,
  showWaypointHandles: true,
  enableHelperLines: true,
  enableKeyboardNudge: true,
} satisfies Partial<InteractionConfig>;

export const actions = ['Reconnect', 'Edit bends', 'Copy', 'Paste', 'Duplicate', 'Lock / unlock'] as const;
export type EditingAction = typeof actions[number];

export async function act(engine: DiagramEngine, action: EditingAction): Promise<void> {
  switch (action) {
    case 'Reconnect':
      engine.setInteractionConfig({ enableWaypointEditing: false });
      break;
    case 'Edit bends':
      engine.setInteractionConfig({ enableWaypointEditing: true, showWaypointHandles: true });
      break;
    case 'Copy':
      if (engine.getDiagram()?.getSelectedNodes().length) {
        await engine.copy();
      }
      break;
    case 'Paste':
      if (engine.hasClipboardData()) {
        await engine.paste({ offset: { x: 30, y: 30 }, selectPasted: true });
      }
      break;
    case 'Duplicate':
      if (engine.getDiagram()?.getSelectedNodes().length) {
        await engine.duplicate({ offset: { x: 30, y: 30 }, selectDuplicated: true });
      }
      break;
    case 'Lock / unlock': {
      const diagram = engine.getDiagram();
      if (diagram) diagram.setReadonly(!diagram.isReadonly());
      break;
    }
  }
}
```

The initial policy enables alignment helper lines and arrow-key nudging. Reconnection starts enabled; bend editing starts disabled. Copy a selected node, then paste to add and select an offset copy. Copy does nothing in this toolbar when no node is selected; the engine's copy command requires a selected node. Duplicate performs the copy-like operation without requiring an earlier Copy click. The clipboard belongs to the engine.

## 2. Mount it in your framework

Choose one implementation below. Each uses the same shared file and displays the same six controls. Select a node before Copy or Duplicate. The selection count shows the current selection, not keyboard focus.

### JavaScript / TypeScript

Start with the mounted canvas in [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start), then use the shared editing policy above.

### React

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

This [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) example adds the shared `interaction` policy, an 8 px `dragThreshold` and editing actions on the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance); see [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections) for initialization and selection-callback wiring.

```tsx title="Editor.tsx"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, interaction, actions, act, type EditingAction } from './editing';

export default function Editor() {
  const instance = useRef<DiagramInstance | null>(null);
  const [selected, setSelected] = useState(0);
  async function run(action: EditingAction) {
    const current = instance.current;
    if (!current) return;
    await act(current.getEngine(), action);
    current.renderNow();
  }
  return <>
    <div>{actions.map(action => <button key={action} onClick={() => void run(action)}>{action}</button>)}</div>
    <p aria-live="polite">Selected: {selected}</p>
    <div style={{ height: 440 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        interaction={interaction} dragThreshold={8}
        onInit={current => { instance.current = current; }}
        onSelectionChange={change => setSelected(change.nodes.length + change.edges.length)} />
    </div>
  </>;
}
```

![React displays A connected to B, C below B, six editing controls and an initial selection count of zero.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/b3de3fe4d74d02287ef161cac22d8fd7.png)

### Vue

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

Render [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue), retain its instance with `@init`, and read selection through `@selection-change`.

> **Known issue:** Vue has no `dragThreshold` prop, and the shared DOM binder captures its threshold at creation instead of reading the engine's live setting. The intended `interaction: { dragThreshold: 8 }` does not change Vue's mouse threshold. Until the binding forwards it, keep the default 4 px threshold in Vue; the other settings below still apply.

```vue title="Editor.vue"
<script setup lang="ts">
import { shallowRef, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, interaction, actions, act, type EditingAction } from './editing';

const instance = shallowRef<DiagramInstance | null>(null);
const selected = ref(0);
function init(current: DiagramInstance) {
  instance.value = current;
  current.getEngine().setInteractionConfig({ ...interaction, dragThreshold: 4 });
}
async function run(action: EditingAction) {
  const current = instance.value;
  if (!current) return;
  await act(current.getEngine(), action);
  current.renderNow();
}
</script>

<template>
  <div><button v-for="action in actions" :key="action" @click="run(action)">{{ action }}</button></div>
  <p aria-live="polite">Selected: {{ selected }}</p>
  <div style="height: 440px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
      :interaction="{ ...interaction, dragThreshold: 4 }" @init="init"
      @selection-change="change => selected = change.nodes.length + change.edges.length" />
  </div>
</template>
```

Vue renders the same initial diagram and controls pictured in the React section.

### Qwik

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

Pass the shared editing policy and an 8 px `dragThreshold` to [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik); see [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections) for the binding's initialization and selection events. Keep the live instance out of serialized state with `noSerialize()`.

```tsx title="Editor.tsx"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, interaction, actions, act } from './editing';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const selected = useSignal(0);

  return <>
    <div>{actions.map(action => (
      <button key={action} onClick$={async () => {
        const current = instance.value;
        if (!current) return;
        await act(current.getEngine(), action);
        current.renderNow();
      }}>{action}</button>
    ))}</div>
    <p aria-live="polite">Selected: {selected.value}</p>
    <div style={{ height: '440px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        interaction={interaction} dragThreshold={8}
        onInit$={current => { instance.value = noSerialize(current); }}
        onSelectionChange$={change => {
          selected.value = change.nodes.length + change.edges.length;
        }} />
    </div>
  </>;
});
```

Qwik renders the same initial diagram and six controls pictured in the React section. Use those controls to switch between reconnection and bend editing, copy, paste, duplicate or toggle the document lock.

### Angular

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

Render [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent) with two-way specs. Read its mounted engine through `activeEngine()`. Angular exposes snapping and keyboard navigation as inputs; enable them directly. Use the [`SelectionChange`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interfaces) output payload to update the count.

```ts title="editor.component.ts"
import { AfterViewInit, Component, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent, type SelectionChange } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, interaction, actions, act, type EditingAction } from './editing';

@Component({
  selector: 'app-editor',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div>@for (action of actions; track action) {
      <button (click)="run(action)">{{ action }}</button>
    }</div>
    <p aria-live="polite">Selected: {{ selected() }}</p>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      [enableSnapping]="true" [enableKeyboardNavigation]="true"
      [enableProximityConnect]="false" (selectionChange)="selectionChanged($event)"
      style="display: block; height: 440px" />
  `,
})
export class EditorComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly actions = actions;
  readonly selected = signal(0);
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  ngAfterViewInit(): void {
    this.canvas().activeEngine()?.setInteractionConfig(interaction);
  }
  selectionChanged(change: SelectionChange): void {
    this.selected.set(change.nodes.length + change.edges.length);
  }
  async run(action: EditingAction): Promise<void> {
    const engine = this.canvas().activeEngine();
    if (!engine) return;
    await act(engine, action);
    this.canvas().scheduleRender();
  }
}
```

Angular renders the same initial diagram and controls pictured in the React section.

## 3. Try connections, reconnections and bends

1. Hover a node to reveal its ports. Drag a port to a compatible target port to create a connection.
2. Click the A → B wire to select it. Drag its endpoint handle at B onto C. The existing link now connects A to C.
3. Click Edit bends. Click the selected wire's body to insert a waypoint, then drag that waypoint. The route bends through the point while its endpoints stay attached.
4. Click Reconnect before dragging an endpoint again.

Waypoints are model constraints, not independent painted handles. They persist with the edge and participate in undo; see [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) for routing around those constraints.

> **Known issue:** With waypoint editing enabled, a path hit can insert a waypoint before the endpoint-reconnection branch runs. The intended combined policy is `setInteractionConfig({ enableWaypointEditing: true, enableLinkReconnection: true })`; until the hit-order conflict is fixed, disable waypoint editing while reconnecting. The two mode buttons above do that without rebuilding the canvas.

## Options that matter

Defaults below are engine defaults unless a surface is named explicitly.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `dragThreshold` | `number` | `4` | Separates a pointer click from a drag in screen pixels. JavaScript, React and Qwik also expose a creation-level option/prop. |
| `enableLinkReconnection` | `boolean` | `true` | Allows moving an existing link endpoint. |
| `showLinkEndpointHandles` | `boolean` | `true` | Displays endpoint handles on selected links. |
| `enableWaypointEditing` | `boolean` | `false` | Enables inserting, moving and removing bends. |
| `showWaypointHandles` | `boolean` | `true` | Displays handles on selected links. It does not enable editing by itself. |
| `snapToPortRadius` | `number` | `30` | Sets the connection's port-snap radius. |
| `enableHelperLines` | `boolean` | `false` | Snaps a single top-level node to sibling alignments/equal spacing and displays dashed guides during dragging. |
| `enableKeyboardNudge` | `boolean` | `false` | Enables selected-node nudging in the shared DOM binding. |
| `enableSnapping` (Angular) | `boolean` | `true` | Enables the canvas's snapping layer. |
| `enableKeyboardNavigation` (Angular) | `boolean` | `true` | Enables focus navigation, nudging, keyboard connection and announcements. |
| `readonly` (JavaScript/React/Vue/Qwik) | `boolean` | `false` in the DOM binder | Prevents editing gestures while retaining viewing interaction. |

For grid snapping, set `waypointEditor.snapToGrid` and `waypointEditor.gridSize` in the interaction policy. The shipped snapping layer reads the same grid settings as the waypoint editor. Preserve the other editor fields when changing this nested object: `setInteractionConfig()` merges only the top level. Use `getInteractionConfig().waypointEditor` as the starting point. Angular additionally exposes `canvasBounds` for keeping dragged boxes inside a rectangle.

## Keyboard, touch and read-only operation

In the React and Vue examples, click a node, then press an arrow to nudge it by one world unit; Shift increases the step to ten. The policy explicitly enables nudging: it is not enabled by the engine default. Ctrl/⌘+A selects all; Ctrl/⌘+C copies, Ctrl/⌘+V pastes, and Ctrl/⌘+D duplicates selected nodes. Ctrl/⌘+Z undoes, and Ctrl/⌘+Shift+Z or Ctrl/⌘+Y redoes. Text-entry targets keep their keys.

Angular's enabled keyboard navigation also draws a focus ring. Tab and Shift+Tab walk nodes and links; arrows nudge a selection or move focus spatially when nothing is selected. On a focused node, C starts keyboard connection, arrows choose a port, Tab chooses a target and Enter commits. Escape cancels that keyboard connection. Focus is distinct from selection.

Touch uses the shipped gesture handling: one finger taps to select, drags a node to move it, drags from a port to connect, or drags empty canvas to pan. Two fingers pan and pinch to zoom. A 500 ms long press emits a context-menu event; it does not create your menu UI. The binding sets `touch-action: none`; do not override it with native browser scrolling on the canvas. Touch uses its own 10 px movement tolerance, rather than the mouse's `dragThreshold`.

Lock / unlock toggles the live document's `setReadonly()` state. Selection and viewing remain available, but document writes are refused. For a canvas that starts view-only, pass `readonly: true` to `render()` or `readonly` to the React, Vue or Qwik component. Angular has no `readonly` input on this canvas: set the mounted document lock through its engine, as the shared action does. Keep viewing controls separate with `enablePan` and the surface's zoom switch (`enableZoom`, or Angular's `enableMouseWheelZoom`).

Use Delete or Backspace to remove the selection through the canvas's keyboard handler. [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) explains the undo stack those edits join.

> **Known issue:** `engine.deleteSelection()` checks the store's selection sets, whereas a shared DOM-binding mouse selection lives on the diagram. The intended call can throw “No entities selected” after a visible selection. Until the helper synchronizes those sources, use the canvas's Delete/Backspace handler, which reads the diagram selection and executes removal commands. Angular's keyboard handler synchronizes selection before calling the helper.

## Live demos and related tasks

- [Reconnect an edge](https://grafloria.com/demos/edges/reconnect-edge.html): select the wire and move its target from B to C.
- [Edit waypoints](https://grafloria.com/demos/edges/editable-edge.html): insert and drag bends.
- [Keyboard and screen-reader operation](https://grafloria.com/demos/interaction/keyboard-a11y.html): explore focus, connections and announcements.
- [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections): control which targets accept a wire.
- [Add editor controls](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/add-editor-controls): add shipped toolbars and canvas controls.
- [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow): mirror edits outside the canvas.

<!-- source: add-editor-controls.md -->

# Add editor controls

Use editor controls when readers need to navigate a diagram and act on its nodes and edges. The examples below add a dotted background, a live minimap, zoom and fit buttons, node actions, a right-click menu, and an edge-delete button to a two-node diagram.

## 1. Install the packages

Run the command for your framework in your own project. The shared action code uses the shipped Angular action presets even when the canvas uses another binding, except in the Qwik workaround below.

JavaScript:

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

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

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

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

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

## 2. Share the data and action wiring

Specs describe the boxes and wire; the mounted instance owns their live models. Type the data with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec).

The node strip uses Duplicate and Delete from [`createStandardPreset`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions#createstandardpreset). The right-click menu takes those same two actions from [`createContextMenuPreset`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions#createcontextmenupreset). Choosing only these actions keeps this example focused on copying and removing boxes rather than supplying an editing dialog.

The edge button uses the Delete action from [`createDefaultLinkActions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions#createdefaultlinkactions). Angular also offers its built-in path-anchored toolbar through `enableLinkToolbar`; that toolbar includes Insert node and Delete by default. Inserting a node splits the link as one undoable step.

> **Known issue:** The shipped node Delete action removes the node directly from the model, bypassing undo history. Until it is fixed, replace that action's `onClick` with `engine.removeNode(node.id)` as below.

The helper accepts the library's [`CanvasPluginHost`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-components#canvaspluginhost) surface. Pass the live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) in JavaScript, React and Vue; the Angular example supplies its canvas's active engine and camera. It returns a cleanup function for unmount. Qwik uses the separate component below.

```ts title="editor.ts"
import {
  createStandardPreset,
  createContextMenuPreset,
  createDefaultLinkActions,
} from '@grafloria/angular';
import type { CanvasPluginHost, NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'a', label: 'Draft', data: { label: 'Draft' }, selected: true,
    position: { x: 100, y: 130 }, size: { width: 150, height: 70 } },
  { id: 'b', label: 'Publish', data: { label: 'Publish' },
    position: { x: 410, y: 130 }, size: { width: 150, height: 70 } },
];
export const edges: EdgeSpec[] = [
  { id: 'e', source: 'a', target: 'b', type: 'smooth' },
];

export function installEditor(host: CanvasPluginHost, repaint: () => void): () => void {
  const engine = host.getEngine();
  const model = host.getModel();
  const container = host.container;
  const bar = document.createElement('div');
  const menu = document.createElement('div');
  const edgeBar = document.createElement('div');
  const coordinates = document.createElement('output');
  for (const element of [bar, menu, edgeBar]) {
    element.style.cssText = 'position:absolute;z-index:10;display:none;gap:6px;' +
      'padding:6px;background:#fff;border:1px solid #64748b;border-radius:6px';
    container.appendChild(element);
  }
  coordinates.style.cssText = 'position:absolute;top:8px;right:8px;z-index:10;' +
    'background:white;padding:4px;font:12px monospace';
  coordinates.textContent = 'Move the pointer to read world coordinates';
  container.appendChild(coordinates);

  const standard = createStandardPreset(engine);
  const context = createContextMenuPreset(engine);
  const nodeActions = (standard.actionGroups ?? []).flatMap(group => group.actions)
    .filter(action => action.id === 'duplicate' || action.id === 'delete');
  const menuActions = (context.actionGroups ?? []).flatMap(group => group.actions)
    .filter(action => action.id === 'duplicate' || action.id === 'delete');

  // Intended shipped call: action.onClick(node).
  // Replace only the defective node-delete implementation.
  for (const action of [...nodeActions, ...menuActions]) {
    if (action.id === 'delete') {
      action.onClick = node => {
        void engine.removeNode(node.id).then(repaint);
      };
    }
  }

  let selectedId: string | undefined;
  let menuId: string | undefined;
  function addButton(parent: HTMLElement, label: string, run: () => void) {
    const button = document.createElement('button');
    button.type = 'button';
    button.textContent = label;
    button.addEventListener('pointerdown', event => event.stopPropagation());
    button.addEventListener('click', event => {
      event.stopPropagation();
      run();
    });
    parent.appendChild(button);
  }
  for (const action of nodeActions) {
    addButton(bar, action.label, () => {
      const node = selectedId ? model.getNode(selectedId) : undefined;
      if (node) action.onClick(node);
      repaint();
    });
  }
  for (const action of menuActions) {
    addButton(menu, action.label, () => {
      const node = menuId ? model.getNode(menuId) : undefined;
      if (node) action.onClick(node);
      menu.style.display = 'none';
      repaint();
    });
  }
  const deleteLink = createDefaultLinkActions(engine)
    .find(action => action.id === 'delete-link');
  if (deleteLink) {
    addButton(edgeBar, deleteLink.label, () => {
      const link = model.getLink('e');
      if (!link) return;
      const point = link.points[Math.floor(link.points.length / 2)];
      if (point) deleteLink.onClick({ link, engine, t: 0.5, point });
    });
  }

  function openMenu(event: MouseEvent) {
    if (!(event.target instanceof Element)) return;
    const id = event.target.closest('[data-node-id]')?.getAttribute('data-node-id');
    if (!id || !model.getNode(id)) return;
    event.preventDefault();
    menuId = id;
    const rect = container.getBoundingClientRect();
    menu.style.left = `${event.clientX - rect.left}px`;
    menu.style.top = `${event.clientY - rect.top}px`;
    menu.style.display = 'flex';
  }
  function dismiss(event: PointerEvent) {
    if (!(event.target instanceof Node) || !menu.contains(event.target)) {
      menu.style.display = 'none';
    }
  }
  function escape(event: KeyboardEvent) {
    if (event.key === 'Escape') menu.style.display = 'none';
  }
  function readPoint(event: PointerEvent) {
    const world = host.viewport.clientToWorld(
      event.clientX, event.clientY, container.getBoundingClientRect(),
    );
    coordinates.textContent = `world: ${world.x.toFixed(1)}, ${world.y.toFixed(1)}`;
  }
  container.addEventListener('contextmenu', openMenu);
  container.addEventListener('pointermove', readPoint);
  document.addEventListener('pointerdown', dismiss);
  document.addEventListener('keydown', escape);

  let frame = 0;
  function positionOverlays() {
    const rect = container.getBoundingClientRect();
    const selected = model.getNodes().filter(node => node.isSelected());
    const node = selected.length === 1 ? selected[0] : undefined;
    selectedId = node?.id;
    bar.style.display = node ? 'flex' : 'none';
    if (node) {
      const point = host.viewport.worldToClient(
        node.position.x + node.size.width / 2, node.position.y, rect,
      );
      bar.style.left = `${point.x - rect.left}px`;
      bar.style.top = `${point.y - rect.top}px`;
      bar.style.transform = 'translate(-50%, calc(-100% - 8px))';
    }
    const link = model.getLink('e');
    const points = link?.points;
    const first = points?.[0];
    const last = points?.[points.length - 1];
    edgeBar.style.display = first && last ? 'flex' : 'none';
    if (first && last) {
      const point = host.viewport.worldToClient(
        (first.x + last.x) / 2, (first.y + last.y) / 2, rect,
      );
      edgeBar.style.left = `${point.x - rect.left}px`;
      edgeBar.style.top = `${point.y - rect.top}px`;
      edgeBar.style.transform = 'translate(-50%, -50%)';
    }
    frame = requestAnimationFrame(positionOverlays);
  }
  positionOverlays();
  return () => {
    cancelAnimationFrame(frame);
    container.removeEventListener('contextmenu', openMenu);
    container.removeEventListener('pointermove', readPoint);
    document.removeEventListener('pointerdown', dismiss);
    document.removeEventListener('keydown', escape);
    for (const element of [bar, menu, edgeBar, coordinates]) element.remove();
  };
}
```

The node strip stays a constant screen size: `worldToClient()` positions it outside the camera-transformed layer. The edge-delete strip sits between this example's two endpoints; it is not an arc-length anchor for a bent route. Use Angular's built-in toolbar for a routed-path anchor, or follow the [edge toolbar demo](https://grafloria.com/demos/edges/edge-toolbar.html).

## 3. Mount the controls in your framework

Build on the mounting and instance wiring in [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) by adding a background, minimap and zoom/fit controls with [`attachCanvasPlugins`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-components#attachcanvasplugins) after [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) in JavaScript, or with `plugins` on [`GrafloriaFlow` for React](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow), [`GrafloriaFlow` for Vue](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow), [`GrafloriaFlow` for Qwik](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow), or [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent).

JavaScript, Angular, React and Vue start with Draft selected and show its floating Duplicate/Delete strip. The separate Qwik component starts with Draft selected and displays Duplicate a, Delete a and Delete edge above the canvas; it does not load the Angular presets. Right-click either node to act on that node. Delete on the wire (or Qwik's Delete edge button) removes the wire, not either endpoint. Move the pointer over the canvas to read world coordinates.

> **Known issue:** Importing `createStandardPreset`, `createContextMenuPreset` and `createDefaultLinkActions` from `@grafloria/angular` in a Qwik app also loads Angular's decorated canvas class through the package's barrel export, causing a decorator parse error. Until this integration is fixed, use the Qwik component below, which invokes the mounted engine directly and does not import `editor.ts`.

Angular's two-way arrays accept specs and live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) and [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel) objects; declare that union so updates from the canvas retain their types.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { attachCanvasPlugins } from '@grafloria/renderer';
import { nodes, edges, installEditor } from './editor';

export function mountEditor(container: HTMLElement): () => void {
  container.style.cssText = 'height:480px;position:relative';
  const instance = render({ nodes, edges }, container, {
    minZoom: 0.25, maxZoom: 2, zoomSensitivity: 0.15,
    enablePan: true, enableZoom: true,
  });
  const plugins = attachCanvasPlugins(instance, {
    background: { variant: 'dots' }, minimap: true, controls: true,
  });
  const cleanup = installEditor(instance, () => instance.render());
  return () => {
    cleanup();
    plugins.dispose();
    instance.dispose();
  };
}

const container = document.createElement('div');
document.body.appendChild(container);
export const unmountEditor = mountEditor(container);
// Call unmountEditor() when your host removes this editor.
```
```ts title="Angular"
import { AfterViewInit, Component, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeModel, LinkModel } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, installEditor } from './editor';

@Component({
  selector: 'app-root', standalone: true, imports: [DiagramCanvasComponent],
  template: `
    <div #host style="height:480px;position:relative">
      <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
        [plugins]="true" [enableLinkToolbar]="false"
        [minZoom]="0.25" [maxZoom]="2" [zoomSensitivity]="0.15"
        [enablePan]="true" [enableMouseWheelZoom]="true"
        style="display:block;height:100%" />
    </div>`,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  nodes: readonly (NodeSpec | NodeModel)[] = nodes;
  edges: readonly (EdgeSpec | LinkModel)[] = edges;
  canvas = viewChild.required(DiagramCanvasComponent);
  host = viewChild.required<ElementRef<HTMLElement>>('host');
  private cleanup?: () => void;

  ngAfterViewInit() {
    const canvas = this.canvas();
    const engine = canvas.activeEngine();
    const viewport = canvas.viewportController();
    const model = engine?.getDiagram();
    if (!engine || !viewport || !model) return;
    this.cleanup = installEditor({
      container: this.host().nativeElement, viewport,
      getEngine: () => engine, getModel: () => model,
      fitView: padding => canvas.fitToContent(padding),
    }, () => canvas.scheduleRender());
  }
  ngOnDestroy() { this.cleanup?.(); }
}
```
```tsx title="Qwik"
import { component$, $, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance, type NodeSpec, type EdgeSpec } from '@grafloria/qwik';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const target = useSignal('a');
  const menu = useSignal(false);
  const coordinates = useSignal('Move the pointer to read world coordinates');
  const nodes: NodeSpec[] = [
    { id: 'a', label: 'Draft', selected: true, position: { x: 100, y: 130 },
      size: { width: 150, height: 70 } },
    { id: 'b', label: 'Publish', position: { x: 410, y: 130 },
      size: { width: 150, height: 70 } },
  ];
  const edges: EdgeSpec[] = [{ id: 'e', source: 'a', target: 'b', type: 'smooth' }];
  const duplicate = $(async () => {
    const api = instance.value;
    const node = api?.getModel().getNode(target.value);
    if (!api || !node) return;
    await api.getEngine().addNode({
      type: node.type, data: { label: node.getMetadata('label') },
      position: { x: node.position.x + 20, y: node.position.y + 20 },
      size: { width: node.size.width, height: node.size.height },
    });
    menu.value = false;
  });
  const remove = $(async () => {
    const api = instance.value;
    if (api?.getModel().getNode(target.value)) {
      await api.getEngine().removeNode(target.value);
    }
    menu.value = false;
  });
  return (
    <div>
      <button onClick$={duplicate}>Duplicate {target.value}</button>
      <button onClick$={remove}>Delete {target.value}</button>
      <button onClick$={async () => {
        const api = instance.value;
        if (api?.getModel().getLink('e')) await api.getEngine().removeLink('e');
      }}>Delete edge</button>
      <output>{coordinates.value}</output>
      <div style={{ height: '480px', position: 'relative' }}
        onContextMenu$={(event) => {
          if (!(event.target instanceof Element)) return;
          const id = event.target.closest('[data-node-id]')?.getAttribute('data-node-id');
          if (!id) return;
          event.preventDefault();
          target.value = id;
          menu.value = true;
        }}
        onPointerMove$={(event) => {
          const api = instance.value;
          if (!api) return;
          const point = api.viewport.clientToWorld(
            event.clientX, event.clientY, api.container.getBoundingClientRect(),
          );
          coordinates.value = `world: ${point.x.toFixed(1)}, ${point.y.toFixed(1)}`;
        }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} plugins
        minZoom={0.25} maxZoom={2} zoomSensitivity={0.15}
        enablePan enableZoom
        onSelectionChange$={(change) => {
          const node = change.nodes[0];
          if (node) target.value = node.id;
        }}
        onInit$={$((api: DiagramInstance) => { instance.value = noSerialize(api); })} />
      {menu.value && <div style={{ position: 'absolute', top: '8px', left: '8px', zIndex: 10, background: 'white' }}>
        <button onClick$={duplicate}>Duplicate {target.value}</button>
        <button onClick$={remove}>Delete {target.value}</button>
        <button onClick$={() => { menu.value = false; }}>Close</button>
      </div>}
      </div>
    </div>
  );
});
```
```tsx title="React"
import { useEffect, useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import { nodes, edges, installEditor } from './editor';

export default function App() {
  const teardown = useRef<(() => void) | null>(null);
  useEffect(() => () => teardown.current?.(), []);
  function onInit(instance: DiagramInstance) {
    teardown.current?.();
    teardown.current = installEditor(instance, () => instance.render());
  }
  return (
    <div style={{ height: '480px', position: 'relative' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} plugins
        minZoom={0.25} maxZoom={2} zoomSensitivity={0.15}
        enablePan enableZoom onInit={onInit} />
    </div>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { onBeforeUnmount } from 'vue';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import { nodes, edges, installEditor } from './editor';

let teardown: (() => void) | undefined;
function onInit(instance: DiagramInstance) {
  teardown?.();
  teardown = installEditor(instance, () => instance.render());
}
onBeforeUnmount(() => teardown?.());
</script>

<template>
  <div style="height:480px;position:relative">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :plugins="true"
      :min-zoom="0.25" :max-zoom="2" :zoom-sensitivity="0.15"
      :enable-pan="true" :enable-zoom="true" @init="onInit" />
  </div>
</template>
```
:::

![JavaScript: Draft is selected, with Duplicate and Delete above it and Delete on the wire. Zoom and fit controls sit at the lower left; the minimap sits at the lower right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/b3e25a4a5d19b705ad3552e342a96c03.png)

The React sample displays the same two-node editor with a coordinate readout at the top right.

![React: Draft connects to Publish over a dotted background, with node actions, an edge-delete button, zoom and fit controls, and a minimap.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6bd4b0810b0644f0ded0597ebd8af22e.png)

Angular also draws its built-in selection handles and action icons around Draft.

![Angular: Draft has resize handles and selection actions alongside the Duplicate/Delete strip; the wire has a Delete button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9a6a15dae869914b8a67193c82452036.png)

Vue renders the same floating action strips and canvas furniture as React. Both initially display a prompt to move the pointer rather than numeric coordinates.

Qwik's separate component renders its actions above the diagram without importing the shared Angular-based helper.

![Qwik: selected Draft connects to Publish on a white canvas. Duplicate a, Delete a, Delete edge and a pointer prompt appear above the canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e4e38f964523a5ff6bfe9024448c0684.png)

The minimap mirrors the node boxes and shows the camera rectangle. Click or drag inside it to move the camera. Fit view frames the content. Ctrl/⌘+wheel zooms at the pointer; plain wheel scroll pans.

## Options that matter

Use [`CanvasPluginOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-components#canvaspluginoptions) to select furniture. `plugins: true` in a binding enables all three; an options object enables only the entries you supply. Calling `attachCanvasPlugins(instance)` with no options enables none.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `background` | `boolean` or background options | Off when omitted | Adds the grid; the store's `gridEnabled` flag controls visibility when bound. |
| `minimap` | `boolean` or minimap options | Off when omitted | Adds node rectangles and the camera rectangle. |
| `controls` | `boolean` or controls options | Off when omitted | Adds zoom and fit buttons. |
| `bindToStore` | `boolean` | `true` | Keeps furniture visibility and the engine store in sync. |
| `controls.showLock` | `boolean` | `false` | Adds the lock toggle. |
| `controls.zoomStep` | `number` | `1.2` | Multiplies zoom per Zoom in click; Zoom out divides by it. |
| `minZoom` | `number` | `0.1` | Lower camera scale limit. |
| `maxZoom` | `number` | `3` | Upper camera scale limit. |
| `zoomSensitivity` | `number` | `0.1` | Wheel zoom uses a factor of `1 + zoomSensitivity`. |
| `enablePan` | `boolean` | `true` | Enables pan gestures. |
| `enableZoom` | `boolean` | `true` | Enables wheel zoom in JavaScript, React, Vue and Qwik. Angular calls this input `enableMouseWheelZoom`. |

Pan and wheel-zoom switches govern gestures, not imperative camera calls or the plugin buttons. To remove zoom buttons, pass `controls: { showZoom: false }`; to remove all furniture, disable the binding's `plugins` prop.

## Coordinate conversion and palettes

Use the mounted camera, not a new [`ViewportController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#viewportcontroller), for conversions. `clientToWorld(event.clientX, event.clientY, rect)` returns a world point, as the sample's coordinate readout demonstrates. `worldToClient(x, y, rect)` returns client coordinates; subtract `rect.left` and `rect.top` to position an absolute overlay inside the canvas.

The camera's `x` and `y` are world coordinates, but its `width` and `height` are CSS-pixel dimensions. `getViewBox()` returns the visible world rectangle after zoom. Do not divide a camera rectangle by zoom before handing it to a renderer: the renderer applies zoom itself.

For a shape palette, use the shipped searchable stencil palette described in [Build a stencil editor](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-stencil-editor). It provides categorized masters and drag-to-place rather than a second set of node templates you maintain yourself. A palette drop needs the same client-to-world conversion shown here.

## Pitfalls and related tasks

- Keep a node toolbar in screen space if its buttons must retain their size. A [`createViewportPortal`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#createviewportportal) lives in the transformed HTML layer: it pans **and scales** with the scene.
- Keep the node menu's target separate from selection. The example's right-click handler reads the node id under the pointer, so right-clicking Publish does not delete a previously selected Draft.
- Keep teardown in the framework's unmount hook. The bindings own canvas disposal; dispose only the overlays you add yourself.
- For app-owned specs, follow the change-event return path in [React state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions), [Vue state and composables](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-state-and-composables), or [Angular state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling).
- For more toolbar edits on the shared history stack, see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

Try the live [minimap and controls](https://grafloria.com/demos/misc/minimap-and-controls.html), [node toolbar](https://grafloria.com/demos/nodes/node-toolbar.html), [edge toolbar](https://grafloria.com/demos/edges/edge-toolbar.html), and [context menu](https://grafloria.com/demos/interaction/context-menu.html) demos. The [minimap demo source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/misc/minimap-and-controls.html) shows the same one-call furniture attachment.

<!-- source: lay-out-a-diagram.md -->

# Lay out a diagram

Use a shipped layout when you want a graph arranged from its connections rather than hand-authored coordinates. Start with a left-to-right pipeline, rerun it from a button, then insert a node with an incremental pass that preserves positions outside the affected neighborhood.

Specs describe the graph; the engine owns its geometry. The framework component's `layout` prop selects the initial arrangement. For subsequent work, get the [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine) through the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) and await `layout()`.

## 1. Choose an algorithm

You do not need to register adapters before using these names.

| Graph | Layout name | What you get |
| --- | --- | --- |
| Flowcharts, pipelines, DAGs | `elk`, `layered`, `dagre` | Layered ranking; ELK also handles ports and nesting. |
| System diagrams with zones | `architecture` | Regions on a grid, boxes sized to their words, and bends in the gutters. |
| Hierarchies, org charts | `tree` | A tidy, parent-centered hierarchy. |
| Networks, clusters | `force`, `community`, `spectral` | Physical spread or grouping by related nodes. |
| Catalogs, galleries | `grid`, `circular`, `radial` | Uniform placement. |
| No predetermined choice | `auto` | Algorithm selection based on the graph. |

An unknown name throws an error listing the registered layouts. Calling `layout()` without a name uses `auto`.

Install the packages for your framework in your own browser application.

JavaScript:

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
```
Angular:

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

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

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

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

## 2. Define a pipeline and its insertion operation

Save this shared file beside the framework sample you choose below. The typed [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) arrays describe six connected boxes, initially stacked at the origin. The `layered` layout separates them left to right. [`UnifiedLayoutOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-unifiedlayoutoptions#unifiedlayoutoptions) types the shared request's options.

`insertNode()` adds a labeled box and two connections to the live graph. Its incremental pass allows the new box and its immediate neighbors to move, while anchoring the rest. It returns the layout result, including a movement report and a tween plan; the samples repaint the committed positions rather than animate the plan.

This page requires the next release of `@grafloria/engine`: `direction: 'LR'` is unreleased and is not available in version 0.4.0. Use the samples after that release is available.

```ts title="layout-demo.ts"
import type { DiagramEngine, UnifiedLayoutOptions } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = ['n0', 'n1', 'n2', 'n3', 'n4', 'n5'].map((id) => ({
  id,
  label: id,
  position: { x: 0, y: 0 },
  size: { width: 110, height: 46 },
}));

export 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' },
];

const options: UnifiedLayoutOptions = { direction: 'LR', nodeSpacing: 40, rankSpacing: 80 };
export const layout = {
  name: 'layered',
  options,
};

export async function insertNode(engine: DiagramEngine) {
  const model = engine.getDiagram();
  const source = model?.getNode('n2');
  const target = model?.getNode('n4');
  const sourcePort = source?.getPorts().find((port) => port.alignment.side === 'right');
  const targetPort = target?.getPorts().find((port) => port.alignment.side === 'left');
  if (!sourcePort || !targetPort) throw new Error('The pipeline is not mounted');

  const inserted = await engine.addNode({
    type: 'rect',
    position: { x: 0, y: 0 },
    size: { width: 110, height: 46 },
  });
  inserted.setLabel('Inserted');
  const input = inserted.getPorts().find((port) => port.alignment.side === 'left');
  const output = inserted.getPorts().find((port) => port.alignment.side === 'right');
  if (!input || !output) throw new Error('The new node has no side ports');

  await engine.addLink({ sourcePortId: sourcePort.id, targetPortId: input.id });
  await engine.addLink({ sourcePortId: output.id, targetPortId: targetPort.id });
  return engine.layoutIncremental({ changed: [inserted.id], direction: 'LR', radius: 1 });
}
```

The new [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) comes from `addNode()`; its default side ports supply the endpoints for `addLink()`. The helper never replaces the existing nodes with their original coordinates. Each inserted node gets the engine's generated id.

## 3. Mount, rerun, and insert

Build on the framework mounting patterns in [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes): here, the layout request arranges the pipeline, and the buttons rerun it or insert a node with an incremental pass.

On load you see `n0` through `n5` arranged left to right. Drag a box, then choose **Rerun layout** to arrange the whole graph again. Choose **Insert node** to add a branch through **Inserted** from `n2` to `n4`; the incremental pass leaves nodes outside that one-hop region in place. The readout reports the total distance traveled by pre-existing nodes, in pixels.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, layout, insertNode } from './layout-demo';

export async function mountPipeline(container: HTMLElement): Promise<() => void> {
  container.innerHTML = `
    <button type="button" data-rerun disabled>Rerun layout</button>
    <button type="button" data-insert disabled>Insert node</button>
    <span data-report>Preparing layout</span>
    <div data-canvas style="height:400px"></div>`;
  const canvas = container.querySelector<HTMLElement>('[data-canvas]')!;
  const rerun = container.querySelector<HTMLButtonElement>('[data-rerun]')!;
  const insert = container.querySelector<HTMLButtonElement>('[data-insert]')!;
  const report = container.querySelector<HTMLElement>('[data-report]')!;
  const instance = render({ nodes, edges }, canvas);

  async function run(add: boolean) {
    rerun.disabled = insert.disabled = true;
    try {
      if (add) {
        const result = await insertNode(instance.getEngine());
        report.textContent = `Existing nodes moved ${result.movement.total.toFixed(1)} px`;
      } else {
        const result = await instance.getEngine().layout(layout.name, layout.options);
        report.textContent = result.algorithm;
      }
      instance.fitView(40);
    } finally {
      rerun.disabled = insert.disabled = false;
    }
  }

  rerun.onclick = () => { void run(false); };
  insert.onclick = () => { void run(true); };
  await run(false);
  return () => { instance.dispose(); container.replaceChildren(); };
}

const container = document.createElement('section');
document.body.appendChild(container);
void mountPipeline(container);
```
```ts title="Angular"
import { ChangeDetectorRef, Component, inject, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, layout, insertNode } from './layout-demo';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button (click)="run(false)" [disabled]="!ready()">Rerun layout</button>
    <button (click)="run(true)" [disabled]="!ready()">Insert node</button>
    <span>{{ report() }}</span>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      [layout]="layout" (layoutDone)="onLayoutDone()"
      style="display:block; height:400px" />
  `,
})
export class AppComponent {
  private readonly cdr = inject(ChangeDetectorRef);
  canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  layout = layout;
  busy = signal(false);
  ready = signal(false);
  report = signal('Preparing layout');

  onLayoutDone() {
    this.canvas().fitToContent(40);
    this.ready.set(true);
    this.report.set('layered');
  }

  async run(add: boolean) {
    const canvas = this.canvas();
    const engine = canvas.activeEngine();
    if (!engine) return;
    this.busy.set(true);
    try {
      if (add) {
        const result = await insertNode(engine);
        this.report.set(`Existing nodes moved ${result.movement.total.toFixed(1)} px`);
      } else {
        await canvas.applyLayout();
      }
      canvas.scheduleRender();
      canvas.fitToContent(40);
    } finally {
      this.busy.set(false);
      this.cdr.detectChanges();
    }
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { nodes, edges, layout, insertNode } from './layout-demo';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const ready = useSignal(false);
  const busy = useSignal(false);
  const report = useSignal('Preparing layout');

  return (
    <section>
      <button disabled={!ready.value || busy.value} onClick$={async () => {
        const api = instance.value;
        if (!api) return;
        busy.value = true;
        try {
          const result = await api.getEngine().layout(layout.name, layout.options);
          api.renderNow();
          api.fitView(40);
          report.value = result.algorithm;
        } finally { busy.value = false; }
      }}>Rerun layout</button>
      <button disabled={!ready.value || busy.value} onClick$={async () => {
        const api = instance.value;
        if (!api) return;
        busy.value = true;
        try {
          const result = await insertNode(api.getEngine());
          api.renderNow();
          api.fitView(40);
          report.value = `Existing nodes moved ${result.movement.total.toFixed(1)} px`;
        } finally { busy.value = false; }
      }}>Insert node</button>
      <span>{report.value}</span>
      <div style={{ height: '400px' }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} layout={layout}
          onInit$={(api) => { instance.value = noSerialize(api); }}
          onLayoutDone$={() => {
            instance.value?.renderNow();
            instance.value?.fitView(40);
            ready.value = true;
            report.value = 'layered';
          }} />
      </div>
    </section>
  );
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import { nodes, edges, layout, insertNode } from './layout-demo';

export default function Pipeline() {
  const instance = useRef<DiagramInstance | null>(null);
  const [ready, setReady] = useState(false);
  const [busy, setBusy] = useState(false);
  const [report, setReport] = useState('Preparing layout');

  async function run(add: boolean) {
    const api = instance.current;
    if (!api) return;
    setBusy(true);
    try {
      if (add) {
        const result = await insertNode(api.getEngine());
        setReport(`Existing nodes moved ${result.movement.total.toFixed(1)} px`);
      } else {
        const result = await api.getEngine().layout(layout.name, layout.options);
        setReport(result.algorithm);
      }
      api.fitView(40);
    } finally { setBusy(false); }
  }

  return (
    <section>
      <button disabled={!ready || busy} onClick={() => void run(false)}>Rerun layout</button>
      <button disabled={!ready || busy} onClick={() => void run(true)}>Insert node</button>
      <span>{report}</span>
      <div style={{ height: 400 }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} layout={layout}
          onInit={(api) => { instance.current = api; }}
          onLayoutDone={() => {
            instance.current?.fitView(40);
            setReady(true);
            setReport('layered');
          }} />
      </div>
    </section>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import { nodes, edges, layout, insertNode } from './layout-demo';

const instance = shallowRef<DiagramInstance>();
const ready = ref(false);
const busy = ref(false);
const report = ref('Preparing layout');

function onInit(api: DiagramInstance) { instance.value = api; }
function onLayoutDone() {
  instance.value?.renderNow();
  instance.value?.fitView(40);
  ready.value = true;
  report.value = 'layered';
}
async function run(add: boolean) {
  const api = instance.value;
  if (!api) return;
  busy.value = true;
  try {
    if (add) {
      const result = await insertNode(api.getEngine());
      report.value = `Existing nodes moved ${result.movement.total.toFixed(1)} px`;
    } else {
      const result = await api.getEngine().layout(layout.name, layout.options);
      report.value = result.algorithm;
    }
    api.renderNow();
    api.fitView(40);
  } finally { busy.value = false; }
}
</script>

<template>
  <section>
    <button :disabled="!ready || busy" @click="run(false)">Rerun layout</button>
    <button :disabled="!ready || busy" @click="run(true)">Insert node</button>
    <span>{{ report }}</span>
    <div style="height:400px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :layout="layout"
        @init="onInit" @layout-done="onLayoutDone" />
    </div>
  </section>
</template>
```
:::

The JavaScript sample shows the six-node chain and its two layout buttons.

![JavaScript: n0 through n5 run left to right below Rerun layout and Insert node.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1f24bad8a50be77f63e6d3da6d6d95e7.png)

Angular renders the same chain through its canvas component.

Its Rerun layout and Insert node buttons sit above the six connected boxes and the layered readout.

Qwik renders the initial pipeline before any insertion.

React starts with the same layered arrangement.

Vue also starts with all six boxes in a single row.

The JavaScript mount function returns a cleanup function: call it when your application removes this view. Framework bindings own their canvas teardown.

### Why layout does not follow every data change

Changing node data does not rerun the `layout` prop. That is deliberate: a drag can round-trip through your state without an automatic layout undoing the user's placement. Change the layout request to select another algorithm; to rerun the same request, await `instance.getEngine().layout(layout.name, layout.options)`. The canvas repaints the changed positions. In Angular, `applyLayout()` without an argument reruns the bound request and resolves with its result; it returns `undefined` when there is no engine or request.

### Preserve the mental map

Start with `layered` when you intend to use incremental layout. `layoutIncremental()` defaults to that engine because it honors anchors during coordinate assignment. An initial layout from a different engine can require a substantial rearrangement on the first incremental pass.

The result's `movement` measures pre-existing nodes, excluding ids in `changed`. Use `total`, `average`, `max`, and `withinBudget` to judge disruption in your own graph. A budget is measured and reported; do not treat `withinBudget` as a guarantee that the engine refuses an over-budget result. The returned `tween` is a plan for a host-driven animation, not an animation that runs automatically.

## 4. Compose architecture zones

Use `architecture` when the drawing is a composition of regions rather than a graph ranking. Declare zone membership through [`GroupSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#groupspec): `children` contains node ids, and `direction: 'LR'` lays the zone's boxes in a row. Without explicit bounds, a zone fits its children. Relations such as `sourceHandle: 'top'` can place a connected region above another, and a node's `near` relation places a note beside its subject.

This complete JavaScript sample draws a user outside a services zone, with **Auth** and **Billing** inside it. It uses the same shipped composition that the framework `layout="architecture"` prop selects.

```ts title="architecture.ts"
import { render } from '@grafloria/element';
import type { NodeSpec, EdgeSpec, GroupSpec } from '@grafloria/renderer';

export function mountArchitecture(container: HTMLElement): () => void {
  container.style.height = '400px';
  const nodes: NodeSpec[] = [
    { id: 'user', label: 'User' },
    { id: 'auth', label: 'Auth' },
    { id: 'billing', label: 'Billing' },
  ];
  const edges: EdgeSpec[] = [
    { source: 'user', target: 'auth' },
    { source: 'auth', target: 'billing' },
  ];
  const groups: GroupSpec[] = [
    { id: 'services', label: 'SERVICES', children: ['auth', 'billing'], direction: 'LR' },
  ];
  const instance = render({ nodes, edges, groups, layout: 'architecture' }, container);
  instance.fitView(40);
  return () => instance.dispose();
}

const container = document.createElement('section');
document.body.appendChild(container);
mountArchitecture(container);
```

![User sits outside the SERVICES zone; Auth and Billing sit inside, connected left to right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/dfeb8df92e717a828cd98951ca073334.png)

For React, Vue, or Qwik, pass these typed arrays as `defaultNodes`, `defaultEdges`, and `defaultGroups`, and select `layout="architecture"` on the flow component. For Angular, zones belong to the canvas's active engine: await `addGroup({ name: 'SERVICES' })`, then await `addToGroup(group.id, nodeId)` for each member before calling `applyLayout('architecture')`. These are memberships, not decorative rectangles; see [Group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes).

## Options that matter

Pass common graph-layout options in the request's `options` object or as the second argument to `layout()`. `UnifiedLayoutOptions` normalizes adapter vocabulary so you use `direction`, not adapter-specific direction keys.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `direction` | `'LR' \| 'RL' \| 'TB' \| 'BT'` | Algorithm-dependent | Sets the primary flow direction. |
| `nodeSpacing` | `number` | Algorithm-dependent | Sets the gap between nodes in a rank or row. |
| `rankSpacing` | `number` | Algorithm-dependent | Sets the gap between ranks or layers. |
| `seed` | `number` | `0x5eed` | Makes randomized layouts reproducible. |
| `nested` | `boolean` | Enabled when groups exist | Arranges grouped content recursively; `architecture` composes its own containers. |
| `removeOverlaps` | `boolean` | `true` | Separates boxes left overlapping by an algorithm. |
| `columns` | `number` | `ceil(sqrt(n))` | Sets the number of columns for `grid`. |

For incremental passes, use [`IncrementalOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-incremental#incrementaloptions), not the separate adapter-level incremental options interface.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `changed` | `string[]` | `[]` | Identifies newly added or edited nodes. |
| `strategy` | `'region' \| 'pin-existing' \| 'minimal-shift'` | `'region'` | Allows neighborhood movement, anchors all unchanged nodes, or allows free movement with realignment. |
| `radius` | `number` | `1` | Expands the changed region by graph hops. |
| `budget` | `{ maxPerNode?: number; averagePerNode?: number }` | No budget limits | Sets thresholds for the returned movement report. |

## Live demos and related guides

- [Auto layout](https://grafloria.com/demos/layout/auto-layout.html): switch among algorithms on one graph. [Source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/layout/auto-layout.html).
- [Layout portfolio](https://grafloria.com/demos/layout/layout-portfolio.html): compare tree, radial, circular, grid, and force arrangements.
- [Dynamic layouting](https://grafloria.com/demos/layout/dynamic-layouting.html): compare incremental movement with a full relayout.
- [Architecture layout](https://grafloria.com/demos/diagrams/architecture-layout.html): compare architecture composition with layered ranking on the same text.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) covers canvas sizing and presentation.
- [Import diagram text and files](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/import-diagram-text-and-files) covers architecture composition from Mermaid.
- [Extend layout execution](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/extend-layout-execution) covers customizing how layouts run.

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

# Group and nest nodes

Use groups when a frame needs real membership, not merely a rectangle behind some nodes. This example renders styled Billing and Archive zones, a nested Team container around two selected nodes, and a Delivery pool with three swimlanes. Its toolbar groups the current selection, fits and collapses the latest container, and adds lanes.

## 1. Define the data and group actions

Put this shared browser-side code in `groups.ts`. Describe nodes with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec), links with [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec), and zones with [`GroupSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#groupspec). A zone's `children` become members; without `bounds`, its frame fits those members with padding. A custom `style` replaces the theme's title-band frame with a captioned zone.

The mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) supplies the live model and [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine). `addGroup()` returns a [`GroupModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-groupmodel#groupmodel); `addToGroup()` adds each selected node through an undoable command. The shipped [`SwimlaneService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-interaction#swimlaneservice) creates ordinary groups tiled into lane bands—no custom layout is needed.

```ts title="groups.ts"
import type { DiagramInstance, EdgeSpec, GroupSpec, NodeSpec } from '@grafloria/renderer';
import { SwimlaneService } from '@grafloria/engine';

export const nodes: NodeSpec[] = [
  { id: 'n1', label: 'Review', position: { x: 100, y: 130 }, size: { width: 120, height: 50 }, selected: true },
  { id: 'n2', label: 'Approve', position: { x: 270, y: 130 }, size: { width: 120, height: 50 }, selected: true },
  { id: 'n3', label: 'Archived', position: { x: 600, y: 130 }, size: { width: 120, height: 50 } },
  { id: 'invoice', label: 'Loose invoice', position: { x: 600, y: 310 }, size: { width: 120, height: 50 } },
  { id: 'login', label: 'Login page', position: { x: 160, y: 470 }, size: { width: 140, height: 40 } },
  { id: 'search', label: 'Search API', position: { x: 160, y: 590 }, size: { width: 140, height: 40 } },
  { id: 'pdf', label: 'Export PDF', position: { x: 160, y: 720 }, size: { width: 140, height: 40 } },
];

export const edges: EdgeSpec[] = [
  { id: 'a', source: 'n3', target: 'n1' },
  { id: 'b', source: 'n3', target: 'n2' },
  { id: 'c', source: 'n1', target: 'n2' },
];

export const zones: GroupSpec[] = [
  {
    id: 'billing', label: 'Billing', bounds: { x: 40, y: 40, width: 440, height: 250 },
    style: { fill: '#eff6ff', stroke: '#2563eb', borderRadius: 12, color: '#1d4ed8' },
    labelPlacement: 'top-left',
  },
  {
    id: 'archive', label: 'Archive', children: ['n3'], padding: 30,
    style: { fill: '#f0fdf4', stroke: '#16a34a', strokeDasharray: '6 4', color: '#166534' },
  },
];

export async function setupGroups(instance: DiagramInstance) {
  const engine = instance.getEngine();
  const diagram = instance.getModel();
  engine.setInteractionConfig({ enableGroupMembershipOnDrop: true, enableGroupDrag: true });
  instance.setGroups(zones);
  let latestId: string | undefined;

  async function groupSelected() {
    const ids = diagram.getSelectedNodes().map(node => node.id);
    if (ids.length === 0) return;
    const group = await engine.addGroup({ name: 'Team' });
    for (const id of ids) await engine.addToGroup(group.id, id);
    group.fitToContents(diagram);
    latestId = group.id;
    instance.renderNow();
  }

  async function nestLatest() {
    if (!latestId) return;
    await engine.addToGroup('billing', latestId);
    engine.getGroup('billing')?.fitToContents(diagram, { deepRecursive: true });
    instance.renderNow();
  }

  function fitLatest() {
    if (!latestId) return;
    engine.getGroup(latestId)?.fitToContents(diagram, { mode: 'exact', deepRecursive: true });
    instance.renderNow();
  }

  async function collapseLatest() {
    if (!latestId) return;
    await engine.collapseGroup(latestId, { proxyLabel: info => `${info.count}×` });
    instance.renderNow();
  }

  async function expandLatest() {
    if (!latestId) return;
    await engine.expandGroup(latestId);
    instance.renderNow();
  }

  await groupSelected();
  await nestLatest();

  const lanesService = new SwimlaneService(diagram);
  const { pool, lanes } = lanesService.createPool({
    name: 'Delivery', orientation: 'horizontal',
    bounds: { x: 40, y: 430, width: 740, height: 360 },
    headerSize: 40,
    lanes: [
      { name: 'Backlog', weight: 1 },
      { name: 'In progress', weight: 2 },
      { name: 'Done', weight: 1 },
    ],
  });
  lanes[0]?.addMember('login', diagram);
  lanes[1]?.addMember('search', diagram);
  lanes[2]?.addMember('pdf', diagram);

  function addLane() {
    lanesService.addLane(pool, { name: 'Follow-up', weight: 1 });
    instance.renderNow();
  }

  instance.renderNow();
  instance.fitView(30);
  return { groupSelected, nestLatest, fitLatest, collapseLatest, expandLatest, addLane };
}
```

The initial selection includes Review and Approve, not Archived. Setup groups that pair and embeds Team in Billing. `deepRecursive: true` fits descendant frames first, then fits the parent around their outer frames. Positions remain absolute world coordinates; nesting does not make node positions parent-relative.

> **Known issue:** `GroupSpec.children` ignores group IDs, so declaring `children: ['team']` does not embed an existing Team group. Until it is fixed, use `await engine.addToGroup('billing', latestId)` after creating Team, as `nestLatest()` does.

## 2. Mount it in your framework

Choose the install command for your existing project's framework.

JavaScript:

```bash
npm install @grafloria/element @grafloria/renderer @grafloria/engine
```
React:

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

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

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

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

JavaScript mounts with [`render()`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render). React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow), Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow), and Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) deliver the instance through their initialization callbacks. Qwik stores the live actions with `noSerialize()`.

In Angular, use [`GrafloriaDiagramComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#grafloriadiagramcomponent) for this example's frame-dragging interaction, following the drop-to-contain demo. Each component owns its diagram's teardown. The JavaScript mount returns an unmount function for your host to call when removing the view.

Save the chosen component as `App.tsx`, `App.vue`, or `app.component.ts`. Save the JavaScript entry as `main.ts`; it creates its own host and controls.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, setupGroups } from './groups';

export async function mountGroups(parent: HTMLElement) {
  const view = document.createElement('section');
  const toolbar = document.createElement('div');
  const canvas = document.createElement('div');
  canvas.style.height = '650px';
  view.append(toolbar, canvas);
  parent.append(view);
  const instance = render({ nodes, edges }, canvas);
  const actions = await setupGroups(instance);
  const buttons = [
    ['Group selected', actions.groupSelected],
    ['Nest latest', actions.nestLatest],
    ['Fit latest', actions.fitLatest],
    ['Collapse latest', actions.collapseLatest],
    ['Expand latest', actions.expandLatest],
    ['Add lane', actions.addLane],
  ] as const;
  for (const [label, action] of buttons) {
    const button = document.createElement('button');
    button.textContent = label;
    button.addEventListener('click', () => { void action(); });
    toolbar.append(button);
  }
  return () => { instance.dispose(); view.remove(); };
}

void mountGroups(document.body);
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, setupGroups } from './groups';

export default function App() {
  const actions = useRef<Awaited<ReturnType<typeof setupGroups>> | null>(null);
  const live = useRef<DiagramInstance | null>(null);
  async function onInit(instance: DiagramInstance) {
    live.current = instance;
    const next = await setupGroups(instance);
    if (live.current === instance) actions.current = next;
  }
  return <section>
    <div>
      <button onClick={() => void actions.current?.groupSelected()}>Group selected</button>
      <button onClick={() => void actions.current?.nestLatest()}>Nest latest</button>
      <button onClick={() => actions.current?.fitLatest()}>Fit latest</button>
      <button onClick={() => void actions.current?.collapseLatest()}>Collapse latest</button>
      <button onClick={() => void actions.current?.expandLatest()}>Expand latest</button>
      <button onClick={() => actions.current?.addLane()}>Add lane</button>
    </div>
    <div style={{ height: 650 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} onInit={onInit} />
    </div>
  </section>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, setupGroups } from './groups';

const actions = shallowRef<Awaited<ReturnType<typeof setupGroups>>>();
async function onInit(instance: DiagramInstance) {
  actions.value = await setupGroups(instance);
}
</script>

<template>
  <section>
    <div>
      <button @click="actions?.groupSelected()">Group selected</button>
      <button @click="actions?.nestLatest()">Nest latest</button>
      <button @click="actions?.fitLatest()">Fit latest</button>
      <button @click="actions?.collapseLatest()">Collapse latest</button>
      <button @click="actions?.expandLatest()">Expand latest</button>
      <button @click="actions?.addLane()">Add lane</button>
    </div>
    <div style="height:650px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="onInit" />
    </div>
  </section>
</template>
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, setupGroups } from './groups';

export default component$(() => {
  const actions = useSignal<NoSerialize<Awaited<ReturnType<typeof setupGroups>>>>();
  return <section>
    <div>
      <button onClick$={async () => { await actions.value?.groupSelected(); }}>Group selected</button>
      <button onClick$={async () => { await actions.value?.nestLatest(); }}>Nest latest</button>
      <button onClick$={() => { actions.value?.fitLatest(); }}>Fit latest</button>
      <button onClick$={async () => { await actions.value?.collapseLatest(); }}>Collapse latest</button>
      <button onClick$={async () => { await actions.value?.expandLatest(); }}>Expand latest</button>
      <button onClick$={() => { actions.value?.addLane(); }}>Add lane</button>
    </div>
    <div style={{ height: '650px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        onInit$={async (instance: DiagramInstance) => {
          actions.value = noSerialize(await setupGroups(instance));
        }} />
    </div>
  </section>;
});
```
```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, setupGroups } from './groups';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: `
    <div>
      <button (click)="actions?.groupSelected()">Group selected</button>
      <button (click)="actions?.nestLatest()">Nest latest</button>
      <button (click)="actions?.fitLatest()">Fit latest</button>
      <button (click)="actions?.collapseLatest()">Collapse latest</button>
      <button (click)="actions?.expandLatest()">Expand latest</button>
      <button (click)="actions?.addLane()">Add lane</button>
    </div>
    <grafloria-diagram [spec]="spec" (ready)="onReady($event)"
      style="display:block;height:650px" />
  `,
})
export class AppComponent {
  readonly spec = { nodes, edges };
  actions?: Awaited<ReturnType<typeof setupGroups>>;
  async onReady(instance: DiagramInstance) {
    this.actions = await setupGroups(instance);
  }
}
```
:::

The JavaScript mount shows Team nested in Billing, Archive to the right, and Delivery below the loose invoice.

![JavaScript: the nested Team frame, Archive zone, and three Delivery lanes beneath the six toolbar buttons.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/85903f2e5819ca1d142044f58cf627a5.png)

React renders the selected Review and Approve nodes inside Team.

![React: Review and Approve have blue selection outlines inside Team and Billing.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/d79336b530518c10e813164d27103168.png)

Vue renders the same container structure and lane tickets.

Qwik renders the loose invoice outside both upper zones.

Angular's diagram host renders the styled zones and nested frame.

## 3. Use the containers

- Ctrl-click nodes or marquee a selection, then press **Group selected**. A fitted Team frame wraps exactly the selected nodes. With no selected nodes, the button does nothing.
- Press **Nest latest** to embed that container in Billing. Press **Fit latest** after moving its members to recompute its frame, including nested descendants.
- Drag Loose invoice into Billing or Archive and release. It joins the target; drag an empty part of that frame and its members travel with it. Drop the invoice on empty canvas to detach it, or into the other frame to transfer membership. The innermost group wins a drop when frames overlap.
- Press **Collapse latest**. Review and Approve hide behind a placeholder for the initial Team; their two incoming crossings from Archived aggregate into a proxy labelled `2×`. Press **Expand latest** to restore the original members and links. Use the engine calls, not `GroupModel.collapse()` alone, for this reversible link transformation.
- Drag Search API between Delivery lanes. Lanes constrain tickets to the pool, but allow transfer to sibling lanes. Press **Add lane** to add Follow-up and redistribute the bands. In progress starts with twice the height of either other lane because its weight is `2`.

### Group a selection on the Angular canvas

If you use [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent), access its `activeEngine()` after the view initializes. This smaller example groups Review and Approve on the mounted canvas, following the selection-grouping demo. Use the diagram host above for dragging group frames.

```ts title="selection.component.ts"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-selection',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:400px" />
  `,
})
export class SelectionComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = [
    { id: 'review', label: 'Review', position: { x: 100, y: 140 }, size: { width: 120, height: 50 }, selected: true },
    { id: 'approve', label: 'Approve', position: { x: 300, y: 140 }, size: { width: 120, height: 50 }, selected: true },
    { id: 'other', label: 'Leave out', position: { x: 550, y: 280 }, size: { width: 120, height: 50 } },
  ];
  edges: EdgeSpec[] = [{ source: 'review', target: 'approve' }];

  async ngAfterViewInit() {
    const engine = this.canvas().activeEngine();
    const diagram = engine?.getDiagram();
    if (!engine || !diagram) return;
    const ids = diagram.getSelectedNodes().map(node => node.id);
    const group = await engine.addGroup({ name: 'Team' });
    for (const id of ids) await engine.addToGroup(group.id, id);
    group.fitToContents(diagram);
    this.canvas().scheduleRender();
  }
}
```

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `GroupSpec.bounds` | `{ x: number; y: number; width: number; height: number }` | Not set | Supplies the authored frame rather than initially fitting it. |
| `GroupSpec.padding` | `number` | `20` | Adds space around members in a fitted zone. Caption room can add extra space. |
| `GroupSpec.labelPlacement` | `'top-left' \| 'top' \| 'top-right' \| 'bottom-left' \| 'bottom' \| 'bottom-right'` | `'top-left'` | Positions the zone caption. |
| `enableGroupMembershipOnDrop` | `boolean` | `true` | Enables drag-end membership changes. |
| `enableGroupDrag` | `boolean` | `true` | Enables moving frames with their members. |
| `GroupModel.fitMode` | `'exact' \| 'grow-only' \| 'shrink-only'` | `'exact'` | Controls whether fitting can grow, shrink, or do both. |
| `GroupModel.constrainChildren` | `boolean` | `false` | Keeps direct member nodes inside the inner extent; swimlanes set it to `true`. |
| [`LaneSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-interaction#lanespec).`weight` | `number` | `1` | Shares remaining cross-axis space proportionally. |
| `LaneSpec.fixedSize` | `number` | Not set | Pins a lane's cross-axis size instead of using its weight. |
| [`CollapseOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-interaction#collapseoptions).`proxyLabel` | `(info: ProxyLabelInfo) => string` | Count for multiple crossings; no synthetic label for one | Labels aggregated crossing links using [`ProxyLabelInfo`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-interaction#proxylabelinfo). |

## Pitfalls

`setGroups()` reconciles the entire group set, not a patch. Include every group you want to retain; omitted groups are removed while their nodes remain. After setup, the example uses engine methods rather than resending `zones`, so Team and the swimlane groups stay in the model.

An authored frame can grow when a new member lies outside it. Use `constrainChildren` when the frame is an extent that members must stay within. Fit a nonempty group: `fitToContents()` does nothing when it has no positioned members.

The grouping toolbar performs several engine commands: creating the group and adding each member are separate history operations. For command composition and undo controls, see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history). For saving membership and collapsed state, use the live document format described in [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

## Live demos and related guides

Try [Selection grouping](https://grafloria.com/demos/grouping/selection-grouping.html), [Drop to contain](https://grafloria.com/demos/grouping/drop-to-contain.html), [Collapse & expand](https://grafloria.com/demos/grouping/collapse-expand.html), and [Swimlanes](https://grafloria.com/demos/grouping/swimlanes.html). The [swimlane demo source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/grouping/swimlanes.html) also shows lane counts and resizing.

- [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) explains composing layouts and zone directions.
- [Configure editing gestures](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/configure-editing-gestures) covers interaction settings beyond membership.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) covers canvas styling and container sizing.

<!-- source: theme-a-canvas.md -->

# Theme a canvas

Use a theme for canvas-wide defaults and spec styles for individual nodes and edges. One [`Theme`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-s-v) object drives node defaults, link colors and selection states; changing it repaints the mounted diagram without replacing your data.

The examples below draw four nodes: a theme-default node, an orange named-style node, a theme-bound warning node, and a gradient-filled node with a shadow. The buttons switch palettes or request a host-token bridge.

## 1. Install your binding

Run the command for your existing framework project. The JavaScript example runs in the browser through your project's bundler.

JavaScript:

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

React:

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

Vue:

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

Angular:

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

Qwik:

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

## 2. Describe the paint once

Create `canvas-theme.ts` beside your component. Type the data with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec); the bindings turn these specs into live models.

Start with the shipped [`LIGHT_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants), [`DARK_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants), [`HIGH_CONTRAST_LIGHT_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants) and [`HIGH_CONTRAST_DARK_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants). Use [`themeRef`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions) when a property expresses a meaning rather than a fixed color: `category.warning` reads the active theme's warning palette, and `numbers.emphasis` reads its numeric scale.

Register reusable paint with [`defineStyles`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions). This is the named-style extension point; the mounted canvas consumes the definitions through `style.styleClass`.

The initialization helper receives a mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance). The shipped [`muiBridge`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions) supplies the host-token map used by the buttons.

```ts title="canvas-theme.ts"
import {
  LIGHT_THEME, DARK_THEME,
  HIGH_CONTRAST_LIGHT_THEME, HIGH_CONTRAST_DARK_THEME,
  defineStyles, themeRef, muiBridge,
  type Theme, type NodeSpec, type EdgeSpec, type DiagramInstance,
} from '@grafloria/renderer';

export const palettes: Record<string, Theme> = {
  light: LIGHT_THEME,
  dark: DARK_THEME,
  contrastLight: HIGH_CONTRAST_LIGHT_THEME,
  contrastDark: HIGH_CONTRAST_DARK_THEME,
};

export function registerPaint(): void {
  defineStyles({
    'orders-warning': { fill: '#fed7aa', stroke: '#9a3412', strokeWidth: 2 },
    'orders-bold': { strokeWidth: 5 },
  });
}

export const nodes: NodeSpec[] = [
  { id: 'plain', label: 'Theme default',
    position: { x: 50, y: 70 }, size: { width: 180, height: 76 } },
  { id: 'named', label: 'Named warning',
    position: { x: 350, y: 70 }, size: { width: 180, height: 76 },
    style: { styleClass: 'orders-warning orders-bold' } },
  { id: 'bound', label: 'Theme-bound warning',
    position: { x: 50, y: 230 }, size: { width: 180, height: 76 },
    style: {
      fill: themeRef('category.warning'),
      stroke: themeRef('category.warning'),
      strokeWidth: themeRef('numbers.emphasis'),
    } },
  { id: 'gradient', label: 'Gradient + shadow',
    position: { x: 350, y: 230 }, size: { width: 180, height: 76 },
    style: {
      fill: {
        type: 'linear', x1: 0, y1: 0, x2: 1, y2: 0,
        stops: [
          { offset: 0, color: '#ddd6fe' },
          { offset: 1, color: '#fbcfe8' },
        ],
      },
      stroke: '#7c3aed', strokeWidth: 2,
      shadow: { offsetX: 4, offsetY: 6, blur: 8, color: 'rgba(0,0,0,0.3)' },
    } },
];

export const edges: EdgeSpec[] = [
  { id: 'named-edge', source: 'plain', target: 'named',
    style: { styleClass: 'orders-warning', strokeDasharray: '6 3' } },
  { id: 'bound-edge', source: 'bound', target: 'gradient',
    style: {
      stroke: themeRef('category.warning'),
      strokeWidth: themeRef('numbers.emphasis'),
    } },
];

export function prepareCanvas(instance: DiagramInstance): void {
  registerPaint();
  instance.renderNow();
}

export const hostBridge = muiBridge();

export function useHostTokens(
  instance: DiagramInstance | null | undefined,
  enabled: boolean,
): void {
  if (!instance) return;
  instance.setTokenBridge(enabled ? hostBridge : null);
  instance.renderNow();
  const node = instance.container.querySelector('[data-node-id="plain"] rect.diagram-node');
  if (!node) return;
  const paint = getComputedStyle(node);
  let readout = instance.container.querySelector('output');
  if (!readout) {
    readout = document.createElement('output');
    readout.style.cssText = 'position:absolute; bottom:0; left:0; background:white; color:black';
    instance.container.append(readout);
  }
  readout.textContent = `Resolved default paint: fill ${paint.fill}; stroke ${paint.stroke}`;
}

export const hostCSS = `
.orders-host {
  --mui-palette-background-paper: #fffbf2;
  --mui-palette-divider: #b8860b;
  --mui-palette-text-primary: #1c1b1f;
  --mui-palette-primary-main: #6750a4;
}
`;
```

The named node gets the orange fill and a five-unit border: later names in the space-separated `styleClass` list win conflicts. An element's own `fill`, `stroke` or `strokeWidth` overrides its named styles; interaction state sits above both. The cascade is **theme → type-default → named-class → element-inline → state**.

Gradient objects produce SVG paint servers, and shadow objects produce drop-shadow filters. Use a linear gradient's normalized endpoints and stops as above, or a radial gradient with `type: 'radial'`, `cx`, `cy`, `r` and `stops`. Edge `stroke` accepts the same gradient objects; an edge is a line, not a filled box.

## 3. Mount and switch the palette

Choose your framework tab. Each sample uses the shared file from step 2 and gives the drawing a resolved height of 400px. **Light**, **Dark**, **Contrast light** and **Contrast dark** change the theme. **Host tokens** requests the MUI bridge; **Theme tokens** requests its removal.

Pass `theme` to JavaScript's [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core), or bind it on React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react), Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue), Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) or Angular's [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent); see [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for mounting and instance access.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import {
  nodes, edges, palettes, prepareCanvas, useHostTokens, hostCSS,
} from './canvas-theme';

const wrapper = document.createElement('section');
wrapper.className = 'orders-host';
const style = document.createElement('style');
style.textContent = hostCSS;
const toolbar = document.createElement('div');
const canvas = document.createElement('div');
canvas.style.height = '400px';
wrapper.append(style, toolbar, canvas);
document.body.append(wrapper);

const instance = render({ nodes, edges }, canvas, { theme: palettes.light });
prepareCanvas(instance);
for (const [key, label] of [
  ['light', 'Light'], ['dark', 'Dark'],
  ['contrastLight', 'Contrast light'], ['contrastDark', 'Contrast dark'],
]) {
  const button = document.createElement('button');
  button.textContent = label;
  button.onclick = () => instance.setTheme(palettes[key]);
  toolbar.append(button);
}
for (const enabled of [true, false]) {
  const button = document.createElement('button');
  button.textContent = enabled ? 'Host tokens' : 'Theme tokens';
  button.onclick = () => useHostTokens(instance, enabled);
  toolbar.append(button);
}
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance, Theme } from '@grafloria/renderer';
import {
  nodes, edges, palettes, prepareCanvas, useHostTokens, hostCSS,
} from './canvas-theme';

export default function App() {
  const [theme, setTheme] = useState<Theme>(palettes.light);
  const instance = useRef<DiagramInstance | null>(null);
  return (
    <section className="orders-host">
      <style>{hostCSS}</style>
      <button onClick={() => setTheme(palettes.light)}>Light</button>
      <button onClick={() => setTheme(palettes.dark)}>Dark</button>
      <button onClick={() => setTheme(palettes.contrastLight)}>Contrast light</button>
      <button onClick={() => setTheme(palettes.contrastDark)}>Contrast dark</button>
      <button onClick={() => useHostTokens(instance.current, true)}>Host tokens</button>
      <button onClick={() => useHostTokens(instance.current, false)}>Theme tokens</button>
      <div style={{ height: 400 }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} theme={theme}
          onInit={(api) => { instance.current = api; prepareCanvas(api); }} />
      </div>
    </section>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, Theme } from '@grafloria/renderer';
import {
  nodes, edges, palettes, prepareCanvas, useHostTokens, hostCSS,
} from './canvas-theme';

const theme = shallowRef<Theme>(palettes.light);
const instance = shallowRef<DiagramInstance | null>(null);
function onInit(api: DiagramInstance): void {
  instance.value = api;
  prepareCanvas(api);
}
</script>

<template>
  <section class="orders-host">
    <component :is="'style'">{{ hostCSS }}</component>
    <button @click="theme = palettes.light">Light</button>
    <button @click="theme = palettes.dark">Dark</button>
    <button @click="theme = palettes.contrastLight">Contrast light</button>
    <button @click="theme = palettes.contrastDark">Contrast dark</button>
    <button @click="useHostTokens(instance, true)">Host tokens</button>
    <button @click="useHostTokens(instance, false)">Theme tokens</button>
    <div style="height:400px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
        :theme="theme" @init="onInit" />
    </div>
  </section>
</template>
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { Theme, TokenBridge, NodeSpec, EdgeSpec } from '@grafloria/renderer';
import {
  nodes, edges, palettes, registerPaint, hostBridge, hostCSS,
} from './canvas-theme';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  styles: [hostCSS],
  template: `
    <section class="orders-host">
      <button (click)="theme = palettes['light']">Light</button>
      <button (click)="theme = palettes['dark']">Dark</button>
      <button (click)="theme = palettes['contrastLight']">Contrast light</button>
      <button (click)="theme = palettes['contrastDark']">Contrast dark</button>
      <button (click)="bridge = hostBridge">Host tokens</button>
      <button (click)="bridge = undefined">Theme tokens</button>
      <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
        [theme]="theme" [tokenBridge]="bridge" style="display:block; height:400px" />
    </section>
  `,
})
export class AppComponent {
  readonly palettes = palettes;
  readonly hostBridge = hostBridge;
  theme: Theme = palettes['light'];
  bridge: TokenBridge | undefined;
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  constructor() { registerPaint(); }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance, Theme } from '@grafloria/renderer';
import {
  nodes, edges, palettes, prepareCanvas, useHostTokens, hostCSS,
} from './canvas-theme';

export default component$(() => {
  const theme = useSignal<Theme>(palettes.light);
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  return (
    <section class="orders-host">
      <style dangerouslySetInnerHTML={hostCSS} />
      <button onClick$={() => { theme.value = palettes.light; }}>Light</button>
      <button onClick$={() => { theme.value = palettes.dark; }}>Dark</button>
      <button onClick$={() => { theme.value = palettes.contrastLight; }}>Contrast light</button>
      <button onClick$={() => { theme.value = palettes.contrastDark; }}>Contrast dark</button>
      <button onClick$={() => useHostTokens(instance.value, true)}>Host tokens</button>
      <button onClick$={() => useHostTokens(instance.value, false)}>Theme tokens</button>
      <div style={{ height: '400px' }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} theme={theme.value}
          onInit$={(api) => {
            instance.value = noSerialize(api);
            prepareCanvas(api);
          }} />
      </div>
    </section>
  );
});
```
:::

![Initial light palette: four nodes, a dashed upper edge, a solid warning-colored lower edge, and six palette and token buttons. The lower-right node has a purple-to-pink fill and a shadow.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/303df64adb0278d9289f1367f61c7248.png)

The default node follows each palette. The literal orange and gradient fills remain literal; the warning node and its edge follow the theme's semantic colors and numeric scale. Qwik registers the named styles in the browser's initialization callback and keeps the live instance out of serialized state.

## Choose `theme` or `colorMode`

Use `theme` when your application selects a complete palette, as above. Use [`ColorMode`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-types) when Grafloria selects the palette from a light/dark choice or OS preferences:

- React and Qwik: pass `colorMode="system"` to the flow instead of `theme`.
- Vue: pass `color-mode="system"` instead of `:theme`.
- Angular: bind `[colorMode]="'system'"` instead of `[theme]`.
- JavaScript: pass `colorMode: 'system'` in the options to `render()` instead of `theme`.

`'light'` and `'dark'` select the light/dark axis explicitly; `'system'` follows `prefers-color-scheme`. A request for more contrast or active forced colors upgrades that axis to the available high-contrast theme, even with an explicit light/dark choice. The default set includes both high-contrast palettes.

On a mounted instance, `setColorMode('system')` starts following the OS and `getColorMode()` returns the requested mode, not the resolved theme. Pass a [`ThemeSet`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-interfaces) as the second argument to choose your own `light`, `dark`, `highContrastLight` and `highContrastDark` palettes. Angular exposes the same set through `[themes]`.

While a binding's `colorMode` is set, it takes precedence over `theme`. In React, removing the prop keeps the last mode. Do not combine the manual palette buttons above with a mode prop that selects a different palette.

## Bridge and scope CSS variables

The shared file uses the shipped `muiBridge` to map Grafloria colors to MUI's `--mui-palette-*` variables. **Host tokens** calls `setTokenBridge(hostBridge)`; **Theme tokens** calls `setTokenBridge(null)`. Angular supplies or removes the bridge through its `[tokenBridge]` input.

In JavaScript, React, Vue and Qwik, the token-button helper reads the default node's browser-computed fill and stroke when it finds the rendered rectangle. The readout reports computed paint, not the requested palette; a bridge request alone does not establish a visible paint change.

The bridge is a [`TokenBridge`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-types): a map from a token such as `node.fill` to a CSS expression such as `var(--app-card)`. For other design systems, use the shipped [`shadcnBridge`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions) or [`tailwindBridge`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions). The shadcn preset supports HSL components, OKLCH components or full color values; the Tailwind preset targets v4's `--color-*` variables.

Keep host variables on the wrapper, as `.orders-host` does, rather than changing `:root` for one diagram. Grafloria scopes its own variable block to the rendered root's `data-grafloria-instance` value. Two diagrams can use different themes on one page; `setTheme()` rewrites only the target instance's block. No Grafloria stylesheet import is required.

`styleClass` names registered paint; it is not a CSS class selector. Use `style.className` for a host-CSS hook on a rendered node or edge. Keep that CSS under your wrapper selector too.

## Options that matter

| Option | Type | Default | What it does |
|---|---|---|---|
| `theme` | `Theme` | Built-in light theme without another theme source | Sets the palette for defaults and state colors. |
| `colorMode` | `'light' \| 'dark' \| 'system'` | No requested mode | Selects the light/dark axis and watches accessibility preferences. |
| Angular `themes` / `setColorMode()` second argument | `ThemeSet` | Built-in light, dark and high-contrast set | Supplies the palettes a mode chooses between. |
| `tokenBridge` | `TokenBridge` | No bridge | Repoints scoped variables to host CSS values. |
| `style.styleClass` | `string` | No named style | Applies registered styles, left to right. |
| `style.className` | `string` | No extra class | Adds a hook for your CSS. |
| Node `style.fill` / node or edge `style.stroke` | Color string, linear/radial gradient or pattern | Cascade supplies paint | Overrides lower paint layers. |
| `style.strokeWidth` | `number` | Cascade supplies width | Sets border or line weight. |
| Node `style.shadow` | Boolean or shadow object | No element override | Uses a drop-shadow filter for a shadow object. |

## Pitfalls

A canvas fills its parent. If that parent has no resolved height, the drawing is blank: give the wrapper a real height or a sized flex/grid allocation, as the samples do.

Namespace global named styles, such as `orders-warning`, to avoid replacing another feature's definitions. Fixed colors do not become theme-bound when you switch palettes; use `themeRef()` for paint that must follow a theme.

For styling your own HTML node content, continue with [JavaScript elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).

## Live demos and related guides

- [Dark mode](https://grafloria.com/demos/styling/dark-mode.html) exercises mode and OS preferences.
- [Themes and design tokens](https://grafloria.com/demos/styling/themes-and-tokens.html) switches among the shipped token bridges.
- [Named style classes](https://grafloria.com/demos/styling/named-style-classes.html) demonstrates cascade precedence.
- [Theme-bound properties](https://grafloria.com/demos/styling/theme-bound-properties.html) switches semantic paint and numeric scales.
- [Paint servers](https://grafloria.com/demos/styling/paint-servers.html) shows gradients, patterns and shadows.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) covers ownership and teardown.

<!-- source: highlight-and-animate-state.md -->

# Highlight and animate state

Use outlines to show hover, selection and validation, and connected-line highlighting to follow a selected step. Use execution statuses and animated strokes to show progress. The examples draw a completed Fetch node, a pulsing Transform node, a pending Save node, and a moving token on the Fetch–Transform wire.

## 1. Define the progress display

Keep specs and live state separate: [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) seed the diagram; query its live [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel) to update progress. The outline settings use [`HighlighterConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-interfaces-a-t); connected-line settings use [`HighlightConnectedOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-b-s).

Create `state.ts` in your browser application's source directory, then mount it with the entry file in step 2. Run on its own, this module mounts a preview; the framework entry replaces that preview when it initializes. The extra Audit–Log branch makes the dimming visible: Transform starts selected, so its connected wires stand out while the unrelated wire fades.

```typescript title="state.ts"
import { render } from '@grafloria/element';
import type { DiagramModel } from '@grafloria/engine';
import type {
  DiagramInstance, NodeSpec, EdgeSpec,
  HighlighterConfig, HighlightConnectedOptions,
} from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'fetch', label: 'Fetch', position: { x: 40, y: 80 },
    size: { width: 120, height: 56 } },
  { id: 'transform', label: 'Transform', selected: true,
    position: { x: 280, y: 80 }, size: { width: 120, height: 56 } },
  { id: 'save', label: 'Save', position: { x: 520, y: 80 },
    size: { width: 120, height: 56 } },
  { id: 'audit', label: 'Audit', position: { x: 40, y: 240 },
    size: { width: 120, height: 56 } },
  { id: 'log', label: 'Log', position: { x: 280, y: 240 },
    size: { width: 120, height: 56 } },
];

export const edges: EdgeSpec[] = [
  { id: 'active', source: 'fetch', target: 'transform',
    style: { animation: { type: 'marching-ants', speed: 'normal' } } },
  { id: 'next', source: 'transform', target: 'save' },
  { id: 'other', source: 'audit', target: 'log' },
];

export const outlines: Partial<HighlighterConfig> = {
  showValidation: false,
};
export const connected: HighlightConnectedOptions = {
  depth: 1, outgoing: 'dashed', dimOpacity: 0.25,
};

let removePreview: (() => void) | undefined;

export function showProgress(model: DiagramModel): void {
  removePreview?.();
  removePreview = undefined;
  model.getNode('fetch')?.setState({ status: 'completed' });
  model.getNode('transform')?.setState({ status: 'running', animateStatus: true });
  model.getNode('save')?.setState({ status: 'pending' });
}

export function attach(
  instance: DiagramInstance,
  reportDragging: (text: string) => void,
): () => void {
  showProgress(instance.getModel());
  instance.fitView(40);
  instance.renderNow();
  const removeRider = mountRider(instance.container);
  const report = () => {
    const ids = instance.getDraggingNodeIds();
    reportDragging(ids.length ? ids.join(', ') : 'none');
  };
  report();
  const timer = window.setInterval(report, 100);
  return () => {
    window.clearInterval(timer);
    removeRider();
  };
}

let riderId = 0;

export function mountRider(host: HTMLElement): () => void {
  const painted = host.querySelector('svg');
  if (!painted) return () => {};
  const ns = 'http://www.w3.org/2000/svg';
  const overlay = document.createElementNS(ns, 'svg');
  overlay.style.cssText =
    'position:absolute;inset:0;width:100%;height:100%;pointer-events:none';
  overlay.setAttribute('aria-hidden', 'true');
  const guide = document.createElementNS(ns, 'path');
  do {
    guide.id = `rider-${++riderId}`;
  } while (document.getElementById(guide.id));
  guide.setAttribute('fill', 'none');
  guide.setAttribute('stroke', 'none');
  const token = document.createElementNS(ns, 'circle');
  token.setAttribute('r', '6');
  token.setAttribute('fill', '#ec4899');
  token.setAttribute('stroke', '#fff');
  token.setAttribute('stroke-width', '1.5');
  const motion = document.createElementNS(ns, 'animateMotion');
  motion.setAttribute('dur', '2.4s');
  motion.setAttribute('begin', '-0.6s');
  motion.setAttribute('repeatCount', 'indefinite');
  const path = document.createElementNS(ns, 'mpath');
  path.setAttribute('href', `#${guide.id}`);
  motion.appendChild(path);
  token.appendChild(motion);
  overlay.append(guide, token);
  host.appendChild(overlay);

  const sync = () => {
    overlay.setAttribute('viewBox', painted.getAttribute('viewBox') ?? '0 0 680 360');
    overlay.setAttribute('preserveAspectRatio',
      painted.getAttribute('preserveAspectRatio') ?? 'xMidYMid meet');
    const wire = painted.querySelector('[data-link-id="active"] path.diagram-link');
    guide.setAttribute('d', wire?.getAttribute('d') ?? '');
  };
  sync();
  const observer = new MutationObserver(sync);
  observer.observe(painted, {
    attributes: true, attributeFilter: ['d', 'viewBox', 'preserveAspectRatio'],
    childList: true, subtree: true,
  });
  const preference = window.matchMedia('(prefers-reduced-motion: reduce)');
  const respectMotion = () => { token.style.display = preference.matches ? 'none' : ''; };
  respectMotion();
  preference.addEventListener('change', respectMotion);
  return () => {
    observer.disconnect();
    preference.removeEventListener('change', respectMotion);
    overlay.remove();
  };
}

if (typeof document !== 'undefined') {
  const preview = document.createElement('div');
  preview.style.cssText = 'position:relative;height:400px';
  document.body.appendChild(preview);
  const instance = render({ nodes, edges }, preview, {
    highlighterConfig: outlines, highlightConnected: connected,
  });
  const detach = attach(instance, () => {});
  removePreview = () => {
    detach();
    instance.dispose();
    preview.remove();
  };
}
```

The shipped stroke animation comes from `style.animation`. The token is different: it is application-owned SVG, not an engine particle API. Following the authors' animating-edges example, it rides a copy of the **painted** path with `animateMotion` and `mpath`. A sibling overlay mirrors the renderer's `viewBox` and path geometry during pan, zoom and rerouting. Do not append tokens inside the renderer-owned SVG subtree.

## 2. Mount it in your framework

Install the packages for your framework in your own project.

JavaScript:

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
```
Angular:

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

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

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

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

For this display, pass `highlighterConfig` and `highlightConnected` to [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) or React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react), Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) or Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik), and use `rendererConfig.highlightConnected` on Angular's [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent); see [edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for mounting and accessing the [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance) or Angular's `activeEngine()`.

Use the matching file below alongside `state.ts`. Each mounts the same progress display in a sized container. In the instance-based bindings, the readout shows the ids currently being dragged; it reads `none` before movement passes the drag threshold and after release. The Angular canvas does not expose `getDraggingNodeIds()`.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, outlines, connected, attach } from './state';

export function mountProgress(parent: HTMLElement): () => void {
  const readout = document.createElement('p');
  const host = document.createElement('div');
  host.style.cssText = 'position:relative;height:400px';
  parent.append(readout, host);
  const instance = render({ nodes, edges }, host, {
    highlighterConfig: outlines, highlightConnected: connected,
  });
  const detach = attach(instance, text => { readout.textContent = `Dragging: ${text}`; });
  return () => {
    detach();
    instance.dispose();
    readout.remove();
    host.remove();
  };
}

const parent = document.getElementById('app')!;
export const unmountProgress = mountProgress(parent);
// Call unmountProgress() when your application removes this view.
```
```ts title="Angular"
import { AfterViewInit, Component, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, outlines, connected, showProgress, mountRider } from './state';

@Component({
  selector: 'app-progress',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div #host style="position:relative;height:400px">
      <grafloria-diagram-canvas
        [(nodes)]="nodes" [(edges)]="edges"
        [highlighterConfig]="outlines" [rendererConfig]="rendererConfig"
        style="display:block;height:100%" />
    </div>
  `,
})
export class ProgressComponent implements AfterViewInit, OnDestroy {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly host = viewChild.required<ElementRef<HTMLElement>>('host');
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  readonly outlines = outlines;
  readonly rendererConfig = { highlightConnected: connected };
  private removeRider: (() => void) | undefined;
  private frame: number | undefined;

  ngAfterViewInit(): void {
    const model = this.canvas().activeEngine()?.getDiagram();
    if (model) showProgress(model);
    this.canvas().fitToContent(40);
    this.canvas().scheduleRender();
    this.frame = requestAnimationFrame(() => {
      this.removeRider = mountRider(this.host().nativeElement);
    });
  }
  ngOnDestroy(): void {
    if (this.frame !== undefined) cancelAnimationFrame(this.frame);
    this.removeRider?.();
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { nodes, edges, outlines, connected, attach } from './state';

export default component$(() => {
  const dragging = useSignal('none');
  const detach = useSignal<NoSerialize<() => void>>();
  useVisibleTask$(({ cleanup }) => {
    cleanup(() => detach.value?.());
  });
  return <>
    <p>Dragging: {dragging.value}</p>
    <div style={{ position: 'relative', height: '400px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        highlighterConfig={outlines} highlightConnected={connected}
        onInit$={instance => {
          detach.value?.();
          detach.value = noSerialize(attach(instance, text => { dragging.value = text; }));
        }} />
    </div>
  </>;
});
```
```tsx title="React"
import { useEffect, useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import { nodes, edges, outlines, connected, attach } from './state';

export default function Progress() {
  const [dragging, setDragging] = useState('none');
  const detach = useRef<(() => void) | undefined>(undefined);
  useEffect(() => () => detach.current?.(), []);
  return <>
    <p>Dragging: {dragging}</p>
    <div style={{ position: 'relative', height: 400 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        highlighterConfig={outlines} highlightConnected={connected}
        onInit={instance => {
          detach.current?.();
          detach.current = attach(instance, setDragging);
        }} />
    </div>
  </>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, outlines, connected, attach } from './state';

const dragging = ref('none');
let detach: (() => void) | undefined;
function init(instance: DiagramInstance): void {
  detach?.();
  detach = attach(instance, text => { dragging.value = text; });
}
onBeforeUnmount(() => detach?.());
</script>

<template>
  <p>Dragging: {{ dragging }}</p>
  <div style="position:relative;height:400px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
      :highlighter-config="outlines" :highlight-connected="connected" @init="init" />
  </div>
</template>
```
:::

![Fetch has a green border, Transform is selected with blue outlines, and a pink token sits on their dashed wire. The Audit–Log wire is faded; the readout shows Dragging: none.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e55985a8fdadbd07c93514c341076080.png)

Fetch has a green completed stroke, Transform has a blue running stroke and pulse, and Save appears faded as pending. The pink circle travels along the animated incoming wire. Select another node to move the connected-line emphasis; click the background to remove it. Hover and selection outlines remain enabled, while validation outlines are disabled in this example.

## 3. Choose the effects you need

`highlighterConfig={false}` disables only the extra outline layer, not selection itself. `true` enables all kinds. An object starts from the defaults on each assignment, so `{ showHover: false }` keeps the other kinds enabled rather than retaining a previous configuration.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `highlighterConfig` | `boolean \| Partial<HighlighterConfig>` | Off in the shared instance; `true` on Angular's canvas | Enables the extra outline layer. |
| `showHover`, `showSelection`, `showValidation`, `showConnectTargets` | `boolean` | Each `true` when the layer is enabled | Selects which outline kinds appear. |
| `hoverPadding`, `selectionPadding`, `validationPadding` | `number` | `2`, `4`, `6` | Adds padding in world coordinates. |
| `highlightConnected` | `boolean \| HighlightConnectedOptions` | Off | Highlights lines connected to selected nodes. |
| `depth` | `number` | `1` | Follows incoming and outgoing paths by this many hops; `Infinity` traces the whole path. |
| `stroke` | `string` | Theme's primary text colour | Colours highlighted lines. |
| `strokeWidth` | `number` | `2.5` | Sets highlighted-line width. |
| `outgoing` | `'solid' \| 'dashed'` | `'solid'` | Adds an outgoing direction cue. |
| `dimOpacity` | `number` | `0.4` | Fades unrelated lines while a node is selected; `1` leaves them undimmed. |
| `style.animation.type` | `'marching-ants' \| 'flow' \| 'pulse' \| 'dash-flow' \| 'none'` | No animation without an animation setting | Chooses a shipped edge-stroke animation, or turns it off. |
| `style.animation.speed` | `'slow' \| 'normal' \| 'fast'` | `'normal'` | Changes stroke animation speed. |
| `style.animation.direction` | `'forward' \| 'reverse'` | Forward unless set to `'reverse'` | Reverses stroke animation. |

For a mounted instance, `setHighlighterConfig()` and `setHighlightConnected()` change these settings and schedule a repaint. `getHighlightConnected()` returns the current boolean or options object. To trace the whole path instead of immediate neighbours, pass `{ depth: Infinity }` through the prop or setter.

Execution status belongs to the live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel): call `setState({ status })` with `idle`, `pending`, `running`, `completed`, `error` or `warning`. `idle` adds no status class; the others retain static visual cues even when motion is disabled. Set `animateStatus: false` to keep the status but suppress its motion. Change a live wire through [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel)'s `updateStyle({ animation: { type: 'flow' } })`, then request a repaint as the samples do.

The instance's `animations` property is its shipped [`AnimationService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-services). `setEnabled(false)` disables motion globally, and `updateConfig({ reducedMotion: true })` requests static rendering. System reduced-motion preferences are detected by default. The custom token is outside that service; this sample separately hides it for the system reduced-motion preference. Wire any application-level motion switch to your own overlay too.

## Keep view effects separate from document changes

- Outlines and connected-line highlighting do not mutate the model or add undo steps. Dragging ids are a read-only observation of the active gesture, not a stored node property.
- Execution `status` and `animateStatus` are durable node state. `style.animation` is link style, and `updateStyle()` records a model change. These are **not** viewer-only effects; document read-only protection blocks those writes.
- The samples directly set a progress snapshot; they do not execute a workflow or record commands on the history stack. Your application decides when a step runs, completes, warns or fails. Use [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) for undoable editor actions, and [save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for persistence.
- Keep the rider in its sibling overlay. Its observer copies routed geometry rather than assuming a straight line, and its teardown disconnects the observer when the view unmounts. The framework binding owns disposal of its diagram; the JavaScript host disposes its instance explicitly.

## Live demos and related tasks

- [Highlight connected lines](https://grafloria.com/demos/edges/highlight-connected.html): immediate neighbours, full-path tracing and lines lifted over crossing cards.
- [Animating edges](https://grafloria.com/demos/edges/animating-edges.html): all four stroke styles plus circles, packages and trains of tokens. [View its source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/edges/animating-edges.html).
- [Execute flow](https://grafloria.com/demos/interaction/execute-flow.html): application-driven status changes, failures, warnings and stepping.
- [Turbo flow](https://grafloria.com/demos/styling/turbo-flow.html): animated borders and glowing gradient edges.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) for appearance; [route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) for geometry.

<!-- source: build-a-workflow-editor.md -->

# Build a workflow editor

Use this pattern when your application needs to edit a branching graph and test which steps a condition reaches. You get a Trigger → Condition workflow with Yes and No branches, an inspector for the condition's threshold, an insertion button, and a test log computed from the mounted diagram's live links. The test is a local simulation; it does not deploy anything or send messages.

Grafloria owns the graph and its interactions. Your application owns the condition, the inspector and the execution policy, as in the [computing flows demo](https://grafloria.com/demos/interaction/computing-flows.html).

## 1. Define the steps and their ports

Put the shared code in `workflow.ts`. Describe the initial drawing with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec). Each condition output has its own port ID: the test chooses a port, not a destination's position on the canvas.

[`PortSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-portspec) carries direction, data type and connection gates. These ports carry numbers. Explicit start/end gates prevent an input from starting a wire or an output from accepting one.

```ts title="workflow.ts"
import type {
  NodeSpec, EdgeSpec, PortSpec, NodeInput, EdgeInput,
} from '@grafloria/renderer';
import type { DiagramModel } from '@grafloria/engine';

let nextId = 0;
function newId(): string {
  return `workflow-edit-${++nextId}`;
}

export function port(id: string, type: 'input' | 'output', index = 0): PortSpec {
  return {
    id, type, index, side: type === 'input' ? 'left' : 'right',
    dataType: 'number',
    gating: {
      isConnectableStart: type === 'output',
      isConnectableEnd: type === 'input',
      allowSelfLink: false,
      allowDuplicateLinks: false,
    },
  };
}

export const nodes: NodeSpec[] = [
  { id: 'trigger', label: 'Trigger', position: { x: 40, y: 150 },
    size: { width: 120, height: 60 }, ports: [port('trigger.out', 'output')] },
  { id: 'condition', label: 'Value ≥ threshold', position: { x: 230, y: 150 },
    size: { width: 160, height: 80 }, data: { threshold: 10 },
    ports: [port('condition.in', 'input'), port('condition.yes', 'output'),
      port('condition.no', 'output', 1)] },
  { id: 'yes', label: 'Approve', position: { x: 610, y: 60 },
    size: { width: 120, height: 60 }, ports: [port('yes.in', 'input')] },
  { id: 'no', label: 'Review', position: { x: 610, y: 260 },
    size: { width: 120, height: 60 }, ports: [port('no.in', 'input')] },
];

export const edges: EdgeSpec[] = [
  { id: 'start', source: 'trigger', target: 'condition',
    sourceHandle: 'trigger.out', targetHandle: 'condition.in' },
  { id: 'yes-edge', source: 'condition', target: 'yes', label: 'Yes',
    sourceHandle: 'condition.yes', targetHandle: 'yes.in' },
  { id: 'no-edge', source: 'condition', target: 'no', label: 'No',
    sourceHandle: 'condition.no', targetHandle: 'no.in' },
];

export class WorkflowEditor {
  constructor(
    private readonly model: DiagramModel,
    private readonly apply: (nodes: NodeInput[], edges: EdgeInput[]) => void,
  ) {}

  inspect(id: string): string {
    const node = this.model.getNode(id);
    if (!node) return 'Select a step';
    return `${node.getLabel() ?? id}: ${node.getIncomingLinks().length} incoming, `
      + `${node.getOutgoingLinks().length} outgoing`;
  }

  threshold(): number {
    return Number(this.model.getNode('condition')?.data.threshold ?? 10);
  }

  setThreshold(value: number): void {
    if (!Number.isFinite(value)) return;
    const next: NodeInput[] = this.model.getNodes().map(node =>
      node.id === 'condition'
        ? { id: node.id, data: { threshold: value } }
        : node,
    );
    this.apply(next, this.model.getLinks());
  }

  insert(): void {
    const condition = this.model.getNode('condition');
    const old = condition?.getOutgoingLinks().find(link =>
      link.sourcePortId === 'condition.yes');
    if (!old?.targetNodeId) return;

    const id = newId();
    const step: NodeSpec = {
      id, label: 'Audit', position: { x: 430, y: 60 },
      size: { width: 120, height: 60 },
      ports: [port(`${id}.in`, 'input'), port(`${id}.out`, 'output')],
    };
    const nextEdges: EdgeInput[] = [
      ...this.model.getLinks().filter(link => link.id !== old.id),
      { id: newId(), source: 'condition', target: id, label: 'Yes',
        sourceHandle: 'condition.yes', targetHandle: `${id}.in` },
      { id: newId(), source: id, target: old.targetNodeId,
        sourceHandle: `${id}.out`, targetHandle: old.targetPortId },
    ];
    this.apply([...this.model.getNodes(), step], nextEdges);
  }

  test(value: number): string {
    if (!Number.isFinite(value)) return 'Enter a finite number';
    const queue = ['trigger'];
    const visited = new Set<string>();
    const log: string[] = [];
    while (queue.length) {
      const id = queue.shift();
      if (!id || visited.has(id)) continue;
      visited.add(id);
      const node = this.model.getNode(id);
      if (!node) continue;
      log.push(`${node.getLabel() ?? id}: completed`);
      const chosen = value >= this.threshold() ? 'condition.yes' : 'condition.no';
      for (const link of node.getOutgoingLinks()) {
        if (id === 'condition' && link.sourcePortId !== chosen) continue;
        if (link.targetNodeId) queue.push(link.targetNodeId);
      }
    }
    return log.join('\n');
  }
}
```

The inspector reads [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel) incoming and outgoing links from the owning [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel). Insertion replaces the first Yes link with two links through an Audit step. Existing live models pass through unchanged via [`NodeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#nodeinput) and [`EdgeInput`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#edgeinput); only the new step and links need specs.

## 2. Mount the editor in your framework

Install the line for your framework in your own project:

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

Connect `WorkflowEditor` to the mounted graph so the inspector, insertion button and test log share its live topology; see [edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for framework mounting and instance access.

Use the shipped [`LIGHT_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants). The canvas shows the four steps and two labelled branches. The adjacent inspector starts with the condition selected in application state; click a step to inspect its live connections.

Save the matching component beside `workflow.ts`. The JavaScript tab exports a mount function: call it with your application's host element, and call its returned cleanup function when that view unmounts.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { LIGHT_THEME } from '@grafloria/renderer';
import { nodes, edges, WorkflowEditor } from './workflow';

export function mountWorkflow(host: HTMLElement): () => void {
  host.innerHTML = `
    <div data-canvas style="height:400px"></div>
    <aside>
      <p data-inspector></p>
      <label>Threshold <input data-threshold type="number" value="10"></label>
      <button data-insert>Insert Audit on Yes</button>
      <label>Test value <input data-value type="number" value="12"></label>
      <button data-test>Test workflow</button>
      <pre data-log>Not run</pre>
    </aside>`;
  const canvas = host.querySelector<HTMLElement>('[data-canvas]')!;
  const inspector = host.querySelector<HTMLElement>('[data-inspector]')!;
  const threshold = host.querySelector<HTMLInputElement>('[data-threshold]')!;
  const value = host.querySelector<HTMLInputElement>('[data-value]')!;
  const log = host.querySelector<HTMLElement>('[data-log]')!;
  const instance = render({ nodes, edges }, canvas, { theme: LIGHT_THEME });
  const editor = new WorkflowEditor(instance.getModel(), (nextNodes, nextEdges) => {
    instance.setNodes(nextNodes);
    instance.setEdges(nextEdges);
    instance.renderNow();
  });
  inspector.textContent = editor.inspect('condition');
  const off = instance.on('selection:change', change => {
    inspector.textContent = editor.inspect(change.nodes[0]?.id ?? '');
  });
  threshold.onchange = () => editor.setThreshold(threshold.valueAsNumber);
  host.querySelector<HTMLButtonElement>('[data-insert]')!.onclick = () => editor.insert();
  host.querySelector<HTMLButtonElement>('[data-test]')!.onclick = () => {
    log.textContent = editor.test(value.valueAsNumber);
  };
  return () => { off(); instance.dispose(); host.replaceChildren(); };
}
```
```ts title="Angular"
import { AfterViewInit, Component, signal, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { LIGHT_THEME, type NodeInput, type EdgeInput } from '@grafloria/renderer';
import { nodes, edges, WorkflowEditor } from './workflow';

@Component({
  selector: 'app-workflow', standalone: true, imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      [theme]="theme" style="display:block;height:400px"
      (selectionChange)="inspect($event.nodes.length ? $event.nodes[0].id : '')" />
    <aside>
      <p>{{ description() }}</p>
      <label>Threshold <input #threshold type="number" value="10"
        (change)="editor?.setThreshold(threshold.valueAsNumber)"></label>
      <button (click)="editor?.insert()">Insert Audit on Yes</button>
      <label>Test value <input #value type="number" value="12"></label>
      <button (click)="test(value.valueAsNumber)">Test workflow</button>
      <pre>{{ log() }}</pre>
    </aside>`,
})
export class WorkflowComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeInput[] = [...nodes];
  edges: EdgeInput[] = [...edges];
  readonly theme = LIGHT_THEME;
  readonly description = signal('Select a step');
  readonly log = signal('Not run');
  editor?: WorkflowEditor;

  ngAfterViewInit(): void {
    const canvas = this.canvas();
    const model = canvas.activeEngine()?.getDiagram();
    if (!model) return;
    this.editor = new WorkflowEditor(model, (nextNodes, nextEdges) => {
      this.nodes = nextNodes;
      this.edges = nextEdges;
    });
    this.inspect('condition');
  }
  inspect(id: string): void {
    this.description.set(this.editor?.inspect(id) ?? 'Select a step');
  }
  test(value: number): void {
    this.log.set(this.editor?.test(value) ?? 'Canvas not ready');
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { LIGHT_THEME } from '@grafloria/renderer';
import { nodes, edges, WorkflowEditor } from './workflow';

export default component$(() => {
  const editor = useSignal<NoSerialize<WorkflowEditor>>();
  const description = useSignal('Select a step');
  const value = useSignal(12);
  const log = useSignal('Not run');
  return <section>
    <div style={{ height: '400px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} theme={LIGHT_THEME}
        onInit$={instance => {
          editor.value = noSerialize(new WorkflowEditor(instance.getModel(), (ns, es) => {
            instance.setNodes(ns); instance.setEdges(es); instance.renderNow();
          }));
          description.value = editor.value?.inspect('condition') ?? 'Select a step';
        }}
        onSelectionChange$={change => {
          description.value = editor.value?.inspect(change.nodes[0]?.id ?? '') ?? 'Select a step';
        }} />
    </div>
    <aside>
      <p>{description.value}</p>
      <label>Threshold <input type="number" value={10}
        onChange$={(_, input) => editor.value?.setThreshold(input.valueAsNumber)} /></label>
      <button onClick$={() => editor.value?.insert()}>Insert Audit on Yes</button>
      <label>Test value <input type="number" value={value.value}
        onInput$={(_, input) => { value.value = input.valueAsNumber; }} /></label>
      <button onClick$={() => { log.value = editor.value?.test(value.value) ?? 'Canvas not ready'; }}>
        Test workflow
      </button>
      <pre>{log.value}</pre>
    </aside>
  </section>;
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import { LIGHT_THEME } from '@grafloria/renderer';
import { nodes, edges, WorkflowEditor } from './workflow';

export default function Workflow() {
  const editor = useRef<WorkflowEditor | null>(null);
  const [description, setDescription] = useState('Select a step');
  const [value, setValue] = useState(12);
  const [log, setLog] = useState('Not run');
  return <section>
    <div style={{ height: 400 }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} theme={LIGHT_THEME}
        onInit={instance => {
          editor.current = new WorkflowEditor(instance.getModel(), (ns, es) => {
            instance.setNodes(ns); instance.setEdges(es);
          });
          setDescription(editor.current.inspect('condition'));
        }}
        onSelectionChange={change => {
          setDescription(editor.current?.inspect(change.nodes[0]?.id ?? '') ?? 'Select a step');
        }} />
    </div>
    <aside>
      <p>{description}</p>
      <label>Threshold <input type="number" defaultValue={10}
        onChange={event => editor.current?.setThreshold(event.currentTarget.valueAsNumber)} /></label>
      <button onClick={() => editor.current?.insert()}>Insert Audit on Yes</button>
      <label>Test value <input type="number" value={value}
        onChange={event => setValue(event.currentTarget.valueAsNumber)} /></label>
      <button onClick={() => setLog(editor.current?.test(value) ?? 'Canvas not ready')}>
        Test workflow
      </button>
      <pre>{log}</pre>
    </aside>
  </section>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import { LIGHT_THEME, type DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, WorkflowEditor } from './workflow';

const editor = shallowRef<WorkflowEditor>();
const description = ref('Select a step');
const value = ref(12);
const threshold = ref(10);
const log = ref('Not run');
function init(instance: DiagramInstance): void {
  editor.value = new WorkflowEditor(instance.getModel(), (ns, es) => {
    instance.setNodes(ns); instance.setEdges(es); instance.renderNow();
  });
  inspect('condition');
}
function inspect(id: string): void {
  description.value = editor.value?.inspect(id) ?? 'Select a step';
}
</script>

<template>
  <section>
    <div style="height:400px">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :theme="LIGHT_THEME"
        @init="init" @selection-change="inspect($event.nodes[0]?.id ?? '')" />
    </div>
    <aside>
      <p>{{ description }}</p>
      <label>Threshold <input v-model.number="threshold" type="number"
        @change="editor?.setThreshold(Number(threshold))"></label>
      <button @click="editor?.insert()">Insert Audit on Yes</button>
      <label>Test value <input v-model.number="value" type="number"></label>
      <button @click="log = editor?.test(Number(value)) ?? 'Canvas not ready'">Test workflow</button>
      <pre>{{ log }}</pre>
    </aside>
  </section>
</template>
```
:::

The Angular sample starts with the condition's connection counts beneath the branching canvas.

![Angular: Trigger feeds the condition, with Yes leading to Approve and No to Review; threshold, insertion and test controls sit below.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e30aabc6325126d10838438a78d2f041.png)

The React sample displays the same graph and an initial Not run log.

The Vue sample also starts with threshold 10 and test value 12.

The Qwik sample shows the initial graph before a test runs.

The framework components own canvas teardown. The Qwik controller is created in the browser initialization callback and kept with `noSerialize()` because it holds a live model and a function, not resumable data.

## 3. Insert, inspect and test a branch

Click **Insert Audit on Yes**. The Yes path now passes through Audit before reaching Approve; the No path still reaches Review. Click Audit to see its one incoming and one outgoing link in the inspector.

Set **Threshold** to change the condition's model data. Press **Test workflow** with a value above or equal to that threshold to list the Yes path; use a smaller value to list the No path. After insertion, the Yes log includes Audit. The returned string lists completed steps in traversal order, and each framework displays it in its `pre` element.

The test reads `getOutgoingLinks()` afresh for every node. It follows each [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel)'s `sourcePortId` and `targetNodeId`, so rewiring changes the next test without rebuilding a private adjacency list. The visited set bounds the simulation when the graph contains a cycle. This is a reachability simulation, not a dependency scheduler: it does not wait for all inputs at a merge or execute remote actions.

For computed downstream values instead of a completion log, use `getIncomingLinks()` to read upstream values, apply your node's operation, and publish the result. The [computing flows demo](https://grafloria.com/demos/interaction/computing-flows.html) demonstrates that policy; Grafloria supplies topology, not your arithmetic.

## Connection options that matter

Set these on authored ports. [`PortModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-portmodel) holds their live values after mounting.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `PortSpec.dataType` | `string` | Unset | Declares the carried type for connection validity and glyph colour. |
| `PortSpec.gating.isConnectableStart` | `boolean` | `true` | Allows or refuses a link starting here. |
| `PortSpec.gating.isConnectableEnd` | `boolean` | `true` | Allows or refuses a link ending here. |
| `PortSpec.gating.fromMaxLinks` | `number \| null` | Unlimited | Caps outgoing links. |
| `PortSpec.gating.toMaxLinks` | `number \| null` | Unlimited | Caps incoming links. |
| `PortSpec.gating.allowSelfLink` | `boolean` | `false` | Allows links back to the same node. |
| `PortSpec.gating.allowDuplicateLinks` | `boolean` | `true` | Allows another link between the same ports. |

## Editing boundaries and next steps

This example reconciles insertion and threshold changes through the binding's data surface. For undoable application edits on the same history as canvas gestures, use the command pattern in [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

Repeated insertions use the same Audit position to keep this example focused on topology. Add [explicit layout](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) to arrange a larger workflow after insertion. Save the live document using [save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents), rather than treating the initial specs as the edited workflow.

Try the [workflow automation builder](https://grafloria.com/demos/interaction/workflow-builder.html) for output-mounted + buttons, action-specific inspectors and animated execution. Its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/interaction/workflow-builder.html) shows a larger application built around the same model-owned steps and port-selected branches.

<!-- source: edit-database-models.md -->

# Edit database models

Use the ER kit for a visual schema editor: render table cards with typed columns and column-level relationships, enable inline edits, cap a long card so its body scrolls, and highlight candidate joins while the reader drags a connection.

[`erDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#erdiagram) turns entities and relationships into ordinary specs plus a wiring step. Mount the complete kit spec, rather than passing its nodes and edges separately, so the host also installs row selection and editing.

## 1. Declare the schema

Install the packages for your framework in your own project.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

Create this shared file beside the framework entry below. The data is typed with [`ErDiagramOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#erdiagramoptions). `CUSTOMERS.id` and `ORDERS.customer_id` attach the relationship to columns, not table centers. The one-to-many markers run from the customer primary key to the order foreign key.

```ts title="schema.ts"
import type { ErDiagramOptions } from '@grafloria/element';

export function schema(): ErDiagramOptions {
  return {
    editable: true,
    entities: [
      {
        id: 'CUSTOMERS', name: 'Customers',
        position: { x: 50, y: 60 }, width: 260, height: 155,
        columns: [
          { name: 'id', type: 'int', pk: true },
          { name: 'name', type: 'varchar' },
          { name: 'email', type: 'varchar' },
          { name: 'country', type: 'varchar' },
          { name: 'city', type: 'varchar' },
          { name: 'postal_code', type: 'varchar' },
        ],
      },
      {
        id: 'ORDERS', name: 'Orders',
        position: { x: 410, y: 100 }, width: 280,
        columns: [
          { name: 'id', type: 'int', pk: true },
          { name: 'status', type: 'varchar' },
          { name: 'customer_id', type: 'int', fk: true },
          { name: 'total', type: 'decimal' },
        ],
      },
    ],
    relationships: [
      {
        id: 'customer-orders',
        from: 'CUSTOMERS.id', to: 'ORDERS.customer_id',
        cardinality: 'one-to-many', label: 'places',
      },
    ],
  };
}
```

The Customers card has more columns than its fixed height can display. Scroll inside its column list; the header and “＋ add column” affordance stay outside the scrolling body. Orders uses automatic height.

## 2. Mount an editable diagram

[`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) returns a live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). Framework kit hosts hand you that same instance through their ready callback or event.

These entries render the same two cards and the `places` relationship. They also add a toolbar button that uses [`erTable`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#ertable) to rename Orders to Sales orders. The returned [`ErTable`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-classes#ertable) reads the live entity; its `spec` getter returns a deep copy, not an editable reference. `rename()` and `resize()` return `Promise<boolean>` and route their edits through the history stack.

### JavaScript

Mount in a browser. Call the returned cleanup function when your application removes this view.

:::code-group
```ts title="JavaScript"
import { render, erDiagram, erTable } from '@grafloria/element';
import { schema } from './schema';

export function mountDatabaseEditor(parent: HTMLElement): () => void {
  const button = document.createElement('button');
  button.textContent = 'Rename Orders';
  const host = document.createElement('div');
  host.style.height = '400px';
  parent.append(button, host);
  const api = render(erDiagram(schema()), host);
  api.fitView(40);
  button.onclick = () => { void erTable(api, 'ORDERS').rename('Sales orders'); };
  return () => {
    api.dispose();
    button.remove();
    host.remove();
  };
}

const parent = document.getElementById('app')!;
export const unmountDatabaseEditor = mountDatabaseEditor(parent);
```
```html title="index.html"
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>
```
:::

![JavaScript: Customers and Orders cards, the places relationship and the Rename Orders button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/8637dabae8821610d969002a2d11d328.png)

### Framework hosts

Use [`GrafloriaDiagramComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#grafloriadiagramcomponent) in Angular. In Qwik, use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadiagram) with `spec$` to build the function-bearing kit spec in the browser. React's [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadiagram) accepts `spec` and `onReady`; Vue's [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadiagram) accepts `:spec` and emits `ready`.

:::code-group
```ts title="Angular"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { erDiagram, erTable } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { schema } from './schema';

@Component({
  standalone: true,
  selector: 'app-database-editor',
  imports: [GrafloriaDiagramComponent],
  template: `
    <button (click)="rename()">Rename Orders</button>
    <grafloria-diagram [spec]="spec" (ready)="ready($event)"
      style="display:block; height:400px" />
  `,
})
export class DatabaseEditorComponent {
  readonly spec = erDiagram(schema());
  private instance?: DiagramInstance;
  ready(api: DiagramInstance): void {
    this.instance = api;
    api.fitView(40);
  }
  rename(): void {
    if (this.instance) void erTable(this.instance, 'ORDERS').rename('Sales orders');
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import { erDiagram, erTable } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { schema } from './schema';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  return (
    <>
      <button onClick$={() => {
        if (instance.value) void erTable(instance.value, 'ORDERS').rename('Sales orders');
      }}>Rename Orders</button>
      <div style={{ height: '400px' }}>
        <GrafloriaDiagram
          spec$={() => erDiagram(schema())}
          onReady$={(api: DiagramInstance) => {
            instance.value = noSerialize(api);
            api.fitView(40);
          }}
        />
      </div>
    </>
  );
});
```
```tsx title="React"
import { useRef } from 'react';
import { GrafloriaDiagram } from '@grafloria/react';
import { erDiagram, erTable } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { schema } from './schema';

const spec = erDiagram(schema());

export default function DatabaseEditor() {
  const instance = useRef<DiagramInstance | null>(null);
  return (
    <>
      <button onClick={() => {
        if (instance.current) void erTable(instance.current, 'ORDERS').rename('Sales orders');
      }}>Rename Orders</button>
      <div style={{ height: '400px' }}>
        <GrafloriaDiagram spec={spec} onReady={(api) => {
          instance.current = api;
          api.fitView(40);
        }} />
      </div>
    </>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaDiagram } from '@grafloria/vue';
import { erDiagram, erTable } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { schema } from './schema';

const spec = erDiagram(schema());
const instance = shallowRef<DiagramInstance>();
function ready(api: DiagramInstance): void {
  instance.value = api;
  api.fitView(40);
}
function rename(): void {
  if (instance.value) void erTable(instance.value, 'ORDERS').rename('Sales orders');
}
</script>

<template>
  <button @click="rename">Rename Orders</button>
  <div style="height:400px">
    <GrafloriaDiagram :spec="spec" @ready="ready" />
  </div>
</template>
```
:::

The framework hosts dispose their instance on unmount. Keep user-facing edits on the live handle instead of replacing the kit spec; changed spec values replace the mounted diagram.

## 3. Edit and scroll the cards

With `editable: true`, use the kit's own controls:

- Double-click a header or column name to open the inline editor. Enter commits; Escape cancels.
- Click “＋ add column” to insert a column and open its name editor.
- Hover a column and click × to delete it. Deleting an attached column also removes its field port and relationship.
- Click a column once to select the row. The container emits `axk:row-select`; use that DOM event for a properties panel, not a framework event the kit host does not declare.

Each edit becomes one undoable step. Surviving field ports move to their columns' new row positions when columns are inserted, removed or reordered. For example, deleting Orders.status moves the `customer_id` relationship up with that row. See [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) for a history toolbar.

To resize a card from your own toolbar, call `erTable(instance, 'CUSTOMERS').resize({ height: 180 })`. A fixed height caps the column body; omitting the initial entity height uses automatic sizing. Use the handle rather than mutating its copied `spec`.

## Guide candidate joins

[`bindJoinGuidance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#bindjoinguidance) listens to the mounted instance's connection lifecycle. Bind it in `onReady`, `ready`, or `onReady$`, or after JavaScript's `render()` call. Keep its returned handle and call `dispose()` when that view unmounts.

The ER kit's field ports are hidden relationship attachment points, not visible query-builder grips. A query editor needs visible per-column connection ports; the [visual SQL demo](https://grafloria.com/demos/diagrams/query-builder.html) shows ports on both sides of each column and binds the shipped guidance function. Its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/diagrams/query-builder.html) also implements the SQL pane and join-type inspector.

During a column connection drag, guidance leaves the source table unchanged and tints other tables' rows:

| Tier | What the reader sees | Matching rule |
| --- | --- | --- |
| `top` | Gold row and “★ BEST” chip | The first highest-scoring candidate, if its score is at least 2 |
| `good` | Green row | Other PK/FK flag matches or stronger naming matches |
| `ok` | Blue row | Equal column names, or both names ending in `id` |
| `none` | Dimmed row | No matching reason |

The strongest naming match is a singular table-name foreign key such as `ORDERS.customer_id` against `CUSTOMERS.id`, or equal `_id` names with an FK flag. Guidance clears its tints and chip when the drag completes or cancels. It ranks candidates; it does not infer SQL or enforce your database's join rules.

> **Known issue:** After a column rename, ER field ports keep their old ids, but the default guidance resolver matches ids against current column names. Until this is fixed, supply `resolvePort` that resolves a port's row position against the live columns.

The intended call is `bindJoinGuidance(instance)`. This complete browser helper supplies the resolver for renamed kit field ports and returns an unbind function. Call it from the host's ready handler when adding join guidance to a view with connection grips.

```ts title="join-guidance.ts"
import { bindJoinGuidance, erRowCenterY, erTable } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';

export function attachJoinGuidance(instance: DiagramInstance): () => void {
  const guidance = bindJoinGuidance(instance, {
    resolvePort(portId, nodeId) {
      const node = nodeId
        ? instance.getModel().getNode(nodeId)
        : instance.getModel().getNodeByPortId(portId);
      if (!node || !node.getMetadata('kitEntity')) return null;
      const port = node.getPort(portId);
      const y = port?.layout?.args?.y;
      if (port?.layout?.strategy !== 'absolute' || typeof y !== 'number') return null;
      const columns = erTable(instance, node.id).spec.columns;
      const index = columns.findIndex((_, i) => erRowCenterY(i) === y);
      const column = columns[index];
      return column ? { nodeId: node.id, column: column.name } : null;
    },
  });
  return () => guidance.dispose();
}
```

[`erRowCenterY`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#errowcentery) supplies the kit's row-center coordinate. This resolver uses the updated row position instead of the preserved port id.

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `editable` | `boolean` | `false` | Adds inline rename, add and delete controls |
| `rowSelection` | `boolean` | Enabled | Adds row selection and container CustomEvents; `false` opts out |
| Entity `height` | `number` | Computed from columns and editing chrome | Caps the card and enables body scrolling |
| Relationship `cardinality` | Named cardinality or `{ tail: string; head: string }` | `one-to-many` | Chooses endpoint markers |
| Relationship `fromSide` / `toSide` | `left`, `right`, `top`, `bottom` | `right` / `left` | Chooses relationship attachment sides |
| Guidance `chipText` | `string` | `★ BEST` | Changes the best candidate's chip text |

Named cardinalities are `one-to-many`, `one-to-one`, `many-to-many`, `one-to-zero-or-many` and `one-to-one-or-many`.

## Pitfalls and next steps

- Spell entity ids and column endpoints exactly. `erDiagram()` throws for an unknown entity or column while building the spec.
- Pass a known kit-node id to `erTable()`; it throws for a missing node or a non-ER node.
- For Qwik kit construction and resumable state, see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits).
- Save the live document rather than reconstructing it from framework specs: [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

Try the [in-canvas ERD editor](https://grafloria.com/demos/diagrams/erd-editor.html) for rename/add/delete, or the [advanced ER demo](https://grafloria.com/demos/diagrams/er-advanced.html) for shared PK endpoints, self-references and junction tables.

<!-- source: edit-uml-classes.md -->

# Edit UML classes

Use the UML kit when your data describes classes, members and relationships. Build the diagram with [`umlDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#umldiagram), then edit its mounted classes with [`umlClass`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#umlclass). You get class cards with name, attribute and method compartments, all seven relationship notations, and a scrolling body for a capped card.

## 1. Declare the classes and relationships

Put this shared file beside the framework sample you choose below. [`UmlDiagramOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#umldiagramoptions) types the data; member signatures are strings, including their visibility prefixes. The kit returns nodes, edges and a wiring step rather than a separate UML model.

The sample places seven pairs of cards in four rows. `Shape` has enough members to demonstrate scrolling after the ready callback caps its height.

```ts title="uml-example.ts"
import { umlDiagram, umlClass, type UmlDiagramOptions } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';

const data: UmlDiagramOptions = {
  editable: true,
  classes: [
    { id: 'Shape', position: { x: 40, y: 40 }, width: 220,
      attributes: ['# x: float', '# y: float', '# width: float', '# height: float',
        '# rotation: float', '# visible: bool'],
      methods: ['+ area(): float', '+ draw(): void', '+ bounds(): Rect'] },
    { id: 'Circle', position: { x: 350, y: 40 }, width: 220,
      attributes: ['+ radius: float'], methods: ['+ area(): float'] },
    { id: 'Drawable', stereotype: 'interface', position: { x: 670, y: 40 }, width: 220,
      methods: ['+ render(): void'] },
    { id: 'Button', position: { x: 980, y: 40 }, width: 220,
      attributes: ['+ label: String'], methods: ['+ render(): void'] },
    { id: 'Playlist', position: { x: 40, y: 300 }, width: 220,
      attributes: ['+ name: String'], methods: ['+ add(s): void'] },
    { id: 'Song', position: { x: 350, y: 300 }, width: 220,
      attributes: ['+ title: String'], methods: ['+ play(): void'] },
    { id: 'Window', position: { x: 670, y: 300 }, width: 220,
      attributes: ['+ title: String'], methods: ['+ close(): void'] },
    { id: 'TitleBar', position: { x: 980, y: 300 }, width: 220,
      attributes: ['+ text: String'], methods: ['+ paint(): void'] },
    { id: 'Student', position: { x: 40, y: 560 }, width: 220,
      attributes: ['+ name: String'], methods: ['+ enroll(): void'] },
    { id: 'Course', position: { x: 350, y: 560 }, width: 220,
      attributes: ['+ code: String'], methods: ['+ start(): void'] },
    { id: 'Order', position: { x: 670, y: 560 }, width: 220,
      attributes: ['+ id: int'], methods: ['+ total(): Money'] },
    { id: 'Product', position: { x: 980, y: 560 }, width: 220,
      attributes: ['+ sku: String'], methods: ['+ price(): Money'] },
    { id: 'OrderService', position: { x: 40, y: 820 }, width: 220,
      methods: ['+ checkout(o): void'] },
    { id: 'Logger', position: { x: 350, y: 820 }, width: 220,
      methods: ['+ log(msg): void'] },
  ],
  relationships: [
    { from: 'Circle', to: 'Shape', kind: 'inheritance',
      fromSide: 'left', toSide: 'right' },
    { from: 'Button', to: 'Drawable', kind: 'realization',
      fromSide: 'left', toSide: 'right' },
    { from: 'Playlist', to: 'Song', kind: 'aggregation',
      fromSide: 'right', toSide: 'left' },
    { from: 'Window', to: 'TitleBar', kind: 'composition',
      fromSide: 'right', toSide: 'left' },
    { from: 'Student', to: 'Course', kind: 'association',
      multiplicity: ['0..*', '1..*'], fromSide: 'right', toSide: 'left' },
    { from: 'Order', to: 'Product', kind: 'directed-association',
      multiplicity: ['1', '0..*'], fromSide: 'right', toSide: 'left' },
    { from: 'OrderService', to: 'Logger', kind: 'dependency', label: '«uses»',
      fromSide: 'right', toSide: 'left' },
  ],
};

export function buildUmlExample() {
  return umlDiagram(data);
}

export async function editShape(api: DiagramInstance): Promise<void> {
  const shape = umlClass(api, 'Shape');
  await shape.rename('AbstractShape');
  await shape.setAbstract(true);
  await shape.attributes.renameAt(0, '# left: float');
  await shape.methods.add('+ move(): void');
  await shape.resize({ height: 170 });
  api.fitView(40);
}
```

### Read the relationship notation

Each [`UmlRelationshipSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#umlrelationshipspec) names class ids in `from` and `to`. Set the whole at `from` for aggregation and composition; set the parent or interface at `to` for inheritance and realization. The kit supplies orthogonal routing and markers—you do not need to configure arrow shapes yourself.

| `kind` | Line | Marker |
| --- | --- | --- |
| `inheritance` | Solid | Hollow triangle at `to` (generalization) |
| `realization` | Dashed | Hollow triangle at `to` |
| `association` | Solid | No arrowheads |
| `directed-association` | Solid | Open arrow at `to` |
| `aggregation` | Solid | Hollow diamond at `from` |
| `composition` | Solid | Filled diamond at `from` |
| `dependency` | Dashed | Open arrow at `to` |

`multiplicity` supplies the chips at the `[from, to]` ends. `fromSide` and `toSide` pin the attachment sides; the sample uses facing sides for each horizontal pair.

## 2. Mount the kit in your framework

Choose one installation command and one host sample. These samples use the same shared data and run `editShape()` only after the diagram mounts. The ready callback receives a live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance).

### JavaScript / TypeScript

[`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) mounts the kit and returns the instance. It runs the kit's wiring step automatically, including multiplicity labels; do not add them yourself.

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

```html title="index.html"
<div id="uml" style="height: 720px"></div>
<script type="module" src="/src/main.ts"></script>
```

Place `uml-example.ts` in `src` with this file. Keep the returned cleanup function for the close or unmount hook of the view that owns the diagram.

```ts title="src/main.ts"
import { render } from '@grafloria/element';
import { buildUmlExample, editShape } from './uml-example';

export function mountUml(container: HTMLElement): () => void {
  container.style.height = '720px';
  const api = render(buildUmlExample(), container);
  void editShape(api);
  return () => api.dispose();
}

const container = document.getElementById('uml');
if (!container) throw new Error('Missing #uml container');
export const unmountUml = mountUml(container);
```

### React

Pass the kit to [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadiagram) and edit through `onReady`. The component owns disposal on unmount.

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

```tsx title="App.tsx"
import { GrafloriaDiagram } from '@grafloria/react';
import { buildUmlExample, editShape } from './uml-example';

const spec = buildUmlExample();

export default function App() {
  return (
    <div style={{ height: '720px' }}>
      <GrafloriaDiagram spec={spec} onReady={editShape} />
    </div>
  );
}
```

![Four rows contain seven UML card pairs with the italic AbstractShape title, triangles, diamonds, multiplicity labels and member-add controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/21a19a42fe24285613092b5d4f8d3564.png)

### Vue

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadiagram)'s `ready` event to run `editShape()` on the mounted UML classes; see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits#vue) for the shared kit-host setup and lifecycle.

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

```vue title="App.vue"
<script setup lang="ts">
import { GrafloriaDiagram } from '@grafloria/vue';
import { buildUmlExample, editShape } from './uml-example';

const spec = buildUmlExample();
</script>

<template>
  <GrafloriaDiagram :spec="spec" @ready="editShape" style="height: 720px" />
</template>
```

### Angular

Import [`GrafloriaDiagramComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#grafloriadiagramcomponent) into your standalone component. Its `ready` output supplies the instance; the host disposes it on destruction.

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

```ts title="app.component.ts"
import { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import { buildUmlExample, editShape } from './uml-example';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: `
    <grafloria-diagram [spec]="spec" (ready)="editShape($event)"
      style="display: block; height: 720px" />
  `,
})
export class AppComponent {
  readonly spec = buildUmlExample();
  readonly editShape = editShape;
}
```

### Qwik

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadiagram) with `spec$` to build the function-bearing kit spec in the browser, then edit through `onReady$`. No live instance enters resumable state in this sample. The component owns disposal on unmount. See [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for resumable kit state.

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

```tsx title="uml-view.tsx"
import { component$ } from '@builder.io/qwik';
import { GrafloriaDiagram } from '@grafloria/qwik';
import { buildUmlExample, editShape } from './uml-example';

export default component$(() => (
  <div style={{ height: '720px' }}>
    <GrafloriaDiagram
      spec$={() => buildUmlExample()}
      onReady$={(api) => { void editShape(api); }}
    />
  </div>
));
```

## 3. Read and edit the live class

After the ready callback completes, `Shape` displays the italic title `AbstractShape`. Its first attribute reads `# left: float`, and its methods include `+ move(): void`. The 170-pixel card keeps its name compartment outside a scrolling body: scroll inside the card to reach its lower members. The other pairs show triangles, diamonds, plain and directed associations, multiplicity chips and a dashed dependency.

`umlClass(api, 'Shape')` returns a typed [`UmlClass`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-classes#umlclass) handle. The id remains `Shape` after a rename. Getters read the live class; `spec` returns a deep copy, so changing that copy does not edit the diagram.

- Read members with `attributes.list()` or `methods.list()`, read their count with `length`, and read one with `at(index)`.
- Append with `add(member)`, or insert with `add(member, { at: index })`.
- Replace a member string with `renameAt(index, member)` and delete one with `removeAt(index)`.
- Change the title with `rename()`, the italic flag with `setAbstract()`, and the displayed stereotype with `setStereotype()`.
- Cap the body with `resize({ height: 170 })`, as the shared callback does. You can also declare `height` in the initial class data.

The edit methods return `Promise<boolean>`. On this mounted instance each call enters the engine's command history and repaints the card; await one edit before deriving the next from the live members. The five calls in `editShape()` are five history steps, not one transaction. For toolbar undo and redo, see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

Because `editable: true` is set, you also get the kit's in-canvas editing: double-click a class name or member to rename it, use `＋ attribute` or `＋ method` to add a member, and use the member's `×` control to delete it. These edits use the same undoable update path. Typed-handle edits do not require this editing chrome.

## Options that matter

[`UmlClassSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#umlclassspec) controls each card's data and dimensions.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `editable` | `boolean` | `false` | Adds rename, add and delete interactions to the cards. |
| `rowSelection` | `boolean` | Enabled unless `false` | Enables selectable members. |
| Class `name` | `string` | Class `id` | Sets the displayed title without changing its id. |
| Class `stereotype` | `string` | None | Displays `«stereotype»` above the title; `abstract` and `interface` also italicize the title. |
| Class `height` | `number` | Derived from members | Fixes the card height and enables a scrolling body when content exceeds it. |
| Class `width` | `number` | Derived from content, between 200 and 420 pixels | Sets an explicit width instead of auto-sizing. |
| Relationship `kind` | Seven string literals listed above | `'association'` | Chooses the line and marker notation. |
| Relationship `multiplicity` | `[string, string]` | None | Adds chips at the `from` and `to` ends. |

## Pitfalls

- Acquire handles after mounting. `umlClass()` throws if the id is absent or the node is not a kit UML class.
- Use the handle to edit, not a modified `spec` copy. A changed kit spec passed to the React, Vue or Angular host replaces the diagram; keep the seed spec stable while editing the live instance.
- A fixed height caps the body, not the member list: members remain in the data and are reached by scrolling. Long member strings stay on one line and ellipsize when they exceed the available width; set an explicit width when you need more space.
- The kit suppresses canvas resize handles on its cards. Use class dimensions or the typed `resize()` method to size them.

## Live demos and related guides

- [Class diagram](https://grafloria.com/demos/diagrams/class-uml.html) — three-compartment cards, inheritance and aggregation.
- [UML relationships](https://grafloria.com/demos/diagrams/uml-relationships.html) — all seven relationship kinds, plus a hand-composed self-association. [Source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/diagrams/uml-relationships.html).
- [Scrollable cards](https://grafloria.com/demos/diagrams/scrollable-cards.html) — capped card bodies.
- [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) — how kit specs compose with the shared document model.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) — persist the live diagram rather than its seed spec.

<!-- source: build-a-stencil-editor.md -->

# Build a stencil editor

Use a stencil editor when readers need to browse shape masters, drop them onto a diagram, edit their shape data, and arrange a selection. This example renders a searchable palette on the left, three flowchart shapes in the canvas, and a selection-following property sheet on the right.

The framework binding mounts the diagram; the live instance connects the palette and panel to the same model and command history. Try the [Visio-style editor demo](https://grafloria.com/demos/diagrams/visio-editor.html) to see the authoring surface running.

## 1. Install the packages

Run this in your browser application's project:

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

For a framework application, also install its binding:

```bash
# Angular
npm install @grafloria/angular @angular/common @angular/core @angular/forms @angular/platform-browser rxjs
# Qwik
npm install @grafloria/qwik @builder.io/qwik
# React
npm install @grafloria/react react react-dom
# Vue
npm install @grafloria/vue vue
```

## 2. Connect the editor to a mounted instance

Save this shared browser module as `stencil-editor.ts`. Each framework below calls it after mount, passing its live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance).

[`registerStencils`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-templates) registers the shipped Flowchart, BPMN, UML and ERD masters in that instance's engine and returns the number registered. [`bindStencilPalette`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-stencil-kit) builds the searchable rail and binds drops to the canvas. [`bindShapeDataPanel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-stencil-kit) builds the property sheet and follows selection changes.

Use [`NodeFactory`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-templates) to seed the document with an approval decision and two process shapes. These are setup writes, not user edits. Toolbar actions use [`AlignCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r) and [`DistributeCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r), so each arrangement joins the same undo stack as palette drops and property edits.

```ts title="stencil-editor.ts"
import { AlignCommand, DistributeCommand, NodeFactory, registerStencils } from '@grafloria/engine';
import { bindShapeDataPanel, bindStencilPalette } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';

export function connectEditor(
  api: DiagramInstance,
  rail: HTMLElement,
  panel: HTMLElement,
  toolbar: HTMLElement,
) {
  const engine = api.getEngine();
  const model = api.getModel();
  registerStencils(engine.templateRegistry);

  const factory = new NodeFactory(engine.templateRegistry, model);
  const decision = factory.createFromTemplate(
    'flowchart-decision', { label: 'Approve?' }, { x: 60, y: 80 },
  );
  factory.createFromTemplate(
    'flowchart-process', { label: 'Pay' }, { x: 230, y: 150 },
  );
  factory.createFromTemplate(
    'flowchart-process', { label: 'Archive' }, { x: 460, y: 100 },
  );

  const palette = bindStencilPalette(api, {
    palette: rail, canvas: api.container,
  }, {
    data: (master) => ({ label: master.meta.name }),
  });
  const properties = bindShapeDataPanel(api, panel);

  const selectedIds = () => model.getSelectedNodes()
    .filter((node) => !node.state.locked)
    .map((node) => node.id);

  const align = document.createElement('button');
  align.type = 'button';
  align.textContent = 'Align top';
  align.onclick = async () => {
    const ids = selectedIds();
    if (ids.length < 2) return;
    await engine.commandManager.execute(new AlignCommand(ids, 'top'));
    api.renderNow();
  };

  const distribute = document.createElement('button');
  distribute.type = 'button';
  distribute.textContent = 'Distribute horizontally';
  distribute.onclick = async () => {
    const ids = selectedIds();
    if (ids.length < 3) return;
    await engine.commandManager.execute(new DistributeCommand(ids, 'horizontal'));
    api.renderNow();
  };

  const selectAll = document.createElement('button');
  selectAll.type = 'button';
  selectAll.textContent = 'Select all shapes';
  selectAll.onclick = () => {
    for (const node of model.getNodes()) model.addToSelection(node);
    api.renderNow();
  };
  toolbar.append(selectAll, align, distribute);

  model.selectNode(decision);
  properties.refresh();
  api.renderNow();

  return {
    destroy() {
      palette.destroy();
      properties.destroy();
      selectAll.remove();
      align.remove();
      distribute.remove();
    },
  };
}
```

The initial selection opens the decision's properties, including its schema fields. The panel reads `dataSchema.properties` from the master identified by the node's `templateId` metadata. Enum fields render as selects, booleans as checkboxes, and numbers or strings as inputs. Press Enter or move focus out of a text field to commit an edit, rather than creating an undo entry for every keystroke.

## 3. Mount it in your application

Choose your framework's tab. Keep the palette, panel and toolbar hosts childless: the shared module owns their contents. All tabs use uncontrolled initial specs because subsequent edits belong to the live model.

The JavaScript tab uses [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core). The framework tabs use [`GrafloriaDiagramComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes) for Angular and [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) for Qwik, [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) for React, or [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) for Vue. The empty initial arrays are followed by the three real masters created during initialization.

:::code-group
```ts title="JavaScript"
// main.ts — load this module from your application's HTML entry point.
import { render } from '@grafloria/element';
import { connectEditor } from './stencil-editor';

const shell = document.createElement('section');
shell.style.cssText = 'height:600px;display:flex;flex-direction:column';
const toolbar = document.createElement('div');
const row = document.createElement('div');
row.style.cssText = 'display:flex;flex:1;min-height:0';
const rail = document.createElement('div');
rail.style.cssText = 'width:220px;flex:none;overflow:auto';
const canvas = document.createElement('div');
canvas.style.cssText = 'flex:1;min-width:0;position:relative';
const panel = document.createElement('div');
panel.style.cssText = 'width:240px;flex:none;overflow:auto';
row.append(rail, canvas, panel);
shell.append(toolbar, row);
document.body.append(shell);

const api = render({ nodes: [], edges: [] }, canvas);
const editor = connectEditor(api, rail, panel, toolbar);

// Call this when your application's router removes this view.
export function unmountEditor() {
  editor.destroy();
  api.dispose();
  shell.remove();
}
```
```ts title="Angular"
// app.component.ts
import { Component, OnDestroy } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import type { RenderSpec } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { connectEditor } from './stencil-editor';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [GrafloriaDiagramComponent],
  template: `
    <section style="height:600px;display:flex;flex-direction:column">
      <div #toolbar></div>
      <div style="display:flex;flex:1;min-height:0">
        <div #rail style="width:220px;flex:none;overflow:auto"></div>
        <grafloria-diagram [spec]="spec"
          (ready)="onReady($event, rail, panel, toolbar)"
          style="flex:1;min-width:0;height:100%" />
        <div #panel style="width:240px;flex:none;overflow:auto"></div>
      </div>
    </section>
  `,
})
export class AppComponent implements OnDestroy {
  readonly spec: RenderSpec = { nodes: [], edges: [] };
  private editor?: ReturnType<typeof connectEditor>;

  onReady(api: DiagramInstance, rail: HTMLElement, panel: HTMLElement, toolbar: HTMLElement) {
    this.editor?.destroy();
    this.editor = connectEditor(api, rail, panel, toolbar);
  }

  ngOnDestroy() { this.editor?.destroy(); }
}
```
```tsx title="Qwik"
// stencil-view.tsx
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { connectEditor } from './stencil-editor';

export default component$(() => {
  const rail = useSignal<HTMLDivElement>();
  const panel = useSignal<HTMLDivElement>();
  const toolbar = useSignal<HTMLDivElement>();
  const editor = useSignal<NoSerialize<ReturnType<typeof connectEditor>>>();
  useVisibleTask$(({ cleanup }) => {
    cleanup(() => editor.value?.destroy());
  });

  return (
    <section style="height:600px;display:flex;flex-direction:column">
      <div ref={toolbar} />
      <div style="display:flex;flex:1;min-height:0">
        <div ref={rail} style="width:220px;flex:none;overflow:auto" />
        <div style="flex:1;min-width:0;position:relative">
          <GrafloriaFlow defaultNodes={[]} defaultEdges={[]} onInit$={(api) => {
            editor.value?.destroy();
            editor.value = noSerialize(connectEditor(api, rail.value!, panel.value!, toolbar.value!));
          }} />
        </div>
        <div ref={panel} style="width:240px;flex:none;overflow:auto" />
      </div>
    </section>
  );
});
```
```tsx title="React"
// StencilView.tsx
import { useEffect, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { connectEditor } from './stencil-editor';

export default function StencilView() {
  const rail = useRef<HTMLDivElement>(null);
  const panel = useRef<HTMLDivElement>(null);
  const toolbar = useRef<HTMLDivElement>(null);
  const editor = useRef<ReturnType<typeof connectEditor> | null>(null);
  useEffect(() => () => { editor.current?.destroy(); }, []);

  function onInit(api: DiagramInstance) {
    editor.current?.destroy();
    editor.current = connectEditor(api, rail.current!, panel.current!, toolbar.current!);
  }

  return (
    <section style={{ height: 600, display: 'flex', flexDirection: 'column' }}>
      <div ref={toolbar} />
      <div style={{ display: 'flex', flex: 1, minHeight: 0 }}>
        <div ref={rail} style={{ width: 220, flex: 'none', overflow: 'auto' }} />
        <div style={{ flex: 1, minWidth: 0, position: 'relative' }}>
          <GrafloriaFlow defaultNodes={[]} defaultEdges={[]} onInit={onInit} />
        </div>
        <div ref={panel} style={{ width: 240, flex: 'none', overflow: 'auto' }} />
      </div>
    </section>
  );
}
```
```vue title="Vue"
<!-- StencilView.vue -->
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { connectEditor } from './stencil-editor';

const rail = ref<HTMLDivElement>();
const panel = ref<HTMLDivElement>();
const toolbar = ref<HTMLDivElement>();
let editor: ReturnType<typeof connectEditor> | undefined;

function onInit(api: DiagramInstance) {
  editor?.destroy();
  editor = connectEditor(api, rail.value!, panel.value!, toolbar.value!);
}
onBeforeUnmount(() => editor?.destroy());
</script>

<template>
  <section style="height:600px;display:flex;flex-direction:column">
    <div ref="toolbar"></div>
    <div style="display:flex;flex:1;min-height:0">
      <div ref="rail" style="width:220px;flex:none;overflow:auto"></div>
      <div style="flex:1;min-width:0;position:relative">
        <GrafloriaFlow :default-nodes="[]" :default-edges="[]" @init="onInit" />
      </div>
      <div ref="panel" style="width:240px;flex:none;overflow:auto"></div>
    </div>
  </section>
</template>
```
:::

![JavaScript: a searchable Flowchart rail, three shapes, arrangement buttons, and the selected decision's property sheet.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/579bbc2def26faa0108c3ae51b77cacb.png)

Angular renders the same rail and property sheet beside the selected decision and the Pay shape; the Archive shape extends behind the panel at this viewport width.

![Angular: the selected Approve? decision with Name, Size & Position, and Format controls on the right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/4f07f6a6e1d745fe688a67872d7f27da.png)

Qwik renders the editor with its three toolbar actions above the palette and canvas.

React renders the same initial selection and arrangement controls.

Vue renders the Flowchart palette with search and the selected decision's property sheet.

Angular's component owns instance disposal. React, Vue and Qwik likewise own the mounted flow's lifecycle; their unmount hooks above remove only the editor's additional bindings. Qwik keeps the function-bearing editor handle in `noSerialize()` state and creates it in the browser's initialization callback.

### Arrange masters with Angular's canvas component

If your Angular editor already uses [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent), bind its `engine` input rather than mounting a second diagram. This standalone alternative renders three shipped masters and applies the arrangement commands to that canvas's model. Click **Align top** to line up their top edges, then **Distribute horizontally** to equalize the gaps.

```ts title="canvas-editor.component.ts"
import { Component, OnDestroy } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { AlignCommand, DiagramEngine, DistributeCommand, NodeFactory, registerStencils } from '@grafloria/engine';

@Component({
  selector: 'app-canvas-editor',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button type="button" (click)="align()">Align top</button>
    <button type="button" (click)="distribute()">Distribute horizontally</button>
    <grafloria-diagram-canvas [engine]="engine"
      style="display:block;height:500px" />
  `,
})
export class CanvasEditorComponent implements OnDestroy {
  readonly engine = new DiagramEngine();
  private readonly model = this.engine.createDiagram('Stencil arrangement');

  constructor() {
    registerStencils(this.engine.templateRegistry);
    const factory = new NodeFactory(this.engine.templateRegistry, this.model);
    factory.createFromTemplate('flowchart-decision', { label: 'Approve?' }, { x: 60, y: 80 });
    factory.createFromTemplate('flowchart-process', { label: 'Pay' }, { x: 230, y: 150 });
    factory.createFromTemplate('flowchart-process', { label: 'Archive' }, { x: 460, y: 100 });
    for (const node of this.model.getNodes()) this.model.addToSelection(node);
  }

  async align() {
    const ids = this.model.getSelectedNodes().map((node) => node.id);
    await this.engine.commandManager.execute(new AlignCommand(ids, 'top'));
  }

  async distribute() {
    const ids = this.model.getSelectedNodes().map((node) => node.id);
    await this.engine.commandManager.execute(new DistributeCommand(ids, 'horizontal'));
  }

  ngOnDestroy() { this.engine.dispose(); }
}
```

![Angular canvas: Approve?, Pay, and Archive are selected, with Align top and Distribute horizontally buttons above them.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/092da5b236f9613314ba771d04d8f3ae.png)

## 4. Drop, edit and arrange shapes

- Type `gateway` in the palette search box. Search matches master names, ids and tags, and opens matching sections. Clearing the query restores the section collapse choices.
- Drag a master onto the canvas. It lands centered on the drop point, converted through the instance's viewport into world coordinates. The placement is one undoable command batch.
- Select a shape to inspect its properties. Select an edge to see its label, line, arrows and route controls; select multiple shapes to see their shared Format section. Deselect everything to return to the empty message.
- Click **Select all shapes**, then **Align top**. The shapes share the smallest top coordinate in the selection.
- Click **Distribute horizontally**. The leftmost and rightmost shapes stay put, and the interior shapes move to equalize the gaps—not the distances between centers.

Alignment needs at least two movable nodes; distribution needs three. Both ignore locked nodes. The sample filters them before checking the count. Distribution can produce negative gaps when the outer span cannot contain all selected widths, so spread the extreme shapes farther apart if you want space between them.

## Options that matter

Configure the palette with [`StencilPaletteOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-stencil-kit) and the panel with [`ShapeDataPanelOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-stencil-kit).

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| Palette `stencils` | `Stencil[]` | Every built-in stencil | Chooses the sections to show; register the same masters in the engine. |
| Palette `search` | `boolean` | `true` | Shows the search input. |
| Palette `collapsed` | `string[]` | All stencil ids except the first | Chooses initially closed sections. |
| Palette `data` | `(master: NodeTemplate) => Record<string, unknown>` | Not supplied | Supplies data merged into template defaults on placement. |
| Panel `title` | `string` | `'Shape data'` | Sets the heading. |
| Panel `emptyText` | `string` | `'Select a shape to edit its data.'` | Sets the no-selection message. |

[`Stencil`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-templates) describes a categorized set of masters; [`NodeTemplate`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-templates) carries each master's structure, defaults and schema. Register masters before placement: the palette's `place(masterId, world)` returns `null` when the registry has no matching master, otherwise it resolves to the placed root node id. `setSearch(query)` filters programmatically. The panel's `refresh()` re-reads selection and rebuilds its fields.

## Related

- [Stencil palette demo](https://grafloria.com/demos/diagrams/stencil-palette.html) and [shape data demo](https://grafloria.com/demos/diagrams/shape-data.html).
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) for application actions and undo.
- [Edit database models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-database-models) for real entity tables rather than notation silhouettes.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for persisting the live model.

<!-- source: build-a-dashboard.md -->

# Build a dashboard

Use the dashboard kit when you need a board of charts that readers can rearrange and resize. Declare widgets as data; the kit owns the pack grid and its gestures. The examples below draw all six shipped widget kinds, add a custom note, and save committed layout changes in browser storage.

## 1. Declare the board and its toolbar actions

Put this shared file beside your framework component. Use [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec#dashboardwidgetspec) for each widget and [`DashboardViewSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-interfaces#dashboardviewspec) for each board. Pass either `views` or the single-view shorthand `widgets`, not both. Multiple views show one board at a time; your application supplies the tab buttons.

The six `kind` values select the shipped painters. You supply the numbers and formatting, not a charting dependency:

| Kind | Data used in this example | What renders |
| --- | --- | --- |
| `kpi` | `label`, `value`, `spark` | Headline value and sparkline in this initial layout |
| `line` | Named `series` and `labels` | Lines over a shared x axis |
| `bar` | `bars` with labels and values | Categorical columns |
| `donut` | `slices`, `centerLabel` | Parts of a whole with a legend |
| `funnel` | Ordered `stages` | Stage bars scaled against the first stage |
| `table` | `columns`, `rows` | A table of strings and numbers |

[`DashboardOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardoptions#dashboardoptions) configures the board. [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle#dashboardhandle) is the live façade; `widget()` returns a [`WidgetHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-widgethandle#widgethandle), or `undefined` for an unknown id. Use these handles for edits rather than rebuilding node models.

```ts title="board.ts"
import type {
  DashboardHandle,
  DashboardOptions,
  DashboardSnapshot,
  DashboardViewSpec,
  DashboardWidgetSpec,
} from '@grafloria/element';

const storageKey = 'sales-dashboard';
let nextWidgetId = 0;

export function initialBoard(): DashboardSnapshot {
  const widgets: DashboardWidgetSpec[] = [
    { id: 'revenue', kind: 'kpi', span: 6, rows: 1,
      data: { label: 'Revenue', value: '$6.8M',
        spark: [42, 45, 51, 55, 61, 76] } },
    { id: 'note', kind: 'note', span: 6, rows: 1,
      title: 'Quarterly review', data: { text: 'Review the pipeline on Friday.' } },
    { id: 'trend', kind: 'line', span: 6, rows: 2, title: 'Revenue trend',
      data: { series: [{ name: 'Revenue', values: [42, 51, 76] }],
        labels: ['Jan', 'Feb', 'Mar'] } },
    { id: 'regions', kind: 'bar', span: 6, rows: 2, title: 'Revenue by region',
      data: { bars: [{ label: 'EMEA', value: 29 }, { label: 'AMER', value: 24 },
        { label: 'APAC', value: 15 }] } },
    { id: 'share', kind: 'donut', span: 6, rows: 2, title: 'Region share',
      data: { slices: [{ label: 'EMEA', value: 29 }, { label: 'AMER', value: 24 },
        { label: 'APAC', value: 15 }], centerLabel: '$6.8M' } },
    { id: 'pipeline', kind: 'funnel', span: 6, rows: 2, title: 'Pipeline',
      data: { stages: [{ label: 'Leads', value: 1200 },
        { label: 'Qualified', value: 820 }, { label: 'Won', value: 188 }] } },
    { id: 'reps', kind: 'table', span: 12, rows: 2, title: 'Top reps',
      data: { columns: ['Rep', 'Deals', 'Revenue'],
        rows: [['A. Farouk', 38, '$1.24M'], ['M. Haddad', 31, '$0.98M']] } },
  ];
  const views: DashboardViewSpec[] = [{ id: 'overview', name: 'Overview', widgets }];
  const options: DashboardOptions = {
    columns: 12, gap: 8, mode: 'fluid', sizing: 'fit',
  };
  return { ...options, views };
}

export function loadBoard(): DashboardSnapshot {
  if (typeof window === 'undefined') return initialBoard();
  const text = localStorage.getItem(storageKey);
  if (!text) return initialBoard();
  try {
    const saved: DashboardSnapshot = JSON.parse(text);
    return saved;
  } catch {
    return initialBoard();
  }
}

export function saveBoard(handle: DashboardHandle): void {
  localStorage.setItem(storageKey, JSON.stringify(handle.toJSON()));
}

export const actions = ['Update revenue', 'Add KPI', 'Remove trend', 'Pin revenue', 'Save'] as const;
export type Action = typeof actions[number];

export function performAction(handle: DashboardHandle | undefined, action: Action): void {
  if (!handle) return;
  switch (action) {
    case 'Update revenue':
      handle.widget('revenue')?.update({
        data: { label: 'Revenue', value: '$7.2M',
          spark: [42, 45, 51, 55, 61, 80] },
      });
      break;
    case 'Add KPI': {
      let id: string;
      do { id = `added-kpi-${++nextWidgetId}`; } while (handle.widget(id));
      const added = handle.addWidget({
        id, kind: 'kpi', span: 3, rows: 1,
        data: { label: 'New customers', value: '128' },
      });
      if (!added) window.alert('The board cannot accept another widget.');
      break;
    }
    case 'Remove trend':
      handle.widget('trend')?.remove();
      break;
    case 'Pin revenue':
      handle.widget('revenue')?.pin(true);
      break;
    case 'Save':
      break;
  }
  saveBoard(handle);
}
```

`update()` replaces `data` and repaints the widget; it does not merge the previous payload. `addWidget()` creates the widget and returns its handle, or `undefined` when the board is unknown or a bounded fit board has no room. `remove()` removes the widget and records the survivors' re-pack as one undoable step. `pin(true)` keeps Revenue from moving or being pushed during reflow.

The toolbar saves after each action. In particular, `update()` repaints directly rather than issuing a layout command, so this example saves its data change explicitly. Layout gestures use the component's layout-change event in the next step.

## 2. Mount it in your framework

Run these examples in your own browser application. Each tab uses `board.ts` above, loads saved data before mounting, and holds the handle using its framework's idiom. The board starts with a Revenue KPI, five other shipped painters and a custom note. Use Add KPI to create a New customers card; the shared action allocates its id with an increasing counter and checks existing widgets before adding it. The other buttons update Revenue, remove the trend, pin Revenue and save.

For JavaScript, [`dashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-functions#dashboard) returns the spec and [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) mounts it. Delegate all non-note kinds to [`defaultWidgetRenderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-constants#defaultwidgetrenderer).

React's [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadashboard) maps kinds to components through `widgetTypes`. Its `WidgetProps` type comes from the [React package reference](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react). Vue's [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadashboard) uses `#widget-<kind>` slots. Angular's [`GrafloriaDashboardComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-grafloriadashboardcomponent#grafloriadashboardcomponent) uses a `grafloriaWidget` template declared with `GrafloriaWidgetDefDirective` from the [Angular package](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-overview). Qwik's [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadashboard) maps kinds to self-contained Qwik components; its `WidgetProps` type comes from the [Qwik package reference](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik).

Install the packages for your framework.

JavaScript:

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

React:

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

Vue:

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

Angular:

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

Qwik:

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

:::code-group
```ts title="JavaScript"
// dashboard-page.ts — call mountDashboard() with a mounted page element.
import { dashboard, render, defaultWidgetRenderer } from '@grafloria/element';
import { actions, performAction, loadBoard, saveBoard } from './board';

export function mountDashboard(page: HTMLElement): () => void {
  const toolbar = document.createElement('nav');
  const container = document.createElement('div');
  container.style.height = '720px';
  page.append(toolbar, container);
  const spec = dashboard({
    ...loadBoard(),
    renderWidget(widget, host) {
      if (widget.kind !== 'note') {
        defaultWidgetRenderer(widget, host);
        return;
      }
      const note = document.createElement('p');
      note.textContent = String(widget.data?.['text'] ?? '');
      note.style.padding = '16px';
      host.replaceChildren(note);
    },
    onLayoutChange() { saveBoard(spec.handle); },
  });
  const instance = render(spec, container);
  for (const action of actions) {
    const button = document.createElement('button');
    button.textContent = action;
    button.onclick = () => performAction(spec.handle, action);
    toolbar.append(button);
  }
  return () => {
    instance.dispose();
    toolbar.remove();
    container.remove();
  };
}

const page = document.getElementById('app');
if (!page) throw new Error('Add an element with id="app" to your page.');
// Keep this callback for your router's unmount hook.
export const unmountDashboard = mountDashboard(page);
```
```tsx title="React"
// DashboardPage.tsx
import { useRef, useState } from 'react';
import { GrafloriaDashboard, type WidgetProps } from '@grafloria/react';
import type { DashboardHandle } from '@grafloria/element';
import { actions, performAction, loadBoard, saveBoard } from './board';

function Note({ data }: WidgetProps) {
  return <p style={{ padding: 16 }}>{String(data['text'] ?? '')}</p>;
}

export default function DashboardPage() {
  const [board] = useState(loadBoard);
  const handle = useRef<DashboardHandle | undefined>(undefined);
  return <>
    <nav>{actions.map(action => <button key={action}
      onClick={() => performAction(handle.current, action)}>{action}</button>)}</nav>
    <div style={{ height: 720 }}>
      <GrafloriaDashboard views={board.views} options={board}
        widgetTypes={{ note: Note }}
        onReady={value => { handle.current = value; }}
        onLayoutChange={() => { if (handle.current) saveBoard(handle.current); }} />
    </div>
  </>;
}
```
```vue title="Vue"
<!-- DashboardPage.vue -->
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle } from '@grafloria/element';
import { actions, performAction, loadBoard, saveBoard } from './board';

const board = loadBoard();
const handle = shallowRef<DashboardHandle>();
function ready(value: DashboardHandle): void { handle.value = value; }
function persist(): void { if (handle.value) saveBoard(handle.value); }
</script>

<template>
  <nav>
    <button v-for="action in actions" :key="action"
      @click="performAction(handle, action)">{{ action }}</button>
  </nav>
  <div style="height:720px">
    <GrafloriaDashboard :views="board.views" :options="board"
      @ready="ready" @layout-change="persist">
      <template #widget-note="{ data }">
        <p style="padding:16px">{{ String(data.text ?? '') }}</p>
      </template>
    </GrafloriaDashboard>
  </div>
</template>
```
```ts title="Angular"
// dashboard-page.component.ts
import { Component } from '@angular/core';
import { GrafloriaDashboardComponent, GrafloriaWidgetDefDirective } from '@grafloria/angular';
import type { DashboardHandle } from '@grafloria/element';
import { actions, performAction, loadBoard, saveBoard } from './board';

@Component({
  selector: 'app-dashboard-page',
  standalone: true,
  imports: [GrafloriaDashboardComponent, GrafloriaWidgetDefDirective],
  template: `
    <nav>
      @for (action of actions; track action) {
        <button (click)="performAction(handle, action)">{{ action }}</button>
      }
    </nav>
    <grafloria-dashboard [views]="board.views" [options]="board"
      (ready)="handle = $event" (layoutChange)="persist()"
      style="height:720px">
      <ng-template grafloriaWidget="note" let-data="data">
        <p style="padding:16px">{{ data['text'] }}</p>
      </ng-template>
    </grafloria-dashboard>
  `,
})
export class DashboardPageComponent {
  readonly board = loadBoard();
  readonly actions = actions;
  readonly performAction = performAction;
  handle?: DashboardHandle;
  persist(): void { if (this.handle) saveBoard(this.handle); }
}
```
```tsx title="Qwik"
// dashboard-page.tsx
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaDashboard, type WidgetProps } from '@grafloria/qwik';
import type { DashboardHandle, DashboardSnapshot } from '@grafloria/element';
import { actions, performAction, loadBoard, saveBoard } from './board';

const Note = component$<WidgetProps>(({ data }) =>
  <p style={{ padding: '16px' }}>{String(data['text'] ?? '')}</p>
);

export default component$(() => {
  const board = useSignal<DashboardSnapshot>();
  const handle = useSignal<NoSerialize<DashboardHandle>>();
  useVisibleTask$(() => { board.value = loadBoard(); });
  return <>
    <nav>{actions.map(action => <button key={action}
      onClick$={() => performAction(handle.value, action)}>{action}</button>)}</nav>
    <div style={{ height: '720px' }}>
      {board.value && <GrafloriaDashboard views={board.value.views} options={board.value}
        widgetTypes={{ note: Note }}
        onReady$={value => { handle.value = noSerialize(value); }}
        onLayoutChange$={() => { if (handle.value) saveBoard(handle.value); }} />}
    </div>
  </>;
});
```
:::

The JavaScript sample starts with the six shipped widget kinds and a note beside Revenue.

![JavaScript dashboard with the five toolbar buttons, Revenue, the review note, charts and Top reps table.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ce19d8675245335d25c3cd6f1c0c6697.png)

React renders the same board with the note component alongside the KPI.

Vue supplies the review note through its widget slot.

Angular supplies the note through its widget template.

Qwik renders the board after loading browser storage.

This example omits the percentage change to match the short initial KPI layout. If you supply `data.delta`, the shipped styles hide it at body heights of 40px or less; the short, wide layout can still show the sparkline.

The framework components dispose their mounted instances on unmount. In JavaScript, call the returned cleanup callback from your application's unmount hook. Qwik loads browser storage in `useVisibleTask$` and keeps the live handle with `noSerialize()`; see [Qwik state and resumption](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-state-and-resumption).

## 3. Save committed changes and reopen the board

Drag or resize a widget: the layout-change callback receives the changed view id and its widget specs after the commit. Save `handle.toJSON()` there, as the samples do, to keep every view and the live board options, not only the changed view. The same reporting path follows layout commands, undo and redo; it suppresses duplicate widget layouts and does not report the initial mount as an edit.

[`DashboardSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types#dashboardsnapshot) is dashboard input data. Reload the page to run `loadBoard()` and mount that snapshot again: JavaScript passes it to `dashboard()`, while each component receives its `views` and options. Changing a React `views` prop after mount is not a replacement operation—the binding mounts once and sends data edits through the handle.

The snapshot saves widget data, cells, membership and per-view layouts, plus live sizing and board switches. It does not save the active top-level view, widget selection, keyboard focus, camera position or command history. Reopening starts a new instance. Reattach custom renderers, framework components/templates and callbacks in application code, as these samples do; JSON storage does not preserve functions. `loadBoard()` reads data written by this application, not untrusted imports—validate externally supplied JSON before using it.

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `columns` | `number` | `12` | Sets the column count |
| `gap` | `number` | `8` | Sets widget gaps and board padding in pixels |
| `layout` | `'grid' \| 'split'` | `'grid'` | Uses cells or a splitter tree; split always fits its pane |
| `mode` | `'fluid' \| 'fixed'` | Fixed when `width` is supplied; otherwise fluid | Fluid uses container pixels; fixed uses an authored board size and camera |
| `sizing` | `'fit' \| 'grow'` | Grow for fluid; fit for fixed | Fit squeezes rows into the board height; grow keeps row height and extends downward |
| `rowHeight` | `number` | `130` | Sets row height in grow mode |
| `static` | `boolean` | `false` | Disables pointer drag, resize and handles |
| Widget `span` / `rows` | `number` | `3` / `1` | Sizes a widget in cells |
| Widget `movable` / `resizable` | `boolean` | `true` / `true` | Restricts user movement/resizing; API movement/resizing remains available |

## Pitfalls

- Omit `x` and `y` to flow widgets in declaration order. Supply both for an explicit cell.
- Missing or invalid painter data produces an empty state. Unknown kinds produce a titled placeholder. Register only your custom kinds; leave shipped kinds to the fallback painter.
- `renderWidget` is a mount hook, not a per-frame callback. Use `update()` for a new payload or `repaint()` after changing data. See [JavaScript elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content) for host lifetime details.
- Check the boolean returned by `moveTo()` or `resize()` when adding those controls: `true` means the board accepts the cell operation. They do not promise that every requested position or size is legal.
- For container sizing, split layouts and nested tab pages, continue with [Arrange dashboard containers](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/arrange-dashboard-containers).

## Live demo and related pages

Try the [dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html) for a larger palette and multi-view toolbar. Its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/dashboard/dashboard-builder.html) shows the same data-first authoring pattern.

- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) explains the shared undo stack.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) covers container sizing and themes.
- [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) covers the shared document format beyond a dashboard snapshot.

<!-- source: arrange-dashboard-containers.md -->

# Arrange dashboard containers

Use a cell grid when widgets need column spans and gravity packing. Use a split layout when widgets need to cover the board and resize through percentage dividers. Both layouts use the same dashboard data; you can switch the mounted board without replacing its widgets.

The example starts with two KPI cards, an Operations section, and a tab container showing Filters. Its controls switch Grid/Split and Fit/Grow, mirror the board, toggle gravity, and change the section caption or active tab.

## 1. Declare the board

Install the packages for the binding you use in your framework project.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

Put the following shared file beside your component or browser entry point. This example adds an inner grid and tab pages to the [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec) entries in a [`DashboardViewSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-interfaces); see [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) for board and widget declarations.

The kit draws the `kpi` kind from your data, so this layout needs no chart renderer. [`DashboardOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardoptions) supplies the shared geometry. These options omit `width`: the board uses fluid sizing at zoom 1 and follows its container. `sizing: 'fit'` keeps its height bounded.

```ts title="board.ts"
import type {
  DashboardOptions,
  DashboardViewSpec,
  DashboardWidgetSpec,
} from '@grafloria/element';

const widgets: DashboardWidgetSpec[] = [
  {
    id: 'revenue', kind: 'kpi', span: 6, rows: 1,
    data: { label: 'Revenue', value: '$6.81M', delta: 12.4 },
  },
  {
    id: 'customers', kind: 'kpi', span: 6, rows: 1,
    data: { label: 'Customers', value: '1,284', delta: 8.1 },
  },
  {
    id: 'ops', title: 'Operations', span: 8, rows: 3,
    columns: 4, sizing: 'fit',
    caption: { subtitle: 'Today', description: 'Operational KPIs' },
    widgets: [
      {
        id: 'orders', kind: 'kpi', span: 2, rows: 1,
        data: { label: 'Orders', value: '312' },
      },
      {
        id: 'churn', kind: 'kpi', span: 2, rows: 1,
        data: { label: 'Churn', value: '1.9%' },
      },
    ],
  },
  {
    id: 'side', title: 'Side panel', span: 4, rows: 3,
    layout: 'tabs', active: 'filters', tabs: { stretch: true },
    widgets: [
      {
        id: 'filters', title: 'Filters', columns: 1, sizing: 'fit',
        widgets: [
          {
            id: 'region', kind: 'kpi', span: 1, rows: 1,
            data: { label: 'Region', value: 'EMEA' },
          },
        ],
      },
      {
        id: 'alerts', title: 'Alerts', columns: 1, sizing: 'fit',
        widgets: [
          {
            id: 'open-alerts', kind: 'kpi', span: 1, rows: 1,
            data: { label: 'Open alerts', value: '3' },
          },
        ],
      },
    ],
  },
];

export const views: DashboardViewSpec[] = [{ id: 'main', widgets }];
export const options: Partial<DashboardOptions> = {
  columns: 12,
  gap: 10,
  sizing: 'fit',
  responsive: { columnWidth: 80 },
  dragHandle: { grip: true, position: 'right', placement: 'inside' },
};
```

At narrower widths, `responsive` derives fewer columns, capped by `columns`. Widening again restores the cached wide layout. Omitted `x` and `y` place widgets in declaration order, wrapping at the column count.

## 2. Mount it and bind the switches

Use [`dashboard()`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-functions) and [`render()`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) in JavaScript. `render()` mounts the spec and initializes its live [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle). Its return value is the renderer's [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance); keep that for teardown, and use the dashboard handle for board operations.

For framework components, use [`GrafloriaDashboardComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-grafloriadashboardcomponent) in Angular, [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadashboard) in Qwik, [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadashboard) in React, or [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadashboard) in Vue. Each binding supplies the handle through its ready event. Bind `layout` and `sizing` as props or inputs: changes call the live handle rather than remounting the board.

Choose one tab below. The framework examples are components to render in your application; the JavaScript entry point runs in the browser. All import `./board` from step 1.

:::code-group
```ts title="JavaScript"
import { dashboard, render } from '@grafloria/element';
import { options, views } from './board';

export function mountDashboard(parent: HTMLElement): () => void {
  const wrapper = document.createElement('section');
  const toolbar = document.createElement('div');
  const host = document.createElement('div');
  host.style.height = '480px';
  wrapper.append(toolbar, host);
  parent.append(wrapper);

  const spec = dashboard({ ...options, views });
  const instance = render(spec, host);
  const handle = spec.handle;
  const button = (label: string, action: () => void): void => {
    const control = document.createElement('button');
    control.textContent = label;
    control.addEventListener('click', action);
    toolbar.append(control);
  };
  button('Grid', () => handle.setLayout('grid'));
  button('Split', () => handle.setLayout('split'));
  button('Fit', () => handle.setSizing('fit'));
  button('Grow', () => handle.setSizing('grow'));
  button('RTL', () => handle.setRtl(!handle.getRtl()));
  button('Float', () => handle.setFloat(!handle.getFloat()));
  button('Caption chip', () => {
    handle.setCaption('ops', { text: 'Operations', position: 'tab', icon: '▤' });
  });
  button('Alerts tab', () => { handle.activateTab('side', 'alerts'); });
  button('Frame board', () => handle.fit());

  return () => {
    instance.dispose();
    wrapper.remove();
  };
}

mountDashboard(document.body);
```
```ts title="Angular"
import { Component, signal } from '@angular/core';
import { GrafloriaDashboardComponent } from '@grafloria/angular';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

@Component({
  selector: 'app-arrange-dashboard',
  standalone: true,
  imports: [GrafloriaDashboardComponent],
  template: `
    <div>
      <button (click)="layout.set('grid')">Grid</button>
      <button (click)="layout.set('split')">Split</button>
      <button (click)="sizing.set('fit')">Fit</button>
      <button (click)="sizing.set('grow')">Grow</button>
      <button (click)="handle?.setRtl(!handle?.getRtl())">RTL</button>
      <button (click)="handle?.setFloat(!handle?.getFloat())">Float</button>
      <button (click)="captionChip()">Caption chip</button>
      <button (click)="handle?.activateTab('side', 'alerts')">Alerts tab</button>
      <button (click)="handle?.fit()">Frame board</button>
    </div>
    <grafloria-dashboard
      [views]="views" [options]="options"
      [layout]="layout()" [sizing]="sizing()"
      (ready)="handle = $event"
      style="display:block; height:480px" />
  `,
})
export class ArrangeDashboardComponent {
  readonly views = views;
  readonly options = options;
  readonly layout = signal<'grid' | 'split'>('grid');
  readonly sizing = signal<'fit' | 'grow'>('fit');
  handle?: DashboardHandle;

  captionChip(): void {
    this.handle?.setCaption('ops', {
      text: 'Operations', position: 'tab', icon: '▤',
    });
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaDashboard } from '@grafloria/qwik';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

export default component$(() => {
  const handle = useSignal<NoSerialize<DashboardHandle>>();
  const layout = useSignal<'grid' | 'split'>('grid');
  const sizing = useSignal<'fit' | 'grow'>('fit');

  return (
    <section>
      <div>
        <button onClick$={() => { layout.value = 'grid'; }}>Grid</button>
        <button onClick$={() => { layout.value = 'split'; }}>Split</button>
        <button onClick$={() => { sizing.value = 'fit'; }}>Fit</button>
        <button onClick$={() => { sizing.value = 'grow'; }}>Grow</button>
        <button onClick$={() => handle.value?.setRtl(!handle.value.getRtl())}>RTL</button>
        <button onClick$={() => handle.value?.setFloat(!handle.value.getFloat())}>Float</button>
        <button onClick$={() => handle.value?.setCaption('ops', {
          text: 'Operations', position: 'tab', icon: '▤',
        })}>Caption chip</button>
        <button onClick$={() => handle.value?.activateTab('side', 'alerts')}>Alerts tab</button>
        <button onClick$={() => handle.value?.fit()}>Frame board</button>
      </div>
      <GrafloriaDashboard
        views={views} options={options} layout={layout.value} sizing={sizing.value}
        onReady$={(value) => { handle.value = noSerialize(value); }}
        style={{ height: '480px' }} />
    </section>
  );
});
```
```tsx title="React"
import { useState } from 'react';
import { GrafloriaDashboard } from '@grafloria/react';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

export default function ArrangeDashboard() {
  const [handle, setHandle] = useState<DashboardHandle | null>(null);
  const [layout, setLayout] = useState<'grid' | 'split'>('grid');
  const [sizing, setSizing] = useState<'fit' | 'grow'>('fit');

  return (
    <section>
      <div>
        <button onClick={() => setLayout('grid')}>Grid</button>
        <button onClick={() => setLayout('split')}>Split</button>
        <button onClick={() => setSizing('fit')}>Fit</button>
        <button onClick={() => setSizing('grow')}>Grow</button>
        <button onClick={() => handle?.setRtl(!handle.getRtl())}>RTL</button>
        <button onClick={() => handle?.setFloat(!handle.getFloat())}>Float</button>
        <button onClick={() => handle?.setCaption('ops', {
          text: 'Operations', position: 'tab', icon: '▤',
        })}>Caption chip</button>
        <button onClick={() => handle?.activateTab('side', 'alerts')}>Alerts tab</button>
        <button onClick={() => handle?.fit()}>Frame board</button>
      </div>
      <GrafloriaDashboard
        views={views} options={options} layout={layout} sizing={sizing}
        onReady={setHandle} style={{ height: '480px' }} />
    </section>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle } from '@grafloria/element';
import { options, views } from './board';

const handle = shallowRef<DashboardHandle | null>(null);
const layout = ref<'grid' | 'split'>('grid');
const sizing = ref<'fit' | 'grow'>('fit');

function captionChip(): void {
  handle.value?.setCaption('ops', {
    text: 'Operations', position: 'tab', icon: '▤',
  });
}
</script>

<template>
  <section>
    <div>
      <button @click="layout = 'grid'">Grid</button>
      <button @click="layout = 'split'">Split</button>
      <button @click="sizing = 'fit'">Fit</button>
      <button @click="sizing = 'grow'">Grow</button>
      <button @click="handle?.setRtl(true)">RTL</button>
      <button @click="handle?.setFloat(!handle.getFloat())">Float</button>
      <button @click="captionChip">Caption chip</button>
      <button @click="handle?.activateTab('side', 'alerts')">Alerts tab</button>
      <button @click="handle?.fit()">Frame board</button>
    </div>
    <GrafloriaDashboard
      :views="views" :options="options" :layout="layout" :sizing="sizing"
      @ready="handle = $event" style="height:480px" />
  </section>
</template>
```
:::

The JavaScript sample starts with Revenue and Customers above Operations and the Filters page.

![JavaScript board with the layout toolbar, Operations caption, and Filters and Alerts tabs.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f927465021a1ebb8756258f4b66a2257.png)

The Angular component shows Orders and Churn inside Operations, beside Region in the active Filters page.

![Angular board with two top-level KPI cards, the Operations section, and Filters selected.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6e5fb9d219e192e5d3fda918533e746d.png)

The Qwik component shows the same initial grid with the toolbar above it.

The React component starts with the Operations subtitle Today and the Filters page showing EMEA.

The Vue component also starts in the grid, with Filters selected and Alerts available beside it.

Press **Split** to replace grid resize corners with dividers; drag a divider to change pane proportions. Press **Grid** to project the split tree back into cells. These controls change the view's layout, not the Operations section's inner grid or the side panel's tabs. To switch a section or page separately, pass its id as the second argument to `setLayout()`, such as `setLayout('split', 'ops')`.

Press **Grow** in grid mode to keep row heights and let the board extend downward; **Fit** keeps the board height and squeezes rows. Split layout always fits, so it does not become a growing grid when you press Grow. **Frame board** calls `fit()` to reframe the current view's camera—it does not change the sizing mode.

The ready callback gives Qwik a live handle in the browser; `noSerialize()` keeps it out of resumable state. The framework components dispose their renderer on unmount. In JavaScript, keep the function returned by `mountDashboard()` and call it when your application removes the panel.

## 3. Tune the geometry and interaction

### Fixed size or fluid size

For a fixed design surface, replace the shared `options` export with `mode: 'fixed', width: 1180, height: 660` alongside your other options. The camera frames those authored dimensions. An explicit `width` also implies fixed mode unless you set `mode` yourself. A fluid board takes its dimensions from the container instead; see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) for container sizing.

The following options govern the board, not the renderer's zoom-to-content operation:

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `mode` | `'fluid' \| 'fixed'` | `'fluid'`; explicit `width` implies `'fixed'` | Uses container pixels at zoom 1, or an authored world size framed by the camera. |
| `width`, `height` | `number` | `1180`, `660` | Defines the fixed board size in pixels. |
| `layout` | `'grid' \| 'split'` | `'grid'` | Packs cells or fills the board through a splitter tree. Split always fits. |
| `sizing` | `'fit' \| 'grow'` | `'grow'` fluid; `'fit'` fixed | Squeezes rows within the height, or keeps row height and extends downward. |
| `rowHeight` | `number` | `130` | Sets row height in growing grids, in pixels. |
| `overflow` | `'bounded' \| 'scroll'` | `'bounded'` | Enforces fit capacity, or opts into an extending frame and camera panning. |
| `squeeze` | `boolean` | `true` | Squeezes bounded fit rows toward the row floor before refusing growth. `false` freezes the current row height for gestures. |
| `columns` | `number` | `12` | Sets the grid's column count; views and containers can override it. |
| `gap` | `number` | `8` | Sets widget gaps and board padding in pixels. |
| `float` | `boolean` | `false` | Allows gaps when true; otherwise gravity packs widgets upward. |
| `rtl` | `boolean` | `false` | Mirrors pixels so cell `x=0` appears on the right; cells stay unchanged. |
| `responsive` | `DashboardOptions['responsive']` | Not set | Derives live columns from width, using column-width rules or breakpoints. |
| `dragHandle` | `DashboardOptions['dragHandle']` | `false` | Chooses the whole card, caption, selector, or painted grip as the drag zone. |
| `static` | `boolean` | `false` | Disables pointer dragging, resizing, and handles; API edits still work. |

A bounded fit grid refuses a drop, resize, or `addWidget()` that needs more rows than its capacity. `addWidget()` returns `undefined` when the widget does not fit. An already oversized board—loaded from a document or switched from Grow—still squeezes to the frame rather than scrolling. With `overflow: 'scroll'`, you explicitly opt out of that bound.

### Gravity, RTL, and columns

Use **Float** in grid mode to toggle whether gaps are legal. Turning float off repacks widgets upward. In the Vue sample, **RTL** calls `setRtl(true)` to mirror widget pixels without rewriting their cells; repeated clicks keep RTL enabled rather than reversing the mirror.

For explicit column controls, call `setColumns(6, 'moveScale', 'main')` on the ready handle. It returns `void`; read `getColumns('main')` for the live count. The optional reflow argument uses [`GridColumnLayout`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-grid-pack):

| Reflow mode | Result |
| --- | --- |
| `'moveScale'` (default) | Scales both horizontal position and span by the new/old column ratio. |
| `'move'` | Scales position; keeps spans, clamped to fit. |
| `'scale'` | Scales spans; keeps positions, clamped to fit. |
| `'none'` | Keeps positions and spans; clamps only what no longer fits. |

One column forces a single stack in every mode. A manual `setColumns()` call pins the grid's column count instead of continuing to follow the width observer. Keep the sample's responsive rule for automatic resizing, or use explicit column controls for a user-selected count; do not expect both to drive the same grid simultaneously.

### Sections, captions, tabs, and grips

Operations has four inner columns regardless of its outer span. Its `sizing: 'fit'` refuses child growth beyond the pane; a container's default `'grow'` instead grows its slab in the parent when a child needs another row. `maxRows` defines the inner grid's designed row count, while `limits.maxRows` limits a widget's own resize. Containers can nest; nesting beyond two levels is not exercised by the library's gates.

[`SectionCaption`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types) accepts `true` for the section title, a string for explicit text, `false` for no caption, or [`SectionCaptionOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-sectioncaptionoptions). The initial subtitle reserves a second caption line. **Caption chip** changes it to a title-sized chip at the section's leading corner; both `position: 'inside'` and `'tab'` reserve space inside the section. `setCaption()` returns `false` for a non-container; a successful change repaints and records one undo step.

For caption behavior, `show: 'design'` removes the band and its reserve in static mode; `show: 'hover'` overlays content without reserving space. Caption action buttons call `onCaptionAction` instead of selecting the section.

[`TabsOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-tabsoptions) controls the strip's alignment, height, and stretching. The sample stretches Filters and Alerts across the strip. **Alerts tab** calls `activateTab('side', 'alerts')`: it shows that page and persists the active id. The call returns `false` for an invalid container or page. Use `setLayout('split', 'alerts')` to change that page's inner layout, not the tab container itself. `setLayout()` accepts only grid and split; declare a tab container with `layout: 'tabs'` in its widget spec.

[`DragGripOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-interfaces) places a painted grip at the left, center, or right of the card's top edge, inside the header or outside as a tab. The sample chooses the right side inside the header. Click a card to select it: only the selected card shows its grip. Call `focusWidget('revenue')` on the ready handle to select it and move keyboard focus there; the method returns `false` for an unknown id.

To make the entire caption the drag target, call `setDragHandle(true)`; use `false` for the whole card, or a selector string for your own handle element. Static mode paints no grip. These handle switches apply across views.

## See it running

Open the [Fluid dashboard demo](https://grafloria.com/demos/dashboard/fluid-board.html) to try Fit/Grow, Grid/Split, captions, tabs, and drag grips. The [Grid options demo](https://grafloria.com/demos/dashboard/grid-options.html) explores gravity, RTL, responsive columns, and nested boards.

## Related

- [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard): widget content and the initial board.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history): user-facing edits and undo.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents): persist the live document instead of projecting framework data.

<!-- source: synchronize-editors.md -->

# Synchronize editors

Use collaboration when several canvases edit the same document. Pass a shipped transport and a unique actor id through `collab`: dragging a node in one canvas moves it in the other. The engine merges document edits per property; the framework binding mounts the renderer and owns the session lifecycle.

## 1. Choose a transport and seed both peers

Use [`BroadcastChannelTransport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-classes) for tabs on the same browser origin, without a server. Use [`WebSocketTransport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-classes#websockettransport) for editors connected through your server. Each peer needs a different actor id, the same room, and matching initial document ids and content.

Install the binding you use, together with the packages the samples import.

JavaScript:

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
```
Angular:

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

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

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

```bash
npm install @grafloria/vue @grafloria/engine @grafloria/renderer @grafloria/element vue
```
Put this shared file beside your component. The typed [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) arrays draw two connected nodes. Each editor gets its own copy of the seed.

```ts title="shared.ts"
import { BroadcastChannelTransport } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export function seedNodes(): NodeSpec[] {
  return [
    { id: 'a', label: 'Ingest', position: { x: 40, y: 80 },
      size: { width: 140, height: 66 } },
    { id: 'b', label: 'Publish', position: { x: 240, y: 80 },
      size: { width: 140, height: 66 } },
  ];
}

export function seedEdges(): EdgeSpec[] {
  return [{ id: 'e1', source: 'a', target: 'b' }];
}

export function makePeer(room: string, actor: string) {
  return {
    transport: new BroadcastChannelTransport({ name: room, actor }),
    actor,
    presence: true,
  };
}
```

Each sample renders two side-by-side canvases with Ingest connected to Publish and an Undo Ana button. For separate tabs, use a shared document-specific room name instead of generating a new room in each tab, and generate a distinct actor id for each editor.

## 2. Mount the editors and keep actor-local undo

Pass the options through your framework's canvas component. The binding joins at mount and leaves at unmount. In JavaScript, join explicitly after mounting the instance.

Keep the session delivered by the binding's collaboration-ready event. Its [`SyncAdapter`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-classes#syncadapter) exposes the local [`Replica`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-collab). Call `replica.undo()` for collaboration-aware undo: it reverses this actor's edit, not a later edit made by another actor. The Undo Ana button below uses that path.

[`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) returns the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance). [`createSyncSession`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-functions) attaches collaboration to that instance's live model.

[`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent) uses two-way node and edge bindings and emits `collabReady` with the session.

For Qwik, give the two [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) components separate [`GrafloriaCollabOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriacollaboptions) for the same room and retain Ana's session through `onCollabReady$` for actor-local undo; see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for browser-only setup and resumable state.

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) accepts `collab` and calls `onCollabReady`. Keep the session in a ref and use uncontrolled defaults so the instance owns the graph.

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) accepts `:collab` and emits `collab-ready`. Keep the session in a shallow ref.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { createSyncSession } from '@grafloria/engine';
import { makePeer, seedNodes, seedEdges } from './shared';

export function mountEditors(container: HTMLElement): () => void {
  const room = 'editors-' + Math.random().toString(36).slice(2);
  const toolbar = document.createElement('div');
  const undo = document.createElement('button');
  undo.textContent = 'Undo Ana';
  toolbar.append(undo);
  const panes = document.createElement('div');
  panes.style.cssText = 'display:flex;gap:12px;height:400px';
  container.append(toolbar, panes);

  function mount(actor: string) {
    const host = document.createElement('div');
    host.style.cssText = 'flex:1;min-width:0;height:400px';
    host.setAttribute('aria-label', actor);
    panes.append(host);
    const instance = render({ nodes: seedNodes(), edges: seedEdges() }, host);
    const options = makePeer(room, actor);
    const session = createSyncSession(instance.getModel(), options.transport,
      { actor });
    session.join();
    return { instance, session, transport: options.transport };
  }

  const ana = mount('ana');
  const ben = mount('ben');
  undo.onclick = () => { ana.session.replica.undo(); };

  return () => {
    for (const peer of [ana, ben]) {
      peer.session.dispose();
      peer.session.replica.dispose();
      peer.transport.close();
      peer.instance.dispose();
    }
    toolbar.remove();
    panes.remove();
  };
}

const container = document.createElement('div');
document.body.append(container);
const unmountEditors = mountEditors(container);
const close = document.createElement('button');
close.textContent = 'Close editors';
close.onclick = () => { unmountEditors(); container.remove(); close.remove(); };
document.body.append(close);
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { SyncAdapter } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { makePeer, seedNodes, seedEdges } from './shared';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button (click)="undoAna()">Undo Ana</button>
    <div style="display:flex;gap:12px;height:400px">
      <grafloria-diagram-canvas
        [(nodes)]="nodesA" [(edges)]="edgesA" [collab]="collabA"
        (collabReady)="sessionA = $event"
        style="display:block;flex:1;min-width:0;height:400px" />
      <grafloria-diagram-canvas
        [(nodes)]="nodesB" [(edges)]="edgesB" [collab]="collabB"
        style="display:block;flex:1;min-width:0;height:400px" />
    </div>
  `,
})
export class AppComponent {
  private readonly room = 'editors-' + Math.random().toString(36).slice(2);
  nodesA: NodeSpec[] = seedNodes();
  edgesA: EdgeSpec[] = seedEdges();
  nodesB: NodeSpec[] = seedNodes();
  edgesB: EdgeSpec[] = seedEdges();
  readonly collabA = makePeer(this.room, 'ana');
  readonly collabB = makePeer(this.room, 'ben');
  sessionA?: SyncAdapter;
  undoAna(): void { this.sessionA?.replica.undo(); }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, useVisibleTask$,
  type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type GrafloriaCollabOptions } from '@grafloria/qwik';
import type { SyncAdapter } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { makePeer, seedNodes, seedEdges } from './shared';

export default component$(() => {
  const collabA = useSignal<NoSerialize<GrafloriaCollabOptions>>();
  const collabB = useSignal<NoSerialize<GrafloriaCollabOptions>>();
  const sessionA = useSignal<NoSerialize<SyncAdapter>>();
  const nodesA: NodeSpec[] = seedNodes();
  const nodesB: NodeSpec[] = seedNodes();
  const edgesA: EdgeSpec[] = seedEdges();
  const edgesB: EdgeSpec[] = seedEdges();

  useVisibleTask$(() => {
    const room = 'editors-' + Math.random().toString(36).slice(2);
    collabA.value = noSerialize(makePeer(room, 'ana'));
    collabB.value = noSerialize(makePeer(room, 'ben'));
  });

  return <div>
    <button onClick$={() => { sessionA.value?.replica.undo(); }}>Undo Ana</button>
    <div style={{ display: 'flex', gap: '12px', height: '400px' }}>
      {collabA.value && collabB.value && <>
        <GrafloriaFlow defaultNodes={nodesA} defaultEdges={edgesA}
          collab={collabA.value}
          onCollabReady$={(session) => { sessionA.value = noSerialize(session); }}
          style={{ flex: '1', minWidth: '0', height: '400px' }} />
        <GrafloriaFlow defaultNodes={nodesB} defaultEdges={edgesB}
          collab={collabB.value}
          style={{ flex: '1', minWidth: '0', height: '400px' }} />
      </>}
    </div>
  </div>;
});
```
```tsx title="React"
import { useMemo, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { SyncAdapter } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { makePeer, seedNodes, seedEdges } from './shared';

export default function Editors() {
  const sessionA = useRef<SyncAdapter | null>(null);
  const peers = useMemo(() => {
    const room = 'editors-' + Math.random().toString(36).slice(2);
    const nodesA: NodeSpec[] = seedNodes();
    const nodesB: NodeSpec[] = seedNodes();
    const edgesA: EdgeSpec[] = seedEdges();
    const edgesB: EdgeSpec[] = seedEdges();
    return { a: makePeer(room, 'ana'), b: makePeer(room, 'ben'),
      nodesA, nodesB, edgesA, edgesB };
  }, []);

  return <div>
    <button onClick={() => { sessionA.current?.replica.undo(); }}>Undo Ana</button>
    <div style={{ display: 'flex', gap: 12, height: 400 }}>
      <GrafloriaFlow defaultNodes={peers.nodesA} defaultEdges={peers.edgesA}
        collab={peers.a} onCollabReady={(session) => { sessionA.current = session; }}
        style={{ flex: 1, minWidth: 0, height: 400 }} />
      <GrafloriaFlow defaultNodes={peers.nodesB} defaultEdges={peers.edgesB}
        collab={peers.b} style={{ flex: 1, minWidth: 0, height: 400 }} />
    </div>
  </div>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { SyncAdapter } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { makePeer, seedNodes, seedEdges } from './shared';

const room = 'editors-' + Math.random().toString(36).slice(2);
const nodesA: NodeSpec[] = seedNodes();
const nodesB: NodeSpec[] = seedNodes();
const edgesA: EdgeSpec[] = seedEdges();
const edgesB: EdgeSpec[] = seedEdges();
const collabA = makePeer(room, 'ana');
const collabB = makePeer(room, 'ben');
const sessionA = shallowRef<SyncAdapter>();
function ready(session: SyncAdapter): void { sessionA.value = session; }
function undoAna(): void { sessionA.value?.replica.undo(); }
</script>

<template>
  <button @click="undoAna">Undo Ana</button>
  <div style="display:flex;gap:12px;height:400px">
    <GrafloriaFlow :default-nodes="nodesA" :default-edges="edgesA"
      :collab="collabA" @collab-ready="ready"
      style="flex:1;min-width:0;height:400px" />
    <GrafloriaFlow :default-nodes="nodesB" :default-edges="edgesB"
      :collab="collabB" style="flex:1;min-width:0;height:400px" />
  </div>
</template>
```
:::

![The JavaScript sample shows two connected-node canvases, an Undo Ana button, and a Close editors button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/38d64f0f37aa759ee22c479eee3662eb.png)

Angular renders the same pair through two canvas components.

![The Angular sample shows Ingest connected to Publish in each canvas and an Undo Ana button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/a99ef17985d78484ea58cf4f2db98365.png)

Qwik mounts the pair after creating the transports in the browser.

React seeds each flow with its own node and edge arrays.

Vue renders the pair with uncontrolled defaults.

Drag Ingest in Ana's left canvas, then Publish in Ben's right canvas. Both canvases show both moves. Click Undo Ana: it reverses Ana's last captured position write on both peers, while Ben's Publish move stays. These samples do not group drag updates into a replica transaction, so one click does not undo the whole drag. Remote changes do not enter Ana's replica undo stack. If another actor has already superseded Ana's write to the same property, undo skips that write instead of restoring stale state.

For your own multi-mutation action, use `session.replica.transact()` to group its mutations into one local undo step. `undo()` and `redo()` return the operations they emit; those inverse edits travel through the same synchronization path. See [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) for the separate engine command API.

## 3. Handle conflicts and reconnects

The merge unit is a property path, not a whole node. A move and a rename of the same node survive together because position and label are separate registers. Two writes to the same register resolve by Lamport clock, then actor id as the tie-breaker—not by network arrival order. Try the [Conflict resolution demo](https://grafloria.com/demos/collab/conflict-resolution.html) to stage a move and rename before exchanging edits.

Read `transport.status` for the current [`TransportStatus`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-types#transportstatus), and subscribe with `onStatus()` for changes. It reports `connected` or `disconnected`; it is not a document-convergence indicator. A WebSocket session's collaboration-ready callback follows `join()`, not necessarily the socket opening.

`disconnect()` deliberately drops a transport without destroying it. Edits still enter the live replica's log while disconnected. `connect()` reopens the channel; the session listens for the connected transition and exchanges missing operations automatically. Use `close()` only when you no longer need the transport. Reconnect catch-up needs another peer that still holds the history: it is not durable storage.

For a server-backed editor, replace each `makePeer()` call with options containing a WebSocket transport. Use the same room URL for both peers, with different actor ids:

```ts title="socket-peer.ts"
import { WebSocketTransport } from '@grafloria/engine';

export function makeSocketPeer(url: string, actor: string) {
  return {
    transport: new WebSocketTransport({ url }),
    actor,
    presence: true,
  };
}
```

Pass your relay's URL, such as `wss://api.example.com/diagrams/ingest`, as `url`. The relay broadcasts each received frame verbatim to every other socket in that room. Your product owns room membership, authentication and persistence; Grafloria does not ship that server.

An unexpected socket close retries automatically with exponential backoff. A deliberate `disconnect()` does not retry; call `connect()` to return. See the [Offline and reconnect demo](https://grafloria.com/demos/collab/offline-and-reconnect.html) for edits made on both sides of a dropped connection.

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `collab.transport` | [`SyncTransport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-interfaces#synctransport) | Required when collaboration is enabled | Carries messages and connection status. |
| `collab.actor` | `string` | Required when collaboration is enabled | Identifies this peer; keep it unique across peers. |
| `collab.presence` | `boolean` or [`BindPresenceOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presence#bindpresenceoptions) | No binding when omitted | `true` mounts live cursors and remote selection outlines with default settings. |
| Broadcast channel `name` | `string` | Required | Names the shared room; namespace it by document id. |
| WebSocket `url` | `string` | Required | Connects to your relay. |
| WebSocket `reconnect` | `boolean` | Enabled unless `false` | Retries unexpected closes. |
| WebSocket `reconnectBaseMs` | `number` | `250` | Initial retry delay, reset after a successful open. |
| WebSocket `reconnectMaxMs` | `number` | `10000` | Caps the doubling retry delay. |

## Pitfalls

- Keep `collab` stable for the mounted canvas. To change rooms or actors, remount the editor; the binding attaches the session for the instance's lifetime.
- Do not use the same actor id for two peers. Ordering depends on actor identity, and the broadcast transport filters messages from its own actor.
- Start both peers from the same document. Creating the session captures subsequent edits; it does not turn independently seeded content into a shared initial operation history.
- If you switch to controlled React data, wire the change-event return path described in the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start).
- Do not confuse presence with saved document edits. Cursor and selection awareness travels separately and does not enter the operation log.

## Live demos and related pages

- [Two tabs, live](https://grafloria.com/demos/collab/two-tabs-live.html) — drag between two independent editors over a real broadcast channel; [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/collab/two-tabs-live.html).
- [Collaboration-aware undo](https://grafloria.com/demos/interaction/undo-redo.html) — reverse one actor's edit while preserving the other actor's move.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) — persist the live document rather than a framework projection.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) — execute user-facing edits through the engine's command stack.

<!-- source: share-presence-and-comments.md -->

# Share presence and comments

Use presence and anchored comments when people review the same document. Use presentation mode when one person drives the camera and followers must not edit. The examples below show two peers on one browser page: move the pointer in Ana's canvas to see her cursor in Bo's canvas, and open the seeded Review conversation to read and reply. The presentation example shares the camera separately and locks the follower's document.

## 1. Create a room and a conversation

Install the binding you use, together with its peers.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

The shipped [`MemoryHub`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-classes) connects peers in one JavaScript context without a server. One hub represents one room. Give each peer a distinct actor id. A comment viewer identifies the person, not that session: use `commentsViewer` for a canvas-created store, or construct a [`CommentStore`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-comments) with `viewer` yourself.

Put this shared file beside your component. [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) describe the two boxes and their connection. `seedConversation()` writes to the displayed document's store. JavaScript, React, Vue and Qwik show its Review pin; the Angular example shows the conversation panel without canvas pins.

```ts title="room.ts"
import { CommentStore, MemoryHub } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export function nodes(): NodeSpec[] {
  return [
    { id: 'plan', label: 'Plan', position: { x: 30, y: 100 },
      size: { width: 110, height: 60 } },
    { id: 'review', label: 'Review', position: { x: 200, y: 100 },
      size: { width: 110, height: 60 } },
  ];
}

export function edges(): EdgeSpec[] {
  return [{ id: 'plan-review', source: 'plan', target: 'review' }];
}

export function makeRoom() {
  const hub = new MemoryHub();
  return {
    ana: { transport: hub.connect('ana-session'), actor: 'ana-session',
      batch: false, awarenessThrottleMs: 0,
      presence: { name: 'Ana', smoothing: 0 } },
    bo: { transport: hub.connect('bo-session'), actor: 'bo-session',
      batch: false, awarenessThrottleMs: 0,
      presence: { name: 'Bo', smoothing: 0 } },
  };
}

export function seedConversation(store: CommentStore): void {
  const ben = new CommentStore(store.diagram, {
    viewer: 'ben', now: () => Date.now() - 60_000,
  });
  const threadId = ben.createThread(
    { kind: 'node', id: 'review' }, 'Can we tighten the hero copy?',
  );
  store.reply(threadId, 'On it — draft by Friday.');
  ben.dispose();
}
```

`createThread()` returns a thread id; `reply()` returns a message id. Each reply occupies its own register, so concurrent replies do not replace each other. The temporary Ben store authors the opener on the same live document; disposing it removes its subscriptions, not its messages.

## 2. Mount peers, pins and the conversation panel

In React, pass `collab`, `comments` and `commentsViewer` to [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react). Get its store in `onInit` and pass it to [`GrafloriaCommentPanel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriacommentpanel).

In Vue, use [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) with `@init`, and keep the live store in a shallow ref for [`GrafloriaCommentPanel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriacommentpanel).

In Qwik, pass each peer's `collab` and `commentsViewer` to [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik), then seed the Review conversation through the live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance)'s `getCommentStore()` and supply that store to [`GrafloriaCommentPanel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriacommentpanel); see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for browser-side setup and nonserializable state.

In Angular, [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent) has no `commentsViewer` input. Construct a store on the bound engine's document and feed it to [`GrafloriaCommentPanelComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes). Two-way node and edge bindings return edits to your component.

In JavaScript, [`render()`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) mounts each diagram. Join it with [`createSyncSession`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-functions), then use [`bindPresence`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presence) on the live instance. [`CommentPanelView`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-comments) is the shipped DOM panel used by the framework components.

> **Known issue:** Angular's intended `[comments]="anaStore"` binding can leave canvas pins invisible: renderer recreation does not reattach an existing comment overlay. Delaying the binding until after the first render does not reliably restore the pins. Until it is fixed, display the shared conversation through `<grafloria-comment-panel [store]="anaStore" />` without promising canvas pins; the Angular example uses this panel-only fallback.

In Vue, `@init` runs before the sync session joins. Wait for both `@collab-ready` events before seeding the conversation so both peers receive its comment operations.

:::code-group
```ts title="JavaScript"
// main.ts — run in the browser; call unmount when removing this view.
import { render } from '@grafloria/element';
import { createSyncSession } from '@grafloria/engine';
import { bindPresence, CommentPanelView } from '@grafloria/renderer';
import { nodes, edges, makeRoom, seedConversation } from './room';

const root = document.createElement('div');
root.style.cssText = 'display:flex;height:420px';
document.body.append(root);
const room = makeRoom();
function peer(config: typeof room.ana, viewer: string) {
  const host = document.createElement('div');
  host.style.cssText = 'flex:1;min-width:0;height:420px';
  root.append(host);
  const instance = render({ nodes: nodes(), edges: edges() }, host,
    { comments: true, commentsViewer: viewer });
  const session = createSyncSession(instance.getModel(), config.transport, {
    actor: config.actor, batch: false, awarenessThrottleMs: 0,
  });
  session.join();
  const presence = bindPresence(instance, session, config.presence);
  return { instance, session, presence };
}
const ana = peer(room.ana, 'ana');
const bo = peer(room.bo, 'bo');
const store = ana.instance.getCommentStore();
if (!store) throw new Error('Comments are not enabled');
seedConversation(store);
const sidebar = document.createElement('div');
sidebar.style.cssText = 'width:280px;overflow:auto';
root.append(sidebar);
const panel = new CommentPanelView(sidebar, store);
const off = store.onChange(() => panel.update());

export function unmount(): void {
  off();
  panel.dispose();
  for (const peer of [ana, bo]) {
    peer.presence.dispose();
    peer.session.leave();
    peer.session.dispose();
    peer.instance.dispose();
  }
  room.ana.transport.close();
  room.bo.transport.close();
  root.remove();
}
```
```ts title="Angular"
// review.component.ts
import { Component, AfterViewInit, OnDestroy } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaCommentPanelComponent } from '@grafloria/angular';
import { DiagramEngine, CommentStore } from '@grafloria/engine';
import { nodes, edges, makeRoom, seedConversation } from './room';

@Component({
  selector: 'app-review', standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaCommentPanelComponent],
  template: `
    <div style="display:flex;height:420px">
      <grafloria-diagram-canvas [engine]="anaEngine"
        [(nodes)]="anaNodes" [(edges)]="anaEdges"
        [collab]="room.ana"
        style="display:block;flex:1;min-width:0;height:100%" />
      <grafloria-diagram-canvas [engine]="boEngine"
        [(nodes)]="boNodes" [(edges)]="boEdges"
        [collab]="room.bo"
        style="display:block;flex:1;min-width:0;height:100%" />
      <grafloria-comment-panel [store]="anaStore"
        style="width:280px;overflow:auto" />
    </div>`,
})
export class ReviewComponent implements AfterViewInit, OnDestroy {
  readonly room = makeRoom();
  readonly anaEngine = new DiagramEngine();
  readonly boEngine = new DiagramEngine();
  readonly anaStore = new CommentStore(this.anaEngine.createDiagram('Review'), { viewer: 'ana' });
  readonly boStore = new CommentStore(this.boEngine.createDiagram('Review'), { viewer: 'bo' });
  anaNodes = nodes();
  anaEdges = edges();
  boNodes = nodes();
  boEdges = edges();
  ngAfterViewInit(): void { seedConversation(this.anaStore); }
  ngOnDestroy(): void {
    this.anaStore.dispose();
    this.boStore.dispose();
    this.anaEngine.dispose();
    this.boEngine.dispose();
    this.room.ana.transport.close();
    this.room.bo.transport.close();
  }
}
```
```tsx title="Qwik"
// review.tsx
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, GrafloriaCommentPanel } from '@grafloria/qwik';
import type { CommentStore } from '@grafloria/engine';
import { nodes, edges, makeRoom, seedConversation } from './room';

export default component$(() => {
  const room = useSignal<NoSerialize<ReturnType<typeof makeRoom>>>();
  const store = useSignal<NoSerialize<CommentStore>>();
  useVisibleTask$(({ cleanup }) => {
    const live = makeRoom();
    room.value = noSerialize(live);
    cleanup(() => {
      live.ana.transport.close();
      live.bo.transport.close();
    });
  });
  return (
    <div style={{ display: 'flex', height: '420px' }}>
      {room.value && <>
        <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
          collab={noSerialize(room.value.ana)} comments commentsViewer="ana"
          style={{ flex: '1', minWidth: '0', height: '100%' }}
          onInit$={(instance) => {
            const live = instance.getCommentStore();
            if (live) { seedConversation(live); store.value = noSerialize(live); }
          }} />
        <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
          collab={noSerialize(room.value.bo)} comments commentsViewer="bo"
          style={{ flex: '1', minWidth: '0', height: '100%' }} />
      </>}
      {store.value && <div style={{ width: '280px', overflow: 'auto' }}>
        <GrafloriaCommentPanel store={store.value} />
      </div>}
    </div>
  );
});
```
```tsx title="React"
// Review.tsx
import { useEffect, useMemo, useState } from 'react';
import { GrafloriaFlow, GrafloriaCommentPanel } from '@grafloria/react';
import type { CommentStore } from '@grafloria/engine';
import { nodes, edges, makeRoom, seedConversation } from './room';

export default function Review() {
  const room = useMemo(makeRoom, []);
  const [store, setStore] = useState<CommentStore | null>(null);
  useEffect(() => () => {
    room.ana.transport.close();
    room.bo.transport.close();
  }, [room]);
  return (
    <div style={{ display: 'flex', height: 420 }}>
      <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
        collab={room.ana} comments commentsViewer="ana"
        style={{ flex: 1, minWidth: 0, height: '100%' }}
        onInit={(instance) => {
          const live = instance.getCommentStore();
          if (live) { seedConversation(live); setStore(live); }
        }} />
      <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
        collab={room.bo} comments commentsViewer="bo"
        style={{ flex: 1, minWidth: 0, height: '100%' }} />
      {store && <div style={{ width: 280, overflow: 'auto' }}>
        <GrafloriaCommentPanel store={store} />
      </div>}
    </div>
  );
}
```
```vue title="Vue"
<!-- Review.vue -->
<script setup lang="ts">
import { shallowRef, onUnmounted } from 'vue';
import { GrafloriaFlow, GrafloriaCommentPanel } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import type { CommentStore } from '@grafloria/engine';
import { nodes, edges, makeRoom, seedConversation } from './room';

const room = makeRoom();
const anaNodes = nodes(), anaEdges = edges();
const boNodes = nodes(), boEdges = edges();
const store = shallowRef<CommentStore | null>(null);
let joined = 0;
function init(instance: DiagramInstance): void {
  const live = instance.getCommentStore();
  if (live) store.value = live;
}
function collabReady(): void {
  joined += 1;
  if (joined === 2 && store.value) seedConversation(store.value);
}
onUnmounted(() => {
  room.ana.transport.close();
  room.bo.transport.close();
});
</script>

<template>
  <div style="display:flex;height:420px">
    <div style="flex:1;min-width:0">
      <GrafloriaFlow :default-nodes="anaNodes" :default-edges="anaEdges"
        :collab="room.ana" :comments="true" comments-viewer="ana" @init="init"
        @collab-ready="collabReady" />
    </div>
    <div style="flex:1;min-width:0">
      <GrafloriaFlow :default-nodes="boNodes" :default-edges="boEdges"
        :collab="room.bo" :comments="true" comments-viewer="bo"
        @collab-ready="collabReady" />
    </div>
    <div v-if="store" style="width:280px;overflow:auto">
      <GrafloriaCommentPanel :store="store" />
    </div>
  </div>
</template>
```
:::

![The JavaScript review view shows two connected nodes in each pane, Review comment pins and a conversation list with one unread message.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/07cbc05ff164e3d6576c09ca70cc7537.png)

The panel initially lists the Review thread. Select it to open the messages and reply form. Move across either canvas to publish that peer's cursor; leaving the canvas clears it. Select a node to show its remote selection outline. Comments are document data carried by the sync session; read state belongs to each viewer and is not synced. Separate peers use stores over their own synced models, not one store pointing at the other peer's model.

Try the [live cursors demo](https://grafloria.com/demos/collab/live-cursors.html) and the [threaded comments demo](https://grafloria.com/demos/collab/comments.html).

## 3. Follow a presenter and lock the follower

[`presentTo`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation#presentto) broadcasts a host's camera. [`followPresenter`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation#followpresenter) applies its centre and zoom while retaining the follower's canvas size. Both return a handle with `stop()`. Use the shipped [`InMemoryViewportChannel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation#inmemoryviewportchannel) for two canvases on one page.

Call [`lockDocument`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation#lockdocument) on the follower's engine. It drives the engine's mode rather than hiding editing controls: commands, guarded model mutators and document-editing gestures refuse writes. Pan and zoom remain available. Unlock with `lockDocument(engine, false)` when your application ends the read-only session.

This shared controller waits for both mounted hosts. It locks the follower before subscribing, frames the presenter, and keeps both handles for unmount. [`PresentationHost`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation#presentationhost) needs only a viewport and `render()`; a diagram instance already satisfies it. Angular supplies those from its canvas. [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) supplies the document lock.

```ts title="presentation.ts"
import {
  InMemoryViewportChannel, presentTo, followPresenter, lockDocument,
} from '@grafloria/renderer';
import type { PresentationHost } from '@grafloria/renderer';
import type { DiagramEngine } from '@grafloria/engine';

export function makePresentation() {
  const channel = new InMemoryViewportChannel();
  let presenter: PresentationHost | undefined;
  let follower: PresentationHost | undefined;
  let frame: (() => void) | undefined;
  let stops: Array<() => void> = [];
  function wire(): void {
    if (!presenter || !follower || stops.length) return;
    const sending = presentTo(presenter, channel, { presenterId: 'ana' });
    const following = followPresenter(follower, channel, { ignorePresenterId: 'bo' });
    stops = [sending.stop, following.stop];
    frame?.();
  }
  return {
    presenter(host: PresentationHost, fit: () => void): void {
      presenter = host; frame = fit; wire();
    },
    follower(host: PresentationHost, engine: DiagramEngine): void {
      lockDocument(engine, true); follower = host; wire();
    },
    dispose(): void {
      for (const stop of stops) stop();
      channel.dispose();
    },
  };
}
```

Replace the review component with the matching presentation component below. These canvases share only the camera, not document edits: dragging Plan in the presenter does not move the follower's Plan. Pan or zoom the presenter to move the follower's view; try dragging a follower node to see the lock refuse the edit.

> **Known issue:** Angular's canvas-to-camera effect can replace the camera's measured dimensions with the viewport signal's default dimensions, so the follower frames a different region. Until it is fixed, copy each measured camera rectangle into its canvas's `viewport` signal before wiring presentation.

:::code-group
```ts title="JavaScript"
// main.ts — browser entry for presentation mode.
import { render } from '@grafloria/element';
import { nodes, edges } from './room';
import { makePresentation } from './presentation';

const root = document.createElement('div');
root.style.cssText = 'display:flex;height:420px';
document.body.append(root);
function mount(label: string) {
  const pane = document.createElement('div');
  pane.style.cssText = 'flex:1;min-width:0';
  const heading = document.createElement('div');
  heading.textContent = label;
  const host = document.createElement('div');
  host.style.height = '390px';
  pane.append(heading, host);
  root.append(pane);
  return render({ nodes: nodes(), edges: edges() }, host);
}
const presenter = mount('Presenter');
const follower = mount('Follower — read-only');
const presentation = makePresentation();
follower.viewport.syncCanvasSize(follower.container.getBoundingClientRect());
presentation.presenter(presenter, () => {
  presenter.viewport.syncCanvasSize(presenter.container.getBoundingClientRect());
  presenter.fitView(60);
});
presentation.follower(follower, follower.getEngine());
export function unmount(): void {
  presentation.dispose();
  presenter.dispose();
  follower.dispose();
  root.remove();
}
```
```ts title="Angular"
// presentation.component.ts
import { Component, AfterViewInit, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { nodes, edges } from './room';
import { makePresentation } from './presentation';

@Component({
  selector: 'app-presentation', standalone: true, imports: [DiagramCanvasComponent],
  template: `
    <div style="display:flex;height:420px">
      <div style="flex:1;min-width:0">Presenter
        <grafloria-diagram-canvas #a [(nodes)]="nodesA" [(edges)]="edgesA"
          style="display:block;height:390px" />
      </div>
      <div style="flex:1;min-width:0">Follower — read-only
        <grafloria-diagram-canvas #b [(nodes)]="nodesB" [(edges)]="edgesB"
          style="display:block;height:390px" />
      </div>
    </div>`,
})
export class PresentationComponent implements AfterViewInit, OnDestroy {
  readonly a = viewChild.required<DiagramCanvasComponent>('a');
  readonly b = viewChild.required<DiagramCanvasComponent>('b');
  readonly presentation = makePresentation();
  nodesA = nodes(); edgesA = edges();
  nodesB = nodes(); edgesB = edges();
  ngAfterViewInit(): void {
    const a = this.a(), b = this.b();
    const viewportA = a.viewportController(), viewportB = b.viewportController();
    const engineB = b.activeEngine();
    if (!viewportA || !viewportB || !engineB) return;
    // Preserve measured dimensions when the canvas-to-camera effect runs.
    a.viewport.set(viewportA.getViewport());
    b.viewport.set(viewportB.getViewport());
    this.presentation.presenter({ viewport: viewportA, render: () => a.scheduleRender() },
      () => a.fitToContent(60));
    this.presentation.follower({ viewport: viewportB, render: () => b.scheduleRender() }, engineB);
  }
  ngOnDestroy(): void { this.presentation.dispose(); }
}
```
```tsx title="Qwik"
// presentation-view.tsx
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { nodes, edges } from './room';
import { makePresentation } from './presentation';

export default component$(() => {
  const presentation = useSignal<NoSerialize<ReturnType<typeof makePresentation>>>();
  useVisibleTask$(({ cleanup }) => {
    const live = makePresentation();
    presentation.value = noSerialize(live);
    cleanup(() => live.dispose());
  });
  return <div style={{ display: 'flex', height: '420px' }}>
    {presentation.value && <>
      <div style={{ flex: '1', minWidth: '0' }}>Presenter
        <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
          style={{ height: '390px' }}
          onInit$={(instance) => {
            presentation.value?.presenter(instance, () => instance.fitView(60));
          }} />
      </div>
      <div style={{ flex: '1', minWidth: '0' }}>Follower — read-only
        <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
          style={{ height: '390px' }}
          onInit$={(instance) => {
            presentation.value?.follower(instance, instance.getEngine());
          }} />
      </div>
    </>}
  </div>;
});
```
```tsx title="React"
// Presentation.tsx
import { useEffect, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import { nodes, edges } from './room';
import { makePresentation } from './presentation';

export default function Presentation() {
  const presentation = useRef(makePresentation());
  useEffect(() => {
    const live = presentation.current;
    return () => live.dispose();
  }, []);
  return <div style={{ display: 'flex', height: 420 }}>
    <div style={{ flex: 1, minWidth: 0 }}>Presenter
      <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
        style={{ height: 390 }} onInit={(instance) => {
          presentation.current.presenter(instance, () => instance.fitView(60));
        }} />
    </div>
    <div style={{ flex: 1, minWidth: 0 }}>Follower — read-only
      <GrafloriaFlow defaultNodes={nodes()} defaultEdges={edges()}
        style={{ height: 390 }} onInit={(instance) => {
          presentation.current.follower(instance, instance.getEngine());
        }} />
    </div>
  </div>;
}
```
```vue title="Vue"
<!-- Presentation.vue -->
<script setup lang="ts">
import { onUnmounted } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './room';
import { makePresentation } from './presentation';

const presentation = makePresentation();
const nodesA = nodes(), edgesA = edges();
const nodesB = nodes(), edgesB = edges();
function initA(instance: DiagramInstance): void {
  presentation.presenter(instance, () => instance.fitView(60));
}
function initB(instance: DiagramInstance): void {
  presentation.follower(instance, instance.getEngine());
}
onUnmounted(() => presentation.dispose());
</script>
<template>
  <div style="display:flex;height:420px">
    <div style="flex:1;min-width:0">Presenter
      <GrafloriaFlow :default-nodes="nodesA" :default-edges="edgesA"
        style="height:390px" @init="initA" />
    </div>
    <div style="flex:1;min-width:0">Follower — read-only
      <GrafloriaFlow :default-nodes="nodesB" :default-edges="edgesB"
        style="height:390px" @init="initB" />
    </div>
  </div>
</template>
```
:::

![The React presentation view shows Plan connected to Review in both the presenter and read-only follower panes.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/0153fedcdd740f4eebce83778ba85e36.png)

See the [live presentation mode demo](https://grafloria.com/demos/collab/presentation-mode.html) and its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/collab/presentation-mode.html).

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `comments` | `boolean` or `CommentStore` | No store when omitted | Creates a store and pins, or uses your supplied store. Qwik requires a nonserializable store. |
| `commentsViewer` | `string` | `'local'` | Identifies the viewer of a `comments: true` store in JavaScript, React, Vue and Qwik. |
| `collab.presence` | `boolean` or presence options | No presence binding when omitted | Enables live cursors and remote selection outlines. |
| `presence.name` | `string` | Not supplied | Labels your cursor on other peers. |
| `presence.smoothing` | `number` | `0.35` | Sets interpolation; `0` snaps to each received cursor position. |
| `presentTo` options: `throttleMs` | `number` | `50` | Coalesces broadcasts, including a trailing send with the final camera position. |
| `followPresenter` options: `ignorePresenterId` | `string` | Not supplied | Ignores your own presenter id to avoid camera echoes. |
| Panel options: `showResolved` | `boolean` | `false` | Includes resolved threads in the conversation list. |

## Pitfalls and related tasks

- A presence cursor is awareness, not a document edit. It uses a separate DOM overlay; cursor updates do not belong in your node specs.
- Deleting a comment's node leaves an orphaned thread, not a deleted conversation. Use `reanchor(threadId, { kind: 'node', id: 'plan' })` to rescue it onto a live node. Resolving a thread hides it from the default panel; `reopen()` makes it unresolved again.
- Presentation and locking are independent. Following a camera does not lock a document or synchronize its nodes. Keep the explicit lock call for a read-only follower.
- A transport does not supply your product's authentication, rooms or storage. For remote peers and reconnect handling, continue with [Synchronize editors](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/synchronize-editors).
- For persistence, save the live document rather than framework projections: [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents). For user-facing edits and undo, see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

<!-- source: save-and-restore-documents.md -->

# Save and restore documents

Save the live document when you need to reopen an editor without dropping its ports, link routing, groups or kit metadata. The document is the persistence API; a framework's node array is a projection for state binding, not a save format.

The examples render two connected nodes with Save and Restore buttons. Drag a node, save, drag again, then restore: the diagram returns to the saved positions. Restoration mounts the saved models rather than rebuilding them from labels and coordinates.

## 1. Add the shared persistence code

Run the install command for your framework in your own project.

JavaScript:

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

React:

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

Vue:

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

Angular:

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

Qwik:

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

Use [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) for the initial data. Both nodes carry explicit ports so the example exercises more than position restoration.

```ts title="data.ts"
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  {
    id: 'intake', label: 'Intake',
    position: { x: 80, y: 100 }, size: { width: 140, height: 60 },
    ports: [{ id: 'intake-out', side: 'right', type: 'output' }],
    metadata: { domain: 'orders' },
  },
  {
    id: 'review', label: 'Review',
    position: { x: 360, y: 100 }, size: { width: 140, height: 60 },
    ports: [{ id: 'review-in', side: 'left', type: 'input' }],
  },
];
export const edges: EdgeSpec[] = [
  {
    id: 'order', source: 'intake', target: 'review',
    sourceHandle: 'intake-out', targetHandle: 'review-in',
    label: 'Order',
  },
];
```

[`DiagramSerializer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization) serializes a [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance)'s live model. `serializeEnvelope()` adds writer identity, a timestamp and, by default, an integrity checksum. [`fromDocument`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) accepts the envelope, the flat serializer form, or a JSON string of either, and returns a mountable spec.

> **Known issue:** `render(fromDocument(json), host)` does not restore the document's top-level model state or saved camera: the loader passes nodes, links and groups into a newly created model, and the renderer initializes its camera separately. Until it is fixed, attach the loaded model through an engine and pass its saved viewport and zoom explicitly.

> **Known issue:** Renderer pan and zoom do not update the model's serialized viewport. Until it is fixed, copy the instance camera into the model before serializing it.

The shared helper uses [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) only to attach the complete loaded model to the renderer. [`RenderOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#renderoptions) carries that engine and the saved camera. `saveLive()` returns JSON; `reopen()` returns the spec and options for the next mounted instance.

```ts title="persistence.ts"
import { DiagramEngine, DiagramSerializer } from '@grafloria/engine';
import { fromDocument, type RenderOptions } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';

export function saveLive(instance: DiagramInstance): string {
  const camera = instance.viewport.getViewport();
  const model = instance.getModel();
  model.setViewport(
    camera.x, camera.y, camera.width, camera.height,
    instance.viewport.getZoom(),
  );
  return JSON.stringify(new DiagramSerializer().serializeEnvelope(model));
}

export function reopen(json: string) {
  const spec = fromDocument(json);
  const engine = new DiagramEngine();
  engine.setDiagram(spec.model);
  const camera = spec.model.getViewport();
  const options: RenderOptions = {
    engine,
    viewport: { x: camera.x, y: camera.y },
    zoom: camera.zoom,
  };
  return { spec, options };
}
```

## 2. Save and reopen a mounted graph

Restore mounts the loaded spec with its saved engine and camera instead of reseeding node and edge arrays; see [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for framework mounting and instance access.

Copy `data.ts` and `persistence.ts` beside the framework file below. Save stores JSON in browser local storage; Restore mounts a fresh instance from it. Save again after restoration to persist subsequent edits.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

const editor = document.createElement('section');
const save = document.createElement('button');
const restore = document.createElement('button');
const host = document.createElement('div');
save.textContent = 'Save';
restore.textContent = 'Restore';
host.style.height = '400px';
editor.append(save, restore, host);
document.body.append(editor);
let instance = render({ nodes, edges }, host);

save.onclick = () => localStorage.setItem('order-document', saveLive(instance));
restore.onclick = () => {
  const json = localStorage.getItem('order-document');
  if (!json) return;
  const loaded = reopen(json);
  instance.dispose();
  instance = render(loaded.spec, host, loaded.options);
};

// Call when your application removes this editor.
export function unmount() {
  instance.dispose();
  editor.remove();
}
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow, GrafloriaDiagram } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

export default function OrderEditor() {
  const instance = useRef<DiagramInstance | null>(null);
  const [loaded, setLoaded] = useState<ReturnType<typeof reopen> | null>(null);
  const [generation, setGeneration] = useState(0);
  function restore() {
    const json = localStorage.getItem('order-document');
    if (!json) return;
    instance.current = null;
    setLoaded(reopen(json));
    setGeneration((value) => value + 1);
  }
  return (
    <section>
      <button onClick={() => {
        if (instance.current) {
          localStorage.setItem('order-document', saveLive(instance.current));
        }
      }}>Save</button>
      <button onClick={restore}>Restore</button>
      <div style={{ height: 400 }}>
        {loaded ? (
          <GrafloriaDiagram key={generation} spec={loaded.spec} options={loaded.options}
            onReady={(api) => { instance.current = api; }} />
        ) : (
          <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
            onInit={(api) => { instance.current = api; }} />
        )}
      </div>
    </section>
  );
}
```
```vue title="Vue"
<script setup lang="ts">
import { shallowRef, ref } from 'vue';
import { GrafloriaFlow, GrafloriaDiagram } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

const instance = shallowRef<DiagramInstance>();
const loaded = shallowRef<ReturnType<typeof reopen>>();
const generation = ref(0);
function ready(api: DiagramInstance) { instance.value = api; }
function save() {
  if (instance.value) {
    localStorage.setItem('order-document', saveLive(instance.value));
  }
}
function restore() {
  const json = localStorage.getItem('order-document');
  if (!json) return;
  instance.value = undefined;
  loaded.value = reopen(json);
  generation.value++;
}
</script>

<template>
  <section>
    <button @click="save">Save</button>
    <button @click="restore">Restore</button>
    <div style="height:400px">
      <GrafloriaDiagram v-if="loaded" :key="generation"
        :spec="loaded.spec" :options="loaded.options" @ready="ready" />
      <GrafloriaFlow v-else :default-nodes="nodes" :default-edges="edges" @init="ready" />
    </div>
  </section>
</template>
```
```ts title="Angular"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaDiagramComponent } from '@grafloria/angular';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

@Component({
  selector: 'app-order-editor',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaDiagramComponent],
  template: `
    <button (click)="save()">Save</button>
    <button (click)="restore()">Restore</button>
    @if (loaded; as document) {
      <grafloria-diagram [spec]="document.spec" [options]="document.options"
        (ready)="instance = $event" style="display:block;height:400px" />
    } @else {
      <grafloria-diagram-canvas [nodes]="nodes" [edges]="edges"
        style="display:block;height:400px" />
    }
  `,
})
export class OrderEditorComponent {
  readonly canvas = viewChild(DiagramCanvasComponent);
  readonly nodes = nodes;
  readonly edges = edges;
  loaded?: ReturnType<typeof reopen>;
  instance?: DiagramInstance;

  save() {
    if (this.instance) {
      localStorage.setItem('order-document', saveLive(this.instance));
    } else {
      const snapshot = this.canvas()?.snapshot();
      if (snapshot) localStorage.setItem('order-document', JSON.stringify(snapshot));
    }
  }
  restore() {
    const json = localStorage.getItem('order-document');
    if (json) this.loaded = reopen(json);
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, GrafloriaDiagram } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const restoredJson = useSignal('');
  const generation = useSignal(0);
  return (
    <section>
      <button onClick$={() => {
        if (instance.value) {
          localStorage.setItem('order-document', saveLive(instance.value));
        }
      }}>Save</button>
      <button onClick$={() => {
        const json = localStorage.getItem('order-document');
        if (!json) return;
        instance.value = undefined;
        restoredJson.value = json;
        generation.value++;
      }}>Restore</button>
      <div style={{ height: '400px' }}>
        {restoredJson.value ? (
          <GrafloriaDiagram key={generation.value}
            spec$={() => {
              const loaded = reopen(restoredJson.value);
              // Keep the engine and camera inside the browser-built spec.
              return { ...loaded.spec, renderOptions: loaded.options };
            }}
            onReady$={(api: DiagramInstance) => { instance.value = noSerialize(api); }} />
        ) : (
          <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
            onInit$={(api: DiagramInstance) => { instance.value = noSerialize(api); }} />
        )}
      </div>
    </section>
  );
});
```
:::

![JavaScript: Intake connects to Review through an Order edge, with Save and Restore buttons above the canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3b329d7568f29f6374fbc47eb3166057.png)

React renders the same initial graph through its flow component.

![Save and Restore buttons above Intake and Review, connected by an arrow labelled Order.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/87c92b54b79a63ade723be86c9b8204f.png)

Vue renders the initial graph with the same controls.

Angular's initial canvas shows the two nodes and their connection.

Qwik's resumed flow renders the same initial document.

The framework components dispose their owned instances on unmount. JavaScript explicitly disposes the old instance when replacing it and exposes an application unmount function. Qwik builds the restored spec in the browser through `spec$`; see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for resumable kit state.

> **Known issue:** Angular's intended `canvas.loadSnapshot(saved)` path projects nodes and links back to specs and does not restore groups or the viewport. Until it is fixed, take `canvas.snapshot()`, then reopen that snapshot through `fromDocument()` and mount it with `GrafloriaDiagramComponent`, as above.

## 3. Save dashboard state

For a whole-document dashboard save, use the same `saveLive()` and `reopen()` helpers. The loader reconstructs built-in widget painters and board interaction wiring from kit metadata. The restored spec's `handle` is the same [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle) API used by an authored dashboard.

This browser sample uses the shipped [`dashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-functions#dashboard) kit and its KPI and table painters. It renders a revenue card and an orders table. Save, move a widget, and restore to return to the saved cells.

```ts title="dashboard-editor.ts"
import { dashboard, render } from '@grafloria/element';
import { saveLive, reopen } from './persistence';

const editor = document.createElement('section');
const save = document.createElement('button');
const restore = document.createElement('button');
const host = document.createElement('div');
save.textContent = 'Save';
restore.textContent = 'Restore';
host.style.height = '400px';
editor.append(save, restore, host);
document.body.append(editor);

const spec = dashboard({
  columns: 12,
  widgets: [
    { id: 'revenue', kind: 'kpi', span: 4, rows: 1,
      data: { label: 'Revenue', value: '$24,000' } },
    { id: 'orders', kind: 'table', span: 8, rows: 2, title: 'Orders',
      data: { columns: ['Order', 'Status'], rows: [['1042', 'Review']] } },
  ],
});
let instance = render(spec, host);
save.onclick = () => localStorage.setItem('dashboard-document', saveLive(instance));
restore.onclick = () => {
  const json = localStorage.getItem('dashboard-document');
  if (!json) return;
  const loaded = reopen(json);
  instance.dispose();
  instance = render(loaded.spec, host, loaded.options);
};
export function unmount() {
  instance.dispose();
  editor.remove();
}
```

![Save and Restore buttons above a Revenue card showing $24,000 and an Orders table containing order 1042 in Review.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/18a3eb081e6321a7d6e74ce3e7a41e1f.png)

For dashboard-only persistence, `handle.toJSON()` returns a [`DashboardSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types#dashboardsnapshot): live views, widget cells and board options. Feed it back to `dashboard()` rather than to `fromDocument()`. It reads the widest cached column layout, so saving a narrow responsive board retains the authored wide layout. Use whole-document serialization when you also need the model document rather than a board authoring snapshot.

Functions do not survive JSON: re-supply your custom widget painter through `fromDocument(json, { renderWidget })`, or through `dashboard({ ...snapshot, renderWidget })` for a board snapshot. A document-loaded board does not restore runtime responsive configuration; it starts at its saved column count. Reattach application callbacks separately.

## 4. Retain collaborative history and the clock

A snapshot contains document state, not a peer's causal history. Persist the op-log tail and clock alongside it. [`Replica`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-collab#replica) captures local mutations on the mounted model; `history()` returns the operations it knows in total order. On restoration, `startClock` resumes the clock and `adopt()` seeds the log and last-writer-wins stamps without applying operations whose effects are already in the snapshot. Use `receive()` only for operations not yet reflected in the model.

This browser sample renders the same two nodes. Drag before saving to create operations. Restore, then drag again: the new peer's clock advances beyond the saved clock. [`Op`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-collab#op) is the library's operation type; no application copy of that type is needed.

```ts title="collaborative-editor.ts"
import { Replica, type Op } from '@grafloria/engine';
import { render } from '@grafloria/element';
import { nodes, edges } from './data';
import { saveLive, reopen } from './persistence';

const editor = document.createElement('section');
const save = document.createElement('button');
const restore = document.createElement('button');
const readout = document.createElement('output');
const host = document.createElement('div');
save.textContent = 'Save';
restore.textContent = 'Restore';
readout.textContent = 'Drag a node, save, drag again, restore.';
host.style.height = '400px';
editor.append(save, restore, readout, host);
document.body.append(editor);

let instance = render({ nodes, edges }, host);
let peer = new Replica(instance.getModel(), {
  actor: Array.from(crypto.getRandomValues(new Uint32Array(4)), (value) => value.toString(16)).join('-'),
});
let saved: { json: string; tail: Op[]; clock: number } | undefined;

save.onclick = () => {
  const json = saveLive(instance);
  saved = { json, tail: [...peer.history()], clock: peer.clock };
  readout.textContent = `Saved ${saved.tail.length} operations; clock ${saved.clock}.`;
};
restore.onclick = () => {
  if (!saved) return;
  const loaded = reopen(saved.json);
  peer.dispose();
  instance.dispose();
  instance = render(loaded.spec, host, loaded.options);
  const startClock = saved.tail.reduce(
    (maximum, op) => Math.max(maximum, op.clock), saved.clock,
  );
  peer = new Replica(instance.getModel(), {
    actor: Array.from(crypto.getRandomValues(new Uint32Array(4)), (value) => value.toString(16)).join('-'),
    startClock,
    onLocalOp: (op) => {
      readout.textContent = `New edit clock ${op.clock}; saved clock ${startClock}.`;
    },
  });
  peer.adopt(saved.tail);
  readout.textContent = `Restored clock ${peer.clock}. Drag to create a newer operation.`;
};
export function unmount() {
  peer.dispose();
  instance.dispose();
  editor.remove();
}
```

![Intake and Review connected by an Order edge, with Save and Restore buttons and the instruction to drag, save, drag again and restore.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/fcc113d5d57c07951abad542031690c8.png)

For durable storage, persist the three fields in `saved` together. Keep each active peer's actor identity unique. `adopt()` does not advance the clock or rebuild the local undo stack, so retain `clock` explicitly and do not treat restoration as an undo-history restore.

## Options and pitfalls

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `WrapOptions.checksum` | `boolean` | `true` | Adds a checksum to the envelope; loading verifies it and throws on mismatch. |
| `FromDocumentOptions.interactive` | `boolean` | `true` | Reattaches kit interactions. `false` skips kit wiring, not all renderer editing. |
| `FromDocumentOptions.renderWidget` | `FromDocumentOptions['renderWidget']` | Built-in widget painter | Reattaches your dashboard painter. |
| `FromDocumentOptions.renderCustomNode` | `(node: NodeModel, host: HTMLElement) => void` | Kit painter or registered node type | Overrides custom-node painting, including dashboard widgets. |
| `ReplicaOptions.startClock` | `number` | No resume value supplied | Starts capture from your persisted clock. |

The option owners are [`WrapOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization#wrapoptions), [`FromDocumentOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#fromdocumentoptions) and [`ReplicaOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-collab#replicaoptions). The custom-node painter receives a [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel). Use the [dashboard guide](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) for custom widget rendering.

- Do not save a change-event node array or hand-project restored nodes. [`toNodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance#tonodespec) omits ports, general metadata and behavior. Serialize the live model or take a snapshot, then reopen the document.
- When replacing **plain specs** with externally edited data that reuses ids, clear edges, then nodes, before setting the replacement nodes and edges. This forces fresh structure instead of patching the old objects; see [Vue quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-quick-start). The document samples above mount a fresh model instead.
- JSON does not carry arbitrary behavior functions or application renderers. The loader reconstructs recognized kit behavior; supply application-specific painting and callbacks again.
- The model document does not save renderer theme or color-mode settings. These samples restore document data and the camera, not renderer configuration. Retain your application's theme and color-mode settings separately and pass them again in the restored host's renderer options.

> **Known issue:** Saving with `saveLive(instance)` and reopening through `fromDocument()` does not preserve the frozen world positions of relative children whose parent was deleted: deleted-parent anchors are session-local and absent from serialization, so restoration falls back to the child's raw offset. A child frozen at (230, 140) with offset (30, 40) reopens at (30, 40). Until it is fixed, retain or restore the parent before saving if you need to preserve those positions.

## Live demos and related guides

- [Save and restore demo](https://grafloria.com/demos/interaction/save-and-restore.html) — snapshot, op-log tail and clock resumption. [Source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/interaction/save-and-restore.html).
- [Dashboard builder demo](https://grafloria.com/demos/dashboard/dashboard-builder.html) — live widget cells and board persistence.
- [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) — shared documents and kit wiring.
- [Synchronize editors](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/synchronize-editors) — connect peers after restoration.
- [Import diagram text and files](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/import-diagram-text-and-files) — the text-format alternative.

<!-- source: import-diagram-text-and-files.md -->

# Import diagram text and files

Use diagram text when you want a file you can review in git and a canvas you can edit by dragging. Load Mermaid into a mounted instance, export the edited document with its sidecar, or import an existing draw.io file. The examples below show Plan → Build → Ship beside an editable text pane.

The text body is Mermaid-compatible. The `%%grafloria:document` comment carries the document data that Mermaid cannot express, and `%%grafloria:body-hash` detects edits to the body. Mermaid consumers ignore these comments; Grafloria reads them back.

## 1. Install the binding you use

Run the matching command in your browser application's project.

For JavaScript:

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

For Angular:

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

For Qwik:

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

For React:

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

For Vue:

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

## 2. Share the data and import helpers

Use [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) for the initial data. Keep the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance) as the editing surface: `exportText()` returns a string, and `loadText()` reconciles text into its live model.

[`importDrawio`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core-functions) accepts plain `<mxGraphModel>` XML and compressed or uncompressed `<mxfile>` documents. [`exportDiagramText`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization) converts its imported model to sidecar-carrying text. Loading that text uses the same instance API as the Mermaid editor, without projecting away ports, groups or styles.

Save this file alongside your component or entry point. The helpers return status text for your UI; they do not print a service response or replace the mounted canvas.

```ts title="diagram-text.ts"
import type { DiagramInstance, NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { importDrawio, exportDiagramText } from '@grafloria/engine';

export const nodes: NodeSpec[] = [
  { id: 'plan', label: 'Plan', position: { x: 40, y: 80 }, size: { width: 140, height: 60 } },
  { id: 'build', label: 'Build', position: { x: 260, y: 80 }, size: { width: 140, height: 60 } },
  { id: 'ship', label: 'Ship', position: { x: 480, y: 80 }, size: { width: 140, height: 60 } },
];
export const edges: EdgeSpec[] = [
  { id: 'e1', source: 'plan', target: 'build' },
  { id: 'e2', source: 'build', target: 'ship' },
];

export function applyText(api: DiagramInstance, text: string): string {
  try {
    const result = api.loadText(text);
    api.renderNow();
    api.fitView(40);
    return result.source === 'sidecar'
      ? 'Loaded the document sidecar'
      : result.sidecarMerged
        ? 'Applied the body edit onto the sidecar document'
        : 'Parsed Mermaid text';
  } catch (error) {
    return error instanceof Error ? error.message : 'Text import failed';
  }
}

export async function applyDrawio(api: DiagramInstance, text: string): Promise<string> {
  const result = await importDrawio(text);
  if (!result.diagram) return result.error ?? 'No readable first page';
  const status = applyText(api, exportDiagramText(result.diagram));
  return [status, ...result.warnings].join('\n');
}
```

## 3. Mount the editor

Choose one binding. Each editor exports its initial canvas into the textarea. Edit `build[Build]` to `build[Verify]`, keeping the sidecar comments, then press **Load Mermaid**: the middle box reads Verify and the surviving nodes retain their sidecar geometry. Press **Export** after dragging a node to capture its new arrangement. Paste XML, or choose a `.drawio` file, then press **Import draw.io** to replace the canvas content with the first imported page.

These editors add a text snapshot and explicit export and import actions to the JavaScript [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core), React [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react), Vue [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) and Qwik [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) mounts; see [group and nest nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/group-and-nest-nodes) for mounting and instance storage.

Angular exposes [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent). Its text loader differs from the renderer instance's loader:

> **Known issue:** Angular's `loadText(text)` applies parser output without rejecting unsupported or erroneous bodies, and does not adopt diagram-level grammar metadata or replace existing groups. Until it is fixed, validate with `importDiagramText()` and replace the canvas's active diagram with the parsed model.

The intended Angular call is `this.canvas().loadText(this.text)`. The Angular tab implements the workaround with [`importDiagramText`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization) and [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine), so an invalid import leaves the current diagram intact and a non-flowchart retains its export grammar. It explicitly schedules a repaint after loading.

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, applyText, applyDrawio } from './diagram-text';

const root = document.createElement('section');
document.body.append(root);
const host = document.createElement('div');
host.style.height = '400px';
const source = document.createElement('textarea');
source.rows = 10;
source.style.width = '100%';
const status = document.createElement('pre');
const file = document.createElement('input');
file.type = 'file';
file.accept = '.drawio,.xml';
const exportButton = document.createElement('button');
exportButton.textContent = 'Export';
const loadButton = document.createElement('button');
loadButton.textContent = 'Load Mermaid';
const drawioButton = document.createElement('button');
drawioButton.textContent = 'Import draw.io';
root.append(host, source, exportButton, loadButton, file, drawioButton, status);
const api = render({ nodes, edges }, host);
api.renderNow();
api.fitView(40);
source.value = api.exportText();
exportButton.onclick = () => { source.value = api.exportText(); };
loadButton.onclick = () => { status.textContent = applyText(api, source.value); };
file.onchange = async () => {
  const selected = file.files?.[0];
  if (selected) source.value = await selected.text();
};
drawioButton.onclick = async () => {
  status.textContent = await applyDrawio(api, source.value);
};

// Call this when your application removes this editor.
export function unmountEditor(): void {
  api.dispose();
  root.remove();
}
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { DiagramEngine, importDiagramText, importDrawio } from '@grafloria/engine';
import { nodes, edges } from './diagram-text';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DiagramCanvasComponent, FormsModule],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:400px" />
    <textarea [(ngModel)]="text" rows="10" style="width:100%"></textarea>
    <button (click)="exportText()">Export</button>
    <button (click)="load()">Load Mermaid</button>
    <input #file type="file" accept=".drawio,.xml" (change)="readFile(file)" />
    <button (click)="drawio()">Import draw.io</button>
    <pre>{{ status }}</pre>
  `,
})
export class AppComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes = nodes;
  edges = edges;
  text = '';
  status = '';
  ngAfterViewInit(): void { this.exportText(); }
  exportText(): void { this.text = this.canvas().exportText(); }
  load(): void {
    if (!this.text.trim()) { this.status = 'Enter diagram text'; return; }
    try {
      const result = importDiagramText(this.text);
      if (result.unsupported || result.errors?.length) {
        this.status = result.unsupported ?? result.errors?.join('\n') ?? 'Unreadable text';
        return;
      }
      const engine: DiagramEngine | undefined = this.canvas().activeEngine();
      if (!engine) { this.status = 'Canvas is not ready'; return; }
      engine.setDiagram(result.diagram);
      this.canvas().scheduleRender();
      this.status = result.sidecarMerged ? 'Applied the body edit onto the sidecar document' : `Loaded from ${result.source}`;
    } catch (error) {
      this.status = error instanceof Error ? error.message : 'Text import failed';
    }
  }
  async readFile(input: HTMLInputElement): Promise<void> {
    const selected = input.files?.[0];
    if (selected) this.text = await selected.text();
  }
  async drawio(): Promise<void> {
    const result = await importDrawio(this.text);
    if (!result.diagram) { this.status = result.error ?? 'No readable first page'; return; }
    const engine: DiagramEngine | undefined = this.canvas().activeEngine();
    if (!engine) { this.status = 'Canvas is not ready'; return; }
    engine.setDiagram(result.diagram);
    this.canvas().scheduleRender();
    this.status = ['Imported first page', ...result.warnings].join('\n');
  }
}
```
```tsx title="Qwik"
import { component$, $, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, applyText, applyDrawio } from './diagram-text';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const text = useSignal('');
  const status = useSignal('');
  return <section>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView
      style={{ height: '400px' }} onInit$={$((api: DiagramInstance) => {
        instance.value = noSerialize(api);
        text.value = api.exportText();
      })} />
    <textarea rows={10} style={{ width: '100%' }} value={text.value}
      onInput$={(_, el) => { text.value = el.value; }} />
    <button onClick$={() => { if (instance.value) text.value = instance.value.exportText(); }}>Export</button>
    <button onClick$={() => { if (instance.value) status.value = applyText(instance.value, text.value); }}>Load Mermaid</button>
    <input type="file" accept=".drawio,.xml" onChange$={async (_, el) => {
      const selected = el.files?.[0];
      if (selected) text.value = await selected.text();
    }} />
    <button onClick$={async () => {
      if (instance.value) status.value = await applyDrawio(instance.value, text.value);
    }}>Import draw.io</button>
    <pre>{status.value}</pre>
  </section>;
});
```
```tsx title="React"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, applyText, applyDrawio } from './diagram-text';

export default function App() {
  const instance = useRef<DiagramInstance | null>(null);
  const [text, setText] = useState('');
  const [status, setStatus] = useState('');
  return <section>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} fitView
      style={{ height: 400 }} onInit={(api) => {
        instance.current = api;
        setText(api.exportText());
      }} />
    <textarea rows={10} style={{ width: '100%' }} value={text}
      onChange={(event) => setText(event.target.value)} />
    <button onClick={() => { if (instance.current) setText(instance.current.exportText()); }}>Export</button>
    <button onClick={() => { if (instance.current) setStatus(applyText(instance.current, text)); }}>Load Mermaid</button>
    <input type="file" accept=".drawio,.xml" onChange={async (event) => {
      const selected = event.target.files?.[0];
      if (selected) setText(await selected.text());
    }} />
    <button onClick={async () => {
      if (instance.current) setStatus(await applyDrawio(instance.current, text));
    }}>Import draw.io</button>
    <pre>{status}</pre>
  </section>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges, applyText, applyDrawio } from './diagram-text';

const instance = shallowRef<DiagramInstance>();
const text = ref('');
const status = ref('');
function onInit(api: DiagramInstance): void {
  instance.value = api;
  text.value = api.exportText();
}
function exportText(): void { if (instance.value) text.value = instance.value.exportText(); }
function load(): void { if (instance.value) status.value = applyText(instance.value, text.value); }
async function readFile(event: Event): Promise<void> {
  const input = event.target;
  if (!(input instanceof HTMLInputElement)) return;
  const selected = input.files?.[0];
  if (selected) text.value = await selected.text();
}
async function drawio(): Promise<void> {
  if (instance.value) status.value = await applyDrawio(instance.value, text.value);
}
</script>

<template>
  <section>
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" fit-view
      style="height:400px" @init="onInit" />
    <textarea v-model="text" rows="10" style="width:100%"></textarea>
    <button @click="exportText">Export</button>
    <button @click="load">Load Mermaid</button>
    <input type="file" accept=".drawio,.xml" @change="readFile" />
    <button @click="drawio">Import draw.io</button>
    <pre>{{ status }}</pre>
  </section>
</template>
```
:::

The text pane is an explicit snapshot, not an automatic mirror of every canvas gesture. Press **Export** to refresh it. The framework components own their canvas teardown; the JavaScript sample exposes an unmount function for its host application.

![The JavaScript editor shows Plan → Build → Ship above the exported Mermaid text, with Export, Load Mermaid, file selection and Import draw.io controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e3eb0dc99afa24f8165e8a4eee00f91a.png)

The Angular editor starts with the same nodes and exported text.

![The Angular editor shows Plan → Build → Ship above its text pane and import controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ae543c8f3cf76318ceee0588dce52713.png)

The Qwik editor holds the text as serializable state beside its live instance.

![The Qwik editor shows the three connected boxes, exported Mermaid text and import controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c62e49925079a46f09490beb12c0d7c7.png)

The React editor exposes the same explicit export and load workflow.

![The React editor shows Plan → Build → Ship, its text pane and the Export, Load Mermaid and Import draw.io controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e0ecddb89972cc2d9feaa487481e201b.png)

The Vue editor also starts with the exported body and document sidecar in its textarea.

![The Vue editor shows the three connected boxes above the Mermaid text and file import controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9a4173b54aead99ebcfa59a476c90bce.png)

Try the [live Mermaid round-trip editor](https://grafloria.com/demos/misc/mermaid-text.html) or the [draw.io importer](https://grafloria.com/demos/misc/drawio-import.html).

## 4. Compose architecture text

Paste this source into any editor above and press **Load Mermaid**. Cloud becomes a region containing Web app and API. The sided line exits Web app on the right and enters API on the left; Grafloria uses those sides to arrange the services. No custom layout plug-in is needed.

```mermaid
architecture-beta
  group cloud(cloud)[Cloud]
  service web(server)[Web app] in cloud
  service api(server)[API] in cloud
  web:R -[HTTPS]-> L:api
```

For a row-and-column composition, paste this instead. `columns 3` defines the grid, `:3` spans a row, and `space` leaves a hole.

```mermaid
block-beta
  columns 3
  title["Application"]:3
  web["Web app"] space api["API"]
  db[("Database")]:3
  web --> api
  api --> db
```

Press **Export** to obtain text in the diagram's grammar, then **Load Mermaid** to read that exported text back. See the [live architecture and block demo](https://grafloria.com/demos/diagrams/mermaid-architecture-block.html) for nested regions and layered grids.

## Supported text and import results

The text format reads and writes these families:

| Header | Use it for |
| --- | --- |
| `flowchart`, `graph` | Nodes, labeled edges and subgraphs |
| `erDiagram` | Entities and relationships |
| `classDiagram` | Classes and relationships |
| `stateDiagram`, `stateDiagram-v2` | States and transitions |
| `architecture-beta` | Services, regions and sided lines |
| `block-beta` | Grids, spans, spaces and nested blocks |

The parser returns an [`ImportTextResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization). Inspect `source` to distinguish a sidecar load from a body parse, `bodyEdited` for a hash mismatch, and `sidecarMerged` for an edit applied onto the sidecar base. `sidecarInvalid` identifies a sidecar whose JSON cannot be parsed. `unsupported` names a recognized but unsupported type, such as `sequenceDiagram`; `errors` lists parser diagnostics with line information.

Standalone `importDiagramText()` is best effort: readable lines can produce a partial model. The renderer instance's `loadText()` rejects empty text, unsupported types and body parse errors before changing the canvas. The sample catches that error and displays its message. Angular needs the validation workaround above.

For draw.io, show `warnings` even when a diagram imports successfully: each warning names a dropped or approximated construct. Unreadable input returns `error`, not a thrown exception. Multi-page files expose `pages`; each page has its own `name`, `diagram`, `warnings` and optional `error`. The samples display the first page. For a page picker, select a readable entry from `pages` and load `exportDiagramText(page.diagram)` through the same helper; a corrupt later page does not invalidate the other pages.

## Options and round-trip boundaries

Pass these options to the instance's text methods, or to the corresponding engine text functions:

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `exportText({ lossless })` | `boolean` | `true` | Includes the document sidecar and body hash; `false` returns only the Mermaid body. |
| `exportText({ positions })` | `boolean` | `false` | Writes readable `%%grafloria:at` comments for exact node and zone positions and sizes. |
| `loadText(text, { prefer })` | `'auto' \| 'sidecar' \| 'text'` | `'auto'` | Uses the sidecar unless the body hash detects an edit; `'sidecar'` ignores body edits; `'text'` ignores the sidecar. |

Keep both sidecar comments for a document round trip. In automatic mode, a body edit changes structure, labels and shapes on the sidecar base; surviving nodes retain their geometry, styles and ports. Forcing `'text'`, or exporting with `lossless: false`, crosses the best-effort boundary: pure Mermaid does not carry all data bags, port geometry, group nesting or viewport data.

“Lossless” refers to document content, not the viewing session. Text export strips node/link selection, hover and focus state and derived routed link points; manual waypoints remain. The renderer instance's `loadText()` reconciles content and grammar metadata, but does not restore the sidecar's camera into the mounted viewport. The JavaScript, React, Vue and Qwik editors deliberately frame the imported content with `fitView(40)` instead.

> **Known issue:** The renderer instance's `loadText()` does not transfer saved comment threads or non-grammar diagram-level metadata into the mounted model, even though the sidecar and the imported model contain them. Until it is fixed, use the shared saved-document workflow rather than this text loader for documents that need those fields preserved.

The intended round trip is `api.loadText(api.exportText())`. In the current renderer, that call transfers nodes, links, groups, strokes and only the listed grammar metadata keys; it does not replace arbitrary diagram metadata or restore saved comments. These text editors therefore do not provide a complete document round trip for comment-bearing or application-metadata-bearing diagrams. Use [save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for those diagrams.

draw.io is an import-only format here. Export the migrated canvas as Grafloria text or a [shared saved document](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents), not as a `.drawio` file. For document loading into a new mount, use [`fromDocument`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core), which restores models and supplies the mounted wiring for groups and kits. Avoid hand-projecting an imported model to a short node/edge tuple; see [save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

## Related

- [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram) — rearrange a larger imported graph.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history) — distinguish document loading from undoable user edits.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) — configure the imported canvas's appearance and sizing.
- [Mermaid viewer](https://grafloria.com/demos/misc/mermaid-viewer.html) — try the supported diagram families.

<!-- source: export-images-and-documents.md -->

# Export images and documents

Use export for a downloadable picture of your live diagram, a vector PDF for printing, or an SVG/PNG that also carries the editable document. Exports render the scene graph, not a screenshot: the default includes content outside the camera.

## 1. Add download controls after paint

Use [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance) for browser exports. `export('svg')` returns raw SVG source; PNG, JPEG, WebP and PDF return data URLs. PDF keeps paths as paths and labels as selectable text.

The following samples draw **Author → Review**, with three download buttons. Click a button to download that format; the status beside the buttons identifies the requested format while export runs. Look for `diagram.png` in your browser's downloads to confirm the PNG download. The PNG uses 2× scale. SVG and PNG include the editable model.

Create these two shared files in your browser project. The data uses the library's [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) types. The download helper accepts the instance method's own type and passes [`ExportOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-exportoptions) through unchanged.

```ts title="diagram-data.ts"
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'author', label: 'Author', position: { x: 40, y: 80 },
    size: { width: 150, height: 66 }, style: { fill: '#dbeafe', stroke: '#2563eb' } },
  { id: 'review', label: 'Review', position: { x: 300, y: 80 },
    size: { width: 150, height: 66 }, style: { fill: '#dcfce7', stroke: '#16a34a' } },
];
export const edges: EdgeSpec[] = [
  { id: 'review-link', source: 'author', target: 'review' },
];
```

```ts title="download.ts"
import type { DiagramInstance, ExportFormat, ExportOptions } from '@grafloria/renderer';

export async function downloadDiagram(
  exportImage: DiagramInstance['export'],
  format: ExportFormat,
): Promise<string> {
  const options: ExportOptions = {
    scale: format === 'png' ? 2 : 1,
    embedModel: format === 'svg' || format === 'png',
    embedModelCreatedAt: '2026-01-01T00:00:00Z',
    onWarnings: (warnings) => {
      if (warnings.length) console.warn('Export fidelity:', warnings);
    },
  };
  const artifact = await exportImage(format, options);
  const a = document.createElement('a');
  a.href = format === 'svg'
    ? 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(artifact)
    : artifact;
  a.download = `diagram.${format}`;
  a.click();
  return `Download requested: diagram.${format}`;
}
```

[`ExportFormat`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-types) also accepts `'jpeg'` and `'webp'`. Run the helper in the browser, where the anchor and default raster backend are available.

### JavaScript

Install the packages, then use [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) in your browser entry. Export from the buttons after the mounted diagram appears.

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

```ts title="main.ts"
import { render } from '@grafloria/element';
import type { ExportFormat } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';
import { downloadDiagram } from './download';

const toolbar = document.createElement('div');
const status = document.createElement('span');
const host = document.createElement('div');
host.style.height = '400px';
document.body.append(toolbar, host);
const instance = render({ nodes, edges }, host);
const formats: ExportFormat[] = ['svg', 'png', 'pdf'];
for (const format of formats) {
  const button = document.createElement('button');
  button.textContent = `Download ${format.toUpperCase()}`;
  button.onclick = async () => {
    status.textContent = `Exporting diagram.${format}`;
    try {
      status.textContent = await downloadDiagram(instance.export, format);
    } catch (error) {
      status.textContent = error instanceof Error ? error.message : String(error);
    }
  };
  toolbar.append(button);
}
toolbar.append(status);
```

![Author connects to Review below the SVG, PNG and PDF download buttons.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/a7d9cc7e573617152fc3bffabd574843.png)

When your application removes this view, call `instance.dispose()` from its teardown handler; keep the instance alive while the view remains mounted.

### React

Render [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react) and hold the ready instance in a ref, following the download demo.

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

```tsx title="ExportDiagram.tsx"
import { useRef, useState } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance, ExportFormat } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';
import { downloadDiagram } from './download';

export default function ExportDiagram() {
  const instance = useRef<DiagramInstance | null>(null);
  const [ready, setReady] = useState(false);
  const [status, setStatus] = useState('');
  async function save(format: ExportFormat) {
    if (!instance.current) return;
    setStatus(`Exporting diagram.${format}`);
    try {
      setStatus(await downloadDiagram(instance.current.export, format));
    } catch (error) {
      setStatus(error instanceof Error ? error.message : String(error));
    }
  }
  return <div>
    <button disabled={!ready} onClick={() => save('svg')}>Download SVG</button>
    <button disabled={!ready} onClick={() => save('png')}>Download PNG</button>
    <button disabled={!ready} onClick={() => save('pdf')}>Download PDF</button>
    <span>{status}</span>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
      style={{ height: '400px' }} onInit={(api) => {
        instance.current = api;
        setReady(true);
      }} />
  </div>;
}
```

The React view shows Author connected to Review and three download buttons.

### Vue

Use [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue)'s `init` event and keep the instance in a shallow ref. The buttons become available after the synchronous paint.

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

```vue title="ExportDiagram.vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, ExportFormat } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';
import { downloadDiagram } from './download';

const instance = shallowRef<DiagramInstance | null>(null);
const status = ref('');
function onInit(api: DiagramInstance) {
  api.renderNow();
  instance.value = api;
}
async function save(format: ExportFormat) {
  if (!instance.value) return;
  status.value = `Exporting diagram.${format}`;
  try {
    status.value = await downloadDiagram(instance.value.export, format);
  } catch (error) {
    status.value = error instanceof Error ? error.message : String(error);
  }
}
</script>

<template>
  <button :disabled="!instance" @click="save('svg')">Download SVG</button>
  <button :disabled="!instance" @click="save('png')">Download PNG</button>
  <button :disabled="!instance" @click="save('pdf')">Download PDF</button>
  <span>{{ status }}</span>
  <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
    style="height:400px" @init="onInit" />
</template>
```

The Vue view shows the blue Author node, green Review node and three download buttons.

### Angular

Use [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent)'s `exportDiagram()` method. This component exposes the same async export pipeline without requiring a renderer instance.

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

```ts title="export-diagram.component.ts"
import { Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec, ExportFormat } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';
import { downloadDiagram } from './download';

@Component({
  selector: 'app-export-diagram',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button (click)="save('svg')">Download SVG</button>
    <button (click)="save('png')">Download PNG</button>
    <button (click)="save('pdf')">Download PDF</button>
    <span>{{ status }}</span>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:400px" />
  `,
})
export class ExportDiagramComponent {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  status = '';
  async save(format: ExportFormat) {
    this.status = `Exporting diagram.${format}`;
    try {
      this.status = await downloadDiagram(
        (f, options) => this.canvas().exportDiagram(f, options), format,
      );
    } catch (error) {
      this.status = error instanceof Error ? error.message : String(error);
    }
  }
}
```

The Angular canvas shows Author connected to Review below three download buttons.

Export from the button after the canvas appears, not during component construction. An unavailable renderer throws “the canvas has not rendered yet”.

### Qwik

Render [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik), and store the ready instance with `noSerialize()`. The plain specs remain serializable; the live renderer does not enter resumable state.

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

```tsx title="export-diagram.tsx"
import { component$, $, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import type { DiagramInstance, ExportFormat } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';
import { downloadDiagram } from './download';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const status = useSignal('');
  const save = $(async (format: ExportFormat) => {
    if (!instance.value) return;
    status.value = `Exporting diagram.${format}`;
    try {
      status.value = await downloadDiagram(instance.value.export, format);
    } catch (error) {
      status.value = error instanceof Error ? error.message : String(error);
    }
  });
  return <div>
    <button disabled={!instance.value} onClick$={() => save('svg')}>Download SVG</button>
    <button disabled={!instance.value} onClick$={() => save('png')}>Download PNG</button>
    <button disabled={!instance.value} onClick$={() => save('pdf')}>Download PDF</button>
    <span>{status.value}</span>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
      style={{ height: '400px' }} onInit$={$((api: DiagramInstance) => {
        api.renderNow();
        instance.value = noSerialize(api);
      })} />
  </div>;
});
```

The Qwik view shows Author connected to Review with SVG, PNG and PDF download controls.

See the live [download image demo](https://grafloria.com/demos/misc/download-image.html) and [vector PDF demo](https://grafloria.com/demos/misc/pdf-export.html).

## 2. Reopen an embedded-model artifact

Pass `embedModel: true` when exporting SVG or PNG. SVG stores the document in `<metadata>`; PNG stores it in an `iTXt` chunk. [`importDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s) returns a live model, or `null` for an image with no embedded model. It uses the engine's deserializer, including checksum verification and migrations. [`extractModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s) returns the embedded envelope without mounting it.

This browser sample exports a painted diagram and restores its nodes, links and groups into a second mounted canvas. Drag a node in the second canvas to edit the reopened data. It passes those entities as live models rather than projecting them into specs. This mounting recipe does not transfer whiteboard strokes, comments, diagram-level metadata or the saved viewport, although the imported model retains them. Use the full-document restoration path in [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for documents containing those fields.

```ts title="reopen.ts"
import { render } from '@grafloria/element';
import { importDiagram, extractModel } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';

async function reopen() {
  const originalHost = document.createElement('div');
  const reopenedHost = document.createElement('div');
  originalHost.style.height = '250px';
  reopenedHost.style.height = '250px';
  document.body.append(originalHost, reopenedHost);
  const original = render({ nodes, edges }, originalHost);
  const svg = await original.export('svg', {
    embedModel: true, embedModelCreatedAt: '2026-01-01T00:00:00Z',
  });
  const envelope = extractModel(svg);
  const model = importDiagram(svg);
  if (!envelope || !model) throw new Error('No embedded model');
  const reopened = render({}, reopenedHost);
  reopened.setNodes(model.getNodes());
  reopened.setEdges(model.getLinks());
  reopened.setGroups(model.getGroups());
}
void reopen();
```

![The original and reopened canvases each show Author connected to Review, stacked vertically.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6e73b320d46ae1ef142c22c340d491ae.png)

The import functions also accept PNG bytes (`Uint8Array`) and exported data URLs. Handle an import exception as a damaged artifact, not as an empty document. Embedding does not make JPEG, WebP or PDF editable through this import path. For complete document persistence, including the saved viewport, see [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

See the live [editable round-trip demo](https://grafloria.com/demos/misc/editable-round-trip.html).

## 3. Scope a dashboard to its active view

Dashboard tabs park inactive views off-camera, but the default export frames the whole model. On your mounted dashboard, pass `includeIds: handle.exportIds()` to `instance.export('pdf', options)`; in Angular, pass the same options to `canvas.exportDiagram('pdf', options)`.

`exportIds()` supplies the active view's group and its widgets, including nested containers and their descendants. Read it at export time, after any view switch. This avoids exporting the large empty gap between parked views. Use `exportIds(viewId)` to name a particular view instead. See [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) for obtaining the dashboard handle.

For a camera slice rather than a view's entities, pass `scope: 'viewport'` **and** an explicit world-space `viewport` rectangle. For the live selection, pass `scope: 'selection'`; it overrides `includeIds`.

## 4. Produce server SVG and PNG

Use [`renderStatic`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core) for the headless path. It delegates to [`renderToStaticSVG`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core) and returns SVG, CSS, layer markup and a hydration snapshot. Specify width and height rather than relying on the 800×600 defaults. Identical specs and options produce deterministic SVG and CSS.

The static SVG needs the returned CSS as well as `standalone: true`. Fold that stylesheet into the file, as the server export demo does. Custom HTML-layer components are not server-rendered by this path.

For Node raster output, use the shipped [`createSharpBackend`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s). This step goes below the browser instance because the server has no mounted canvas or browser SVG rasterizer. Sharp accepts SVG bytes; its adapter returns a data URL. Install the native package only in your server project.

```bash
npm install @grafloria/element @grafloria/renderer @grafloria/engine sharp
npm install --save-dev tsx typescript @types/node
```

```ts title="server-export.ts"
import { writeFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';
import sharp from 'sharp';
import { renderStatic } from '@grafloria/element';
import { createSharpBackend } from '@grafloria/renderer';
import { nodes, edges } from './diagram-data';

async function exportFiles() {
  const width = 520;
  const height = 300;
  const result = renderStatic({ nodes, edges, width, height, standalone: true });
  const svg = result.svg.replace(/^(<svg[^>]*>)/, `$1<style>${result.css}</style>`);
  await writeFile('diagram.svg', svg, 'utf8');
  const png = await createSharpBackend(sharp).rasterize({
    svg, width, height, mimeType: 'image/png',
  });
  const payload = png.slice(png.indexOf(',') + 1);
  await writeFile('diagram.png', Buffer.from(payload, 'base64'));
}
void exportFiles();
```

```bash
npx tsx server-export.ts
```

Open `diagram.svg` or `diagram.png`: both show Author connected to Review in a 520×300 image. Keep specs, options, fonts and rasterizer versions fixed when you need reproducible raster bytes; deterministic SVG alone does not pin an external encoder's environment.

The shipped [`createResvgBackend`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s) accepts the `@resvg/resvg-js` module and encodes PNG only; it rejects JPEG and WebP. Sharp supports all three raster formats. In the browser, exports default to [`createDomRasterBackend`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s), so you do not need either native package there.

See the live [server-side export demo](https://grafloria.com/demos/misc/server-side-export.html).

## Options and fidelity

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `scale` | `number` | `1` | Multiplies intrinsic output size without changing the world-space picture. |
| `quality` | `number` | `0.92` | Sets JPEG/WebP encoder quality, from 0 to 1. |
| `backgroundColor` | `string` | Transparent; JPEG uses white | Paints the export backdrop. |
| `padding` | `number` | `20` | Adds world-space margin around content; ignored with explicit `viewport`. |
| `scope` | `'content' \| 'viewport' \| 'selection'` | `'content'` | Chooses whole content, an explicit slice, or selected entities. |
| `includeIds` | `Iterable<string>` | Not set | Prunes output to the named entities. |
| `maxSize` | `number` | `4000` for raster output | Reduces scale to fit the cap, rather than cropping. SVG has no automatic cap. |
| `embedModel` | `boolean` | Not set | Carries editable data in SVG/PNG. |
| `embedModelCreatedAt` | `string` | Wall-clock timestamp when embedding | Pins the envelope timestamp for repeatable embedded exports. |
| `customNodeTimeout` | `number` | `5000` ms | Bounds waiting for tracked async painters; reports unfinished paint. |

Prefer async export when custom nodes or external images matter. It waits for tracked painters and fetches external images; `onWarnings` reports fidelity gaps. `exportSvgString()` and `exportPdf()` capture current custom-node content synchronously and do not fetch assets. Angular names the synchronous SVG method `exportSvg()`.

If an image server blocks CORS, use `assetFetcher` to route through your own allowlisted proxy, or supply `resolvedAssets` with bytes already encoded as data URLs. Never expose an unrestricted image proxy: arbitrary upstream URLs create an SSRF risk. An unresolved image remains an SVG reference but is missing from PDF, with a warning.

Browser file export does not preserve CSS animations. Fonts are not embedded automatically; use `embedFonts` or `embedFontCss` when the SVG must carry its own glyph resources. Inspect warnings before distributing files with custom HTML content.

## Related

- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) — keep the renderer alive until unmount.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) — persist the full document rather than a framework projection.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) — size the mounted view and choose the theme its exports use.

<!-- source: draw-and-edit-ink.md -->

# Draw and edit ink

Use the shipped whiteboard tools to annotate a mounted diagram with vector ink. The example starts with a teal stroke and four toolbar buttons: draw more ink, erase whole strokes, drag out rectangle nodes, or move committed ink.

Ink belongs to the live document, not to the framework's node array. Freehand marks are [`StrokeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-strokemodel#strokemodel) entities; rectangles are nodes. The tools use the canvas's existing pointer and touch gesture pipeline.

## 1. Install the packages

Run the common install command in your application, then add your framework binding if you use one.

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

JavaScript:

```bash
npm install @grafloria/element
```

Angular:

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

Qwik:

```bash
npm install @grafloria/qwik @builder.io/qwik
```

React:

```bash
npm install @grafloria/react react react-dom
```

Vue:

```bash
npm install @grafloria/vue vue
```

## 2. Attach the tools and toolbar

Create `ink-tools.ts` in your browser application's source directory. The next step imports it from each framework's mounted canvas.

[`createDrawTool`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-functions#createdrawtool), [`createEraserTool`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-functions#createerasertool), [`createRectangleTool`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-functions#createrectangletool) and [`createStrokeEditTool`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-functions#createstrokeedittool) return live tools. Attach each with [`registerTool`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#registertool), and use `setActive()` to switch modes. Each registration returns a cleanup function.

The factories take a [`WhiteboardHost`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-interfaces-v-w#whiteboardhost): the mounted model, viewport, container and repaint hook, plus the engine for history. A [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) already supplies these members. Angular supplies the same members through its canvas component.

This helper seeds real ink, registers the shipped tools, and creates the toolbar. It keeps exactly one tool active, including disabling stroke editing in eraser mode.

```ts title="ink-tools.ts"
import { StrokeModel } from '@grafloria/engine';
import {
  createDrawTool,
  createEraserTool,
  createRectangleTool,
  createStrokeEditTool,
  registerTool,
  type WhiteboardHost,
} from '@grafloria/renderer';

export function attachInkTools(host: WhiteboardHost, toolbar: HTMLElement): () => void {
  host.getModel().addStroke(new StrokeModel(
    [
      { x: 80, y: 140 }, { x: 160, y: 110 },
      { x: 240, y: 150 }, { x: 320, y: 120 },
    ],
    { color: '#0f766e', width: 4 },
    { id: 'ink-seed', label: 'Example annotation' },
  ));

  const draw = createDrawTool(host, {
    color: '#0f766e', width: 4, simplifyEpsilon: 0.8,
  });
  const eraser = createEraserTool(host, { radius: 10, active: false });
  const rectangle = createRectangleTool(host, {
    fill: '#dbeafe', stroke: '#2563eb', strokeWidth: 2,
    label: 'Box', active: false,
  });
  const edit = createStrokeEditTool(host, { tolerance: 6, active: false });
  const tools = [draw, eraser, rectangle, edit];
  const unregister = tools.map(tool => registerTool(tool));
  const abort = new AbortController();
  const buttons: HTMLButtonElement[] = [];
  const names = ['Draw', 'Erase', 'Rectangle', 'Edit ink'];
  const status = document.createElement('output');
  status.setAttribute('aria-live', 'polite');

  toolbar.style.cssText = 'display:flex;gap:8px;padding:8px;font:14px sans-serif';
  function activate(index: number): void {
    tools.forEach((tool, i) => tool.setActive(i === index));
    status.textContent = `Active tool: ${names[index]}`;
    buttons.forEach((button, i) => {
      button.setAttribute('aria-pressed', String(i === index));
      button.style.background = i === index ? '#0f766e' : '#fff';
      button.style.color = i === index ? '#fff' : '#111';
    });
  }

  names.forEach((name, index) => {
    const button = document.createElement('button');
    button.type = 'button';
    button.textContent = name;
    button.style.cssText = 'padding:6px 12px;border:1px solid #94a3b8;border-radius:4px';
    button.addEventListener('pointerdown', () => activate(index), { signal: abort.signal });
    button.addEventListener('click', () => activate(index), { signal: abort.signal });
    buttons.push(button);
    toolbar.append(button);
  });
  toolbar.append(status);
  activate(0);
  host.render();

  return () => {
    abort.abort();
    for (const off of unregister.reverse()) off();
    for (const button of buttons) button.remove();
    status.remove();
  };
}
```

## 3. Mount a canvas in your framework

Each tab renders the same initial annotation in a 400-pixel-high canvas. Keep `ink-tools.ts` beside the file below. The framework owns the diagram's lifetime; its unmount hook removes the tool registrations.

Pass the JavaScript [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) instance to `attachInkTools()`, or adapt Angular's [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) to `WhiteboardHost` as below; see [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for canvas setup and typed node/edge bindings.

Connect `attachInkTools()` to React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react), Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue), or Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) as below; see [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for instance initialization and Qwik's browser-only setup.

:::code-group
```ts title="JavaScript"
// main.ts — your HTML contains <div id="app"></div>.
import { render } from '@grafloria/element';
import { attachInkTools } from './ink-tools';

export function mountInkBoard(target: HTMLElement): () => void {
  const toolbar = document.createElement('div');
  const canvas = document.createElement('div');
  canvas.style.cssText = 'height:400px;position:relative;touch-action:none';
  target.append(toolbar, canvas);
  const instance = render({ nodes: [], edges: [] }, canvas);
  const removeTools = attachInkTools(instance, toolbar);
  return () => {
    removeTools();
    instance.dispose();
    toolbar.remove();
    canvas.remove();
  };
}

const target = document.getElementById('app');
if (!target) throw new Error('Missing #app');
export const unmountInkBoard = mountInkBoard(target);
```
```ts title="Angular"
// ink-board.component.ts
import { AfterViewInit, Component, ElementRef, OnDestroy, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeInput, EdgeInput, WhiteboardHost } from '@grafloria/renderer';
import { attachInkTools } from './ink-tools';

@Component({
  selector: 'app-ink-board',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <div #toolbar></div>
    <div #host style="height:400px;position:relative;touch-action:none">
      <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
        style="display:block;height:100%" />
    </div>
  `,
})
export class InkBoardComponent implements AfterViewInit, OnDestroy {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly host = viewChild.required<ElementRef<HTMLElement>>('host');
  readonly toolbar = viewChild.required<ElementRef<HTMLElement>>('toolbar');
  nodes: NodeInput[] = [];
  edges: EdgeInput[] = [];
  private removeTools?: () => void;

  ngAfterViewInit(): void {
    const canvas = this.canvas();
    const engine = canvas.activeEngine();
    const model = engine?.getDiagram();
    const viewport = canvas.viewportController();
    if (!engine || !model || !viewport) throw new Error('Canvas not initialized');
    const host: WhiteboardHost = {
      getModel: () => model,
      getEngine: () => engine,
      viewport,
      container: this.host().nativeElement,
      render: () => canvas.scheduleRender(),
    };
    this.removeTools = attachInkTools(host, this.toolbar().nativeElement);
  }

  ngOnDestroy(): void {
    this.removeTools?.();
  }
}
```
```tsx title="Qwik"
// ink-board.tsx
import { $, component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { attachInkTools } from './ink-tools';

export default component$(() => {
  const toolbar = useSignal<HTMLDivElement>();
  const instance = useSignal<NoSerialize<DiagramInstance>>();

  useVisibleTask$(({ track, cleanup }) => {
    const mounted = track(() => instance.value);
    const controls = track(() => toolbar.value);
    if (!mounted || !controls) return;
    cleanup(attachInkTools(mounted, controls));
  });

  return <div>
    <div ref={toolbar} />
    <GrafloriaFlow style={{ height: '400px', display: 'block', touchAction: 'none' }}
      onInit$={$((mounted: DiagramInstance) => {
        instance.value = noSerialize(mounted);
      })} />
  </div>;
});
```
```tsx title="React"
// ink-board.tsx
import { useEffect, useRef } from 'react';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/react';
import { attachInkTools } from './ink-tools';

export default function InkBoard() {
  const toolbar = useRef<HTMLDivElement>(null);
  const removeTools = useRef<(() => void) | undefined>(undefined);
  useEffect(() => () => { removeTools.current?.(); }, []);

  function onInit(instance: DiagramInstance): void {
    if (!toolbar.current) throw new Error('Missing toolbar');
    removeTools.current = attachInkTools(instance, toolbar.current);
  }

  return <div>
    <div ref={toolbar} />
    <GrafloriaFlow style={{ height: 400, display: 'block', touchAction: 'none' }}
      onInit={onInit} />
  </div>;
}
```
```vue title="Vue"
<!-- InkBoard.vue -->
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import { attachInkTools } from './ink-tools';

const toolbar = ref<HTMLDivElement | null>(null);
let removeTools: (() => void) | undefined;
function onInit(instance: DiagramInstance): void {
  if (!toolbar.value) throw new Error('Missing toolbar');
  removeTools = attachInkTools(instance, toolbar.value);
}
onBeforeUnmount(() => { removeTools?.(); });
</script>

<template>
  <div>
    <div ref="toolbar"></div>
    <GrafloriaFlow style="height:400px;display:block;touch-action:none" @init="onInit" />
  </div>
</template>
```
:::

The JavaScript sample starts with Draw selected above a teal annotation.

![Draw, Erase, Rectangle and Edit ink buttons above the teal stroke in JavaScript.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c0c9b7dad27f2d103f58358a51f637bc.png)

Call the JavaScript tab's exported `unmountInkBoard()` when your application removes that view. The framework tabs leave instance disposal to their binding.

### Try the gestures

Click a mode button and look for `Active tool: <mode>` beside the buttons, where `<mode>` is the selected tool's name. The status text changes in the same handler that activates the tool.

1. With Draw active, press and drag in the canvas, then release. The growing preview becomes one simplified vector stroke in the live model.
2. Click Edit ink, press on the seeded stroke, and drag. A ghost follows the pointer; release moves the whole stroke. Escape cancels the move without changing the document.
3. Click Erase and sweep across ink. Release removes every stroke the sweep crosses, including the entire stroke rather than a pixel-wide gap. Nodes remain untouched.
4. Click Rectangle and drag corner to corner. Release creates a node labelled Box, positioned and sized by the drag. Either drag direction works; a drag smaller than `minSize` in either dimension creates nothing.

Drawing, erasing and translating ink each commit one command when the host supplies `getEngine()`. For history controls, see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

> **Known issue:** The rectangle tool adds its node directly to the model, so rectangle creation does not join the engine's undo stack. Use the shipped tool for drawing boxes; if your application requires undoable creation, add a node through `getEngine().addNode()` from your own creation control, as shown in [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes).

## Options that matter

Pass these options to the corresponding factory. Sizes and hit tolerances are in world coordinates, so zoom changes their apparent screen size.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| Draw `color` | `string` | `'#1f2933'` | Sets ink and preview color. |
| Draw `width` | `number` | `3` | Sets ink width. |
| Draw `simplifyEpsilon` | `number` | Model's simplification default | Sets Douglas–Peucker tolerance at commit. |
| Draw `label` | `string` | Omitted | Names each committed stroke for accessibility. |
| Eraser `radius` | `number` | `8` | Adds a hit radius around the swept path. |
| Rectangle `minSize` | `number` | `4` | Rejects drags whose width or height is smaller. |
| Rectangle `label` | `string` | Omitted | Labels the created node. |
| Edit `tolerance` | `number` | `6` | Adds a hit radius around committed ink. |
| Edit `highlightColor` | `string` | `'#2563eb'` | Colors the selected stroke's highlight. |
| All tools `active` | `boolean` | `true` | Enables gesture claims; change it later with `setActive()`. |

Anonymous ink is hidden from the accessibility tree. A stroke with a `label`, such as the seeded annotation, is exposed as an image with that accessible name.

## Tool ownership and pitfalls

- Keep at most one of draw, eraser and rectangle active. They claim every press while active, including presses over nodes. Select Edit ink to let the built-in node and empty-canvas interactions run wherever there is no ink.
- If you keep stroke editing active alongside drawing, a press on ink edits instead of drawing over it: the ink-specific tool has higher priority. Disable editing when you want the eraser to consume ink. The example's mode switch does this.
- Tool registrations are global, and the shipped tools have fixed ids. Use this example for one active whiteboard at a time, and remove its registrations on unmount rather than leaving tools attached to an old canvas.
- Save the live document rather than treating a node array as the ink document. See [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

## Live demos and related tasks

Try [Freehand draw](https://grafloria.com/demos/whiteboard/freehand-draw.html), [Eraser](https://grafloria.com/demos/whiteboard/eraser.html), [Rectangle tool](https://grafloria.com/demos/whiteboard/rectangle.html), and [Stroke edit](https://grafloria.com/demos/whiteboard/stroke-edit.html). The [stroke-edit demo source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/whiteboard/stroke-edit.html) shows the same `setActive()` toolbar switch.

- [Configure editing gestures](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/configure-editing-gestures) covers the built-in interaction modes.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) covers canvas sizing and appearance.

<!-- source: tune-large-graph-rendering.md -->

# Tune large-graph rendering

Use renderer configuration, level of detail (LOD), and batched mutations when a large diagram spends too much time painting. The examples below mount a 900-node mesh, let you compare near and overview zooms, and move every node in one batch. A performance overlay reports measurements from the mounted scene; Angular also exposes its own render-loop metrics.

## 1. Prepare the scene and renderer policy

In your existing framework project, install the packages for your framework.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

Create this shared file beside your component or browser entry point. Type the input data with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec). Pass [`SVGRendererConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-svgrendererconfig#svgrendererconfig) through the binding's `rendererConfig` prop, or JavaScript's `renderer` option.

The renderer ships an adaptive [`QualityGovernor`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-perf#qualitygovernor); enable it through configuration rather than creating a separate governor that the canvas never uses. It measures renderer frame times, lowers detail when the budget is exceeded, and restores detail after sustained headroom. Zoom determines what detail is useful; the governor determines what the machine can afford.

The live [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel#diagrammodel) holds the [`LODConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-interfaces-b-r#lodconfig). This example keeps the shipped feature sets and raises the medium tier's lower zoom bound from `0.5` to `0.6`. At zooms between `0.5` and `0.6`, the diagram therefore uses sketch detail before any governor bias.

```ts title="scene.ts"
import type { DiagramModel, LODConfig } from '@grafloria/engine';
import type { NodeSpec, EdgeSpec, SVGRendererConfig } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [];
export const edges: EdgeSpec[] = [];
const side = 30;
const id = (row: number, col: number) => `n${row * side + col}`;

for (let row = 0; row < side; row++) {
  for (let col = 0; col < side; col++) {
    nodes.push({
      id: id(row, col), label: `${row * side + col}`,
      position: { x: col * 120, y: row * 80 },
      size: { width: 92, height: 46 },
    });
    if (col + 1 < side) {
      edges.push({ source: id(row, col), target: id(row, col + 1) });
    }
    if (row + 1 < side) {
      edges.push({ source: id(row, col), target: id(row + 1, col) });
    }
  }
}

export const rendererConfig = {
  enableCaching: true,
  maxCacheSize: 2000,
  qualityGovernor: { budgetMs: 16.7 },
} satisfies SVGRendererConfig;

export function configureLOD(model: DiagramModel): void {
  const policy: LODConfig = {
    tiers: model.getLODConfig().tiers.map(tier => ({
      ...tier,
      minZoom: tier.name === 'medium' ? 0.6 : tier.minZoom,
    })),
  };
  model.setLODConfig(policy);
}
```

## 2. Measure and batch on the mounted instance

For JavaScript, Qwik, React, and Vue, use the [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) received at initialization. `getQualityState()` returns the tier actually painted and, when enabled, the governor's last verdict. Read it after painting, not immediately after changing zoom. The instance's `viewport` is a [`ViewportController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#viewportcontroller); call its `setZoom()` method to change the camera scale.

Use the shipped [`PerfHud`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-perf#perfhud) to display a [`PerfSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-perf#perfsnapshot). It is an opt-in DOM overlay with `pointer-events: none`; it does not collect measurements for you. This helper times a synchronous repaint and counts node and link elements in the diagram container. It refreshes on initialization and after each button action, not continuously.

The HUD's FPS, dirty, and routed counters remain `0` here because this helper does not instrument those counters. `frameMs` measures the explicit repaint, including the synchronous DOM work; it is not an average frame duration. `mountedViews` counts node elements in this SVG-only sample. Use the visible-to-total ratios to inspect culling, and the tier and governor verdict to explain reduced detail.

```ts title="inspection.ts"
import { PerfHud, type DiagramInstance, type PerfSnapshot } from '@grafloria/renderer';
import { configureLOD } from './scene';

export function refresh(api: DiagramInstance, hud: PerfHud): void {
  const start = performance.now();
  api.renderNow();
  const frameMs = performance.now() - start;
  const model = api.getModel();
  const quality = api.getQualityState();
  const visibleNodes = api.container.querySelectorAll('[data-node-id]').length;
  const snapshot: PerfSnapshot = {
    fps: 0, frameMs,
    nodes: model.getNodes().length,
    links: model.getLinks().length,
    visibleNodes,
    visibleLinks: api.container.querySelectorAll('[data-link-id]').length,
    mountedViews: visibleNodes,
    dirtyNodes: 0, dirtyLinks: 0, routedLinks: 0,
    tier: quality.tier,
    governor: quality.governor,
  };
  hud.update(snapshot);
}

export function initialize(api: DiagramInstance, host: HTMLElement): PerfHud {
  configureLOD(api.getModel());
  const hud = new PerfHud(host);
  hud.show();
  api.fitView(40);
  api.viewport.setZoom(0.7);
  refresh(api, hud);
  return hud;
}

export function zoom(api: DiagramInstance, hud: PerfHud, value: number): void {
  api.viewport.setZoom(value);
  refresh(api, hud);
}

export function shift(api: DiagramInstance, hud: PerfHud): void {
  api.batchUpdate(model => {
    for (const node of model.getNodes()) {
      node.setPosition(node.position.x + 20, node.position.y);
    }
  });
  refresh(api, hud);
}
```

`batchUpdate()` runs a synchronous mutator against the live model and coalesces the resulting repaint. The extra `renderNow()` above forces that queued paint to finish before measuring and reading the quality state. For ordinary updates without immediate inspection, use the queued repaint instead of forcing every frame.

## 3. Mount the mesh in your framework

Choose one tab. Each sample starts at `0.7×`, shows a slice of the mesh, and leaves all 900 nodes in the model. Click **Overview** to zoom out; click **Move all +20** to shift the entire graph right. Detail can fall below the zoom-derived tier when the governor detects expensive frames.

These mounts add renderer configuration, LOD setup, and performance controls to the framework mounting patterns in [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes).

:::code-group
```ts title="JavaScript"
// main.ts — mount() returns cleanup; call it when your host view unmounts.
import { render } from '@grafloria/element';
import { nodes, edges, rendererConfig } from './scene';
import { initialize, zoom, shift } from './inspection';

export function mount(parent: HTMLElement): () => void {
  const view = document.createElement('section');
  view.innerHTML = `
    <button data-near>Near</button>
    <button data-overview>Overview</button>
    <button data-move>Move all +20</button>
    <div data-stage style="height:480px;position:relative">
      <div data-canvas style="height:100%"></div>
      <div data-hud style="position:absolute;top:0;left:0"></div>
    </div>`;
  parent.appendChild(view);
  const host = view.querySelector<HTMLElement>('[data-canvas]')!;
  const hudHost = view.querySelector<HTMLElement>('[data-hud]')!;
  const api = render({ nodes, edges }, host, { renderer: rendererConfig });
  const hud = initialize(api, hudHost);
  view.querySelector<HTMLButtonElement>('[data-near]')!.onclick = () => zoom(api, hud, 0.7);
  view.querySelector<HTMLButtonElement>('[data-overview]')!.onclick = () => zoom(api, hud, 0.15);
  view.querySelector<HTMLButtonElement>('[data-move]')!.onclick = () => shift(api, hud);
  return () => { hud.hide(); api.dispose(); view.remove(); };
}

const parent = document.getElementById('app')!;
export const unmount = mount(parent);
```
```ts title="Angular"
// app.component.ts
import { AfterViewInit, Component, ElementRef, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, rendererConfig, configureLOD } from './scene';

@Component({
  selector: 'app-root', standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <button (click)="setZoom(0.7)">Near</button>
    <button (click)="setZoom(0.15)">Overview</button>
    <button (click)="move()">Move all +20</button>
    <button (click)="inspect()">Inspect metrics</button>
    <pre #readout>Click Inspect metrics after a repaint.</pre>
    <grafloria-diagram-canvas
      [(nodes)]="nodes" [(edges)]="edges"
      [rendererConfig]="rendererConfig"
      style="display:block;height:480px" />
  `,
})
export class AppComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  readonly readout = viewChild.required<ElementRef<HTMLElement>>('readout');
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;
  readonly rendererConfig = rendererConfig;

  ngAfterViewInit(): void {
    const model = this.canvas().activeEngine()?.getDiagram();
    if (model) configureLOD(model);
    this.canvas().fitToContent(40);
    this.setZoom(0.7);
  }

  setZoom(value: number): void {
    this.canvas().viewportController()?.setZoom(value);
    this.canvas().scheduleRender();
  }

  move(): void {
    const model = this.canvas().activeEngine()?.getDiagram();
    if (!model) return;
    model.beginBatch();
    try {
      for (const node of model.getNodes()) {
        node.setPosition(node.position.x + 20, node.position.y);
      }
    } finally {
      model.endBatch();
    }
    this.canvas().scheduleRender();
  }

  inspect(): void {
    this.readout().nativeElement.textContent =
      JSON.stringify(this.canvas().getPerformanceMetrics(), null, 2);
  }
}
```
```tsx title="Qwik"
// app.tsx
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { type DiagramInstance, type PerfHud } from '@grafloria/renderer';
import { nodes, edges, rendererConfig } from './scene';
import { initialize, zoom, shift } from './inspection';

export default component$(() => {
  const host = useSignal<HTMLElement>();
  const api = useSignal<NoSerialize<DiagramInstance>>();
  const hud = useSignal<NoSerialize<PerfHud>>();
  useVisibleTask$(({ cleanup }) => {
    cleanup(() => hud.value?.hide());
  });
  return <section>
    <button onClick$={() => { if (api.value && hud.value) zoom(api.value, hud.value, 0.7); }}>Near</button>
    <button onClick$={() => { if (api.value && hud.value) zoom(api.value, hud.value, 0.15); }}>Overview</button>
    <button onClick$={() => { if (api.value && hud.value) shift(api.value, hud.value); }}>Move all +20</button>
    <div style={{ height: '480px', position: 'relative' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} rendererConfig={rendererConfig}
        onInit$={instance => {
          api.value = noSerialize(instance);
          if (host.value) hud.value = noSerialize(initialize(instance, host.value));
        }} />
      <div ref={host} style={{ position: 'absolute', top: '0', left: '0' }} />
    </div>
  </section>;
});
```
```tsx title="React"
// App.tsx
import { useEffect, useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance, PerfHud } from '@grafloria/renderer';
import { nodes, edges, rendererConfig } from './scene';
import { initialize, zoom, shift } from './inspection';

export default function App() {
  const host = useRef<HTMLDivElement>(null);
  const api = useRef<DiagramInstance | null>(null);
  const hud = useRef<PerfHud | null>(null);
  useEffect(() => () => { hud.current?.hide(); }, []);
  function setZoom(value: number) {
    if (api.current && hud.current) zoom(api.current, hud.current, value);
  }
  return <section>
    <button onClick={() => setZoom(0.7)}>Near</button>
    <button onClick={() => setZoom(0.15)}>Overview</button>
    <button onClick={() => { if (api.current && hud.current) shift(api.current, hud.current); }}>Move all +20</button>
    <div style={{ height: 480, position: 'relative' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} rendererConfig={rendererConfig}
        onInit={instance => {
          api.current = instance;
          hud.current?.hide();
          if (host.current) hud.current = initialize(instance, host.current);
        }} />
      <div ref={host} style={{ position: 'absolute', top: 0, left: 0 }} />
    </div>
  </section>;
}
```
```vue title="Vue"
<!-- App.vue -->
<script setup lang="ts">
import { onUnmounted, ref, shallowRef } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import type { DiagramInstance, PerfHud } from '@grafloria/renderer';
import { nodes, edges, rendererConfig } from './scene';
import { initialize, zoom, shift } from './inspection';

const host = ref<HTMLElement>();
const api = shallowRef<DiagramInstance>();
const hud = shallowRef<PerfHud>();
function onInit(instance: DiagramInstance): void {
  api.value = instance;
  if (host.value) hud.value = initialize(instance, host.value);
}
function setZoom(value: number): void {
  if (api.value && hud.value) zoom(api.value, hud.value, value);
}
function move(): void {
  if (api.value && hud.value) shift(api.value, hud.value);
}
onUnmounted(() => hud.value?.hide());
</script>

<template>
  <section>
    <button @click="setZoom(0.7)">Near</button>
    <button @click="setZoom(0.15)">Overview</button>
    <button @click="move">Move all +20</button>
    <div style="height:480px;position:relative">
      <GrafloriaFlow :default-nodes="nodes" :default-edges="edges"
        :renderer-config="rendererConfig" @init="onInit" />
      <div ref="host" style="position:absolute;top:0;left:0" />
    </div>
  </section>
</template>
```
:::

The JavaScript sample opens with a labeled mesh and the performance overlay.

![JavaScript: a slice of the numbered mesh, the performance HUD, and Near, Overview, and Move all +20 buttons.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/48bab42b59a91cc17c456801749ec64d.png)

The Angular sample adds an explicit metrics inspection button.

![Angular: numbered nodes and directional links below the controls and the initial metrics prompt.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7d1a377efc6ed489c1e977f963933560.png)

The Qwik sample shows the mesh and its overlay.

![Qwik: a grid of connected boxes beneath three controls, with the performance HUD overlaying the upper-left corner.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/94c0d7857d93c6df01798c72f3d8a0fd.png)

The React sample shows the numbered nodes behind the overlay.

![React: numbered boxes connected horizontally and vertically, with the HUD reporting medium detail.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/53f714e8876ca8288c7ddc10239fd5f3.png)

The Vue sample opens on the same mesh slice.

![Vue: the labeled mesh, performance overlay, and Near, Overview, and Move all +20 controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/de035c34eff0bcfa0fce4d28c819dba4.png)

Angular does not expose the renderer-level instance through this component. Batch through the model obtained from `activeEngine()`, then queue the component's repaint. Click **Inspect metrics** after a paint to get `fps`, `frameTime`, `droppedFrames`, and `sampleCount`. Its ring buffers retain up to 60 painted frames; skipped frames do not add samples. `frameTime` is the average duration in that window. The source counts a dropped frame when rendering exceeds **32 ms**, not the governor's `16.7 ms` budget. This return shape differs from the renderer's [`PerformanceMetrics`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-b-s#performancemetrics).

## Options that matter

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `enableCaching` | `boolean` | `true` | Enables VNode caching. |
| `maxCacheSize` | `number` | `1000` | Bounds the renderer's LRU VNode cache. |
| `qualityGovernor` | `boolean \| GovernorOptions` | `true` | Uses defaults with `true`, tunes the governor with an object, or disables adaptive bias with `false`. |
| `qualityGovernor.budgetMs` | `number` | `16.7` | Sets the frame-time budget in milliseconds. |
| `qualityGovernor.window` | `number` | `12` | Sets the normal decision window. |
| `qualityGovernor.recoveryWindows` | `number` | `3` | Requires this many consecutive fast windows before restoring one tier. |
| `qualityGovernor.maxBias` | `0 \| 1 \| 2` | `2` | Limits how many tiers below the zoom-derived tier the governor can render. |

[`GovernorOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-perf#governoroptions) also controls the down/up thresholds and catastrophic-frame escalation. The defaults use a median, a dead band, and slower recovery to avoid oscillating between detail levels.

The shipped LOD policy uses these inclusive lower bounds. The sample changes only the medium bound to `0.6`.

| Tier | Shipped zoom range | What renders |
| --- | --- | --- |
| `high` | `zoom >= 1` | All LOD features. |
| `medium` | `0.5 <= zoom < 1` | Labels, borders, ports, decorations, handles, routing, link detail, and gradients. |
| `sketch` | `0.2 <= zoom < 0.5` | Borders, routing, and link detail; no labels or ports. |
| `low` | `zoom < 0.2` | No optional LOD features: plain boxes and direct lines. |

## Pitfalls

- Pass `qualityGovernor: false` when comparing zoom tiers deterministically. Otherwise the reported tier can be simpler than the zoom policy requests.
- Configure React, Vue, and Qwik renderer options when mounting: their bindings pass `rendererConfig` into instance creation. Angular recreates its renderer when that input changes, so keep the object stable during ordinary data edits.
- Keep the `batchUpdate()` callback synchronous. It ends the model batch when the callback returns, not when asynchronous work finishes.
- Render batching is not an undoable edit. For user-facing operations that need history, use [commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).
- At fit-to-content, the full mesh can be visible, so a high visible-node count does not by itself indicate failed culling. Compare it with the near view.
- For container sizing, see [theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

## Live demos and related tasks

- [Stress test](https://grafloria.com/demos/nodes/stress-test.html): compare viewport culling and layout on a 900-node mesh.
- [Contextual zoom](https://grafloria.com/demos/interaction/contextual-zoom.html): compare the four rendered detail tiers.
- [Perf HUD and quality governor](https://grafloria.com/demos/misc/perf-hud.html), with [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/misc/perf-hud.html): inspect the shipped overlay and governor behavior.
- [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram): arrange the graph rather than only changing render cost.

<!-- source: extend-rendered-geometry.md -->

# Extend rendered geometry

Use a geometry extension when the shipped figures, arrowheads or line styles cannot express your notation. Register the geometry by name, then use that name in the specs you pass to your mounted diagram. The renderer owns the geometry as nodes move; your extension supplies an outline, a path or the SVG elements that paint it.

Start with the built-ins: figures include `diamond`, `cylinder`, `document` and `actor`; markers include `open-arrow`, `crow-foot` and `hollow-diamond`. For routing and corner treatment, see [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges). Go below the component's props only to define geometry the renderer does not already provide.

## 1. Register a silhouette, pipe and marker

This example draws a built-in rectangle connected to a custom chevron by a two-stroke pipe, then connects the chevron to a sink with a feather marker. The pipe follows the routed path rather than a fixed picture.

Use [`registerPathShape`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registerpathshape) for an SVG-path silhouette. It derives boundary points and port anchors from the outline and reuses the outline for the body, selection and shadow. Use [`registerShape`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registershape) only when you need to implement the full [`ShapeDefinition`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-shapedefinition#shapedefinition) contract yourself: `outline`, `boundaryPoint` and `portAnchor`, with an optional `innerRect` for the label.

[`registerLinkTemplate`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registerlinktemplate) receives the current routed points, `pathData` and selection state. Its output replaces the visible edge rendering; the renderer retains the link wrapper and hit area. [`registerMarker`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registermarker) defines an endpoint glyph. Put the supplied `transform` on its root element and declare `tipOffset` so its visual tip meets the endpoint.

Create this shared file in your browser application. Its nodes use the library's [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) type and its edges use [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec).

```ts title="geometry.ts"
import {
  registerPathShape,
  registerLinkTemplate,
  registerMarker,
  type NodeSpec,
  type EdgeSpec,
} from '@grafloria/renderer';

export function registerGeometry(): void {
  registerPathShape(
    'notation-chevron',
    'M2,4 L14,4 L22,12 L14,20 L2,20 L10,12 Z',
    {
      viewBox: { x: 0, y: 0, w: 24, h: 24 },
      innerRect: (w, h) => ({ x: w * 0.42, y: h * 0.35, w: w * 0.2, h: h * 0.3 }),
    },
  );

  registerLinkTemplate('notation-pipe', (ctx) => {
    const stroke = ctx.selected ? '#2563eb' : '#0ea5e9';
    return [
      {
        type: 'path',
        props: {
          d: ctx.pathData, fill: 'none', stroke,
          'stroke-width': 10, 'stroke-opacity': 0.35,
          'stroke-linecap': 'round',
        },
      },
      {
        type: 'path',
        props: { d: ctx.pathData, fill: 'none', stroke, 'stroke-width': 2.5 },
      },
    ];
  });

  registerMarker('notation-feather', {
    tipOffset: (style) => style.size,
    render: (ctx) => ({
      type: 'path',
      props: {
        d: `M0,0 L${ctx.size},0 M${ctx.size * 0.4},-4 L${ctx.size},0 L${ctx.size * 0.4},4`,
        stroke: ctx.color, fill: 'none', 'stroke-width': 1.5,
        transform: ctx.transform,
      },
    }),
  });
}

export const nodes: NodeSpec[] = [
  {
    id: 'source', position: { x: 40, y: 80 },
    size: { width: 120, height: 64 }, label: 'Source',
    shape: { type: 'rect', fill: '#dbeafe', stroke: '#2563eb' },
  },
  {
    id: 'gate', position: { x: 260, y: 160 },
    size: { width: 140, height: 100 }, label: 'Go',
    shape: { type: 'notation-chevron', fill: '#dbeafe', stroke: '#2563eb' },
  },
  {
    id: 'sink', position: { x: 500, y: 80 },
    size: { width: 120, height: 64 }, label: 'Sink',
    shape: { type: 'rect', fill: '#dbeafe', stroke: '#2563eb' },
  },
];

export const edges: EdgeSpec[] = [
  {
    id: 'pipe', source: 'source', target: 'gate', type: 'smooth',
    style: { template: 'notation-pipe' },
  },
  {
    id: 'feather', source: 'gate', target: 'sink',
    style: { arrowHead: { type: 'notation-feather', size: 14, filled: false } },
  },
];
```

The registration function returns no instance. The next step mounts real nodes and edges that consume all three names.

## 2. Mount the diagram in your framework

Install the shared packages and the binding you use:

```bash
npm install @grafloria/element @grafloria/engine @grafloria/renderer
# Add one binding for a framework application:
npm install @grafloria/react
npm install @grafloria/vue
npm install @grafloria/angular
npm install @grafloria/qwik
```

This task adds geometry registration to the existing mounting pattern; see [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes) for the component and instance entry points.

The browser entry point calls [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) after registration.

```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges, registerGeometry } from './geometry';

registerGeometry();
const wrapper = document.createElement('section');
const host = document.createElement('div');
host.style.height = '400px';
const remove = document.createElement('button');
remove.textContent = 'Remove diagram';
wrapper.append(host, remove);
document.body.append(wrapper);
const instance = render({ nodes, edges }, host);
remove.addEventListener('click', () => {
  instance.dispose();
  wrapper.remove();
}, { once: true });
```

For React, register before rendering [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react); see [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) for the default-spec mounting pattern.

```tsx title="GeometryDiagram.tsx"
import { GrafloriaFlow } from '@grafloria/react';
import { nodes, edges, registerGeometry } from './geometry';

registerGeometry();

export default function GeometryDiagram() {
  return <div style={{ height: '400px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} />
  </div>;
}
```

For Vue, register in the setup script before [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) mounts; see [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works) for default-spec ownership.

```vue title="GeometryDiagram.vue"
<script setup lang="ts">
import { GrafloriaFlow } from '@grafloria/vue';
import { nodes, edges, registerGeometry } from './geometry';

registerGeometry();
</script>

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

For Angular, register in the constructor before [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent) paints; see [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works) for the two-way bindings.

```ts title="geometry-diagram.component.ts"
import { Component } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';
import { nodes, edges, registerGeometry } from './geometry';

@Component({
  selector: 'app-geometry-diagram',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px" />
  `,
})
export class GeometryDiagramComponent {
  nodes: NodeSpec[] = nodes;
  edges: EdgeSpec[] = edges;

  constructor() {
    registerGeometry();
  }
}
```

For Qwik, register in [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik)'s browser initialization callback and repaint its live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance); see [Route and label edges](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/route-and-label-edges) for the default-spec mounting pattern.

```tsx title="GeometryDiagram.tsx"
import { component$, $ } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { nodes, edges, registerGeometry } from './geometry';

export default component$(() => (
  <div style={{ height: '400px' }}>
    <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
      onInit$={$((instance: DiagramInstance) => {
        registerGeometry();
        instance.renderNow();
      })} />
  </div>
));
```

The chevron labelled Go connects to Source through the blue two-stroke pipe; its thinner outgoing line ends with the feather marker at Sink.

You see Source, the chevron labelled Go, and Sink. Drag the chevron to change both routes; the pipe repaints from the routed `pathData`, and the feather receives the endpoint's new transform. Select the pipe to switch its strokes to the selection blue.

Register before the first paint in JavaScript, React, Vue and Angular. In Qwik, register from the browser's `onInit$` callback and call `renderNow()` to repaint with the definitions; do not rely on a server-side registration surviving resumption. The specs contain names, not the template functions.

See the live [Shapes](https://grafloria.com/demos/nodes/shapes.html), [Custom edges](https://grafloria.com/demos/edges/custom-edges.html) and [Edge markers](https://grafloria.com/demos/edges/edge-markers.html) demos for the individual extensions.

## Choose the remaining geometry seams

Keep the stages separate: an anchor chooses one endpoint, a connection-point strategy chooses both endpoints, a router computes the polyline, and a connector turns that polyline into an SVG path. An edge template replaces the visible rendering after that path has been computed.

| Extension | Select it with | Input and result |
| --- | --- | --- |
| [`registerAnchor`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#registeranchor) | `metadata.sourceAnchor` or `metadata.targetAnchor` on the edge | Reads this end, the opposite end, the default point and arguments; returns `{ point, side? }`. Use the world-space node rectangle for a notation-specific attachment. |
| [`registerConnectionPoint`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#registerconnectionpoint) | Edge `metadata.connectionPoint`, or the renderer's `connectionPoint` default | Reads both ends and their defaults; returns `{ start, end, sourceDirection?, targetDirection? }`, or `null` to defer to the default pipeline. The context supplies a shape-boundary solver. |
| [`registerConnector`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions#registerconnector) | Edge `connector` | Reads the routed world-space points, style and resolved corner radius; returns a complete SVG path string. |
| [`registerLabelTemplate`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registerlabeltemplate) | A live link label's `template` | Reads the label, link, world-space anchor, rotation and theme; returns SVG elements or a `foreignObject`, or `null` to suppress the label. |
| [`registerPortLayout`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w#registerportlayout) | Port `layout.strategy`, or a group's layout under node `metadata.portGroups` | Reads node-local width, height, side, rank, count and shape type, plus layout arguments; returns node-local `{ x, y }`. |

For floating attachment, try the shipped `smart` connection-point strategy before implementing a two-ended strategy. For connectors, try `straight`, `rounded`, `smooth` or `bezier`. For port layouts, the shipped choices are `shape`, `absolute`, `line`, `sideLinear`, `ellipse` and `ellipseSpread`; `shape` preserves the silhouette's own anchors.

To select a label template during setup, obtain the live link through `instance.getModel().getLink(id)` and call its `addLabel()` with `text`, `position` or `slot`, and `template`. The top-level edge `label` is the text convenience field, not a label-template selector. Repaint through the instance after setup mutations. For user-facing edits that need undo, use [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

## Options that matter

The shape options belong to [`PathShapeOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-interfaces-o-s#pathshapeoptions).

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `viewBox` | `{ x: number; y: number; w: number; h: number }` | `{ x: 0, y: 0, w: 1, h: 1 }` | Scales a static path's reference box into the node box. Set it to the art box you authored. |
| `sampleSteps` | `number` | `24` | Sets curve subdivision when sampling the outline. |
| `portAnchor` | `ShapeDefinition['portAnchor']` | Derived from the path | Supplies exact node-local port anchors instead of sampled anchors. |
| `boundaryPoint` | `ShapeDefinition['boundaryPoint']` | Derived from the path | Supplies exact world-space floating attachments instead of sampled boundaries. |
| `innerRect` | `ShapeDefinition['innerRect']` | Padded bounding box | Gives the label a box inside a slanted or concave silhouette. |

## Pitfalls and registration lifetime

- An edge template owns the visible edge, including any markers and labels you want it to show. Setting `arrowHead` on the pipe edge does not add the built-in marker rendering to its output. The example puts the feather on a separate, non-templated edge.
- Use a distinct custom connector name. The built-in connector names use internal rendering branches; registering one of those names does not replace that branch.
- Global registration functions share their names across diagrams. Prefix your notation's names to avoid replacing another extension. Shape, edge-template, label-template, marker and port-layout registration functions return `void`; anchor, connection-point and connector registration functions return a disposer that restores the previous definition. Run disposers when the owning extension unmounts, not immediately after registration.
- For shape, marker, template and link-pipeline definitions private to one diagram, use the corresponding methods on `instance.registry`. Those methods return restoring disposers and resolve local definitions before global ones. Port layouts use the global port-layout registry.

## Related

- [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections) — connection rules rather than port geometry.
- [JavaScript: elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content) — HTML content inside engine-positioned node hosts.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) — persist the model; register the named geometry in the application that renders it.

<!-- source: extend-layout-execution.md -->

# Extend layout execution

Use a shipped layout first. Extend the registry when your domain needs an arrangement the shipped algorithms do not express, and attach a worker when layout computation must leave the main thread. The samples below render a connected graph and an editorial workflow.

Run layouts through the mounted [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine) and use its registry only to add an algorithm; [How Grafloria works](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/how-grafloria-works) explains obtaining it from [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance) through `getEngine()`.

## 1. Choose a shipped layout

The engine registers its built-ins for you. You do not need to construct adapters or call [`createBuiltInLayoutAdapters`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-functions-a-t).

| Graph | Layout name | Arrangement |
| --- | --- | --- |
| Pipelines and DAGs | `elk`, `dagre`, `layered` | Layered ranking |
| Systems with zones | `architecture` | Regions composed on a grid |
| Hierarchies | `tree` | Parent-centered branches |
| Networks | `force`, `community`, `spectral` | Physical spread or clusters |
| Catalogs | `grid`, `circular`, `radial` | Uniform placement |
| No explicit choice | `auto` | Graph classification and dispatch |

Calling `engine.layout()` selects `auto`. An unknown name throws an error listing the registered names. For ordinary declarative layout and on-demand reruns, see [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram).

Install the shared packages and the binding you use in your browser application:

```bash
npm install @grafloria/engine @grafloria/renderer @grafloria/element
# Angular
npm install @grafloria/angular
# Qwik
npm install @grafloria/qwik
# Vue
npm install @grafloria/vue
```

## 2. Serve layout in a module worker

Your application creates the worker; the engine does not choose a bundler or worker URL for you. [`LayoutPort`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-i-l) defines the host-side message surface, and [`serveLayout`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-functions-a-t) supplies the worker's message loop.

> **Known issue:** The documented `engine.setLayoutPort(worker)` and `serveLayout(self)` calls can fail strict TypeScript checks because the port types accept a plain `{ data }` event while browser handlers require a full `MessageEvent`. Until it is fixed, forward browser events through the typed port objects below.

Create these shared files beside your application component or entry point. Use a toolchain that bundles module workers created with `new Worker(new URL(..., import.meta.url))`.

```ts title="layout.worker.ts"
import { serveLayout, type LayoutServePort, type LayoutRequest } from '@grafloria/engine';

const port: LayoutServePort = {
  onmessage: null,
  postMessage: (message) => self.postMessage(message),
};
self.addEventListener('message', (event: MessageEvent<LayoutRequest>) => {
  port.onmessage?.({ data: event.data });
});
serveLayout(port);
```

[`LayoutServePort`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-l-u) and [`LayoutRequest`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-types) type the worker side. [`LayoutResponse`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-types) types the messages returned to the host.

The worker resolves the algorithm by name in its own bundle. Registering a function in the main thread does not transfer that function to the worker.

The data uses the library's [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec). Chain edges keep all 45 nodes connected so force layout can use its interruptible path.

```ts title="graph.ts"
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = Array.from({ length: 45 }, (_, i) => ({
  id: `n${i}`,
  label: String(i),
  position: { x: (i % 9) * 90, y: Math.floor(i / 9) * 90 },
  size: { width: 40, height: 40 },
}));

export const edges: EdgeSpec[] = Array.from({ length: 44 }, (_, i) => ({
  id: `e${i}`,
  source: `n${i}`,
  target: `n${i + 1}`,
  type: 'direct',
}));
```

This shared function first applies the shipped `grid` layout, then attaches the worker and requests a long `force` run. Its progress callback requests cancellation at 10%, and its completion handler prints the returned status. The returned function aborts and waits for settlement before terminating the worker; call it during unmount.

```ts title="execution.ts"
import type { DiagramEngine, LayoutPort, LayoutResponse } from '@grafloria/engine';

export function startLayout(engine: DiagramEngine, repaint: () => void): () => void {
  const controller = new AbortController();
  const worker = new Worker(new URL('./layout.worker.ts', import.meta.url), {
    type: 'module',
  });
  const port: LayoutPort = {
    onmessage: null,
    postMessage: (message) => worker.postMessage(message),
  };
  worker.addEventListener('message', (event: MessageEvent<LayoutResponse>) => {
    port.onmessage?.({ data: event.data });
  });
  let disposed = false;

  const running = (async () => {
    await engine.layout('grid', { columns: 9 });
    if (disposed) return;
    repaint();
    engine.setLayoutPort(port);
    const result = await engine.layout('force', {
      seed: 0x5eed,
      iterations: 4000,
      threshold: 0,
      sliceMs: 0,
      signal: controller.signal,
      onProgress: (progress) => {
        console.log('Layout progress', progress.progress, progress.phase);
        if (progress.progress >= 0.1) controller.abort();
      },
    });
    console.log('Layout result', result.partial, result.reason, result.iteration);
    if (!disposed) repaint();
  })().catch((error: Error) => {
    if (!disposed) console.error(error);
  });

  return () => {
    disposed = true;
    controller.abort();
    void running.finally(() => {
      engine.setLayoutPort(undefined);
      worker.terminate();
    });
  };
}
```

Cancellation is not an exception: `layout()` resolves with a [`UnifiedLayoutResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-l-u), including `nodePositions`, `bounds`, `partial`, `reason`, and iteration counts. The engine commits the returned positions even when `partial` is true. Keep that picture; do not reset the nodes after an abort.

## 3. Run against the mounted diagram

The JavaScript, Angular and Vue tabs run the shipped `grid` layout on their mounted engine and show numbered nodes in five rows. The Qwik tab replaces the browser-side rule setup from [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections#2-mount-the-same-editor-in-your-framework) with `startLayout()` to attach the worker, report progress and cancel the run.

Add the layout call to the mounting patterns for [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core), [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent), Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik) and Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue) in [Edit nodes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-nodes#2-mount-the-canvas-in-your-framework).

:::code-group
```ts title="JavaScript"
import { render } from '@grafloria/element';
import { nodes, edges } from './graph';

export function mountLayout(container: HTMLElement): () => void {
  container.style.height = '400px';
  const instance = render({ nodes, edges }, container);
  void instance.getEngine().layout('grid', { columns: 9 }).then(() => {
    instance.fitView(30);
  });
  return () => {
    instance.dispose();
  };
}

const container = document.createElement('div');
document.body.append(container);
export const unmount = mountLayout(container);
// Call unmount() when your application removes this view.
```
```ts title="Angular"
import { AfterViewInit, Component, viewChild } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import { nodes, edges } from './graph';

@Component({
  selector: 'app-layout',
  standalone: true,
  imports: [DiagramCanvasComponent],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block;height:400px" />
  `,
})
export class LayoutComponent implements AfterViewInit {
  readonly canvas = viewChild.required(DiagramCanvasComponent);
  nodes = nodes;
  edges = edges;

  ngAfterViewInit(): void {
    const canvas = this.canvas();
    const engine = canvas.activeEngine();
    if (engine) {
      void engine.layout('grid', { columns: 9 }).then(() => canvas.scheduleRender());
    }
  }
}
```
```tsx title="Qwik"
import { component$, noSerialize, useSignal, useVisibleTask$, type NoSerialize } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { nodes, edges } from './graph';
import { startLayout } from './execution';

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();

  useVisibleTask$(({ track, cleanup }) => {
    const api = track(() => instance.value);
    if (!api) return;
    cleanup(startLayout(api.getEngine(), () => {
      api.renderNow();
      api.fitView(30);
    }));
  });

  return (
    <div style={{ height: '400px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
        onInit$={(api: DiagramInstance) => { instance.value = noSerialize(api); }} />
    </div>
  );
});
```
```vue title="Vue"
<script setup lang="ts">
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/vue';
import { nodes, edges } from './graph';

function onInit(instance: DiagramInstance): void {
  void instance.getEngine().layout('grid', { columns: 9 }).then(() => {
    instance.fitView(30);
  });
}
</script>

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

The JavaScript sample initially shows the numbered nodes in five rows with connecting arrows.

The Angular sample shows the same grid at the left edge of its canvas.

The Qwik sample shows the nodes spread into a compact network.

Connecting arrows link the numbered nodes in the Qwik canvas.

The Vue sample initially shows the five-row grid framed in the canvas.

## 4. Register a domain-specific layout only when needed

Suppose your editorial workflow requires a fixed reading order: Draft, Review, Published. [`createLayout`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-functions-a-t) wraps a [`GraphLayoutFn`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-types) as a [`RegisteredLayout`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-l-u). It provides canonical input order and disconnected-component packing. Return a [`LayoutResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-i-l) rather than mutating node positions yourself.

Register it in the mounted engine's [`LayoutRegistry`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-classes). `register()` returns a disposer that restores the previous layout under that name, if one existed.

> **Known issue:** A layout created with `createLayout()` exposes an adapter, so an attached worker receives its name even though `serveLayout(self)` cannot resolve your main-thread registration. Until it is fixed, finish any worker run and call `engine.setLayoutPort(undefined)` before running this custom layout inline.

The intended invocation is `await engine.layout('editorial')` after registration, including when a worker is attached. The sample below includes the inline workaround and renders the three stages from left to right.

```ts title="editorial.ts"
import { createLayout, type GraphLayoutFn } from '@grafloria/engine';
import { render } from '@grafloria/element';
import type { NodeSpec, EdgeSpec } from '@grafloria/renderer';

const stageOrder: Record<string, number> = { draft: 0, review: 1, published: 2 };
const arrangeEditorial: GraphLayoutFn = (nodes) => {
  const nodePositions = new Map<string, { x: number; y: number }>();
  let width = 0;
  let height = 0;
  for (const node of nodes) {
    const x = (stageOrder[node.id] ?? 0) * 220;
    nodePositions.set(node.id, { x, y: 0 });
    width = Math.max(width, x + (node.size?.width ?? 140));
    height = Math.max(height, node.size?.height ?? 60);
  }
  return { nodePositions, bounds: { x: 0, y: 0, width, height } };
};

export async function mountEditorial(container: HTMLElement): Promise<() => void> {
  const nodes: NodeSpec[] = [
    { id: 'draft', label: 'Draft', size: { width: 140, height: 60 } },
    { id: 'review', label: 'Review', size: { width: 140, height: 60 } },
    { id: 'published', label: 'Published', size: { width: 140, height: 60 } },
  ];
  const edges: EdgeSpec[] = [
    { source: 'draft', target: 'review' },
    { source: 'review', target: 'published' },
  ];
  container.style.height = '400px';
  const instance = render({ nodes, edges }, container);
  const engine = instance.getEngine();
  const unregister = engine.getLayoutRegistry().register(
    createLayout('editorial', arrangeEditorial),
  );
  engine.setLayoutPort(undefined);
  await engine.layout('editorial');
  instance.fitView(30);
  return () => {
    unregister();
    instance.dispose();
  };
}

const container = document.createElement('div');
document.body.append(container);
export const unmountEditorial = mountEditorial(container);
// On unmount, use unmountEditorial.then((unmount) => unmount()).
```

![Draft, Review and Published arranged left to right with connecting arrows.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f836353434d5ed3931de709cd4f95b65.png)

The algorithm and registry call are framework-independent: use the same registration on the engine obtained in step 3. A [`LayoutAdapter`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-i-l) additionally defines `applyIncremental()` and `validateOptions()`. The adapter produced by `createLayout()` throws for `applyIncremental()`; do not treat this wrapper as an incremental-layout implementation.

## Options that control execution

These fields belong to [`UnifiedLayoutOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-unifiedlayoutoptions). Run controls stay on the host side rather than crossing the worker boundary as callbacks or signals.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `signal` | `AbortSignal` | Not supplied | Requests cooperative cancellation |
| `onProgress` | `(progress: LayoutProgress) => void` | Not supplied | Reports progress on the caller's thread |
| `sliceMs` | `number` | `12` | Sets computation time between event-loop yields |
| `timeBudgetMs` | `number` | No budget | Stops an interruptible run with a partial result and `reason: 'timeout'` |
| `stopAfterIteration` | `number` | No cap | Stops at an iteration count with `reason: 'iteration-cap'` |
| `seed` | `number` | Fixed constant | Makes randomized layouts reproducible |
| `iterations` | `number` | `300` for force | Sets the force simulation's iteration limit |

[`LayoutProgress`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-i-l) contains `progress` from 0 to 1, `phase`, `iteration`, and `totalIterations`. A completed force run reaches 1; a cancelled run reports its actual stopping point. A time budget depends on wall-clock timing; use `stopAfterIteration` when you need a reproducible partial result.

## Execution limits

- Mid-run cancellation and iteration progress require the steppable path. The shipped force adapter uses it for connected graphs. Disconnected force graphs take the packed, one-shot path instead; they retain readable component placement but lose mid-run cancellation.
- One-shot adapters, including dagre, spectral and community, cannot stop inside their algorithm call. They report start and completion rather than simulation iterations.
- Grouped diagrams use the nested-container path by default. That path runs inline and returns a complete single-pass result; attaching a worker does not move it off-thread.
- A `RegisteredLayout` without an `adapter` also runs inline. Worker-side algorithms must exist in the worker bundle; a main-thread closure cannot cross `postMessage()`.

> **Known issue:** Requesting `engine.layout('elk')` through the module worker can fail while constructing ELK's nested worker. Until it is fixed, settle the current run, call `engine.setLayoutPort(undefined)`, then call `await engine.layout('elk')` inline.

## Live demo and related guides

See [Off-thread layout](https://grafloria.com/demos/layout/off-thread-layout.html) for a real worker, streamed progress, cancellation and a main-thread responsiveness check. Its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/layout/off-thread-layout.html) shows the same worker wiring.

- [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram): declarative layouts and explicit reruns.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history): user-facing edits and undo.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas): sizing and appearance.

<!-- source: javascript-elements-and-content.md -->

# JavaScript: elements and content

Use the custom element for HTML-driven embeds and [`render`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#render) for programmatic mounts. Both give you an engine-positioned box whose inside you paint: your content does not take over dragging, selection, ports or connections. This page mounts connected cards, wires events, and updates a custom dashboard widget without rebuilding the board.

## 1. Choose the embedding surface

[`GrafloriaFlowElement`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#grafloriaflowelement) implements `<grafloria-flow>`. Importing `@grafloria/element` registers that tag. Pass arrays through the element's `nodes` and `edges` properties; use JSON attributes when the data lives in markup.

`render()` takes the spec first, a container or CSS selector second, and options third. It returns a live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance). Its input is an object or JSON, not Mermaid text; see [Import diagram text and files](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/import-diagram-text-and-files) for text parsing.

| Choose | What you get |
| --- | --- |
| Element attributes | An HTML embed with JSON data and named DOM events |
| Element properties | Array inputs without JSON encoding, plus `diagram` and `fitView()` |
| `render(spec, target, options)` | A direct instance return, instance events, and kit finalization |

Run the JavaScript examples in a browser project with an ESM bundler, such as the project from the [JavaScript quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-quick-start). Install the packages they import:

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

This property-based embed uses [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) to draw Build and Publish with a connection between them. Register the DOM listener before appending the element. The ready event's detail contains `{ diagram }`; the example reads the typed `diagram` property instead of casting an untyped DOM event payload.

```ts title="src/element.ts"
import { GrafloriaFlowElement } from '@grafloria/element';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const nodes: NodeSpec[] = [
  { id: 'build', label: 'Build', position: { x: 60, y: 100 },
    size: { width: 180, height: 80 } },
  { id: 'publish', label: 'Publish', position: { x: 360, y: 100 },
    size: { width: 180, height: 80 } },
];
const edges: EdgeSpec[] = [{ id: 'release', source: 'build', target: 'publish' }];
const flow = document.createElement('grafloria-flow');
if (!(flow instanceof GrafloriaFlowElement)) throw new Error('Element not registered');
flow.style.height = '400px';
flow.setAttribute('theme', 'light');
flow.setAttribute('fit-view', '');
flow.nodes = nodes;
flow.edges = edges;
const status = document.createElement('p');
status.textContent = 'Starting diagram';
flow.addEventListener('grafloria-ready', () => {
  status.textContent = `Ready: ${flow.diagram?.getModel().getNodes().length} nodes`;
});
flow.addEventListener('grafloria-selection-change', () => {
  const selected = flow.diagram?.getModel().getNodes()
    .filter((node) => node.isSelected()).map((node) => node.id) ?? [];
  status.textContent = selected.length ? `Selected: ${selected.join(', ')}` : 'No selection';
});
const close = document.createElement('button');
close.textContent = 'Close diagram';
close.onclick = () => { flow.remove(); status.remove(); close.remove(); };
document.body.append(status, close, flow);
```

![Build connects to Publish below the Ready: 2 nodes status and Close diagram button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ee724717516cfd0c222576690ebd69b1.png)

Assigning `flow.nodes` or `flow.edges` after mounting calls the instance's corresponding setter. Removing the element disposes its instance. For parent sizing arrangements, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

### Attribute options

The following defaults come from the element's mount logic. Set mount-only attributes before inserting the element.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `nodes`, `edges` | JSON array strings | Empty arrays | Supplies node and edge specs; prefer properties for rich data |
| `theme` | `'light'` or `'dark'` | `'light'` | Selects a shipped theme; unknown names resolve to light |
| `fit-view` | Presence flag | Absent | Frames the content on mount |
| `readonly` | Presence flag | Absent | Configures read-only interaction on mount |
| `pan` | String | Enabled | `"false"` disables pan on mount |
| `wheel-zoom` | String | Enabled | `"false"` disables zoom interaction on mount |
| `zoom` | Numeric string | Not supplied by the element | Supplies the initial zoom |
| `min-zoom`, `max-zoom` | Numeric strings | Not supplied by the element | Supplies mount-time zoom bounds |
| `highlight-connected` | Flag, `"false"`, `"trace"`, or depth string | Off | Highlights selected nodes' connections; `"trace"` follows every path |

### DOM events

Every forwarded event bubbles and is composed, so it can cross a surrounding shadow boundary. Read the payload from `CustomEvent.detail` when your host supplies a typed event adapter.

| DOM event | Detail |
| --- | --- |
| `grafloria-ready` | `{ diagram }` |
| `grafloria-nodes-change` | `{ nodes }` with live node models |
| `grafloria-edges-change` | `{ edges }` with live link models |
| `grafloria-selection-change` | `{ nodes, edges }` |
| `grafloria-connect` | `{ link }` |
| `grafloria-node-click` | `{ node, world }` |
| `grafloria-edge-click` | `{ edge, world }` |
| `grafloria-viewport-change` | `{ viewport, zoom }` |

For a programmatic mount, use `instance.on('selection:change', handler)` instead. It infers the payload type and returns a function that removes the subscription. The programmatic example in the next step shows that cleanup on Close.

### Rename the tag

[`Grafloria`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#grafloria) exposes the intended call `Grafloria.define('project-flow')`.

> **Known issue:** `Grafloria.define('project-flow')` reuses the constructor already registered as `grafloria-flow`, which the browser rejects for a second tag. Until it is fixed, register a subclass under your own tag.

This browser example registers the subclass once and mounts a Release node under `<project-flow>`:

```ts title="src/renamed-element.ts"
import { GrafloriaFlowElement } from '@grafloria/element';
import type { NodeSpec } from '@grafloria/renderer';

if (!customElements.get('project-flow')) {
  class ProjectFlow extends GrafloriaFlowElement {}
  customElements.define('project-flow', ProjectFlow);
}
const flow = document.createElement('project-flow');
if (!(flow instanceof GrafloriaFlowElement)) throw new Error('Unexpected tag constructor');
const nodes: NodeSpec[] = [
  { id: 'release', label: 'Release', position: { x: 80, y: 90 },
    size: { width: 180, height: 80 } },
];
flow.nodes = nodes;
flow.style.height = '400px';
flow.setAttribute('fit-view', '');
document.body.append(flow);
```

![A Release node is centered in the renamed element's canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/03e17d9c53b8449fd7aa963625fb6dfe.png)

## 2. Fill custom node hosts

Register a JavaScript renderer before mounting, and set `custom: true` on each node that uses it. Registering a type alone does not opt JavaScript or React nodes into HTML rendering. React uses `nodeTypes`; Vue exact `#node-<type>` slots and Angular typed templates opt matching specs in automatically. Vue's wildcard `#node` slot still needs `custom: true`.

A JavaScript renderer is a mount hook, not a data binding: it runs once when the host is created. Later node-data changes do not reinvoke it. Update the DOM you own. A missing renderer leaves an empty host, and registering later does not back-fill that host. Style a child of the host; the engine owns the host's position and dimensions.

Use `NodeSpec` and `EdgeSpec` in the shared file below. All framework tabs import it. The cards display Build and Publish, and the wire remains attached when you drag either card.

```ts title="content.ts"
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

export const nodes: NodeSpec[] = [
  { id: 'build', type: 'card', custom: true, position: { x: 60, y: 100 },
    size: { width: 220, height: 110 }, data: { title: 'Build' } },
  { id: 'publish', type: 'card', custom: true, position: { x: 380, y: 100 },
    size: { width: 220, height: 110 }, data: { title: 'Publish' } },
];
export const edges: EdgeSpec[] = [{ id: 'release', source: 'build', target: 'publish' }];
export const cardStyle = {
  boxSizing: 'border-box' as const, height: '100%', padding: '12px',
  border: '1px solid #94a5f0', borderRadius: '10px', background: '#fff',
  color: '#232a3d', fontFamily: 'system-ui',
};
```

Install your binding in addition to the three shared packages above.

JavaScript:

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

Angular:

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

Qwik:

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

React:

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

Vue:

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

Use these components in an existing framework project. React's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow) maps types to components accepting [`NodeProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#nodeprops). Qwik's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) uses Qwik components and its own [`NodeProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#nodeprops). Vue's [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow) uses named slots. Angular's [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) uses `ng-template[grafloriaNode]`, declared by [`GrafloriaNodeDefDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#graflorianodedefdirective).

Each tab exposes a card-local Mark complete button. It changes that card's content to Complete, without pretending that a mount hook is a reactive binding. Selection updates the status outside the canvas through the binding's own event.

:::code-group
```ts title="JavaScript"
import { Grafloria, render } from '@grafloria/element';
import { nodes, edges, cardStyle } from './content';

Grafloria.registerNodeType('card', (node, host) => {
  const card = document.createElement('div');
  Object.assign(card.style, cardStyle);
  const title = document.createElement('strong');
  title.textContent = String(node.getData('title') ?? '');
  const complete = document.createElement('button');
  complete.textContent = 'Mark complete';
  complete.onclick = () => { title.textContent = 'Complete'; };
  card.append(title, document.createElement('br'), complete);
  host.replaceChildren(card);
});
const canvas = document.createElement('div');
canvas.style.height = '400px';
const status = document.createElement('p');
status.textContent = 'Select a card';
const close = document.createElement('button');
close.textContent = 'Close diagram';
document.body.append(status, close, canvas);
const instance = render({ nodes, edges }, canvas, { fitView: true });
const off = instance.on('selection:change', ({ nodes: selected }) => {
  status.textContent = selected.map((node) => node.id).join(', ') || 'No selection';
});
close.onclick = () => {
  off();
  instance.dispose();
  canvas.remove();
  status.remove();
  close.remove();
};
```
```ts title="Angular"
import { Component } from '@angular/core';
import { DiagramCanvasComponent, GrafloriaNodeDefDirective } from '@grafloria/angular';
import { nodes, edges } from './content';

@Component({
  selector: 'app-custom-content',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaNodeDefDirective],
  template: `
    <p>{{ status }}</p>
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      (selectionChange)="status = $event.nodes.length + ' selected'"
      style="display:block;height:400px">
      <ng-template grafloriaNode="card" let-node let-data="data">
        <div style="box-sizing:border-box;height:100%;padding:12px;border:1px solid #94a5f0;
                    border-radius:10px;background:white;color:#232a3d;font-family:system-ui">
          <strong>{{ completed.has(node.id) ? 'Complete' : data['title'] }}</strong><br>
          <button (click)="completed.add(node.id)">Mark complete</button>
        </div>
      </ng-template>
    </grafloria-diagram-canvas>
  `,
})
export class CustomContentComponent {
  nodes = nodes;
  edges = edges;
  status = 'Select a card';
  completed = new Set<string>();
}
```
```tsx title="Qwik"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow, type NodeProps } from '@grafloria/qwik';
import { nodes, edges, cardStyle } from './content';

const Card = component$((props: NodeProps) => {
  const complete = useSignal(false);
  return <div style={cardStyle}>
    <strong>{complete.value ? 'Complete' : String(props.data['title'] ?? '')}</strong><br />
    <button onClick$={() => { complete.value = true; }}>Mark complete</button>
  </div>;
});

export default component$(() => {
  const status = useSignal('Select a card');
  return <>
    <p>{status.value}</p>
    <div style={{ height: '400px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} nodeTypes={{ card: Card }} fitView
        onSelectionChange$={(change) => {
          status.value = `${change.nodes.length} selected`;
        }} />
    </div>
  </>;
});
```
```tsx title="React"
import { useState } from 'react';
import { GrafloriaFlow, type NodeProps } from '@grafloria/react';
import { nodes, edges, cardStyle } from './content';

function Card({ data }: NodeProps) {
  const [complete, setComplete] = useState(false);
  return <div style={cardStyle}>
    <strong>{complete ? 'Complete' : String(data['title'] ?? '')}</strong><br />
    <button onClick={() => setComplete(true)}>Mark complete</button>
  </div>;
}

export default function CustomContent() {
  const [status, setStatus] = useState('Select a card');
  return <>
    <p>{status}</p>
    <div style={{ height: '400px' }}>
      <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} nodeTypes={{ card: Card }} fitView
        onSelectionChange={({ nodes: selected }) => setStatus(`${selected.length} selected`)} />
    </div>
  </>;
}
```
```vue title="Vue"
<script setup lang="ts">
import { defineComponent, h, ref } from 'vue';
import { GrafloriaFlow } from '@grafloria/vue';
import { nodes, edges, cardStyle } from './content';

const status = ref('Select a card');
const Card = defineComponent({
  props: { title: { type: String, required: true } },
  setup(props) {
    const complete = ref(false);
    return () => h('div', { style: cardStyle }, [
      h('strong', complete.value ? 'Complete' : props.title),
      h('br'),
      h('button', { onClick: () => { complete.value = true; } }, 'Mark complete'),
    ]);
  },
});
</script>

<template>
  <p>{{ status }}</p>
  <div style="height:400px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" fit-view
      @selection-change="status = $event.nodes.length + ' selected'">
      <template #node-card="{ data }">
        <Card :title="String(data['title'] ?? '')" />
      </template>
    </GrafloriaFlow>
  </div>
</template>
```
:::

The JavaScript mount includes a Close diagram button above the connected cards.

![JavaScript shows Build and Publish cards with Mark complete buttons, a connecting arrow, and Close diagram.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/305ba9c55380f7834dc5b43bf921bf43.png)

The Angular template fills both cards and leaves the surrounding node outlines and ports visible.

![Angular shows connected Build and Publish cards with Mark complete buttons, orange outlines, and gray port dots.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e9ecdd6cb5c709ac252151a1faf34f43.png)

The Qwik components draw the card content inside the connected hosts.

![Qwik shows Build and Publish cards with Mark complete buttons below Select a card.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9e3b916fdaa9ea8ecdff1f3b5fde7293.png)

The React components and Vue slot components produce the same initial card content: Build and Publish, each with a Mark complete button.

Vue slots do not repaint for in-place node-data changes. Put a component in the slot that subscribes to your own reactive source, rather than relying on slot reinvocation. The Vue card above owns a reactive completion flag. Qwik custom nodes occupy separate Qwik containers: keep them self-contained and pass their initial payload through node data, not surrounding app context.

### Use a template for markup-driven cards

For a CMS or static page, place a `<template data-node-type="template-card">` inside the element. This alternative clones the template for the Build node. `data-field="title"` reads the data bag; `data-field="id"` reads the node id. Missing and null values become empty strings. A registered renderer takes precedence over a matching template.

```html title="index.html"
<!doctype html>
<html lang="en">
<head><meta charset="UTF-8"><title>Template card</title></head>
<body>
  <grafloria-flow style="height:400px" fit-view
    nodes='[{"id":"build","type":"template-card","custom":true,"position":{"x":80,"y":90},"size":{"width":220,"height":110},"data":{"title":"Build"}}]'>
    <template data-node-type="template-card">
      <div style="box-sizing:border-box;height:100%;padding:12px;border:1px solid #94a5f0;border-radius:10px;background:white">
        <strong data-field="title"></strong>
        <p data-field="id"></p>
      </div>
    </template>
  </grafloria-flow>
  <script type="module" src="/src/register.ts"></script>
</body>
</html>
```

```ts title="src/register.ts"
import '@grafloria/element';
```

Template substitution uses `textContent`, not HTML injection. Use the same rule in your JavaScript renderers: never interpolate user-supplied text into `innerHTML`. Templates share the mount-once contract; use owned DOM or widget handles when content must change later. The canvas uses light DOM, so your page stylesheet applies to the cloned children.

## 3. Update custom dashboard content through a handle

Use a [`WidgetHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-widgethandle#widgethandle) to repaint your custom content without remounting the board; see [Arrange dashboard containers](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/arrange-dashboard-containers) for creating and mounting the board and obtaining its handles.

The kit ships KPI, line, bar, donut, funnel and table painters. Delegate those kinds to [`defaultWidgetRenderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-constants#defaultwidgetrenderer) before adding your own painter. Type the data with [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec#dashboardwidgetspec) and the painter with [`WidgetRenderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types#widgetrenderer). This board draws a shipped Builds KPI beside a custom Release note. Update note changes the note to Ready to publish without replacing the board or its instance.

```ts title="src/widgets.ts"
import { dashboard, defaultWidgetRenderer, render } from '@grafloria/element';
import type { DashboardWidgetSpec, WidgetRenderer } from '@grafloria/element';

const widgets: DashboardWidgetSpec[] = [
  { id: 'builds', kind: 'kpi', span: 3, rows: 1,
    data: { label: 'Builds', value: '24' } },
  { id: 'note', kind: 'release-note', span: 3, rows: 1,
    title: 'Release note', data: { text: 'Waiting for review' } },
];
const paint: WidgetRenderer = (widget, host) => {
  if (widget.kind !== 'release-note') {
    defaultWidgetRenderer(widget, host);
    return;
  }
  const card = document.createElement('div');
  Object.assign(card.style, {
    boxSizing: 'border-box', height: '100%', padding: '12px',
    background: '#fff', border: '1px solid #94a5f0', borderRadius: '10px',
    fontFamily: 'system-ui', color: '#232a3d',
  });
  const title = document.createElement('strong');
  title.textContent = widget.title ?? '';
  const text = document.createElement('p');
  text.textContent = String(widget.data?.['text'] ?? '');
  card.append(title, text);
  host.replaceChildren(card);
};
const canvas = document.createElement('div');
canvas.style.height = '400px';
const update = document.createElement('button');
update.textContent = 'Update note';
const close = document.createElement('button');
close.textContent = 'Close board';
document.body.append(update, close, canvas);
const spec = dashboard({ columns: 6, widgets, renderWidget: paint });
const instance = render(spec, canvas);
const handle = spec.handle;
update.onclick = () => {
  handle.widget('note')?.update({ data: { text: 'Ready to publish' } });
};
close.onclick = () => {
  handle.dispose();
  instance.dispose();
  canvas.remove();
  update.remove();
  close.remove();
};
```

![The Builds KPI displays 24 beside a Release note reading Waiting for review; Update note and Close board appear above.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/22b0a37cd56cc47c8a7cf22c31baebbf.png)

`WidgetRenderer` receives the declared widget spec and its HTML host. It mounts once during ordinary rendering; the widget handle explicitly invokes it again for content updates.

| Operation or option | Type | Default | What it does |
| --- | --- | --- | --- |
| `renderWidget` | `WidgetRenderer` | Shipped painter | Fills each widget's host |
| `columns` | `number` | `12` | Sets the board's column count |
| `rowHeight` | `number` | `130` | Sets row height in grow mode |
| `update(patch)` | Partial `data`, `title`, `kind` fields | No patch | Replaces supplied fields and repaints; returns `void` |
| `repaint()` | No arguments | No automatic data binding | Reinvokes the painter with the current declared spec; returns `void` |

`update()` replaces `data`; it does not merge keys into the old payload. Supply every data field the painter needs. If your painter reads an external store, change that store and call `handle.widget('note')?.repaint()` to refresh the same host. Neither call recreates the widget node.

The handle calls are shared across bindings. For React widget components, Vue widget slots, Angular widget templates and Qwik widget components, use the complete mounted examples in [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard).

## Demos and next steps

- [Custom nodes live demo](https://grafloria.com/demos/nodes/custom-nodes.html) and its [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/nodes/custom-nodes.html): drag connected, custom-shaped nodes.
- [HTML nodes live demo](https://grafloria.com/demos/nodes/html-nodes.html): inspect rich content that moves with a node.
- [Dashboard builder live demo](https://grafloria.com/demos/dashboard/dashboard-builder.html): see the shipped painters on a rearrangeable board.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle): keep an instance and clean it up with its host.
- [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow): choose who owns spec data and return edits to that owner.
- [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections): constrain connections around custom content.

<!-- source: react-state-and-subscriptions.md -->

# React: state and subscriptions

Use controlled state when application UI needs the graph; use subscriptions when a toolbar or inspector needs the live selection or camera. The React binding forwards your specs into live models and returns committed edits through callbacks—it does not implement diagram behavior in React.

This example renders two connected nodes, a sibling Fit button, a selection inspector, a camera readout, and node coordinates backed by React state.

Install the binding and its peers in your React project:

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

## 1. Choose the state owner

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow) supports two ownership paths:

| Ownership | Props | What you get |
|---|---|---|
| Uncontrolled | `defaultNodes`, `defaultEdges` | The props seed the instance at mount. Later default arrays do not update it; use instance methods for subsequent changes. |
| Controlled | `nodes` with `onNodesChange`, `edges` with `onEdgesChange` | React owns plain specs, and the binding reconciles new arrays into the live model. Callbacks return model changes to React. |

Choose uncontrolled for a self-contained viewer or editor. Choose controlled when your application needs graph-derived UI or a server round-trip. For persistence, save the live document rather than the React projection; see [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

[`useNodesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#usenodesstate) returns `[nodes, setNodes, onNodesChange]`. [`useEdgesState`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useedgesstate) returns the equivalent edge tuple:

- The first element contains plain [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) or [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) values to pass to the component.
- The second element is a React state setter: use it to write application intent as specs.
- The third element accepts the engine's live models and converts them back to specs. Pass it to the matching change callback to close the return leg.

For the controlled-component pitfall, see the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start). The example below wires both return legs.

## 2. Share the instance with siblings and subscribe

Wrap the canvas and its sibling consumers in [`GrafloriaProvider`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaprovider). [`useGrafloria`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#usegrafloria) returns the live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance), or `null` before the canvas mounts. Disable instance-dependent controls while it is `null`.

Use [`useSelection`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useselection) for rendered selection state and [`useViewport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useviewport) for `{ zoom, x, y }`. If a consumer needs a callback rather than the current state, use [`useOnSelectionChange`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#useonselectionchange). Its inline handler stays current through a ref without resubscribing on each render. A consumer colocated with the canvas can instead use its `onSelectionChange` callback prop.

Replace your application's `App.tsx` with this component:

```tsx title="App.tsx"
import { useState } from 'react';
import {
  GrafloriaFlow,
  GrafloriaProvider,
  useEdgesState,
  useGrafloria,
  useNodesState,
  useOnSelectionChange,
  useSelection,
  useViewport,
} from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

const initialNodes: NodeSpec[] = [
  {
    id: 'extract', label: 'Extract',
    position: { x: 80, y: 100 }, size: { width: 150, height: 66 },
  },
  {
    id: 'load', label: 'Load',
    position: { x: 330, y: 180 }, size: { width: 150, height: 66 },
  },
];
const initialEdges: EdgeSpec[] = [
  { id: 'pipeline', source: 'extract', target: 'load' },
];

function Inspector() {
  const instance = useGrafloria();
  const selection = useSelection();
  const { zoom, x, y } = useViewport();
  const [selectionEvents, setSelectionEvents] = useState(0);

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

  return (
    <aside>
      <button disabled={!instance} onClick={() => instance?.fitView()}>
        Fit
      </button>
      <p>Selected: {selection.nodes.length} nodes, {selection.edges.length} edges</p>
      <p>Node ids: {selection.nodes.map((node) => node.id).join(', ') || 'none'}</p>
      <p>Zoom: {zoom.toFixed(2)}; origin: {x.toFixed(1)}, {y.toFixed(1)}</p>
      <p>Selection events: {selectionEvents}</p>
    </aside>
  );
}

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

  return (
    <>
      <button onClick={() => setNodes((current) => current.map((node) =>
        node.id === 'load' ? { ...node, label: 'Load records' } : node
      ))}>
        Rename Load
      </button>
      <ul>
        {nodes.map((node) => (
          <li key={node.id}>
            {node.label}: {node.position?.x.toFixed(1)}, {node.position?.y.toFixed(1)}
          </li>
        ))}
      </ul>
      <div style={{ height: 400 }}>
        <GrafloriaFlow
          nodes={nodes} onNodesChange={onNodesChange}
          edges={edges} onEdgesChange={onEdgesChange}
        />
      </div>
    </>
  );
}

export default function App() {
  return (
    <GrafloriaProvider>
      <Inspector />
      <Editor />
    </GrafloriaProvider>
  );
}
```

![Extract connects to Load beneath the coordinate list. Look at the sibling Fit button, Rename Load button, and selection and camera readouts above the canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3959b9ec88a82b32b7f99431e95fd05a.png)

Click a node to update the selection inspector and event counter. Drag a node and release it: the coordinate list catches up through `onNodesChange`. Click Rename Load to send a new spec array into the canvas; the second node's label becomes “Load records”. Click Fit to frame the content through the same instance the canvas uses; the camera readout follows viewport changes.

The return path reports document changes at commit points, not every frame of a drag. During the gesture, the core moves the model and paints the canvas directly. Keep the controlled arrays in state or memoize them: their reference is the effect dependency. A new array triggers reconciliation, not a remount; nodes with matching ids keep their live objects.

If the consumer is in the same component as the canvas, capture the instance with `onInit` in a React ref instead. Consumers passed as `GrafloriaFlow` children already have access to the flow's own store and need no outer provider. Siblings do need the shared provider shown above.

The binding refreshes callback refs on each render and keeps the instance for the mounted canvas. It unsubscribes and disposes the instance on unmount; the subscription hooks also return their unsubscribe functions from effects.

## 3. Adopt server markup at client mount

For an SSR application, call [`renderToStaticSVG`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#rendertostaticsvg) on the server. It returns the layer `html`, standalone `svg`, stylesheet `css`, and hydration `snapshot`. Pass the result to `ssr` with the same node and edge specs, and include its stylesheet so the diagram is styled before client JavaScript runs.

Here is a Next.js App Router example. The server page passes a serializable [`StaticRenderResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#staticrenderresult) into a client component; the client mounts the flow and exposes a Fit button through the provider.

```tsx title="app/page.tsx"
import { renderToStaticSVG } from '@grafloria/renderer';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import HydratedFlow from './HydratedFlow';

export default function Page() {
  const nodes: NodeSpec[] = [
    {
      id: 'extract', label: 'Extract',
      position: { x: 80, y: 100 }, size: { width: 150, height: 66 },
    },
    {
      id: 'load', label: 'Load',
      position: { x: 330, y: 180 }, size: { width: 150, height: 66 },
    },
  ];
  const edges: EdgeSpec[] = [
    { id: 'pipeline', source: 'extract', target: 'load' },
  ];
  const ssr = renderToStaticSVG({
    nodes, edges, width: 800, height: 400, instanceId: 'pipeline-ssr',
  });

  return (
    <>
      <style>{ssr.css}</style>
      <HydratedFlow nodes={nodes} edges={edges} ssr={ssr} />
    </>
  );
}
```

```tsx title="app/HydratedFlow.tsx"
'use client';

import { GrafloriaFlow, GrafloriaProvider, useGrafloria } from '@grafloria/react';
import type { EdgeSpec, NodeSpec, StaticRenderResult } from '@grafloria/renderer';

function FitButton() {
  const instance = useGrafloria();
  return (
    <button disabled={!instance} onClick={() => instance?.fitView()}>Fit</button>
  );
}

export default function HydratedFlow({ nodes, edges, ssr }: {
  nodes: NodeSpec[];
  edges: EdgeSpec[];
  ssr: StaticRenderResult;
}) {
  return (
    <GrafloriaProvider>
      <FitButton />
      <div style={{ width: 800, maxWidth: '100%', height: 400 }}>
        <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} ssr={ssr} />
      </div>
    </GrafloriaProvider>
  );
}
```

The server response contains the two nodes and their connecting edge. At client mount, the flow creates its live instance using the snapshot and adopts the existing diagram DOM instead of rebuilding it. After mount, you can select and drag nodes and use Fit. This version uses uncontrolled defaults: client-side edits belong to the instance.

The flow freezes the initial SSR markup for the component's lifetime. Later `ssr` values do not replace the DOM the instance owns. Custom HTML nodes are absent from the server render and mount on the client; built-in nodes, ports, edges, labels, and routing are present in the SVG.

## Options that matter

The ownership and hydration props belong to [`GrafloriaFlowProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflowprops). The callback types use [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) and [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel), not spec arrays. The [`HydrationSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#hydrationsnapshot) carries the instance scope, dimensions, zoom, and camera origin.

| Option | Type | Default | What it does |
|---|---|---|---|
| `nodes` / `edges` | `NodeSpec[]` / `EdgeSpec[]` | Omitted | Controls the corresponding data; new array references reconcile into the instance. |
| `defaultNodes` / `defaultEdges` | `NodeSpec[]` / `EdgeSpec[]` | Empty arrays when no controlled inputs exist | Seeds the initial model only. |
| `onNodesChange` / `onEdgesChange` | `(nodes: NodeModel[]) => void` / `(edges: LinkModel[]) => void` | Omitted | Receives live models; the state hooks supply the model-to-spec return handlers. |
| `onInit` | `(instance: DiagramInstance) => void` | Omitted | Receives the instance after the flow publishes it to its store. |
| `ssr` | `{ html: string; snapshot: HydrationSnapshot }` | Omitted | Emits initial server markup and supplies the snapshot for DOM adoption. |

Give each server-rendered diagram on a page a distinct `instanceId`.

## Live demos and related guides

- [React drag and undo demo](https://grafloria.com/demos-react/#/interaction/drag-undo): use toolbar actions against a mounted canvas.
- [Server-side export demo](https://grafloria.com/demos/misc/server-side-export.html): inspect a headless SVG result. This is an image preview, not an interactive hydration example.
- [Save and restore demo](https://grafloria.com/demos/interaction/save-and-restore.html): explore live-model persistence rather than saving React projections.
- [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow): follow the shared spec/model event paths.
- [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history): make application editing actions join the engine's undo stack.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas): configure appearance and container sizing.

<!-- source: react-custom-content.md -->

# React: custom content

Use React components when a node or dashboard widget needs application UI, context or local state. You paint the inside of the box; the engine owns its geometry and gestures. For a different silhouette or fill without application UI, use the shipped shapes instead; see [JavaScript: elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).

The examples below run in your React application's browser entry. Install the binding and its peers:

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

## 1. Render components inside connected nodes

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriaflow) maps `nodeTypes` keys to node `type` strings. Your component receives [`NodeProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#nodeprops):

- `id`: the node's id.
- `data`: the node's payload, not a separate set of component props.
- `selected`: the live selection state.
- `node`: the live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel), for queries or tracked setters beyond the other props.

Type the registry with [`NodeTypes`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#nodetypes), the nodes with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec), and the connections with [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec). Each custom spec below carries `custom: true`; for the HTML rendering opt-in, see [elements and content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/javascript-elements-and-content).

Replace your application's `App.tsx` with this example. It renders Build and Deploy cards connected by an edge. Each card reads the surrounding React context; the checkbox changes the owner line in both cards.

```tsx title="App.tsx"
import { createContext, useContext, useState } from 'react';
import {
  GrafloriaFlow,
  type NodeProps,
  type NodeTypes,
} from '@grafloria/react';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

type CardData = { title: string; owner: string };
const ShowOwners = createContext(true);

function Card({ id, data, selected }: NodeProps<CardData>) {
  const showOwners = useContext(ShowOwners);
  return (
    <div
      aria-label={`${data.title} (${id})`}
      style={{
        width: '100%',
        height: '100%',
        boxSizing: 'border-box',
        padding: '12px 16px',
        background: '#fff',
        color: '#232a3d',
        borderRadius: 12,
        border: selected ? '2px solid #3b52d9' : '2px solid #94a5f0',
        font: '14px/1.5 system-ui, sans-serif',
      }}
    >
      <strong>{data.title}</strong>
      {showOwners && <div>Owner: {data.owner}</div>}
    </div>
  );
}

const nodeTypes: NodeTypes = { card: Card };
const nodes: NodeSpec[] = [
  {
    id: 'build', type: 'card', custom: true,
    position: { x: 80, y: 90 }, size: { width: 230, height: 110 },
    data: { title: 'Build', owner: 'CI' },
  },
  {
    id: 'deploy', type: 'card', custom: true,
    position: { x: 430, y: 90 }, size: { width: 230, height: 110 },
    data: { title: 'Deploy', owner: 'CD' },
  },
];
const edges: EdgeSpec[] = [
  { id: 'build-deploy', source: 'build', target: 'deploy' },
];

export default function App() {
  const [showOwners, setShowOwners] = useState(true);
  return (
    <ShowOwners.Provider value={showOwners}>
      <label>
        <input
          type="checkbox"
          checked={showOwners}
          onChange={(event) => setShowOwners(event.target.checked)}
        />
        Show owners
      </label>
      <div style={{ height: 400 }}>
        <GrafloriaFlow
          defaultNodes={nodes}
          defaultEdges={edges}
          nodeTypes={nodeTypes}
          fitView
        />
      </div>
    </ShowOwners.Provider>
  );
}
```

![Build and Deploy cards connected by an arrow, with owner lines and the Show owners checkbox.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/1cf8a739328bad8a23f1dce58880db27.png)

Click a card to change its selection border, or drag it to move its box. The binding uses React portals, so context and hooks remain part of your application tree rather than a separate React root. Removing a node drops its portal and unmounts the component.

Give each node a `size` and fill that box with `width: '100%'`, `height: '100%'` and `boxSizing: 'border-box'`. Padding and borders then stay inside the geometry used for hit-testing and connections. Declare ports on the spec, not as elements inside the card; see [port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections).

### When node content refreshes

The binding refreshes custom components on `nodes:change` and `selection:change`, reading `node.isSelected()` again. It also observes the node's data and metadata writes and supplies a fresh `data` object. Use `node.setData()` rather than assigning payload properties directly.

Position changes during a drag move the host rather than triggering a content render on every frame. Keep positioning out of your component's styles. Your own React state and context still render normally.

These examples use uncontrolled defaults. For controlled data and its change-event return path, follow the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start).

## 2. Mix custom widgets with shipped painters

[`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadashboard) uses `widgetTypes` to map a widget's `kind` to a component. [`WidgetProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#widgetprops) supplies `{ widget, data }`: the full widget spec and its payload. Unlike nodes, dashboard widgets need no `custom` flag.

Use the shipped `kpi`, `line`, `bar`, `donut`, `funnel` and `table` painters for those kinds. Register a component only where you need your own UI; unmatched kinds pass to the built-in renderer.

> **Known issue:** A painter supplied through `options.renderWidget` never runs in the React binding: the wrapper overwrites that option with its portal callback. Until this is fixed, supply custom content through `widgetTypes` and keep `options` for board behavior and geometry.

The kit's intended custom-painting option is `options.renderWidget`; the React equivalent is `widgetTypes={{ note: Note }}`, used below. Type that mapping with [`WidgetTypes`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#widgettypes) and the data with [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec#dashboardwidgetspec).

Replace `App.tsx` with this independent example. It renders a shipped Revenue KPI beside a React release note. The note reads application context and keeps an acknowledgement count in local state. The toolbar switches the mounted board between fit and grow sizing.

```tsx title="App.tsx"
import { createContext, useContext, useState } from 'react';
import {
  GrafloriaDashboard,
  type WidgetProps,
  type WidgetTypes,
} from '@grafloria/react';
import type { DashboardWidgetSpec } from '@grafloria/element';

const Team = createContext('Release team');

function Note({ widget, data }: WidgetProps) {
  const team = useContext(Team);
  const [acknowledgements, setAcknowledgements] = useState(0);
  const text = typeof data.text === 'string' ? data.text : '';
  return (
    <section style={{
      width: '100%', height: '100%', boxSizing: 'border-box',
      padding: 16, background: '#eef2ff', color: '#232a3d',
      borderRadius: 10, font: '14px/1.5 system-ui, sans-serif',
    }}>
      <strong>{widget.title}</strong>
      <div>{team}</div>
      <p>{text}</p>
      <button onClick={() => setAcknowledgements((count) => count + 1)}>
        Acknowledge ({acknowledgements})
      </button>
    </section>
  );
}

const widgetTypes: WidgetTypes = { note: Note };
const widgets: DashboardWidgetSpec[] = [
  {
    id: 'revenue', kind: 'kpi', span: 3, rows: 1,
    data: { label: 'Revenue', value: '$6.81M', delta: 12.4 },
  },
  {
    id: 'release', kind: 'note', span: 3, rows: 1,
    title: 'Release note', data: { text: 'Deployment approved for Friday.' },
  },
];

export default function App() {
  const [sizing, setSizing] = useState<'fit' | 'grow'>('fit');
  return (
    <Team.Provider value="Release team">
      <button onClick={() => setSizing('fit')}>Fit rows</button>
      <button onClick={() => setSizing('grow')}>Grow rows</button>
      <span> Sizing: {sizing}</span>
      <div style={{ height: 400 }}>
        <GrafloriaDashboard
          widgets={widgets}
          widgetTypes={widgetTypes}
          options={{ columns: 6, gap: 8, rowHeight: 180 }}
          sizing={sizing}
        />
      </div>
    </Team.Provider>
  );
}
```

![Revenue KPI beside the release note, with Acknowledge (0), Fit rows and Grow rows controls and Sizing: fit.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/2a0dadac8f136a75c3cb7c94233570f6.png)

Custom widgets also mount through portals. Switching `sizing` calls the board handle rather than remounting the board, so the note's acknowledgement state remains intact.

## 3. Mount a spec without React content registrations

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-react#grafloriadiagram) when you already have a [`RenderSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#renderspec) rather than React node or widget components. It accepts plain diagram specs as well as kit specs. This independent `App.tsx` renders two connected, shipped silhouettes without a `nodeTypes` registry.

```tsx title="App.tsx"
import { GrafloriaDiagram } from '@grafloria/react';
import type { RenderSpec } from '@grafloria/element';

const spec: RenderSpec = {
  nodes: [
    {
      id: 'ingest', position: { x: 60, y: 80 },
      size: { width: 180, height: 80 }, label: 'Ingest',
      shape: { type: 'terminal', fill: '#ecfdf5', stroke: '#059669' },
    },
    {
      id: 'publish', position: { x: 380, y: 80 },
      size: { width: 180, height: 80 }, label: 'Publish',
      shape: { type: 'document', fill: '#fdf4ff', stroke: '#9333ea' },
    },
  ],
  edges: [{ id: 'ingest-publish', source: 'ingest', target: 'publish' }],
};

export default function App() {
  return (
    <div style={{ height: 400 }}>
      <GrafloriaDiagram spec={spec} options={{ fitView: true }} />
    </div>
  );
}
```

Unlike the mount-once dashboard inputs, a changed `spec` or `options` value replaces this component's diagram. An equal value rebuilt on a React render keeps the existing instance. For React components inside boxes, keep using `GrafloriaFlow` or `GrafloriaDashboard` above.

## Options that matter

Board geometry lives in [`DashboardOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardoptions#dashboardoptions). The following defaults come from the kit; the example explicitly selects fit sizing at first render.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `columns` | `number` | `12` | Sets the column count for views without an override. |
| `gap` | `number` | `8` | Sets the widget gap and board padding in pixels. |
| `rowHeight` | `number` | `130` | Sets row height in grow mode. |
| `sizing` | `'fit' \| 'grow'` | Grow for fluid boards; fit for fixed boards | Fit keeps the board height and squeezes rows; grow extends downward at `rowHeight`. |
| `layout` | `'grid' \| 'split'` | `'grid'` | Selects cells or a splitter tree; split always uses fit sizing. |
| `mode` | `'fluid' \| 'fixed'` | Fluid unless `width` is supplied | Fluid uses the container's CSS dimensions; fixed uses authored world dimensions. |

### Respect the mount-once board props

`views`, `widgets` and `options` seed the dashboard at mount. Replacing those props later does not rebuild or reconcile the board. Use either `views` for multiple boards or `widgets` for one board, not both.

The live props are `activeView`, `layout`, `sizing` and `static`. Changes call the handle's `showView()`, `setLayout()`, `setSizing()` and `setStatic()` respectively. Top-level `layout`, `sizing` and `static` override the corresponding `options` fields at mount.

For runtime widget edits, capture the [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle#dashboardhandle) with `onReady` and use its widget methods rather than replacing the initial array. Use `onLayoutChange` to receive the affected view's widgets after committed gestures. See [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) for handle-driven editing.

## Demos and related guides

- [Custom React nodes](https://grafloria.com/demos-react/#/nodes/html-nodes): components inside connected nodes.
- [Custom shapes](https://grafloria.com/demos/nodes/custom-nodes.html): use shipped silhouettes when no component is needed.
- [Dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html): a data-first board with shipped widget kinds.
- [React state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions): keep application state aligned with model events.
- [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas): size the canvas and integrate its appearance with your application.

<!-- source: vue-state-and-composables.md -->

# Vue: state and composables

Use uncontrolled defaults when the diagram owns its data. Use `v-model` when your application also edits the specs. In both cases, sibling toolbars and inspectors subscribe to the same live instance; save that instance's document rather than its reactive spec projection.

These examples run in a Vue 3.4+ browser application. Install the binding and its peers:

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

## 1. Choose the state owner

[`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow) reads `default-nodes` and `default-edges` at mount. Later changes to those defaults do not reconcile into the diagram. This form gives you two connected boxes that you can drag without maintaining application refs:

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

const nodes: NodeSpec[] = [
  { id: 'plan', label: 'Plan', position: { x: 80, y: 100 }, size: { width: 150, height: 60 } },
  { id: 'ship', label: 'Ship', position: { x: 340, y: 100 }, size: { width: 150, height: 60 } },
];
const edges: EdgeSpec[] = [{ id: 'plan-ship', source: 'plan', target: 'ship' }];
</script>

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

![Plan and Ship connected by an arrow on the uncontrolled canvas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f77d9c2031687179db0b2553b9dcc808.png)

The data uses the shared [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec) vocabulary. For controlled mode, bind both refs with `v-model:nodes` and `v-model:edges`, as in the next step. Inbound array replacements and in-place reactive edits reach the canvas; the binding skips its own emitted array when `v-model` writes it back.

Outbound updates are not a frame-by-frame mutation feed. Adds, removals and node drops produce spec updates; a selection click uses `selectionChange` instead. Read selection through that event or the composables, not through a saved `selected` field in the emitted specs.

## 2. Mount a controlled canvas and a sibling inspector

Wrap the canvas and its sibling in [`GrafloriaProvider`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaprovider). The flow publishes its live [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) to that provider at mount.

The example renders Plan → Ship and an inspector above it. **Add review** appends a third node through the controlled ref. **Save text** captures the current diagram; after dragging a box, **Restore text** reloads the saved document content.

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

const InspectorPanel = defineComponent({
  name: 'InspectorPanel',
  setup() {
    const grafloria = useGrafloria();
    const selection = useSelection();
    const viewport = useViewport();
    const lastSelection = ref('No selection event yet.');

    useOnSelectionChange((change) => {
      const ids = change.nodes.map((node) => node.id);
      lastSelection.value = ids.length ? ids.join(', ') : 'No nodes selected.';
    });

    return () => h('aside', [
      h('button', {
        disabled: !grafloria.value,
        onClick: () => grafloria.value?.fitView(40),
      }, 'Fit diagram'),
      h('p',
        `${selection.value.nodes.length} selected nodes · ` +
        `${selection.value.edges.length} selected edges · ` +
        `zoom ${viewport.value.zoom.toFixed(2)} · ` +
        `x ${viewport.value.x.toFixed(2)} · y ${viewport.value.y.toFixed(2)}`),
      h('p', lastSelection.value),
    ]);
  },
});

const nodes = ref<NodeSpec[]>([
  { id: 'plan', label: 'Plan', position: { x: 80, y: 100 }, size: { width: 150, height: 60 } },
  { id: 'ship', label: 'Ship', position: { x: 340, y: 100 }, size: { width: 150, height: 60 } },
]);
const edges = ref<EdgeSpec[]>([{ id: 'plan-ship', source: 'plan', target: 'ship' }]);
const instance = shallowRef<DiagramInstance | null>(null);
const flow = ref<InstanceType<typeof GrafloriaFlow> | null>(null);
const savedText = ref<string | null>(null);
const message = ref('Select or drag a box.');
let nextReview = 1;

function onInit(api: DiagramInstance): void {
  instance.value = api;
}

function addReview(): void {
  const number = nextReview++;
  nodes.value = [...nodes.value, {
    id: `review-${number}`,
    label: `Review ${number}`,
    position: { x: 80 + (number - 1) * 180, y: 240 },
    size: { width: 150, height: 60 },
  }];
}

function saveText(): void {
  const api = instance.value;
  if (!api) return;
  savedText.value = api.exportText();
  message.value = 'Saved. Move a box, then restore.';
}

function restoreText(): void {
  const api = instance.value;
  if (!api || savedText.value === null) return;
  try {
    api.loadText(savedText.value);
    api.renderNow();
    message.value = 'Restored the saved document content.';
  } catch (error) {
    message.value = error instanceof Error ? error.message : 'Restore failed.';
  }
}
</script>

<template>
  <GrafloriaProvider>
    <InspectorPanel />
    <div style="display: flex; gap: 8px; margin: 8px 0">
      <button :disabled="!instance" @click="addReview">Add review</button>
      <button :disabled="!instance" @click="saveText">Save text</button>
      <button :disabled="!instance || savedText === null" @click="restoreText">Restore text</button>
    </div>
    <p aria-live="polite">{{ message }}</p>
    <GrafloriaFlow
      ref="flow"
      v-model:nodes="nodes"
      v-model:edges="edges"
      @init="onInit"
      style="height: 400px"
    />
  </GrafloriaProvider>
</template>
```

![The controlled canvas with Plan and Ship, selection counts, zoom and camera coordinates, and Fit diagram, Add review, Save text and Restore text controls.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c907e22d11cb099746276c3048307065.png)

For the shared instance, selection and camera roles, see [React: state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions#2-share-the-instance-with-siblings-and-subscribe); in Vue, [`useGrafloria`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#usegrafloria), [`useSelection`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#useselection) and [`useViewport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#useviewport) return refs accessed through `.value` in render functions, and event subscriptions—including the callback registered with [`useOnSelectionChange`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#useonselectionchange)—tear down when the component's scope disposes.

`App.vue` defines and mounts `InspectorPanel` inside the provider alongside the canvas, so its composables subscribe to the diagram shown below it.

Click a box to update the counts and callback readout. The selection composable also reads the existing selection when it attaches, so an inspector mounted later starts with the current selection. **Fit diagram** frames the diagram and updates the camera readout.

Keep one flow per provider when siblings need an unambiguous instance. Without a provider above the sibling, its instance ref stays `null`. Children inside the flow's default slot can use the composables without an extra provider.

## 3. Choose the template ref or the instance

At runtime, the `flow` template ref in `App.vue` exposes these shortcuts. `@init` gives you the same underlying instance for renderer methods and engine access.

| Template-ref method | Result |
|---|---|
| `getInstance()` | The live instance, or `null` before mount. |
| `applyLayout(request)` | A promise that completes after running the named layout; emits `layoutDone`. |
| `snapshot()` | The live model's serialized document, or `null` before mount. |
| `exportSvg(options)` | A synchronous SVG export result, including warnings—not a bare string. |
| `exportPdf(options)` | A synchronous PDF export result—not a promise of a data URL. |
| `exportDiagram(format, options)` | The instance's asynchronous image/SVG export. |
| `exportText(options)` / `loadText(text, options)` | Text export and import on the live instance. |
| `fitView(padding)` | Frames the diagram content. |

> **Known issue:** The runtime template-ref methods are registered with `expose()` but are absent from the component's inferred public instance type. Until a typed ref surface is exported, capture the typed instance with `@init`, as in `App.vue`.

The intended template-ref call is `flow.value?.getInstance()`. The strict-TypeScript alternative in the sample is `onInit(api: DiagramInstance)`, storing `api` in a `shallowRef`. Use `instance.value?.fitView(40)` instead of `flow.value?.fitView(40)`, and `instance.value?.getModel().serialize()` instead of `flow.value?.snapshot()`. Do not redeclare the component's API to make a ref compile.

For command history, use the engine behind `getEngine()`; see [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history). For layout requests and their options, see [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram).

## 4. Separate projections from persistence

Controlled refs are application-facing projections, not the shared document. The node projection carries identity, type, position, size, data, label, sublabel, near-label placement, shape and the custom flag. It does not carry declared ports, arbitrary metadata, node styles or selection. The edge projection likewise does not carry every serialized link field. See [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for document snapshots and structured restoration.

The sample uses the instance's `exportText()` / `loadText()` pair rather than serializing `nodes.value`. By default, exported text includes a document sidecar. Loading it passes live nodes and links into the reconciler and restores groups and ink, without replacing the mounted diagram model or disconnecting its subscribers.

This is a document-content round trip, not a viewing-session restore: the text sidecar strips selected, hovered and focused state, and strips derived link polylines while retaining manual bends. `loadText()` does not apply the saved viewport to the active camera. The sample leaves the camera alone; use **Fit diagram** to frame the restored content.

> **Known issue:** `loadText(savedText)` does not restore the saved diagram name, arbitrary diagram-level metadata or anchored comments, even though the sidecar saves them. Until the loader restores those fields, use the full-document restoration path in [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) when you need lossless persistence; use this sample only for its node, link, group and ink round trip.

The loader copies only its explicit grammar-metadata keys, such as `diagramType`, `direction` and kit specs. It leaves other diagram-level fields on the existing model unchanged. A full snapshot from `instance.value?.getModel().serialize()` includes the name, metadata and comments; restoring that document through the full-document path avoids this text-loader boundary.

For externally edited specs with reused ids, follow the replacement procedure in [Vue quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-quick-start), rather than treating a spec assignment as a full-document restore.

## Options that matter

| Option | Type | Default | What it does |
|---|---|---|---|
| `nodes` | `NodeSpec[]` | `undefined` | Controls nodes; enables `update:nodes` for the return path. |
| `edges` | `EdgeSpec[]` | `undefined` | Controls edges; enables `update:edges` for the return path. |
| `defaultNodes` | `NodeSpec[]` | `undefined` | Seeds nodes once when no controlled nodes are supplied. |
| `defaultEdges` | `EdgeSpec[]` | `undefined` | Seeds edges once when no controlled edges are supplied. |

Do not listen for `update:nodes` on an uncontrolled canvas expecting a spec feed: the binding emits it only when `nodes` is bound. Use `@selection-change` for a parent-owned selection handler, or the provider composables for a sibling inspector.

## Live demos and related guides

- [Mermaid viewer](https://grafloria.com/demos/misc/mermaid-viewer.html) shows text-driven diagram updates; [Vue source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/apps/demos-vue/src/demos/mermaid-viewer.vue).
- [Save & restore](https://grafloria.com/demos/interaction/save-and-restore.html) demonstrates snapshot and operation-history persistence.
- [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) explains controlled inputs and the return path across bindings.
- [Vue: slots and widgets](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-slots-and-widgets) covers custom content inside a flow.

<!-- source: vue-slots-and-widgets.md -->

# Vue: slots and widgets

Use slots when a node or dashboard tile needs Vue content rather than a stock shape or chart. You paint the interior; the engine keeps the geometry. This page shows exact and wildcard node slots, a reactive child component, and a two-view dashboard with live layout, sizing and viewer switches.

In your Vue 3.4+ project, install the binding and its peers:

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

## 1. Match node types to slots

On [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriaflow), declaring `#node-job` opts specs with `type: 'job'` into HTML rendering. The wildcard `#node` catches already-custom nodes without an exact slot; it does not opt them in. Set `custom: true` for that path. An explicit `custom: false` keeps a node in SVG even when an exact slot exists.

The slot context, [`NodeSlotProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#nodeslotprops), contains:

- `node`: the live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel), not a spec copy.
- `data`: the node's payload, or `{}`.
- `engine`: the [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine) that owns behavior.

The following files draw two connected cards. Build uses the exact slot; Deploy uses the wildcard. Type the specs with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec).

## 2. Keep live content in a child component

> **Known issue:** In-place live-model data changes do not re-invoke node slots. Until this is fixed, put live content in a child component that reads your own reactive source.

The intended model write is `node.setData('status', 'passing')`. The flow repaints slots on `nodes:change`, not on an in-place data change. For a card that needs live updates, use a reactive map keyed by node id instead. The mounted child tracks that map independently of canvas repainting.

Create these three files. The **Mark Build passing** button changes the visible status in the Build card without adding or removing nodes.

```ts title="job-state.ts"
import { reactive } from 'vue';

export const jobs = reactive<Record<string, { title: string; status: string }>>({
  build: { title: 'Build', status: 'running' },
  deploy: { title: 'Deploy', status: 'ready' },
});
```

```vue title="JobCard.vue"
<script setup lang="ts">
import { jobs } from './job-state';

defineProps<{ nodeId: string }>();
</script>

<template>
  <article class="job-card">
    <strong>{{ jobs[nodeId]?.title }}</strong>
    <p>Status: {{ jobs[nodeId]?.status }}</p>
  </article>
</template>

<style scoped>
.job-card {
  height: 100%;
  box-sizing: border-box;
  padding: 16px;
  border: 2px solid #2563eb;
  border-radius: 10px;
  background: #eff6ff;
  color: #172554;
  font: 14px/1.4 system-ui, sans-serif;
}
</style>
```

```vue title="App.vue"
<script setup lang="ts">
import { GrafloriaFlow, type NodeSpec, type EdgeSpec } from '@grafloria/vue';
import JobCard from './JobCard.vue';
import { jobs } from './job-state';

const nodes: NodeSpec[] = [
  {
    id: 'build', type: 'job', position: { x: 60, y: 90 },
    size: { width: 220, height: 110 }, data: { owner: 'CI' },
  },
  {
    id: 'deploy', type: 'release', custom: true,
    position: { x: 390, y: 90 }, size: { width: 220, height: 110 },
    data: { owner: 'CD' },
  },
];
const edges: EdgeSpec[] = [
  { id: 'build-deploy', source: 'build', target: 'deploy' },
];

function markPassing() {
  const build = jobs.build;
  if (build) build.status = 'passing';
}
</script>

<template>
  <button @click="markPassing">Mark Build passing</button>
  <div style="height: 400px">
    <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" fit-view>
      <template #node-job="{ node }">
        <JobCard :node-id="node.id" />
      </template>
      <template #node="{ node }">
        <JobCard :node-id="node.id" />
      </template>
    </GrafloriaFlow>
  </div>
</template>
```

![Build and Deploy cards connected by an arrow, with running and ready statuses and the Mark Build passing button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/acf57cabed039ddee9f37da8d1c9a6f9.png)

The spec's `size` determines each footprint; `height: 100%` and `box-sizing: border-box` make the card fill it. Custom node content lives in light DOM, so the child component's scoped stylesheet applies. For canvas sizing, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

Use a slot for components and controls, not to recreate a stock silhouette. For rectangles, terminals or documents, use the spec's `shape` instead; compare the [custom-shaped nodes demo](https://grafloria.com/demos/nodes/custom-nodes.html).

## 3. Render widget slots and switch the live board

On [`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadashboard), declare `#widget-<kind>` slots instead of React's `widgetTypes`; see [React: custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content) for the shared [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec#dashboardwidgetspec) payload contract and shipped-painter fallback.

Replace `App.vue` with the following independent dashboard sample. Overview opens with a shipped KPI painter and a Vue note slot. Operations contains another note. Your buttons supply the tab bar: `v-model:active-view` asks the wrapper to show the selected view.

Capture the [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle#dashboardhandle) through `@ready` in a `shallowRef`. **Update note** calls the [`WidgetHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-widgethandle#widgethandle)'s `update()` method, which replaces the payload and repaints the slot.

```vue title="App.vue"
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { GrafloriaDashboard } from '@grafloria/vue';
import type { DashboardHandle, DashboardWidgetSpec } from '@grafloria/element';

const handle = shallowRef<DashboardHandle | null>(null);
const tab = ref('overview');
const layout = ref<'grid' | 'split'>('grid');
const sizing = ref<'fit' | 'grow'>('fit');
const viewer = ref(false);
const options = { columns: 6, gap: 10 };
const overviewWidgets: DashboardWidgetSpec[] = [
  {
    id: 'revenue', kind: 'kpi', span: 3, rows: 1,
    data: { label: 'Total revenue', value: '$6.81M', delta: 12.4,
      spark: [3.9, 4.4, 4.1, 5.2, 5.9, 6.8] },
  },
  {
    id: 'summary', kind: 'note', title: 'Release summary', span: 3, rows: 1,
    data: { text: 'Build is running.' },
  },
];
const operationsWidgets: DashboardWidgetSpec[] = [
  {
    id: 'operations-note', kind: 'note', title: 'Operations', span: 6, rows: 1,
    data: { text: 'Deployment window opens at 14:00.' },
  },
];
const views = [
  { id: 'overview', name: 'Overview', widgets: overviewWidgets },
  { id: 'operations', name: 'Operations', widgets: operationsWidgets },
];

function updateNote() {
  handle.value?.widget('summary')?.update({
    data: { text: 'Build passed. Ready to deploy.' },
  });
}
</script>

<template>
  <nav aria-label="Dashboard views">
    <button v-for="view in views" :key="view.id"
      :aria-pressed="tab === view.id" @click="tab = view.id">
      {{ view.name }}
    </button>
  </nav>
  <div class="controls">
    <button @click="layout = 'grid'">Grid</button>
    <button @click="layout = 'split'">Split</button>
    <button @click="sizing = 'fit'">Fit</button>
    <button @click="sizing = 'grow'">Grow</button>
    <label><input v-model="viewer" type="checkbox" /> Viewer mode</label>
    <button :disabled="!handle || tab !== 'overview'" @click="updateNote">
      Update note
    </button>
  </div>
  <div style="height: 400px">
    <GrafloriaDashboard :views="views" :options="options"
      v-model:active-view="tab" :layout="layout" :sizing="sizing"
      :static="viewer" @ready="handle = $event">
      <template #widget-note="{ widget, data }">
        <article class="note">
          <strong>{{ widget.title }}</strong>
          <p>{{ data.text }}</p>
        </article>
      </template>
    </GrafloriaDashboard>
  </div>
</template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; gap: 6px; margin: 8px 0; }
.note {
  height: 100%;
  box-sizing: border-box;
  padding: 16px;
  background: #fffbeb;
  color: #78350f;
  font: 14px/1.4 system-ui, sans-serif;
}
</style>
```

![Overview shows a revenue KPI and Release summary note beneath the view buttons, layout and sizing switches, Viewer mode checkbox and Update note button.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/af868db3f8a08af9caec5f98b33b960b.png)

**Split** changes every view to a splitter tree with percentage dividers; **Grid** returns them to cells. These switches call the existing handle, not a remount. In grid mode, **Fit** keeps the board height and squeezes rows; **Grow** keeps row height and extends the board downward. Split layout always uses fit sizing. **Viewer mode** disables pointer dragging and resizing and removes handles.

## 4. Mount a spec without slot content

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-vue#grafloriadiagram) when you have a complete [`RenderSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#renderspec) rather than node or widget slots. This independent sample draws a stock Build node connected to Deploy. The generic host mounts the spec; changing the spec's value replaces the diagram, while rebuilding an equal spec does not.

```vue title="App.vue"
<script setup lang="ts">
import { GrafloriaDiagram, type NodeSpec, type EdgeSpec } from '@grafloria/vue';
import type { RenderSpec } from '@grafloria/element';

const nodes: NodeSpec[] = [
  { id: 'build', label: 'Build', position: { x: 60, y: 90 },
    size: { width: 180, height: 80 } },
  { id: 'deploy', label: 'Deploy', position: { x: 340, y: 90 },
    size: { width: 180, height: 80 } },
];
const edges: EdgeSpec[] = [
  { id: 'build-deploy', source: 'build', target: 'deploy' },
];
const spec: RenderSpec = { nodes, edges };
</script>

<template>
  <div style="height: 400px">
    <GrafloriaDiagram :spec="spec" :options="{ fitView: true }" />
  </div>
</template>
```

## Options and pitfalls

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| Node `custom` | `boolean` | Exact-slot opt-in when omitted | `true` permits wildcard rendering; `false` overrides an exact slot. |
| Widget `span` / `rows` | `number` / `number` | `3` / `1` | Sets column and row spans. Omit `x` and `y` to flow in declaration order. |
| Dashboard `layout` | `'grid' \| 'split'` | Prop unset; kit uses `'grid'` | Overrides options at mount; later changes affect all views. |
| Dashboard `sizing` | `'fit' \| 'grow'` | Prop unset; fluid boards use `'grow'`, fixed boards use `'fit'` | Overrides options at mount and calls `setSizing()` on changes. |
| Dashboard `static` | `boolean` | Prop unset | Overrides options at mount and calls `setStatic()` on changes. |
| Dashboard `activeView` | `string` | Prop unset | Chooses the visible view; mount emits the initial id through `update:activeView`. |

The dashboard wrapper owns `options.renderWidget` and `options.onLayoutChange` and overwrites both. Use widget slots and `@layout-change` instead. That event carries `{ viewId, widgets }`, with widget specs containing their current cells.

Unlike a live-model node-data mutation, `widget(id)?.update({ data: ... })` explicitly repaints widget content. Use it for payload changes rather than expecting a changed declaration array to refresh an existing dashboard.

The binding cleans up its mounted content and instance on unmount; do not dispose the handle immediately after `@ready`.

## Live demos and related guides

- [Dashboard builder](https://grafloria.com/demos/dashboard/dashboard-builder.html): shipped widget painters and multiple views.
- [Fluid dashboard](https://grafloria.com/demos/dashboard/fluid-board.html): live sizing and layout switches; [Vue source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/apps/demos-vue/src/demos/fluid-board.vue).
- [Vue: state and composables](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/vue-state-and-composables): controlled flow data and access from child components.
- [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard): the board's layout and widget operations.
- [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents): persistence rather than framework spec projections.

<!-- source: angular-state-and-tooling.md -->

# Angular: state and tooling

Use this pattern when your Angular application owns the diagram state and needs an editor around it. You get two connected nodes, camera bindings, history buttons, interaction settings, a selection-driven node toolbar, and a property panel.

The binding is a thin skin over the headless model: your specs describe intent, the live models hold data, and the engine owns behavior. Use [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) for the canvas and its everyday methods; reach through `activeEngine()` only for tools that require the engine.

## 1. Set the application default

In an Angular 18.1–22 application, install the binding and its peers:

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

[`provideGrafloria`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#providegrafloria) accepts a [`GrafloriaConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#grafloriaconfig). Its theme applies to canvases without an explicit `[theme]` input; an explicit input wins. This example uses the shipped [`DARK_THEME`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants#dark_theme).

```ts title="src/main.ts"
import { bootstrapApplication } from '@angular/platform-browser';
import { provideGrafloria } from '@grafloria/angular';
import { DARK_THEME } from '@grafloria/renderer';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [provideGrafloria({ theme: DARK_THEME })],
}).catch(console.error);
```

## 2. Bind state and mount the supplied tools

Bind all four `model()` signals: `[(nodes)]`, `[(edges)]`, `[(viewport)]`, and `[(zoom)]`. Each also exposes its next-value output: `nodesChange`, `edgesChange`, `viewportChange`, and `zoomChange`. Plain properties and writable signals both work.

Type the collections with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec). The inputs also accept live [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) and [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel) objects. Keeping the input's full type in the sample accommodates the two-way output contract, including `undefined`.

The supplied [`InteractionConfigPanelComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interactionconfigpanelcomponent#interactionconfigpanelcomponent) reads and updates the mounted canvas's engine. Its `configChanged` output reports the partial configuration it applies; you do not need to apply it again.

The supplied [`NodeToolbarComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-nodetoolbarcomponent#nodetoolbarcomponent) renders actions for the selected live node. Use the shipped [`createDuplicateAction`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions#createduplicateaction) rather than implementing duplication yourself.

The sample also mounts [`LinkToolbarComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-linktoolbarcomponent#linktoolbarcomponent) for the selected edge, using the shipped [`createDeleteLinkAction`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions#createdeletelinkaction). It disables the canvas's hosted edge toolbar to avoid displaying two toolbars.

> **Known issue:** Binding the canvas's camera rectangle directly to the node toolbar's `[viewport]` mispositions it after pan or zoom: the toolbar treats `x` and `y` as pixel translations. Until it is fixed, derive those translations from `(viewportChanged)`, the visible world rectangle, as the sample does.

The intended toolbar binding is `[viewport]="viewport()"`. The runnable version below instead uses `[viewport]="toolbarViewport()"` and updates it from the visible rectangle.

Use [`PropertyPanelComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-propertypanelcomponent#propertypanelcomponent) with a schema registered through [`PropertyPanelService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services-propertypanelservice#propertypanelservice). The schema uses the shipped string editor. [`PropertySchema`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-b-s#propertyschema) describes the fields, while [`PropertyDiagramNode`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services#propertydiagramnode) supplies their values.

> **Known issue:** The property service writes directly into `node.data`, without issuing a model mutation or an engine command. Until it is fixed, edit detached drafts and return their values through controlled specs. This updates the diagram, but these property edits do not join the undo stack or emit `modelChange`.

```ts title="src/app/app.component.ts"
import {
  AfterViewInit, Component, ElementRef, OnDestroy,
  computed, effect, signal, viewChild,
} from '@angular/core';
import {
  DiagramCanvasComponent, InteractionConfigPanelComponent,
  NodeToolbarComponent, LinkToolbarComponent, PropertyPanelComponent, PropertyPanelService,
  createDuplicateAction, createDeleteLinkAction,
  type PropertyDiagramNode, type ToolbarAction, type LinkToolbarAction,
} from '@grafloria/angular';
import { NodeModel, type LinkModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec, PropertySchema } from '@grafloria/renderer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    DiagramCanvasComponent, InteractionConfigPanelComponent,
    NodeToolbarComponent, LinkToolbarComponent, PropertyPanelComponent,
  ],
  providers: [PropertyPanelService],
  template: `
    <nav aria-label="Diagram actions">
      <button type="button" (click)="undo()">Undo</button>
      <button type="button" (click)="redo()">Redo</button>
      <button type="button" (click)="canvas().zoomIn()">Zoom in</button>
      <button type="button" (click)="canvas().zoomOut()">Zoom out</button>
      <button type="button" (click)="canvas().fitToContent(40)">Fit</button>
      <button type="button" (click)="flush()">Flush changes</button>
    </nav>
    <p>{{ status() }} · Zoom: {{ zoom() }}</p>
    <div style="display:flex; flex-wrap:wrap; gap:16px">
      <div #host style="position:relative; flex:1 1 480px; min-width:0; height:400px">
        <grafloria-diagram-canvas
          [(nodes)]="nodes" [(edges)]="edges"
          [(viewport)]="viewport" [(zoom)]="zoom"
          [plugins]="true"
          [enableLinkToolbar]="false"
          (modelChange)="recordPatch($event)"
          (selectionChange)="select($event.nodes, $event.edges)"
          (viewportChanged)="visibleRect.set($event)"
          style="display:block; height:100%" />
        @if (canvas().activeEngine(); as engine) {
          @if (selected(); as node) {
            <grafloria-node-toolbar
              [node]="node" [engine]="engine"
              [canvasElement]="host"
              [viewport]="toolbarViewport()" [zoom]="zoom()"
              [actions]="actions()" [visible]="true" />
          }
          @if (selectedEdge(); as link) {
            <grafloria-link-toolbar
              [link]="link" [engine]="engine" [canvasElement]="host"
              [viewport]="viewport()" [zoom]="zoom()"
              [actions]="linkActions()" />
          }
        }
      </div>
      <aside style="width:280px">
        @if (canvas().activeEngine(); as engine) {
          <grafloria-interaction-config-panel
            [engine]="engine" [expanded]="true"
            (configChanged)="status.set('Interaction settings changed')" />
        }
        <diagram-property-panel
          [updateMode]="'immediate'"
          (propertyChanged)="commitDrafts()"
          (validationError)="status.set('Check the property value')" />
      </aside>
    </div>
    <pre>{{ lastPatch() }}</pre>
  `,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  canvas = viewChild.required(DiagramCanvasComponent);
  propertyPanel = viewChild(PropertyPanelComponent);
  host = viewChild.required<ElementRef<HTMLElement>>('host');
  nodes = signal<readonly (NodeSpec | NodeModel)[] | undefined>([
    { id: 'a', type: 'task', label: 'Extract', data: { label: 'Extract' },
      position: { x: 80, y: 100 }, size: { width: 140, height: 70 } },
    { id: 'b', type: 'task', label: 'Load', data: { label: 'Load' },
      position: { x: 320, y: 100 }, size: { width: 140, height: 70 } },
  ]);
  edges = signal<readonly (EdgeSpec | LinkModel)[] | undefined>([
    { id: 'ab', source: 'a', target: 'b' },
  ]);
  viewport = signal({ x: 0, y: 0, width: 800, height: 400 });
  zoom = signal(1);
  visibleRect = signal({ x: 0, y: 0, width: 800, height: 400 });
  toolbarViewport = computed(() => {
    const rect = this.visibleRect();
    return { x: -rect.x * this.zoom(), y: -rect.y * this.zoom(),
      width: rect.width, height: rect.height };
  });
  selected = signal<NodeModel | null>(null);
  selectedEdge = signal<LinkModel | null>(null);
  drafts = signal<PropertyDiagramNode[]>([]);
  actions = computed<ToolbarAction[]>(() => {
    const engine = this.canvas().activeEngine();
    return engine ? [createDuplicateAction(engine)] : [];
  });
  linkActions = computed<LinkToolbarAction[]>(() => {
    const engine = this.canvas().activeEngine();
    return engine ? [createDeleteLinkAction(engine)] : [];
  });
  status = signal('Select a node to edit its label');
  lastPatch = signal('');
  private resizeObserver?: ResizeObserver;

  constructor(properties: PropertyPanelService) {
    const schema: PropertySchema = {
      properties: [{ key: 'label', label: 'Label', editor: 'string' }],
    };
    properties.registerSchema('task', schema);
    effect(() => {
      const panel = this.propertyPanel();
      const drafts = this.drafts();
      if (panel) panel.selectedNodes = drafts;
    });
  }

  ngAfterViewInit(): void {
    this.resizeObserver = new ResizeObserver(() => this.canvas().scheduleRender());
    this.resizeObserver.observe(this.host().nativeElement);
  }

  select(nodes: NodeModel[], edges: LinkModel[]): void {
    this.selected.set(nodes[0] ?? null);
    this.selectedEdge.set(edges[0] ?? null);
    this.drafts.set(nodes.map(node => ({
      id: node.id, type: node.type, data: { ...node.data },
    })));
  }

  commitDrafts(): void {
    this.nodes.update(nodes => (nodes ?? []).map(node => {
      if (node instanceof NodeModel) return node;
      const draft = this.drafts().find(item => item.id === node.id);
      if (!draft || typeof draft.data['label'] !== 'string') return node;
      return { ...node, label: draft.data['label'], data: { ...draft.data } };
    }));
    this.status.set('Label returned through controlled specs');
  }

  recordPatch(patch: Parameters<DiagramCanvasComponent['modelChange']['emit']>[0]): void {
    this.lastPatch.set(JSON.stringify(patch, null, 2));
    this.status.set('Engine change captured');
  }

  async undo(): Promise<void> { await this.canvas().undo(); }
  async redo(): Promise<void> { await this.canvas().redo(); }
  flush(): void { this.canvas().flushModelChange(); }
  ngOnDestroy(): void { this.resizeObserver?.disconnect(); }
}
```

![Extract connects to Load on a dotted canvas, with history and camera buttons above, a minimap below, and expanded interaction settings on the right.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/0a255185dba0c50a48ee4c3f32f3f5f0.png)

On load, the canvas contains Extract connected to Load, with the supplied minimap and zoom/fit controls. The settings panel opens expanded; the property panel starts in its empty state. Select a node to show its Duplicate toolbar and Label editor. Editing Label returns a new spec array to the canvas. Dragging a node updates the two-way collections and displays the engine's incremental patch beneath the editor.

Select the edge to show its Delete toolbar. The property panel receives drafts through its `selectedNodes` setter, reached with `viewChild`, rather than a template binding.

## 3. Consume patches and component methods

`modelChange` describes added, removed, and modified entities. It accompanies the next-array outputs, but fires only for engine-originated changes: inbound `[nodes]` and `[edges]` writes are not echoed. Use it to persist user changes rather than saving your own inbound writes again.

The canvas coalesces engine events in a microtask. `flushModelChange()` synchronously drains the pending capture window; it returns `void` and emits nothing when no change exists. The sample's Flush changes button exercises that call without fabricating a patch. The JSON readout is an inspection hook, not a complete persistence store; save the live document as described in [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents).

`viewChild.required(DiagramCanvasComponent)` gives you the mounted component. `undo()` and `redo()` return `Promise<void>`; the sample awaits them. `zoomIn()`, `zoomOut()`, and `fitToContent()` change the camera. Engine access is available from `ngAfterViewInit` onward. History availability belongs to the engine's `canUndo()` and `canRedo()`, not to component methods of those names.

Persist `viewportChange`, the camera rectangle used by the input. Use `viewportChanged` for the visible world rectangle after zoom or pan; they are not interchangeable.

## Responsive canvases

[`ResponsiveCanvasDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#responsivecanvasdirective) uses the selector `[grafloriaResponsiveCanvas]`. Its `[engine]` input expects [`IResponsiveCanvasEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#iresponsivecanvasengine), not the canvas's [`DiagramEngine`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine#diagramengine).

> **Known issue:** `[engine]="canvas().activeEngine()"` cannot wire the responsive directive to this canvas: its engine contract requires `getZoom()`, `getPan()`, and `setPan()`, which the diagram engine does not implement. Until it is fixed, observe the wrapper and call `scheduleRender()`, as the mounted sample does.

The observer requests a repaint after the wrapper changes size. The canvas measures that wrapper when deriving its rendered viewport. Cleanup disconnects the observer on component destruction. For wrapper sizing rules, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas).

## Options that matter

| Option | Type | Default | What it does |
|---|---|---|---|
| `nodes` | `readonly (NodeSpec \| NodeModel)[] \| undefined` | `undefined` | Controls nodes; unbound leaves the engine's node set alone. |
| `edges` | `readonly (EdgeSpec \| LinkModel)[] \| undefined` | `undefined` | Controls edges and returns the next collection. |
| `skipModelUpdate` | `boolean` | `false` | Suspends inbound reconciliation only; outbound emissions continue. Switching back resumes synchronization. |
| `viewport` | Rectangle with numeric `x`, `y`, `width`, `height` | `{ x: 0, y: 0, width: 800, height: 600 }` | Two-way camera rectangle. |
| `zoom` | `number` | `1` | Two-way zoom level. |
| Settings panel `expanded` | `boolean` | `false` | Opens the panel on initialization when true. |
| Settings panel `showAdvanced` | `boolean` | `true` | Includes advanced settings. |
| Property panel `updateMode` | `'immediate' \| 'deferred'` | `'immediate'` | Applies valid edits immediately or holds them until Save. |
| Property panel `showHeader` | `boolean` | `true` | Displays the selected-node header. |
| Property panel `collapsibleGroups` | `boolean` | `true` | Lets the reader collapse property groups. |

## Pitfalls and alternatives

- Leave `nodes` and `edges` unbound and supply `[engine]` for uncontrolled use. In controlled use, keep the next-value return path: two-way binding provides it in this sample.
- Use the property panel's UI output for UI edits. Its `propertyChanged` payload has `nodes`, `property`, and `value`; the service's change observable uses a different payload with `propertyKey` and `newValue`.
- [`PropertyEditorRegistryService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services#propertyeditorregistryservice) registers the built-in editors on initialization. Register a custom editor only when a shipped editor does not cover your field.
- [`AutoToolbarDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#autotoolbardirective) and [`NodeToolbarService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#nodetoolbarservice) offer automatic selection-based and programmatic toolbar management. The sample uses the component directly so it can pass the corrected viewport translation through Angular inputs.
- Edges already have a hosted toolbar: hover or select an edge to expose its default delete and insert-node actions. Configure it through the canvas's `enableLinkToolbar`, `linkToolbarActions`, and `linkToolbarAnchor` inputs when you do not need the explicit selection-driven toolbar shown here.
- For data changes that also need layout, follow [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram).

## Live demos and related guides

Explore the [node toolbar demo](https://grafloria.com/demos/nodes/node-toolbar.html), the [shape data panel demo](https://grafloria.com/demos/diagrams/shape-data.html), and [minimap and controls](https://grafloria.com/demos/misc/minimap-and-controls.html). Their Angular variants are available in the [Angular gallery](https://grafloria.com/demos-angular/).

Continue with [Angular templates and handles](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-templates-and-handles), [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow), or [Commands and history](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/commands-and-history).

<!-- source: angular-templates-and-handles.md -->

# Angular: templates and handles

Use projected Angular templates when a node or dashboard widget needs your own HTML, bindings or controls. The examples below render two connected cards, then a two-view dashboard with a custom note and a shipped KPI painter. Your template paints inside a box; the engine and renderer still own its position and geometry.

In your Angular application, install the binding and its peers. Use Angular 18.1 or a supported major from 19 through 22.

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

## 1. Project typed and wildcard node templates

Import both [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent#diagramcanvascomponent) and [`GrafloriaNodeDefDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#graflorianodedefdirective). A `grafloriaNode="ticket"` template matches the node's `type` exactly. In controlled mode that match opts the spec into HTML rendering without a `custom` flag.

A bare `grafloriaNode` is the wildcard fallback, not an opt-in: set `custom: true` on an unmatched spec to send it to the HTML layer. Exact templates take precedence.

The controlled data below adds template matching, wildcard opt-in and named ports; see [Angular: state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling) for typing arrays with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec), [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec), [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel#nodemodel) and [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel#linkmodel).

The [`GrafloriaNodeTemplateContext`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#graflorianodetemplatecontext) supplies the live model as `let-node`, its payload as `let-data="data"`, and the engine as `let-engine="engine"`. Read payload keys with index syntax.

### Attach HTML connection handles

Import [`GrafloriaHandleDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core#grafloriahandledirective) and use its declared selector, `grafloriaHandle="source"` or `grafloriaHandle="target"`. Put it inside the node template. The canvas wrapper supplies the ancestor `data-node-id` that the directive uses to register the element; destruction unregisters it.

This browser component renders “Review login” through the typed template and “Release” through the wildcard. Each card has an HTML handle, and the edge names the corresponding port ids. The CSS places the handles at the same sides as the declared ports.

```ts title="ticket-board.component.ts"
import { Component } from '@angular/core';
import {
  DiagramCanvasComponent,
  GrafloriaHandleDirective,
  GrafloriaNodeDefDirective,
} from '@grafloria/angular';
import type { LinkModel, NodeModel } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';

@Component({
  selector: 'app-ticket-board',
  standalone: true,
  imports: [DiagramCanvasComponent, GrafloriaNodeDefDirective, GrafloriaHandleDirective],
  template: `
    <grafloria-diagram-canvas [(nodes)]="nodes" [(edges)]="edges"
      style="display:block; height:400px">
      <ng-template grafloriaNode="ticket" let-data="data">
        <article class="card">
          <strong>{{ data['title'] }}</strong>
          <p>Assigned to {{ data['assignee'] }}</p>
          <span class="handle output" grafloriaHandle="source"
            handleId="out" handlePosition="right" aria-label="Output"></span>
        </article>
      </ng-template>
      <ng-template grafloriaNode let-node let-data="data">
        <article class="card fallback">
          <strong>{{ data['title'] }}</strong>
          <p>{{ node.id }}</p>
          <span class="handle input" grafloriaHandle="target"
            handleId="in" handlePosition="left" aria-label="Input"></span>
        </article>
      </ng-template>
    </grafloria-diagram-canvas>
  `,
  styles: [`
    .card { position:relative; width:100%; height:100%; box-sizing:border-box;
      padding:16px; border:2px solid #6478d3; border-radius:10px;
      background:white; color:#243047; font:14px system-ui; }
    .fallback { border-color:#059669; }
    .handle { position:absolute; top:50%; width:12px; height:12px;
      border:2px solid white; border-radius:50%; background:#334155;
      transform:translate(-50%, -50%); cursor:crosshair; }
    .output { left:100%; } .input { left:0; }
  `],
})
export class TicketBoardComponent {
  nodes: readonly (NodeSpec | NodeModel)[] = [
    {
      id: 'review', type: 'ticket', position: { x: 60, y: 100 },
      size: { width: 220, height: 110 },
      data: { title: 'Review login', assignee: 'Nour' },
      ports: [{ id: 'out', side: 'right', type: 'output' }],
    },
    {
      id: 'release', type: 'release', custom: true,
      position: { x: 420, y: 100 }, size: { width: 180, height: 110 },
      data: { title: 'Release' },
      ports: [{ id: 'in', side: 'left', type: 'input' }],
    },
  ];
  edges: readonly (EdgeSpec | LinkModel)[] = [
    { id: 'review-release', source: 'review', target: 'release',
      sourceHandle: 'out', targetHandle: 'in' },
  ];
}
```

![Review login and Release cards connected through their right and left HTML handles.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/60f905375e623beb91c90ec41e59d149.png)

Render `<app-ticket-board />` in your application's template after importing `TicketBoardComponent` into its standalone host. Both cards occupy their spec's `size`; their roots fill those boxes rather than determining the node dimensions.

For standard handles, omit the hand-painted spans and keep the `ports` declarations: the canvas already renders HTML connection handles for ports when its visibility policy allows them. Use your own handle elements when you need different HTML or styling, not a separate registry implementation.

## 2. Render widget templates and switch dashboard views

Use [`GrafloriaDashboardComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-grafloriadashboardcomponent#grafloriadashboardcomponent) for cells and packing rather than free-positioned graph nodes. Import [`GrafloriaWidgetDefDirective`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes#grafloriawidgetdefdirective) alongside it. A widget's `kind` selects the matching template; without a match or wildcard, the component uses the shipped KPI, line, bar, donut, funnel or table painter.

The [`GrafloriaWidgetTemplateContext`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interfaces#grafloriawidgettemplatecontext) exposes the widget spec as `let-widget` and its payload as `let-data="data"`. The template root fills the widget cell.

This component opens Overview with a KPI and an Angular note. Click Operations to see the second view. `[(activeView)]` connects the tab property to the mounted board; `[layout]` and `[sizing]` switch live through the component.

### Save and reopen a snapshot

`snapshot()` returns a [`DashboardSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types#dashboardsnapshot), or `null` before the board is live. It contains widget layouts and board options from the handle's `toJSON()`. The sample displays the saved JSON and retains the snapshot in memory.

> **Known issue:** The snapshot clears only `renderWidget` and `onLayoutChange`; other function options, such as `onSelect`, `renderCaption`, `onCaptionAction` and `onTabChange`, remain in memory. For JSON persistence, serialize with `JSON.stringify()`, which drops function-valued properties, and supply your callbacks again when mounting.

The snapshot does not save widget selection or the view's scroll/camera position. Reopening restores the widget layouts and board options, but selection is lost and `showView()` reframes the chosen view rather than restoring its previous camera position.

The intended restore is to assign `saved.views` to `[views]` and `saved` to `[options]`.

> **Known issue:** Changing `[views]` or `[options]` does not rebuild an already mounted dashboard: the component reads them only in `ngAfterViewInit()`. Until it is fixed, unmount the board and mount it again with the snapshot inputs.

Click Save snapshot, then Close board, then Reopen saved board. The separate close and reopen actions let Angular destroy the old component before creating the restored one. Templates remain declared in your application; they are not stored in the JSON.

```ts title="notes-dashboard.component.ts"
import { Component, viewChild } from '@angular/core';
import {
  GrafloriaDashboardComponent,
  GrafloriaWidgetDefDirective,
} from '@grafloria/angular';
import type { DashboardSnapshot } from '@grafloria/element';

@Component({
  selector: 'app-notes-dashboard',
  standalone: true,
  imports: [GrafloriaDashboardComponent, GrafloriaWidgetDefDirective],
  template: `
    <nav aria-label="Dashboard views">
      @for (view of views; track view.id) {
        <button type="button" (click)="tab = view.id"
          [attr.aria-pressed]="tab === view.id">{{ view.name }}</button>
      }
    </nav>
    <button type="button" (click)="layout = layout === 'grid' ? 'split' : 'grid'">
      Toggle grid/split
    </button>
    <button type="button" (click)="sizing = sizing === 'fit' ? 'grow' : 'fit'">
      Toggle fit/grow
    </button>
    <button type="button" (click)="save()" [disabled]="!mounted">Save snapshot</button>
    <button type="button" (click)="mounted = false" [disabled]="!saved || !mounted">
      Close board
    </button>
    <button type="button" (click)="reopen()" [disabled]="!saved || mounted">
      Reopen saved board
    </button>
    @if (mounted) {
      <grafloria-dashboard [views]="views" [options]="options"
        [(activeView)]="tab" [layout]="layout" [sizing]="sizing"
        (layoutChange)="dirty = true" style="display:block; height:400px">
        <ng-template grafloriaWidget="note" let-data="data">
          <article class="note">{{ data['text'] }}</article>
        </ng-template>
      </grafloria-dashboard>
    }
    <p>{{ dirty ? 'Layout changed since save' : 'No unsaved layout gesture' }}</p>
    @if (saved) { <pre>{{ savedText }}</pre> }
  `,
  styles: [`
    .note { height:100%; box-sizing:border-box; padding:20px;
      background:#fffbeb; color:#78350f; font:16px system-ui; }
    pre { max-height:200px; overflow:auto; }
  `],
})
export class NotesDashboardComponent {
  board = viewChild(GrafloriaDashboardComponent);
  mounted = true;
  dirty = false;
  tab: string | undefined = 'overview';
  layout: 'grid' | 'split' = 'grid';
  sizing: 'fit' | 'grow' = 'fit';
  saved: DashboardSnapshot | null = null;
  savedText = '';
  options: DashboardSnapshot = { columns: 12, gap: 8, views: [] };
  views: DashboardSnapshot['views'] = [
    { id: 'overview', name: 'Overview', widgets: [
      { id: 'orders', kind: 'kpi', span: 6, rows: 1,
        data: { label: 'Orders', value: '128', delta: 8 } },
      { id: 'review-note', kind: 'note', span: 6, rows: 1,
        data: { text: 'Review the weekly order report.' } },
    ] },
    { id: 'operations', name: 'Operations', widgets: [
      { id: 'operations-note', kind: 'note', span: 12, rows: 1,
        data: { text: 'Prepare the release checklist.' } },
    ] },
  ];

  save(): void {
    const snapshot = this.board()?.snapshot();
    if (!snapshot) return;
    this.saved = snapshot;
    this.savedText = JSON.stringify(snapshot, null, 2);
    this.dirty = false;
  }

  reopen(): void {
    if (!this.saved || this.mounted) return;
    this.views = this.saved.views;
    this.options = this.saved;
    this.mounted = true;
  }
}
```

![Overview shows the Orders KPI beside the weekly-report note, with view tabs, layout controls and snapshot buttons above.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c631dd987cb7c8b9fc7dcdc7c570c631.png)

Render `<app-notes-dashboard />` in your standalone host after importing `NotesDashboardComponent`. For imperative controls, `(ready)` supplies a typed [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle#dashboardhandle); `getHandle()` returns the same live handle, or `undefined` before the first paint. For layout autosave, `(layoutChange)` supplies `{ viewId, widgets }` after committed gestures.

A bare `<ng-template grafloriaWidget>` handles every kind without an exact template, including built-in kinds. Leave it out when you want unmatched KPIs and charts to use the shipped painters, as this sample does.

## Options that matter

| Option | Type | Default | What it does |
|---|---|---|---|
| `grafloriaNode` | `string` | `''` | Selects a node type; empty string is the HTML-layer fallback. |
| `grafloriaWidget` | `string` | `''` | Selects a widget kind; empty string is the unmatched-kind fallback. |
| `grafloriaHandle` | `'source' \| 'target'` | Required | Marks an output or input HTML handle. |
| `handleId` | `string` | Generated | Identifies a handle within its node. Pass an explicit id for named connections. |
| `handlePosition` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Records the connection side; position the element with your CSS. |
| Dashboard `activeView` | `string \| undefined` | `undefined` | Selects the on-camera view; two-way binding reflects the boot view when unset. |
| Dashboard `layout` | `'grid' \| 'split' \| undefined` | `undefined` | Overrides options at mount and changes every view's layout live. |
| Dashboard `sizing` | `'fit' \| 'grow' \| undefined` | `undefined` | Overrides options at mount and changes sizing live. Split layout uses fit sizing. |
| Dashboard `static` | `boolean \| undefined` | `undefined` | Overrides options at mount; `true` disables drag, resize and handles. |

## Pitfalls

- Import each template directive in the component that declares the template. An attribute without its directive does not register a template.
- An explicit `custom: false` overrides an exact node-template match. Live models pass through without the spec's automatic opt-in rewrite.
- Keep handles inside a node wrapper. Without an ancestor `data-node-id`, registration stops with a console warning.
- Widget templates mount once per widget; the host is reused across renders. Put ongoing data flow in your widget's Angular bindings or child components, not in an expectation that the dashboard re-stamps the template every frame.
- Bind either dashboard `views` or `widgets`, not both.
- For canvas sizing, see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas). For explicitly rerunning graph layout, see [Lay out a diagram](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/lay-out-a-diagram).

## Live demos and related guides

- [Custom nodes demo](https://grafloria.com/demos/nodes/custom-nodes.html) — custom bodies with connected edges.
- [Typed ports demo](https://grafloria.com/demos/ports/typed-ports.html) — connection validation; see [Validate port connections](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/validate-port-connections) for the rules.
- [Dashboard builder demo](https://grafloria.com/demos/dashboard/dashboard-builder.html) and [source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/demos/dashboard/dashboard-builder.html) — widget templates, tabs and board controls.
- [Angular: state and tooling](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/angular-state-and-tooling) — controlled bindings and component methods.
- [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard) — board data and layout options.

<!-- source: qwik-state-and-resumption.md -->

# Qwik: state and resumption

Use QRL callbacks and instance signals to connect a resumable diagram to sibling controls. You get two connected nodes, a Fit view button, selection and camera readouts, and a server-rendered version that becomes interactive in the browser.

The binding is a thin skin over the shared model: keep plain specs in resumable state and use the live instance for rendering operations. Start with an existing Qwik 1.x project using `@builder.io/qwik` ^1.5.0 and its optimizer; see the [Qwik quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-quick-start) for project setup.

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

## 1. Keep the diagram input as data

Share the [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow) input data—typed with [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec)—between the sibling-subscription and server-adoption examples below; see the [React quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-quick-start) for basic node-and-edge setup.

```ts title="diagram-data.ts"
import type { NodeSpec, EdgeSpec } from '@grafloria/qwik';

export const nodes: NodeSpec[] = [
  { id: 'plan', label: 'Plan', position: { x: 60, y: 80 },
    size: { width: 160, height: 64 } },
  { id: 'ship', label: 'Ship', position: { x: 320, y: 80 },
    size: { width: 160, height: 64 } },
];

export const edges: EdgeSpec[] = [
  { id: 'plan-ship', source: 'plan', target: 'ship',
    sourceHandle: 'right', targetHandle: 'left' },
];
```

## 2. Connect QRL callbacks and sibling subscriptions

Wrap the canvas and its toolbar in [`GrafloriaProvider`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaprovider). [`useGrafloria`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#usegrafloria) returns the shared instance signal; it is `undefined` until the flow mounts. [`useSelection`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#useselection) returns the current selected nodes and edges, and [`useViewport`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#useviewport) returns the camera's zoom and world origin.

Use the [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance) signal to show canvas readiness beside the sibling toolbar; see the [Qwik quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-quick-start) for `onInit$`, `noSerialize()` and QRL callback setup.

For a sibling side effect, [`useOnSelectionChange$`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#useonselectionchange) fires a QRL on each selection change and removes its subscription automatically. Here it counts selection notifications rather than storing live models in application state.

[`useOnSelectionChangeQrl`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#useonselectionchangeqrl) accepts an explicitly `$()`-wrapped handler. The second subscription logs selected node ids to the browser console.

```tsx title="editor.tsx"
import { $, component$, noSerialize, useSignal, type NoSerialize } from '@builder.io/qwik';
import {
  GrafloriaFlow, GrafloriaProvider, useGrafloria,
  useSelection, useViewport, useOnSelectionChange$, useOnSelectionChangeQrl,
  type DiagramInstance,
} from '@grafloria/qwik';
import { nodes, edges } from './diagram-data';

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

  useOnSelectionChange$(() => {
    notifications.value += 1;
  });

  useOnSelectionChangeQrl($(({ nodes: selectedNodes }) => {
    console.log('Selected nodes:', selectedNodes.map((node) => node.id));
  }));

  return (
    <div>
      <button type="button" disabled={!instance.value}
        onClick$={() => instance.value?.fitView(40)}>
        Fit view
      </button>
      <p>
        Selected: {selection.value.nodes.length} node(s),{' '}
        {selection.value.edges.length} edge(s).{' '}
        Zoom: {viewport.value.zoom.toFixed(2)}.{' '}
        Origin: {viewport.value.x.toFixed(0)}, {viewport.value.y.toFixed(0)}.
      </p>
      <p>Selection notifications: {notifications.value}</p>
    </div>
  );
});

export default component$(() => {
  const instance = useSignal<NoSerialize<DiagramInstance>>();
  const clicked = useSignal('None');

  return (
    <GrafloriaProvider>
      <Toolbar />
      <p>Canvas: {instance.value ? 'Ready' : 'Starting'}. Last clicked node: {clicked.value}</p>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        fitView
        style={{ height: '400px' }}
        onInit$={(diagram) => { instance.value = noSerialize(diagram); }}
        onNodeClick$={({ node }) => { clicked.value = node.id; }}
      />
    </GrafloriaProvider>
  );
});
```

The mounted canvas shows Plan connected to Ship. Click a node to update the clicked-node text and selection readout. Pan or zoom to update the camera readout; Fit view frames the content. `defaultNodes` and `defaultEdges` seed the instance once, so the instance owns subsequent edits.

![Plan connects to Ship beneath the Fit view button, selection and camera readouts, and Ready status. No node is selected.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ae426f8eada442464e38f2f188564e8e.png)

For controlled state instead, pass `nodes` and `edges` from typed signals and write the returned specs back through `onNodesChange$` and `onEdgesChange$`. Those callbacks receive spec arrays, not the live models supplied by selection callbacks. See [State and event flow](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/state-and-event-flow) for the ownership decision.

## 3. Adopt the server SVG with its CSS

Pass the [`StaticRenderResult`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#staticrenderresult) from [`renderToStaticSVG`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#rendertostaticsvg) to the Qwik flow's `ssr` prop and emit its CSS separately to turn the server preview into an interactive canvas; see [React: state and subscriptions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-state-and-subscriptions) for the static result's fields.

In an SSR-rendered component, build the result in `useTask$`, following the resumable demo. Keep that result as plain data and pass it to `ssr` together with the same node and edge specs. This example emits the stylesheet beside the flow; when composing your document shell, place `result.css` in a `<style>` in the document head so the first server response already carries the diagram's styles.

```tsx title="resumable-diagram.tsx"
import { component$, useSignal, useTask$ } from '@builder.io/qwik';
import { GrafloriaFlow, renderToStaticSVG, type StaticRenderResult } from '@grafloria/qwik';
import { nodes, edges } from './diagram-data';

export default component$(() => {
  const result = useSignal<StaticRenderResult>();
  const ready = useSignal(false);

  useTask$(() => {
    result.value = renderToStaticSVG({
      nodes, edges, width: 640, height: 400,
      instanceId: 'plan-ship-ssr', fitView: true,
    });
  });

  return (
    <>
      <style dangerouslySetInnerHTML={result.value?.css ?? ''} />
      <p>{ready.value ? 'Interactive' : 'Server preview'}</p>
      <GrafloriaFlow
        defaultNodes={nodes}
        defaultEdges={edges}
        ssr={result.value}
        style={{ height: '400px' }}
        onInit$={() => { ready.value = true; }}
      />
    </>
  );
});
```

View the server response source: Plan, Ship and their SVG are already in the HTML. At document ready, the flow builds a live instance using the snapshot and adopts the existing DOM instead of rebuilding it. The status changes to Interactive, and you can drag the nodes. Resumption avoids re-walking the component tree; it does not defer the diagram's initialization until the first click.

![The Interactive status appears above Plan connected to Ship; the left edge of the Plan box is clipped by the canvas boundary.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/29c446c92ec1090acbb76c77b6dd5867.png)

The snapshot carries instance scope, canvas width and height, zoom, and viewport origin—not a saved document. The client rebuilds the model from your specs. Use [Save and restore documents](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/save-and-restore-documents) for persistence. Custom HTML nodes mount in the browser; they are not part of the server-rendered SVG.

## Options that matter

For the flow options below, see [`GrafloriaFlowProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflowprops). Static rendering takes [`StaticRenderOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#staticrenderoptions).

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `defaultNodes`, `defaultEdges` | `NodeSpec[]`, `EdgeSpec[]` | Empty arrays when no controlled inputs exist | Seed the instance on mount. |
| `nodes`, `edges` | `NodeSpec[]`, `EdgeSpec[]` | Unset | Reconcile controlled specs into the instance. Wire their change callbacks back to your state. |
| `ssr` | `{ html: string; snapshot: HydrationSnapshot }` | Unset | Emit server markup and adopt it in the browser. Supply its CSS separately. |
| Static `width`, `height` | `number` | `800`, `600` | Set the server canvas dimensions in CSS pixels. |
| Static `instanceId` | `string` | `'grafloria-ssr'` | Scope the diagram. Give multiple server-rendered diagrams distinct ids. |
| Static `fitView` | `boolean` | `false` | Frame content instead of using the supplied camera. |
| Static `fitPadding` | `number` | `40` | Set fit padding in CSS pixels. |

[`HydrationSnapshot`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core#hydrationsnapshot) is returned by static rendering; pass it through rather than reconstructing it.

## Keep browser objects out of resumable state

The provider's instance signal is already marked `noSerialize()`. Your own instance signal needs the explicit marker shown above. Its value does not survive serialization: the browser builds a fresh instance, and `onInit$` supplies that instance again. Do not close over a live instance directly in another QRL; capture its signal and read `.value` when the handler runs.

Create live transports and shared stores in `useVisibleTask$`, retain them with `noSerialize()`, and tear them down when their owner unmounts. The flow's collaboration options are fixed for the instance's lifetime, so create the options before mounting a flow that consumes them. See [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for live-object handling and [Qwik: custom content and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-custom-content-and-kits) for browser-built `spec$` factories.

Keep the provider above both the canvas and its subscribing siblings. Outside a provider, the hooks have no instance to reach; `useGrafloria()` stays `undefined` and logs a development warning. Use a separate provider for each independently controlled canvas.

## Load the event loader in client-only apps

An SSR page carries Qwik's event loader automatically. If your app only calls Qwik's `render()` in the browser, add the loader once before rendering; without it, DOM handlers such as Fit view do not fire.

Use this entry only for a client-only app. It mounts the editor from step 2 into a newly created element in the browser.

```tsx title="main.tsx"
import { render } from '@builder.io/qwik';
import { QWIK_LOADER } from '@builder.io/qwik/loader';
import Editor from './editor';

const loader = document.createElement('script');
loader.textContent = QWIK_LOADER;
document.head.appendChild(loader);

const container = document.createElement('div');
document.body.appendChild(container);
void render(container, <Editor />);
```

## Live demos and related tasks

- [Qwik gallery](https://grafloria.com/demos-qwik/) — run the framework's diagrams and inspect their source.
- [Server-side export](https://grafloria.com/demos/misc/server-side-export.html) — inspect a static SVG preview; unlike the adopted flow above, that preview is not interactive.
- [Resumable sample source](https://github.com/grafloria/grafloria/blob/cccb505e76c7af26c8bafecaba8146db7d8df928/apps/demos-qwik/src/demos/ssr-resumable.tsx) — the server markup and snapshot handoff.
- [Instance and lifecycle](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/instance-and-lifecycle) — instance operations and teardown.
- [Qwik: custom content and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-custom-content-and-kits) — custom containers and QRL spec factories.

<!-- source: qwik-custom-content-and-kits.md -->

# Qwik: custom content and kits

Keep custom nodes and widgets self-contained, pass their content through typed data props, and build function-bearing kits in the browser with `spec$`. Use this pattern when a node needs application-specific HTML or a kit needs to survive server rendering and resumption.

Your custom component paints the inside of an engine-positioned box; the engine and renderer still own dragging, selection and connections. Start in a Qwik 1.x project using `@builder.io/qwik` ^1.5.0 and its optimizer. See the [Qwik quick start](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-quick-start) for setup.

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

## 1. Pass node content through typed props

Unlike React, registering a component in [`GrafloriaFlow`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriaflow)'s [`NodeTypes`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#nodetypes) map automatically opts matching nodes into HTML rendering unless they specify `custom: false`; see [React: custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content) for the shared type-to-component mapping.

The Qwik sample uses [`NodeProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#nodeprops) with a `ServiceData` payload to carry owner and status across the container boundary, alongside typed [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec#nodespec) and [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec#edgespec) inputs; see [React: custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content) for the shared props contract.

Custom nodes mount in separate Qwik containers. They cannot read contexts from the surrounding application, including router contexts. Pass the values they need through `node.data` rather than calling a parent-context hook inside the card. This is Qwik's container behavior, not a wrapper defect.

```tsx title="service-flow.tsx"
import { component$ } from '@builder.io/qwik';
import {
  GrafloriaFlow,
  type NodeProps,
  type NodeTypes,
  type NodeSpec,
  type EdgeSpec,
} from '@grafloria/qwik';

interface ServiceData {
  name: string;
  owner: string;
  status: 'healthy' | 'degraded';
}

const ServiceNode = component$((props: NodeProps<ServiceData>) => (
  <div style={{
    boxSizing: 'border-box', width: '100%', height: '100%',
    padding: '12px', borderRadius: '10px', background: '#ffffff',
    border: `2px solid ${props.data.status === 'healthy' ? '#059669' : '#d97706'}`,
    color: '#232a3d', font: '13px/1.4 system-ui, sans-serif',
  }}>
    <strong>{props.data.name}</strong>
    <div>{props.data.owner}</div>
    <div>{props.data.status}</div>
  </div>
));

const nodeTypes = { service: ServiceNode } satisfies NodeTypes;
const gateway: ServiceData = {
  name: 'api-gateway', owner: 'platform', status: 'healthy',
};
const orders: ServiceData = {
  name: 'orders-svc', owner: 'commerce', status: 'degraded',
};
const nodes: NodeSpec[] = [
  { id: 'gateway', type: 'service', position: { x: 60, y: 80 },
    size: { width: 190, height: 96 }, data: gateway },
  { id: 'orders', type: 'service', position: { x: 370, y: 80 },
    size: { width: 190, height: 96 }, data: orders },
];
const edges: EdgeSpec[] = [
  { id: 'gateway-orders', source: 'gateway', target: 'orders',
    sourceHandle: 'right', targetHandle: 'left' },
];

export default component$(() => (
  <GrafloriaFlow
    defaultNodes={nodes} defaultEdges={edges} nodeTypes={nodeTypes}
    fitView style={{ height: '400px' }}
  />
));
```

![Look at the green-bordered api-gateway and amber-bordered orders-svc cards: each displays its owner and status, and an arrow connects them.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/12ee0e9f14f826928827d0f7c387f677.png)

The canvas contains two connected service cards: a green-bordered healthy gateway and an amber-bordered degraded orders service. Each card fills the size declared on its node. The defaults seed an uncontrolled instance; this example does not mirror edits into application state.

## 2. Mix a custom widget with a shipped painter

[`GrafloriaDashboard`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadashboard) uses the same container boundary. Map a widget's `kind` through [`WidgetTypes`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#widgettypes), and receive its full spec and data through [`WidgetProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#widgetprops). Feed it through `widget.data`; do not rely on surrounding application contexts.

Declare the board with [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec#dashboardwidgetspec). Only the `note` kind below has a custom component. The `kpi` kind uses the shipped painter, so you do not need to write a KPI renderer.

```tsx title="service-board.tsx"
import { component$ } from '@builder.io/qwik';
import {
  GrafloriaDashboard, type WidgetProps, type WidgetTypes,
} from '@grafloria/qwik';
import type { DashboardWidgetSpec } from '@grafloria/element';

interface NoteData {
  title: string;
  text: string;
}

const NoteWidget = component$((props: WidgetProps<NoteData>) => (
  <article style={{
    boxSizing: 'border-box', width: '100%', height: '100%',
    padding: '16px', background: '#fffbeb', color: '#78350f',
    font: '14px/1.5 system-ui, sans-serif',
  }}>
    <strong>{props.data.title}</strong>
    <p>{props.data.text}</p>
  </article>
));

const widgetTypes = { note: NoteWidget } satisfies WidgetTypes;
const note: NoteData = {
  title: 'Operations note', text: 'Check the orders service before the release.',
};
const widgets: DashboardWidgetSpec[] = [
  { id: 'services', kind: 'kpi', span: 3, rows: 1,
    data: { label: 'Healthy services', value: '2 / 3' } },
  { id: 'release-note', kind: 'note', span: 3, rows: 1, data: { ...note } },
];

export default component$(() => (
  <GrafloriaDashboard
    widgets={widgets} widgetTypes={widgetTypes}
    options={{ columns: 6, width: 800, height: 400, gap: 8 }}
    style={{ height: '400px' }}
  />
));
```

The board displays a Healthy services KPI beside an Operations note card. Qwik builds and mounts the dashboard kit in the browser; see [React: custom content](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/react-custom-content#respect-the-mount-once-board-props) for the shared mount-once input behavior. For runtime widget edits, see [Build a dashboard](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/build-a-dashboard).

## 3. Build a kit through `spec$` and remount for new data

Use [`GrafloriaDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-qwik#grafloriadiagram) for a kit rather than rebuilding its cards yourself. The shipped [`erDiagram`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions#erdiagram) builder returns table-card specs and a `finalize` function. Its entities become HTML tables with typed columns and PK/FK badges; its relationships become orthogonal edges with crow's-foot cardinality.

Pass the builder through `spec$`, not `spec`. The QRL runs in the browser, so the function-bearing result never enters server-rendered resumable state. Plain-data specs and JSON/DSL strings can use `spec` instead. See [Documents and kits](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/documents-and-kits) for live-object serialization rules.

A `$` prop stays fixed for the life of its component. Capture a data snapshot and change the component's `key` when you want a new diagram. This example starts with Customer and Order tables; Add email rebuilds them with an extra Customer column. The `onReady$` callback receives the mounted [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance#diagraminstance), and `fitView(40)` frames its content.

Type the schema data with [`ErEntitySpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#erentityspec) and [`ErRelationshipSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces#errelationshipspec).

```tsx title="schema-diagram.tsx"
import { component$, useSignal } from '@builder.io/qwik';
import { GrafloriaDiagram, type DiagramInstance } from '@grafloria/qwik';
import { erDiagram, type ErEntitySpec, type ErRelationshipSpec } from '@grafloria/element';

export default component$(() => {
  const schemaVersion = useSignal(0);
  const version = schemaVersion.value;
  const entities: ErEntitySpec[] = [
    { id: 'CUSTOMER', name: 'Customer', position: { x: 60, y: 80 },
      columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'name', type: 'varchar' },
        ...(version > 0 ? [{ name: 'email', type: 'varchar' }] : []),
      ] },
    { id: 'ORDER', name: 'Order', position: { x: 420, y: 80 },
      columns: [
        { name: 'id', type: 'int', pk: true },
        { name: 'customer_id', type: 'int', fk: true },
      ] },
  ];
  const relationships: ErRelationshipSpec[] = [
    { from: 'CUSTOMER', to: 'ORDER', label: 'places' },
  ];

  return (
    <section>
      <button disabled={version > 0} onClick$={() => { schemaVersion.value += 1; }}>
        Add email
      </button>
      <GrafloriaDiagram
        key={version}
        spec$={() => erDiagram({ entities, relationships })}
        onReady$={(instance: DiagramInstance) => { instance.fitView(40); }}
        style={{ height: '400px' }}
      />
    </section>
  );
});
```

![Look at the CUSTOMER and ORDER tables, their PK/FK badges, and the places relationship with a crow's-foot at ORDER. The Add email button sits above the initial diagram.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/03558c35e914bad6652c2eaa91d1bbb4.png)

The initial diagram contains two tables joined by a relationship labelled places. Add email replaces the mounted diagram; it is a rebuild, not an undoable edit of the old instance. The wrapper disposes the old instance on unmount, so do not retain it for later calls.

For editing the existing document instead of replacing it, see [Edit database models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/edit-database-models).

## Options that matter

[`RenderSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core#renderspec) is the shared render-input type used by `spec` and `spec$`.

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| `nodeTypes` | `NodeTypes` | No registrations | Maps node types to Qwik components and opts matching specs into custom rendering. |
| `NodeSpec.custom` | `boolean` | Inferred for registered types by the binding | An explicit value overrides the inferred custom flag. |
| `widgetTypes` | `WidgetTypes` | No registrations | Maps widget kinds to Qwik components; unmatched kinds use shipped painters. |
| `spec` | `RenderSpec` | Not set | Supplies plain data or text to the generic host. |
| `spec$` | `QRL<() => RenderSpec \| Promise<RenderSpec>>` | Not set | Builds the spec in the browser; takes precedence over `spec`. |

Give a canvas a resolved height as shown above; see [Theme a canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/theme-a-canvas) for sizing and appearance.

## Demos and related pages

- [Custom nodes live demo](https://grafloria.com/demos/nodes/custom-nodes.html): select its Qwik binding to inspect framework-rendered cards.
- [Table / ER live demo](https://grafloria.com/demos/diagrams/table-er.html): inspect the shipped table-card kit and its relationships.
- [Dashboard builder live demo](https://grafloria.com/demos/dashboard/dashboard-builder.html): explore boards built from widget data.
- [Qwik gallery and source](https://grafloria.com/demos-qwik/): view the Qwik examples in place.
- [Qwik state and resumption](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/qwik-state-and-resumption): connect application controls to the live instance.

<!-- 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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-overview): `bindDashboardGrid`, `BUILT_IN_WIDGET_KINDS`, `dashboard`, `DashboardGridHandle`, `DashboardGridOptions`, `DashboardHandle`, `DashboardOptions`, `DashboardSnapshot`, `DashboardSpec`, `DashboardViewSpec`, `DashboardWidgetSpec`, `defaultWidgetRenderer` and 7 more

<!-- 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.4.0
- `@grafloria/renderer` ^0.5.0
- `react` ^17.0.0 || ^18.0.0 || ^19.0.0
- `react-dom` ^17.0.0 || ^18.0.0 || ^19.0.0
- `@grafloria/element` ^0.5.0

## 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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'`, `'dark'` or `'system'` (follow the OS). Applied at mount; a change |
| `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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'` or `'dark'` pins the built-in light/dark theme; `'system'` follows the |
| `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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'`, `'dark'` or `'system'` (follow the OS). Applied at mount; a change applies live — unlike a changed `options`, it does not replace the diagram. |
| `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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'` or `'dark'` pins the built-in light/dark theme; `'system'` follows the OS (and its high-contrast setting). Applied at mount; a change applies live, with no remount. While a mode is set, the `theme` prop does not override it — the same rule as Angular's `colorMode` input. Removing the prop keeps the last mode. |
| `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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `HydrationSnapshot`, `LIGHT_THEME`, `NodeSpec`, `PortSpec`, `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.4.0
- `@grafloria/renderer` ^0.5.0
- `vue` ^3.4.0
- `@grafloria/element` ^0.5.0

## 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: () =` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'`, `'dark'` or `'system'` (follow the OS). Applied at mount; a change |

**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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'` or `'dark'` pins the built-in light/dark theme; `'system'` follows |
| `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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `LIGHT_THEME`, `NodeSpec`, `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.4.0
- `@grafloria/renderer` ^0.5.0
- `@builder.io/qwik` ^1.5.0
- `@grafloria/element` ^0.5.0

## 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 (and says so once, in
development).

```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` |  | The spec as DATA — `{ nodes, edges }`, or JSON/DSL text. A kit spec carries |
| `spec$?` | `QRL<() => RenderSpec \| Promise<RenderSpec>>` |  | A QRL that BUILDS the spec in the browser: `spec$={() => erDiagram({ … })}`. The way to pass any kit spec, and the only one that survives server rendering. |
| `options?` | `RenderOptions` |  |  |
| `onReady$?` | `QRL<(instance: DiagramInstance) => void>` |  | Fires once the kit has rendered, with the live instance. |
| `colorMode?` | `ColorMode` |  | `'light'`, `'dark'` or `'system'` (follow the OS). Applied at mount; a change |
| `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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'` or `'dark'` pins the built-in light/dark theme; `'system'` follows the |
| `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` |  | The spec as DATA — `{ nodes, edges }`, or JSON/DSL text. A kit spec carries functions; under SSR pass it through `spec$` instead (see the note above). |
| `spec$?` | `QRL<() => RenderSpec \| Promise<RenderSpec>>` |  | A QRL that BUILDS the spec in the browser: `spec$={() => erDiagram({ … })}`. The way to pass any kit spec, and the only one that survives server rendering. |
| `options?` | `RenderOptions` |  |  |
| `onReady$?` | `QRL<(instance: DiagramInstance) => void>` |  | Fires once the kit has rendered, with the live instance. |
| `colorMode?` | `ColorMode` |  | `'light'`, `'dark'` or `'system'` (follow the OS). Applied at mount; a change applies live — unlike changed `options`, it does not replace the diagram. |
| `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` |  |  |
| `colorMode?` | `ColorMode` |  | `'light'` or `'dark'` pins the built-in light/dark theme; `'system'` follows the OS (and its high-contrast setting). Applied at mount; a change applies live, with no remount. While a mode is set, `theme` does not override it — the same rule as Angular's `colorMode` input. Removing the prop keeps the last mode. |
| `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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-overview): `DARK_THEME`, `DiagramInstance`, `EdgeSpec`, `GroupSpec`, `HighlightConnectedOptions`, `HydrationSnapshot`, `LIGHT_THEME`, `NodeSpec`, `renderToStaticSVG`, `StaticRenderOptions`, `StaticRenderResult`, `Theme`

<!-- source: grafloria-qwik-vite.md -->

# @grafloria/qwik/vite

Part of the `@grafloria/qwik` package: install `@grafloria/qwik` and import these from `@grafloria/qwik/vite`.

## Functions

### `default`

The package's default export: import it under a name of your own, `import vite from '@grafloria/qwik/vite'`.

```ts
function grafloriaQwik()
```

### `grafloriaQwik`

```ts
function grafloriaQwik()
```

<!-- 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.4.0

## What it exports

- [Core](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-core): 17 exports, including `cancelFrame`, `CanvasRect`, `getDocument`, `hasDocument`
- [A11y](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-a11y): 51 exports, including `Adjacency`, `analyseTopology`, `boundsOfPoints`, `buildAdjacency`
- [Canvas](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas): 79 exports, including `ALWAYS_SAFE_MODE`, `applyMatrix`, `arcToCubics`, `BackendMode`
- [Comments](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-comments): 9 exports, including `CommentOverlayController`, `CommentOverlayOptions`, `CommentPanelOptions`, `CommentPanelView`
- [Export](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export): 111 exports, including `Artifact`, `AssetFetcher`, `AVG_CHAR_WIDTH_EM`, `base64ToBytes`
- [Export — Pdf](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-pdf): 10 exports, including `BaseFont`, `exportPdf`, `Orientation`, `PAGE_SIZES`
- [Ext](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext): 115 exports, including `activeRegistryScope`, `AnchorContext`, `AnchorFn`, `AnchorResult`
- [Ext — Components](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-components): 15 exports, including `attachCanvasPlugins`, `BACKGROUND_LAYER_CLASS`, `BackgroundHandle`, `BackgroundOptions`
- [Instance](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance): 49 exports, including `applyEdges`, `applyEdgeSpec`, `applyGroups`, `applyNodes`
- [Interaction](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction): 85 exports, including `AddWaypointResult`, `AlignmentGuide`, `angleAt`, `Announcement`
- [Lazy](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-lazy): 13 exports, including `DeferredQuery`, `EntityKind`, `FreezeQuery`, `HostCullMode`
- [Perf](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-perf): 8 exports, including `EMPTY_SNAPSHOT`, `formatSnapshot`, `GovernorOptions`, `GovernorState`
- [Presence](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presence): 12 exports, including `actorColor`, `actorInitials`, `bindPresence`, `BindPresenceOptions`
- [Presentation](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-presentation): 11 exports, including `FollowOptions`, `followPresenter`, `InMemoryViewportChannel`, `isDocumentLocked`
- [Services](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-services): 25 exports, including `AnimationConfig`, `AnimationEventData`, `AnimationLifecycleEvent`, `AnimationLifecycleManager`
- [Svg](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg): 200 exports, including `applySpread`, `ArrowRenderer`, `assignSpreadLanes`, `autoSizeDiagram`
- [Themes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes): 83 exports, including `assertThemeContrast`, `auditThemeContrast`, `BASE_STYLE_RULES`, `BRIDGEABLE_TOKENS`
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types): 50 exports, including `BooleanPropertyDefinition`, `BoundingBox`, `CanvasRendererConfig`, `ColorPalette`
- [Utils](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-utils): 37 exports, including `AnimationColorSchemes`, `AnimationDescriptor`, `AnimationPresets`, `AnimationPriority`
- [Vnode](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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.
- `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.
- `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)`.
- `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.
- `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[]` |  |  |
| `groups?` | `GroupSpec[]` |  | Group / lane frames, as `render()` and `setGroups()` take them. |
| `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-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.
- `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.
- `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.

<!-- source: grafloria-renderer-export-pdf.md -->

# Export — Pdf

Import these from `@grafloria/renderer`.

## Functions

### `exportPdf`

Export a rendered VNode tree as a vector PDF.

```ts
function exportPdf(root: VNode, options: PdfExportOptions = {}): PdfExportResult
```

### `pageDimensions`

The page's dimensions in points, after orientation.

```ts
function pageDimensions(
  size: PageSize | { width: number; height: number },
  orientation: Orientation
): { width: number; height: number }
```

## Constants

### `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; }; }
```

## Interfaces

### `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. |
| `resolveVar?` | `(name: string) => string \| null \| undefined` |  | The LIVE value of a CSS custom property — e.g. `getComputedStyle(svg).getPropertyValue(name)` on the diagram's root. An element's own paint can be a `var(--…)` (the line markers ride `var(--grafloria-link-stroke, …)` so a token bridge recolours them with their line); this is how a bridged value reaches the PDF. |

### `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` |  |  |

## Types

### `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';
```

### `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;
```

<!-- 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-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.
- `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.
- `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.
- `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.
- `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-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

```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
- `static getNodeId(containerId: string): string | null` (static) — Extract the node ID from a container ID
- `static reset(): void` (static) — Reset the internal counter to zero

### `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.
- `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` |  |  |
| `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` |  |  |

## 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-renderer-a11y.md -->

# A11y

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-a11y-classes): 3 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-a11y-constants): 5 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-a11y-functions): 30 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-a11y-interfaces): 11 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-classes): 4 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-constants): 5 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-functions): 42 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-interfaces): 20 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-types): 5 types.
- [`Canvas2DLike`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-canvas2dlike): The subset of `CanvasRenderingContext2D` the painter uses. A real 2D context
- [`CanvasRenderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-canvas-canvasrenderer)
- [`RecordingContext2D`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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.

### `DiagramRenderBackend`

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.
- `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).
- `hitTest(worldX: number, worldY: number): CanvasPick | null`
- `setTheme(theme: Theme): void`
- `dispose(): void`

### `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. |
| `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.
- `getPerformanceMetrics(): PerformanceMetrics` — Get performance metrics
- `hitTest(x: number, y: number): VNode | null` — The topmost element at a WORLD coordinate.
- `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-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-export.md -->

# Export

Import these from `@grafloria/renderer`.

## On their own pages

- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-constants): 12 constants.
- [Functions B–S](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-b-s): 57 functions, `base64ToBytes` to `svgToDataUri`.
- [Functions V–W](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-functions-v-w): 3 functions, `viewBoxTransform` to `withInlinedImages`.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-interfaces): 25 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-types): 11 types.
- [`CustomNodeHostSource`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-customnodehostsource): Where a canvas's custom nodes are painted — the one thing the pipeline cannot know.
- [`SerializeOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-export-serializeoptions)
- [`SvgExportOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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_CUSTOM_NODE_TIMEOUT`

Default bound on waiting for an async painter. See ExportOptions.customNodeTimeout.

```ts
const DEFAULT_CUSTOM_NODE_TIMEOUT: 5000
```

### `DEFAULT_MAX_OUTPUT_SIZE`

The default cap on an exported raster's pixel size, per side.

```ts
const DEFAULT_MAX_OUTPUT_SIZE: 4000
```

### `EXPORT_IGNORE_ATTRIBUTE`

The opt-out: an element marked `data-grafloria-export="ignore"` is on screen but not in
the file — interaction chrome a canvas draws inside a host (the Angular canvas's port
handles), or a card's own buttons. Its whole subtree is skipped.

```ts
const EXPORT_IGNORE_ATTRIBUTE: "data-grafloria-export"
```

### `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
```

### `nodeWorldBounds`

World bounds of a node — the rect both the culler and the capture work in.

```ts
const nodeWorldBounds: (node: NodeModel) => Rectangle
```

### `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-b-s.md -->

# Functions B–S

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
```

### `captureCustomNodes`

THE SYNCHRONOUS CAPTURE — materialize → read → restore, with no suspension point.

The DOM read happens HERE, once, and produces plain data — `exportSvg` stays pure,
DOM-free and deterministic. A painter that defers its paint has not drawn anything by
the time this looks; `paintWarning` says so rather than exporting a silent blank.

```ts
function captureCustomNodes(
  source: CustomNodeHostSource,
  needed: (node: NodeModel) => boolean = () => true
): CustomNodeCapture[]
```

### `captureCustomNodesAsync`

THE ASYNC CAPTURE — the same boundary, allowed to wait for a painter that said it was
not finished.

THE SIGNAL IS THE PROMISE (`pendingPaint`), and nothing else — never a fixed sleep. `timeoutMs` is a safety net: on expiry the export takes the host as it stands and
`paintWarning(…, waited = true)` reports it. If nothing in scope is pending, this runs
materialize → read → restore with no suspension point at all, i.e. the identical
sequence {@link captureCustomNodes} performs, so an all-sync board exports the same
bytes through both paths.

```ts
async function captureCustomNodesAsync(
  source: CustomNodeHostSource,
  needed: (node: NodeModel) => boolean,
  timeoutMs: number
): Promise<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(--…)`.

### `createCustomNodeCapturer`

Bind the capture to one canvas's hosts.

ONE async capture at a time per canvas: two exports in flight would otherwise
interleave their materialize/restore pairs — the first's restore tearing down a host
the second is still waiting to read.

```ts
function createCustomNodeCapturer(source: CustomNodeHostSource): CustomNodeCapturer
```

### `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
```

### `createExportPipeline`

Bind the whole pipeline to one renderer and one canvas's custom-node hosts.

```ts
function createExportPipeline(
  renderer: PipelineRenderer,
  source: CustomNodeHostSource
): ExportPipeline
```

### `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[]>
```

### `exportScopeFilter`

Which nodes this export will actually contain.

Materializing is the expensive half — it runs a painter — so it is bounded by the
export's own scope rather than mounting a 300-widget board to capture the three
widgets `includeIds` asked for. The predicates mirror what the renderer resolves
`ids` to (`SVGRenderer.selectedIds` reads exactly this `state.selected`), so what is
mounted and what survives `filterCaptures` are the same set.

```ts
function exportScopeFilter(exportOptions?: ExportOptions): (node: NodeModel) => boolean
```

### `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
```

### `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
```

### `substituteCssVars`

Substitute every `var(--name[, fallback])` in a CSS value through `lookup`.

Unlike {@link resolveCssVars} (written for our own stylesheet, whose fallbacks are
plain literals) this parses BALANCED parentheses, because an element's inline paint
can carry `var(--grafloria-link-stroke, rgb(107, 114, 128))` — and a fallback that is
itself a `var()`. A name `lookup` cannot answer falls back to the var()'s fallback;
a name with neither is listed in `unresolved` and the value is not returned.

```ts
function substituteCssVars(
  value: string,
  lookup: (name: string) => string | undefined
): { value?: string; unresolved: string[] }
```

### `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
```

<!-- source: grafloria-renderer-export-functions-v-w.md -->

# Functions V–W

Import these from `@grafloria/renderer`.

## Functions

### `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
```

### `withInlinedImages`

EXTERNAL-URL IMAGES → embedded bytes, for the async export only.

A widget's `<img src="https://…">` captures as `<image href="https://…">`, which an
SVG renders online and a PDF cannot draw at all. The export runs in a browser, which
can usually fetch that URL itself — so every external reference is fetched and swapped
for a `data:` URI, three tiers (see `fetchAssetsTiered`): environment fetch, then
`ExportOptions.assetFetcher`, then the accurate warning.

TWO KINDS OF IMAGE, ONE PASS. Widget captures (`exportOptions.customNodes`) are
substituted here directly. A panel image painted by the RENDERER'S OWN tree is built
inside the synchronous export, so the renderer enumerates those URLs up front
(`collectExportImageUrls`), the fetch covers the UNION (one fetch per URL), and the
resolved map rides down `ExportOptions.resolvedAssets`. A URL the caller pre-resolved
is trusted, never fetched.

THE WARNING LEDGER IS RECONCILED, both ways: a capture whose images were all embedded
loses its capture-time "EXTERNAL URL" caveat; a URL every tier failed on keeps the
reference and gains a warning naming the URL and the reason — a tree image's failure
goes to `onWarnings`.

Run it AFTER the custom-node capture, so the captured images are in the options.

```ts
async function withInlinedImages(
  renderer: ExportImageUrlSource,
  exportOptions: ExportOptions
): Promise<ExportOptions>
```

<!-- 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. |

### `CustomNodeCapturer`

The two capture entry points a canvas exposes, bound to its host source.

```ts
interface CustomNodeCapturer
```

**Members**

- `withCustomNodes(exportOptions?: ExportOptions): ExportOptions` — Synchronous: add `customNodes` captured now. A caller's own `customNodes` wins.
- `withCustomNodesAsync(exportOptions?: ExportOptions): Promise<ExportOptions>` — Async: wait for pending painters (bounded), then capture. A caller's own `customNodes` wins.

### `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. |

### `ExportImageUrlSource`

What image inlining needs from the renderer: the URLs its own tree references.

```ts
interface ExportImageUrlSource
```

**Members**

- `collectExportImageUrls(options?: ExportOptions): string[]`

### `ExportPipeline`

A canvas's three export entry points, with its custom nodes in them.

```ts
interface ExportPipeline
```

**Members**

- `export(format?: ExportFormat, options?: ExportOptions): Promise<string>` — The full async pipeline: wait for async painters (bounded by `customNodeTimeout`), capture every in-scope custom node, fetch and embed external images, then export.
- `exportSvgString(options?: ExportOptions): SvgExportResult` — Synchronous SVG: custom nodes captured as they stand now; no fetch (only `resolvedAssets`).
- `exportPdf(options?: ExportOptions): PdfExportResult` — Synchronous vector PDF: custom nodes captured as they stand now; no fetch.

### `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. |

### `PipelineRenderer`

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

What the full pipeline needs from the renderer.

```ts
interface PipelineRenderer extends ExportImageUrlSource
```

**Members**

- `export(format?: ExportFormat, options?: ExportOptions): Promise<string>`
- `exportSvgString(options?: ExportOptions): SvgExportResult`
- `exportPdf(options?: ExportOptions): PdfExportResult`

### `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 }>;
```

### `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';
```

### `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-customnodehostsource.md -->

# CustomNodeHostSource

Import it from `@grafloria/renderer`.

Where a canvas's custom nodes are painted — the one thing the pipeline cannot know.

Only `getNodes` and `getHost` are required. The optional members exist for a canvas
that culls hosts or runs async painters (the JS canvas); a framework canvas whose hosts
are always in the document leaves them out.

```ts
interface CustomNodeHostSource
```

**Members**

- `getNodes(): readonly NodeModel[]` — Every node, in MODEL order — captures come out in this order, so exports are stable.
- `getHost(nodeId: string): HTMLElement | null | undefined` — The element this node's content is painted into, if it has one right now.
- `isExportable?(node: NodeModel): boolean` — Whether this node's widget can be in an export at all. Default: `metadata.useHTMLLayer` is set. (The JS canvas also refuses an explicitly frozen node, which the render pass of the same export omits.)
- `bounds?(node: NodeModel): Rectangle` — The world rect the capture is placed at. Default: `node.position` + `node.size`.
- `materialize?(nodes: readonly NodeModel[]): () => void` — Make sure the hosts of these (in-scope) nodes exist and are laid out, and return the undo. Called before every read. Default: nothing to mount.
- `pendingPaint?(nodeId: string): Promise<void> | undefined` — A promise for a host whose painter has not finished — the async path waits for it.
- `paintWarning?(nodeId: string, waited: boolean, timeoutMs: number): string | undefined` — A per-node caveat (a painter that threw, or is still painting), led into the capture's warning.
- `pin?(nodeIds: readonly string[]): () => void` — Hold these hosts in the document while an async capture waits; returns the release.

<!-- 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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-classes): 3 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-constants): 13 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-functions): 45 functions.
- [Interfaces A–T](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-interfaces-a-t): 34 interfaces, `AnchorContext` to `TemplateCapability`.
- [Interfaces T–V](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-interfaces-t-v): 5 interfaces, `ToolCapability` to `ViewportPortal`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-ext-types): 14 types.
- [`DiagramRegistry`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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.
- `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.
- `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.
- `dispose(): void` — Drop every contribution this diagram made. No-op on the global registry.

<!-- source: grafloria-renderer-instance.md -->

# Instance

Import these from `@grafloria/renderer`.

## On their own pages

- [`CreateDiagramOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-creatediagramoptions)
- [`DiagramInstance`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-diagraminstance)
- [`EdgeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-edgespec): An edge, as a host hands it in. Node-to-node, like React Flow.
- [`NodeSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-instance-nodespec)
- [`PortSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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`

Spec → `PortModel`, carrying the WHOLE port vocabulary through.

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 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 what the canvas draws — every visible node, every routed
link waypoint, every group frame with its caption — 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} — no `selected` either, for the same reason.

```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.

It carries no `selected`. Selection is viewer state that changes on every
click, and `nodes:change` — when hosts store this projection — fires for the
document (a node added, removed, dropped), not for a click. A projected
`selected` therefore went stale the moment the user clicked elsewhere, and the
host's next write (a rename) selected the node again. Absent, writing the
projection back never touches the selection. A host that wants to DRIVE the
selection still sets `selected` in its own specs (`setNodes` applies it) and
reads it from `selection:change`.

```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).
- `hasActiveGesture(): boolean` — True while a resize / rotate / vertex gesture owns the pointer.
- `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`, …).
- `beginSelectionBatch?(): void` — Optional: bracket a USER GESTURE so the host can coalesce its selection events. The binder opens a batch around every DOM event it handles, and holds one from a press to its release (a marquee clears on the press and selects on the release). Batches nest; a host that implements these emits ONE `selection:change`, with the final selection, when the outermost one closes — instead of one per model mutation plus the binder's own (which fired stale, mid-gesture events: `{n:1,e:1}` then `{n:1,e:0}` for one click).
- `endSelectionBatch?(): void`

### `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.
- `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.
- `exportSvgString(options?: ExportOptions): SvgExportResult` — Synchronous, DOM-free, deterministic. Carries `warnings`.
- `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.
- `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. The diagram type comes along, so `exportText` writes it back in the grammar it came in.
- `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.

`router` (where the line goes) and `connector` (how it is drawn, by registered
name) are separate, per-link settings that round-trip through `serialize()`. `metadata` is how a link names its anchor and its connection-point strategy
(floating edges), and `waypoints` restore saved bends.

```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` |  | Select (or deselect) the edge. Omitted, the selection is left alone; see `NodeSpec.selected`. |
| `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` |  | Select (or deselect) the node. Omitted, `setNodes` leaves the selection as the user made it — and `toNodeSpec` never projects it, so a host writing its stored specs back never re-selects anything. |
| `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.

Carries the whole port vocabulary through to the `PortModel`: glyph shapes,
port labels, the pluggable layout strategies, port groups, data types,
directional gating, link spots and link spreading. `Grafloria.render()`,
`<grafloria-flow>` and every framework component build their ports from this.

```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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-classes): 8 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-constants): 9 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-functions): 14 functions.
- [Interfaces A–T](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-interfaces-a-t): 33 interfaces, `AddWaypointResult` to `TouchGestureOptions`.
- [Interfaces V–W](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-interfaces-v-w): 5 interfaces, `ValidationIssue` to `WhiteboardHost`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-types): 9 types.
- [`ControlPointEditor`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-controlpointeditor): ControlPointEditor provides functionality for editing bezier curve control points
- [`InteractionController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-interactioncontroller): InteractionController — the framework-agnostic interaction brain.
- [`KeyboardNavigationController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-keyboardnavigationcontroller)
- [`SelectionToolsController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-selectiontoolscontroller)
- [`SnapController`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-snapcontroller)
- [`ToolHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-interaction-toolhandle): One grabbable tool in the floating layer.
- [`WaypointEditor`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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.
- `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 delegates to `evaluatePortConnection`,
the engine-side validator the connection drag also runs through, so a port you
can drag to is a port the magnet snaps to.

`rejectDuplicatesByDefault` is this call site's own 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`

SnapController — alignment snaplines, equal-spacing guides, grid snap,
keep-in-bounds, magnetic snap-to-port and proximity connect.

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.

InPlaceTextEditor — the model behind double-click-to-edit.

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: an in-place edit is one undo step.

```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
- `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` — Easy Connect: 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.
- `updateLinkReconnection(worldX: number, worldY: number, engine: DiagramEngine): boolean` — Update the in-progress endpoint reconnection as the cursor moves.
- `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.
- `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.
- `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, engine?: DiagramEngine): boolean` — Insert a bend where the path was clicked. Returns false when nothing was inserted: a read-only link, a point too close to an endpoint, or a point on an existing bend (a bend is never stacked on another).
- `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.
- `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.
- `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.
- `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.
- `hitTest(layer: SelectionToolLayer, worldX: number, worldY: number): ToolHandle | null` — Which tool (if any) is under a world point.
- `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}). `snap` optionally quantises the resulting box (grid / alignment) — the host passes the SnapController's hook so snapping composes with resizing.
- `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.
- `computeSnap(box: Rectangle, others: Rectangle[]): SnapResult` — Snap `box` against `others`.
- `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.
- `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?
- `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 (a 6px dot would sit 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-svg.md -->

# Svg

Import these from `@grafloria/renderer`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-classes): 7 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-constants): 16 constants.
- [Functions A–P](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-a-p): 68 functions, `applySpread` to `pointAtPositionOnPolyline`.
- [Functions P–W](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-functions-p-w): 38 functions, `portLabelGeometry` to `wrapText`.
- [Interfaces A–N](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-interfaces-a-n): 26 interfaces, `AutoSizeOptions` to `NodeToolbarConfig`.
- [Interfaces O–S](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-interfaces-o-s): 30 interfaces, `OptimizerFrame` to `SpotInput`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-types): 12 types.
- [`ShapeDefinition`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-shapedefinition): The single geometry contract every node shape implements. Register once via
- [`SVGRenderer`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-svgrenderer)
- [`TextBlockOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-svg-textblockoptions)

<!-- source: grafloria-renderer-svg-classes.md -->

# Classes

Import these from `@grafloria/renderer`.

## Classes

### `ArrowRenderer`

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.
- `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 } });
```

### `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.
- `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.
- `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 }
```

### `groupFrameRects`

Every drawn group frame's world rectangle, grown to take in a caption that runs past
the frame. Frames the renderer does not draw — a layout container with
`frameChrome: 'none'` (unless collapsed, which always draws) or a group with no
geometry yet — are left out.

```ts
function groupFrameRects(
  diagram: { getGroups?: () => FrameGroup[] } | null | undefined,
  options: GroupFrameBoundsOptions = {}
): Rectangle[]
```

### `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.

```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.

`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]

```ts
function parallelOffsets(count: number, spacing = DEFAULT_PARALLEL_SPACING): number[]
```

### `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
```

<!-- source: grafloria-renderer-svg-functions-p-w.md -->

# Functions P–W

Import these from `@grafloria/renderer`.

## Functions

### `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-n.md -->

# Interfaces A–N

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` |  |  |

### `GroupFrameBoundsOptions`

```ts
interface GroupFrameBoundsOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `captionFontSize?` | `number` |  | Caption font size for theme frames (the theme's `fontSize.sm`). Default 12. |

### `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[]` |  |  |

<!-- source: grafloria-renderer-svg-interfaces-o-s.md -->

# Interfaces O–S

Import these from `@grafloria/renderer`.

## Interfaces

### `OptimizerFrame`

```ts
interface OptimizerFrame
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `OptimizerNode[]` |  |  |
| `links` | `OptimizerLink[]` |  |  |

### `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. |
| `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-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.
- `getQualityState(): { tier: LODLevel; governor?: GovernorState }` — The tier actually rendered last frame, and the governor's reasoning for it.
- `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".
- `getFrameCoverage(): FrameCoverage | null` — The {@link FrameCoverage} of the most recent `render()` pass.
- `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.
- `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.
- `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.
- `applyInstanceScope(element: Element | null | undefined): void` — Put this diagram's scope on a host element.
- `setViewLifecycle(lifecycle: ViewLifecycle | null): void` — Install the freeze / lazy-mount gate.
- `getViewLifecycle(): ViewLifecycle | null`
- `getDeferredEntities(): ReadonlyArray<readonly [LazyEntityKind, string]>` — What culling admitted on the last frame and the gate held back.
- `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.
- `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.
- `exportPages(pagination: PaginationOptions, options: ExportOptions = {}): PagedSvgResult` — Slice the diagram into pages.
- `exportPaginatedPdf(pagination: PaginationOptions, options: ExportOptions = {}): PdfExportResult` — A multi-page PDF of a diagram too big for one sheet.
- `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.
- `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.
- `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).
- `getAccessibleFocus(): { type: 'node' | 'link' | 'comment'; id: string } | null`
- `setCommentSource(source: CommentSource | null): void` — Attach (or detach) the source of comment pins.
- `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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-classes): 1 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-constants): 16 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-functions): 50 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-themes-interfaces): 11 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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–S](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-b-s): 27 interfaces, `BooleanPropertyDefinition` to `SelectOption`.
- [Interfaces S–V](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-interfaces-s-v): 13 interfaces, `SelectPropertyDefinition` to `VNode`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-types): 5 types.
- [`ExportOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-exportoptions): Export options.
- [`PropertyDefinition`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-propertydefinition): Definition of a single property in a property schema
- [`PropertyValidation`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-propertyvalidation): Validation rules for property values
- [`SVGRendererConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-svgrendererconfig): SVG Renderer Configuration
- [`VNodeProps`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-types-vnodeprops): VNode properties supporting SVG attributes, styles, and event handlers

<!-- source: grafloria-renderer-types-interfaces-b-s.md -->

# Interfaces B–S

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 |

### `ColorPalette`

Color palette for theme

```ts
interface ColorPalette
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `background` | `{ default: string; surface: string; elevated: string; }` |  | Background colors |
| `text` | `{ primary: string; secondary: string; disabled: string; inverse: string; }` |  | Text colors |
| `node` | `{ default: { fill: string; stroke: string; }; selected: { fill: string; stroke: string; }; 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; 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` |  |  |

### `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. |

### `IRenderer`

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. 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.

### `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'
};
```

### `PropertySchema`

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?` | `{ version?: string; author?: string; 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'
  }
};
```

### `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 |

<!-- source: grafloria-renderer-types-interfaces-s-v.md -->

# Interfaces S–V

Import these from `@grafloria/renderer`.

## Interfaces

### `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; }` |  | 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` |  |  |

### `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.

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-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-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-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-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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core): 45 exports, including `ArchitectureGrid`, `ArchitectureLayoutOptions`, `ArchitectureLayoutResult`, `BulkSelectionOptions`
- [Collab](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-collab): 25 exports, including `ActorId`, `AddOp`, `applyEntitySet`, `applyOp`
- [Commands](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands): 64 exports, including `AddGroupCommand`, `AddLinkCommand`, `AddNodeCommand`, `AddPortCommand`
- [Comments](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-comments): 22 exports, including `AnchorSpec`, `CommentAnchor`, `CommentMessage`, `CommentRegisterTree`
- [Config](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-config): 10 exports, including `ConnectionLineStyle`, `ControlPointEditorConfig`, `DEFAULT_INTERACTION_CONFIG`, `DELIBERATE_MODE_CONFIG`
- [Dsl](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl): 118 exports, including `adoptTextGrammarMetadata`, `applyArchitectureModel`, `applyBlockGrid`, `ARCHITECTURE_ICONS`
- [Engine](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-engine): 8 exports, including `DiagramEngine`, `DiagramEngineConfig`, `DiagramMode`, `isValidDiagramMode`
- [Interaction](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-interaction): 24 exports, including `areSiblingLanes`, `clampBoxInto`, `CollapseOptions`, `CommandDispatcher`
- [Layout](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout): 177 exports, including `analyseGraphShape`, `ApplyLayoutConfig`, `assessLabelClearance`, `assessPortRespect`
- [Layout — Grid Pack](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-grid-pack): 12 exports, including `BesideSide`, `CachedCell`, `GridColumnLayout`, `GridLayoutCache`
- [Layout — Incremental](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-incremental): 11 exports, including `affectedRegion`, `alignToPrevious`, `constraintsForStrategy`, `IncrementalOptions`
- [Layout — Sugiyama](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-sugiyama): 11 exports, including `createLayeredLayout`, `inferDirection`, `LayeredLayoutOptions`, `LayoutDirection`
- [Models](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models): 45 exports, including `bumpMutationEpoch`, `ChangeEntry`, `CollapsedState`, `DEFAULT_GROUP_HEADER_HEIGHT`
- [Ports](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-ports): 47 exports, including `AnchorSide`, `ANY_PORT_TYPE`, `arePortDataTypesCompatible`, `buildDynamicPortCommands`
- [Routing](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-routing): 40 exports, including `AStarHeuristic`, `AStarOptions`, `AStarRouter`, `CostFunction`
- [Serialization](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-serialization): 41 exports, including `beginIncrementalCapture`, `canonicalStringify`, `checksumOf`, `DeserializedSubgraph`
- [State](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-state): 9 exports, including `ConnectionDragState`, `ConnectionStateManager`, `ConnectionValidator`, `DiagramState`
- [Sync](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync): 40 exports, including `ActorFrontier`, `Awareness`, `AwarenessChange`, `AwarenessMessage`
- [Template Library](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-template-library): 39 exports, including `Activity`, `BadgeLabel`, `BarChart`, `ButtonNode`
- [Templates](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-templates): 26 exports, including `builtInStencils`, `DataBindConfig`, `DragHandlerConfig`, `FlexDirection`
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types): 85 exports, including `Alignment`, `ALL_LOD_FEATURES`, `ArrowStyle`, `BoundingBox`
- [Utils](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-utils): 17 exports, including `boxesIntersect`, `clampToBox`, `createBoundingBox`, `deepClone`
- [Validation](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-validation): 10 exports, including `createConnectionGroupValidator`, `GroupTypeDefinition`, `isConnectionAllowedByGroup`, `LinkTypeDefinition`

<!-- source: grafloria-engine-collab.md -->

# Collab

Import these from `@grafloria/engine`.

## 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?
- `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.
- `silently(fn: () => void): void` — Run `fn` with capture SUPPRESSED — the model mutations it makes emit no ops.
- `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.
- `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.

### `ReferentialIntegrity`

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.
- `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?
- `settle(op: Op): void` — The INCREMENTAL invariant check: only what THIS op could possibly have broken.
- `reconcile(): void` — Re-evaluate the invariant over the WHOLE document.
- `forget(op: Op): void` — Drop a link from quarantine for good — its presence register says it is gone.

### `Replica`

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.
- `undo(): Op[]` — UNDO MY LAST EDIT — not the last edit.
- `redo(): Op[]`
- `transact<T>(fn: () => T): T` — Group everything `fn` does into ONE undo step.
- `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.
- `dispose(): void`

### `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.
- `transact<T>(fn: () => T): T` — Group everything `fn` does into ONE undo step.
- `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.
- `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.

Undo 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-comments.md -->

# Comments

Import these from `@grafloria/engine`.

## 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

### `CommentStore`

```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.
- `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.
- `deleteMessage(threadId: string, messageId: string): boolean` — Delete a message — TOMBSTONE, never key removal.
- `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.
- `thread(threadId: string): CommentThreadView | undefined` — Assemble a thread for reading.
- `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`

### `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.
- `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.
- `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-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` |  | 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` |  | React-Flow "Proximity Connect": 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` |  | Auto-link radius in world units for {@link enableProximityConnect}. Defaults to `DEFAULT_SNAP_CONFIG`'s value when unset/0. |
| `enableHelperLines` | `boolean` |  | React-Flow "Helper Lines": 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 (computed by the SnapController). Default false (opt-in). |
| `enableGroupMembershipOnDrop` | `boolean` |  | 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. The drop runs through `GroupMembershipService` (hit-test, per-group `canAddMember` veto, undoable Add/RemoveFromGroupCommand) and is one undo step with the move. Default true. |
| `enableInPlaceTextEdit` | `boolean` |  | Double-click a node to edit its label in place, as one undoable commit. Default false (opt-in), so a host that already answers `node:doubleclick` 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` |  | React-Flow "Easy Connect": 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'` |  | 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-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
- `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 addLink(config: { sourcePortId: string; targetPortId: string; type?: string; data?: any; }): Promise<LinkModel>` — Add link
- `async removeLink(linkId: string): Promise<void>` — Remove link
- `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.
- `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:
- `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.
- `async layout( name: string = DEFAULT_LAYOUT_NAME, options: UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult>` — Lay out the whole diagram.
- `async layoutIncremental( options: IncrementalOptions & { name?: string } & UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult & { movement: MovementReport; tween: TweenPlan }>` — Mental-map-preserving incremental layout.
- `setLayoutPort(port?: LayoutPort): void` — Run layout off the main thread.
- `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, not only the two ports. 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 (its `headerHeight`). 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-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).
- `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.
- `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.
- `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, so growing a first-row KPI can never push the strip past … |
| `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). `changed: false` alone can
also mean "already there", so 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.

For an animated transition from old to new positions instead of a snap. 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`

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>` |  | Rank per node — auto-selection and the incremental pass both read it. |
| `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-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. |
| `errors?` | `string[]` |  | When the body was parsed (`source: 'text'`): what in it could not be read — a line the parser skipped, an unclosed bracket or quote, a header that is not a diagram type — each naming its line. The import itself is best effort (the readable lines are in `diagram`); empty means the text is clean. |

### `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-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`

Register every template in the template library into a TemplateRegistry.

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-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-engine-core.md -->

# Core

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core-classes): 11 classes.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core-functions): 7 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core-interfaces): 25 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-core-types): 1 types.
- [`SelectionManager`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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).
- `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

### `ForceDirectedLayoutAlgorithm`

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
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram
- `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

### `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

### `HybridLayoutAlgorithm`

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
- `calculatePlacement(options: PlacementOptions): PlacementResult` — Calculate position for a single new node
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram
- `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)

### `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` |  |  |

### `ComponentAdapter`

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
- `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
- `updateComponentInstance(instance: any, node: NodeModel): void` — Update component instance with new node data
- `destroyComponentInstance(instance: any): void` — Destroy component instance and clean up resources
- `getRegisteredTypes(): string[]` — Get list of all registered node type identifiers
- `destroyAll?(): void` — Destroy all component instances (optional)
- `getActiveCount?(): number` — Get count of active component instances (optional)

### `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-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-commands.md -->

# Commands

Import these from `@grafloria/engine`.

## On their own pages

- [Classes A–R](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-a-r): 28 classes, `AddGroupCommand` to `RemoveStrokesCommand`.
- [Classes R–U](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-classes-r-u): 17 classes, `ResizeNodeCommand` to `UpdateLinkStyleCommand`.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-functions): 2 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-interfaces): 10 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-types): 4 types.
- [`CutCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-cutcommand): CutCommand = {@link CopyCommand} + {@link DeleteSelectionCommand}, executed as
- [`SetLinkPointsCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-setlinkpointscommand): Replace a link's `points` (its routed polyline, including any user waypoints),
- [`SetStrokePointsCommand`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-commands-setstrokepointscommand): Replace an ink stroke's point list, undoable. The stroke-edit tool's commit:

<!-- 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.

Adds a node, link or group to a group, as one undoable step.

A member that joins from outside the frame is taken in: the frame grows (it
never shrinks) to contain the member plus the group's padding and header
band, and each enclosing group grows to contain the grown frame —
`GroupModel.addMember` does that itself, on every path. On top of it, a
group with no frame yet gets one fitted around its members here. Undo
removes the member and puts every frame back exactly as it was.

Frames that something else owns are left alone (see
`GroupModel.ownsItsFrame`): a collapsed group, a layout container, a lane
or pool, a confining group, and a group drawn without a frame.

```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?
- `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.
- `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?
- `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().
- `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

### `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

<!-- source: grafloria-engine-commands-classes-r-u.md -->

# Classes R–U

Import these from `@grafloria/engine`.

## Classes

### `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.

The inline label editor commits through this command, so an edge-label edit
is one undo step like every other direct-manipulation edit.

```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

### `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

### `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) never enters history. |
| `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-commands-setlinkpointscommand.md -->

# SetLinkPointsCommand

Import it from `@grafloria/engine`.

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

Replace a link's `points` (its routed polyline, including any user waypoints),
undoable. Each bend gesture on the canvas (insert, move, remove) commits one
of these when the pointer is released.

The `hasManualWaypoints` metadata flag is part of the state being changed:
the renderer keeps a link's interior points only while that flag is set, so
execute sets it when the new path has bends and undo restores the value it
had before. Without the old value, undoing a bend drag would clear the flag
and the next re-route would drop the bend itself.

```ts
class SetLinkPointsCommand extends Command
```

**Parameters**

- `linkId`: The link to edit.
- `newPoints`: The path to apply.
- `oldPoints`: The path to restore on undo. Pass it when the link has already been changed live (during a drag); omitted, the link's points at the first execute are used.
- `oldManual`: The `hasManualWaypoints` flag to restore on undo. Pass it with `oldPoints` when the flag has also been changed live; omitted, the link's flag at the first execute is used.

**Methods**

- `constructor( private linkId: string, newPoints: Point[], oldPoints?: Point[], oldManual?: 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 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

<!-- source: grafloria-engine-commands-setstrokepointscommand.md -->

# SetStrokePointsCommand

Import it from `@grafloria/engine`.

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.

COLLAB: execute()/undo() each call `setPoints` exactly ONCE, and `points` on a
stroke is a per-property register, so stroke geometry reaches peers. 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

<!-- source: grafloria-engine-dsl.md -->

# Dsl

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-classes): 12 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-constants): 2 constants.
- [Enums](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-enums): 1 enums.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-functions): 34 functions.
- [Interfaces A–S](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-interfaces-a-s): 39 interfaces, `ASTNode` to `SubgraphNode`.
- [Interfaces S–U](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-interfaces-s-u): 7 interfaces, `SyncMetrics` to `UmlSpec`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-types): 22 types.
- [`DSL`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-dsl-dsl)

<!-- 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

### `LayoutApplicator`

```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.
- `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

### `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**

- `getErrors(): ParseError[]` — The errors the last `parse()` RECOVERED from.
- `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"]
```

### `TEXT_GRAMMAR_METADATA_KEYS`

```ts
const TEXT_GRAMMAR_METADATA_KEYS: readonly string[]
```

<!-- 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

### `adoptTextGrammarMetadata`

Make `target` carry `source`'s grammar metadata: copy every key `source` has, and
DELETE every key it lacks — a flowchart loaded after an erDiagram must not keep the
stale `diagramType` and export as ER.

```ts
function adoptTextGrammarMetadata(target: DiagramModel, source: DiagramModel): void
```

### `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. |

### `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 |
| `errors?` | `string[]` |  | Lines the flowchart parser could not read and SKIPPED. It recovers line by line (one bad line must not lose the diagram), so `parse()` never throws for these — read them here, or use `validate()`. Empty for the other grammars. |
| `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
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `SUPPORTED_TEXT_TYPES` (static) (not released yet) | `readonly string[]` |  | The diagram types the text format reads and writes back (the canvas round-trips these). |

**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.
- `generateUML(diagram: DiagramModel): string` — Generate UML DSL from diagram

<!-- source: grafloria-engine-layout.md -->

# Layout

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-classes): 18 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-constants): 7 constants.
- [Functions A–T](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-functions-a-t): 46 functions, `analyseGraphShape` to `toElkPortSide`.
- [Functions T–T](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-functions-t-t): 2 functions, `translateOptions` to `treeLayout`.
- [Interfaces A–H](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-a-h): 24 interfaces, `ApplyLayoutConfig` to `HybridOptions`.
- [Interfaces I–L](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-i-l): 29 interfaces, `ILayoutAlgorithm` to `LayoutRun`.
- [Interfaces L–U](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-interfaces-l-u): 28 interfaces, `LayoutRunOptions` to `UnifiedLayoutResult`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-types): 19 types.
- [`ELKLayoutOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-elklayoutoptions): ELK-specific layout options
- [`LayoutOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-layoutoptions): Base options for all layout adapters
- [`SubgraphLayoutManager`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-layout-subgraphlayoutmanager): Subgraph layout computation utilities
- [`UnifiedLayoutOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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
- `abstract reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram
- `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

### `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.
- `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>`

### `LayoutManager`

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
- `optimizeConnections(layoutContext?: { direction?: 'TB' | 'LR' | 'RL' | 'BT'; ranks?: Map<string, number>; }): number` — Optimize all connections after layout
- `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

### `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.

Registration is a plain map, deliberately: extension-registered layouts (via
the ExtensionHost) and the built-ins are the same kind of thing, and a host
must be able to replace a built-in — `register()` returns a disposer that
RESTORES what was there before rather than deleting the name, as every other
registry does.

```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.

### `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

### `PortAwareLayoutManager`

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.
- `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

### `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-t.md -->

# Functions A–T

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?

A measurement, not placement — the renderer's edge optimizer does collision-aware
placement at render time. 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?

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.

Measured from the routing output the adapters report. 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:
`engine.layout(name)` is THE entry point, so auto-selection composes with the
registry rather than forking a second one. 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.

Registered eagerly by `DiagramEngine.getLayoutRegistry()`, so `engine.layout()`
works with no setup call. 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.

Laziness is required, not an optimisation: constructing ELK calls
`new ElkConstructor()`, which tries to spawn elkjs's OWN nested Worker, and
inside a Web Worker that throws `_Worker is not a constructor`. Built lazily,
the layout worker constructs only the algorithm actually requested, so asking
for `force` never touches ELK.

```ts
function createBuiltInLayoutFactories(): Map<string, () => LayoutAdapter>
```

### `createDefaultLayoutRegistry`

The registry `engine.layout()` runs against.

Registration order is the override order, and it is deliberate:

1. the five ADAPTERS (dagre/elk/force/spectral/community);
  2. the PORTFOLIO (tree/grid/circular/radial/force). `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 — 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.

The two things EVERY layout in the engine gets here, whether it is a wrapped
third-party adapter or a built-in:

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`

Build the `PortInfo[]` that `PortAwareLayoutManager` and the ELK adapter read,
from the port model.

Only DECLARED ports are emitted (see the file header). Ordering is canonical —
sorted by (nodeId, side, index, id) — because layout is deterministic, and a
Map-iteration-ordered port list would make it depend on insertion order.

```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.

It does two things for every adapter:

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). The order matters,
because "highest degree" alone picks the wrong root: in the tree

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:position` 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.

Exported because the layout HOST — the path `engine.layout()` takes — does not
call `apply()` for a steppable algorithm such as force: it drives
`createRun()`/`step()`/`snapshot()` so the run can report progress and be
cancelled, and runs this pass on the snapshot itself.

```ts
function separateOverlappingNodes(
  nodes: readonly NodeModel[],
  positions: Map<string, { x: number; y: number }>,
  options: UnifiedLayoutOptions = {}
): Map<string, { x: number; y: number }>
```

### `serializeGraph`

Freeze a live graph into the wire format.

Emits nodes and links in CANONICAL (id-sorted) order, as `fromAdapter`
does. Determinism needs both halves: a seeded PRNG *and* a stable input
order. Map-iteration order would not do, because an authored diagram and
the same diagram loaded from JSON do not iterate alike.

```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
```

<!-- source: grafloria-engine-layout-functions-t-t.md -->

# Functions T–T

Import these from `@grafloria/engine`.

## Functions

### `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. Callers use one vocabulary whichever engine runs.

Exported for nested layout, which runs a DIFFERENT engine per container
(`group.subgraphLayout.algorithm`), so it has to translate the one vocabulary
per level rather than once up front. 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? 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
- `reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>` — Re-layout all nodes in the diagram
- `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
- `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). |

### `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.

ELK does genuine port-aware layered layout with orthogonal edge routing;
these are the port positions and edge sections it produced.

They are HINTS, deliberately: the
renderer computes endpoints and hands them to the routing engine
(ManhattanRouter / GlobalRouteSolver), which owns the final path. 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. |

### `LayoutRun`

An in-flight, pre-emptible layout computation.

Pure and synchronous by construction: no DOM, no clock, no `Math.random()`. That is what lets the identical object run on the main thread and inside a
Worker and produce byte-identical coordinates.

```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).

<!-- source: grafloria-engine-layout-interfaces-l-u.md -->

# Interfaces L–U

Import these from `@grafloria/engine`.

## Interfaces

### `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`

```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?` | `{ gridPosition?: { row: number; column: number }; detectedPattern?: 'grid' \| 'tree' \| 'freeform'; reason?: string; attempt?: number; [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[]; }` |  | 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' }`. |

### `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 (it can differ from the name asked for, as with `auto`). |
| `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. Nested layout resolves
whatever the registry knows (dagre, elk, force, spectral, community, or an
extension-registered engine).

```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-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). The routes come back as HINTS (see `LayoutResult.routing`) — the routing engine stays authoritative. |

<!-- 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-models.md -->

# Models

Import these from `@grafloria/engine`.

## On their own pages

- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-constants): 6 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-functions): 6 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-interfaces): 17 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-types): 7 types.
- [`DetachedParentAnchor`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-detachedparentanchor): The LAST-KNOWN ANCHOR of a node the diagram has REMOVED.
- [`DiagramEntity`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagramentity)
- [`DiagramModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-diagrammodel)
- [`GroupModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-groupmodel)
- [`LinkModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-linkmodel)
- [`NodeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-nodemodel)
- [`PortModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-portmodel)
- [`SerializedPort`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-models-serializedport)
- [`StrokeModel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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; height: number; 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. Padding and header come from the group's `padding`/`headerHeight`; size clamps
come from fitToContents.

```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.

WHERE the line goes (routing geometry), independent of HOW the polyline is
drawn (the connector). Both are per-link, serializable settings; `pathType`
is the 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`

```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.
- `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).
- `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).
- `writeCommentRegister(path: string, value: unknown): boolean` — Write ONE comment register — `t1.status`, `t1.messages.m3` — and nothing else.
- `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.
- `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.
- `replaceNode(next: NodeModel): void` — Swap the live model under `next.id` for `next`, KEEPING the links attached to it. (An id not on the canvas is simply added.)
- `getLinksForNode(nodeId: string): LinkModel[]` — Every link with an endpoint on `nodeId` (either end, including a self-loop).
- `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
- `connectNodes( sourceNode: NodeModel, targetNode: NodeModel, pathType: 'direct' | 'orthogonal' | 'smooth' | 'bezier' = 'smooth' ): boolean` — High-level API to connect two nodes
- `getNodeConnections(node: NodeModel): { incoming: LinkModel[]; outgoing: LinkModel[]; all: LinkModel[]; }` — Get all connections for a node
- `disconnectNodes(sourceNode: NodeModel, targetNode: NodeModel): number` — Disconnect two nodes
- `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.
- `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?
- `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 Option B: Pan/Zoom controls
- `fitToView(padding: number = 100): void` — Fit viewport to show all nodes (without changing zoom level) Option B: Pan/Zoom controls
- `zoomToFit(targetWidth: number, targetHeight: number, padding: number = 100): void` — Fit viewport to show all nodes AND adjust zoom to fit screen Option B: 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.
- `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
- `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.
- `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.
- `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.
- `ownsItsFrame(): boolean` — Whether a joining member may grow this group's frame. Frames that something else owns are left alone: a collapsed group, a layout container (`setLayout`), a swimlane or pool (`laneConfig`), a group that confines its members (`constrainChildren`: its frame is the extent they are kept inside), and a group drawn without a frame (`metadata.frameChrome === 'none'`, as dashboard boards are).
- `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.
- `growToFitMembers(diagram?: DiagramModel): boolean` — Grow the frame just enough to take in every member, plus padding and the header band, without ever shrinking it. A group with no frame yet gets one fitted around its members. Writes nothing when the members already fit, so an unchanged frame records no change.
- `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?
- `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`, as on NodeModel. It is how a LinkModel mutator (waypoints, control points, labels, reconnection) sees the document's read-only lock. |
| `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?
- `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.
- `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
- `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.
- `override getLabel(): string | undefined` — Overloaded label read.
- `override getLabel(labelId: string): LinkLabel | undefined` — Overloaded label read.
- `override getLabel(labelId?: string): string | LinkLabel | undefined` — Overloaded label read.
- `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.
- `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` |  | Model-level stacking order (lower renders further back), as on `GroupModel`. A document fact, so undo and the diff/collab layers see it (unlike `style.zIndex`). |
| `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.
- `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.
- `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.
- `addClass(className: string): void` — Add CSS class
- `removeClass(className: string): void` — Remove CSS class
- `setClasses(classNames: string[]): void` — REPLACE the whole class collection.
- `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.
- `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.
- `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 two ports. Either direction counts: with this off, B → A is refused when A → B exists. 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.
- `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.
- `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.
- `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.
- `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.

<!-- source: grafloria-engine-ports.md -->

# Ports

Import these from `@grafloria/engine`.

## On their own pages

- [`PortLayoutArgs`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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.

A port with no group and none of these fields resolves to the defaults
(circle glyph via `shape: undefined`, `always/on-hover` visibility from the
existing precedence chain, unlimited unrestricted connectability).

```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`?
- `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`

The gating defaults: start and end allowed, no caps, no type whitelist, duplicates allowed, self-links refused.

```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, on top of the total `maxConnections`: whether a
port may start a link or end one, and per-direction caps — e.g. a flow-chart
output that fans out to many but accepts none.

Every field is optional. The defaults:
  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 two ports. Either direction counts: with this off, B → A is refused when A → B exists. 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.

Disabled by default: a port with one link never moves, and a port with many
links keeps them on its centre point unless the author opts in.

```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. `circle` is the default glyph.

`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. `shape` is the DEFAULT: defer to the shape
registry's `portAnchor`, which knows
the true silhouette of every shape (cylinder rim seam, actor hands, hexagon
flats…). 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

- [`RoutingOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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`

```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?
- `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).

### `PathSimplifier`

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
- `removeCollinearPoints(points: Point[], tolerance: number = 0.01): Point[]` — Remove collinear points from path
- `arePointsCollinear( p1: Point, p2: Point, p3: Point, tolerance: number = 0.01 ): boolean` — Check if three points are collinear (lie on the same line)
- `perpendicularDistance( point: Point, lineStart: Point, lineEnd: Point ): number` — Calculate perpendicular distance from point to line segment
- `calculatePathLength(points: Point[]): number` — Calculate total path length
- `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);
```

### `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-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-sync.md -->

# Sync

Import these from `@grafloria/engine`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-classes): 8 classes.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-functions): 5 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-interfaces): 20 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-types): 4 types.
- [`Awareness`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-awareness): The presence store for one peer: our own state, and everyone else's.
- [`SyncAdapter`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-syncadapter): Binds one `Replica` to one `SyncTransport`.
- [`SyncAdapterOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-sync-syncadapteroptions)

<!-- 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.

### `CausalBuffer`

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.
- `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.

### `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.
- `dispose(): void`

### `UnreliableHub`

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.
- `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`

### `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. |

### `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.
- `applyRemote(actor: ActorId, state: AwarenessState | null, seq: number): AwarenessChange | null` — Take a peer's published state.
- `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.
- `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-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.
- `join(): void` — Announce ourselves and ask for what we are missing.
- `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."
- `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}.
- `sharedHistory(): Op[]` — THE LOG AS THE NETWORK SEES IT — our history, minus everything coalescing withheld.
- `setAwareness(patch: Partial<AwarenessState>): void` — Publish our cursor / selection / name.
- `dispose(): void` — Stop for good: leave (which DISCONNECTS the transport), drop every timer and unsubscribe from the transport.

<!-- source: grafloria-engine-sync-syncadapteroptions.md -->

# SyncAdapterOptions

Import it from `@grafloria/engine`.

```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. Default: a third of {@link awarenessTimeoutMs} (5 s with the defaults). 0 turns the heartbeat off; peers then expire anyone silent for the timeout, idle or not. |
| `awarenessThrottleMs?` | `number` |  | Minimum ms between awareness sends. 60Hz in, ~20Hz out. |
| `awarenessTimeoutMs?` | `number` |  | Drop a peer's presence (its cursor, selection and name) after this long without a word from it. Default 15 s. Checked on a timer, so a peer that crashes without saying goodbye is removed within about the timeout plus a third of it. A peer that leaves cleanly is removed at once. |
| `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` |  |  |

<!-- source: grafloria-engine-types.md -->

# Types

Import these from `@grafloria/engine`.

## On their own pages

- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-constants): 9 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-functions): 4 functions.
- [Interfaces B–R](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-interfaces-b-r): 40 interfaces, `BoundingBox` to `Rectangle`.
- [Interfaces S–V](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-interfaces-s-v): 16 interfaces, `SelectionEvent` to `ViewportEvent`.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-types): 11 types.
- [`ArrowStyle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-arrowstyle)
- [`createDefaultLODConfig`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-createdefaultlodconfig): Build the default 3-tier LOD policy.
- [`LinkLabel`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-linklabel)
- [`LinkStyle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-types-linkstyle)
- [`NodeStyle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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: the zoom breakpoints and
the features each tier draws.

```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' \| 'crow-foot' \| 'one' \| 'zero-or-one' \| 'zero-or-many' \| 'one-or-many' \| 'hollow-diamond' \| 'filled-diamond' \| 'generalization' \| 'open-arrow' \| 'double-arrow' \| 'cross' \| 'bar' \| 'dot' \| 'oval' \| 'half-arrow-left' \| 'half-arrow-right' \| 'custom' \| (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 = a 20px best-effort stub. |
| `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-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.4.0
- `@grafloria/renderer` ^0.5.0

## What it exports

- [Core](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-core): 20 exports, including `defineGrafloriaFlow`, `DiagramSpec`, `fromDocument`, `FromDocumentOptions`
- [Dashboard Kit](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit): 65 exports, including `BarWidgetData`, `bindDashboardGrid`, `boardHeightFor`, `buildCommitCommands`
- [Diagram Kit](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit): 53 exports, including `addColumnAt`, `assignTiers`, `bindCardEditing`, `bindJoinGuidance`
- [Stencil Kit](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-renderer-overview): `activeRegistryScope`, `actorColor`, `actorInitials`, `AddWaypointResult`, `Adjacency`, `AlignmentGuide`, `ALWAYS_SAFE_MODE`, `analyseTopology`, `AnchorContext`, `AnchorFn`, `AnchorResult`, `ANCHORS` and 984 more
- From [@grafloria/engine](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-engine-overview): `Activity`, `ActorFrontier`, `ActorId`, `AddGroupCommand`, `AddLinkCommand`, `AddNodeCommand`, `AddOp`, `AddPortCommand`, `AddStrokeCommand`, `AddToGroupCommand`, `adoptTextGrammarMetadata`, `affectedRegion` and 916 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.
- `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.
- `before(...nodes: (Node | string)[]): void` — Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.
- `remove(): void` — Removes node.
- `replaceWith(...nodes: (Node | string)[]): void` — Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.
- `append(...nodes: (Node | string)[]): void` — Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.
- `prepend(...nodes: (Node | string)[]): void` — Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes.
- `querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null` — Returns the first element that is a descendant of node that matches selectors.
- `querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>` — Returns all element descendants of node that match selectors.
- `replaceChildren(...nodes: (Node | string)[]): void` — Replace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes.
- `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` |  | Puts back what `nodes`/`edges` do not carry — groups, whiteboard strokes, kit wiring — on the mounted instance. `render()` calls it for you. |
| `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`

Everything `render()` mounts: a plain {@link DiagramSpec}, a kit spec
(`dashboard()`, `erDiagram()`, `umlDiagram()`, …), a reopened document from
`fromDocument()`, or the JSON string of a plain spec.

```ts
type RenderSpec = DiagramSpec | DashboardSpec | KitDiagramSpec | LoadedDiagramSpec | 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-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`

What the panel needs from a diagram: its engine (every edit runs as an
undoable command), its model (the selection), and a subscription to
selection changes that returns its unsubscribe function. A
`DiagramInstance` is all of this, so pass the instance itself.

```ts
interface ShapeDataPanelApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `getEngine` | `() => DiagramEngine` |  |  |
| `getModel` | `() => DiagramModel` |  |  |
| `on` | `( event: 'selection:change', handler: (change: DiagramEventMap['selection:change']) => 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`

What the palette needs from a diagram: its engine (a drop runs as one
undoable command), its model, and the viewport that turns the drop point
into world coordinates. A `DiagramInstance` is all of this, so pass the
instance itself.

```ts
interface StencilPaletteApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `getEngine` | `() => DiagramEngine` |  |  |
| `getModel` | `() => DiagramModel` |  |  |
| `viewport` | `{ clientToWorld( x: number, y: number, rect: { left: number; top: number; width: number; height: number } ): { x: number; y: number }; }` |  |  |

### `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-element-dashboard-kit.md -->

# Dashboard Kit

Import these from `@grafloria/element`.

## On their own pages

- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-constants): 16 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-functions): 19 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-interfaces): 18 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-types): 4 types.
- [`DashboardGridHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardgridhandle)
- [`DashboardGridOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardgridoptions)
- [`DashboardHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardhandle): The typed façade — the `erTable`/`umlClass` equivalent for dashboards.
- [`DashboardOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardoptions)
- [`DashboardWidgetSpec`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-dashboardwidgetspec): A widget, declared as data.
- [`SectionCaptionOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-sectioncaptionoptions)
- [`TabsOptions`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-dashboard-kit-tabsoptions): TAB CONTAINERS — a container whose children are PAGES, one visible at a
- [`WidgetHandle`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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 never gives its body away to the band.

```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.
- `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. Unlike a pointer commit (which fire-and-forgets, because the visible state is already final), these AWAIT the command execution so a caller can undo immediately after.
- `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()`:
- `exportIds(viewId?: string): Set<string>` — The node ids ONE view occupies — pass straight to `includeIds` to export just that board:
- `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. |
| `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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-classes): 6 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-constants): 4 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-functions): 22 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-interfaces): 15 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-element-diagram-kit-types): 5 types.
- [`JoinColumn`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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-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.4.0
- `@grafloria/renderer` ^0.5.0
- `rxjs` ^7.8.0
- `@grafloria/element` ^0.5.0

## What it exports

- [Core](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-core): 9 exports, including `AngularComponentAdapter`, `GRAFLORIA_CONFIG`, `GrafloriaConfig`, `GrafloriaHandleDirective`
- [Components](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components): 68 exports, including `AnimationPreset`, `AutoToolbarDirective`, `clamp01`, `ClosestHit`
- [Interaction](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-interaction): 17 exports, including `buildMarqueeRect`, `directionToIntersectionMode`, `HitKind`, `HitTestResult`
- [Services](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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
- `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-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-components.md -->

# Components

Import these from `@grafloria/angular`.

## On their own pages

- [Classes](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-classes): 5 classes.
- [Constants](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-constants): 1 constants.
- [Functions](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-functions): 30 functions.
- [Interfaces](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interfaces): 19 interfaces.
- [Types](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-types): 6 types.
- [`DiagramCanvasComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-diagramcanvascomponent): DiagramCanvasComponent
- [`GrafloriaDashboardComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-grafloriadashboardcomponent): `<grafloria-dashboard>` — the dashboard kit, the Angular way.
- [`InteractionConfigPanelComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-interactionconfigpanelcomponent): InteractionConfigPanelComponent
- [`LinkToolbarComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-linktoolbarcomponent): Card B — a floating, PATH-ANCHORED action layer.
- [`NodeToolbarComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-nodetoolbarcomponent): NodeToolbar Component
- [`PropertyPanelComponent`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-components-propertypanelcomponent): Property panel component for editing diagram node properties. Displays editable properties based on PropertySchema.
- [`RenderedLinkPath`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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>` |  |  |

### `SelectionChange`

Payload of `(selectionChange)`: the selected nodes and edges after the change
— the same shape React's `onSelectionChange`, Vue's `selectionChange` and
Qwik's `onSelectionChange$` hand their callbacks.

```ts
interface SelectionChange
```

**Properties**

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

### `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 /
- `selectionChange` — The selection changed: the selected nodes and edges AFTER the change. Same

**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. |
| `selectionChange` |  |  | The selection changed: the selected nodes and edges AFTER the change. Same name and payload as React's `onSelectionChange`, Vue's `selectionChange` and Qwik's `onSelectionChange$`. |
| `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: ExportOptions = {} ): Promise<string>` — Async export — the full pipeline, the same one `createDiagram().export()` runs.
- `exportSvg(options: ExportOptions = {}): SvgExportResult` — Synchronous SVG export. Custom nodes are captured from the HTML node layer as they stand now; NOTHING is fetched, so an external image stays a URL (with a warning) — use `await exportDiagram('svg')` to embed it, or pass `options.resolvedAssets`.
- `exportPdf(options: ExportOptions = {}): PdfExportResult` — Synchronous vector-PDF export. Custom nodes are captured as they stand now; nothing is fetched, so an external image is MISSING from the PDF (and reported in `warnings`) — use `await exportDiagram('pdf')` to embed it.
- `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).
- `scheduleRender(): void` — The ONE coalescing entry point for every re-render.
- `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.
- `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) — and every group and lane FRAME, captions included: a frame reaches past its members (a pool's title strip and empty lanes), and fitting to node boxes alone clipped it. 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
- `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.
- `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.

**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`.
- `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-services.md -->

# Services

Import these from `@grafloria/angular`.

## On their own pages

- [`AngularAnimationService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services-angularanimationservice): Angular-injectable Animation Service
- [`BreakpointManagerService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services-breakpointmanagerservice): BreakpointManager Service
- [`ComponentRendererService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services-componentrendererservice): Service for rendering Angular components inside SVG foreignObject elements. Manages component lifecycle, inputs/outputs, and container management.
- [`ModeManagerService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/developer/grafloria-angular-services-modemanagerservice): Angular service wrapper for engine ModeManager. Provides reactive API using RxJS observables.
- [`PropertyPanelService`](https://bench-grafloria-61d.atloria.app/p/bench-grafloria-61d-mQCmWpDrxv/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

### `ExecutionTrackerService`

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);
}
```

### `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.
- `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.

```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-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.