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

package/dist/chunk-A7SXOVDB.js

@@ -0,0 +1,350 @@
+// src/helpers/clone.ts
+function freezeClone(value) {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      freezeClone(entry);
+    }
+    return Object.freeze(value);
+  }
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) {
+      freezeClone(child);
+    }
+    return Object.freeze(value);
+  }
+  return value;
+}
+function sameArray(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return a.every((value, index) => value === b[index]);
+}
+function readonlyMapView(source) {
+  let view;
+  view = Object.freeze({
+    get size() {
+      return source.size;
+    },
+    get: (key) => source.get(key),
+    has: (key) => source.has(key),
+    entries: () => source.entries(),
+    keys: () => source.keys(),
+    values: () => source.values(),
+    forEach: (callback, thisArg) => {
+      source.forEach((value, key) => callback.call(thisArg, value, key, view));
+    },
+    [Symbol.iterator]: () => source[Symbol.iterator]()
+  });
+  return view;
+}
+function readonlySetView(source) {
+  let view;
+  view = Object.freeze({
+    get size() {
+      return source.size;
+    },
+    has: (value) => source.has(value),
+    entries: () => source.entries(),
+    keys: () => source.keys(),
+    values: () => source.values(),
+    forEach: (callback, thisArg) => {
+      source.forEach((value) => callback.call(thisArg, value, value, view));
+    },
+    [Symbol.iterator]: () => source[Symbol.iterator](),
+    union: (other) => {
+      const result = new Set(source);
+      for (const value of iteratorValues(other.keys())) result.add(value);
+      return result;
+    },
+    intersection: (other) => {
+      const result = /* @__PURE__ */ new Set();
+      for (const value of source) {
+        if (other.has(value)) result.add(value);
+      }
+      return result;
+    },
+    difference: (other) => {
+      const result = /* @__PURE__ */ new Set();
+      for (const value of source) {
+        if (!other.has(value)) result.add(value);
+      }
+      return result;
+    },
+    symmetricDifference: (other) => {
+      const result = new Set(source);
+      for (const value of iteratorValues(other.keys())) {
+        if (source.has(value)) result.delete(value);
+        else result.add(value);
+      }
+      return result;
+    },
+    isSubsetOf: (other) => {
+      for (const value of source) if (!other.has(value)) return false;
+      return true;
+    },
+    isSupersetOf: (other) => {
+      for (const value of iteratorValues(other.keys())) {
+        if (!source.has(value)) return false;
+      }
+      return true;
+    },
+    isDisjointFrom: (other) => {
+      for (const value of source) if (other.has(value)) return false;
+      return true;
+    }
+  });
+  return view;
+}
+function* iteratorValues(iterator) {
+  while (true) {
+    const result = iterator.next();
+    if (result.done) return;
+    yield result.value;
+  }
+}
+
+// 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/helpers/json.ts
+var DEFAULT_MAX_JSON_DEPTH = 64;
+var DEFAULT_MAX_JSON_VALUES = 25e4;
+var DEFAULT_MAX_JSON_STRING_CHARACTERS = 8e6;
+function createJsonValueBudget() {
+  return {
+    remainingValues: DEFAULT_MAX_JSON_VALUES,
+    remainingStringCharacters: DEFAULT_MAX_JSON_STRING_CHARACTERS
+  };
+}
+function consumeBudget(budget, path, stringCharacters = 0) {
+  budget.remainingValues -= 1;
+  budget.remainingStringCharacters -= stringCharacters;
+  if (budget.remainingValues < 0 || budget.remainingStringCharacters < 0) {
+    throw new BoardInputError(`${path} exceeds the supported JSON size.`);
+  }
+}
+function freezeJsonValue(value, path, ancestors = /* @__PURE__ */ new Set(), budget = createJsonValueBudget(), depth = 0) {
+  if (depth > DEFAULT_MAX_JSON_DEPTH) {
+    throw new BoardInputError(
+      `${path} exceeds the supported JSON nesting depth.`
+    );
+  }
+  consumeBudget(budget, path, typeof value === "string" ? value.length : 0);
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new BoardInputError(`${path} must contain only finite numbers.`);
+    }
+    return value;
+  }
+  if (typeof value !== "object") {
+    throw new BoardInputError(`${path} must contain only JSON values.`);
+  }
+  if (ancestors.has(value)) {
+    throw new BoardInputError(`${path} must not contain cycles.`);
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const ownKeys = Reflect.ownKeys(value);
+      for (const key of ownKeys) {
+        if (key === "length") continue;
+        if (typeof key === "symbol" || !/^(0|[1-9]\d*)$/.test(key)) {
+          throw new BoardInputError(
+            `${path} must contain only indexed JSON array values.`
+          );
+        }
+      }
+      const entries2 = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor || !descriptor.enumerable || !("value" in descriptor)) {
+          throw new BoardInputError(
+            `${path}[${index}] must be an enumerable JSON value.`
+          );
+        }
+        entries2.push(
+          freezeJsonValue(
+            descriptor.value,
+            `${path}[${index}]`,
+            ancestors,
+            budget,
+            depth + 1
+          )
+        );
+      }
+      return Object.freeze(entries2);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new BoardInputError(`${path} must contain only plain objects.`);
+    }
+    const entries = [];
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key === "symbol") {
+        throw new BoardInputError(`${path} must not contain symbol keys.`);
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor?.enumerable || !("value" in descriptor)) {
+        throw new BoardInputError(
+          `${path}.${key} must be an enumerable data property.`
+        );
+      }
+      budget.remainingStringCharacters -= key.length;
+      if (budget.remainingStringCharacters < 0) {
+        throw new BoardInputError(`${path} exceeds the supported JSON size.`);
+      }
+      entries.push([
+        key,
+        freezeJsonValue(
+          descriptor.value,
+          `${path}.${key}`,
+          ancestors,
+          budget,
+          depth + 1
+        )
+      ]);
+    }
+    return Object.freeze(Object.fromEntries(entries));
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function freezeJsonObject(value, path, budget = createJsonValueBudget()) {
+  const cloned = freezeJsonValue(value, path, /* @__PURE__ */ new Set(), budget);
+  if (Array.isArray(cloned) || cloned === null || typeof cloned !== "object") {
+    throw new BoardInputError(`${path} must be a JSON object.`);
+  }
+  return cloned;
+}
+function collectJsonObjectExtras(value, knownKeys, path = "JSON object", budget = createJsonValueBudget()) {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(value).filter(([key]) => !knownKeys.has(key)).map(([key, entry]) => [
+        key,
+        freezeJsonValue(entry, `${path}.${key}`, /* @__PURE__ */ new Set(), budget)
+      ])
+    )
+  );
+}
+
+// src/dom-attributes.ts
+var BOARD_ROOT_ATTRIBUTE = "data-board-root";
+var BOARD_ROOT_SELECTOR = `[${BOARD_ROOT_ATTRIBUTE}="true"]`;
+var BOARD_INTERACTIVE_ATTRIBUTE = "data-board-interactive";
+var BOARD_INTERACTIVE_SELECTOR = `[${BOARD_INTERACTIVE_ATTRIBUTE}="true"]`;
+var BOARD_EDITOR_ATTRIBUTE = "data-editor";
+var BOARD_NODE_ID_ATTRIBUTE = "data-node-id";
+var BOARD_RESIZE_ATTRIBUTE = "data-resize";
+var BOARD_INTERACTIVE_TARGET_SELECTOR = [
+  BOARD_INTERACTIVE_SELECTOR,
+  `[${BOARD_EDITOR_ATTRIBUTE}="true"]`,
+  "input",
+  "textarea",
+  "select",
+  "button",
+  "a[href]",
+  '[contenteditable]:not([contenteditable="false"])'
+].join(",");
+function asElement(target) {
+  return typeof Element !== "undefined" && target instanceof Element ? target : null;
+}
+function isEventOwnedByBoardRoot(target, root) {
+  const element = asElement(target);
+  return Boolean(
+    element && root && element.closest(BOARD_ROOT_SELECTOR) === root
+  );
+}
+function isBoardInteractiveEventTarget(target, options = {}) {
+  const element = asElement(target);
+  if (options.allowResizeHandle && element?.closest(`[${BOARD_RESIZE_ATTRIBUTE}]`)) {
+    return false;
+  }
+  return Boolean(element?.closest(BOARD_INTERACTIVE_TARGET_SELECTOR));
+}
+
+// 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 {
+  freezeClone,
+  sameArray,
+  readonlyMapView,
+  readonlySetView,
+  BoardError,
+  BoardInputError,
+  BoardNotFoundError,
+  BoardConflictError,
+  BoardDestroyedError,
+  createJsonValueBudget,
+  freezeJsonValue,
+  freezeJsonObject,
+  collectJsonObjectExtras,
+  BOARD_ROOT_ATTRIBUTE,
+  BOARD_ROOT_SELECTOR,
+  BOARD_INTERACTIVE_ATTRIBUTE,
+  BOARD_INTERACTIVE_SELECTOR,
+  BOARD_EDITOR_ATTRIBUTE,
+  BOARD_NODE_ID_ATTRIBUTE,
+  BOARD_RESIZE_ATTRIBUTE,
+  isEventOwnedByBoardRoot,
+  isBoardInteractiveEventTarget,
+  registerBoardInteractionAdapter,
+  getBoardInteractionAdapter,
+  defineInternalBoardPlugin,
+  assertInternalBoardPlugin
+};

