@lupinum/board-core 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/agent/pages/docs/build-features/custom-node-renderers.md

@@ -0,0 +1,219 @@
+---
+title: "Custom renderers"
+description: "Register custom Vue components for supported JSON Canvas node types while keeping board interactions intact."
+url: "https://nuxt-board.lupinum.com/docs/build-features/custom-node-renderers"
+route: "/docs/build-features/custom-node-renderers"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Custom renderers
+
+> Register custom Vue components for supported JSON Canvas node types while keeping board interactions intact.
+
+Custom renderers make nodes look like your product, not the default text box. The board shell still handles positioning, selection, resize handles, and z-ordering — your renderer only draws content.
+
+> Component omitted: `renderer-board-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## Choose the data shape first
+
+Custom renderers do not create new node types or a second node schema. They read
+the same `BoardNode` records as the default renderer.
+
+| Need | Use |
+| --- | --- |
+| Editable text cards | `type: 'text'` with `node.text`. |
+| File previews | `type: 'file'` with `node.file` and optional `node.subpath`. |
+| Link previews | `type: 'link'` with `node.url`. |
+| Visual containers | `type: 'group'` with `node.label`, `node.background`, and `node.backgroundStyle`. |
+| Product state that is richer than JSON Canvas | Choose one canonical app model, then derive board nodes from it. |
+
+Do not put the same product field in two places. If a workflow record owns
+status and assignee, keep that record as the source of truth and rebuild the
+matching board node fields from it. If the board document is the source of
+truth, keep the data in supported JSON Canvas fields.
+
+For app-owned records, use the board node ID as the join key and pass the app
+record through a scoped slot:
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+
+const tasks = ref([{ id: 'task-1', title: 'Qualify lead', status: 'active' }])
+const tasksById = computed(
+  () => new Map(tasks.value.map((task) => [task.id, task])),
+)
+
+const engine = createBoardEngine()
+engine.createNode({
+  id: asNodeId('task-1'),
+  type: 'text',
+  text: '',
+})
+</script>
+
+<template>
+  <BoardRoot :engine="engine">
+    <template #node:text="{ node, selected }">
+      <TaskCard :task="tasksById.get(node.id)" :selected="selected" />
+    </template>
+  </BoardRoot>
+</template>
+```
+
+Here the task owns `title` and `status`; the board owns position, size,
+selection, and camera state. If the task changes, the renderer updates from the
+task record. If the user drags the card, the engine updates the board layout.
+
+## The renderer registry
+
+Map supported node types to Vue components via the `renderers` prop. The first release supports the JSON Canvas node types: `text`, `file`, `link`, and `group`.
+
+```vue
+<script setup lang="ts">
+import { createBoardEngine } from '@lupinum/board-core'
+import type { BoardRendererRegistry } from '@lupinum/vue-board'
+import TextCard from './TextCard.vue'
+
+const engine = createBoardEngine()
+
+const renderers: BoardRendererRegistry = {
+  text: TextCard,
+}
+</script>
+
+<template>
+  <BoardRoot :engine="engine" :renderers="renderers" style="height: 100vh" />
+</template>
+```
+
+Text nodes without a renderer fall through to the built-in text renderer. Other supported node types fall back to a simple label unless you provide a renderer, slot, or `fallbackRenderer`.
+
+## Writing a custom renderer
+
+A renderer is a standard Vue component that receives props from the board:
+
+```vue
+<!-- TextCard.vue -->
+<script setup lang="ts">
+import type { BoardNode } from '@lupinum/board-core'
+
+defineProps<{
+  node: BoardNode
+  selected: boolean
+  editing: boolean
+  beginEdit: () => void
+  commitText: (text: string) => void
+}>()
+</script>
+
+<template>
+  <div class="w-full h-full">
+    {{ node.text }}
+  </div>
+</template>
+```
+
+### Renderer props
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `node` | `BoardNode` | The node record: position, size, type, JSON Canvas fields, and metadata. |
+| `selected` | `boolean` | Whether the node is currently selected. |
+| `editing` | `boolean` | Whether this text node is in text editing mode. Always false for other node types. |
+| `beginEdit` | `() => void` | Enter text editing mode for a text node; otherwise a no-op. |
+| `commitText` | `(text: string) => void` | Commit a text node edit; otherwise a no-op. |
+
+Your renderer fills the node's bounding box. Use `width: 100%` and `height: 100%`.
+
+<tip>
+Use `useBoardEngine()` inside your renderer to access the engine and call commands.
+</tip>
+
+### Editing from a renderer
+
+The bundled editing callbacks are deliberately text-only. File, link, and group renderers should keep custom UI state locally and persist supported fields with `engine.updateNode()`.
+
+Do not mutate the `node` prop. Call engine commands or the renderer callbacks:
+
+```vue
+<script setup lang="ts">
+import type { BoardNode } from '@lupinum/board-core'
+
+const props = defineProps<{
+  node: BoardNode
+  editing: boolean
+  beginEdit: () => void
+  commitText: (text: string) => void
+}>()
+</script>
+
+<template>
+  <button v-if="!editing" type="button" @click="beginEdit">Edit</button>
+  <textarea
+    v-else
+    :value="props.node.text"
+    data-editor="true"
+    @change="commitText(($event.target as HTMLTextAreaElement).value)"
+  />
+</template>
+```
+
+<warning>
+Use real form controls or `contenteditable` elements for keyboard editing, and mark custom editor controls with `data-editor="true"` so board pointer and double-click handlers pass through them.
+</warning>
+
+## Slot-based rendering
+
+You can also use named slots on `BoardRoot` instead of (or in addition to) the registry:
+
+```vue
+<BoardRoot :engine="engine">
+  <template #node:text="{ node, selected }">
+    <article :class="{ selected }">
+      {{ node.text }}
+    </article>
+  </template>
+</BoardRoot>
+```
+
+### Resolution order
+
+1. `#node:{type}` named slot (highest priority)
+2. `#node` fallback slot
+3. `renderers[type]` from the registry
+4. `fallbackRenderer` prop
+5. Built-in text renderer (lowest priority)
+
+## Level of detail (LOD)
+
+`BoardRoot` assigns one of three LOD levels based on screen-space size:
+
+| LOD | Condition | What renders |
+| --- | --- | --- |
+| `full` | Selected, or >= 96px | Your custom renderer. |
+| `simple` | 6–96px | Minimal placeholder with stripe pattern. |
+| `hidden` | < 6px | Nothing (unmounted from DOM). |
+
+Selected nodes always render at `full` LOD regardless of size.
+
+<collapsible>
+### Custom resize handles
+
+Override resize handle appearance with the `handle` slot:
+
+```vue
+<BoardRoot :engine="engine">
+  <template #handle="{ handle }">
+    <div class="my-custom-handle" :data-resize="handle" />
+  </template>
+</BoardRoot>
+```
+
+The `data-resize` attribute is required — `BoardRoot` uses it to identify which handle was clicked.
+</collapsible>

