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

package/dist/agent/pages/docs/evaluate/how-nuxt-board-works.md

@@ -33,8 +33,457 @@ application intent
 3. **Renderers own presentation.** A renderer receives a node record. It does not create a competing state model.
 4. **Packages own named capabilities.** Core owns nodes; connections owns edges; history owns undo stacks; Nuxt owns registration.
 
-> Component omitted: `engine-command-lab`.
-> This page contains an interactive or site-specific block that has no agent markdown serializer yet.
+## Live example source
+
+Use the installation guide to register @lupinum/nuxt-board. These are the actual documentation demo files. Keep their paths under app/. The module auto-imports Board components; install the optional packages named in imports. For the local content components, use components: [{ path: "~/components/content", pathPrefix: false }, "~/components"] in nuxt.config.ts, as this site does, or import them explicitly. createDemoDocument is a local helper, not a package export. DocsLab and the inspector components provide presentation only.
+
+### app/components/demos/EngineCommandLab.vue
+
+````vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import { asNodeId, createBoardEngine } from '@lupinum/board-core'
+import { createDemoDocument } from '../../utils/demoDocument'
+
+const CARD_ID = asNodeId('review-card')
+const engine = createBoardEngine({ grid: { size: 20, snap: true } })
+const revision = ref(0)
+const events = ref<{ label: string; detail?: string; tone?: 'success' }[]>([])
+const before = ref<Record<string, unknown>>({})
+const after = ref<Record<string, unknown>>({})
+const disposers: (() => void)[] = []
+
+function nodeSummary() {
+  const node = engine.getState().nodes.get(CARD_ID)
+  return node
+    ? { id: node.id, text: node.text, x: node.x, y: node.y, color: node.color }
+    : { id: CARD_ID, deleted: true }
+}
+
+const state = computed(() => {
+  void revision.value
+  return {
+    nodes: engine.getState().nodes.size,
+    selection: engine.getSelection(),
+    card: nodeSummary(),
+  }
+})
+
+function seed() {
+  engine.loadDocument(
+    createDemoDocument({
+      camera: { x: 0, y: 0, z: 1 },
+      grid: engine.getGridSettings(),
+      selection: [CARD_ID],
+      nextZIndex: 3,
+      nodes: [
+        {
+          id: CARD_ID,
+          type: 'text',
+          x: 90,
+          y: 80,
+          width: 240,
+          height: 120,
+          text: 'Review onboarding',
+          color: '5',
+          zIndex: 1,
+          locked: false,
+          visible: true,
+        },
+        {
+          id: asNodeId('release-card'),
+          type: 'text',
+          x: 400,
+          y: 180,
+          width: 240,
+          height: 120,
+          text: 'Prepare release notes',
+          color: '4',
+          zIndex: 2,
+          locked: false,
+          visible: true,
+        },
+      ],
+    }),
+    { mode: 'replace' },
+  )
+  events.value = []
+  before.value = nodeSummary()
+  after.value = nodeSummary()
+  revision.value++
+}
+
+function rename() {
+  before.value = nodeSummary()
+  events.value = []
+  engine.updateNode(CARD_ID, {
+    text: 'Review onboarding · approved',
+    color: '4',
+  })
+  after.value = nodeSummary()
+  revision.value++
+}
+
+function move() {
+  before.value = nodeSummary()
+  events.value = []
+  engine.moveNode(CARD_ID, 80, 40)
+  after.value = nodeSummary()
+  revision.value++
+}
+
+onMounted(async () => {
+  disposers.push(
+    engine.on('command:before', (name) =>
+      events.value.push({ label: 'command:before', detail: name }),
+    ),
+    engine.on('node:updated', (node) =>
+      events.value.push({ label: 'node:updated', detail: node.id }),
+    ),
+    engine.on('command:after', (name) =>
+      events.value.push({
+        label: 'command:after',
+        detail: name,
+        tone: 'success',
+      }),
+    ),
+  )
+  seed()
+  await engine.zoomToFit(64, false)
+})
+
+onBeforeUnmount(() => disposers.forEach((dispose) => dispose()))
+</script>
+
+<template>
+  <DocsLab
+    title="Command inspector"
+    description="Run one command and inspect the state change and publication order."
+    instructions="Rename or move the selected card. The command commits before public events appear."
+  >
+    <template #controls>
+      <button type="button" @click="seed">Reset</button>
+      <button type="button" data-primary="true" @click="rename">
+        Rename card
+      </button>
+      <button type="button" @click="move">Move card</button>
+    </template>
+    <BoardRoot :engine="engine" style="height: 360px" />
+    <template #inspect>
+      <StateInspector title="Engine state" :value="state" />
+    </template>
+    <template #timeline>
+      <EventTimeline :entries="events" />
+      <DocumentDiff :before="before" :after="after" />
+    </template>
+    <template #code>
+      <CodePreview
+        code="engine.updateNode(card.id, {\n  text: 'Review onboarding · approved',\n  color: '4',\n})"
+      />
+    </template>
+  </DocsLab>
+</template>
+````
+
+### app/utils/demoDocument.ts
+
+````ts
+import type {
+  BoardNode,
+  BoardNodeMetadata,
+  Camera,
+  GridSettings,
+  JsonCanvasDocument,
+  JsonCanvasNode,
+  NodeId,
+} from '@lupinum/board-core'
+
+type DemoNode = Omit<
+  Pick<
+    BoardNode,
+    | 'id'
+    | 'type'
+    | 'x'
+    | 'y'
+    | 'width'
+    | 'height'
+    | 'color'
+    | 'text'
+    | 'file'
+    | 'subpath'
+    | 'url'
+    | 'label'
+    | 'background'
+    | 'backgroundStyle'
+    | 'zIndex'
+    | 'locked'
+    | 'visible'
+    | 'parentId'
+  >,
+  'id' | 'parentId'
+> & {
+  id: NodeId | string
+  parentId?: NodeId | string
+}
+
+export interface DemoDocumentInput {
+  nodes: readonly DemoNode[]
+  camera?: Camera
+  grid?: GridSettings
+  selection?: readonly (NodeId | string)[]
+  nextZIndex?: number
+}
+
+function toJsonCanvasNode(node: DemoNode): JsonCanvasNode {
+  const base = {
+    id: node.id as NodeId,
+    type: node.type,
+    x: node.x,
+    y: node.y,
+    width: node.width,
+    height: node.height,
+    ...(node.color ? { color: node.color } : {}),
+  }
+
+  switch (node.type) {
+    case 'file':
+      return {
+        ...base,
+        type: 'file',
+        file: node.file ?? '',
+        ...(node.subpath ? { subpath: node.subpath } : {}),
+      }
+    case 'link':
+      return {
+        ...base,
+        type: 'link',
+        url: node.url ?? '',
+      }
+    case 'group':
+      return {
+        ...base,
+        type: 'group',
+        ...((node.label ?? node.text)
+          ? { label: node.label ?? node.text }
+          : {}),
+        ...(node.background ? { background: node.background } : {}),
+        ...(node.backgroundStyle
+          ? { backgroundStyle: node.backgroundStyle }
+          : {}),
+      }
+    case 'text':
+    default:
+      return {
+        ...base,
+        type: 'text',
+        text: node.text ?? '',
+      }
+  }
+}
+
+function toNodeMetadata(node: DemoNode): BoardNodeMetadata {
+  return {
+    zIndex: node.zIndex,
+    locked: node.locked,
+    visible: node.visible,
+    ...(node.parentId ? { parentId: node.parentId as NodeId } : {}),
+  }
+}
+
+export function createDemoDocument(
+  input: DemoDocumentInput,
+): JsonCanvasDocument {
+  return {
+    nodes: input.nodes.map(toJsonCanvasNode),
+    'x-lupinum-board': {
+      ...(input.camera ? { camera: input.camera } : {}),
+      ...(input.grid ? { grid: input.grid } : {}),
+      ...(input.selection
+        ? { selection: input.selection.map((id) => id as NodeId) }
+        : {}),
+      nextZIndex:
+        input.nextZIndex ??
+        input.nodes.reduce((max, node) => Math.max(max, node.zIndex), 0) + 1,
+      nodes: Object.fromEntries(
+        input.nodes.map((node) => [node.id, toNodeMetadata(node)]),
+      ),
+    },
+  }
+}
+````
+
+### app/components/content/DocsLab.vue
+
+````vue
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    title: string
+    description: string
+    instructions?: string
+  }>(),
+  { instructions: undefined },
+)
+</script>
+
+<template>
+  <section class="docs-lab" :aria-label="title">
+    <header class="docs-lab__header">
+      <div>
+        <h3>{{ title }}</h3>
+        <p>{{ description }}</p>
+      </div>
+      <div v-if="$slots.controls" class="docs-lab__controls">
+        <slot name="controls" />
+      </div>
+    </header>
+
+    <p v-if="instructions" class="docs-lab__instructions">
+      <span>Try this</span>
+      {{ instructions }}
+    </p>
+
+    <div class="docs-lab__workspace">
+      <div class="docs-lab__stage">
+        <slot />
+      </div>
+      <aside
+        v-if="$slots.inspect"
+        class="docs-lab__inspect"
+        aria-label="Live inspector"
+      >
+        <slot name="inspect" />
+      </aside>
+    </div>
+
+    <div v-if="$slots.timeline" class="docs-lab__timeline">
+      <slot name="timeline" />
+    </div>
+    <div v-if="$slots.code" class="docs-lab__code">
+      <slot name="code" />
+    </div>
+  </section>
+</template>
+````
+
+### app/components/content/StateInspector.vue
+
+````vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = withDefaults(
+  defineProps<{
+    title?: string
+    value: unknown
+    empty?: string
+  }>(),
+  { title: 'State', empty: 'No value' },
+)
+
+const formatted = computed(() => {
+  if (props.value === undefined || props.value === null) return props.empty
+  return typeof props.value === 'string'
+    ? props.value
+    : JSON.stringify(props.value, null, 2)
+})
+</script>
+
+<template>
+  <div class="state-inspector">
+    <p class="state-inspector__title">{{ title }}</p>
+    <pre aria-live="polite">{{ formatted }}</pre>
+  </div>
+</template>
+````
+
+### app/components/content/CodePreview.vue
+
+````vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = withDefaults(defineProps<{ code: string; label?: string }>(), {
+  label: 'Relevant code',
+})
+const copied = ref(false)
+
+async function copy() {
+  await navigator.clipboard.writeText(props.code)
+  copied.value = true
+  window.setTimeout(() => (copied.value = false), 1400)
+}
+</script>
+
+<template>
+  <div class="code-preview">
+    <div>
+      <span>{{ label }}</span>
+      <button type="button" @click="copy">
+        {{ copied ? 'Copied' : 'Copy' }}
+      </button>
+    </div>
+    <pre><code>{{ code }}</code></pre>
+  </div>
+</template>
+````
+
+### app/components/content/EventTimeline.vue
+
+````vue
+<script setup lang="ts">
+export interface TimelineEntry {
+  label: string
+  detail?: string
+  tone?: 'default' | 'success' | 'danger'
+}
+
+defineProps<{ entries: TimelineEntry[] }>()
+</script>
+
+<template>
+  <div class="event-timeline" aria-live="polite">
+    <p v-if="entries.length === 0" class="event-timeline__empty">
+      Run an action to inspect its publication order.
+    </p>
+    <ol v-else>
+      <li
+        v-for="(entry, index) in entries"
+        :key="`${index}-${entry.label}`"
+        :data-tone="entry.tone"
+      >
+        <span>{{ String(index + 1).padStart(2, '0') }}</span>
+        <strong>{{ entry.label }}</strong>
+        <code v-if="entry.detail">{{ entry.detail }}</code>
+      </li>
+    </ol>
+  </div>
+</template>
+````
+
+### app/components/content/DocumentDiff.vue
+
+````vue
+<script setup lang="ts">
+defineProps<{
+  before: Record<string, unknown>
+  after: Record<string, unknown>
+}>()
+</script>
+
+<template>
+  <div class="document-diff">
+    <div>
+      <p>Before</p>
+      <pre>{{ JSON.stringify(before, null, 2) }}</pre>
+    </div>
+    <div>
+      <p>After</p>
+      <pre>{{ JSON.stringify(after, null, 2) }}</pre>
+    </div>
+  </div>
+</template>
+````
 
 Run a command in the lab. The document changes before queued public events publish. Subscribers never receive an intermediate candidate.
 

