@lupinum/board-connections 1.0.0-beta.4 → 1.0.0-beta.6

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @lupinum/board-connections
+
+## 1.0.0-beta.6
+
+### Patch Changes
+
+- [#80](https://github.com/lupinum-dev/nuxt-board/pull/80) [`334b6d5`](https://github.com/lupinum-dev/nuxt-board/commit/334b6d577ed6dd0bb2e7f13399636d056203114e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Change the packaged agent docs to every documentation page, indexed in `dist/agent/AGENTS.md`, and add an "Agent setup" section to each README.
+  
+  The `./agent-docs` export still resolves to `dist/agent/AGENTS.md`. Each package now also ships its `CHANGELOG.md`.
+- Updated dependencies [[`334b6d5`](https://github.com/lupinum-dev/nuxt-board/commit/334b6d577ed6dd0bb2e7f13399636d056203114e)]:
+  - @lupinum/board-core@1.0.0-beta.6
+  - @lupinum/vue-board@1.0.0-beta.6

package/README.md

@@ -17,30 +17,6 @@
 
 Use this plugin when nodes must connect to each other. The plugin owns connection state and provides a Vue SVG layer for rendering.
 
-<!-- BEGIN:consumer-onboarding -->
-
-## Use a coding agent
-
-A coding agent is a development tool that can inspect and change your project.
-
-Copy this task prompt into your application agent:
-
-```text
-Use the installed Nuxt Board packages to implement my requested feature.
-Read the application's instructions first. Resolve @lupinum/board-core/agent-docs
-and each installed Board package’s agent-docs entry from this application
-directory. Read the relevant local pages.
-Preserve the existing AGENTS.md. If it has no equivalent guidance, append
-one short note to resolve installed package docs before integration work
-and after dependency changes. Do not install a consumer skill.
-Check the completed feature using this project's normal commands.
-```
-
-The installed documentation matches the package version. If an older version
-has no documentation export, use its README, types and matching release docs.
-
-<!-- END:consumer-onboarding -->
-
 ## Requirements
 
 Install the same version of this package, `@lupinum/board-core`, and `@lupinum/vue-board`. The fixed-version release keeps the plugin ABI aligned.
@@ -78,9 +54,54 @@ The package exports the connections plugin and the Vue connection layer.
 
 Read the [connections reference](https://nuxt-board.lupinum.com/docs/reference/connections).
 
+## Agent setup
+
+`@lupinum/board-connections` ships its documentation inside the package for coding
+agents such as Claude Code, Codex and Cursor. The pages match the installed
+version, so an agent does not follow the website for a different version.
+
+To set it up, give your coding agent this task:
+
+```text
+Set up @lupinum/board-connections for coding agents as described under "Agent setup" in its README.
+```
+
+### Steps for the agent
+
+1. Find `node_modules/@lupinum/board-connections/dist/agent/AGENTS.md`. Look in the
+   directory of the project that depends on `@lupinum/board-connections` first, then
+   in its parent directories up to the repository root (workspaces can hoist
+   packages). Read it; it lists the documentation pages.
+2. Add the section below to the project's agent instructions: `AGENTS.md`, or
+   `CLAUDE.md` if the project has only that file. If it has neither, create
+   `AGENTS.md`. Write the path relative to the repository root, through
+   `node_modules/@lupinum/board-connections` (for example
+   `apps/web/node_modules/@lupinum/board-connections/...` in a workspace). Never write
+   a resolved path such as `node_modules/.pnpm/...`: it contains the version and
+   breaks after an upgrade. If a section for `@lupinum/board-connections` already
+   exists, leave it as it is.
+
+   Use the path you found in place of the sample path:
+
+   ```md
+   ## @lupinum/board-connections
+
+   Before you change code that uses @lupinum/board-connections, read
+   `node_modules/@lupinum/board-connections/dist/agent/AGENTS.md` and the pages it
+   lists. They document the installed version. Prefer them over what you
+   remember about this package and over the website.
+   ```
+
+3. Do not copy the documentation into the project and do not install a skill.
+   The section points into the installed package, so it stays correct after
+   every upgrade or downgrade.
+
+If the file does not exist, the installed version has no packaged
+documentation. Read the package README and its TypeScript types instead.
+
 ## Support and security
 
-Open a [GitHub issue](https://github.com/lupinum-dev/nuxt-board/issues) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/nuxt-board/security/policy).
+Open a [GitHub issue](https://github.com/lupinum-dev/nuxt-board/issues) for bugs, or ask in the [Lupinum OSS Discord](https://discord.lupinum.com). Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/nuxt-board/security/policy).
 
 ## License
 

package/dist/agent/AGENTS.md

@@ -1,63 +1,59 @@
-# @lupinum/board-connections
+# @lupinum/board-connections 1.0.0-beta.6 documentation
 
-Documentation for installed version 1.0.0-beta.4.
+These pages document the installed version 1.0.0-beta.6. Prefer them over what you
+remember about this package and over the website, which may describe another version.
+Read the pages that match the task before you write code. If they do not answer a question,
+the user can ask in the Lupinum OSS Discord: https://discord.lupinum.com
 
-Read the relevant local pages before changing this package’s integration.
-Project instructions govern architecture, style and permissions.
+> A command-driven board engine and Vue renderer for products that need a real document model.
 
-## Start here
+## When to use
 
-- [Installation](./pages/docs/start-building/installation.md) — /docs/start-building/installation
-- [@lupinum/board-connections](./pages/docs/reference/connections.md) — /docs/reference/connections
+Use this site to build node-based editors with Nuxt Board.
 
-## Find a page
+## Documentation
 
-The index below maps public documentation routes to this installed snapshot.
-For links to this documentation site, use the matching local page in manifest.json
-instead of fetching a possibly different website version. Preserve URL fragments.
-External dependencies have their own versioned contracts. Report missing guidance.
-
-- [Nuxt Board documentation](./pages/docs.md) — /docs
-- [Connections](./pages/docs/build-features/connections.md) — /docs/build-features/connections
-- [Custom renderers](./pages/docs/build-features/custom-node-renderers.md) — /docs/build-features/custom-node-renderers
-- [Group nodes](./pages/docs/build-features/groups-and-nesting.md) — /docs/build-features/groups-and-nesting
-- [Performance](./pages/docs/build-features/performance.md) — /docs/build-features/performance
-- [First-party features and command guards](./pages/docs/build-features/read-only-and-command-guards.md) — /docs/build-features/read-only-and-command-guards
-- [Serialization](./pages/docs/build-features/save-and-load.md) — /docs/build-features/save-and-load
-- [Selection and interaction](./pages/docs/build-features/selection-and-keyboard.md) — /docs/build-features/selection-and-keyboard
-- [SSR deterministic scene](./pages/docs/build-features/ssr-and-deterministic-state.md) — /docs/build-features/ssr-and-deterministic-state
-- [Theming](./pages/docs/build-features/theming.md) — /docs/build-features/theming
-- [History](./pages/docs/build-features/undo-and-redo.md) — /docs/build-features/undo-and-redo
-- [Design decisions](./pages/docs/evaluate/design-decisions.md) — /docs/evaluate/design-decisions
-- [How Nuxt Board works](./pages/docs/evaluate/how-nuxt-board-works.md) — /docs/evaluate/how-nuxt-board-works
-- [Why Nuxt Board](./pages/docs/evaluate/why-nuxt-board.md) — /docs/evaluate/why-nuxt-board
-- [Contributing](./pages/docs/project/contributing.md) — /docs/project/contributing
-- [Support and security](./pages/docs/project/support-and-security.md) — /docs/project/support-and-security
-- [@lupinum/board-core types](./pages/docs/reference/board-core-types.md) — /docs/reference/board-core-types
-- [@lupinum/board-core](./pages/docs/reference/board-core.md) — /docs/reference/board-core
-- [@lupinum/board-connections](./pages/docs/reference/connections.md) — /docs/reference/connections
-- [Events and subscriptions](./pages/docs/reference/events-and-errors.md) — /docs/reference/events-and-errors
-- [Glossary](./pages/docs/reference/glossary.md) — /docs/reference/glossary
-- [@lupinum/board-history](./pages/docs/reference/history.md) — /docs/reference/history
-- [@lupinum/vue-board/minimap](./pages/docs/reference/minimap.md) — /docs/reference/minimap
-- [@lupinum/nuxt-board](./pages/docs/reference/nuxt-board.md) — /docs/reference/nuxt-board
-- [Package overview](./pages/docs/reference/package-overview.md) — /docs/reference/package-overview
-- [@lupinum/vue-board](./pages/docs/reference/vue-board.md) — /docs/reference/vue-board
-- [Vue composables](./pages/docs/reference/vue-composables.md) — /docs/reference/vue-composables
-- [Mind map](./pages/docs/solutions/mind-map.md) — /docs/solutions/mind-map
-- [Nuxt auto-imports](./pages/docs/solutions/nuxt-application.md) — /docs/solutions/nuxt-application
-- [Planning board](./pages/docs/solutions/planning-board.md) — /docs/solutions/planning-board
-- [Read-only viewer](./pages/docs/solutions/read-only-viewer.md) — /docs/solutions/read-only-viewer
-- [Workflow renderer demo](./pages/docs/solutions/workflow-builder.md) — /docs/solutions/workflow-builder
-- [Add connections and history](./pages/docs/start-building/add-connections-and-history.md) — /docs/start-building/add-connections-and-history
-- [Customize your first node](./pages/docs/start-building/customize-your-first-node.md) — /docs/start-building/customize-your-first-node
-- [Installation](./pages/docs/start-building/installation.md) — /docs/start-building/installation
-- [Your first board](./pages/docs/start-building/your-first-board.md) — /docs/start-building/your-first-board
-- [Camera and coordinates](./pages/docs/understand-the-system/camera-and-coordinates.md) — /docs/understand-the-system/camera-and-coordinates
-- [Commands and transactions](./pages/docs/understand-the-system/commands-and-transactions.md) — /docs/understand-the-system/commands-and-transactions
-- [Document and session state](./pages/docs/understand-the-system/document-and-session-state.md) — /docs/understand-the-system/document-and-session-state
-- [Nodes and hierarchy](./pages/docs/understand-the-system/nodes-and-hierarchy.md) — /docs/understand-the-system/nodes-and-hierarchy
-- [Packages and plugins](./pages/docs/understand-the-system/packages-and-plugins.md) — /docs/understand-the-system/packages-and-plugins
-- [Persistence and JSON Canvas](./pages/docs/understand-the-system/persistence-and-json-canvas.md) — /docs/understand-the-system/persistence-and-json-canvas
-- [Rendering and interaction](./pages/docs/understand-the-system/rendering-and-interaction.md) — /docs/understand-the-system/rendering-and-interaction
-- [The engine](./pages/docs/understand-the-system/the-engine.md) — /docs/understand-the-system/the-engine
+- [Why Nuxt Board](./pages/docs/evaluate/why-nuxt-board.md): The product problems Nuxt Board solves and the boundaries it keeps explicit.
+- [How Nuxt Board works](./pages/docs/evaluate/how-nuxt-board-works.md): The complete mental model from application intent to rendered board.
+- [Design decisions](./pages/docs/evaluate/design-decisions.md): The constraints Nuxt Board chooses, the problems they solve, and their costs.
+- [Installation](./pages/docs/start-building/installation.md): Install the smallest Nuxt Board package set for Vue or Nuxt.
+- [Your first board](./pages/docs/start-building/your-first-board.md): Create, populate, and mount a working board with one canonical example.
+- [Customize your first node](./pages/docs/start-building/customize-your-first-node.md): Render product-specific Vue content without creating another document schema.
+- [Add connections and history](./pages/docs/start-building/add-connections-and-history.md): Install edges and undo without expanding the core package.
+- [The engine](./pages/docs/understand-the-system/the-engine.md): State ownership, lifecycle, reads, commands, and subscriptions.
+- [Document and session state](./pages/docs/understand-the-system/document-and-session-state.md): Why rendered state and exported state can differ during a gesture.
+- [Commands and transactions](./pages/docs/understand-the-system/commands-and-transactions.md): How changes are guarded, staged, validated, committed, and published.
+- [Nodes and hierarchy](./pages/docs/understand-the-system/nodes-and-hierarchy.md): The canonical node records, geometry, parent relationships, and z-order.
+- [Camera and coordinates](./pages/docs/understand-the-system/camera-and-coordinates.md): Pan, zoom, viewport measurements, and board-space conversion.
+- [Rendering and interaction](./pages/docs/understand-the-system/rendering-and-interaction.md): What BoardRoot owns and where custom rendering begins.
+- [Packages and plugins](./pages/docs/understand-the-system/packages-and-plugins.md): One owner for each capability and the reason packages stay focused.
+- [Persistence and JSON Canvas](./pages/docs/understand-the-system/persistence-and-json-canvas.md): What the engine exports, validates, normalizes, and deliberately excludes.
+- [Custom renderers](./pages/docs/build-features/custom-node-renderers.md): Register custom Vue components for supported JSON Canvas node types while keeping board interactions intact.
+- [Connections](./pages/docs/build-features/connections.md): Add edges between nodes with the connections plugin — anchors, routing styles, and the SVG connection layer.
+- [Group nodes](./pages/docs/build-features/groups-and-nesting.md): Create groups, assign children, capture nodes by dragging, and keep z-order correct.
+- [History](./pages/docs/build-features/undo-and-redo.md): Record state changes and navigate them with the history plugin.
+- [Selection and interaction](./pages/docs/build-features/selection-and-keyboard.md): Selection modes, box selection, and the interaction state machine.
+- [First-party features and command guards](./pages/docs/build-features/read-only-and-command-guards.md): Install first-party packages and block commands with command guards.
+- [Serialization](./pages/docs/build-features/save-and-load.md): Export and import boards with the engine's JSON Canvas document API.
+- [Theming](./pages/docs/build-features/theming.md): Customize board appearance with CSS custom properties.
+- [Performance](./pages/docs/build-features/performance.md): Viewport culling, level of detail, batching, and rendering habits for large boards.
+- [SSR deterministic scene](./pages/docs/build-features/ssr-and-deterministic-state.md): Seed a board with initial nodes for server-side rendering and hydration.
+- [Workflow renderer demo](./pages/docs/solutions/workflow-builder.md): Render step-style cards with custom renderers, connections, and undo/redo.
+- [Mind map](./pages/docs/solutions/mind-map.md): Spatial topic hierarchy with connections, custom renderers, and branch-from-selection.
+- [Planning board](./pages/docs/solutions/planning-board.md): A practical planning surface with notes, grouping, and zoom-to-fit.
+- [Read-only viewer](./pages/docs/solutions/read-only-viewer.md): Display a board for viewing without allowing edits by using a command guard.
+- [Nuxt auto-imports](./pages/docs/solutions/nuxt-application.md): Use board components and composables without manual imports via the Nuxt module.
+- [Package overview](./pages/docs/reference/package-overview.md): The supported entrypoints and the capability each package owns.
+- [@lupinum/board-core](./pages/docs/reference/board-core.md): The supported public API for the headless board engine.
+- [@lupinum/board-core types](./pages/docs/reference/board-core-types.md): The public state, node, and JSON Canvas document types.
+- [@lupinum/vue-board](./pages/docs/reference/vue-board.md): Vue 3 components for rendering interactive boards.
+- [Vue composables](./pages/docs/reference/vue-composables.md): Reactive composables for accessing board state inside Vue components.
+- [@lupinum/board-connections](./pages/docs/reference/connections.md): Edge and connection management plugin with routing, anchors, and an SVG connection layer.
+- [@lupinum/board-history](./pages/docs/reference/history.md): Deterministic structural undo/redo with connection-aware state restoration.
+- [@lupinum/vue-board/minimap](./pages/docs/reference/minimap.md): Minimap composable and component for board navigation.
+- [@lupinum/nuxt-board](./pages/docs/reference/nuxt-board.md): Nuxt module with auto-imported board components and composables.
+- [Events and subscriptions](./pages/docs/reference/events-and-errors.md): React to state changes with the event system and subscribables.
+- [Glossary](./pages/docs/reference/glossary.md): Canonical definitions for Nuxt Board architecture and API terms.
+- [Contributing](./pages/docs/project/contributing.md): Set up the repo, run the docs, and make changes that are ready to review.
+- [Support and security](./pages/docs/project/support-and-security.md): Where to report bugs, request features, and disclose security issues.
+- [Nuxt Board documentation](./pages/docs.md): Learn how to build domain-specific spatial tools with the command-driven Nuxt Board engine, renderer, and focused feature packages.

package/dist/agent/pages/docs/build-features/connections.md

@@ -15,8 +15,339 @@ source: "ginko-content"
 
 Connections draw edges between nodes. Install the plugin, create edges, and the connection layer renders them as SVG paths with five routing styles.
 
-> Component omitted: `connections-board-demo`.
-> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+## Live example source
+
+Use the installation guide to register @lupinum/nuxt-board. These are the actual documentation demo files. Keep their paths under app/. The module auto-imports Board components; install the optional packages named in imports. For the local content components, use components: [{ path: "~/components/content", pathPrefix: false }, "~/components"] in nuxt.config.ts, as this site does, or import them explicitly. createDemoDocument is a local helper, not a package export. DocsLab and the inspector components provide presentation only.
+
+### app/components/demos/ConnectionsBoardDemo.vue
+
+````vue
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+import {
+  connectionsPlugin,
+  type ConnectionRouting,
+} from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+import { historyPlugin } from '@lupinum/board-history'
+import { BoardMinimap } from '@lupinum/vue-board/minimap'
+
+const engine = createBoardEngine({
+  grid: { size: 20, majorEvery: 5, snap: true, pattern: 'dot' },
+  plugins: [historyPlugin(), connectionsPlugin()],
+})
+
+const historyState = computed(() => engine.plugins.history.getState())
+const routing = ref<ConnectionRouting>('bezier')
+const INPUT_ID = asNodeId('input')
+const PARSE_ID = asNodeId('parse')
+const SCORE_ID = asNodeId('score')
+const OUTPUT_ID = asNodeId('output')
+let shuffleStep = 0
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: -80, y: -40, z: 1 },
+      grid: engine.getGridSettings(),
+      nodes: [
+        {
+          id: 'input',
+          type: 'text',
+          x: 80,
+          y: 150,
+          width: 180,
+          height: 96,
+          text: 'Collect input',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'parse',
+          type: 'text',
+          x: 340,
+          y: 80,
+          width: 200,
+          height: 96,
+          text: 'Normalize data',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'score',
+          type: 'text',
+          x: 340,
+          y: 240,
+          width: 200,
+          height: 96,
+          text: 'Score result',
+          zIndex: 3,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: 'output',
+          type: 'text',
+          x: 650,
+          y: 150,
+          width: 180,
+          height: 96,
+          text: 'Publish output',
+          zIndex: 4,
+          locked: false,
+          visible: true,
+        },
+      ],
+      selection: [],
+      nextZIndex: 5,
+    }),
+    { mode: 'replace' },
+  )
+  const connections = engine.plugins.connections
+  for (const edge of connections.getEdges()) {
+    connections.deleteEdge(edge.id)
+  }
+  connections.createEdge({
+    from: INPUT_ID,
+    to: PARSE_ID,
+    label: 'clean',
+    data: {},
+  })
+  connections.createEdge({
+    from: INPUT_ID,
+    to: SCORE_ID,
+    label: 'rank',
+    data: {},
+  })
+  connections.createEdge({
+    from: PARSE_ID,
+    to: OUTPUT_ID,
+    label: 'emit',
+    data: {},
+  })
+  connections.createEdge({
+    from: SCORE_ID,
+    to: OUTPUT_ID,
+    label: 'merge',
+    data: {},
+  })
+}
+
+function shuffle() {
+  shuffleStep = (shuffleStep + 1) % 3
+  engine.updateNode(PARSE_ID, {
+    x: 320 + shuffleStep * 28,
+    y: 60 + shuffleStep * 22,
+  })
+  engine.updateNode(SCORE_ID, {
+    x: 360 - shuffleStep * 20,
+    y: 220 + shuffleStep * 18,
+  })
+  engine.updateNode(OUTPUT_ID, {
+    x: 620 + shuffleStep * 26,
+    y: 120 + shuffleStep * 24,
+  })
+}
+
+onMounted(async () => {
+  seed()
+  await engine.zoomToFit(84, false)
+})
+</script>
+
+<template>
+  <div class="demo-frame">
+    <div class="demo-toolbar">
+      <button class="demo-danger" @click="seed">Reset</button>
+      <button @click="shuffle">Shuffle</button>
+      <span class="demo-toggle-group">
+        <button
+          :class="{ active: routing === 'bezier' }"
+          @click="routing = 'bezier'"
+        >
+          Bezier
+        </button>
+        <button
+          :class="{ active: routing === 'smooth-step' }"
+          @click="routing = 'smooth-step'"
+        >
+          Smooth
+        </button>
+        <button
+          :class="{ active: routing === 'step' }"
+          @click="routing = 'step'"
+        >
+          Step
+        </button>
+        <button
+          :class="{ active: routing === 'straight' }"
+          @click="routing = 'straight'"
+        >
+          Straight
+        </button>
+      </span>
+      <button
+        :disabled="!engine.plugins.history.canUndo()"
+        @click="engine.plugins.history.undo()"
+      >
+        Undo
+      </button>
+      <button
+        :disabled="!engine.plugins.history.canRedo()"
+        @click="engine.plugins.history.redo()"
+      >
+        Redo
+      </button>
+      <span class="demo-history-badge ml-auto"
+        >{{ historyState.undoDepth }} undo /
+        {{ historyState.redoDepth }} redo</span
+      >
+    </div>
+
+    <div class="relative">
+      <BoardRoot :engine="engine" style="height: 360px">
+        <BoardConnectionLayer :routing="routing" />
+      </BoardRoot>
+      <div
+        class="absolute right-4 bottom-4 rounded-md border border-default bg-elevated/90 p-2 shadow-lg backdrop-blur"
+      >
+        <BoardMinimap :engine="engine" :width="180" :height="110" />
+      </div>
+    </div>
+  </div>
+</template>
+````
+
+### app/utils/demoDocument.ts
+
+````ts
+import type {
+  BoardNode,
+  BoardNodeMetadata,
+  Camera,
+  GridSettings,
+  JsonCanvasDocument,
+  JsonCanvasNode,
+  NodeId,
+} from '@lupinum/board-core'
+
+type DemoNode = Omit<
+  Pick<
+    BoardNode,
+    | 'id'
+    | 'type'
+    | 'x'
+    | 'y'
+    | 'width'
+    | 'height'
+    | 'color'
+    | 'text'
+    | 'file'
+    | 'subpath'
+    | 'url'
+    | 'label'
+    | 'background'
+    | 'backgroundStyle'
+    | 'zIndex'
+    | 'locked'
+    | 'visible'
+    | 'parentId'
+  >,
+  'id' | 'parentId'
+> & {
+  id: NodeId | string
+  parentId?: NodeId | string
+}
+
+export interface DemoDocumentInput {
+  nodes: readonly DemoNode[]
+  camera?: Camera
+  grid?: GridSettings
+  selection?: readonly (NodeId | string)[]
+  nextZIndex?: number
+}
+
+function toJsonCanvasNode(node: DemoNode): JsonCanvasNode {
+  const base = {
+    id: node.id as NodeId,
+    type: node.type,
+    x: node.x,
+    y: node.y,
+    width: node.width,
+    height: node.height,
+    ...(node.color ? { color: node.color } : {}),
+  }
+
+  switch (node.type) {
+    case 'file':
+      return {
+        ...base,
+        type: 'file',
+        file: node.file ?? '',
+        ...(node.subpath ? { subpath: node.subpath } : {}),
+      }
+    case 'link':
+      return {
+        ...base,
+        type: 'link',
+        url: node.url ?? '',
+      }
+    case 'group':
+      return {
+        ...base,
+        type: 'group',
+        ...((node.label ?? node.text)
+          ? { label: node.label ?? node.text }
+          : {}),
+        ...(node.background ? { background: node.background } : {}),
+        ...(node.backgroundStyle
+          ? { backgroundStyle: node.backgroundStyle }
+          : {}),
+      }
+    case 'text':
+    default:
+      return {
+        ...base,
+        type: 'text',
+        text: node.text ?? '',
+      }
+  }
+}
+
+function toNodeMetadata(node: DemoNode): BoardNodeMetadata {
+  return {
+    zIndex: node.zIndex,
+    locked: node.locked,
+    visible: node.visible,
+    ...(node.parentId ? { parentId: node.parentId as NodeId } : {}),
+  }
+}
+
+export function createDemoDocument(
+  input: DemoDocumentInput,
+): JsonCanvasDocument {
+  return {
+    nodes: input.nodes.map(toJsonCanvasNode),
+    'x-lupinum-board': {
+      ...(input.camera ? { camera: input.camera } : {}),
+      ...(input.grid ? { grid: input.grid } : {}),
+      ...(input.selection
+        ? { selection: input.selection.map((id) => id as NodeId) }
+        : {}),
+      nextZIndex:
+        input.nextZIndex ??
+        input.nodes.reduce((max, node) => Math.max(max, node.zIndex), 0) + 1,
+      nodes: Object.fromEntries(
+        input.nodes.map((node) => [node.id, toNodeMetadata(node)]),
+      ),
+    },
+  }
+}
+````
 
 ## Setup