package/dist/agent/pages/docs/build-features/groups-and-nesting.md

@@ -0,0 +1,172 @@
+---
+title: "Group nodes"
+description: "Create groups, assign children, capture nodes by dragging, and keep z-order correct."
+url: "https://nuxt-board.lupinum.com/docs/build-features/groups-and-nesting"
+route: "/docs/build-features/groups-and-nesting"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Group nodes
+
+> Create groups, assign children, capture nodes by dragging, and keep z-order correct.
+
+Groups are board nodes with `type: 'group'`. Children point at a group through `parentId`, and the engine moves the whole subtree when the group moves.
+
+## Create a group
+
+A group stores its display name in `label`. Its visual color lives on the top-level `color` field.
+
+```ts
+const group = engine.createNode({
+  type: 'group',
+  x: 50,
+  y: 50,
+  width: 520,
+  height: 360,
+  color: '6',
+  label: 'Group',
+})
+```
+
+The default Vue renderer uses the color for the group border, tinted fill, and label chip.
+
+## Assign children
+
+Set `parentId` when creating or updating a node:
+
+```ts
+const card = engine.createNode({
+  type: 'text',
+  x: 90,
+  y: 110,
+  width: 260,
+  height: 140,
+  parentId: group.id,
+  text: 'Node',
+})
+
+engine.updateNode(card.id, { parentId: undefined })
+```
+
+Clearing `parentId` removes the node from the group.
+
+## Capture nodes by dragging a group
+
+When a group is dragged over visible, unlocked nodes, the engine checks final node bounds. A node that is fully contained by the moved group becomes a child of that group.
+
+This is the behavior users expect from spatial tools: drop a group over cards, then move the group again and the captured cards follow.
+
+```ts
+engine.select([group.id])
+engine.translateSelectedNodes(320, 0)
+```
+
+`translateSelectedNodes()` uses the same hierarchy logic as pointer dragging.
+
+## Wrap the current selection
+
+Use selection helpers to create a group around selected nodes:
+
+```ts
+import { getSelectionBounds, getSelectionNodes } from '@lupinum/board-core'
+
+function wrapSelectionInGroup(engine: BoardEngine) {
+  const selected = getSelectionNodes(engine)
+  const bounds = getSelectionBounds(engine)
+
+  if (selected.length === 0 || !bounds) {
+    return
+  }
+
+  const padding = 24
+  const group = engine.createNode({
+    type: 'group',
+    x: bounds.minX - padding,
+    y: bounds.minY - padding,
+    width: bounds.maxX - bounds.minX + padding * 2,
+    height: bounds.maxY - bounds.minY + padding * 2,
+    color: '5',
+    label: 'Group',
+    select: false,
+  })
+
+  for (const node of selected) {
+    engine.updateNode(node.id, { parentId: group.id })
+  }
+
+  engine.sendToBack(group.id)
+  engine.select([group.id, ...selected.map((node) => node.id)])
+}
+```
+
+The important steps are creating the group, assigning `parentId`, and sending
+the group behind its children.
+
+## Keep groups behind children
+
+Groups should render behind their children. Send the group behind once; the
+engine maintains descendant ordering as hierarchy changes:
+
+```ts
+engine.sendToBack(group.id)
+```
+
+The engine also keeps descendants above their group during drag and front/back commands.
+
+## Nested groups
+
+Nested groups work through the same `parentId` field:
+
+```ts
+const outer = engine.createNode({
+  type: 'group',
+  width: 600,
+  height: 420,
+  label: 'Group',
+})
+
+const inner = engine.createNode({
+  type: 'group',
+  x: 80,
+  y: 80,
+  width: 320,
+  height: 220,
+  parentId: outer.id,
+  label: 'Group',
+})
+```
+
+When a node could belong to multiple groups, containment helpers choose the smallest visible group that fully contains the node bounds.
+
+## Custom group rendering
+
+Custom renderers receive the same node record as other node types. Read group title from `node.label` and color from `node.color`.
+
+```vue [MyGroupRenderer.vue]
+<script setup lang="ts">
+import type { BoardNode } from '@lupinum/board-core'
+
+const props = defineProps<{
+  node: BoardNode
+  selected: boolean
+}>()
+</script>
+
+<template>
+  <div class="group-shell" :class="{ 'is-selected': selected }">
+    <span>{{ props.node.label ?? 'Untitled group' }}</span>
+  </div>
+</template>
+```
+
+Use CSS variables from the board shell when you want your renderer to match the built-in color system:
+
+```css
+.group-shell {
+  border: 2px solid var(--board-node-color-soft, var(--board-group-border));
+  background: var(--board-node-tint, var(--board-group-bg));
+}
+```

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