package/dist/agent/pages/docs/project/contributing.md

@@ -17,7 +17,7 @@ Contributions are welcome when they keep the library easier to use, test, and ma
 
 ## Set up the repository
 
-The canonical contribution policy is [CONTRIBUTING.md](https://github.com/lupinum-dev/nuxt-board/blob/main/CONTRIBUTING.md). From the repository root:
+The canonical contribution policy is [CONTRIBUTING.md](https://github.com/lupinum-dev/nuxt-board/blob/main/.github/CONTRIBUTING.md). From the repository root:
 
 ```bash
 corepack enable
@@ -27,8 +27,8 @@ pnpm install
 Start the playground or docs app:
 
 ```bash
-pnpm dev:playground
-pnpm dev:docs
+pnpm dev
+pnpm docs:dev
 ```
 
 The playground is the fastest place to verify interaction changes. The docs app uses the workspace packages, so examples exercise the same code consumers install.
@@ -41,7 +41,7 @@ Run the narrowest relevant check while you work, then the repository gate before
 pnpm verify
 ```
 
-Use `pnpm test:e2e` for browser interaction or screenshot changes. Maintainers use `pnpm release:verify` only on a release candidate.
+Use `pnpm test:e2e` for browser interaction or screenshot changes.
 
 ## Where docs live
 

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

@@ -37,4 +37,4 @@ 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.
+The [`SECURITY.md`](https://github.com/lupinum-dev/nuxt-board/blob/main/.github/SECURITY.md) is the source of truth for the current reporting policy.