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

package/dist/internal.d.ts

@@ -1,9 +1,12 @@
 export type { InternalBoardCommit, InternalHistoryRoot } from './state/types.js';
+export { readonlyMapView } from './helpers/clone.js';
+export { collectJsonObjectExtras, freezeJsonObject, freezeJsonValue, } from './helpers/json.js';
+export { BOARD_EDITOR_ATTRIBUTE, BOARD_INTERACTIVE_ATTRIBUTE, BOARD_INTERACTIVE_SELECTOR, BOARD_NODE_ID_ATTRIBUTE, BOARD_RESIZE_ATTRIBUTE, BOARD_ROOT_ATTRIBUTE, BOARD_ROOT_SELECTOR, isBoardInteractiveEventTarget, isEventOwnedByBoardRoot, } from './dom-attributes.js';
 export type { InternalBoardPlugin, InternalBoardPluginDefinition, InternalInteractionAdapter, InternalPluginContext, InternalPluginPersistence, } from './types.js';
 /** Resolve the unsupported first-party pointer/session surface used by framework adapters. */
 export declare function getBoardInteractionAdapter(engine: import('./types.js').BoardEngine): InternalInteractionAdapter;
 import type { BoardEventMap, BoardPlugin, BoardPluginApis, InternalBoardPlugin, InternalBoardPluginDefinition, InternalInteractionAdapter } from './types.js';
 export declare function defineInternalBoardPlugin<TPluginApis extends BoardPluginApis = BoardPluginApis, TEvents extends {
     [K in keyof TEvents]: (...args: never[]) => unknown;
-} = BoardEventMap>(plugin: InternalBoardPluginDefinition<TPluginApis, TEvents>): InternalBoardPlugin<TPluginApis, TEvents>;
+} = BoardEventMap, TState = unknown>(plugin: InternalBoardPluginDefinition<TPluginApis, TEvents, TState>): InternalBoardPlugin<TPluginApis, TEvents, TState>;
 export declare function assertInternalBoardPlugin(plugin: BoardPlugin): asserts plugin is InternalBoardPlugin;

package/dist/internal.js

@@ -1,10 +1,36 @@
 import {
+  BOARD_EDITOR_ATTRIBUTE,
+  BOARD_INTERACTIVE_ATTRIBUTE,
+  BOARD_INTERACTIVE_SELECTOR,
+  BOARD_NODE_ID_ATTRIBUTE,
+  BOARD_RESIZE_ATTRIBUTE,
+  BOARD_ROOT_ATTRIBUTE,
+  BOARD_ROOT_SELECTOR,
   assertInternalBoardPlugin,
+  collectJsonObjectExtras,
   defineInternalBoardPlugin,
-  getBoardInteractionAdapter
-} from "./chunk-5JZXHZWR.js";
+  freezeJsonObject,
+  freezeJsonValue,
+  getBoardInteractionAdapter,
+  isBoardInteractiveEventTarget,
+  isEventOwnedByBoardRoot,
+  readonlyMapView
+} from "./chunk-A7SXOVDB.js";
 export {
+  BOARD_EDITOR_ATTRIBUTE,
+  BOARD_INTERACTIVE_ATTRIBUTE,
+  BOARD_INTERACTIVE_SELECTOR,
+  BOARD_NODE_ID_ATTRIBUTE,
+  BOARD_RESIZE_ATTRIBUTE,
+  BOARD_ROOT_ATTRIBUTE,
+  BOARD_ROOT_SELECTOR,
   assertInternalBoardPlugin,
+  collectJsonObjectExtras,
   defineInternalBoardPlugin,
-  getBoardInteractionAdapter
+  freezeJsonObject,
+  freezeJsonValue,
+  getBoardInteractionAdapter,
+  isBoardInteractiveEventTarget,
+  isEventOwnedByBoardRoot,
+  readonlyMapView
 };

package/dist/state/types.d.ts

