@crossworks/content-core 0.230.43

package/src/onboarding-questions.ts

@@ -0,0 +1,90 @@
+/**
+ * The first-run "what is this brain for" capture.
+ *
+ * Browser-safe leaf (NO `@mantle/db` import) so the onboarding wizard client can
+ * render the archetypes and the server action can validate the chosen key from
+ * the same source. The chosen archetype + a free-text description are persisted
+ * as profile preferences (`purposeArchetype` + `purpose`, see
+ * profile-preferences.ts) — first-class, settings-editable, and the seam a later
+ * phase can branch provisioning on. The purpose then feeds the always-on
+ * identity block (`identity-context.ts`) as a "# Purpose of this brain" section,
+ * so every agent knows the brain's mission from turn one.
+ *
+ * This replaced the old multi-question personal interview: a brain is now as
+ * often a specialist (data/RBI analytics, robotics, …) as it is a personal one,
+ * so we capture the brain's PURPOSE rather than the operator's life story. The
+ * passive `seed-get-to-know-user` heartbeat still harvests personal facts during
+ * normal chat for the brains where that matters.
+ */
+
+/** A brain "speciality" the operator picks at first run. Purely descriptive in
+ *  this phase (persisted + injected); a later phase can map a key to a
+ *  provisioning profile (which specialists/tool-groups to emphasise). */
+export type PurposeArchetype = {
+  /** Stable key — persisted as `purposeArchetype`; never shown to the user. */
+  key: string;
+  /** Short label shown in the picker + the identity block's "Speciality:" line. */
+  label: string;
+  /** One-line description of what this kind of brain is for. */
+  blurb: string;
+};
+
+/**
+ * The archetype set. `personal` leads (the most common starting point); `custom`
+ * trails as the description-only escape hatch. Order is the display order.
+ */
+export const PURPOSE_ARCHETYPES: PurposeArchetype[] = [
+  {
+    key: 'personal',
+    label: 'Personal brain',
+    blurb: 'A second brain for your life — notes, journal, tasks, people, and memory.',
+  },
+  {
+    key: 'analytics',
+    label: 'Data / RBI analytics',
+    blurb: 'A specialist for analysing data, documents, and reports (RBI and similar).',
+  },
+  {
+    key: 'research',
+    label: 'Research',
+    blurb: 'Gathering, reading, and synthesising sources into findings.',
+  },
+  {
+    key: 'robotics',
+    label: 'Robotics',
+    blurb: 'Sensing, control, and operational data for a robot or device.',
+  },
+  {
+    key: 'team',
+    label: 'Team / org knowledge',
+    blurb: 'Shared knowledge for a team — docs, decisions, and context in one place.',
+  },
+  {
+    key: 'custom',
+    label: 'Something else',
+    blurb: 'Describe it yourself below.',
+  },
+];
+
+export const PURPOSE_ARCHETYPE_KEYS: readonly string[] = PURPOSE_ARCHETYPES.map((a) => a.key);
+
+/** Narrow an unknown value to a known archetype key. */
+export function isPurposeArchetype(key: unknown): boolean {
+  return typeof key === 'string' && PURPOSE_ARCHETYPE_KEYS.includes(key);
+}
+
+/** Archetype key → human label, tolerant of unknown values (returns null so the
+ *  identity block can simply omit the "Speciality:" line). */
+export function purposeArchetypeLabel(key: string | null | undefined): string | null {
+  if (!key) return null;
+  return PURPOSE_ARCHETYPES.find((a) => a.key === key)?.label ?? null;
+}
+
+/** Derive a short display name (first name) from a name answer. Falls back to the
+ *  whole trimmed string when there's no whitespace. Kept from the old interview —
+ *  the optional "Your name" field on the welcome step still uses it. */
+export function deriveDisplayName(fullName: string): string {
+  const flat = (fullName ?? '').replace(/\s+/g, ' ').trim();
+  if (!flat) return '';
+  return flat.split(' ')[0] ?? flat;
+}

