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

package/dist/agent/pages/docs/project/support-and-security.md

@@ -0,0 +1,40 @@
+---
+title: "Support and security"
+description: "Where to report bugs, request features, and disclose security issues."
+url: "https://nuxt-board.lupinum.com/docs/project/support-and-security"
+route: "/docs/project/support-and-security"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Support and security
+
+> Where to report bugs, request features, and disclose security issues.
+
+Use GitHub issues for bugs and feature requests. Include a reproduction when the issue involves interaction, rendering, serialization, or Nuxt integration.
+
+## Bug reports
+
+A useful bug report includes:
+
+- package versions
+- browser and operating system when UI behavior is involved
+- a small reproduction or failing test
+- expected behavior
+- actual behavior
+- screenshots or video for visual regressions
+
+## Feature requests
+
+Describe the product workflow first. API proposals are welcome, but the use case matters more than the first shape of the API.
+
+## Security reports
+
+Use GitHub private vulnerability reporting. If that channel is not available,
+email `info@lupinum.com`. Do not open a public issue with exploit details.
+
+Include the affected package, the suspected impact, and reproduction steps if you can share them safely.
+
+The root [`SECURITY.md`](https://github.com/lupinum-dev/nuxt-board/blob/main/SECURITY.md) is the source of truth for the current reporting policy.

package/dist/agent/pages/docs/reference/board-core-types.md

@@ -0,0 +1,82 @@
+---
+title: "@lupinum/board-core types"
+description: "The public state, node, and JSON Canvas document types."
+url: "https://nuxt-board.lupinum.com/docs/reference/board-core-types"
+route: "/docs/reference/board-core-types"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/board-core types
+
+> The public state, node, and JSON Canvas document types.
+
+## Persisted documents
+
+Persisted board data uses `JsonCanvasDocument`.
+
+```ts
+interface JsonCanvasDocument {
+  readonly nodes: readonly JsonCanvasNode[]
+  readonly edges?: readonly JsonCanvasEdge[]
+  readonly 'x-lupinum-board'?: BoardDocumentMetadata
+}
+```
+
+Core owns node persistence and board metadata. The connections package owns edge
+persistence. Runtime snapshot fields such as `camera`, `grid`, and `selection`
+are not accepted as top-level persisted document fields.
+
+## Runtime state
+
+`BoardState` is the immutable runtime view used by renderers and UI reads.
+
+```ts
+interface BoardState {
+  readonly camera: Camera
+  readonly grid: GridSettings
+  readonly nodes: ReadonlyMap<NodeId, BoardNode>
+  readonly selection: ReadonlySet<NodeId>
+  readonly interaction: InteractionState
+  readonly snapGuides: readonly SnapGuide[]
+}
+```
+
+Read it with `engine.getState()`. Use `engine.exportDocument()` and
+`engine.loadDocument()` for persistence; runtime state is not a persistence
+payload.
+
+## BoardNode
+
+```ts
+interface BoardNodeBase {
+  readonly id: NodeId
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+  readonly color?: CanvasColor
+  readonly zIndex: number
+  readonly locked: boolean
+  readonly visible: boolean
+  readonly parentId?: NodeId
+}
+
+type BoardNode =
+  | (BoardNodeBase & { type: 'text'; text: string })
+  | (BoardNodeBase & { type: 'file'; file: string; subpath?: string })
+  | (BoardNodeBase & { type: 'link'; url: string })
+  | (BoardNodeBase & {
+      type: 'group'
+      label?: string
+      background?: string
+      backgroundStyle?: 'cover' | 'ratio' | 'repeat'
+    })
+```
+
+There is no `data` property on public nodes. `BoardNode` is discriminated by
+`type`, so narrowing guarantees the corresponding JSON Canvas content field.
+`NodeInput` defaults to a text node; file and link inputs require `file` and
+`url` respectively.

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

@@ -0,0 +1,261 @@
+---
+title: "@lupinum/board-core"
+description: "The supported public API for the headless board engine."
+url: "https://nuxt-board.lupinum.com/docs/reference/board-core"
+route: "/docs/reference/board-core"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# @lupinum/board-core
+
+> The supported public API for the headless board engine.
+
+`@lupinum/board-core` exports the engine factory, public board types, JSON Canvas
+document types, color helpers, and selection helpers.
+
+It does not expose transaction roots, plugin persistence hooks, or history
+internals as stable consumer API.
+
+The package also publishes `@lupinum/board-core/internal` so first-party
+packages such as `@lupinum/board-history` and `@lupinum/board-connections` can
+compose with the core engine after they are installed from npm. That subpath is
+the first-party feature ABI, not an application plugin API; app code should use
+the top-level `@lupinum/board-core` entrypoint and install supported features
+through `plugins`.
+
+## createBoardEngine
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+
+const engine = createBoardEngine({
+  grid: { size: 24, snap: true },
+  onUnhandledError(error, context) {
+    reportError(error, context)
+  },
+})
+```
+
+Listener, reactive subscriber, and finalized plugin commit-effect failures are
+reported through `onUnhandledError` after a commit; they cannot roll committed
+state back. Inspect `context.source` to distinguish `event-listener`,
+`subscriber`, and `commit-effect` failures. Without a hook, the engine falls
+back to `console.error`.
+
+Install first-party packages with `plugins`.
+
+```ts
+const engine = createBoardEngine({
+  plugins: [historyPlugin(), connectionsPlugin()],
+})
+```
+
+Plugin names must be unique. Construction throws `BoardConflictError` before
+any plugin installs when the tuple contains a duplicate name.
+
+## Nodes
+
+Nodes use JSON Canvas fields directly.
+
+```ts
+engine.createNode({
+  type: 'text',
+  x: 120,
+  y: 80,
+  width: 240,
+  height: 120,
+  text: 'Release plan',
+})
+```
+
+Supported node fields are `text`, `file`, `subpath`, `url`, `label`,
+`background`, and `backgroundStyle`. There is no legacy data compatibility layer.
+
+## Persistence
+
+Use `exportDocument()` and `loadDocument()` for persisted documents.
+
+```ts
+const document = engine.exportDocument()
+engine.loadDocument(document, { mode: 'replace' })
+```
+
+Core persists nodes and board metadata. Edges belong to
+`@lupinum/board-connections`; importing a document with edges without that
+connections package installed fails instead of dropping edge data.
+
+## Engine reference
+
+The engine is the public mutation boundary. App code should use these methods
+instead of editing node maps, selection sets, or camera objects directly.
+
+### State and lifecycle
+
+| API | Purpose |
+| --- | --- |
+| `engine.plugins` | Feature APIs installed through `plugins`. |
+| `engine.$camera` | Subscribable camera state. |
+| `engine.$nodes` | Subscribable read-only map of nodes. |
+| `engine.$selection` | Subscribable read-only set of selected node IDs. |
+| `engine.$interaction` | Subscribable current pointer/editing interaction state. |
+| `engine.$snapGuides` | Subscribable active snap guides. |
+| `destroy()` | Tear down engine subscriptions and resources. |
+| `batch(fn)` | Run multiple commands while deferring subscribable notifications. |
+| `getState()` | Read the current board state. |
+| `getGridSettings()` | Read resolved grid settings. |
+| `updateGridSettings(patch)` | Update grid settings and return the resolved settings. |
+| `getViewportSize()` | Read the last viewport size reported by the renderer. |
+| `setViewportSize(size)` | Update viewport size. Renderers call this from resize observation. |
+| `exportTrace()` | Read command trace entries. |
+| `addCommandGuard(fn)` | Register a synchronous command guard for concrete product policy. |
+
+### Events
+
+```ts
+const unsubscribe = engine.on('node:created', (node) => {
+  console.log(node.id)
+})
+
+engine.once('destroy', () => {
+  console.log('engine destroyed')
+})
+
+engine.off('node:created', handler)
+unsubscribe()
+```
+
+See [events and subscriptions](/raw/docs/reference/events-and-errors.md) for the full
+event catalog and payloads.
+
+### Coordinate and camera methods
+
+| API | Purpose |
+| --- | --- |
+| `screenToWorld(point)` | Convert a screen-space point to world coordinates. |
+| `worldToScreen(point)` | Convert a world-space point to screen coordinates. |
+| `getVisibleBounds(width, height)` | Compute visible world bounds for a viewport size. |
+| `panBy(dx, dy)` | Move the camera by a world-space delta. |
+| `panTo(worldPoint, animated?)` | Pan to a world point, optionally animated. |
+| `zoomAt(screenPoint, delta)` | Zoom around a screen-space point. |
+| `zoomTo(level, animated?)` | Zoom to an absolute level, clamped by zoom settings. |
+| `zoomToFit(padding?, animated?)` | Fit all visible nodes into the viewport. |
+| `zoomToNodes(ids, padding?, animated?)` | Fit specific nodes into the viewport. |
+
+### Node methods
+
+| API | Purpose |
+| --- | --- |
+| `getNode(id)` | Return a node or throw if it does not exist. |
+| `findNode(id)` | Return a node or `null`. |
+| `hasNode(id)` | Check whether a node exists. |
+| `getNodeAt(worldPoint)` | Return the topmost visible node at a world point. |
+| `getNodesInBounds(bounds)` | Return visible nodes intersecting the bounds. |
+| `createNode(input)` | Create a node and select it unless `select: false` is passed. |
+| `updateNode(id, patch)` | Update node fields. |
+| `deleteNode(id)` | Delete a node. Deleting a group also deletes descendants. |
+| `moveNode(id, dx, dy)` | Move one node by a world-space delta. |
+| `translateSelectedNodes(dx, dy)` | Move the current selection, respecting group hierarchy. |
+| `resizeNode(id, handle, dx, dy)` | Resize one node from a compass handle. |
+| `bringToFront(id)` | Move a node above other nodes. |
+| `sendToBack(id)` | Move a node behind other nodes. |
+| `lockNode(id)` | Prevent interactive move, resize, and delete. |
+| `unlockNode(id)` | Re-enable interactive changes. |
+| `duplicateNodes(ids, offset?)` | Duplicate nodes and preserve supported hierarchy between copies. |
+
+### Selection and clipboard methods
+
+| API | Purpose |
+| --- | --- |
+| `select(ids, mode?)` | Replace, add, remove, or toggle selected node IDs. |
+| `selectAll()` | Select all visible nodes. |
+| `clearSelection()` | Clear the selection. |
+| `deleteSelected()` | Delete unlocked selected nodes and group descendants. |
+| `getSelection()` | Return selected node IDs as an array. |
+| `copySelected()` | Copy selected nodes into the engine clipboard. |
+| `pasteClipboard(offset?)` | Paste nodes from the engine clipboard. |
+
+The engine clipboard is internal to the engine. It does not read from or write
+to the system clipboard.
+
+### Text editing and document methods
+
+Pointer interactions are intentionally framework-internal. Text editing remains
+public so custom renderers can provide their own editors.
+
+| API | Purpose |
+| --- | --- |
+| `beginTextEdit(id)` | Enter text-editing mode for a text node. |
+| `commitTextEdit(id, text?)` | Commit text editing and update the text node. |
+| `cancelTextEdit()` | Leave text editing without changing content. |
+| `exportDocument()` | Return a typed JSON Canvas document. |
+| `loadDocument(document, options?)` | Validate and atomically load with `replace` or `merge`. |
+
+## Public helpers
+
+The public helpers are the helpers consumers need to build boards:
+
+- color helpers such as `BOARD_COLOR_PRESETS`, `colorForPreset`, and
+  `isBoardColorPreset`
+- id helpers such as `asNodeId` and `asEdgeId`
+- selection helpers such as `getSelectionNodes`, `getSelectionBounds`, and
+  `toggleIds`
+- geometry helpers used by renderers and overlays
+
+## Math helpers
+
+- These utility functions are exported from `@lupinum/board-core`. They are pure functions and can be used outside the engine for custom calculations.
+
+The engine also exposes instance methods such as `engine.screenToWorld()` and `engine.worldToScreen()` when the calculation depends on the current board camera.
+
+## General math
+
+### clamp
+
+Constrains a value to a range.
+
+```ts
+clamp(value: number, min: number, max: number): number
+```
+
+```ts
+clamp(15, 0, 10) // 10
+clamp(-5, 0, 10) // 0
+```
+
+## Bounds logic
+
+### boundsIntersect
+
+Returns `true` if two bounds overlap.
+
+```ts
+boundsIntersect(a: Bounds, b: Bounds): boolean
+```
+
+### getBoundsFromPoints
+
+Creates a `Bounds` from two arbitrary points. Minimum and maximum corners are computed automatically.
+
+```ts
+getBoundsFromPoints(a: Point, b: Point): Bounds
+```
+
+```ts
+const bounds = getBoundsFromPoints({ x: 10, y: 20 }, { x: 50, y: 5 })
+// { minX: 10, minY: 5, maxX: 50, maxY: 20 }
+```
+
+### getVisibleBounds
+
+Returns the world-space bounds visible within a viewport for the given camera.
+
+```ts
+getVisibleBounds(width: number, height: number, camera: Camera): Bounds
+```
+
+```ts
+const bounds = getVisibleBounds(1280, 720, camera)
+```