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

package/dist/agent/pages/docs/reference/glossary.md

@@ -0,0 +1,58 @@
+---
+title: "Glossary"
+description: "Canonical definitions for Nuxt Board architecture and API terms."
+url: "https://nuxt-board.lupinum.com/docs/reference/glossary"
+route: "/docs/reference/glossary"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Glossary
+
+> Canonical definitions for Nuxt Board architecture and API terms.
+
+## Board document
+
+The committed, persistable JSON Canvas data owned by the engine and installed persistence plugins.
+
+## Board engine
+
+The framework-agnostic source of truth created by `createBoardEngine()`.
+
+## Command
+
+A named operation that changes persistent board state through the transaction boundary.
+
+## Effective geometry
+
+The node geometry rendered at a given moment: committed geometry plus any active session override.
+
+## History boundary
+
+One successful persistent commit recorded as a single undoable transition.
+
+## Plugin slice
+
+Immutable state owned by one installed first-party plugin and committed with core state.
+
+## Renderer
+
+A Vue component that presents an existing node record. It does not define another persisted node type.
+
+## Session state
+
+Runtime-only state such as viewport measurements, active interaction, snap guides, clipboard data, and transient geometry.
+
+## Snapshot
+
+An immutable public view of runtime state. It is not the persistence format.
+
+## Subscribable
+
+A focused reactive channel that publishes a current value and its previous outer-transaction value.
+
+## Transaction
+
+The staged unit in which commands update a candidate, validate it, commit it, and then publish subscriptions and events.

package/dist/agent/pages/docs/reference/history.md

@@ -0,0 +1,193 @@
+---
+title: "@lupinum/board-history"
+description: "Deterministic structural undo/redo with connection-aware state restoration."
+url: "https://nuxt-board.lupinum.com/docs/reference/history"
+route: "/docs/reference/history"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/board-history
+
+> Deterministic structural undo/redo with connection-aware state restoration.
+
+## Install
+
+<code-group>
+```bash [pnpm]
+pnpm add @lupinum/board-history @lupinum/board-core
+```
+
+```bash [npm]
+npm install @lupinum/board-history @lupinum/board-core
+```
+</code-group>
+
+## historyPlugin
+
+Creates the history plugin. Install it during engine creation via `createBoardEngine({ plugins })`.
+
+```ts
+const plugin = historyPlugin({ maxSteps: 100 })
+```
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxSteps` | `number` | `200` | Maximum number of undo steps to retain. |
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { historyPlugin } from '@lupinum/board-history'
+
+const engine = createBoardEngine({
+  plugins: [historyPlugin({ maxSteps: 100 })],
+})
+```
+
+### Command capture
+
+History capture is driven by command metadata emitted by the engine and internal features. Camera movement, transient pointer setup/teardown, text-edit begin, imports, and selection-only commands mark themselves as ignored; geometry and content mutations mark themselves as recorded.
+
+---
+
+## Plugin API
+
+After installing the plugin, the history API is available on `engine.plugins.history`.
+
+### undo
+
+Restores the previous state. No-op if there is nothing to undo.
+
+```ts
+undo(): void
+```
+
+```ts
+engine.plugins.history.undo()
+```
+
+### redo
+
+Re-applies the next state. No-op if there is nothing to redo.
+
+```ts
+redo(): void
+```
+
+### canUndo
+
+Returns `true` if there is at least one undo step available.
+
+```ts
+canUndo(): boolean
+```
+
+### canRedo
+
+Returns `true` if there is at least one redo step available.
+
+```ts
+canRedo(): boolean
+```
+
+### clear
+
+Clears the entire history stack (both undo and redo).
+
+```ts
+clear(): void
+```
+
+### getState
+
+Returns the current history state.
+
+```ts
+getState(): HistoryState
+```
+
+```ts
+const state = engine.plugins.history.getState()
+console.log(`${state.undoDepth} undo steps, ${state.redoDepth} redo steps`)
+```
+
+---
+
+## History boundaries
+
+History has no timers or implicit coalescing. A completed gesture, text edit, or outer `batch()` call creates one step. Separate programmatic commands create separate steps.
+
+## BoardHistoryShortcuts
+
+Import `BoardHistoryShortcuts` from `@lupinum/board-history/vue` and render it
+inside `BoardRoot` with
+`<BoardHistoryShortcuts :history="engine.plugins.history" />`. The required
+prop identifies the history API, while the enclosing root identifies which DOM
+events it may handle. Editable controls and events already handled by another
+component keep their native behavior.
+
+---
+
+## Connection-aware restoration
+
+When the connections plugin is also installed, the history plugin automatically captures and restores edge state. Undoing a node deletion also restores any edges that were connected to that node.
+
+---
+
+## Types
+
+### HistoryState
+
+```ts
+interface HistoryState {
+  undoDepth: number // number of undo steps available
+  redoDepth: number // number of redo steps available
+  current: string | null // label of the current history entry
+}
+```
+
+### HistoryEntry
+
+```ts
+interface HistoryEntry {
+  label: string // command name that created this entry
+  timestamp: number // Date.now() when the entry was created
+}
+```
+
+### HistoryPluginOptions
+
+```ts
+interface HistoryPluginOptions {
+  maxSteps?: number // default: 200
+}
+```
+
+---
+
+## Events
+
+The history plugin adds these events to `BoardEventMap`:
+
+| Event | Handler | Description |
+| --- | --- | --- |
+| `history:push` | `(entry: HistoryEntry) => void` | A new entry was added to the undo stack. |
+| `history:undo` | `(entry: HistoryEntry \| null) => void` | An undo operation was performed. |
+| `history:redo` | `(entry: HistoryEntry \| null) => void` | A redo operation was performed. |
+| `history:clear` | `() => void` | The history stack was cleared. |
+
+```ts
+engine.on('history:push', (entry) => {
+  console.log('New undo step:', entry.label)
+})
+
+engine.on('history:undo', () => {
+  console.log('Undo depth:', engine.plugins.history.getState().undoDepth)
+})
+```
+
+---