@@ -0,0 +1,76 @@
+---
+title: "Performance"
+description: "Viewport culling, level of detail, batching, and rendering habits for large boards."
+url: "https://nuxt-board.lupinum.com/docs/build-features/performance"
+route: "/docs/build-features/performance"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Performance
+
+> Viewport culling, level of detail, batching, and rendering habits for large boards.
+
+Nuxt Board keeps large boards usable with viewport culling, level of detail, requestAnimationFrame pointer updates, and granular subscriptions. Your code still needs to batch bulk operations and avoid deep-reactive engine wrappers.
+
+## Viewport culling
+
+`BoardRoot` only renders nodes within the viewport plus a configurable margin. Nodes outside are completely unmounted from the DOM:
+
+```vue
+<BoardRoot :engine="engine" :cull-margin="200" />
+```
+
+Increase `cull-margin` if nodes appear too late during fast panning. Decrease it when DOM count matters more than early rendering.
+
+## Level of detail (LOD)
+
+| LOD | Condition | What renders |
+| --- | --- | --- |
+| `full` | Selected, or >= 96px on screen | Full custom renderer. |
+| `simple` | 6–96px | Lightweight placeholder that preserves node color and group shape. |
+| `hidden` | < 6px | Nothing (unmounted). |
+
+Selected nodes always render at `full` detail. Zoomed-out boards keep colored borders and fills so users can still scan structure without mounting every custom renderer.
+
+## Batching
+
+Use `engine.batch()` when creating many nodes at once:
+
+```ts
+engine.batch(() => {
+  for (let i = 0; i < 100; i++) {
+    engine.createNode({
+      type: 'text',
+      x: i * 260,
+      y: 0,
+      text: `Node ${i}`,
+    })
+  }
+  // One notification instead of 100
+})
+```
+
+## Best practices
+
+Do not wrap the engine in `reactive()`. The engine manages its own reactivity through subscribables. Use `shallowRef` if you need to store the engine in Vue state.
+
+Prefer composables such as `useBoardCamera()` and `useBoardNodes()` over manual subscriptions. They keep component dependencies narrow.
+
+Keep node updates immutable. Pass a fresh patch to `engine.updateNode()` instead of mutating objects returned from snapshots.
+
+Batch bulk operations with `engine.batch()` so subscribers receive one coherent update.
+
+<collapsible>
+### RAF throttling
+
+`BoardRoot` throttles pointer projection updates to one internal adapter call per animation frame. Applications do not drive the pointer state machine directly.
+</collapsible>
+
+<collapsible>
+### Subscribable granularity
+
+The five subscribables (`$camera`, `$nodes`, `$selection`, `$interaction`, `$snapGuides`) fire independently. A camera change does not trigger a `$nodes` notification. This prevents cascading re-renders in Vue's reactivity system.
+</collapsible>

