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

package/dist/agent/pages/docs/solutions/mind-map.md

@@ -0,0 +1,104 @@
+---
+title: "Mind map"
+description: "Spatial topic hierarchy with connections, custom renderers, and branch-from-selection."
+url: "https://nuxt-board.lupinum.com/docs/solutions/mind-map"
+route: "/docs/solutions/mind-map"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Mind map
+
+> Spatial topic hierarchy with connections, custom renderers, and branch-from-selection.
+
+> Component omitted: `mind-map-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What happens
+
+The root topic sits at the center with branches radiating outward. Each topic is a custom renderer that styles itself based on depth (root, branch, leaf). Connections use bezier routing to draw the edges between parent and child topics.
+
+Select any topic and click "Add branch" to grow the map from that point. The new node auto-connects to its parent using the connections plugin. History tracks every change so you can undo freely.
+
+Topic text stays as topic text. The renderer gets depth from the connection
+graph, so branch styling is derived from the map structure instead of hidden in
+the first line of `node.text`.
+
+## The code
+
+<code-tree defaultValue="app.vue">
+```vue [app.vue]
+<script setup lang="ts">
+import { computed } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+import { historyPlugin } from '@lupinum/board-history'
+import TopicNode from './TopicNode.vue'
+
+const ROOT_ID = asNodeId('root')
+const engine = createBoardEngine({
+  grid: { size: 20, snap: true, pattern: 'dot' },
+  plugins: [historyPlugin(), connectionsPlugin({ routing: 'bezier' })],
+})
+
+const topicDepthsById = computed(() => {
+  const depths = new Map([[ROOT_ID, 0]])
+  for (const edge of engine.plugins.connections.getEdges()) {
+    const fromDepth = depths.get(edge.from)
+    if (fromDepth !== undefined) {
+      depths.set(edge.to, fromDepth + 1)
+    }
+  }
+  return depths
+})
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh">
+    <template #node:text="{ node, selected }">
+      <TopicNode
+        :node="node"
+        :selected="selected"
+        :depth="topicDepthsById.get(node.id) ?? 2"
+      />
+    </template>
+    <BoardConnectionLayer routing="bezier" />
+  </BoardRoot>
+</template>
+```
+
+```vue [TopicNode.vue]
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  node: { text?: string }
+  depth: number
+}>()
+
+const topic = computed(() => {
+  const [title = 'Topic', detail = ''] = props.node.text?.split('\n') ?? []
+  return { title, detail }
+})
+</script>
+
+<template>
+  <div class="topic-card" :class="depthClass(depth)">
+    <strong>{{ topic.title }}</strong>
+    <p>
+      {{ topic.detail }}
+    </p>
+  </div>
+</template>
+```
+</code-tree>
+
+## Try these things
+
+- Select the root topic, then add a branch. The new node connects automatically.
+- Drag a branch away from the center. The bezier edge stretches to follow.
+- Undo a few times to watch the map shrink back.
+- Zoom out to see the full map structure.

package/dist/agent/pages/docs/solutions/nuxt-application.md

@@ -0,0 +1,47 @@
+---
+title: "Nuxt auto-imports"
+description: "Use board components and composables without manual imports via the Nuxt module."
+url: "https://nuxt-board.lupinum.com/docs/solutions/nuxt-application"
+route: "/docs/solutions/nuxt-application"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Nuxt auto-imports
+
+> Use board components and composables without manual imports via the Nuxt module.
+
+> Component omitted: `nuxt-auto-imports-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What happens
+
+This is the same board model you would build in Vue, but the Nuxt module auto-imports the component and composable layer. That removes boilerplate without changing the engine surface.
+
+## The code
+
+<code-tree defaultValue="app.vue">
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-board'],
+})
+```
+
+```vue [app.vue]
+<script setup lang="ts">
+const engine = createBoardEngine()
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh" />
+</template>
+```
+</code-tree>
+
+## Try these things
+
+- Add a node from the demo toolbar.
+- Confirm the board works without any explicit imports in the example source.
+- Compare it with the [Quick Start](/raw/docs/start-building/your-first-board.md) tabs.

package/dist/agent/pages/docs/solutions/planning-board.md

@@ -0,0 +1,51 @@
+---
+title: "Planning board"
+description: "A practical planning surface with notes, grouping, and zoom-to-fit."
+url: "https://nuxt-board.lupinum.com/docs/solutions/planning-board"
+route: "/docs/solutions/planning-board"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Planning board
+
+> A practical planning surface with notes, grouping, and zoom-to-fit.
+
+> Component omitted: `basic-board-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What happens
+
+This planning surface uses a seeded document, direct engine commands, grouping, and the default interaction model. The application can add domain renderers later without replacing its board document.
+
+## The code
+
+<code-tree defaultValue="app.vue">
+```ts [app.vue]
+const engine = createBoardEngine({
+  grid: { size: 20, majorEvery: 5, snap: true, pattern: 'line' },
+})
+
+engine.loadDocument(document, { mode: 'replace' })
+```
+
+```ts [toolbar.ts]
+engine.createNode({ type: 'text', text: 'New note' })
+engine.zoomToFit(72, false)
+```
+</code-tree>
+
+## Try these things
+
+- Click **Add note** and drag the new node around. It snaps to the grid.
+- Hold <kbd>
+  Shift
+  </kbd>
+   and click two nodes, then click **Group selection**.
+- Double-click a node to edit its text. Press <kbd>
+  Escape
+  </kbd>
+   to cancel.
+- Spread nodes apart, then click **Zoom to fit** to recenter.