package/dist/agent/pages/docs/reference/minimap.md

@@ -0,0 +1,157 @@
+---
+title: "@lupinum/vue-board/minimap"
+description: "Minimap composable and component for board navigation."
+url: "https://nuxt-board.lupinum.com/docs/reference/minimap"
+route: "/docs/reference/minimap"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/vue-board/minimap
+
+> Minimap composable and component for board navigation.
+
+## Install
+
+<code-group>
+```bash [pnpm]
+pnpm add @lupinum/vue-board @lupinum/board-core
+```
+
+```bash [npm]
+npm install @lupinum/vue-board @lupinum/board-core
+```
+</code-group>
+
+## useBoardMinimap
+
+A composable that computes minimap projections from the engine state. Returns reactive bounds, viewport rectangle, projected nodes, and a pan function.
+
+```ts
+function useBoardMinimap(
+  engine: BoardEngine,
+  options?: MinimapOptions,
+): {
+  bounds: ComputedRef<Bounds>
+  viewportRect: ComputedRef<{
+    x: number
+    y: number
+    width: number
+    height: number
+  }>
+  minimapNodes: ComputedRef<
+    Array<{
+      node: BoardNode
+      x: number
+      y: number
+      width: number
+      height: number
+    }>
+  >
+  panToMinimapPoint: (point: Point) => Promise<void>
+}
+```
+
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `MaybeRefOrGetter<number>` | `200` | Minimap width in pixels. |
+| `height` | `MaybeRefOrGetter<number>` | `140` | Minimap height in pixels. |
+| `padding` | `MaybeRefOrGetter<number>` | `24` | Padding around the world-space content. |
+
+### Return type
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `bounds` | `ComputedRef<Bounds>` | World-space bounds of all nodes (with padding). |
+| `viewportRect` | `ComputedRef<{x, y, width, height}>` | Viewport rectangle projected onto the minimap. |
+| `minimapNodes` | `ComputedRef<Array<...>>` | All nodes projected onto minimap coordinates. |
+| `panToMinimapPoint` | `(point: Point) => Promise<void>` | Pans the main camera so the clicked minimap point is centered. |
+
+```ts
+import { useBoardMinimap } from '@lupinum/vue-board/minimap'
+
+const minimap = useBoardMinimap(engine, { width: 200, height: 120 })
+
+// Access minimap data
+const nodes = minimap.minimapNodes.value
+const viewport = minimap.viewportRect.value
+
+// Navigate by clicking on the minimap
+await minimap.panToMinimapPoint({ x: 100, y: 60 })
+```
+
+Pass refs or getters when dimensions come from reactive state. `BoardMinimap` does this internally for its `width` and `height` props. Keep the `engine` instance stable for the lifetime of the component or composable.
+
+---
+
+## BoardMinimap
+
+A ready-to-use Vue component that renders a minimap.
+
+The minimap is focusable. Arrow keys pan by 24 screen pixels; hold
+<kbd>
+Shift
+</kbd>
+
+ to pan by 100 pixels.
+
+### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `engine` | `BoardEngine \| null` | `null` | Engine instance. Falls back to `useBoardEngine()` context if omitted. |
+| `width` | `number` | `200` | Minimap width in pixels. |
+| `height` | `number` | `140` | Minimap height in pixels. |
+
+### Slots
+
+#### default
+
+Custom minimap rendering. If not provided, renders rectangles for nodes and a viewport indicator.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `nodes` | `Array<{ node, x, y, width, height }>` | Projected node positions. |
+| `viewport` | `{ x, y, width, height }` | Viewport rectangle on the minimap. |
+
+### Usage
+
+Place the minimap component in the default slot of `BoardRoot` (not inside the viewport, since it should stay in screen-space):
+
+```vue
+<BoardRoot :engine="engine">
+  <template #default>
+    <div class="minimap-container">
+      <BoardMinimap :width="208" :height="148" />
+    </div>
+  </template>
+</BoardRoot>
+```
+
+```css
+.minimap-container {
+  position: absolute;
+  bottom: 16px;
+  right: 16px;
+}
+```
+
+---
+
+## Types
+
+### MinimapOptions
+
+```ts
+interface MinimapOptions {
+  width?: number // default: 200
+  height?: number // default: 140
+  padding?: number // default: 24
+}
+```
+
+---