@@ -1,4 +1,8 @@
-import type { BoardEventMap, BoardNode, Camera, CommandMetadata, GridSettings, InteractionState, NodeConstraints, NodeId, Point, SnapGuide, ZoomSettings } from '../types.js';
+import type { BoardEventMap, BoardNode, Camera, CommandMetadata, GridSettings, InteractionState, JsonObject, NodeConstraints, NodeId, Point, SnapGuide, ZoomSettings } from '../types.js';
+export interface JsonCanvasPassthrough {
+    readonly document: JsonObject;
+    readonly nodes: ReadonlyMap<NodeId, JsonObject>;
+}
 export declare const DEFAULT_CAMERA: Camera;
 export declare const DEFAULT_ZOOM: ZoomSettings;
 export declare const DEFAULT_GRID: GridSettings;
@@ -11,6 +15,7 @@ export interface MutableBoardState {
     interaction: InteractionState;
     snapGuides: SnapGuide[];
     nextZIndex: number;
+    jsonCanvas: JsonCanvasPassthrough;
 }
 export type ListenerMap = Map<keyof BoardEventMap, Set<(...args: unknown[]) => void>>;
 /** Structurally shared persistent state captured by first-party history. */
@@ -19,6 +24,7 @@ export interface InternalHistoryRoot {
     readonly grid: GridSettings;
     readonly selection: ReadonlySet<NodeId>;
     readonly nextZIndex: number;
+    readonly jsonCanvas: JsonCanvasPassthrough;
     readonly pluginSlices: ReadonlyMap<string, unknown>;
 }
 /** A successfully published outer command. */

package/dist/types.d.ts

@@ -74,6 +74,14 @@ export type JsonCanvasBackgroundStyle = 'cover' | 'ratio' | 'repeat';
 export type BoardColorPreset = '1' | '2' | '3' | '4' | '5' | '6';
 /** JSON Canvas color value: a preset id or a concrete hex color. */
 export type CanvasColor = BoardColorPreset | `#${string}`;