package/src/page-diff.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { computeDiffOverlay } from './page-diff';
+
+const p = (id: string, text: string) => ({
+  type: 'paragraph',
+  attrs: { id },
+  content: [{ type: 'text', text }],
+});
+const doc = (content: unknown[]) => ({ type: 'doc', content });
+
+describe('computeDiffOverlay', () => {
+  it('flags added blocks (top-most) and counts them', () => {
+    const committed = doc([p('a', 'one')]);
+    const draft = doc([p('a', 'one'), p('b', 'two')]);
+    const o = computeDiffOverlay(committed, draft);
+    expect(o.addedIds).toEqual(['b']);
+    expect(o.changedIds).toEqual([]);
+    expect(o.removed).toEqual([]);
+    expect(o.counts).toEqual({ added: 1, changed: 0, removed: 0 });
+  });
+
+  it('flags changed blocks', () => {
+    const committed = doc([p('a', 'one'), p('b', 'two')]);
+    const draft = doc([p('a', 'one EDITED'), p('b', 'two')]);
+    const o = computeDiffOverlay(committed, draft);
+    expect(o.changedIds).toEqual(['a']);
+    expect(o.counts.changed).toBe(1);
+  });
+
+  it('emits a removed ghost anchored after the previous surviving block', () => {
+    const committed = doc([p('a', 'keep'), p('b', 'goner'), p('c', 'tail')]);
+    const draft = doc([p('a', 'keep'), p('c', 'tail')]);
+    const o = computeDiffOverlay(committed, draft);
+    expect(o.removed).toHaveLength(1);
+    expect(o.removed[0]).toMatchObject({ id: 'b', kind: 'paragraph', text: 'goner', afterId: 'a' });
+    expect(o.counts.removed).toBe(1);
+  });
+
+  it('anchors a removed first block at the top (afterId null)', () => {
+    const committed = doc([p('a', 'first'), p('b', 'second')]);
+    const draft = doc([p('b', 'second')]);
+    const o = computeDiffOverlay(committed, draft);
+    expect(o.removed[0]).toMatchObject({ id: 'a', afterId: null });
+  });
+
+  it('borders the DEEPEST changed block, not its unchanged container shell', () => {
+    const callout = (id: string, childId: string, text: string) => ({
+      type: 'callout',
+      attrs: { id, variant: 'info' },
+      content: [p(childId, text)],
+    });
+    const committed = doc([callout('c1', 'p1', 'inner')]);
+    const draft = doc([callout('c1', 'p1', 'inner CHANGED')]);
+    const o = computeDiffOverlay(committed, draft);
+    // both c1 (its JSON changed because a child changed) and p1 are "changed",
+    // but only the deepest (p1) gets the border.
+    expect(o.changedIds).toEqual(['p1']);
+  });
+
+  it('borders an added subtree once (top-most), not every new child', () => {
+    const callout = (id: string, childId: string) => ({
+      type: 'callout',
+      attrs: { id, variant: 'info' },
+      content: [p(childId, 'x')],
+    });
+    const committed = doc([p('a', 'one')]);
+    const draft = doc([p('a', 'one'), callout('c1', 'p1')]);
+    const o = computeDiffOverlay(committed, draft);
+    expect(o.addedIds).toEqual(['c1']); // not p1
+  });
+
+  it('is empty when docs match', () => {
+    const same = doc([p('a', 'one')]);
+    const o = computeDiffOverlay(same, structuredClone(same));
+    expect(o).toMatchObject({
+      addedIds: [],
+      changedIds: [],
+      removed: [],
+      counts: { added: 0, changed: 0, removed: 0 },
+    });
+  });
+});

package/src/page-diff.ts

