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

package/dist/agent/pages/docs/understand-the-system/nodes-and-hierarchy.md

@@ -0,0 +1,24 @@
+---
+title: "Nodes and hierarchy"
+description: "The canonical node records, geometry, parent relationships, and z-order."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/nodes-and-hierarchy"
+route: "/docs/understand-the-system/nodes-and-hierarchy"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Nodes and hierarchy
+
+> The canonical node records, geometry, parent relationships, and z-order.
+
+Nodes are immutable JSON Canvas records. Vue components render them later.
+
+Supported types are `text`, `file`, `link`, and `group`. Shared fields include ID, position, size, z-index, visibility, lock state, parent ID, and color. Type-specific content lives directly on the record.
+
+`createNode()` accepts partial input, fills defaults, and selects the result unless `select: false` is set. Use complete deterministic records in `initialNodes` for SSR and fixtures.
+
+Hierarchy uses `parentId`. Core owns reparenting, cycle prevention, group capture, and z-order policy. Deleting or changing a parent cannot leave an observable invalid hierarchy because validation occurs before commit.
+
+Use `asNodeId()` for stable explicit IDs. Do not store the same domain field in both application state and node content without a defined canonical owner and rebuild path.

package/dist/agent/pages/docs/understand-the-system/packages-and-plugins.md

@@ -0,0 +1,29 @@
+---
+title: "Packages and plugins"
+description: "One owner for each capability and the reason packages stay focused."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/packages-and-plugins"
+route: "/docs/understand-the-system/packages-and-plugins"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Packages and plugins
+
+> One owner for each capability and the reason packages stay focused.
+
+| Package | Owns |
+| --- | --- |
+| `@lupinum/board-core` | Nodes, camera, grid, selection, hierarchy, commands, validation, JSON Canvas, events |
+| `@lupinum/vue-board` | DOM input, reactive adaptation, rendering, default chrome, minimap subpath |
+| `@lupinum/board-connections` | Edge state, commands, persistence, routing, hit testing, optional Vue layer |
+| `@lupinum/board-history` | Runtime undo and redo roots |
+| `@lupinum/nuxt-board` | Auto-import and style registration |
+
+Plugins install only during construction and expose one named API. The plugin tuple controls engine typing; importing a package alone does not augment every engine.
+
+First-party plugins can participate in the same candidate transaction as core. For example, deleting a node and its incident edges commits atomically. Applications should not build generic plugins against the unsupported internal ABI.
+
+The first-party packages use one lockstep release version. That keeps their
+internal ABI exact while applications consume only the supported public APIs.

package/dist/agent/pages/docs/understand-the-system/persistence-and-json-canvas.md

@@ -0,0 +1,25 @@
+---
+title: "Persistence and JSON Canvas"
+description: "What the engine exports, validates, normalizes, and deliberately excludes."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/persistence-and-json-canvas"
+route: "/docs/understand-the-system/persistence-and-json-canvas"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Persistence and JSON Canvas
+
+> What the engine exports, validates, normalizes, and deliberately excludes.
+
+`exportDocument()` returns committed JSON Canvas data. It excludes transient interaction, DOM measurements, subscribers, and history stacks.
+
+`loadDocument(unknown, options)` validates and normalizes the entire input before publication. A rejected candidate leaves the current board unchanged.
+
+> Component omitted: `persistence-lab`.
+> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+
+Load the invalid example in the lab. The error is reported without destroying the current document. A valid import is normalized and then committed once.
+
+Core owns JSON Canvas nodes. The connections plugin owns its edge extension. If the application has richer domain state, choose one canonical application model and derive board records rather than persisting competing copies.

package/dist/agent/pages/docs/understand-the-system/rendering-and-interaction.md

