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

package/dist/agent/pages/docs/build-features/selection-and-keyboard.md

@@ -0,0 +1,145 @@
+---
+title: "Selection and interaction"
+description: "Selection modes, box selection, and the interaction state machine."
+url: "https://nuxt-board.lupinum.com/docs/build-features/selection-and-keyboard"
+route: "/docs/build-features/selection-and-keyboard"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Selection and interaction
+
+> Selection modes, box selection, and the interaction state machine.
+
+Selection and interaction are how users communicate with the board. Select nodes to act on them, drag to move, resize from handles, and box-select on empty canvas.
+
+> Component omitted: `interaction-state-viz`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## Selecting nodes
+
+```ts
+engine.select(nodeId) // replace selection
+engine.select([nodeA, nodeB]) // replace with multiple
+engine.select(nodeId, 'append') // add to selection
+engine.select(nodeId, 'toggle') // flip in/out
+engine.selectAll() // all visible nodes
+engine.clearSelection() // deselect everything
+const selected = engine.getSelection() // NodeId[]
+```
+
+| Mode | Behavior |
+| --- | --- |
+| `'replace'` | Clears existing selection, selects the given IDs (default). |
+| `'append'` | Adds IDs to the existing selection. |
+| `'toggle'` | Flips each ID in/out of the selection. |
+
+Keyboard shortcuts: <kbd>
+⌘
+</kbd>
+
+ + <kbd>
+A
+</kbd>
+
+ to select all, <kbd>
+Escape
+</kbd>
+
+ to deselect.
+
+In Vue, use the `useBoardSelection()` composable for reactive access:
+
+```vue
+<script setup lang="ts">
+const selection = useBoardSelection()
+// selection.value is readonly NodeId[]
+</script>
+```
+
+## Interaction state machine
+
+The engine tracks pointer interactions through six modes. Only one mode is active at a time.
+
+<accordion>
+<accordion-item title="Idle">
+No interaction is active. This is the default state.
+</accordion-item>
+
+<accordion-item title="Panning">
+Triggered by <kbd>
+Space
+</kbd>
+
+ + drag or middle mouse drag. The camera follows the pointer.
+</accordion-item>
+
+<accordion-item title="Dragging nodes">
+Triggered by clicking and dragging a node. If the node is part of a selection, all selected nodes move. Grid and edge snapping produce alignment guides.
+</accordion-item>
+
+<accordion-item title="Resizing a node">
+Triggered by dragging a resize handle (`n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`). Hold <kbd>
+Shift
+</kbd>
+
+ for aspect-ratio locking.
+The default Vue handles are also keyboard-operable: focus a handle and use the
+arrow keys to move its active edge by one grid step, or hold <kbd>
+Shift
+</kbd>
+
+ for a
+major-grid step.
+</accordion-item>
+
+<accordion-item title="Box selection">
+Triggered by clicking on empty canvas and dragging. By default, box selection follows AutoCAD semantics: drag left-to-right for window selection (node must be fully enclosed) and right-to-left for crossing selection (node only needs to intersect the box). Override this with `createBoardEngine({ boxSelect: { behavior: 'contain' | 'intersect' } })`.
+</accordion-item>
+
+<accordion-item title="Text editing">
+Triggered by double-clicking a text node, pressing `Enter` with one text node selected, or choosing **Edit** in the selection toolbar. The built-in `BoardNode` shows a `<textarea>` overlay. File, link, and group renderers own any custom editing UI they provide.
+</accordion-item>
+</accordion>
+
+## Pointer event flow
+
+When a pointer event hits `BoardRoot`:
+
+1. **Middle mouse / Space** starts panning.
+2. **Resize handle** selects the node, then starts resizing after the drag threshold.
+3. **Node** selects the node, then starts dragging after the drag threshold.
+4. **Empty canvas** clears selection, then starts a box-selection session after the drag threshold.
+
+Pointer movement is throttled through `requestAnimationFrame` and translated by `BoardRoot`; the low-level start, update, commit, and cancellation methods are absent from the normal engine API and available only through the unsupported first-party framework ABI. Pointer up commits the session, while pointer cancellation or Escape restores its starting geometry.
+
+<note>
+`BoardRoot` handles two-finger pinch gestures on touch devices automatically.
+</note>
+
+<collapsible>
+### Text editing commands
+
+`BoardRoot` exclusively owns pointer sessions. Applications can still control
+the meaningful text-edit boundary directly:
+
+```ts
+engine.beginTextEdit(nodeId)
+engine.commitTextEdit(nodeId, 'New text')
+engine.cancelTextEdit()
+```
+</collapsible>
+
+<collapsible>
+### Interaction events
+
+```ts
+engine.on('interaction:start', (state) => console.log('Started:', state.mode))
+engine.on('interaction:update', (state) => {
+  /* high-frequency during drag */
+})
+engine.on('interaction:end', (state) => console.log('Ended:', state.mode))
+```
+</collapsible>