@@ -0,0 +1,120 @@
+/**
+ * page-diff — the visual-diff overlay model for the page editor's review mode
+ * (Phase 3a Pass 2). Turns a (committed `doc`, working `draft`) pair into the
+ * exact sets the editor needs to paint:
+ *
+ *   - addedIds   — blocks the draft introduced, TOP-MOST only (an added callout
+ *                  is bordered once, not again on each of its new children).
+ *   - changedIds — blocks whose content differs, DEEPEST only (a changed inner
+ *                  paragraph is bordered, not its unchanged-shell container) and
+ *                  never inside an added subtree (already covered).
+ *   - removed    — TOP-LEVEL blocks the draft dropped, with the text to show in
+ *                  a "ghost" card and the draft block id to anchor it after
+ *                  (`afterId`, null = top of doc). Removed blocks aren't in the
+ *                  draft, so the editor can only show them as widget overlays —
+ *                  this is what makes a deletion visible at all.
+ *
+ * `counts` reflect EVERY change (added/changed/removed at any depth, straight
+ * from diffBlocks) so the legend is honest even though nested removals aren't
+ * drawn as ghosts.
+ *
+ * Pure + DB-free (built on diffBlocks). Recomputed client-side on every draft
+ * change, so the overlay always matches "what Commit will publish".
+ */
+
+import { diffBlocks } from './block-diff';
+
+type AnyNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  content?: AnyNode[];
+  text?: string;
+};
+
+export type RemovedGhost = {
+  id: string;
+  /** PM node type, e.g. 'paragraph' | 'heading' | 'callout'. */
+  kind: string;
+  /** Plain-text preview of the removed block (capped). */
+  text: string;
+  /** Draft block id to render the ghost after; null → top of document. */
+  afterId: string | null;
+};
+
+export type DiffOverlay = {
+  addedIds: string[];
+  changedIds: string[];
+  removed: RemovedGhost[];
+  counts: { added: number; changed: number; removed: number };
+};
+
+const TEXT_CAP = 400;
+
+/** Plain text of a node — descendant text nodes concatenated, trimmed + capped. */
+function nodeText(node: AnyNode): string {
+  let out = '';
+  const walk = (n: AnyNode) => {
+    if (out.length > TEXT_CAP) return;
+    if (typeof n.text === 'string') out += n.text;
+    for (const c of n.content ?? []) walk(c);
+  };
+  walk(node);
+  out = out.trim();
+  return out.length > TEXT_CAP ? `${out.slice(0, TEXT_CAP)}…` : out;
+}
+
+function collectIds(node: AnyNode, into: Set<string>): void {
+  const id = node.attrs?.id;
+  if (typeof id === 'string') into.add(id);
+  for (const c of node.content ?? []) collectIds(c, into);
+}
+
+export function computeDiffOverlay(
+  committed: Record<string, unknown>,
+  draft: Record<string, unknown>,
+): DiffOverlay {
+  const d = diffBlocks(committed, draft);
+  const addedSet = new Set(d.added.map((b) => b.id));
+  const changedSet = new Set(d.changed.map((c) => c.to.id));
+
+  // Walk the DRAFT tree once: collect top-most added + deepest changed, so the
+  // borders land on the most specific block and never nest.
+  const addBorder = new Set<string>();
+  const changeBorder = new Set<string>();
+  const walk = (node: AnyNode, insideAdded: boolean): boolean => {
+    const id = typeof node.attrs?.id === 'string' ? (node.attrs.id as string) : null;
+    const isAdded = id != null && addedSet.has(id);
+    if (isAdded && !insideAdded && id) addBorder.add(id);
+    const nowInsideAdded = insideAdded || isAdded;
+    let descChanged = false;
+    for (const c of node.content ?? []) descChanged = walk(c, nowInsideAdded) || descChanged;
+    const isChanged = id != null && changedSet.has(id);
+    if (isChanged && !descChanged && !nowInsideAdded && id) changeBorder.add(id);
+    return isChanged || descChanged;
+  };
+  for (const top of (draft as AnyNode).content ?? []) walk(top, false);
+
+  // Top-level removals → ghost cards, anchored after the nearest surviving
+  // top-level block (by id) so they appear where they used to be.
+  const draftIds = new Set<string>();
+  collectIds(draft as AnyNode, draftIds);
+  const removed: RemovedGhost[] = [];
+  let lastSurviving: string | null = null;
+  for (const top of (committed as AnyNode).content ?? []) {
+    const id = typeof top.attrs?.id === 'string' ? (top.attrs.id as string) : null;
+    if (id && draftIds.has(id)) {
+      lastSurviving = id;
+      continue;
+    }
+    if (id) {
+      removed.push({ id, kind: top.type ?? 'block', text: nodeText(top), afterId: lastSurviving });
+    }
+  }
+
+  return {
+    addedIds: [...addBorder],
+    changedIds: [...changeBorder],
+    removed,
+    counts: { added: d.added.length, changed: d.changed.length, removed: d.removed.length },
+  };
+}