+/** A value that can be persisted without changing its JSON representation. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** A JSON object used for extension-owned persisted data. */
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
 interface JsonCanvasNodeBase<TType extends JsonCanvasNodeType> {
     readonly id: string;
     readonly type: TType;
@@ -112,30 +120,30 @@ export interface JsonCanvasEdge {
     readonly color?: CanvasColor;
     readonly label?: string;
 }
-export interface VueBoardNodeMetadata {
+export interface BoardNodeMetadata {
     readonly zIndex?: number;
     readonly locked?: boolean;
     readonly visible?: boolean;
     readonly parentId?: string;
 }
-export interface VueBoardEdgeMetadata {
+export interface BoardEdgeMetadata {
     readonly zIndex?: number;
-    readonly data?: Record<string, unknown>;
+    readonly data?: JsonObject;
 }
 /** Nuxt Board metadata for engine state that JSON Canvas 1.0 does not define. */
-export interface VueBoardDocumentMetadata {
+export interface BoardDocumentMetadata {
     readonly camera?: Camera;
     readonly grid?: GridSettings;
     readonly selection?: readonly string[];
     readonly nextZIndex?: number;
-    readonly nodes?: Readonly<Record<string, VueBoardNodeMetadata>>;
-    readonly edges?: Readonly<Record<string, VueBoardEdgeMetadata>>;
+    readonly nodes?: Readonly<Record<string, BoardNodeMetadata>>;
+    readonly edges?: Readonly<Record<string, BoardEdgeMetadata>>;
 }
 /** Canonical persisted board document. */
 export interface JsonCanvasDocument {
     readonly nodes: readonly JsonCanvasNode[];
     readonly edges?: readonly JsonCanvasEdge[];
-    readonly 'x-vue-board'?: VueBoardDocumentMetadata;
+    readonly 'x-lupinum-board'?: BoardDocumentMetadata;
 }
 interface BoardNodeBase {
     readonly id: NodeId;
@@ -260,6 +268,10 @@ export interface DuplicateNodesResult {
     readonly nodes: readonly BoardNode[];
     readonly idMap: ReadonlyMap<NodeId, NodeId>;
 }
+/** Clipboard hook used to translate host payloads into board nodes. */
+export interface BoardClipboardHooks {
+    deserialize(payload: unknown): NodeInput[] | null;
+}
 /** Options controlling how a validated document enters the current board. */
 export interface DocumentLoadOptions {
     mode?: 'replace' | 'merge';
@@ -373,6 +385,7 @@ export interface BoardEngineOptions<TPlugins extends readonly BoardPlugin[] = re
     nodes?: Partial<NodeConstraints>;
     boxSelect?: Partial<BoxSelectSettings>;
     plugins?: TPlugins;
+    clipboard?: BoardClipboardHooks;
     diagnostics?: boolean | {
         traceLimit?: number;
     };
@@ -491,6 +504,8 @@ export interface BoardEngine<TPluginApis extends BoardPluginApis = BoardPluginAp
     duplicateNodes(ids: NodeId[], offset?: Point): DuplicateNodesResult;
     copySelected(): BoardNode[];
     pasteClipboard(offset?: Point): BoardNode[];
+    /** Paste a host payload, or return `null` when the hook does not recognize it. */
+    pasteData(payload: unknown, offset?: Point): BoardNode[] | null;
     select(ids: NodeId | NodeId[], mode?: SelectionMode): void;
     selectAll(): void;
     clearSelection(): void;
@@ -523,7 +538,7 @@ export interface InternalInteractionAdapter {
  */
 export interface InternalPluginContext<TPluginApis extends BoardPluginApis = BoardPluginApis, TEvents extends {
     [K in keyof TEvents]: (...args: never[]) => unknown;
-} = BoardEventMap> extends Omit<BoardEngine, 'plugins'> {
+} = BoardEventMap, TState = unknown> extends Omit<BoardEngine, 'plugins'> {
     readonly plugins: TPluginApis;
     /** Assert that the owning engine has not been destroyed. */
     assertActive(): void;
@@ -539,38 +554,40 @@ export interface InternalPluginContext<TPluginApis extends BoardPluginApis = Boa
      */
     runCommand<T>(name: string, args: unknown[], fn: () => T, metadata: CommandMetadata): T;
     /** Read the immutable persistent slice owned by the current plugin. */
-    getPluginState<S>(): S;
+    getPluginState(): TState;
     /** Replace the current plugin's persistent slice inside the active command. */
-    updatePluginState<S>(update: (current: S) => S): S;
+    updatePluginState(update: (current: TState) => TState): TState;
+    /** Project persistent plugin state through the canonical subscribable lifecycle. */
+    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;
 }
 /** Persistent state owned by an internal plugin. */
-interface InternalPluginSlice {
-    initial: unknown;
+interface InternalPluginSlice<TState> {
+    initial: TState;
 }
 /** Optional internal hook for persisted JSON Canvas document data. */
 export interface InternalPluginPersistence<TPluginApis extends BoardPluginApis = BoardPluginApis, TEvents extends {
     [K in keyof TEvents]: (...args: never[]) => unknown;
-} = BoardEventMap> {
-    exportDocument?(engine: InternalPluginContext<TPluginApis, TEvents>): Partial<JsonCanvasDocument> | void;
-    loadDocument?(engine: InternalPluginContext<TPluginApis, TEvents>, document: JsonCanvasDocument, mode: 'replace' | 'merge', idMap: ReadonlyMap<NodeId, NodeId>): void;
+} = BoardEventMap, TState = unknown> {
+    exportDocument?(engine: InternalPluginContext<TPluginApis, TEvents, TState>): Partial<JsonCanvasDocument> | void;
+    loadDocument?(engine: InternalPluginContext<TPluginApis, TEvents, TState>, document: JsonCanvasDocument, mode: 'replace' | 'merge', idMap: ReadonlyMap<NodeId, NodeId>): void;
 }
 /** Internal plugin contract for state, commands, and side effects. */
 export interface InternalBoardPlugin<TPluginApis extends BoardPluginApis = BoardPluginApis, TEvents extends {
     [K in keyof TEvents]: (...args: never[]) => unknown;
-} = BoardEventMap> extends BoardPlugin<TPluginApis, TEvents> {
+} = BoardEventMap, TState = unknown> extends BoardPlugin<TPluginApis, TEvents> {
     name: string;
-    slice?: InternalPluginSlice;
-    persistence?: InternalPluginPersistence<TPluginApis, TEvents>;
-    nodeDeleted?(engine: InternalPluginContext<TPluginApis, TEvents>, nodeId: NodeId): void;
-    install(engine: InternalPluginContext<TPluginApis, TEvents>, options?: Record<string, unknown>): void | PluginCleanup;
+    slice?: InternalPluginSlice<TState>;
+    persistence?: InternalPluginPersistence<TPluginApis, TEvents, TState>;
+    nodeDeleted?(engine: InternalPluginContext<TPluginApis, TEvents, TState>, nodeId: NodeId): void;
+    install(engine: InternalPluginContext<TPluginApis, TEvents, TState>, options?: Record<string, unknown>): void | PluginCleanup;
 }
 export type InternalBoardPluginDefinition<TPluginApis extends BoardPluginApis = BoardPluginApis, TEvents extends {
     [K in keyof TEvents]: (...args: never[]) => unknown;
-} = BoardEventMap> = Omit<InternalBoardPlugin<TPluginApis, TEvents>, keyof BoardPlugin> & {
+} = BoardEventMap, TState = unknown> = Omit<InternalBoardPlugin<TPluginApis, TEvents, TState>, keyof BoardPlugin> & {
     readonly name: string;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/board-core",
-  "version": "0.1.0",
+  "version": "1.0.0-beta.2",
   "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)",

package/dist/chunk-5JZXHZWR.js

@@ -1,68 +0,0 @@
-// src/errors.ts
-var BoardError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var BoardInputError = class extends BoardError {
-};
-var BoardNotFoundError = class extends BoardError {
-};
-var BoardConflictError = class extends BoardError {
-};
-var BoardDestroyedError = class extends BoardError {
-  constructor() {
-    super("Board engine has been destroyed.");
-  }
-};
-
-// src/engine/interaction-adapter.ts
-var adapterKey = /* @__PURE__ */ Symbol.for("@lupinum/board-core/interaction-adapter");
-function registerBoardInteractionAdapter(engine, adapter) {
-  Object.defineProperty(engine, adapterKey, {
-    configurable: true,
-    value: adapter,
-    enumerable: false
-  });
-}
-function getRegisteredBoardInteractionAdapter(engine) {
-  const adapter = Reflect.get(engine, adapterKey);
-  if (!adapter) {
-    throw new BoardInputError(
-      "The supplied engine was not created by createBoardEngine()."
-    );
-  }
-  return adapter;
-}
-
-// src/internal.ts
-function getBoardInteractionAdapter(engine) {
-  return getRegisteredBoardInteractionAdapter(engine);
-}
-function defineInternalBoardPlugin(plugin) {
-  return plugin;
-}
-function assertInternalBoardPlugin(plugin) {
-  const candidate = plugin;
-  if (typeof candidate.name !== "string" || candidate.name.length === 0) {
-    throw new Error("Invalid board plugin: expected a named plugin token.");
-  }
-  if (typeof candidate.install !== "function") {
-    throw new Error(
-      `Invalid board plugin "${candidate.name}": expected a token created by a first-party plugin factory.`
-    );
-  }
-}
-
-export {
-  BoardError,
-  BoardInputError,
-  BoardNotFoundError,
-  BoardConflictError,
-  BoardDestroyedError,
-  registerBoardInteractionAdapter,
-  getBoardInteractionAdapter,
-  defineInternalBoardPlugin,
-  assertInternalBoardPlugin
-};