@pilotiq/tiptap 3.10.4 → 3.10.6

package/src/render.ts

@@ -1,480 +0,0 @@
-/**
- * Server-safe Tiptap renderer.
- *
- * Walks a Tiptap JSON document (or HTML string) and returns an HTML string.
- * Pure function — no DOM, no Tiptap runtime, no React. Safe to call from
- * any server context: route handlers, page-data builders, RSC, edge.
- *
- * Output is intentionally NOT sanitized. Same posture as `Markdown` /
- * `Html` display primes in `@pilotiq/pilotiq` — admin-trusted authors only.
- * Text content gets HTML-escaped, link / image hrefs get scheme-checked,
- * but the surrounding markup is constructed by us, not parsed from user
- * input, so there's no place an unexpected tag can sneak in.
- *
- * Coverage matches what `RichTextField` ships in Phases A-G:
- *   nodes — doc / paragraph / heading / blockquote / codeBlock / bulletList
- *           / orderedList / listItem / horizontalRule / hardBreak / text
- *           / image / table / tableRow / tableCell / tableHeader
- *           / details / detailsSummary / detailsContent
- *           / grid / gridColumn
- *           / mergeTag / mention
- *   marks — bold / italic / strike / underline / subscript / superscript
- *           / code / link / textStyle (color) / highlight (color)
- *           / lead (paragraph emphasis) / small (semantic <small>)
- *   attrs — heading.level / orderedList.start / codeBlock.language
- *           / paragraph.textAlign + heading.textAlign
- *           / image.src + alt + title + width + height
- *           / tableCell.colspan + rowspan + colwidth (also tableHeader)
- *           / mergeTag.id / mention.id + label + trigger
- *   custom blocks — render to `<div data-type="..." data-attrs="...">` so
- *           consumers can replay or style by data-type.
- */
-
-export interface RenderRichTextOptions {
-  /**
-   * Override the rendering of a custom block (anything that isn't a
-   * built-in node). Receives the raw node; return the HTML string.
-   * Default emits `<div data-type="..." data-attrs="...">`.
-   */
-  renderBlock?: (node: TiptapNode) => string
-  /**
-   * Substitution map for `{{ tag }}` placeholders inserted via
-   * `RichTextField.mergeTags(['name', …])`. When the renderer hits a
-   * `mergeTag` node whose `id` is a key in this map, it emits the value
-   * (HTML-escaped). Unmatched ids fall back to a styled `<span class="merge-tag">`
-   * that preserves the placeholder visually.
-   */
-  mergeTags?: Record<string, string>
-  /**
-   * Override the label rendered inside a mention chip at read time. The
-   * editor caches the label on insert (so static snapshots stay self-
-   * contained), but rendered surfaces can call back into a directory or
-   * cache to refresh stale names. Return `undefined` to fall back to the
-   * cached label.
-   */
-  resolveMention?: (trigger: string, id: string) => string | undefined
-}
-
-/** Tiptap JSON node — structural, no runtime dep on `@tiptap/core`. */
-export interface TiptapNode {
-  type:     string
-  text?:    string
-  attrs?:   Record<string, unknown>
-  content?: TiptapNode[]
-  marks?:   TiptapMark[]
-}
-
-export interface TiptapMark {
-  type:   string
-  attrs?: Record<string, unknown>
-}
-
-/**
- * Render Tiptap content to HTML.
- *
- * Accepts:
- *   - a Tiptap JSON document (`{ type: 'doc', content: [...] }`) — walked
- *     and converted node-by-node;
- *   - a JSON-encoded string of the same — parsed then walked;
- *   - a raw HTML string — returned verbatim (the editor was configured
- *     with `.storage('html')` and the value is already HTML).
- *
- * Returns `''` on null / undefined / unparseable input.
- */
-export function renderRichTextToHtml(content: unknown, opts: RenderRichTextOptions = {}): string {
-  if (content === null || content === undefined) return ''
-
-  if (typeof content === 'string') {
-    const trimmed = content.trimStart()
-    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
-      try {
-        const parsed = JSON.parse(content)
-        return renderNode(parsed, opts)
-      } catch {
-        return ''
-      }
-    }
-    return content
-  }
-
-  if (typeof content === 'object') return renderNode(content as TiptapNode, opts)
-
-  return ''
-}
-
-/**
- * Detect whether a value looks like Tiptap rich-text content. Conservative:
- * only matches the canonical document root (`{ type: 'doc', content: [...] }`),
- * either object-form or as a JSON-encoded string. Plain text and arbitrary
- * objects are NOT auto-detected — display surfaces should fall through to
- * their default formatter.
- */
-export function isRichTextValue(v: unknown): boolean {
-  if (v === null || v === undefined) return false
-  if (typeof v === 'object') return isTiptapDoc(v)
-  if (typeof v === 'string') {
-    const trimmed = v.trimStart()
-    if (!trimmed.startsWith('{')) return false
-    try {
-      return isTiptapDoc(JSON.parse(v))
-    } catch {
-      return false
-    }
-  }
-  return false
-}
-
-function isTiptapDoc(v: unknown): boolean {
-  return (
-    typeof v === 'object' && v !== null
-    && (v as { type?: unknown }).type === 'doc'
-    && Array.isArray((v as { content?: unknown }).content)
-  )
-}
-
-// ─── Node walker ─────────────────────────────────────────────────────
-
-function renderNode(node: unknown, opts: RenderRichTextOptions): string {
-  if (node === null || node === undefined) return ''
-  if (Array.isArray(node)) return node.map(n => renderNode(n, opts)).join('')
-  if (typeof node !== 'object') return ''
-
-  const n = node as TiptapNode
-
-  switch (n.type) {
-    case 'doc':            return renderChildren(n, opts)
-    case 'paragraph':      return wrap('p', n, opts, alignStyle(n))
-    case 'heading': {
-      const level = clampLevel(n.attrs?.['level'])
-      return wrap(`h${level}`, n, opts, alignStyle(n))
-    }
-    case 'blockquote':     return wrap('blockquote', n, opts)
-    case 'codeBlock': {
-      const lang = typeof n.attrs?.['language'] === 'string'
-        ? n.attrs!['language'] as string
-        : undefined
-      const cls  = lang ? ` class="language-${escapeAttr(lang)}"` : ''
-      return `<pre><code${cls}>${renderChildren(n, opts)}</code></pre>`
-    }
-    case 'bulletList':     return wrap('ul', n, opts)
-    case 'orderedList': {
-      const startRaw = n.attrs?.['start']
-      const start    = typeof startRaw === 'number' ? startRaw : Number(startRaw)
-      const startAttr = Number.isFinite(start) && start !== 1 ? ` start="${Math.trunc(start)}"` : ''
-      return `<ol${startAttr}>${renderChildren(n, opts)}</ol>`
-    }
-    case 'listItem':       return wrap('li', n, opts)
-    case 'horizontalRule': return '<hr>'
-    case 'hardBreak':      return '<br>'
-    case 'image':          return renderImage(n)
-    case 'table':          return renderTable(n, opts)
-    case 'tableRow':       return wrap('tr', n, opts)
-    case 'tableCell':      return renderCell('td', n, opts)
-    case 'tableHeader':    return renderCell('th', n, opts)
-    case 'details':        return renderDetails(n, opts)
-    case 'detailsSummary': return wrap('summary', n, opts)
-    // The editor's NodeView wraps content in a `<div data-type="detailsContent">`
-    // for click handling, but the read-side HTML doesn't need a wrapper —
-    // a `<details>` block's content sits directly after the `<summary>` per
-    // the platform spec, which matches reader expectations.
-    case 'detailsContent': return renderChildren(n, opts)
-    case 'grid':           return renderGrid(n, opts)
-    case 'gridColumn':     return wrap('div', n, opts)
-    case 'mergeTag':       return renderMergeTag(n, opts)
-    case 'mention':        return renderMention(n, opts)
-    case 'text':           return renderText(n)
-    default:
-      if (opts.renderBlock) return opts.renderBlock(n)
-      return renderCustomBlock(n)
-  }
-}
-
-function renderChildren(n: TiptapNode, opts: RenderRichTextOptions): string {
-  if (!n.content) return ''
-  return n.content.map(c => renderNode(c, opts)).join('')
-}
-
-function wrap(tag: string, n: TiptapNode, opts: RenderRichTextOptions, extraAttrs = ''): string {
-  return `<${tag}${extraAttrs}>${renderChildren(n, opts)}</${tag}>`
-}
-
-function alignStyle(n: TiptapNode): string {
-  const align = n.attrs?.['textAlign']
-  if (typeof align !== 'string' || align === '' || align === 'left') return ''
-  // `start` / `end` / `center` / `justify` — TextAlign extension allows-list.
-  if (!/^[a-z]+$/.test(align)) return ''
-  return ` style="text-align: ${align}"`
-}
-
-function clampLevel(raw: unknown): number {
-  const n = typeof raw === 'number' ? raw : Number(raw)
-  if (!Number.isFinite(n)) return 1
-  return Math.min(6, Math.max(1, Math.trunc(n)))
-}
-
-// ─── Text + marks ────────────────────────────────────────────────────
-
-function renderText(n: TiptapNode): string {
-  let html = escapeHtml(String(n.text ?? ''))
-  const marks = Array.isArray(n.marks) ? n.marks : []
-  // Tiptap stores marks innermost-first in array order; wrap from index
-  // 0 outward so the first mark ends up nested deepest — matches Tiptap's
-  // own DOM serialization.
-  for (const mark of marks) html = wrapMark(html, mark)
-  return html
-}
-
-function wrapMark(inner: string, mark: TiptapMark | undefined): string {
-  if (!mark || typeof mark !== 'object') return inner
-  const attrs = (mark.attrs ?? {}) as Record<string, unknown>
-  switch (mark.type) {
-    case 'bold':        return `<strong>${inner}</strong>`
-    case 'italic':      return `<em>${inner}</em>`
-    case 'strike':      return `<s>${inner}</s>`
-    case 'underline':   return `<u>${inner}</u>`
-    case 'subscript':   return `<sub>${inner}</sub>`
-    case 'superscript': return `<sup>${inner}</sup>`
-    case 'code':        return `<code>${inner}</code>`
-    case 'lead':        return `<span class="lead">${inner}</span>`
-    case 'small':       return `<small>${inner}</small>`
-    case 'link': {
-      const href   = sanitizeUrl(attrs['href'])
-      const target = typeof attrs['target'] === 'string'
-        ? ` target="${escapeAttr(String(attrs['target']))}"` : ''
-      const rel    = attrs['target'] === '_blank' ? ' rel="noopener noreferrer"' : ''
-      return `<a href="${href}"${target}${rel}>${inner}</a>`
-    }
-    case 'textStyle': {
-      const color = attrs['color']
-      if (typeof color !== 'string' || color === '') return inner
-      const safe = sanitizeColor(color)
-      if (!safe) return inner
-      return `<span style="color: ${safe}">${inner}</span>`
-    }
-    case 'highlight': {
-      const color = attrs['color']
-      if (typeof color !== 'string' || color === '') return `<mark>${inner}</mark>`
-      const safe = sanitizeColor(color)
-      if (!safe) return `<mark>${inner}</mark>`
-      return `<mark style="background-color: ${safe}">${inner}</mark>`
-    }
-    default:
-      return inner
-  }
-}
-
-// ─── Image ───────────────────────────────────────────────────────────
-
-function renderImage(n: TiptapNode): string {
-  const attrs = (n.attrs ?? {}) as Record<string, unknown>
-  const src   = sanitizeUrl(attrs['src'])
-  // Don't emit a broken `<img>` if src couldn't be sanitized to anything
-  // meaningful. `sanitizeUrl` returns `'#'` for unsafe inputs — and `<img
-  // src="#">` re-fetches the page, which is the worst possible default.
-  if (src === '#') return ''
-  const alt    = typeof attrs['alt']   === 'string' ? ` alt="${escapeAttr(String(attrs['alt']))}"`     : ' alt=""'
-  const title  = typeof attrs['title'] === 'string' ? ` title="${escapeAttr(String(attrs['title']))}"` : ''
-  const width  = pixelAttr('width',  attrs['width'])
-  const height = pixelAttr('height', attrs['height'])
-  return `<img src="${src}"${alt}${title}${width}${height}>`
-}
-
-function pixelAttr(name: string, raw: unknown): string {
-  if (raw === null || raw === undefined || raw === '') return ''
-  const n = typeof raw === 'number' ? raw : Number(raw)
-  if (!Number.isFinite(n) || n <= 0) return ''
-  return ` ${name}="${Math.trunc(n)}"`
-}
-
-// ─── Tables ──────────────────────────────────────────────────────────
-
-/**
- * Render a Tiptap `table` node. The Tiptap table extension stores per-column
- * widths on individual cells via `colwidth: number[]` — we collect the widths
- * from the first row and emit a `<colgroup>` so read-side renders match the
- * editor's column proportions.
- */
-function renderTable(n: TiptapNode, opts: RenderRichTextOptions): string {
-  const colgroup = buildColgroup(n)
-  return `<table>${colgroup}<tbody>${renderChildren(n, opts)}</tbody></table>`
-}
-
-function buildColgroup(table: TiptapNode): string {
-  const firstRow = table.content?.find((c) => c.type === 'tableRow')
-  if (!firstRow || !firstRow.content) return ''
-  const widths: (number | null)[] = []
-  let hasAnyWidth = false
-  for (const cell of firstRow.content) {
-    if (cell.type !== 'tableCell' && cell.type !== 'tableHeader') continue
-    const colspan = clampPositiveInt(cell.attrs?.['colspan']) ?? 1
-    const colwidth = cell.attrs?.['colwidth']
-    const widthArr = Array.isArray(colwidth)
-      ? colwidth.map((w) => clampPositiveInt(w))
-      : []
-    for (let i = 0; i < colspan; i++) {
-      const w = widthArr[i] ?? null
-      if (w !== null) hasAnyWidth = true
-      widths.push(w)
-    }
-  }
-  // Only emit a colgroup when at least one width is known. Tiptap's table
-  // extension only sets colwidth after the user drags a column-resize handle —
-  // out-of-the-box tables have no widths, so an always-emitted colgroup would
-  // be noise.
-  if (!hasAnyWidth) return ''
-  const cols = widths.map((w) => w !== null ? `<col style="width: ${w}px">` : '<col>')
-  return `<colgroup>${cols.join('')}</colgroup>`
-}
-
-function renderCell(tag: 'td' | 'th', n: TiptapNode, opts: RenderRichTextOptions): string {
-  const attrs = (n.attrs ?? {}) as Record<string, unknown>
-  const colspan = clampPositiveInt(attrs['colspan'])
-  const rowspan = clampPositiveInt(attrs['rowspan'])
-  const span = [
-    colspan && colspan !== 1 ? ` colspan="${colspan}"` : '',
-    rowspan && rowspan !== 1 ? ` rowspan="${rowspan}"` : '',
-  ].join('')
-  return `<${tag}${span}>${renderChildren(n, opts)}</${tag}>`
-}
-
-function clampPositiveInt(raw: unknown): number | null {
-  if (raw === null || raw === undefined || raw === '') return null
-  const n = typeof raw === 'number' ? raw : Number(raw)
-  if (!Number.isFinite(n) || n <= 0) return null
-  return Math.trunc(n)
-}
-
-// ─── Details (collapsible blocks) ────────────────────────────────────
-
-/**
- * Render a `details` node. The `open` attribute round-trips the editor's
- * open/closed state when `Details.configure({ persist: true })` is set —
- * matches the platform `<details open>` attribute exactly so a reader's
- * snapshot reflects how the author last left it.
- */
-function renderDetails(n: TiptapNode, opts: RenderRichTextOptions): string {
-  const isOpen = n.attrs?.['open'] === true
-  return `<details${isOpen ? ' open' : ''}>${renderChildren(n, opts)}</details>`
-}
-
-// ─── Grid (multi-column layout) ──────────────────────────────────────
-
-/**
- * Render a `grid` node. The `data-columns` attribute round-trips the
- * editor's column count; class names mirror the editor's `renderHTML` so
- * one stylesheet paints both surfaces (consumer owns the CSS — same
- * posture as `lead` / `small`).
- *
- * Out-of-range column counts (anything other than 2 or 3) clamp to 2 —
- * the schema enforces it on the editor side, but a tampered Tiptap JSON
- * fed straight to the renderer shouldn't paint a `grid-cols-99` class.
- */
-function renderGrid(n: TiptapNode, opts: RenderRichTextOptions): string {
-  const cols = clampGridColumnsForRender(n.attrs?.['columns'])
-  return `<div class="pilotiq-grid pilotiq-grid-cols-${cols}">${renderChildren(n, opts)}</div>`
-}
-
-function clampGridColumnsForRender(raw: unknown): 2 | 3 {
-  const n = typeof raw === 'number' ? raw : Number(raw)
-  if (!Number.isFinite(n)) return 2
-  const trunc = Math.trunc(n)
-  return trunc === 3 ? 3 : 2
-}
-
-// ─── Merge tags + mentions ───────────────────────────────────────────
-
-/**
- * Render a `mergeTag` atom — either substitute the value from
- * `opts.mergeTags` (HTML-escaped) or fall back to a styled `<span>` that
- * preserves the placeholder visually so server-rendered previews stay
- * informative when no substitution map is supplied.
- */
-function renderMergeTag(n: TiptapNode, opts: RenderRichTextOptions): string {
-  const id = String((n.attrs ?? {})['id'] ?? '').trim()
-  if (id === '') return ''
-  const map = opts.mergeTags
-  // Only substitute when the map explicitly carries the id — using
-  // `Object.prototype.hasOwnProperty` so `null` / empty-string substitutions
-  // still win over the fallback span.
-  if (map && Object.prototype.hasOwnProperty.call(map, id)) {
-    return escapeHtml(String(map[id] ?? ''))
-  }
-  return `<span class="merge-tag" data-id="${escapeAttr(id)}">{{ ${escapeHtml(id)} }}</span>`
-}
-
-/**
- * Render a `mention` atom as a styled `<span>` carrying the cached label.
- * `opts.resolveMention` can override the label per `(trigger, id)` pair —
- * useful for refreshing display names from a directory at render time.
- * Both `id` and `trigger` are required; missing either drops the chip.
- */
-function renderMention(n: TiptapNode, opts: RenderRichTextOptions): string {
-  const attrs   = (n.attrs ?? {}) as Record<string, unknown>
-  const id      = String(attrs['id']      ?? '').trim()
-  const trigger = String(attrs['trigger'] ?? '').trim()
-  if (id === '' || trigger === '') return ''
-  const cached   = String(attrs['label'] ?? '').trim()
-  const resolved = opts.resolveMention?.(trigger, id)
-  const label    = resolved !== undefined ? resolved : (cached !== '' ? cached : id)
-  return (
-    `<span class="mention" data-trigger="${escapeAttr(trigger)}" data-id="${escapeAttr(id)}">` +
-    escapeHtml(`${trigger}${label}`) +
-    `</span>`
-  )
-}
-
-// ─── Custom blocks ───────────────────────────────────────────────────
-
-function renderCustomBlock(n: TiptapNode): string {
-  const type = String(n.type ?? '')
-  const dataAttrs = n.attrs ? ` data-attrs="${escapeAttr(JSON.stringify(n.attrs))}"` : ''
-  const inner = n.content ? renderChildren(n, {}) : ''
-  return `<div data-type="${escapeAttr(type)}"${dataAttrs}>${inner}</div>`
-}
-
-// ─── Escapers + sanitizers ───────────────────────────────────────────
-
-function escapeHtml(s: string): string {
-  return s.replace(/[&<>"']/g, ch => HTML_ESCAPES[ch] ?? ch)
-}
-
-const HTML_ESCAPES: Record<string, string> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-}
-
-function escapeAttr(s: string): string {
-  return escapeHtml(s)
-}
-
-/**
- * Allowlist for color values. Accepts hex (`#abc` / `#abcdef`), rgb()/rgba(),
- * hsl()/hsla(), oklch(), and named colors (alpha-only). Returns `''` for
- * anything that doesn't match — caller falls back to no inline style.
- */
-function sanitizeColor(raw: string): string {
-  const v = raw.trim()
-  if (v === '') return ''
-  if (/^#[0-9a-f]{3,8}$/i.test(v)) return v
-  if (/^rgba?\([^()<>"']+\)$/i.test(v)) return v
-  if (/^hsla?\([^()<>"']+\)$/i.test(v)) return v
-  if (/^oklch\([^()<>"']+\)$/i.test(v)) return v
-  if (/^[a-z]+$/i.test(v)) return v
-  return ''
-}
-
-/**
- * Block dangerous URL schemes. Anything that isn't an absolute http(s),
- * mailto, tel, anchor (#…), root-relative (/…), or relative path falls
- * back to `#`. Output is HTML-escaped.
- */
-function sanitizeUrl(raw: unknown): string {
-  if (typeof raw !== 'string') return '#'
-  const v = raw.trim()
-  if (v === '') return '#'
-  if (/^(?:javascript|data|vbscript):/i.test(v)) return '#'
-  return escapeAttr(v)
-}

package/src/surgicalOps.ts

@@ -1,205 +0,0 @@
-/**
- * Surgical block-op planners for AI-driven precise edits.
- *
- * Each planner takes the editor + a logical block index + a payload and
- * returns a `TransactionModifier` — a function the caller (typically
- * `useAiInlineDiff`) feeds into
- * `editor.commands.applySurgicalAiInlineDiff(id, modifier)`. The diff
- * extension wraps the modifier in a snapshot-then-apply step so the
- * inline-diff overlay renders against the precise changed range.
- *
- * "Block index" refers to a 0-based position across the doc's top-level
- * children — what the AI agent sees as a numbered structural summary.
- * Planners translate that to absolute ProseMirror positions internally.
- *
- * Planners return `null` when the request can't be satisfied (out-of-
- * range index, unparseable HTML, unknown mark). Callers should treat
- * `null` as "abort the surgical op" and surface a clear error to the
- * agent so it can retry with a different plan.
- */
-
-import type { Editor } from '@tiptap/core'
-import type { Transaction } from '@tiptap/pm/state'
-import type { Mark, MarkType, Node as ProseMirrorNode } from '@tiptap/pm/model'
-import { DOMParser as PMDOMParser } from '@tiptap/pm/model'
-import { parseMarkdownToHtml } from './markdownStorage.js'
-
-export type TransactionModifier = (tr: Transaction) => void
-
-/** Resolve the start position of the top-level child at `blockIndex`. */
-function blockStartPos(doc: ProseMirrorNode, blockIndex: number): number | null {
-  if (!Number.isInteger(blockIndex) || blockIndex < 0 || blockIndex >= doc.childCount) return null
-  let pos = 0
-  for (let i = 0; i < blockIndex; i++) pos += doc.child(i).nodeSize
-  return pos
-}
-
-/**
- * Parse content into a doc-replaceable Slice against the editor's
- * schema. Auto-detects markdown editors by sniffing for the
- * `tiptap-markdown` extension's `storage.markdown.parser`: if present,
- * the editor is a `MarkdownEditor` and AI-supplied `content` is
- * markdown source — run it through the markdown parser to produce
- * HTML first. Otherwise content is HTML (the `RichTextField` /
- * `TiptapEditor` path).
- *
- * Mirrors the same auto-detect strategy `MarkdownEditor.tsx` uses for
- * its `parseSuggestion` whole-field callback (see `useAiInlineDiff`),
- * so surgical ops on markdown fields stay consistent with the
- * existing whole-field replacement path.
- *
- * Returns `null` when DOM isn't available (SSR — shouldn't happen
- * here, but keeps the planner safe) or when the markdown parser
- * throws / returns a non-string (malformed content).
- */
-function parseContentToSlice(editor: Editor, content: string): ReturnType<typeof PMDOMParser.prototype.parseSlice> | null {
-  if (typeof document === 'undefined') return null
-  let html = content
-  try {
-    const parsed = parseMarkdownToHtml(editor, content)
-    if (parsed !== undefined) html = parsed
-  } catch { return null }
-  const container = document.createElement('div')
-  container.innerHTML = html
-  return PMDOMParser.fromSchema(editor.schema).parseSlice(container)
-}
-
-/**
- * Replace the top-level block at `blockIndex` with the parsed content.
- * `content` is HTML for `RichTextField` (Tiptap) editors and markdown
- * source for `MarkdownField` (markdown-extension) editors —
- * auto-detected by `parseContentToSlice`. Multiple top-level nodes are
- * allowed and will all land where the original block was.
- */
-export function planReplaceBlock(
-  editor:     Editor,
-  blockIndex: number,
-  content:    string,
-): TransactionModifier | null {
-  const doc = editor.state.doc
-  const start = blockStartPos(doc, blockIndex)
-  if (start === null) return null
-  const slice = parseContentToSlice(editor, content)
-  if (!slice) return null
-  const end = start + doc.child(blockIndex).nodeSize
-  return (tr) => { tr.replace(start, end, slice) }
-}
-
-/**
- * Insert one or more top-level nodes before the block at `blockIndex`.
- * `content` is HTML on `RichTextField` editors and markdown source on
- * `MarkdownField` editors — auto-detected by `parseContentToSlice`.
- * `blockIndex === doc.childCount` appends at the end.
- */
-export function planInsertBlockBefore(
-  editor:     Editor,
-  blockIndex: number,
-  content:    string,
-): TransactionModifier | null {
-  const doc = editor.state.doc
-  if (!Number.isInteger(blockIndex) || blockIndex < 0 || blockIndex > doc.childCount) return null
-  const slice = parseContentToSlice(editor, content)
-  if (!slice) return null
-  let pos = 0
-  for (let i = 0; i < blockIndex; i++) pos += doc.child(i).nodeSize
-  return (tr) => { tr.replace(pos, pos, slice) }
-}
-
-/**
- * Delete the top-level block at `blockIndex`. Doc must retain at least
- * one child after the delete (most schemas require this) — refuses to
- * delete the last remaining block.
- */
-export function planDeleteBlock(
-  editor:     Editor,
-  blockIndex: number,
-): TransactionModifier | null {
-  const doc = editor.state.doc
-  const start = blockStartPos(doc, blockIndex)
-  if (start === null) return null
-  if (doc.childCount <= 1) return null
-  const end = start + doc.child(blockIndex).nodeSize
-  return (tr) => { tr.delete(start, end) }
-}
-
-export interface BlockMarkRange {
-  /** 0-based text offset from the start of the block's content. */
-  from: number
-  /** Exclusive end offset. */
-  to:   number
-}
-
-/**
- * Apply or remove an inline mark on a range *within* the block at
- * `blockIndex`. `range.from` / `range.to` are text offsets relative to
- * the start of the block's content (so `0` is the first character of
- * the block, not the start of the doc).
- *
- * `apply = true` sets the mark (with optional `attrs`); `apply = false`
- * removes it. Unknown marks (not in the editor's schema) return `null`
- * so the caller can surface a clean error to the agent.
- */
-export function planUpdateBlockMark(
-  editor:     Editor,
-  blockIndex: number,
-  mark:       string,
-  range:      BlockMarkRange,
-  apply:      boolean,
-  attrs?:     Record<string, unknown>,
-): TransactionModifier | null {
-  const doc = editor.state.doc
-  const start = blockStartPos(doc, blockIndex)
-  if (start === null) return null
-  const markType: MarkType | undefined = editor.schema.marks[mark]
-  if (!markType) return null
-
-  const block      = doc.child(blockIndex)
-  const blockInner = start + 1 // step inside the block's opening token
-  const contentMax = block.content.size
-
-  if (!Number.isInteger(range.from) || !Number.isInteger(range.to)) return null
-  const clampedFrom = Math.max(0, Math.min(range.from, contentMax))
-  const clampedTo   = Math.max(clampedFrom, Math.min(range.to, contentMax))
-  if (clampedTo === clampedFrom) return null
-
-  const from = blockInner + clampedFrom
-  const to   = blockInner + clampedTo
-
-  if (apply) {
-    const m: Mark = markType.create(attrs ?? null)
-    return (tr) => { tr.addMark(from, to, m) }
-  }
-  return (tr) => { tr.removeMark(from, to, markType) }
-}
-
-/**
- * Summarize a doc's top-level structure as a numbered list the AI can
- * cite by index when proposing surgical ops. Each entry includes the
- * block index, node type, and a truncated text preview — enough for the
- * model to identify which block it wants to modify without sending the
- * whole HTML/markdown back through token-priced channels.
- *
- * Returns one line per top-level child:
- *   `[0] heading: Welcome to the docs`
- *   `[1] paragraph: Lorem ipsum dolor sit amet…`
- *   `[2] bulletList: 3 items`
- */
-export function summarizeBlockStructure(doc: ProseMirrorNode, maxChars = 80): string {
-  const lines: string[] = []
-  for (let i = 0; i < doc.childCount; i++) {
-    const node = doc.child(i)
-    const text = node.textContent.trim().replace(/\s+/g, ' ')
-    const preview = text.length === 0
-      ? describeStructuralNode(node)
-      : text.length > maxChars ? `${text.slice(0, maxChars)}…` : text
-    lines.push(`[${i}] ${node.type.name}: ${preview}`)
-  }
-  return lines.join('\n')
-}
-
-function describeStructuralNode(node: ProseMirrorNode): string {
-  const kids = node.childCount
-  if (kids === 0) return '(empty)'
-  if (kids === 1) return `1 ${node.firstChild?.type.name ?? 'child'}`
-  return `${kids} children`
-}