package/dist/dom-attributes.d.ts

@@ -0,0 +1,13 @@
+export declare const BOARD_ROOT_ATTRIBUTE = "data-board-root";
+export declare const BOARD_ROOT_SELECTOR = "[data-board-root=\"true\"]";
+export declare const BOARD_INTERACTIVE_ATTRIBUTE = "data-board-interactive";
+export declare const BOARD_INTERACTIVE_SELECTOR = "[data-board-interactive=\"true\"]";
+export declare const BOARD_EDITOR_ATTRIBUTE = "data-editor";
+export declare const BOARD_NODE_ID_ATTRIBUTE = "data-node-id";
+export declare const BOARD_RESIZE_ATTRIBUTE = "data-resize";
+/** Whether a bubbled DOM event belongs to this board rather than a nested root. */
+export declare function isEventOwnedByBoardRoot(target: EventTarget | null, root: HTMLElement | null): boolean;
+/** Whether native editable or explicitly interactive content owns an event. */
+export declare function isBoardInteractiveEventTarget(target: EventTarget | null, options?: {
+    allowResizeHandle?: boolean;
+}): boolean;

package/dist/engine/json-canvas-extras.d.ts

@@ -0,0 +1,12 @@
+import type { JsonCanvasPassthrough } from '../state/types.js';
+import type { JsonObject, NodeId } from '../types.js';
+/** Remove one canonical node's private JSON Canvas passthrough fields. */
+export declare function removeNodeExtras(current: JsonCanvasPassthrough, id: NodeId): JsonCanvasPassthrough;
+/** Copy private node fields through an ID remap into the canonical store. */
+export declare function copyNodeExtras(current: JsonCanvasPassthrough, idMap: ReadonlyMap<NodeId, NodeId>, source?: ReadonlyMap<NodeId, JsonObject>): JsonCanvasPassthrough;
+/** Replace all private JSON Canvas fields from a normalized document. */
+export declare function replaceJsonCanvasExtras(incoming: JsonCanvasPassthrough): JsonCanvasPassthrough;
+/** Merge normalized document fields while remapping colliding node IDs. */
+export declare function mergeJsonCanvasExtras(current: JsonCanvasPassthrough, incoming: JsonCanvasPassthrough, idMap: ReadonlyMap<NodeId, NodeId>): JsonCanvasPassthrough;
+/** Select private fields for nodes copied into the internal clipboard. */
+export declare function selectNodeExtras(source: ReadonlyMap<NodeId, JsonObject>, ids: Iterable<NodeId>): Map<NodeId, JsonObject>;