package/src/page-split.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { splitDocByHeading, extractSection, headingText } from './page-split';
+
+const h = (level: number, text: string, id?: string) => ({
+  type: 'heading',
+  attrs: id ? { level, id } : { level },
+  content: [{ type: 'text', text }],
+});
+const p = (text: string) => ({ type: 'paragraph', content: [{ type: 'text', text }] });
+const doc = (content: unknown[]) => ({ type: 'doc', content });
+
+describe('headingText', () => {
+  it('concatenates descendant text and trims', () => {
+    expect(
+      headingText({
+        type: 'heading',
+        content: [
+          { type: 'text', text: '🔥 Point ' },
+          { type: 'text', text: 'One ' },
+        ],
+      }),
+    ).toBe('🔥 Point One');
+  });
+});
+
+describe('splitDocByHeading', () => {
+  it('splits on the chosen level: heading → title, following blocks → body', () => {
+    const d = doc([h(2, 'Alpha'), p('a1'), p('a2'), h(2, 'Beta'), p('b1')]);
+    const { intro, sections } = splitDocByHeading(d, 2);
+    expect(intro).toEqual([]);
+    expect(sections).toHaveLength(2);
+    expect(sections[0]!.title).toBe('Alpha');
+    expect(
+      sections[0]!.blocks.map((b) => (b as { content?: { text: string }[] }).content?.[0]?.text),
+    ).toEqual(['a1', 'a2']);
+    expect(sections[1]!.title).toBe('Beta');
+    expect(sections[1]!.blocks).toHaveLength(1);
+  });
+
+  it('keeps pre-heading blocks as the intro', () => {
+    const d = doc([p('lead-in'), h(1, 'One'), p('x')]);
+    const { intro, sections } = splitDocByHeading(d, 1);
+    expect(intro.map((b) => (b as { content?: { text: string }[] }).content?.[0]?.text)).toEqual([
+      'lead-in',
+    ]);
+    expect(sections).toHaveLength(1);
+    expect(sections[0]!.title).toBe('One');
+  });
+
+  it('does NOT repeat the heading block in the section body (it becomes the title)', () => {
+    const d = doc([h(1, 'Title'), p('body')]);
+    const { sections } = splitDocByHeading(d, 1);
+    expect(sections[0]!.blocks.some((b) => (b as { type?: string }).type === 'heading')).toBe(
+      false,
+    );
+  });
+
+  it('only splits on the requested level — other-level headings stay in the body', () => {
+    const d = doc([h(1, 'Big'), p('x'), h(2, 'Small'), p('y')]);
+    const { sections } = splitDocByHeading(d, 1);
+    expect(sections).toHaveLength(1);
+    // the h2 + its paragraph ride along inside the h1 section, verbatim
+    expect(sections[0]!.blocks.map((b) => (b as { type?: string }).type)).toEqual([
+      'paragraph',
+      'heading',
+      'paragraph',
+    ]);
+  });
+
+  it('returns no sections when the level is absent (caller treats as no-op)', () => {
+    const d = doc([p('just text'), h(3, 'deep')]);
+    expect(splitDocByHeading(d, 1).sections).toEqual([]);
+    expect(splitDocByHeading(d, 2).sections).toEqual([]);
+  });
+
+  it('handles an empty section (heading with no following blocks)', () => {
+    const d = doc([h(2, 'Lonely')]);
+    const { sections } = splitDocByHeading(d, 2);
+    expect(sections).toHaveLength(1);
+    expect(sections[0]!.blocks).toEqual([]);
+  });
+
+  it('preserves block object references (byte-faithful redistribution)', () => {
+    const body = p('keep me');
+    const d = doc([h(1, 'S'), body]);
+    const { sections } = splitDocByHeading(d, 1);
+    expect(sections[0]!.blocks[0]).toBe(body); // same reference, not a copy
+  });
+});
+
+const txt = (b: unknown) => (b as { content?: { text: string }[] }).content?.[0]?.text;
+
+describe('extractSection', () => {
+  it('lifts a heading + its body, splitting before/after around it', () => {
+    const d = doc([
+      p('intro'),
+      h(2, 'Target', 'h1'),
+      p('b1'),
+      p('b2'),
+      h(2, 'Next', 'h2'),
+      p('n1'),
+    ]);
+    const r = extractSection(d, 'h1')!;
+    expect(r.title).toBe('Target');
+    expect(r.childBlocks.map(txt)).toEqual(['b1', 'b2']); // heading not repeated
+    expect(r.before.map(txt)).toEqual(['intro']);
+    expect(r.after.map((b) => (b as { type: string }).type)).toEqual(['heading', 'paragraph']);
+  });
+
+  it('section ends at the next EQUAL-or-higher heading (h1 ends an h2 section)', () => {
+    const d = doc([h(2, 'Sec', 's'), p('x'), h(3, 'sub'), p('y'), h(1, 'Top'), p('z')]);
+    const r = extractSection(d, 's')!;
+    // the nested h3 + its paragraph ride along; the h1 is the boundary
+    expect(r.childBlocks.map((b) => (b as { type: string }).type)).toEqual([
+      'paragraph',
+      'heading',
+      'paragraph',
+    ]);
+    expect(r.after.map((b) => (b as { type: string }).type)).toEqual(['heading', 'paragraph']);
+  });
+
+  it('runs to end of doc when no boundary heading follows', () => {
+    const d = doc([h(1, 'Only', 'o'), p('a'), p('b')]);
+    const r = extractSection(d, 'o')!;
+    expect(r.childBlocks.map(txt)).toEqual(['a', 'b']);
+    expect(r.after).toEqual([]);
+  });
+
+  it('returns null for an unknown id or a non-heading block', () => {
+    const para = { ...p('plain'), attrs: { id: 'pid' } };
+    const d = doc([para, h(1, 'H', 'hid')]);
+    expect(extractSection(d, 'missing')).toBeNull();
+    expect(extractSection(d, 'pid')).toBeNull(); // id exists but isn't a heading
+  });
+
+  it('preserves block object references (byte-faithful)', () => {
+    const body = p('keep me');
+    const d = doc([h(1, 'S', 'sid'), body]);
+    expect(extractSection(d, 'sid')!.childBlocks[0]).toBe(body);
+  });
+});