package/dist/agent/pages/docs/reference/nuxt-board.md

@@ -0,0 +1,148 @@
+---
+title: "@lupinum/nuxt-board"
+description: "Nuxt module with auto-imported board components and composables."
+url: "https://nuxt-board.lupinum.com/docs/reference/nuxt-board"
+route: "/docs/reference/nuxt-board"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/nuxt-board
+
+> Nuxt module with auto-imported board components and composables.
+
+## Install
+
+Requires Nuxt 3.19 or newer, or Nuxt 4.
+
+<code-group>
+```bash [pnpm]
+pnpm add @lupinum/nuxt-board @lupinum/board-core @lupinum/vue-board
+```
+
+```bash [npm]
+npm install @lupinum/nuxt-board @lupinum/board-core @lupinum/vue-board
+```
+</code-group>
+
+Add the module to `nuxt.config.ts`:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-board'],
+  board: {
+    // options
+  },
+})
+```
+
+---
+
+## Module options
+
+Configure via the `board` key in `nuxt.config.ts`:
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `prefix` | `string` | `''` | Optional prefix for all auto-imported exports. Example: `'My'` produces `<MyBoardRoot>`, `useMyBoardCamera()`, and `createMyBoardEngine()`. |
+| `autoImportComponents` | `boolean` | `true` | Make board components available through Nuxt's component auto-imports. |
+| `autoImportComposables` | `boolean` | `true` | Make board composables and `createBoardEngine` available through Nuxt auto-imports. |
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-board'],
+  board: {
+    prefix: 'My',
+    autoImportComponents: true,
+    autoImportComposables: true,
+  },
+})
+```
+
+---
+
+## Auto-imported components
+
+When `autoImportComponents` is `true` (default), these components are auto-imported when used:
+
+| Component | Source |
+| --- | --- |
+| `BoardRoot` | `@lupinum/vue-board` |
+| `BoardViewport` | `@lupinum/vue-board` |
+| `BoardNode` | `@lupinum/vue-board` |
+| `BoardNodeHandle` | `@lupinum/vue-board` |
+| `BoardSelectionToolbar` | `@lupinum/vue-board` |
+| `BoardGrid` | `@lupinum/vue-board` |
+| `BoardBoxSelect` | `@lupinum/vue-board` |
+| `BoardSnapGuides` | `@lupinum/vue-board` |
+| `BoardMinimap` | `@lupinum/vue-board/minimap` |
+
+With a prefix of `'My'`, they become `<MyBoardRoot>`, `<MyBoardViewport>`, etc.
+
+---
+
+## Auto-imported composables
+
+When `autoImportComposables` is `true` (default), these are available without imports:
+
+| Composable | Source |
+| --- | --- |
+| `useBoardEngine` | `@lupinum/vue-board` |
+| `useBoardCamera` | `@lupinum/vue-board` |
+| `useBoardNodes` | `@lupinum/vue-board` |
+| `useBoardSelection` | `@lupinum/vue-board` |
+| `useBoardInteraction` | `@lupinum/vue-board` |
+| `useBoardVisibleBounds` | `@lupinum/vue-board` |
+| `useBoardVisibleNodes` | `@lupinum/vue-board` |
+| `useBoardGridStyle` | `@lupinum/vue-board` |
+| `useBoardNode` | `@lupinum/vue-board` |
+| `useBoardBoxSelectBounds` | `@lupinum/vue-board` |
+| `useBoardMinimap` | `@lupinum/vue-board/minimap` |
+
+With a prefix of `'My'`, these aliases become `useMyBoardEngine()`, `useMyBoardCamera()`, `useMyBoardNodes()`, and so on.
+
+---
+
+## Auto-imported functions
+
+These helpers are registered with the composable auto-imports. If `autoImportComposables` is `false`, import them explicitly.
+
+| Function | Source |
+| --- | --- |
+| `createBoardEngine` | `@lupinum/board-core` |
+
+With a prefix of `'My'`, the helper becomes `createMyBoardEngine()`.
+
+---
+
+## Usage
+
+With the Nuxt module installed, you can use board features without any imports:
+
+```vue [app.vue]
+<script setup lang="ts">
+import { asNodeId } from '@lupinum/board-core'
+
+const engine = createBoardEngine({
+  grid: { size: 20, snap: true },
+})
+
+engine.createNode({
+  id: asNodeId('nuxt-hello'),
+  type: 'text',
+  x: 100,
+  y: 100,
+  width: 240,
+  height: 160,
+  text: 'Node',
+})
+</script>
+
+<template>
+  <BoardRoot :engine="engine" style="height: 100vh" />
+</template>
+```
+
+---