package/dist/agent/pages/docs/build-features/read-only-and-command-guards.md

@@ -0,0 +1,52 @@
+---
+title: "First-party features and command guards"
+description: "Install first-party packages and block commands with command guards."
+url: "https://nuxt-board.lupinum.com/docs/build-features/read-only-and-command-guards"
+route: "/docs/build-features/read-only-and-command-guards"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# First-party features and command guards
+
+> Install first-party packages and block commands with command guards.
+
+First-party features are package infrastructure for this workspace. They are how
+`@lupinum/board-history` and `@lupinum/board-connections` attach state, events,
+and persistence to the core engine.
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { historyPlugin } from '@lupinum/board-history'
+
+const engine = createBoardEngine({
+  plugins: [historyPlugin(), connectionsPlugin({ routing: 'step' })],
+})
+```
+
+This is not a third-party plugin surface. The supported consumer API is the
+package API exposed by each first-party package, such as `engine.plugins.history` and
+`engine.plugins.connections`.
+
+> Component omitted: `read-only-toggle-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## Command guards
+
+`addCommandGuard` registers a command guard. Use it when an app needs read-only
+mode, audit logging, or one concrete product policy.
+
+```ts
+engine.addCommandGuard(({ name }) =>
+  name === 'deleteSelected' ? 'Deleting nodes is disabled.' : true,
+)
+```
+
+<warning>
+If a guard returns a reason, the board state does not change and the command
+throws `CommandBlockedError` with that reason. Listen to `command:blocked` when
+the UI also needs a general blocked-command signal.
+</warning>

package/dist/agent/pages/docs/build-features/save-and-load.md

