@crossworks/content-core 0.230.43

package/src/block-ids.test.ts

@@ -0,0 +1,358 @@
+/**
+ * Unit tests for ensureBlockIds + allBlocksHaveIds.
+ *
+ * The block-id layer is the foundation of Phase 2b (block-addressed
+ * editing) — every test below locks down an invariant the editor / tool
+ * surface depends on: every block-type node has an id, existing ids are
+ * preserved, non-block nodes (text, inline math) stay untouched, and the
+ * helper is idempotent + structurally stable when nothing needs adding.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { allBlocksHaveIds, ensureBlockIds, repairTableRows } from './block-ids';
+
+describe('ensureBlockIds', () => {
+  it('injects an id on every top-level block', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Hi' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'World' }] },
+        { type: 'horizontalRule' },
+      ],
+    };
+    const out = ensureBlockIds(doc);
+    const blocks = (out as { content: { attrs?: { id?: string } }[] }).content;
+    expect(blocks).toHaveLength(3);
+    for (const b of blocks) {
+      expect(typeof b.attrs?.id).toBe('string');
+      expect(b.attrs!.id!.length).toBeGreaterThan(8);
+    }
+    // All ids unique within the doc
+    const ids = blocks.map((b) => b.attrs!.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('descends into containers — callout body + columns + lists each get ids per block', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { variant: 'info' },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'Inside' }] },
+            { type: 'paragraph', content: [{ type: 'text', text: 'callout' }] },
+          ],
+        },
+        {
+          type: 'columnList',
+          content: [
+            {
+              type: 'column',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'L' }] }],
+            },
+            {
+              type: 'column',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'R' }] }],
+            },
+          ],
+        },
+        {
+          type: 'bulletList',
+          content: [
+            {
+              type: 'listItem',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'a' }] }],
+            },
+            {
+              type: 'listItem',
+              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'b' }] }],
+            },
+          ],
+        },
+      ],
+    };
+    const out = ensureBlockIds(doc);
+    expect(allBlocksHaveIds(out)).toBe(true);
+  });
+
+  it('preserves existing ids — does NOT regenerate', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: 'keep-me' }, content: [{ type: 'text', text: 'A' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'B' }] },
+      ],
+    };
+    const out = ensureBlockIds(doc) as {
+      content: { attrs?: { id?: string } }[];
+    };
+    expect(out.content[0]!.attrs?.id).toBe('keep-me');
+    expect(typeof out.content[1]!.attrs?.id).toBe('string');
+    expect(out.content[1]!.attrs?.id).not.toBe('keep-me');
+  });
+
+  it('returns the SAME reference when every block already has an id (no-op fast path)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: 'a' }, content: [{ type: 'text', text: 'x' }] },
+        {
+          type: 'callout',
+          attrs: { id: 'b', variant: 'info' },
+          content: [
+            { type: 'paragraph', attrs: { id: 'c' }, content: [{ type: 'text', text: 'y' }] },
+          ],
+        },
+      ],
+    };
+    const out = ensureBlockIds(doc);
+    // Identity equality — proves no allocation on the no-op path. This is
+    // the lazy-backfill happy case (every page after the first read).
+    expect(out).toBe(doc);
+  });
+
+  it('does NOT inject ids on inline-only nodes (text, marks, inline math)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'Plain ' },
+            { type: 'text', text: 'bold', marks: [{ type: 'bold' }] },
+            { type: 'inlineMath', attrs: { latex: 'E=mc^2' } },
+          ],
+        },
+      ],
+    };
+    const out = ensureBlockIds(doc) as {
+      content: {
+        attrs?: { id?: string };
+        content: { type: string; attrs?: { id?: string } }[];
+      }[];
+    };
+    const para = out.content[0]!;
+    // The paragraph itself gets an id (it's a block).
+    expect(typeof para.attrs?.id).toBe('string');
+    // But its inline children stay un-id'd — they're not addressable units.
+    for (const inline of para.content) {
+      expect(inline.attrs?.id).toBeUndefined();
+    }
+  });
+
+  it('injects an id on a childPage atom (Phase 4a — addressable sub-page card)', () => {
+    const doc = {
+      type: 'doc',
+      content: [{ type: 'childPage', attrs: { pageId: 'p1', title: 'Sub' } }],
+    };
+    const out = ensureBlockIds(doc) as {
+      content: { attrs?: { id?: string; pageId?: string } }[];
+    };
+    expect(typeof out.content[0]!.attrs?.id).toBe('string');
+    // The id is added alongside the existing attrs, never replacing them.
+    expect(out.content[0]!.attrs?.pageId).toBe('p1');
+  });
+
+  it('idempotent — running twice produces the same ids', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'one' }] },
+        { type: 'paragraph', content: [{ type: 'text', text: 'two' }] },
+      ],
+    };
+    const first = ensureBlockIds(doc) as { content: { attrs?: { id?: string } }[] };
+    const second = ensureBlockIds(first) as { content: { attrs?: { id?: string } }[] };
+    expect(first.content[0]!.attrs!.id).toBe(second.content[0]!.attrs!.id);
+    expect(first.content[1]!.attrs!.id).toBe(second.content[1]!.attrs!.id);
+    // And the no-op fast path: ref equality on the second pass.
+    expect(first).toBe(second);
+  });
+});
+
+describe('ensureBlockIds — duplicate-id self-heal', () => {
+  // Reproduces the refinery-SOP draft corruption (2026-07-06):
+  // four top-level step paragraphs sharing one id, produced by the editor
+  // copying ids on split/paste. Every later occurrence must be re-minted;
+  // the FIRST keeps the id (that's the block findBlock already resolved
+  // to, so any address the agent holds stays valid).
+  const DUP = 'a7f08640-07b3-44a5-bcb3-4bafb4fe3735';
+  const stepDoc = () => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'heading',
+        attrs: { id: 'h-55', level: 3 },
+        content: [{ type: 'text', text: '5.5 Service Import' }],
+      },
+      { type: 'paragraph', attrs: { id: DUP }, content: [{ type: 'text', text: 'Step 1' }] },
+      { type: 'paragraph', attrs: { id: DUP }, content: [{ type: 'text', text: 'Step 2' }] },
+      { type: 'paragraph', attrs: { id: DUP }, content: [{ type: 'text', text: 'Step 3' }] },
+      { type: 'paragraph', attrs: { id: 'unique-78' }, content: [{ type: 'text', text: 'Note' }] },
+      { type: 'paragraph', attrs: { id: DUP }, content: [{ type: 'text', text: 'Step 4' }] },
+    ],
+  });
+
+  it('re-mints every duplicate; the first occurrence keeps its id', () => {
+    const out = ensureBlockIds(stepDoc()) as { content: { attrs: { id: string } }[] };
+    const ids = out.content.map((b) => b.attrs.id);
+    expect(new Set(ids).size).toBe(ids.length); // all unique
+    expect(ids[1]).toBe(DUP); // first dup keeps the id
+    expect(ids[0]).toBe('h-55'); // untouched
+    expect(ids[4]).toBe('unique-78'); // untouched
+    for (const later of [ids[2], ids[3], ids[5]]) {
+      expect(later).not.toBe(DUP);
+    }
+  });
+
+  it('heals a duplicate nested inside a container (pre-order: outer first)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: 'x' }, content: [{ type: 'text', text: 'top' }] },
+        {
+          type: 'callout',
+          attrs: { id: 'c', variant: 'info' },
+          content: [
+            { type: 'paragraph', attrs: { id: 'x' }, content: [{ type: 'text', text: 'inner' }] },
+          ],
+        },
+      ],
+    };
+    const out = ensureBlockIds(doc) as unknown as {
+      content: [
+        { attrs: { id: string } },
+        { attrs: { id: string }; content: { attrs: { id: string } }[] },
+      ];
+    };
+    expect(out.content[0].attrs.id).toBe('x');
+    expect(out.content[1].content[0]!.attrs.id).not.toBe('x');
+  });
+
+  it('is idempotent after the heal (second pass is a ref-equal no-op)', () => {
+    const healed = ensureBlockIds(stepDoc());
+    expect(ensureBlockIds(healed)).toBe(healed);
+  });
+});
+
+describe('allBlocksHaveIds', () => {
+  it('returns false when two blocks share an id (dup counts as broken)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', attrs: { id: 'same' } },
+        { type: 'paragraph', attrs: { id: 'same' } },
+      ],
+    };
+    expect(allBlocksHaveIds(doc)).toBe(false);
+  });
+
+  it("returns true on a fully-id'd doc", () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { id: '1', level: 1 } },
+        { type: 'paragraph', attrs: { id: '2' } },
+      ],
+    };
+    expect(allBlocksHaveIds(doc)).toBe(true);
+  });
+
+  it('returns false if any block is missing an id', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { id: '1', level: 1 } },
+        { type: 'paragraph' }, // missing id
+      ],
+    };
+    expect(allBlocksHaveIds(doc)).toBe(false);
+  });
+
+  it('returns false if any nested block is missing an id', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { id: 'c1', variant: 'info' },
+          content: [
+            { type: 'paragraph' }, // nested missing id
+          ],
+        },
+      ],
+    };
+    expect(allBlocksHaveIds(doc)).toBe(false);
+  });
+});
+
+describe('repairTableRows', () => {
+  const cell = (t: string) => ({
+    type: 'tableCell',
+    content: [{ type: 'paragraph', content: [{ type: 'text', text: t }] }],
+  });
+  const para = (t: string) => ({ type: 'paragraph', content: [{ type: 'text', text: t }] });
+
+  it('wraps a bare paragraph child of a tableRow back into a tableCell', () => {
+    // The exact production shape: a 3-col row where 2 cells lost their wrapper.
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'table',
+          content: [
+            {
+              type: 'tableRow',
+              content: [cell('SOP / Procedure'), para('Refinery SOP Rev.0'), para('✅ Complete')],
+            },
+          ],
+        },
+      ],
+    };
+    const fixed = repairTableRows(doc) as typeof doc;
+    const row = (fixed.content[0] as { content: Array<{ type: string; content: unknown[] }> })
+      .content[0] as {
+      content: Array<{ type: string; content: Array<{ type: string }> }>;
+    };
+    // All three children are now cells (the intended 3-column row).
+    expect(row.content.map((c) => c.type)).toEqual(['tableCell', 'tableCell', 'tableCell']);
+    // The wrapped cells hold the original paragraph as their block content.
+    expect(row.content[1]?.content[0]?.type).toBe('paragraph');
+  });
+
+  it('leaves a valid table untouched (same reference)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'table', content: [{ type: 'tableRow', content: [cell('A'), cell('B')] }] },
+      ],
+    };
+    expect(repairTableRows(doc)).toBe(doc);
+  });
+
+  it('repairs a table nested inside a column', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'columnList',
+          content: [
+            {
+              type: 'column',
+              content: [
+                { type: 'table', content: [{ type: 'tableRow', content: [cell('X'), para('Y')] }] },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const fixed = repairTableRows(doc) as typeof doc;
+    const row = (fixed.content[0] as any).content[0].content[0].content[0] as {
+      content: Array<{ type: string }>;
+    };
+    expect(row.content.map((c) => c.type)).toEqual(['tableCell', 'tableCell']);
+  });
+});

package/src/block-ids.ts

@@ -0,0 +1,242 @@
+/**
+ * Block-id injection for ProseMirror docs (Phase 2b — block-addressed
+ * editing). Walks a doc tree and adds `attrs.id` (a UUID) to every block
+ * node that doesn't already have one, AND re-mints the id of any block
+ * that repeats an id already seen earlier in the same doc (first
+ * occurrence in document order keeps it). Everything else is untouched.
+ * Pure, idempotent, no DB.
+ *
+ * Why the dedupe: a duplicated id makes every later occurrence
+ * unaddressable — findBlock resolves to the first match, so block tools
+ * silently edit the wrong block (refinery-SOP incident, 2026-07-06:
+ * four step paragraphs in one section shared one id). The editor used
+ * to copy ids on split/paste (fixed in page-editor/block-id.ts), and any
+ * doc corrupted that way self-heals here on the next read or save.
+ *
+ * Why this exists: pages today are addressable only by position in the
+ * tree ("the 3rd paragraph"). Position breaks on every insert/delete and
+ * is brittle when an agent emits edits. Stable per-block ids give us
+ * "edit block <id>" semantics that survive concurrent changes.
+ *
+ * The injection runs in three places:
+ *  - `markdownToDoc`     — every freshly-generated doc gets ids at parse
+ *  - `getPage`           — legacy docs (no ids) get them on read (lazy
+ *                          backfill, no DB write — saveDraft / commitPage
+ *                          persist them on the next user action)
+ *  - `saveDraft` / `commitPage` — guarantees the stored doc carries ids
+ *
+ * The TipTap editor side is in `apps/web/components/page-editor/block-id.ts`
+ * — a global attribute extension that PRESERVES the `id` on parse/serialize
+ * so user edits don't strip ids the agent placed.
+ *
+ * Block coverage — every node type that's editorially meaningful as a unit:
+ * paragraph, heading, blockquote, codeBlock, horizontalRule, callout, aside,
+ * columnList, column, bulletList, orderedList, taskList, listItem, taskItem,
+ * table, tableRow, tableCell, tableHeader, blockMath, image, pageImage,
+ * fileEmbed, childPage. Inline text/marks + inlineMath stay un-id'd (they're not
+ * addressable units; the model edits their containing block instead).
+ */
+
+const BLOCK_TYPES = new Set([
+  // Standard structural
+  'paragraph',
+  'heading',
+  'blockquote',
+  'codeBlock',
+  'horizontalRule',
+  // Lists
+  'bulletList',
+  'orderedList',
+  'taskList',
+  'listItem',
+  'taskItem',
+  // Tables
+  'table',
+  'tableRow',
+  'tableCell',
+  'tableHeader',
+  // Mantle custom blocks
+  'callout',
+  'aside',
+  'columnList',
+  'column',
+  // Atoms still worth addressing (the agent might want to swap an image)
+  'image',
+  'pageImage',
+  'fileEmbed',
+  'blockMath',
+  'diagram',
+  // Sub-page link card (Phase 4a) — addressable so block tools can move/remove it
+  'childPage',
+]);
+
+type AnyNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  content?: AnyNode[];
+  text?: string;
+  marks?: Array<{ type: string; attrs?: Record<string, unknown> }>;
+};
+
+function newId(): string {
+  // crypto.randomUUID is in Node 19+ and modern browsers — both surfaces
+  // we run on. Falls back to a Math.random hex string for older runtimes
+  // (vitest in legacy modes, hypothetically) so a missing API never throws.
+  try {
+    return globalThis.crypto?.randomUUID?.() ?? fallbackId();
+  } catch {
+    return fallbackId();
+  }
+}
+
+function fallbackId(): string {
+  const r = () =>
+    Math.floor(Math.random() * 0xffffffff)
+      .toString(16)
+      .padStart(8, '0');
+  return `${r()}-${r().slice(0, 4)}-4${r().slice(1, 4)}-${r().slice(0, 4)}-${r()}${r().slice(0, 4)}`;
+}
+
+/**
+ * Walk a ProseMirror JSON node, returning a new tree with `attrs.id` set
+ * on every block-type node that's missing one, and a FRESH id on every
+ * block whose id duplicates an earlier block's (pre-order — the first
+ * occurrence keeps the id, which is the block findBlock already resolves
+ * to, so existing tool addresses stay valid). Unique existing ids are
+ * kept as-is. Non-block nodes (text, inline math, marks) are unchanged.
+ *
+ * Returns the SAME reference when nothing changes (no allocations), so
+ * call sites can skip a write when ids were already present.
+ */
+export function ensureBlockIds<T extends Record<string, unknown>>(doc: T): T {
+  const result = walk(doc as AnyNode, new Set<string>());
+  return result as unknown as T;
+}
+
+function walk(node: AnyNode, seen: Set<string>): AnyNode {
+  if (!node || typeof node !== 'object') return node;
+
+  let next: AnyNode = node;
+  const isBlock = node.type !== undefined && BLOCK_TYPES.has(node.type);
+  const existingId =
+    isBlock && node.attrs && typeof node.attrs.id === 'string' && node.attrs.id
+      ? node.attrs.id
+      : null;
+  // Mint when the id is missing OR already claimed by an earlier block.
+  const needsId = isBlock && (existingId === null || seen.has(existingId));
+
+  if (needsId) {
+    const id = newId();
+    seen.add(id);
+    next = {
+      ...node,
+      attrs: { ...(node.attrs ?? {}), id },
+    };
+  } else if (existingId !== null) {
+    seen.add(existingId);
+  }
+
+  if (Array.isArray(node.content) && node.content.length > 0) {
+    let childrenChanged = false;
+    const nextContent: AnyNode[] = new Array(node.content.length);
+    for (let i = 0; i < node.content.length; i++) {
+      const w = walk(node.content[i]!, seen);
+      nextContent[i] = w;
+      if (w !== node.content[i]) childrenChanged = true;
+    }
+    if (childrenChanged) {
+      next = { ...next, content: nextContent };
+    }
+  }
+
+  return next;
+}
+
+/**
+ * Repair invalid table structure so a doc stays renderable. ProseMirror's
+ * `tableRow` content model is `(tableCell | tableHeader)+`; an agent block
+ * edit (or any programmatic write) can drop a cell's wrapper, leaving a bare
+ * `paragraph` (or other block) as a DIRECT row child. That doc is schema-
+ * invalid, so the editor throws `RangeError: Invalid content for node
+ * tableRow` the instant it loads — white-screening the whole page. Wrap any
+ * stray non-cell child back into a `tableCell` (restoring the intended
+ * column). Recurses, so nested tables (inside columns / callouts) are fixed
+ * too. Idempotent; returns the SAME reference when nothing needed fixing, so
+ * the getPage read-path no-op + lazy-persist optimisation still holds.
+ */
+export function repairTableRows<T extends Record<string, unknown>>(doc: T): T {
+  return repairWalk(doc as AnyNode) as unknown as T;
+}
+
+const CELL_TYPES = new Set(['tableCell', 'tableHeader']);
+
+/** Wrap a stray row child in a `tableCell`. A cell needs block content, so a
+ *  bare inline/text node gets a `paragraph` wrapper first. */
+function wrapInCell(child: AnyNode): AnyNode {
+  const inner =
+    child && typeof child.type === 'string' && child.type !== 'text'
+      ? child
+      : { type: 'paragraph', attrs: { id: newId() }, content: child ? [child] : [] };
+  return { type: 'tableCell', attrs: { id: newId() }, content: [inner] };
+}
+
+function repairWalk(node: AnyNode): AnyNode {
+  if (
+    !node ||
+    typeof node !== 'object' ||
+    !Array.isArray(node.content) ||
+    node.content.length === 0
+  ) {
+    return node;
+  }
+  // Recurse first so deeply-nested tables get repaired as well.
+  let changed = false;
+  const walked: AnyNode[] = new Array(node.content.length);
+  for (let i = 0; i < node.content.length; i++) {
+    const w = repairWalk(node.content[i]!);
+    walked[i] = w;
+    if (w !== node.content[i]) changed = true;
+  }
+  let content = walked;
+  if (node.type === 'tableRow' && walked.some((c) => !c || !CELL_TYPES.has(c.type ?? ''))) {
+    content = walked.map((c) => (c && CELL_TYPES.has(c.type ?? '') ? c : wrapInCell(c)));
+    changed = true;
+  }
+  return changed ? { ...node, content } : node;
+}
+
+/**
+ * Check whether a doc has a UNIQUE id on every block — handy for tests +
+ * for the lazy-backfill paths that want to skip the rewrite when there's
+ * nothing to do. Duplicated ids count as "not ok" (they'd be re-minted by
+ * ensureBlockIds), matching what that pass would change. Walks the whole
+ * tree; O(N) in nodes.
+ */
+export function allBlocksHaveIds(doc: Record<string, unknown>): boolean {
+  return checkAll(doc as AnyNode, new Set<string>());
+}
+
+function checkAll(node: AnyNode, seen: Set<string>): boolean {
+  if (!node || typeof node !== 'object') return true;
+  if (node.type && BLOCK_TYPES.has(node.type)) {
+    if (!node.attrs || typeof node.attrs.id !== 'string' || !node.attrs.id) return false;
+    if (seen.has(node.attrs.id)) return false;
+    seen.add(node.attrs.id);
+  }
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      if (!checkAll(child, seen)) return false;
+    }
+  }
+  return true;
+}
+
+/** Exported for the TipTap-side extension and any other consumer. */
+export const BLOCK_NODE_TYPES = BLOCK_TYPES;
+
+/** Mint a fresh block id outside a full ensureBlockIds pass, for helpers
+ *  that build a container node in code (wrapBlocks) and must know its id
+ *  BEFORE the doc is saved, so tool output can report it for chaining. */
+export function mintBlockId(): string {
+  return newId();
+}