package/src/page-split.ts

@@ -0,0 +1,128 @@
+/**
+ * page-split — the pure, deterministic core of `page_split` (Phase 4b). Given a
+ * ProseMirror page document, partition it into an intro plus one section per
+ * top-level heading of a chosen level. The heading's text becomes the section
+ * title; the blocks under it (until the next heading of that level) become the
+ * section body — the heading block itself is NOT repeated in the body, since it
+ * lives on as the child page's title.
+ *
+ * Byte-faithful: every non-heading block is carried through verbatim (same
+ * object references), so the split redistributes content without rewriting it.
+ * DB-free + side-effect-free, so it's unit-testable and safe to call anywhere;
+ * `splitPage` in pages.ts wraps it with the page creation + draft write.
+ */
+
+type PMNode = {
+  type?: string;
+  attrs?: Record<string, unknown> | null;
+  content?: PMNode[];
+  text?: string;
+};
+
+/** Heading level to split on: h1 (top-level sections) or h2 (subsections). */
+export type SplitLevel = 1 | 2;
+
+export type SplitSection = {
+  /** Plain-text heading, used as the child page title. */
+  title: string;
+  /** The blocks under the heading (verbatim), the child page body. */
+  blocks: PMNode[];
+};
+
+export type SplitResult = {
+  /** Blocks before the first split heading — kept on the parent if requested. */
+  intro: PMNode[];
+  sections: SplitSection[];
+};
+
+/** Plain text of a node — concatenate descendant text nodes, trimmed. */
+export function headingText(node: PMNode): string {
+  let out = '';
+  const walk = (n: PMNode) => {
+    if (typeof n.text === 'string') out += n.text;
+    for (const c of n.content ?? []) walk(c);
+  };
+  walk(node);
+  return out.trim();
+}
+
+function isSplitHeading(n: PMNode, level: SplitLevel): boolean {
+  return n.type === 'heading' && Number(n.attrs?.level) === level;
+}
+
+export type ExtractResult = {
+  /** Plain-text heading → the child page title. */
+  title: string;
+  /** The section body (blocks under the heading, until the boundary) — verbatim. */
+  childBlocks: PMNode[];
+  /** Top-level blocks before the heading (kept on the parent, verbatim). */
+  before: PMNode[];
+  /** Top-level blocks from the boundary onward (kept on the parent, verbatim). */
+  after: PMNode[];
+};
+
+/**
+ * Promote one section to a sub-page (Phase 4c). Locate the TOP-LEVEL heading
+ * with the given block id; its section runs until the next heading of EQUAL OR
+ * HIGHER level (i.e. level ≤ the heading's — an h2 section ends at the next h2
+ * or h1), or end of doc. The heading text becomes the child title; the blocks
+ * under it become the child body (the heading itself is not repeated). Returns
+ * the surrounding blocks so the caller can splice a `childPage` card into the
+ * parent where the section was.
+ *
+ * Returns null when the id doesn't resolve to a top-level heading (nested
+ * headings inside callouts/columns aren't promotable this way).
+ */
+export function extractSection(
+  doc: Record<string, unknown>,
+  headingId: string,
+): ExtractResult | null {
+  const blocks = ((doc as PMNode).content ?? []) as PMNode[];
+  const hi = blocks.findIndex(
+    (b) => b.type === 'heading' && (b.attrs?.id as string | undefined) === headingId,
+  );
+  if (hi === -1) return null;
+
+  const level = Number(blocks[hi]!.attrs?.level) || 1;
+  let end = blocks.length;
+  for (let i = hi + 1; i < blocks.length; i++) {
+    const b = blocks[i]!;
+    if (b.type === 'heading' && (Number(b.attrs?.level) || 1) <= level) {
+      end = i;
+      break;
+    }
+  }
+
+  return {
+    title: headingText(blocks[hi]!) || 'Untitled',
+    childBlocks: blocks.slice(hi + 1, end),
+    before: blocks.slice(0, hi),
+    after: blocks.slice(end),
+  };
+}
+
+/**
+ * Partition a doc into an intro + one section per top-level heading of `level`.
+ * Only TOP-LEVEL blocks are inspected (nested headings inside callouts/columns
+ * stay with their container). A section runs from its heading until the next
+ * heading of the same level (or end of doc).
+ */
+export function splitDocByHeading(doc: Record<string, unknown>, level: SplitLevel): SplitResult {
+  const blocks = ((doc as PMNode).content ?? []) as PMNode[];
+  const intro: PMNode[] = [];
+  const sections: SplitSection[] = [];
+  let current: SplitSection | null = null;
+
+  for (const b of blocks) {
+    if (isSplitHeading(b, level)) {
+      current = { title: headingText(b) || 'Untitled', blocks: [] };
+      sections.push(current);
+    } else if (current) {
+      current.blocks.push(b);
+    } else {
+      intro.push(b);
+    }
+  }
+
+  return { intro, sections };
+}