package/dist/agent/pages/docs/build-features/ssr-and-deterministic-state.md

@@ -0,0 +1,67 @@
+---
+title: "SSR deterministic scene"
+description: "Seed a board with initial nodes for server-side rendering and hydration."
+url: "https://nuxt-board.lupinum.com/docs/build-features/ssr-and-deterministic-state"
+route: "/docs/build-features/ssr-and-deterministic-state"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# SSR deterministic scene
+
+> Seed a board with initial nodes for server-side rendering and hydration.
+
+SSR only works if the server and client render the same scene. That means deterministic IDs, deterministic node order, and no random creation during setup.
+
+<tabs>
+<tab label="Server" icon="i-lucide-server">
+```ts
+const engine = createBoardEngine({
+  initialNodes: [
+    {
+      id: asNodeId('welcome'),
+      type: 'text',
+      x: 100,
+      y: 100,
+      width: 240,
+      height: 160,
+      text: 'Node',
+      zIndex: 1,
+      locked: false,
+      visible: true,
+    },
+  ],
+})
+```
+</tab>
+
+<tab label="Client" icon="i-lucide-monitor">
+```vue
+<BoardRoot :engine="engine" style="height: 100vh" />
+```
+</tab>
+</tabs>
+
+<steps>
+### Use deterministic IDs
+
+```ts
+id: asNodeId('welcome')
+```
+
+### Seed the full node records up front
+
+```ts
+initialNodes: [{ id, type, x, y, width, height, text, zIndex, locked, visible }]
+```
+
+### Avoid random runtime creation during hydration
+
+Do not call `createNode()` in a way that would diverge between server and client.
+</steps>
+
+<tip>
+If the scene is bigger, build a deterministic JSON Canvas document once and import that document on both sides.
+</tip>

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

