@cat-factory/app 0.6.0 → 0.7.2

package/app/utils/agentOutput.spec.ts

@@ -1,128 +1,128 @@
-import { describe, it, expect } from 'vitest'
-import { parseOutputOutline, sliceSource } from '~/utils/agentOutput'
-
-describe('parseOutputOutline', () => {
-  it('splits on headings and builds a ToC', () => {
-    const out = parseOutputOutline(
-      ['# Overview', 'intro text', '', '## Findings', '- a', '- b'].join('\n'),
-    )
-    expect(out.hasToc).toBe(true)
-    expect(out.minDepth).toBe(1)
-    expect(out.sections.map((s) => s.title)).toEqual(['Overview', 'Findings'])
-    expect(out.sections[0]!.depth).toBe(1)
-    expect(out.sections[1]!.depth).toBe(2)
-    const findings = out.sections[1]!.bodyHtml
-    // top-level blocks now carry data-src-* anchors, so match the open tag loosely
-    expect(findings).toContain('<ul')
-    expect(findings).toContain('<li>a</li>')
-  })
-
-  it('keeps text before the first heading as an untitled preamble (no ToC entry)', () => {
-    const out = parseOutputOutline('loose intro\n\n## Section')
-    expect(out.sections[0]!.title).toBe('')
-    expect(out.sections[0]!.depth).toBe(0)
-    expect(out.sections[0]!.bodyHtml).toContain('loose intro')
-    expect(out.sections.filter((s) => s.depth > 0)).toHaveLength(1)
-  })
-
-  it('reports no ToC when there are no headings', () => {
-    const out = parseOutputOutline('just a paragraph of prose')
-    expect(out.hasToc).toBe(false)
-    expect(out.sections).toHaveLength(1)
-  })
-
-  it('gives every section a unique id even with duplicate titles', () => {
-    const out = parseOutputOutline('## Risks\na\n## Risks\nb')
-    const ids = out.sections.map((s) => s.id)
-    expect(new Set(ids).size).toBe(ids.length)
-  })
-
-  it('captures fenced code verbatim without treating its lines as headings', () => {
-    const out = parseOutputOutline('## Code\n```ts\nconst x = 1\n# not a heading\n```')
-    expect(out.sections).toHaveLength(1)
-    const body = out.sections[0]!.bodyHtml
-    expect(body).toContain('<pre>')
-    expect(body).toContain('# not a heading')
-  })
-
-  it('escapes raw HTML rather than injecting it (html: false)', () => {
-    const out = parseOutputOutline('## S\n<img src=x onerror=alert(1)>')
-    const body = out.sections[0]!.bodyHtml
-    expect(body).not.toContain('<img')
-    expect(body).toContain('&lt;img')
-  })
-
-  it('renders inline marks and decorates links to open safely in a new tab', () => {
-    const out = parseOutputOutline('## S\nsee **bold** and [site](https://example.com)')
-    const body = out.sections[0]!.bodyHtml
-    expect(body).toContain('<strong>bold</strong>')
-    expect(body).toContain('href="https://example.com"')
-    expect(body).toContain('target="_blank"')
-    expect(body).toContain('rel="noopener noreferrer"')
-  })
-
-  it('does not create a link for javascript: URLs (markdown-it validateLink)', () => {
-    // validateLink rejects the scheme, so it stays inert plain text — never an <a>.
-    const out = parseOutputOutline('## S\n[x](javascript:alert(1))')
-    const body = out.sections[0]!.bodyHtml
-    expect(body).not.toContain('<a ')
-    expect(body).not.toContain('href')
-  })
-
-  it('tolerates empty / nullish input', () => {
-    expect(parseOutputOutline('').sections).toHaveLength(0)
-    expect(parseOutputOutline(undefined as unknown as string).sections).toHaveLength(0)
-  })
-})
-
-describe('sliceSource', () => {
-  it('returns the verbatim line range (0-based, end-exclusive)', () => {
-    const text = ['line0', 'line1', 'line2', 'line3'].join('\n')
-    expect(sliceSource(text, 1, 3)).toBe('line1\nline2')
-    expect(sliceSource(text, 0, 1)).toBe('line0')
-  })
-
-  it('tolerates nullish input', () => {
-    expect(sliceSource(undefined as unknown as string, 0, 1)).toBe('')
-  })
-})
-
-describe('source-line stamping (approval-mode block anchors)', () => {
-  // Find a rendered block by its text and round-trip its `data-src-*` range back
-  // through `sliceSource` against the ORIGINAL output — this is the contract the
-  // approval reader relies on to quote the agent's own markdown back to it.
-  const blockFor = (output: string, contains: string) => {
-    const { sections } = parseOutputOutline(output)
-    const host = document.createElement('div')
-    host.innerHTML = sections.map((s) => s.bodyHtml).join('\n')
-    const el = Array.from(host.querySelectorAll('[data-src-start]')).find((e) =>
-      (e.textContent ?? '').includes(contains),
-    )
-    if (!el) throw new Error(`no source-stamped block containing "${contains}"`)
-    return {
-      start: Number(el.getAttribute('data-src-start')),
-      end: Number(el.getAttribute('data-src-end')),
-    }
-  }
-
-  it('round-trips a paragraph block to its original source lines', () => {
-    const output = ['## Summary', '', 'First paragraph.', '', 'Second paragraph here.'].join('\n')
-    const { start, end } = blockFor(output, 'First paragraph.')
-    expect(sliceSource(output, start, end)).toBe('First paragraph.')
-  })
-
-  it('round-trips a multi-line fenced code block verbatim', () => {
-    const code = ['```ts', 'const x = 1', 'const y = 2', '```'].join('\n')
-    const output = ['## Code', '', code].join('\n')
-    const { start, end } = blockFor(output, 'const x = 1')
-    expect(sliceSource(output, start, end)).toBe(code)
-  })
-
-  it('stamps top-level blocks only (a comment targets a whole block, not a nested item)', () => {
-    const output = ['Intro paragraph.', '', '- item one', '- item two'].join('\n')
-    const { start, end } = blockFor(output, 'item one')
-    // The whole list is the top-level block, so the slice spans both items.
-    expect(sliceSource(output, start, end)).toContain('- item one')
-    expect(sliceSource(output, start, end)).toContain('- item two')
-  })
-})
+import { describe, it, expect } from 'vitest'
+import { parseOutputOutline, sliceSource } from '~/utils/agentOutput'
+
+describe('parseOutputOutline', () => {
+  it('splits on headings and builds a ToC', () => {
+    const out = parseOutputOutline(
+      ['# Overview', 'intro text', '', '## Findings', '- a', '- b'].join('\n'),
+    )
+    expect(out.hasToc).toBe(true)
+    expect(out.minDepth).toBe(1)
+    expect(out.sections.map((s) => s.title)).toEqual(['Overview', 'Findings'])
+    expect(out.sections[0]!.depth).toBe(1)
+    expect(out.sections[1]!.depth).toBe(2)
+    const findings = out.sections[1]!.bodyHtml
+    // top-level blocks now carry data-src-* anchors, so match the open tag loosely
+    expect(findings).toContain('<ul')
+    expect(findings).toContain('<li>a</li>')
+  })
+
+  it('keeps text before the first heading as an untitled preamble (no ToC entry)', () => {
+    const out = parseOutputOutline('loose intro\n\n## Section')
+    expect(out.sections[0]!.title).toBe('')
+    expect(out.sections[0]!.depth).toBe(0)
+    expect(out.sections[0]!.bodyHtml).toContain('loose intro')
+    expect(out.sections.filter((s) => s.depth > 0)).toHaveLength(1)
+  })
+
+  it('reports no ToC when there are no headings', () => {
+    const out = parseOutputOutline('just a paragraph of prose')
+    expect(out.hasToc).toBe(false)
+    expect(out.sections).toHaveLength(1)
+  })
+
+  it('gives every section a unique id even with duplicate titles', () => {
+    const out = parseOutputOutline('## Risks\na\n## Risks\nb')
+    const ids = out.sections.map((s) => s.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('captures fenced code verbatim without treating its lines as headings', () => {
+    const out = parseOutputOutline('## Code\n```ts\nconst x = 1\n# not a heading\n```')
+    expect(out.sections).toHaveLength(1)
+    const body = out.sections[0]!.bodyHtml
+    expect(body).toContain('<pre>')
+    expect(body).toContain('# not a heading')
+  })
+
+  it('escapes raw HTML rather than injecting it (html: false)', () => {
+    const out = parseOutputOutline('## S\n<img src=x onerror=alert(1)>')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).not.toContain('<img')
+    expect(body).toContain('&lt;img')
+  })
+
+  it('renders inline marks and decorates links to open safely in a new tab', () => {
+    const out = parseOutputOutline('## S\nsee **bold** and [site](https://example.com)')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).toContain('<strong>bold</strong>')
+    expect(body).toContain('href="https://example.com"')
+    expect(body).toContain('target="_blank"')
+    expect(body).toContain('rel="noopener noreferrer"')
+  })
+
+  it('does not create a link for javascript: URLs (markdown-it validateLink)', () => {
+    // validateLink rejects the scheme, so it stays inert plain text — never an <a>.
+    const out = parseOutputOutline('## S\n[x](javascript:alert(1))')
+    const body = out.sections[0]!.bodyHtml
+    expect(body).not.toContain('<a ')
+    expect(body).not.toContain('href')
+  })
+
+  it('tolerates empty / nullish input', () => {
+    expect(parseOutputOutline('').sections).toHaveLength(0)
+    expect(parseOutputOutline(undefined as unknown as string).sections).toHaveLength(0)
+  })
+})
+
+describe('sliceSource', () => {
+  it('returns the verbatim line range (0-based, end-exclusive)', () => {
+    const text = ['line0', 'line1', 'line2', 'line3'].join('\n')
+    expect(sliceSource(text, 1, 3)).toBe('line1\nline2')
+    expect(sliceSource(text, 0, 1)).toBe('line0')
+  })
+
+  it('tolerates nullish input', () => {
+    expect(sliceSource(undefined as unknown as string, 0, 1)).toBe('')
+  })
+})
+
+describe('source-line stamping (approval-mode block anchors)', () => {
+  // Find a rendered block by its text and round-trip its `data-src-*` range back
+  // through `sliceSource` against the ORIGINAL output — this is the contract the
+  // approval reader relies on to quote the agent's own markdown back to it.
+  const blockFor = (output: string, contains: string) => {
+    const { sections } = parseOutputOutline(output)
+    const host = document.createElement('div')
+    host.innerHTML = sections.map((s) => s.bodyHtml).join('\n')
+    const el = Array.from(host.querySelectorAll('[data-src-start]')).find((e) =>
+      (e.textContent ?? '').includes(contains),
+    )
+    if (!el) throw new Error(`no source-stamped block containing "${contains}"`)
+    return {
+      start: Number(el.getAttribute('data-src-start')),
+      end: Number(el.getAttribute('data-src-end')),
+    }
+  }
+
+  it('round-trips a paragraph block to its original source lines', () => {
+    const output = ['## Summary', '', 'First paragraph.', '', 'Second paragraph here.'].join('\n')
+    const { start, end } = blockFor(output, 'First paragraph.')
+    expect(sliceSource(output, start, end)).toBe('First paragraph.')
+  })
+
+  it('round-trips a multi-line fenced code block verbatim', () => {
+    const code = ['```ts', 'const x = 1', 'const y = 2', '```'].join('\n')
+    const output = ['## Code', '', code].join('\n')
+    const { start, end } = blockFor(output, 'const x = 1')
+    expect(sliceSource(output, start, end)).toBe(code)
+  })
+
+  it('stamps top-level blocks only (a comment targets a whole block, not a nested item)', () => {
+    const output = ['Intro paragraph.', '', '- item one', '- item two'].join('\n')
+    const { start, end } = blockFor(output, 'item one')
+    // The whole list is the top-level block, so the slice spans both items.
+    expect(sliceSource(output, start, end)).toContain('- item one')
+    expect(sliceSource(output, start, end)).toContain('- item two')
+  })
+})

package/app/utils/agentOutput.ts

@@ -1,173 +1,173 @@
-// Turn an agent's prose output (markdown) into a heading-delimited outline so it
-// can be read in the dedicated reader overlay: a navigable table of contents on
-// one side, collapsible sections on the other.
-//
-// Markdown → HTML is done by `markdown-it` (a mature CommonMark parser) with
-// `html: false`, so it is secure by default: any raw HTML in the agent's output
-// is escaped rather than injected, and its `validateLink` blocks dangerous URL
-// schemes — no separate sanitizer needed for the LLM-generated text we feed it.
-// This module only adds the one thing markdown-it doesn't: SEGMENTATION — split
-// the rendered document at each heading into sections we can collapse
-// independently and link from a ToC. That split is done over the parsed DOM, so
-// it is independent of markdown-it's token internals.
-import MarkdownIt from 'markdown-it'
-
-/**
- * Stamp every TOP-LEVEL block element with its source line range
- * (`data-src-start`/`data-src-end`, 0-based, end-exclusive — straight from
- * markdown-it's `token.map`). The approval-mode reader uses these to let a human
- * comment on a specific block and quote that block's verbatim raw markdown back to
- * the agent on a "request changes" re-run. Only top-level blocks are tagged (depth
- * tracked over the flat token stream) so a comment targets a whole paragraph/list/
- * heading rather than a nested fragment.
- */
-function sourceLinePlugin(md: MarkdownIt): void {
-  md.core.ruler.push('source_lines', (state) => {
-    let depth = 0
-    for (const token of state.tokens) {
-      const atTopLevel = depth === 0
-      // Annotate a top-level block's opening token (nesting 1) or a self-contained
-      // block token (nesting 0, e.g. fence/hr/code_block/html_block).
-      if (atTopLevel && token.block && token.type !== 'inline' && token.map && token.nesting >= 0) {
-        token.attrSet('data-src-start', String(token.map[0]))
-        token.attrSet('data-src-end', String(token.map[1]))
-      }
-      if (token.nesting === 1) depth++
-      else if (token.nesting === -1) depth--
-    }
-    return true
-  })
-}
-
-/**
- * The verbatim raw-markdown source of a block, given the original output text and a
- * 0-based, end-exclusive line range (as captured from `data-src-start/end`).
- */
-export function sliceSource(output: string, start: number, end: number): string {
-  return (output ?? '').split('\n').slice(start, end).join('\n')
-}
-
-/** One heading-delimited section. `depth` 0 / empty `title` is the preamble that
- * precedes the first heading (rendered, but never shown in the ToC). */
-export interface OutputSection {
-  id: string
-  depth: number
-  /** Plain-text heading, for the ToC. */
-  title: string
-  /** Inline-rendered heading HTML (code/bold/… preserved), for the section header. */
-  titleHtml: string
-  /** HTML of everything under this heading up to the next one. */
-  bodyHtml: string
-}
-
-export interface OutputOutline {
-  sections: OutputSection[]
-  /** True once there is at least one real heading worth a ToC entry. */
-  hasToc: boolean
-  /** Shallowest heading depth present, so the ToC can indent relative to it. */
-  minDepth: number
-}
-
-const md = new MarkdownIt({
-  html: false, // secure by default: escape raw HTML rather than render it
-  linkify: true, // turn bare URLs into links
-  breaks: true, // single newlines → <br>, matching how agents lay out prose
-  typographer: true,
-}).use(sourceLinePlugin)
-
-const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6'])
-const LINK_CLASS = 'text-indigo-300 underline decoration-indigo-500/40 hover:text-indigo-200'
-
-function slugify(title: string, used: Set<string>): string {
-  const base =
-    title
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '') || 'section'
-  let slug = base
-  let n = 2
-  while (used.has(slug)) slug = `${base}-${n++}`
-  used.add(slug)
-  return slug
-}
-
-/** Make every link open safely in a new tab and pick up the reader's link style. */
-function decorateLinks(root: HTMLElement): void {
-  for (const a of Array.from(root.querySelectorAll('a'))) {
-    a.setAttribute('target', '_blank')
-    a.setAttribute('rel', 'noopener noreferrer')
-    a.setAttribute('class', LINK_CLASS)
-  }
-}
-
-/** Build the heading-based outline for an agent's prose output. */
-export function parseOutputOutline(text: string): OutputOutline {
-  const source = text ?? ''
-  if (!source.trim()) return { sections: [], hasToc: false, minDepth: 1 }
-
-  const html = md.render(source)
-
-  // No DOM (SSR / non-browser): fall back to one un-segmented section. The reader
-  // overlay is client-only, so this path is effectively dead outside any runtime
-  // without `document`.
-  if (typeof document === 'undefined') {
-    return {
-      sections: [{ id: 'overview', depth: 0, title: '', titleHtml: '', bodyHtml: html }],
-      hasToc: false,
-      minDepth: 1,
-    }
-  }
-
-  const root = document.createElement('div')
-  root.innerHTML = html
-  decorateLinks(root)
-
-  const used = new Set<string>()
-  const sections: OutputSection[] = []
-  let current: OutputSection | null = null
-  let body: HTMLElement | null = null
-
-  const flush = () => {
-    if (current && body) current.bodyHtml = body.innerHTML.trim()
-    if (current) sections.push(current)
-  }
-
-  for (const node of Array.from(root.childNodes)) {
-    const el = node.nodeType === 1 ? (node as HTMLElement) : null
-    if (el && HEADINGS.has(el.tagName)) {
-      flush()
-      const title = (el.textContent ?? '').trim()
-      current = {
-        id: slugify(title, used),
-        depth: Number(el.tagName[1]),
-        title,
-        titleHtml: el.innerHTML,
-        bodyHtml: '',
-      }
-      body = document.createElement('div')
-    } else {
-      if (!current) {
-        // Content before the first heading → untitled preamble section.
-        current = {
-          id: slugify('overview', used),
-          depth: 0,
-          title: '',
-          titleHtml: '',
-          bodyHtml: '',
-        }
-        body = document.createElement('div')
-      }
-      body!.appendChild(node.cloneNode(true))
-    }
-  }
-  flush()
-
-  // A preamble that turned out to hold nothing renderable is noise — drop it.
-  const cleaned = sections.filter((s) => s.title || s.bodyHtml)
-  const headed = cleaned.filter((s) => s.depth > 0)
-  return {
-    sections: cleaned,
-    hasToc: headed.length > 0,
-    minDepth: headed.length ? Math.min(...headed.map((s) => s.depth)) : 1,
-  }
-}
+// Turn an agent's prose output (markdown) into a heading-delimited outline so it
+// can be read in the dedicated reader overlay: a navigable table of contents on
+// one side, collapsible sections on the other.
+//
+// Markdown → HTML is done by `markdown-it` (a mature CommonMark parser) with
+// `html: false`, so it is secure by default: any raw HTML in the agent's output
+// is escaped rather than injected, and its `validateLink` blocks dangerous URL
+// schemes — no separate sanitizer needed for the LLM-generated text we feed it.
+// This module only adds the one thing markdown-it doesn't: SEGMENTATION — split
+// the rendered document at each heading into sections we can collapse
+// independently and link from a ToC. That split is done over the parsed DOM, so
+// it is independent of markdown-it's token internals.
+import MarkdownIt from 'markdown-it'
+
+/**
+ * Stamp every TOP-LEVEL block element with its source line range
+ * (`data-src-start`/`data-src-end`, 0-based, end-exclusive — straight from
+ * markdown-it's `token.map`). The approval-mode reader uses these to let a human
+ * comment on a specific block and quote that block's verbatim raw markdown back to
+ * the agent on a "request changes" re-run. Only top-level blocks are tagged (depth
+ * tracked over the flat token stream) so a comment targets a whole paragraph/list/
+ * heading rather than a nested fragment.
+ */
+function sourceLinePlugin(md: MarkdownIt): void {
+  md.core.ruler.push('source_lines', (state) => {
+    let depth = 0
+    for (const token of state.tokens) {
+      const atTopLevel = depth === 0
+      // Annotate a top-level block's opening token (nesting 1) or a self-contained
+      // block token (nesting 0, e.g. fence/hr/code_block/html_block).
+      if (atTopLevel && token.block && token.type !== 'inline' && token.map && token.nesting >= 0) {
+        token.attrSet('data-src-start', String(token.map[0]))
+        token.attrSet('data-src-end', String(token.map[1]))
+      }
+      if (token.nesting === 1) depth++
+      else if (token.nesting === -1) depth--
+    }
+    return true
+  })
+}
+
+/**
+ * The verbatim raw-markdown source of a block, given the original output text and a
+ * 0-based, end-exclusive line range (as captured from `data-src-start/end`).
+ */
+export function sliceSource(output: string, start: number, end: number): string {
+  return (output ?? '').split('\n').slice(start, end).join('\n')
+}
+
+/** One heading-delimited section. `depth` 0 / empty `title` is the preamble that
+ * precedes the first heading (rendered, but never shown in the ToC). */
+export interface OutputSection {
+  id: string
+  depth: number
+  /** Plain-text heading, for the ToC. */
+  title: string
+  /** Inline-rendered heading HTML (code/bold/… preserved), for the section header. */
+  titleHtml: string
+  /** HTML of everything under this heading up to the next one. */
+  bodyHtml: string
+}
+
+export interface OutputOutline {
+  sections: OutputSection[]
+  /** True once there is at least one real heading worth a ToC entry. */
+  hasToc: boolean
+  /** Shallowest heading depth present, so the ToC can indent relative to it. */
+  minDepth: number
+}
+
+const md = new MarkdownIt({
+  html: false, // secure by default: escape raw HTML rather than render it
+  linkify: true, // turn bare URLs into links
+  breaks: true, // single newlines → <br>, matching how agents lay out prose
+  typographer: true,
+}).use(sourceLinePlugin)
+
+const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6'])
+const LINK_CLASS = 'text-indigo-300 underline decoration-indigo-500/40 hover:text-indigo-200'
+
+function slugify(title: string, used: Set<string>): string {
+  const base =
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'section'
+  let slug = base
+  let n = 2
+  while (used.has(slug)) slug = `${base}-${n++}`
+  used.add(slug)
+  return slug
+}
+
+/** Make every link open safely in a new tab and pick up the reader's link style. */
+function decorateLinks(root: HTMLElement): void {
+  for (const a of Array.from(root.querySelectorAll('a'))) {
+    a.setAttribute('target', '_blank')
+    a.setAttribute('rel', 'noopener noreferrer')
+    a.setAttribute('class', LINK_CLASS)
+  }
+}
+
+/** Build the heading-based outline for an agent's prose output. */
+export function parseOutputOutline(text: string): OutputOutline {
+  const source = text ?? ''
+  if (!source.trim()) return { sections: [], hasToc: false, minDepth: 1 }
+
+  const html = md.render(source)
+
+  // No DOM (SSR / non-browser): fall back to one un-segmented section. The reader
+  // overlay is client-only, so this path is effectively dead outside any runtime
+  // without `document`.
+  if (typeof document === 'undefined') {
+    return {
+      sections: [{ id: 'overview', depth: 0, title: '', titleHtml: '', bodyHtml: html }],
+      hasToc: false,
+      minDepth: 1,
+    }
+  }
+
+  const root = document.createElement('div')
+  root.innerHTML = html
+  decorateLinks(root)
+
+  const used = new Set<string>()
+  const sections: OutputSection[] = []
+  let current: OutputSection | null = null
+  let body: HTMLElement | null = null
+
+  const flush = () => {
+    if (current && body) current.bodyHtml = body.innerHTML.trim()
+    if (current) sections.push(current)
+  }
+
+  for (const node of Array.from(root.childNodes)) {
+    const el = node.nodeType === 1 ? (node as HTMLElement) : null
+    if (el && HEADINGS.has(el.tagName)) {
+      flush()
+      const title = (el.textContent ?? '').trim()
+      current = {
+        id: slugify(title, used),
+        depth: Number(el.tagName[1]),
+        title,
+        titleHtml: el.innerHTML,
+        bodyHtml: '',
+      }
+      body = document.createElement('div')
+    } else {
+      if (!current) {
+        // Content before the first heading → untitled preamble section.
+        current = {
+          id: slugify('overview', used),
+          depth: 0,
+          title: '',
+          titleHtml: '',
+          bodyHtml: '',
+        }
+        body = document.createElement('div')
+      }
+      body!.appendChild(node.cloneNode(true))
+    }
+  }
+  flush()
+
+  // A preamble that turned out to hold nothing renderable is noise — drop it.
+  const cleaned = sections.filter((s) => s.title || s.bodyHtml)
+  const headed = cleaned.filter((s) => s.depth > 0)
+  return {
+    sections: cleaned,
+    hasToc: headed.length > 0,
+    minDepth: headed.length ? Math.min(...headed.map((s) => s.depth)) : 1,
+  }
+}