package/src/page-toc.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { buildPageToc } from './page-toc';
+
+const h = (level: number, id: string, text: string) => ({
+  type: 'heading',
+  attrs: { id, level },
+  content: [{ type: 'text', text }],
+});
+const p = (text: string) => ({ type: 'paragraph', content: [{ type: 'text', text }] });
+const child = (id: string, title: string) => ({ type: 'childPage', attrs: { id, title } });
+const doc = (content: unknown[]) => ({ type: 'doc', content });
+
+describe('buildPageToc', () => {
+  it('returns empty for nullish / non-doc input', () => {
+    expect(buildPageToc(null)).toEqual([]);
+    expect(buildPageToc({})).toEqual([]);
+  });
+
+  it('extracts headings in order with depth = level - 1', () => {
+    const toc = buildPageToc(
+      doc([h(1, 'a', 'Intro'), p('body'), h(2, 'b', 'Details'), h(3, 'c', 'Fine print')]),
+    );
+    expect(toc).toEqual([
+      { id: 'a', kind: 'heading', level: 1, depth: 0, label: 'Intro' },
+      { id: 'b', kind: 'heading', level: 2, depth: 1, label: 'Details' },
+      { id: 'c', kind: 'heading', level: 3, depth: 2, label: 'Fine print' },
+    ]);
+  });
+
+  it('nests a sub-page one level deeper than its enclosing heading section', () => {
+    const toc = buildPageToc(doc([h(2, 'b', 'Section'), child('p1', 'Sub doc')]));
+    const sub = toc.find((e) => e.kind === 'page')!;
+    expect(sub).toEqual({ id: 'p1', kind: 'page', level: 2, depth: 2, label: 'Sub doc' });
+  });
+
+  it('places a sub-page before any heading at depth 0', () => {
+    const toc = buildPageToc(doc([child('p1', 'Top sub')]));
+    expect(toc[0]).toEqual({ id: 'p1', kind: 'page', level: 0, depth: 0, label: 'Top sub' });
+  });
+
+  it('skips headings / sub-pages without a block id (cannot be jump targets)', () => {
+    const toc = buildPageToc(
+      doc([{ type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'No id' }] }]),
+    );
+    expect(toc).toEqual([]);
+  });
+
+  it('falls back to placeholder labels for empty headings / untitled pages', () => {
+    const toc = buildPageToc(
+      doc([
+        { type: 'heading', attrs: { id: 'a', level: 1 } },
+        { type: 'childPage', attrs: { id: 'p1' } },
+      ]),
+    );
+    expect(toc[0]!.label).toBe('Untitled heading');
+    expect(toc[1]!.label).toBe('Untitled page');
+  });
+});