@@ -0,0 +1,22 @@
+---
+title: "Rendering and interaction"
+description: "What BoardRoot owns and where custom rendering begins."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/rendering-and-interaction"
+route: "/docs/understand-the-system/rendering-and-interaction"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Rendering and interaction
+
+> What BoardRoot owns and where custom rendering begins.
+
+`BoardRoot` is a convenience facade over the engine, not a second engine. It maps focused subscribables to shallow Vue refs and renders the viewport, grid, nodes, selection chrome, snap guides, and interaction affordances.
+
+The framework adapter translates pointer and keyboard input. Low-level interaction methods live in the unsupported first-party ABI rather than the normal application API.
+
+Custom renderers draw node content. Dragging, resizing, positioning, selection, and LOD remain board-shell responsibilities. Slots provide a local alternative to a renderer registry.
+
+Keep controls that edit text inside the renderer, then call engine commands for persistent changes. Stop pointer propagation for interactive form elements so editing does not begin a board drag.

package/dist/agent/pages/docs/understand-the-system/the-engine.md

@@ -0,0 +1,28 @@
+---
+title: "The engine"
+description: "State ownership, lifecycle, reads, commands, and subscriptions."
+url: "https://nuxt-board.lupinum.com/docs/understand-the-system/the-engine"
+route: "/docs/understand-the-system/the-engine"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# The engine
+
+> State ownership, lifecycle, reads, commands, and subscriptions.
+
+The engine is the board source of truth. It owns document state, runtime session state, commands, validation, events, and installed plugin slices.
+
+Create it once with `createBoardEngine()`. Read immutable runtime state with `getState()` and focused methods such as `getSelection()`. Observe reactive channels such as `$nodes`, or subscribe to semantic events.
+
+Change state through commands. Directly mutating a returned node record does not update the engine and bypasses its invariants.
+
+## Lifecycle
+
+Plugins install during construction. Duplicate plugin names fail before installation. `destroy()` is idempotent but terminal: it clears listeners, guards, plugin cleanup, and reactive resources. Later commands throw `BoardDestroyedError`.
+
+Listener, subscriber, and finalized commit-effect failures occur after commit. They are isolated and reported through `onUnhandledError`; they cannot roll committed state back. Inspect `context.source` to distinguish `event-listener`, `subscriber`, and `commit-effect` failures.
+
+Use the root package API in applications. The exported `/internal` subpath is an unsupported ABI for first-party packages.

package/dist/agent/pages/docs.md

@@ -0,0 +1,18 @@
+---
+title: "Nuxt Board documentation"
+description: "Learn how to build domain-specific spatial tools with the command-driven Nuxt Board engine, renderer, and focused feature packages."
+url: "https://nuxt-board.lupinum.com/docs"
+route: "/docs"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Nuxt Board documentation
+
+> Learn how to build domain-specific spatial tools with the command-driven Nuxt Board engine, renderer, and focused feature packages.
+
+Start with [your first board](/raw/docs/start-building/your-first-board.md), or read [how Nuxt Board works](/raw/docs/evaluate/how-nuxt-board-works.md) before choosing the architecture.
+
+The sidebar has two major sections: learn the system first, then build production features with its explicit commands and document model.

package/dist/engine/transaction.d.ts