package/dist/engine/persistence.d.ts

@@ -1,3 +1,4 @@
+import type { JsonCanvasPassthrough } from '../state/types.js';
 import type { BoardNode, InternalBoardSnapshot, JsonCanvasDocument, JsonCanvasNodeType } from '../types.js';
 export declare function normalizeNodeType(value: unknown): JsonCanvasNodeType;
 export declare function withNodeFields(base: Pick<BoardNode, 'id' | 'x' | 'y' | 'width' | 'height' | 'color' | 'zIndex' | 'locked' | 'visible' | 'parentId'> & {
@@ -12,7 +13,8 @@ export declare function withNodeFields(base: Pick<BoardNode, 'id' | 'x' | 'y' |
     background?: string;
     backgroundStyle?: string;
 }): BoardNode;
-export declare function toPersistedDocument(snapshot: InternalBoardSnapshot, featureDocuments: Partial<JsonCanvasDocument>[]): JsonCanvasDocument;
+export declare function toPersistedDocument(snapshot: InternalBoardSnapshot, featureDocuments: Partial<JsonCanvasDocument>[], passthrough: JsonCanvasPassthrough): JsonCanvasDocument;
 export declare function normalizeDocumentForImport(raw: unknown): JsonCanvasDocument;
+export declare function extractJsonCanvasPassthrough(document: JsonCanvasDocument): JsonCanvasPassthrough;
 export declare function materializeSnapshotNodes(snapshot: InternalBoardSnapshot): BoardNode[];
 export declare function documentToSnapshot(document: JsonCanvasDocument): InternalBoardSnapshot;

package/dist/engine/public-engine.d.ts

@@ -0,0 +1,8 @@
+import type { BoardEngine, BoardPluginApis } from '../types.js';
+/**
+ * Build the public capability boundary explicitly.
+ *
+ * Keep this whitelist in sync with `BoardEngine`: privileged plugin and pointer
+ * methods must never become observable merely because the runtime gains a key.
+ */
+export declare function createPublicEngine<TPluginApis extends BoardPluginApis, TPluginEvents>(engine: BoardEngine<TPluginApis>): BoardEngine<TPluginApis, TPluginEvents>;

package/dist/helpers/json.d.ts

@@ -0,0 +1,13 @@
+import type { JsonObject, JsonValue } from '../types.js';
+export interface JsonValueBudget {
+    remainingValues: number;
+    remainingStringCharacters: number;
+}
+/** Create one shared resource budget for an untrusted JSON input boundary. */
+export declare function createJsonValueBudget(): JsonValueBudget;
+/** Clone, validate, and freeze a JSON-compatible value at an input boundary. */
+export declare function freezeJsonValue(value: unknown, path: string, ancestors?: Set<object>, budget?: JsonValueBudget, depth?: number): JsonValue;
+/** Clone, validate, and freeze a JSON object at an input boundary. */
+export declare function freezeJsonObject(value: unknown, path: string, budget?: JsonValueBudget): JsonObject;
+/** Retain unrecognized JSON fields without allowing them to override known fields. */
+export declare function collectJsonObjectExtras(value: Readonly<Record<string, unknown>>, knownKeys: ReadonlySet<string>, path?: string, budget?: JsonValueBudget): JsonObject;

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { getSelectionBounds, getSelectionNodes, toggleIds, } from './selection.j
 /** Geometry helpers used by renderers and framework adapters. */
 export { boundsIntersect, clamp, getBoundsFromPoints, getVisibleBounds, } from './math.js';
 /** Core engine, document, geometry, and node model types. */
-export type { BoxSelectBehavior, BoxSelectMode, BoxSelectSettings, BoardColorPreset, BoardState, Bounds, Camera, CanvasColor, BoardEngine, BoardEngineOptions, BoardUnhandledErrorContext, BoardEventMap, BoardPlugin, BoardNode, EdgeId, DuplicateNodesResult, GridPattern, GridSettings, InteractionMode, InteractionState, ValidationFailure, BoardPluginApis, JsonCanvasBackgroundStyle, JsonCanvasDocument, JsonCanvasEdge, JsonCanvasEdgeEnd, JsonCanvasFileNode, JsonCanvasGroupNode, JsonCanvasLinkNode, JsonCanvasNode, JsonCanvasNodeType, JsonCanvasSide, JsonCanvasTextNode, NodeConstraints, NodeId, NodeInput, NodePatch, Point, ResizeHandle, SelectionMode, SnapAxis, SnapGuide, Subscribable, TraceEntry, Unsubscribe, VueBoardDocumentMetadata, VueBoardEdgeMetadata, VueBoardNodeMetadata, ZoomSettings, } from './types.js';
+export type { BoxSelectBehavior, BoxSelectMode, BoxSelectSettings, BoardDocumentMetadata, BoardEdgeMetadata, BoardNodeMetadata, BoardColorPreset, BoardClipboardHooks, BoardState, Bounds, Camera, CanvasColor, BoardEngine, BoardEngineOptions, BoardUnhandledErrorContext, BoardEventMap, BoardPlugin, BoardNode, EdgeId, DuplicateNodesResult, GridPattern, GridSettings, InteractionMode, InteractionState, ValidationFailure, BoardPluginApis, JsonCanvasBackgroundStyle, JsonCanvasDocument, JsonCanvasEdge, JsonCanvasEdgeEnd, JsonCanvasFileNode, JsonCanvasGroupNode, JsonCanvasLinkNode, JsonCanvasNode, JsonCanvasNodeType, JsonCanvasSide, JsonCanvasTextNode, JsonObject, JsonValue, NodeConstraints, NodeId, NodeInput, NodePatch, Point, ResizeHandle, SelectionMode, SnapAxis, SnapGuide, Subscribable, TraceEntry, Unsubscribe, ZoomSettings, } from './types.js';