package/dist/agent/pages/docs/solutions/read-only-viewer.md

@@ -0,0 +1,61 @@
+---
+title: "Read-only viewer"
+description: "Display a board for viewing without allowing edits by using a command guard."
+url: "https://nuxt-board.lupinum.com/docs/solutions/read-only-viewer"
+route: "/docs/solutions/read-only-viewer"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Read-only viewer
+
+> Display a board for viewing without allowing edits by using a command guard.
+
+> Component omitted: `read-only-toggle-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What happens
+
+This example uses `addCommandGuard` to register a command guard. The board still renders and the camera still moves, but the edit commands used by the demo exit early when read-only mode is enabled.
+
+## The code
+
+<steps>
+### Load the scene
+
+```ts
+const engine = createBoardEngine()
+engine.loadDocument(JSON.parse(savedBoardJson), { mode: 'replace' })
+```
+
+### Block mutation commands
+
+```ts
+const blocked = new Set([
+  'beginNodeDrag',
+  'beginResize',
+  'beginTextEdit',
+  'createNode',
+  'updateNode',
+  'deleteSelected',
+])
+
+const stopReadOnly = engine.addCommandGuard(({ name }) =>
+  blocked.has(name) ? 'Board is read-only.' : true,
+)
+```
+
+### Remove the guard to restore editing
+
+```ts
+stopReadOnly()
+```
+</steps>
+
+## Try these things
+
+- Leave the demo in read-only mode and try dragging or deleting a node.
+- Toggle back to edit mode and repeat the same action.
+- Watch the blocked command counter increment when a guard rejects a mutation.

package/dist/agent/pages/docs/solutions/workflow-builder.md

@@ -0,0 +1,124 @@
+---
+title: "Workflow renderer demo"
+description: "Render step-style cards with custom renderers, connections, and undo/redo."
+url: "https://nuxt-board.lupinum.com/docs/solutions/workflow-builder"
+route: "/docs/solutions/workflow-builder"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Workflow renderer demo
+
+> Render step-style cards with custom renderers, connections, and undo/redo.
+
+> Component omitted: `workflow-renderer-demo`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## What happens
+
+This example combines three patterns: app-owned workflow records, board-owned
+layout, and first-party connections/history. The workflow step fields live in
+one app model. Board nodes keep only the spatial identity that the canvas needs.
+
+The history plugin records board commands such as dragging, resizing, grouping,
+and connection edits. If your product needs undo for workflow status changes,
+put that in the workflow model's own command/history path instead of copying the
+status into `node.text`.
+
+## The code
+
+<code-tree defaultValue="app.vue">
+```vue [app.vue]
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { historyPlugin } from '@lupinum/board-history'
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { BoardConnectionLayer } from '@lupinum/board-connections/vue'
+import StepNode from './StepNode.vue'
+
+const steps = ref([
+  {
+    id: 'capture',
+    status: 'done',
+    label: 'Capture lead',
+    summary: 'Collect the request and normalize inputs.',
+  },
+  {
+    id: 'qualify',
+    status: 'active',
+    label: 'Qualify',
+    summary: 'Score, tag, and route the lead.',
+  },
+])
+const stepsById = computed(
+  () => new Map(steps.value.map((step) => [step.id, step])),
+)
+const engine = createBoardEngine({
+  plugins: [historyPlugin(), connectionsPlugin({ routing: 'step' })],
+})
+
+for (const step of steps.value) {
+  engine.createNode({
+    id: asNodeId(step.id),
+    type: 'text',
+    text: '',
+  })
+}
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh">
+    <template #node:text="{ node, selected }">
+      <StepNode :step="stepsById.get(node.id)" :selected="selected" />
+    </template>
+    <BoardConnectionLayer routing="step" />
+  </BoardRoot>
+</template>
+```
+
+```vue [StepNode.vue]
+<script setup lang="ts">
+defineProps<{
+  step?: {
+    status: 'pending' | 'active' | 'done'
+    label: string
+    summary: string
+  }
+  selected: boolean
+}>()
+</script>
+
+<template>
+  <div class="step-card">
+    <span>{{ step?.status ?? 'pending' }}</span>
+    <strong>{{ step?.label ?? 'Missing step' }}</strong>
+    <p>{{ step?.summary }}</p>
+  </div>
+</template>
+```
+</code-tree>
+
+## Try these things
+
+- Select a step, then click **Cycle selected step** to advance its status.
+- Drag a step — the routed edges redraw to stay readable and the engine history records the layout change.
+- Press <kbd>
+  ⌘
+  </kbd>
+   + <kbd>
+  Z
+  </kbd>
+   to undo the layout change, then <kbd>
+  ⌘
+  </kbd>
+   + <kbd>
+  Shift
+  </kbd>
+   + <kbd>
+  Z
+  </kbd>
+   to redo it.
+- Watch the undo/redo counter in the toolbar update in real time.

package/dist/agent/pages/docs/start-building/add-connections-and-history.md

@@ -0,0 +1,42 @@
+---
+title: "Add connections and history"
+description: "Install edges and undo without expanding the core package."
+url: "https://nuxt-board.lupinum.com/docs/start-building/add-connections-and-history"
+route: "/docs/start-building/add-connections-and-history"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Add connections and history
+
+> Install edges and undo without expanding the core package.
+
+Install both plugins when constructing the engine:
+
+```ts
+import { connectionsPlugin } from '@lupinum/board-connections'
+import { historyPlugin } from '@lupinum/board-history'
+
+const engine = createBoardEngine({
+  plugins: [connectionsPlugin(), historyPlugin()],
+})
+```
+
+Render connections under the matching `BoardRoot`:
+
+```vue
+<BoardRoot :engine="engine" style="height: 100vh">
+  <BoardConnectionLayer />
+</BoardRoot>
+```
+
+Create an edge through its installed API and undo through history:
+
+```ts
+engine.plugins.connections.createEdge({ from: source.id, to: target.id })
+engine.plugins.history.undo()
+```
+
+Plugin names must be unique. Construction throws `BoardConflictError` before installation when the tuple contains duplicate names.

package/dist/agent/pages/docs/start-building/customize-your-first-node.md

@@ -0,0 +1,38 @@
+---
+title: "Customize your first node"
+description: "Render product-specific Vue content without creating another document schema."
+url: "https://nuxt-board.lupinum.com/docs/start-building/customize-your-first-node"
+route: "/docs/start-building/customize-your-first-node"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Customize your first node
+
+> Render product-specific Vue content without creating another document schema.
+
+Register a Vue component for an existing JSON Canvas node type.
+
+```ts
+import type { BoardRendererRegistry } from '@lupinum/vue-board'
+import TaskCard from './TaskCard.vue'
+
+const renderers: BoardRendererRegistry = {
+  text: TaskCard,
+}
+```
+
+```vue
+<BoardRoot :engine="engine" :renderers="renderers" style="height: 100vh" />
+```
+
+The renderer receives the node and selection state. Store canonical content in direct node fields such as `text`; do not introduce a nested content mirror.
+
+> Component omitted: `renderer-lab`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+Switch the renderer in the lab. The card changes while the record keeps the same ID, type, text, and color.
+
+For a complete renderer contract, editing hooks, slots, and LOD behavior, read [Custom node renderers](/raw/docs/build-features/custom-node-renderers.md).

package/dist/agent/pages/docs/start-building/installation.md

@@ -0,0 +1,76 @@
+---
+title: "Installation"
+description: "Install the smallest Nuxt Board package set for Vue or Nuxt."
+url: "https://nuxt-board.lupinum.com/docs/start-building/installation"
+route: "/docs/start-building/installation"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Installation
+
+> Install the smallest Nuxt Board package set for Vue or Nuxt.
+
+## 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.
+
+## Vue
+
+```bash
+pnpm add @lupinum/board-core @lupinum/vue-board
+```
+
+Import the stylesheet once in the application entry or root component:
+
+```ts
+import '@lupinum/vue-board/style.css'
+```
+
+Nuxt Board requires Vue 3.5 and Node 20.19 or newer for the supported toolchain.
+
+## Nuxt
+
+```bash
+pnpm add @lupinum/nuxt-board @lupinum/board-core @lupinum/vue-board
+```
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-board'],
+})
+```
+
+The module registers styles and optional component/composable auto-imports. It owns no board behavior.
+
+Vue and Nuxt use the same engine. For SSR, use deterministic IDs and complete
+initial records; do not create random initial nodes during hydration. Browser-only
+measurements remain session state and are populated after mount.
+
+## Optional packages
+
+```bash
+pnpm add @lupinum/board-connections @lupinum/board-history
+```
+
+Import the minimap from `@lupinum/vue-board/minimap`; it is a subpath, not a separate package.
+
+Install optional packages only when the product needs their capability. Continue with [Your first board](/raw/docs/start-building/your-first-board.md).