@@ -0,0 +1,102 @@
+---
+title: "Theming"
+description: "Customize board appearance with CSS custom properties."
+url: "https://nuxt-board.lupinum.com/docs/build-features/theming"
+route: "/docs/build-features/theming"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Theming
+
+> Customize board appearance with CSS custom properties.
+
+Theme the board with CSS variables. Keep semantic state, such as node color presets, in engine state.
+
+> Component omitted: `theme-playground`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+## Core tokens
+
+| Token | Default | Purpose |
+| --- | --- | --- |
+| `--board-bg` | `#fbfbfd` | Page and panel background token used by the board UI. |
+| `--board-canvas-bg` | `#f5f6fa` | Canvas background behind nodes and overlays. |
+| `--board-fg` | `#14161f` | Text, grid contrast, and general foreground color. |
+| `--board-node-bg` | `#fff` | Default node surface. |
+| `--board-node-border` | `#e4e5ee` | Default node border color. |
+| `--board-accent` | `#6366e8` | Selection accents and snap guides. |
+| `--board-node-color` | `unset` | Resolved border color for a colored node, usually set by the renderer from `node.color`. |
+| `--board-node-tint` | `unset` | Subtle surface tint for colored cards and groups. |
+| `--board-node-color-ring` | `unset` | Selection outline color for a colored node. |
+| `--board-snap-guide-color` | `rgba(99, 102, 232, 0.95)` | Snap guide line color. |
+
+## Light and dark examples
+
+<tabs>
+<tab label="Light" icon="i-lucide-sun">
+```css
+.board-root {
+  --board-bg: #f8fafc;
+  --board-fg: #0f172a;
+  --board-node-bg: #ffffff;
+  --board-node-border: rgba(15, 23, 42, 0.14);
+  --board-accent: #0ea5e9;
+}
+```
+</tab>
+
+<tab label="Dark" icon="i-lucide-moon">
+```css
+.board-root {
+  --board-bg: #0f172a;
+  --board-fg: #e2e8f0;
+  --board-node-bg: #162033;
+  --board-node-border: rgba(226, 232, 240, 0.12);
+  --board-accent: #22d3ee;
+}
+```
+</tab>
+</tabs>
+
+## Node colors
+
+Node colors are stored on `node.color` as preset IDs or six-digit hex colors:
+
+```ts
+engine.updateNode(card.id, { color: '5' })
+engine.updateNode(card.id, { color: undefined })
+```
+
+The built-in renderer resolves those colors into `--board-node-color`, `--board-node-tint`, `--board-node-color-soft`, and `--board-node-color-ring`. Use those variables in custom renderers instead of reading preset IDs directly in CSS.
+
+```css
+.task-card {
+  border-color: var(--board-node-color, var(--board-node-border));
+  background: var(--board-node-tint, var(--board-node-bg));
+}
+```
+
+The selection toolbar can batch-apply the same preset to selected cards and groups.
+
+<collapsible>
+### Styling specific states
+
+```css
+.board-node.is-selected {
+  outline: calc(3px / var(--board-zoom, 1)) solid var(--board-accent);
+}
+
+.board-node.is-locked {
+  opacity: 0.72;
+}
+
+.board-node.is-group {
+  background: var(--board-node-tint, var(--board-group-bg));
+}
+```
+
+Use state classes when you want a special selected, locked, or group look without replacing the full renderer.
+</collapsible>

package/dist/agent/pages/docs/build-features/undo-and-redo.md