package/dist/agent/pages/docs/reference/package-overview.md

@@ -0,0 +1,58 @@
+---
+title: "Package overview"
+description: "The supported entrypoints and the capability each package owns."
+url: "https://nuxt-board.lupinum.com/docs/reference/package-overview"
+route: "/docs/reference/package-overview"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Package overview
+
+> The supported entrypoints and the capability each package owns.
+
+Install only the packages that own capabilities your product uses.
+
+| Import | Contract |
+| --- | --- |
+| `@lupinum/board-core` | Framework-agnostic engine, types, commands, math, events, and JSON Canvas |
+| `@lupinum/vue-board` | `BoardRoot`, board components, composables, and styles |
+| `@lupinum/vue-board/minimap` | Minimap composable and renderer |
+| `@lupinum/board-connections` | Headless edge plugin, routing, and geometry |
+| `@lupinum/board-connections/vue` | Connection rendering and interaction |
+| `@lupinum/board-history` | Undo and redo plugin |
+| `@lupinum/nuxt-board` | Nuxt registration |
+
+`@lupinum/board-core/internal` is published so separately versioned first-party packages can share an ABI. Applications should not depend on it.
+
+All packages are ESM and target Node 20.19 or newer. Vue-facing packages require Vue 3.5.
+
+Use the pages in this section for exact signatures, return values, events, and failures.
+
+## Installed documentation
+
+Every package exports `./agent-docs`, a readable Markdown file. Resolve it from
+your application directory; for example, resolve
+`@lupinum/board-history/agent-docs` before changing history integration. Read the
+local pages from its index. The snapshot matches the installed package version.
+Resolve it again after an upgrade or rollback. This export is not a JavaScript module.
+
+Use the [installation prompt](/raw/docs/start-building/installation.md#use-a-coding-agent)
+to start an agent task. Existing project instructions remain authoritative.
+
+## Runtime export index
+
+Core exports `BOARD_COLOR_PRESETS`, `BoardError`, `BoardInputError`,
+`BoardNotFoundError`, `BoardConflictError`, `CommandBlockedError`,
+`BoardDestroyedError`, `createBoardEngine`, `asNodeId`, `asEdgeId`, `clamp`,
+`boundsIntersect`, `getBoundsFromPoints`, `getVisibleBounds`,
+`getSelectionNodes`, `getSelectionBounds`, `toggleIds`, `colorForPreset`, and
+`isBoardColorPreset`.
+
+Connections exports `EDGE_COLOR_PRESETS`, `connectionsPlugin`,
+`buildArcRoute`, `buildConnectionRoute`, `getVisibleEdges`,
+`resolveAnchorPoint`, `resolveAutoAnchorSide`, `resolveConnectionEndpoint`,
+`resolveEdgeRenderState`, `resolveFloatingEndpoint`, `edgeEndsForDirectionality`,
+`presetForColor`, `resolvePresetColor`, and its own `colorForPreset` helper.