package/dist/agent/pages/docs/start-building/your-first-board.md

@@ -0,0 +1,52 @@
+---
+title: "Your first board"
+description: "Create, populate, and mount a working board with one canonical example."
+url: "https://nuxt-board.lupinum.com/docs/start-building/your-first-board"
+route: "/docs/start-building/your-first-board"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Your first board
+
+> Create, populate, and mount a working board with one canonical example.
+
+Create one stable engine and pass it to `BoardRoot`.
+
+```vue
+<script setup lang="ts">
+import { createBoardEngine } from '@lupinum/board-core'
+import { BoardRoot } from '@lupinum/vue-board'
+import '@lupinum/vue-board/style.css'
+
+const engine = createBoardEngine({
+  grid: { size: 20, snap: true },
+})
+
+engine.createNode({
+  type: 'text',
+  x: 80,
+  y: 80,
+  width: 260,
+  height: 140,
+  color: '5',
+  text: 'Review onboarding',
+})
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh" />
+</template>
+```
+
+The container needs a real height. `BoardRoot` cannot infer space from an auto-sized empty parent.
+
+Try dragging, resizing, selecting, panning, and zooming. `createNode()` selects the new node by default.
+
+## What happened
+
+The engine created and selected a JSON Canvas text record. `BoardRoot` subscribed to the engine and rendered the record with the default renderer. Pointer interactions update the same engine through the framework adapter.
+
+Keep the engine instance stable after mount. Load new contents with `engine.loadDocument()` instead of replacing the engine prop.