@@ -0,0 +1,124 @@
+---
+title: "History"
+description: "Record state changes and navigate them with the history plugin."
+url: "https://nuxt-board.lupinum.com/docs/build-features/undo-and-redo"
+route: "/docs/build-features/undo-and-redo"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# History
+
+> Record state changes and navigate them with the history plugin.
+
+The history plugin stores references to committed structural roots. Undo and redo restore those roots atomically, without inverse actions, replay ordering, or timers. A completed gesture or explicit batch is one deterministic undo step.
+
+## Setup
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { historyPlugin } from '@lupinum/board-history'
+
+const engine = createBoardEngine({
+  plugins: [historyPlugin({ maxSteps: 100 })],
+})
+```
+
+Render the shortcut component inside the matching board root:
+
+```vue
+<script setup lang="ts">
+import { createBoardEngine } from '@lupinum/board-core'
+import { historyPlugin } from '@lupinum/board-history'
+import { BoardHistoryShortcuts } from '@lupinum/board-history/vue'
+
+const engine = createBoardEngine({ plugins: [historyPlugin()] })
+</script>
+
+<template>
+  <BoardRoot :engine="engine">
+    <BoardHistoryShortcuts :history="engine.plugins.history" />
+  </BoardRoot>
+</template>
+```
+
+### Plugin options
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `maxSteps` | `number` | `200` | Maximum undo steps to keep. Older entries are dropped. |
+
+## Undo and redo
+
+```ts
+engine.plugins.history.undo()
+engine.plugins.history.redo()
+
+if (engine.plugins.history.canUndo()) {
+  /* ... */
+}
+
+const state = engine.plugins.history.getState()
+// { undoDepth, redoDepth }
+
+engine.plugins.history.clear()
+```
+
+Call `undo()` and `redo()` outside `engine.batch()`. Replay with a retained frame inside a batch throws `BoardConflictError` before changing the document or history. If that error leaves the batch, preceding edits roll back. Group new edits in a batch, then undo or redo the completed batch as one operation.
+
+A rejected undo or redo retains its frame. Replay completes its history bookkeeping before notifying listeners, so an edit from a listener starts a new branch and clears redo.
+
+History entries are available synchronously after a successful outer command. Read methods such as `canUndo()`, `canRedo()`, and `getState()` never mutate history state.
+
+`BoardHistoryShortcuts` handles <kbd>
+⌘
+</kbd>
+
+ + <kbd>
+Z
+</kbd>
+
+ to undo and <kbd>
+⌘
+</kbd>
+
+ + <kbd>
+Shift
+</kbd>
+
+ + <kbd>
+Z
+</kbd>
+
+ or <kbd>
+⌘
+</kbd>
+
+ + <kbd>
+Y
+</kbd>
+
+ to redo. Pass the matching board's history API through its required `history` prop. It handles only events from its enclosing board.
+
+<note>
+When both `historyPlugin` and `connectionsPlugin` are installed, undoing a node deletion also restores its connected edges.
+</note>
+
+<collapsible>
+### Ignored commands
+
+History capture follows command metadata emitted by the engine and first-party features. Camera movement, transient interaction setup/teardown, imports, and selection-only commands are ignored; geometry and content mutations are recorded.
+</collapsible>
+
+<collapsible>
+### Events
+
+```ts
+engine.on('history:push', (entry) => console.log('New step:', entry.label))
+engine.on('history:undo', () => console.log('Undo'))
+engine.on('history:redo', () => console.log('Redo'))
+engine.on('history:clear', () => console.log('History cleared'))
+```
+</collapsible>

package/dist/agent/pages/docs/evaluate/design-decisions.md

@@ -0,0 +1,44 @@
+---
+title: "Design decisions"
+description: "The constraints Nuxt Board chooses, the problems they solve, and their costs."
+url: "https://nuxt-board.lupinum.com/docs/evaluate/design-decisions"
+route: "/docs/evaluate/design-decisions"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Design decisions
+
+> The constraints Nuxt Board chooses, the problems they solve, and their costs.
+
+Nuxt Board limits its extension points to keep state ownership and failure behavior understandable.
+
+## One engine owns board state
+
+**Decision:** nodes, camera, grid, selection, hierarchy, and plugin slices belong to one engine.
+
+**Benefit:** commands, snapshots, events, and persistence cannot silently use different board instances.
+
+**Cost:** applications must adapt existing product data at a deliberate boundary instead of mirroring every field into Vue state.
+
+## Commands are the mutation boundary
+
+Persistent changes stage a candidate, validate it, and publish only after the outer transaction succeeds. The cost is that direct record mutation is unsupported. The benefit is atomic failure and one observable lifecycle.
+
+## Document and session state are separate
+
+Pointer gestures update transient geometry. Completion commits once; cancellation discards the override. Runtime and exported state can differ during a gesture. That difference keeps persistence and history stable.
+
+## JSON Canvas node types are canonical
+
+Custom renderers use existing `text`, `file`, `link`, and `group` records. This rules out arbitrary type strings, but prevents a second persistence schema.
+
+## Plugins are first-party infrastructure
+
+Connections and history install during engine construction. The unsupported `@lupinum/board-core/internal` ABI exists for separately published first-party packages, not application extensions.
+
+## Nuxt owns no board behavior
+
+`@lupinum/nuxt-board` registers imports and styles. Domain invariants stay below the framework boundary.

package/dist/agent/pages/docs/evaluate/how-nuxt-board-works.md

@@ -0,0 +1,41 @@
+---
+title: "How Nuxt Board works"
+description: "The complete mental model from application intent to rendered board."
+url: "https://nuxt-board.lupinum.com/docs/evaluate/how-nuxt-board-works"
+route: "/docs/evaluate/how-nuxt-board-works"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# How Nuxt Board works
+
+> The complete mental model from application intent to rendered board.
+
+Nuxt Board follows one direct flow:
+
+```text
+application intent
+  → engine command
+  → validated transaction
+  → canonical board state
+  → subscriptions
+  → Vue rendering
+```
+
+`createBoardEngine()` creates the source of truth. Application code changes it through commands. `BoardRoot` subscribes to the engine, renders effective state, and translates pointer and keyboard input through the framework adapter.
+
+## Four boundaries
+
+1. **Commands own persistent mutation.** Guards, validation, plugins, history, subscriptions, and events see the same commit.
+2. **Session state stays transient.** Drag and resize updates render immediately without rewriting the persisted document on every pointer move.
+3. **Renderers own presentation.** A renderer receives a node record. It does not create a competing state model.
+4. **Packages own named capabilities.** Core owns nodes; connections owns edges; history owns undo stacks; Nuxt owns registration.
+
+> Component omitted: `engine-command-lab`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+Run a command in the lab. The document changes before queued public events publish. Subscribers never receive an intermediate candidate.
+
+The engine is mutable internally so commands remain direct. Its public records and snapshots are immutable contracts. Keep the engine out of Vue deep reactivity; use a stable instance or `shallowRef`.

package/dist/agent/pages/docs/evaluate/why-nuxt-board.md

@@ -0,0 +1,61 @@
+---
+title: "Why Nuxt Board"
+description: "The product problems Nuxt Board solves and the boundaries it keeps explicit."
+url: "https://nuxt-board.lupinum.com/docs/evaluate/why-nuxt-board"
+route: "/docs/evaluate/why-nuxt-board"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Why Nuxt Board
+
+> The product problems Nuxt Board solves and the boundaries it keeps explicit.
+
+Nuxt Board gives your application a board model that exists independently of the component tree. That matters when the canvas is part of a product rather than a disposable visualization.
+
+## What it owns
+
+The headless engine owns spatial state and behavior: nodes, hierarchy, camera, selection, commands, validation, events, and JSON Canvas persistence. `@lupinum/vue-board` owns DOM interaction and rendering. Optional packages own connections and history.
+
+This separation gives application code one mutation path. A command can be guarded, validated, recorded in history, and observed without coordinating several Vue stores.
+
+## What you keep
+
+Your product owns business rules, backend execution, and domain data. Custom Vue renderers control how records look. Nuxt Board does not turn a planning card into a task service or a workflow node into an execution engine.
+
+## Why the limits help
+
+Nuxt Board supports the JSON Canvas node types: `text`, `file`, `link`, and `group`. Custom renderers change presentation without introducing another node schema. First-party plugins add bounded capabilities instead of an unrestricted extension system.
+
+The cost is less speculative flexibility. The benefit is one document model, predictable persistence, and fewer invalid combinations.
+
+Choose Nuxt Board when those boundaries match the system you want to maintain.
+
+## Strong fit
+
+- Users arrange, resize, group, select, or connect structured records.
+- Board state must exist outside the Vue component tree.
+- Mutations need guards, atomic batches, events, validation, or undo boundaries.
+- Custom Vue components should render a stable document schema.
+- JSON Canvas is a useful persistence or interchange format.
+- Connections, history, and minimaps should remain optional.
+
+## Look elsewhere when
+
+- You only need a static graph renderer.
+- Freehand drawing and vector illustration are the primary interaction.
+- You want a complete collaborative whiteboard product rather than a library.
+- Your graph is already modeled around another library's node and edge model.
+- You need backend workflow execution; Nuxt Board only owns the editor surface.
+
+Graph-first components such as Vue Flow are a better fit when handles and edges
+define the product. Drawing libraries such as Konva or Fabric are a better fit
+when shapes and low-level scene manipulation are the core abstraction. Complete
+whiteboard SDKs fit products that value a prescribed toolset over a narrow
+Vue-specific engine, while static renderers such as Mermaid fit non-interactive
+diagrams.
+
+The deciding question is where canonical state should live. Choose Nuxt Board
+when you want a headless board document changed through explicit commands.

package/dist/agent/pages/docs/project/contributing.md

@@ -0,0 +1,101 @@
+---
+title: "Contributing"
+description: "Set up the repo, run the docs, and make changes that are ready to review."
+url: "https://nuxt-board.lupinum.com/docs/project/contributing"
+route: "/docs/project/contributing"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Contributing
+
+> Set up the repo, run the docs, and make changes that are ready to review.
+
+Contributions are welcome when they keep the library easier to use, test, and maintain.
+
+## Set up the repository
+
+The canonical contribution policy is [CONTRIBUTING.md](https://github.com/lupinum-dev/nuxt-board/blob/main/CONTRIBUTING.md). From the repository root:
+
+```bash
+corepack enable
+pnpm install
+```
+
+Start the playground or docs app:
+
+```bash
+pnpm dev:playground
+pnpm dev:docs
+```
+
+The playground is the fastest place to verify interaction changes. The docs app uses the workspace packages, so examples exercise the same code consumers install.
+
+## Run the checks
+
+Run the narrowest relevant check while you work, then the repository gate before handoff:
+
+```bash
+pnpm verify
+```
+
+Use `pnpm test:e2e` for browser interaction or screenshot changes. Maintainers use `pnpm release:verify` only on a release candidate.
+
+## Where docs live
+
+Docs content lives in `docs/content`.
+
+| Folder | Purpose |
+| --- | --- |
+| `1.evaluate` | Product fit and architecture orientation. |
+| `2.start-building` | Installation and first working board. |
+| `3.understand-the-system` | State, commands, coordinates, and data. |
+| `4.build-features` | Task-focused feature guides. |
+| `5.solutions` | Complete application examples. |
+| `6.reference` | Maintained public API contracts. |
+| `7.project` | Contribution, support, and security. |
+
+## Documentation standards
+
+Write each page for one reader and one job. A quickstart should not become a reference page, and a reference page should not become a tutorial.
+
+Before shipping docs, check:
+
+- The first paragraph says what the page helps the reader do or understand.
+- Examples include imports and setup when needed.
+- Claims about defaults, fields, commands, and behavior match source or tests.
+- Links describe the destination.
+- The page ends with a useful next step.
+
+## When code needs docs
+
+Update docs when a change affects:
+
+- exported package APIs
+- node, edge, selection, camera, or import/export behavior
+- Nuxt module options or auto-imports
+- default UI behavior
+- migration steps for existing users
+- setup commands or package names
+
+For publishable package changes, add a changeset:
+
+```bash
+pnpm changeset
+```
+
+## Pull request shape
+
+A reviewable change has a narrow scope, tests for changed behavior, and docs for user-visible changes.
+
+Include screenshots or short recordings for visual interaction changes. For API docs, include the source change and matching reference update together.
+
+## Documentation voice
+
+Write in a calm, direct, technically honest voice. Lead with the answer. Name the package that owns a capability. Explain non-obvious constraints through decision, reason, benefit, cost, and consequence.
+
+Use product-direct writing for evaluation, principle-led writing for concepts, task-first writing for guides, contract-style writing for reference, and neutral analytical writing for comparisons.
+
+Do not hide required facts inside a demo, tab, or accordion. Every interactive lab needs a textual objective, expected result, invariant, and relevant consumer code.