@@ -29,7 +29,7 @@ interface TransactionExecutorDeps<TRoot> {
     beginPersistentTransaction: () => TRoot;
     rollbackPersistentTransaction: (checkpoint: TRoot) => void;
     beforeExecute: (name: string, metadata: CommandMetadata, historyBefore: InternalHistoryRoot | null) => InternalHistoryRoot | null;
-    prepareCommit: (label: string, metadata: CommandMetadata, before: InternalHistoryRoot) => PreparedCommit | null;
+    prepareCommit: (label: string, metadata: CommandMetadata, before: InternalHistoryRoot, onCommit?: () => void) => PreparedCommit | null;
     reportCommitError: (label: string, error: unknown) => void;
     validate: (context: string) => void;
     isCancellation: (error: unknown) => boolean;
@@ -45,7 +45,7 @@ export interface PreparedCommit {
 }
 /** Own guarded command staging, validation, publication, and rollback order. */
 export declare function createTransactionExecutor<TRoot>(deps: TransactionExecutorDeps<TRoot>): {
-    runCommand: <T>(name: string, args: unknown[], fn: () => T, metadata?: RuntimeCommandMetadata, commitOverride?: CommitOverride) => T;
+    runCommand: <T>(name: string, args: unknown[], fn: () => T, metadata?: RuntimeCommandMetadata, commitOverride?: CommitOverride, onCommit?: () => void) => T;
     runAsyncCommand: <T>(name: string, args: unknown[], fn: () => Promise<T>, metadata?: RuntimeCommandMetadata) => Promise<T>;
 };
 /**

package/dist/index.js

@@ -1432,7 +1432,7 @@ function createTransactionExecutor(deps) {
     }
     if (emitBefore) deps.emitBefore(name, args, metadata);
   }
-  function runCommand(name, args, fn, metadata = defaultMetadata, commitOverride) {
+  function runCommand(name, args, fn, metadata = defaultMetadata, commitOverride, onCommit) {
     const inBatch = deps.isBatching();
     prepare(name, args, metadata, false);
     const started = performance.now();
@@ -1452,7 +1452,8 @@ function createTransactionExecutor(deps) {
       const preparedCommit = commitBefore ? deps.prepareCommit(
         commitOverride?.label ?? name,
         commitOverride?.metadata ?? metadata,
-        commitBefore
+        commitBefore,
+        onCommit
       ) : null;
       const commitErrors = preparedCommit?.finalize() ?? [];
       if (!inBatch) {
@@ -2698,9 +2699,10 @@ function createBoardEngine(options = {}) {
     }
     return true;
   }
-  function prepareCommit(label, metadata, before) {
+  function prepareCommit(label, metadata, before, onCommit) {
     const after = captureHistoryRoot();
-    if (sameHistoryRoot(before, after)) return null;
+    const unchanged = sameHistoryRoot(before, after);
+    if (unchanged && !onCommit) return null;
     const commit = Object.freeze({
       label,
       timestamp: Date.now(),
@@ -2708,7 +2710,8 @@ function createBoardEngine(options = {}) {
       before,
       after
     });
-    const effects = Array.from(commitProjectors, (project) => project(commit));
+    const effects = unchanged ? [] : Array.from(commitProjectors, (project) => project(commit));
+    if (onCommit) effects.unshift(onCommit);
     return {
       label,
       finalize() {
@@ -3292,7 +3295,13 @@ function createBoardEngine(options = {}) {
       projectedSubscribables.add(projection);
       return projection;
     },
-    restoreHistoryRoot(root) {
+    restoreHistoryRoot(root, onCommit) {
+      assertCommandReady();
+      if (batches.isBatching()) {
+        throw new BoardConflictError(
+          "Undo and redo are unavailable inside a batch."
+        );
+      }
       runCommand(
         "history:restore",
         [],
@@ -3320,7 +3329,9 @@ function createBoardEngine(options = {}) {
           notifyNodesChanged();
           notifySelectionChanged();
         },
-        IGNORE_COMMAND
+        IGNORE_COMMAND,
+        void 0,
+        onCommit
       );
     },
     screenToWorld(point) {

package/dist/types.d.ts

@@ -561,8 +561,8 @@ export interface InternalPluginContext<TPluginApis extends BoardPluginApis = Boa
     createCommitSubscribable<T>(select: () => T, channel: string): Subscribable<T>;
     /** Prepare final bookkeeping/event publication for a validated outer commit. The effect cannot mutate or destroy the board. */
     projectCommit(projector: (commit: import('./state/types.js').InternalBoardCommit) => () => void): Unsubscribe;
-    /** Atomically restore a persistent root without recording another history frame. */
-    restoreHistoryRoot(root: import('./state/types.js').InternalHistoryRoot): void;
+    /** Restore an outer history operation; finalize bookkeeping before public notifications, including equal roots. Reject replay inside a batch. */
+    restoreHistoryRoot(root: import('./state/types.js').InternalHistoryRoot, onCommit?: () => void): void;
 }
 /** Persistent state owned by an internal plugin. */
 interface InternalPluginSlice<TState> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/board-core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "Headless node-based board engine for spatial editors, diagramming tools, and whiteboard-style interfaces.",
   "license": "MIT",
   "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
@@ -22,7 +22,8 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
-    }
+    },
+    "./agent-docs": "./dist/agent/AGENTS.md"
   },
   "repository": {
     "type": "git",