package/dist/agent/pages/docs/understand-the-system/camera-and-coordinates.md

@@ -0,0 +1,22 @@
+---
+title: "Camera and coordinates"
+description: "Pan, zoom, viewport measurements, and board-space conversion."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/camera-and-coordinates"
+route: "/docs/understand-the-system/camera-and-coordinates"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Camera and coordinates
+
+> Pan, zoom, viewport measurements, and board-space conversion.
+
+The camera stores translation `x`, `y`, and zoom `z`. Nodes remain in board coordinates. `BoardRoot` applies the camera transform and owns viewport measurement.
+
+Use engine camera commands such as `panBy`, `zoomTo`, and `zoomToFit`. Use the exported math helpers when application UI must convert between screen and board space.
+
+Viewport size is runtime session state because it depends on the mounted DOM. It does not belong in the persisted JSON Canvas document.
+
+Rendering can derive visible bounds from the camera and viewport, then cull nodes outside the margin. Camera changes publish through their focused subscribable and events.

package/dist/agent/pages/docs/understand-the-system/commands-and-transactions.md

@@ -0,0 +1,31 @@
+---
+title: "Commands and transactions"
+description: "How changes are guarded, staged, validated, committed, and published."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/commands-and-transactions"
+route: "/docs/understand-the-system/commands-and-transactions"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Commands and transactions
+
+> How changes are guarded, staged, validated, committed, and published.
+
+Every persistent command joins one outer transaction.
+
+1. Command guards inspect an immutable description.
+2. Writable roots and plugin slices are staged.
+3. The command and nested commands update the candidate.
+4. Core and plugin invariants validate the candidate.
+5. Commit projectors finalize history and plugin effects.
+6. Subscriptions publish.
+7. Public events publish.
+
+> Component omitted: `failed-transaction-lab`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+Run the failing batch. The first nested update is staged, but the duplicate ID rejects the candidate. State, plugin slices, queued events, subscriptions, and history remain unchanged.
+
+Subscriber callbacks receive the value from before the outer command as `prev`, even when nested commands updated the same concept several times.

package/dist/agent/pages/docs/understand-the-system/document-and-session-state.md

@@ -0,0 +1,25 @@
+---
+title: "Document and session state"
+description: "Why rendered state and exported state can differ during a gesture."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/document-and-session-state"
+route: "/docs/understand-the-system/document-and-session-state"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Document and session state
+
+> Why rendered state and exported state can differ during a gesture.
+
+Committed document state contains the records a successful command can persist. Session state contains browser measurements, active interaction, snap guides, clipboard data, and transient geometry.
+
+> Component omitted: `document-session-lab`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+During a drag, `$nodes` exposes effective geometry: committed nodes plus transient overrides. `exportDocument()` continues to return committed geometry. Releasing the pointer commits the final position once. Escape or pointer cancellation discards the override.
+
+This distinction prevents every pointer move from becoming a document transaction or history entry. The trade-off is intentional: runtime and exported coordinates may differ while the gesture is active.
+
+Persist `exportDocument()`, not `getState()`, Vue refs, or DOM state.