@@ -0,0 +1,142 @@
+---
+title: "Serialization"
+description: "Export and import boards with the engine's JSON Canvas document API."
+url: "https://nuxt-board.lupinum.com/docs/build-features/save-and-load"
+route: "/docs/build-features/save-and-load"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Serialization
+
+> Export and import boards with the engine's JSON Canvas document API.
+
+Save and load boards as JSON Canvas documents. Runtime snapshots are for rendering and tests; persisted documents go through `engine.exportDocument()` and `engine.loadDocument()`.
+
+> Component omitted: `json-import-export-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What to persist
+
+Persist the object returned by `engine.exportDocument()`. Serialize it when your storage requires a string. Do not persist
+`getState()`, Vue refs, or DOM state.
+
+| Data | Persisted by `exportDocument()` |
+| --- | --- |
+| JSON Canvas nodes | Yes |
+| JSON Canvas edges | Yes, when connections are installed |
+| Camera and grid settings | Yes, under `x-lupinum-board` |
+| Selection | Yes, under `x-lupinum-board` |
+| Z-order, lock state, visibility | Yes, under `x-lupinum-board` |
+| Active pointer/text interaction | No |
+| Runtime snap guides | No |
+
+## Quick export/import
+
+The engine exports the canonical persisted document shape:
+
+```ts
+// Export
+const document = engine.exportDocument()
+localStorage.setItem('board', JSON.stringify(document))
+
+// Import
+const stored = localStorage.getItem('board')
+if (stored) {
+  engine.loadDocument(JSON.parse(stored), { mode: 'replace' })
+}
+```
+
+`loadDocument()` validates and clones imported data before it changes the board.
+To keep imports safe on the browser main thread, one document supports up to
+10,000 nodes, 20,000 edges, 10,000 selected node IDs, 64 nested JSON levels,
+250,000 JSON values, and 8 million string characters. Also limit the raw byte
+size before calling `JSON.parse()` when documents come from an untrusted source.
+
+---
+
+## Connections
+
+```ts
+const engine = createBoardEngine({
+  plugins: [connectionsPlugin()],
+})
+
+const document = engine.exportDocument()
+engine.loadDocument(document, { mode: 'replace' })
+```
+
+Install the same first-party plugins before importing documents that use them.
+When the connections plugin is installed, it owns edge export and import. Core
+validates the JSON Canvas document and passes plugin-owned fields to installed
+plugins; core does not persist hidden connection state by itself.
+
+### Node colors
+
+Node colors are exported as top-level JSON Canvas node `color` fields:
+
+```json
+{
+  "id": "card-1",
+  "type": "text",
+  "x": 80,
+  "y": 80,
+  "width": 260,
+  "height": 140,
+  "color": "5",
+  "text": "Draft release notes"
+}
+```
+
+Import accepts valid preset IDs and six-digit hex colors into `BoardNode.color`. Edge colors stay on JSON Canvas edge records owned by the connections package.
+
+---
+
+## The x-lupinum-board extension
+
+Board-specific metadata that has no JSON Canvas top-level field is stored under `x-lupinum-board`. Imports still accept the legacy `x-vue-board` key from 0.1 documents. Exports always use the new key.
+
+<collapsible>
+### Document structure
+
+```json
+{
+  "nodes": [...],
+  "edges": [...],
+  "x-lupinum-board": {
+    "camera": { "x": 0, "y": 0, "z": 1 },
+    "grid": { "size": 20, "majorEvery": 5, "snap": true, "pattern": "line" },
+    "nextZIndex": 5,
+    "nodes": {
+      "node-1": { "zIndex": 1, "locked": false, "visible": true },
+      "node-2": { "zIndex": 2, "parentId": "group-1" }
+    }
+  }
+}
+```
+</collapsible>
+
+---
+
+## Import modes
+
+```ts
+// Replace all state
+engine.loadDocument(document, { mode: 'replace' })
+
+// Merge into existing board
+engine.loadDocument(document, { mode: 'merge' })
+```
+
+| Mode | Use when |
+| --- | --- |
+| `'replace'` | Loading a saved board document or resetting the whole scene. |
+| `'merge'` | Importing another document into the current board without clearing it. |
+
+`loadDocument()` validates the document. Invalid node fields, invalid node colors,
+missing edge endpoints, or unsupported plugin-owned edge data fail the import
+instead of silently creating a partial board.
+
+---