Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

77.3 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// The agent surface: what `window.bento` reports, and how it is patched.
//
// WHY THIS EXISTS. An agent authoring a space is working blind in a way a human
// author is not. Everything that goes wrong here goes wrong SILENTLY: a link to
// a page that was renamed away still looks like a link in the JSON, a `<p>` in
// a block's html is unwrapped at render with no complaint, an unknown block
// type falls back to its text, an `asset:` reference that nothing points at is
// just megabytes. None of it throws, and none of it is visible in the document
// the agent just wrote. `validate()` is the pass that says so out loud.
//
// The other half is writing. Before this, the only structural verbs were
// `insertBlocks` and `newPage`; everything else meant `loadDoc(JSON.stringify(
// wholeDocument))`, which flattens undo to one entry, clobbers whatever a human
// typed while the agent was thinking, and re-mints nothing but is trusted with
// everything. The verbs here are each ONE undoable step and touch only what
// they name.
//
// THE INVARIANT THAT SHAPES THIS FILE: an agent must not be able to write a
// document this build could not itself have produced. So html goes through the
// sanitizer on the way IN (not only on the way to the screen), a patch value
// that JSON cannot carry is refused rather than silently dropped at save time,
// and a page can never be left with zero blocks — the editor has no way to
// place a caret in one, so it would be a page nobody can ever type in again.
//
// PLAN/APPLY. Every write verb returns a PLAN: it validates against the
// document and hands back a thunk. `store.commit` checkpoints undo BEFORE it
// mutates, so planning inside a commit would mean a refused patch still pushed
// an undo entry that undoes nothing. Planning first also makes the whole write
// path testable in node, where there is no store and no DOM.

import { type SpacesDoc, type Page, type Block, buildIndex, isRemote, newBlock, newPage, uid, descendantsOf, linkCard, commentsOn, pageAssetKeys } from './model.ts'
import { SPECS, SPEC } from './blocks.ts'
import { aliasesOf, nameKey } from './mentions.ts'
import { sanitizeInline, textOf, inertBody, esc, UNWRAP } from './sanitize.ts'
import { orphanAssets, humanBytes } from './assets.ts'
import { designProblems, designAssetKeys, BUILT_IN_NAMES } from './designs.ts'
import { isPageRef, anchorOf, sectionOf, embedReaches } from './embed.ts'
import { danglingRefs, orphanNotes, LABEL_OK } from './footnotes.ts'
import {
  type FieldSpec, ISSUE_FIELDS, fieldsOf, fieldByKey, optionOf, propBlock, propHtml, valuesOf, isIssue, headerLength,
} from './fields.ts'

// ---------------------------------------------------------------------------
// shared helpers
// ---------------------------------------------------------------------------

// The block REGISTRY is the one list of known types (blocks.ts). A second
// const here would drift the first time someone adds a block type — which is
// precisely what the registry exists to prevent, and validate() reporting a
// real type as unknown would have an agent 'fix' working documents.
const KNOWN_BLOCK_TYPES = SPECS.map((s) => s.type)
const KNOWN = new Set<string>(KNOWN_BLOCK_TYPES)

/** A media block whose kind is audio — anything else is drawn as video, which
 *  is the same rule renderers and exporters here already apply. */
const isAudio = (b: Block): boolean =>
  b.type === 'media' && String((b as { kind?: unknown }).kind ?? 'video') === 'audio'

const words = (s: string): number => (s.trim() ? s.trim().split(/\s+/).length : 0)

const utf8len = (s: string): number =>
  typeof TextEncoder !== 'undefined' ? new TextEncoder().encode(s).length : s.length

export interface BlockAt { block: Block; page: Page; index: number }

export function findBlock(doc: SpacesDoc, id: string): BlockAt | null {
  for (const page of doc.pages) {
    const index = page.blocks.findIndex((b) => b.id === id)
    if (index >= 0) return { block: page.blocks[index], page, index }
  }
  return null
}

/**
 * Every block nested under `id`.
 *
 * Delegates to model.ts's ONE rule. It used to sweep the `parent` graph to a
 * fixed point "rather than trusting the order", which is the right instinct and
 * the wrong rule: on a merged document a `parent` cycle makes that sweep return
 * the whole connected component INCLUDING `id` itself, so planRemoveBlocks
 * would delete blocks the caller never named. The positional rule cannot cycle.
 */
function descendants(page: Page, id: string): Set<string> {
  return descendantsOf(page, id)
}

/**
 * Would JSON.stringify carry this value unchanged?
 *
 * A function, a DOM node, a Map or a Date all assign fine and then either
 * VANISH at save time or throw on a cycle — either way the failure surfaces
 * hours later, in the file, with no clue where it came from. The format is
 * additive, so unknown keys are welcome; unknown SHAPES are not.
 */
export function jsonSafe(v: unknown, depth = 0): boolean {
  if (v === null) return true
  const t = typeof v
  if (t === 'string' || t === 'boolean') return true
  if (t === 'number') return Number.isFinite(v as number)
  if (depth > 12) return false
  if (Array.isArray(v)) return v.every((x) => jsonSafe(x, depth + 1))
  if (t === 'object') {
    const proto = Object.getPrototypeOf(v)
    if (proto !== Object.prototype && proto !== null) return false
    return Object.values(v as Record<string, unknown>).every((x) => jsonSafe(x, depth + 1))
  }
  return false
}

const hasElements = (html: string): boolean =>
  typeof document === 'undefined'
    ? /<[a-z][a-z0-9]*(\s|\/|>)/i.test(html)
    : !!inertBody(html).querySelector('*')

/**
 * The stored form of a block's html, as the EDITOR would have stored it.
 *
 * Rich blocks are sanitized inline html. A `code` block is different: the
 * renderer takes its textContent, and a contentEditable `<code>` stores what
 * you type ESCAPED — so `<div>` in a code block lives in the file as
 * `&lt;div&gt;`. Sanitizing code would delete the sample someone was showing,
 * so code is escaped instead, and only when it actually carries live tags:
 * already-escaped text passes through untouched, which keeps this idempotent
 * (a patch replayed twice must not double-escape).
 */
export function normalizeHtml(html: string, type: string): string {
  if (type === 'code') return hasElements(html) ? esc(html) : html
  return sanitizeInline(html)
}

/** A page title renders as TEXT, so markup in one would show literally. */
export const plainTitle = (v: unknown): string => textOf(String(v ?? ''))

/**
 * A title has to BE a string.
 *
 * `plainTitle` coerces, and that is right for what it was written for: markup
 * pasted into a title, a number someone used for a heading. But coercion
 * applied to the wrong TYPE is not forgiveness, it is a lie —
 * `newPage({ title: 'Tracker' })`, written in the object shape every other verb
 * on this surface takes, made a page called "[object Object]" and reported
 * success. Every other verb here refuses input it cannot honour, and a title is
 * a poor place to start guessing: the page is created either way, so the caller
 * finds out by reading the sidebar.
 *
 * `null`/absent stays legal — that is "no title", and each caller has its own
 * default for it.
 */
export const badTitle = (v: unknown): boolean => v != null && typeof v !== 'string'

// ---------------------------------------------------------------------------
// validate()
// ---------------------------------------------------------------------------

export type Severity = 'error' | 'warning' | 'info'

export interface Finding {
  /** stable machine-readable code, e.g. 'broken-link' */
  code: string
  severity: Severity
  /** what is wrong, in one line, actionable on its own */
  message: string
  /** how to fix it */
  fix: string
  page?: string
  block?: string
  /** the field it is about, when it is about one */
  path?: string
}

export interface ValidateResult {
  /** no errors. Warnings and info do not make a document invalid. */
  ok: boolean
  counts: Record<Severity, number>
  findings: Finding[]
}

/** Inline tags a block may keep (sanitize.ts ALLOWED, lowercased). */
const INLINE_OK = new Set(['b', 'i', 'u', 's', 'em', 'strong', 'code', 'br', 'span', 'mark', 'sub', 'sup', 'a'])
/** Tags the sanitizer unwraps: the tag goes, the words stay (sanitize.ts UNWRAP). */
// Derived from the sanitizer, never restated: this list IS what sanitizeInline
// unwraps, and a copy would drift the moment that policy changes.
const UNWRAPPED = new Set([...UNWRAP].map((t) => t.toLowerCase()))

const TAG_RE = /<\/?([a-z][a-z0-9]*)\b/gi
const LINK_RE = /href\s*=\s*["']([^"']*)["']/gi

/**
 * WHAT IS DELIBERATELY NOT CHECKED: unknown property names.
 *
 * Slides warns about them, because its element schema is closed. This format's
 * unknown fields are a FEATURE — they are how a future build's data survives an
 * older one, and how an agent parks its own metadata on a block. Warning about
 * them would fire on documents that are working exactly as designed, and a
 * validator that cries wolf on good documents is one an agent learns to skip.
 */
export function validateDoc(doc: SpacesDoc): ValidateResult {
  const findings: Finding[] = []
  const add = (f: Finding) => findings.push(f)
  const pages = Array.isArray(doc.pages) ? doc.pages : []
  const assets = doc.assets ?? {}

  if (!pages.length) {
    add({ code: 'no-pages', severity: 'error', message: 'This space has no pages.',
      fix: 'Add at least one page — the reader shows "This space has no pages." until there is one.' })
  }

  // ---- identity ----------------------------------------------------------
  // Every id is unique across the WHOLE document: links, backlinks and (later)
  // collaboration key on them. parseDoc repairs duplicates deterministically,
  // but a repaired id is a NEW id, so whatever pointed at the old one is now
  // pointing somewhere else. Emitting them unique is the only way to keep the
  // references an author wrote.
  const seen = new Set<string>()
  const claim = (id: unknown, where: Pick<Finding, 'page' | 'block'>, what: string) => {
    if (typeof id !== 'string' || !id) {
      add({ ...where, code: 'missing-id', severity: 'error', path: 'id',
        message: `A ${what} has no id.`,
        fix: 'Give it a unique string id. Loading assigns one derived from the bytes, which is not the id you meant to link to.' })
      return
    }
    if (seen.has(id)) {
      add({ ...where, code: 'duplicate-id', severity: 'error', path: 'id',
        message: `The id "${id}" is used more than once. Ids are unique across the whole document, not per page.`,
        fix: 'Rename the later one. Loading repairs it to a derived id, which silently breaks every link that pointed at it.' })
      return
    }
    seen.add(id)
  }
  for (const p of pages) {
    claim(p.id, { page: p.id }, 'page')
    for (const b of Array.isArray(p.blocks) ? p.blocks : []) claim(b.id, { page: p.id, block: b.id }, 'block')
  }

  const pageIx = new Map(pages.map((p) => [p.id, p]))

  // ---- the page tree ------------------------------------------------------
  for (const p of pages) {
    if (p.parent && !pageIx.has(p.parent)) {
      add({ page: p.id, code: 'no-such-page-parent', severity: 'warning', path: 'parent',
        message: `Page "${p.title}" names parent "${p.parent}", which is not a page in this space.`,
        fix: 'Point parent at a real page id, or remove it. Loading drops it and the page becomes a root page.' })
    }
    // a parent CHAIN that loops never reaches the root, so the page is not in
    // the sidebar at all — the one way a page can be genuinely unreachable
    const walked = new Set<string>([p.id])
    for (let up = p.parent; up; up = pageIx.get(up)?.parent) {
      if (walked.has(up)) {
        add({ page: p.id, code: 'page-cycle', severity: 'error', path: 'parent',
          message: `Page "${p.title}" is inside its own subtree, so the tree never reaches the root and the page never appears in the sidebar.`,
          fix: 'Break the loop: give it a parent outside its own descendants, or none.' })
        break
      }
      walked.add(up)
    }
  }
  if (doc.home && !pageIx.has(doc.home)) {
    add({ code: 'no-such-home', severity: 'warning', path: 'home',
      message: `home names "${doc.home}", which is not a page in this space.`,
      fix: 'Set home to a real page id. Readers land on the first page instead, which may not be the one you wrote to be landed on.' })
  }

  // ---- names and aliases ---------------------------------------------------
  // TWO PAGES CLAIMING ONE NAME is not an error and is not repaired: a file
  // arrives already written, and the resolver has a deterministic answer for
  // it (mentions.ts nameIndex — titles before aliases, then document order).
  // But the answer is invisible from the outside, so `[[Projects]]` lands
  // somewhere the author did not choose and nothing anywhere says why. This is
  // that report: the one place this app tells you about a clash it resolved on
  // your behalf.
  //
  // A page ALIASED to its own title is silently fine — `namesOf` de-duplicates
  // it — so it is not reported. Two pages simply TITLED the same thing is also
  // not reported: that is ordinary and the ids keep them apart everywhere
  // except a `[[wikilink]]`, which is the one case worth a line.
  {
    const claims = new Map<string, Array<{ id: string; title: string; alias: boolean }>>()
    for (const kind of [false, true]) {
      for (const p of pages) {
        if (!p || typeof p.id !== 'string') continue
        const names = kind ? aliasesOf(p) : [String(p.title ?? '')]
        for (const n of names) {
          const k = nameKey(n)
          if (!k) continue
          const list = claims.get(k)
          if (list) { if (!list.some((c) => c.id === p.id)) list.push({ id: p.id, title: String(p.title ?? ''), alias: kind }) }
          else claims.set(k, [{ id: p.id, title: String(p.title ?? ''), alias: kind }])
        }
      }
    }
    for (const [k, list] of claims) {
      if (list.length < 2 || !list.some((c) => c.alias)) continue
      const winner = list[0]
      for (const loser of list.slice(1)) {
        add({
          page: loser.id, code: 'alias-collision', severity: 'warning', path: 'aliases',
          message: `More than one page answers to the name "${k}": ${list.map((c) => `"${c.title}"${c.alias ? ' (alias)' : ' (title)'}`).join(', ')}. A [[${k}]] link resolves to "${winner.title}".`,
          fix: `Rename the alias on "${loser.title}", or remove it. A title always wins over an alias, and among aliases the first page in doc.pages wins — so the page an author meant is not necessarily the page they get.`,
        })
      }
    }
  }

  // ---- the field schema ----------------------------------------------------
  // Only a DECLARED `doc.fields` can be wrong; a document without one gets
  // DEFAULT_FIELDS, which is code.
  const fieldOf = new Map<string, FieldSpec>()
  for (const f of fieldsOf(doc)) {
    if (f && typeof f.key === 'string' && f.key && typeof f.label === 'string') { fieldOf.set(f.key, f); continue }
    add({ code: 'bad-field-schema', severity: 'error', path: 'fields',
      message: `A field in doc.fields has no string key and label (${JSON.stringify(f ?? null).slice(0, 60)}). Writing a value for it THROWS while building its readable form, so the editor's field picker fails on click and the page does not repaint.`,
      fix: 'Give every entry a string `key`, a string `label`, and a `vt` of select | person | number | date | text | labels.' })
  }

  // ---- pages and blocks ---------------------------------------------------
  const usedAssets = new Set<string>()
  for (const p of pages) {
    const blocks = Array.isArray(p.blocks) ? p.blocks : []
    const own = new Set(blocks.map((b) => b.id))
    /** field keys already seen on THIS page — one value per field, per page */
    const propKeys = new Set<string>()

    // ---- the cover -------------------------------------------------------
    // A page's cover is the one asset reference that is not on a block, so it
    // needs saying here or every cover reads as an orphan below. And a REMOTE
    // one renders nothing at all — the field is kept (additivity), but silence
    // is the failure this report exists to break.
    const coverRef = typeof (p as { cover?: unknown }).cover === 'string'
      ? String((p as { cover?: unknown }).cover) : ''
    if (coverRef.startsWith('asset:')) {
      const key = coverRef.slice(6)
      usedAssets.add(key)
      if (!(key in assets)) {
        add({ page: p.id, code: 'missing-asset', severity: 'error', path: 'cover',
          message: `Page "${p.title}" has a cover referencing asset "${key}", which is not in doc.assets — no cover renders.`,
          fix: 'Add the data: URI to doc.assets under that key, or point cover at one that is there.' })
      }
    } else if (coverRef && isRemote(coverRef)) {
      add({ page: p.id, code: 'remote-cover', severity: 'warning', path: 'cover',
        message: `Page "${p.title}" has a remote cover (${coverRef.slice(0, 48)}), which is DROPPED at render — opening a space never contacts a third party.`,
        fix: 'Embed the bytes: put the data: URI in doc.assets and reference it as asset:<key>.' })
    }

    if (!blocks.length) {
      // Not cosmetic: the editor's caret, gutter and / menu all hang off a
      // block, so a page with none cannot be typed into at all. The editor
      // never produces one — model.newPage() always mints a paragraph.
      add({ page: p.id, code: 'no-blocks', severity: 'error', path: 'blocks',
        message: `Page "${p.title}" has no blocks, so there is nothing in it to put a caret in — it cannot be typed into.`,
        fix: 'Give it at least one block, e.g. { "type": "p", "html": "" }.' })
    } else if (!blocks.some((b) => textOf(b.html).trim() || b.type === 'image' || b.type === 'media' || b.type === 'pagelink' || b.type === 'embed' || b.type === 'link' || b.type === 'divider')) {
      add({ page: p.id, code: 'empty-page', severity: 'info',
        message: `Page "${p.title}" has blocks but no content.`,
        fix: 'Write something, or remove the page. A deliberately blank page (an inbox, a stub) is fine — this is only a note.' })
    }

    for (const b of blocks) {
      const at = { page: p.id, block: b.id }

      if (!KNOWN.has(b.type)) {
        add({ ...at, code: 'unknown-block-type', severity: 'warning', path: 'type',
          message: `"${b.type}" is not a block type this build renders — it falls back to showing its html as plain text.`,
          fix: `Use one of: ${KNOWN_BLOCK_TYPES.join(', ')}. The block and its fields survive untouched either way, so a future build can render it.` })
      }

      if (b.parent && !own.has(b.parent)) {
        add({ ...at, code: 'no-such-block-parent', severity: 'warning', path: 'parent',
          message: `Block parent "${b.parent}" is not a block on this page — nesting only works inside one page.`,
          fix: 'Name a block on the same page, or drop parent. Loading drops it and the block un-nests.' })
      }

      // ---- html ----------------------------------------------------------
      if (typeof b.html === 'string' && b.html.includes('<')) {
        const unwrapped: string[] = []
        const dropped: string[] = []
        for (const m of b.html.matchAll(TAG_RE)) {
          const tag = m[1].toLowerCase()
          if (INLINE_OK.has(tag)) continue
          if (UNWRAPPED.has(tag)) { if (!unwrapped.includes(tag)) unwrapped.push(tag) }
          else if (!dropped.includes(tag)) dropped.push(tag)
        }
        if (b.type === 'code' && (unwrapped.length || dropped.length)) {
          add({ ...at, code: 'markup-in-code', severity: 'warning', path: 'html',
            message: `A code block's html is plain TEXT — the renderer shows its textContent, so <${(unwrapped[0] ?? dropped[0])}> disappears and takes its markup with it.`,
            fix: 'Escape it: write &lt;div&gt; rather than <div>. That is what typing into a code block stores.' })
        } else if (b.type !== 'code') {
          if (unwrapped.length) {
            add({ ...at, code: 'block-markup', severity: 'warning', path: 'html',
              message: `html is inline only, and carries block markup (<${unwrapped.join('>, <')}>). The tags are unwrapped at render and the structure is lost.`,
              fix: 'Split it into separate blocks — structure is Block.type, never markup.' })
          }
          if (dropped.length) {
            add({ ...at, code: 'dropped-markup', severity: 'error', path: 'html',
              message: `<${dropped.join('>, <')}> is outside the inline allowlist, so the tag AND everything inside it is removed before anything is shown. That content is invisible to every reader.`,
              fix: 'Use a block type that can carry it (image, code, quote), or inline tags only: b i u s em strong code a span mark sub sup br.' })
          }
        }
        // A TABLE CELL'S LINKS ARE IN `html` TOO, so this scan already sees
        // them: `writeTable` is the one writer and it keeps the fallback html
        // as the cells joined, links intact — which is also how buildIndex
        // finds a backlink from a cell. Scanning `rows` as well would report
        // the same dead link twice.
        for (const m of b.html.matchAll(LINK_RE)) {
          const href = m[1]
          if (href.startsWith('#p/')) {
            // The SAME last-slash rule the resolver and the backlink index use
            // (editor.resolveAnchor / model.linkTarget): `#p/<page>/<block>` is
            // a legal href — sanitize.ts admits it and navigation resolves it to
            // the page — so looking the whole remainder up as a page id reported
            // every block anchor as a broken link, at severity ERROR, with a fix
            // ("remove the link") that would destroy a working link. An agent
            // acting on a false error does more damage than one told nothing.
            const raw = href.slice(3)
            const cut = raw.lastIndexOf('/')
            const target = pageIx.has(raw) || cut <= 0 ? raw : raw.slice(0, cut)
            if (!pageIx.has(target)) {
              add({ ...at, code: 'broken-link', severity: 'error', path: 'html',
                message: `Links to page "${target}", which does not exist — the link renders and does nothing when clicked.`,
                fix: 'Point it at a real page id, create that page, or remove the link.' })
            }
          } else if (!/^(https?:|mailto:)/i.test(href)) {
            add({ ...at, code: 'dead-href', severity: 'warning', path: 'html',
              message: `href "${href.slice(0, 40)}" is outside the allowlist (https:, mailto:, #p/), so the sanitizer drops the link and leaves only its text.`,
              fix: 'Use #p/<pageId> for a page in this space, or an https:/mailto: url.' })
          }
        }
      }

      // ---- per type --------------------------------------------------------
      if (b.type === 'pagelink') {
        const target = typeof b.page === 'string' ? b.page : ''
        if (!target || !pageIx.has(target)) {
          add({ ...at, code: 'broken-link', severity: 'error', path: 'page',
            message: `A pagelink card points at "${target || '(nothing)'}", which is not a page — it renders as "(missing page)".`,
            fix: 'Set page to a real page id, or remove the block.' })
        }
      }

      // AN EMBED IS A PAGELINK THAT SHOWS ITS TARGET, so it can go wrong in
      // three ways instead of one — and every one of them is silent to a
      // reader who never saw the page it was supposed to be showing.
      if (b.type === 'embed') {
        const target = typeof b.page === 'string' ? b.page : ''
        const anchor = anchorOf(b)
        if (!target || !pageIx.has(target)) {
          add({ ...at, code: 'broken-embed', severity: 'error', path: 'page',
            message: `An embed points at "${target || '(nothing)'}", which is not a page — it renders as a note saying so instead of the content.`,
            fix: 'Set page to a real page id, or remove the block.' })
        } else if (embedReaches(doc, p.id, target)) {
          // NAMED, not merely counted: the renderer stops the loop safely (a
          // placeholder where the repeat would be), so this is not a crash
          // waiting to happen — it is content the author believes is on the
          // page and that nobody will ever see.
          add({ ...at, code: 'embed-cycle', severity: 'error', path: 'page',
            message: `This embed of "${pageIx.get(target)?.title ?? target}" leads back to this page, so the loop is cut short and the rest of the embed is not shown.`,
            fix: 'Point the embed at a page that does not embed this one, or narrow it to a section with anchor.' })
        } else if (anchor && !sectionOf(pageIx.get(target)!, anchor)) {
          add({ ...at, code: 'no-section', severity: 'warning', path: 'anchor',
            message: `No heading named "${anchor}" on "${pageIx.get(target)?.title ?? target}" — the embed shows a note instead of that section.`,
            fix: 'Match anchor to a heading on that page, or remove anchor to embed the whole page.' })
        }
      }

      if (b.type === 'link') {
        // A CARD IS NOT A LINK UNTIL ITS URL IS ONE. `linkCard` returns '' for
        // an empty url and for anything outside https:/http:/mailto: — and a
        // card that is not clickable renders as a dead card rather than as a
        // link that silently goes nowhere, so this is the only way to find out.
        const c = linkCard(b)
        if (!c.url) {
          const raw = String(b.url ?? '')
          add({ ...at, code: raw ? 'dead-href' : 'link-no-url', severity: raw ? 'warning' : 'error', path: 'url',
            message: raw
              ? `A link card's url "${raw.slice(0, 40)}" is outside the allowlist (https:, mailto:), so the card renders but is not clickable.`
              : 'A link card has no url, so it renders as an empty card that goes nowhere.',
            fix: 'Set url to an https: or mailto: address. Use a pagelink block for a page in this space.' })
        }
        if (isRemote(String(b.image ?? ''))) {
          add({ ...at, code: 'remote-image', severity: 'warning', path: 'image',
            message: `A link card's image (${String(b.image).slice(0, 48)}) is remote, so it is DROPPED at render — opening a space never contacts a third party.`,
            fix: 'Embed the bytes: put the data: URI in doc.assets and reference it as asset:<key>.' })
        }
      }

      // ---- field values ----------------------------------------------------
      // An ISSUE IS A PAGE and its values are `prop` blocks. Everything that
      // can be wrong here is wrong SILENTLY: the page still renders, the board
      // still draws, and the file still says something — just not what the
      // author meant.
      if (b.type === 'prop') {
        const key = String((b as { key?: unknown }).key ?? '')
        const f = fieldOf.get(key)
        const value = (b as { value?: unknown }).value
        const unset = value === undefined || value === null || value === ''
        if (!key) {
          add({ ...at, code: 'prop-no-key', severity: 'warning', path: 'key',
            message: 'A prop block has no `key`, so it names no field: nothing reads it, the header strip cannot label it, and a board cannot group by it.',
            fix: `Set key to one of: ${[...fieldOf.keys()].join(', ')}.` })
        } else if (!f) {
          // INFO, not a warning: `doc.fields` is additive, so a key this
          // schema does not declare is how a NEWER build's field arrives. The
          // value keeps rendering — the block carries its own html — but this
          // build cannot label it or edit it.
          add({ ...at, code: 'unknown-field-key', severity: 'info', path: 'key',
            message: `"${key}" is not a field in doc.fields, so its value shows only as the text in its html and cannot be edited or grouped by here.`,
            fix: `Add { "key": "${key}", "label": "…", "vt": "text" } to doc.fields, or use one of: ${[...fieldOf.keys()].join(', ')}.` })
        } else if (f.vt === 'select' && !unset && !optionOf(f, value)) {
          // INFO for the same reason: an option a newer build declared must
          // survive this one untouched. It is still worth saying, because the
          // OTHER way to get here is typing a label ('In progress') where an
          // id ('doing') belongs, and then wondering why the board files it
          // under "Other".
          add({ ...at, code: 'unknown-field-value', severity: 'info', path: 'value',
            message: `"${String(value)}" is not one of ${key}'s options, so it is shown verbatim and grouped apart from the rest.`,
            fix: `Use an option id — ${(f.options ?? []).map((o) => o.id).join(', ')} — or declare this one in doc.fields. The value is kept either way.` })
        } else if (b.html !== propHtml(f, value)) {
          // THE ONE THAT MATTERS. `html` is what an older build, a
          // thumbnailer, a grep and the markdown export see, and it is ALL
          // they see. A value edited without it says one thing to this build
          // and another to every one of them, forever, with nothing to notice
          // it — which is the whole degradation guarantee, broken silently.
          //
          // Deliberately NOT checked when the value names no known option
          // (above): the writer knew a label this build does not, so its html
          // is RIGHT and ours would be the guess.
          add({ ...at, code: 'prop-html-stale', severity: 'warning', path: 'html',
            message: `This value's readable form disagrees with its value: html is ${JSON.stringify(b.html ?? '')} where the value reads "${propHtml(f, value)}". An older build, a thumbnailer, a grep and the markdown export show the html — so they all show the wrong value.`,
            fix: 'Write both together: bento.setField(page, key, value) does, and so does the editor. Never assign `value` on its own.' })
        }
        if (key) {
          if (propKeys.has(key)) {
            add({ ...at, code: 'duplicate-prop', severity: 'warning', path: 'key',
              message: `This page carries more than one value for "${key}". A reader takes the LAST one, so the earlier block is a value that is shown in the header, found by search, and ignored by every query.`,
              fix: 'Remove the duplicate block. bento.setField writes all of them at once while they exist, so the page at least cannot disagree with itself.' })
          }
          propKeys.add(key)
        }
      }

      const src = typeof b.src === 'string' ? b.src : ''
      if (src.startsWith('asset:')) usedAssets.add(src.slice(6))
      // a video's poster is a second reference into the asset table, and one
      // this sweep did not see — so the still an author picked would read as an
      // orphan and validate() would advise deleting it
      const posterRef = typeof b.poster === 'string' ? b.poster : ''
      if (posterRef.startsWith('asset:')) usedAssets.add(posterRef.slice(6))
      if (b.type === 'image' || b.type === 'media') {
        const what = b.type === 'media'
          ? (String(b.kind ?? 'video') === 'audio' ? 'An audio' : 'A video')
          : 'An image'
        if (!src) {
          add({ ...at, code: `${b.type}-no-src`, severity: b.type === 'media' ? 'warning' : 'error', path: 'src',
            // a media block with no src is a CHOOSER, not a hole: the editor
            // inserts one and asks for the file second, so an unfinished block
            // is a normal intermediate state rather than a broken document
            message: b.type === 'media'
              ? `${what} block has no src, so it renders as a "choose a file" box.`
              : 'An image block has no src, so nothing renders.',
            fix: 'Set src to asset:<key>, a data: URI, or an https: address.' })
        } else if (src.startsWith('asset:') && !(src.slice(6) in assets)) {
          add({ ...at, code: 'missing-asset', severity: 'error', path: 'src',
            message: `src references asset "${src.slice(6)}", which is not in doc.assets — nothing renders.`,
            fix: 'Add the data: URI to doc.assets under that key, or point src at one that is there.' })
        } else if (isRemote(src)) {
          add({ ...at, code: b.type === 'media' ? 'remote-media' : 'remote-image', severity: 'warning', path: 'src',
            message: `src is remote (${src.slice(0, 48)}), so it shows a placeholder naming the host until the reader agrees to load it. Opening a document never contacts a third party.`,
            fix: 'Embed the bytes: put the data: URI in doc.assets and reference it as asset:<key>.' })
        }
        if (!String(b.alt ?? '').trim()) {
          add({ ...at, code: 'image-no-alt', severity: 'warning', path: 'alt',
            message: `${what} block has no alt text — screen readers get nothing, and alt is what a reader SEES if it is remote and unloaded.`,
            fix: 'Write what it shows, in a sentence.' })
        }
        // AUDIO HAS NO PIXELS. The intrinsic size is about the aspect box that
        // holds the layout still while a picture decodes, and an audio player
        // is a fixed-height control that never reflows anything — so asking for
        // w/h on one is asking an author to write down a number that does not
        // exist. Every correctly-authored audio block would have carried this
        // finding, which is the false positive that teaches an agent to stop
        // reading them.
        if (!isAudio(b) && (!b.w || !b.h)) {
          add({ ...at, code: 'image-no-size', severity: 'info', path: 'w',
            message: 'No intrinsic w/h, so the page reflows under the reader as the image decodes.',
            fix: 'Set w and h to the image\'s pixel size.' })
        }
      }
    }
  }

  // ---- the design ----------------------------------------------------------
  // Validated, never sanitized: every value a doc-local design carries is
  // checked against a closed rule, and one that fails is DROPPED to the base
  // design's value. The document still opens and still looks designed — so
  // this is the only place an author finds out a colour was not used.
  for (const pr of designProblems(doc)) {
    add({ ...(pr.page ? { page: pr.page } : {}), code: pr.code, path: pr.path, message: pr.message,
      severity: pr.code === 'unknown-design-key' ? 'info' : 'warning',
      fix: pr.code === 'unknown-design'
        ? (pr.page
          ? `Set this page's design to one of ${BUILT_IN_NAMES.join(', ')} or a name under designs, or delete the key so the page inherits its parent's.`
          : `Set design to one of ${BUILT_IN_NAMES.join(', ')}, define it under designs, or delete the key for the default look.`)
        : pr.code === 'design-shadows-builtin' || pr.code === 'bad-design-name'
          ? 'Rename the entry (lowercase letters, digits, hyphens; not a built-in name) and point design at the new name.'
          : 'Write a value the rule accepts (see docs/spaces-agents.md, Designs), or delete the key to take the base design\'s.' })
  }
  for (const k of designAssetKeys(doc)) {
    if (!(k in assets)) {
      add({ code: 'missing-asset', severity: 'error', path: 'designs',
        message: `A design names embedded font asset "${k}", which is not in doc.assets — the face never loads and text falls back to the role's stack.`,
        fix: 'Add the font data: URI under that key, or point the font role at a name from the list.' })
    }
    usedAssets.add(k)
  }

  // ---- assets --------------------------------------------------------------
  for (const f of doc.fonts ?? []) {
    if (f.asset && !(f.asset in assets)) {
      add({ code: 'missing-asset', severity: 'error', path: `fonts.${f.family}`,
        message: `Font "${f.family}" names asset "${f.asset}", which is not in doc.assets — the face never loads and text silently falls back.`,
        fix: 'Add the woff2 data: URI under that key, or drop the font entry.' })
    }
    usedAssets.add(f.asset)
  }
  const orphans = orphanAssets(doc)
  if (orphans.length) {
    // ONE finding, not one per key: an author who deleted a photo-heavy page
    // has dozens, and the actionable fact is the total.
    let bytes = 0
    for (const k of orphans) bytes += (assets[k] ?? '').length
    add({ code: 'orphan-asset', severity: 'info', path: 'assets',
      message: `${orphans.length} asset(s) (${humanBytes(bytes)}) are in doc.assets but referenced by nothing.`,
      fix: `Delete these keys to shrink the file: ${orphans.slice(0, 8).join(', ')}${orphans.length > 8 ? ', …' : ''}` })
  }

  // ---- footnotes -----------------------------------------------------------
  // BOTH HALVES ARE REPORTED AND NEITHER IS AN ERROR, because neither loses a
  // word: a dangling reference still shows the `[^1]` the author typed and a
  // note nothing points at is still the note they wrote. What they lose is the
  // CONNECTION, and a connection is exactly the thing an author cannot see is
  // missing by reading the page. Neither can throw — every lookup here goes
  // through footnotes.ts, which uses Object.hasOwn and tolerates a
  // `"footnotes": "yes"` out of a hand-edited file.
  for (const d of danglingRefs(doc)) {
    add({ page: d.pageId, block: d.blockId, code: 'dangling-footnote', severity: 'warning', path: 'footnotes',
      message: `A footnote reference [^${d.label}] has no note behind it, so it renders as the literal text "[^${d.label}]" instead of a number.`,
      fix: `Add "${d.label}" to doc.footnotes, or delete the [^${d.label}] from the text.` })
  }
  const loose = orphanNotes(doc)
  if (loose.length) {
    // ONE finding, like the orphan assets above and for the same reason: the
    // actionable fact is the total plus the labels, not a row each.
    add({ code: 'orphan-footnote', severity: 'info', path: 'footnotes',
      message: `${loose.length} footnote(s) in doc.footnotes are referenced by nothing, so they are never numbered and never printed: ${loose.slice(0, 8).join(', ')}${loose.length > 8 ? ', …' : ''}`,
      fix: 'Put a [^label] back in the text, or delete the key from doc.footnotes.' })
  }
  const rawNotes = (doc as { footnotes?: unknown }).footnotes
  if (rawNotes && typeof rawNotes === 'object' && !Array.isArray(rawNotes)) {
    // A label outside the token grammar can never be REFERENCED — `[^a b]`
    // does not match — so the note is unreachable however many times it is
    // written into the prose. Silent, and only findable from here.
    const bad = Object.keys(rawNotes as object).filter((k) => !LABEL_OK.test(k))
    if (bad.length) {
      add({ code: 'unreachable-footnote', severity: 'warning', path: 'footnotes',
        message: `${bad.length} footnote label(s) are outside the reference grammar (letters, digits, "_" and "-", up to 32), so no [^label] can ever point at them: ${bad.slice(0, 5).map((b) => JSON.stringify(b)).join(', ')}`,
        fix: 'Rename the key to a plain label and update the [^label] in the text.' })
    }
  }

  const counts: Record<Severity, number> = { error: 0, warning: 0, info: 0 }
  for (const f of findings) counts[f.severity]++
  return { ok: counts.error === 0, counts, findings }
}

// ---------------------------------------------------------------------------
// outline()
// ---------------------------------------------------------------------------

export interface OutlineHeading { id: string; level: 1 | 2 | 3; text: string }

export interface OutlineNode {
  id: string
  title: string
  /** 0 for a root page */
  depth: number
  parent?: string
  icon?: string
  archived?: true
  /** the landing page */
  home?: true
  blocks: number
  words: number
  headings?: OutlineHeading[]
  /** page ids this page links to, deduped — inline #p/ links and pagelink cards */
  links?: string[]
}

export interface OutlineResult {
  title: string
  docId: string
  pages: number
  blocks: number
  words: number
  tree: OutlineNode[]
}

/**
 * The whole space in one call, in sidebar order.
 *
 * Orientation used to cost one `getPage` per page — for a 200-page handbook
 * that is 200 round trips and the entire document in context, to answer "where
 * does the onboarding material live". Headings carry their block id so the
 * answer is directly actionable: what comes back can be passed straight to
 * updateBlock or moveBlock.
 */
export function outlineDoc(doc: SpacesDoc): OutlineResult {
  const ix = buildIndex(doc)
  const tree: OutlineNode[] = []
  const emitted = new Set<string>()

  const node = (p: Page, depth: number): OutlineNode => {
    const headings: OutlineHeading[] = []
    const links: string[] = []
    let w = 0
    for (const b of p.blocks) {
      const text = textOf(b.html)
      w += words(text)
      if (b.type === 'h1' || b.type === 'h2' || b.type === 'h3') {
        headings.push({ id: b.id, level: Number(b.type.slice(1)) as 1 | 2 | 3, text })
      }
      // pagelink AND embed: both name a page, and an outline that listed only
      // the first would under-report exactly the dependency that hurts most.
      if (isPageRef(b) && !links.includes(String(b.page))) links.push(String(b.page))
      for (const m of (b.html ?? '').matchAll(/href\s*=\s*["']#p\/([^"']+)["']/g)) {
        if (!links.includes(m[1])) links.push(m[1])
      }
    }
    return {
      id: p.id, title: p.title, depth,
      ...(p.parent ? { parent: p.parent } : {}),
      ...(p.icon ? { icon: p.icon } : {}),
      ...(p.archived ? { archived: true as const } : {}),
      ...(doc.home === p.id ? { home: true as const } : {}),
      blocks: p.blocks.length,
      words: w,
      ...(headings.length ? { headings } : {}),
      ...(links.length ? { links } : {}),
    }
  }

  const walk = (parent: string, depth: number) => {
    for (const p of ix.children.get(parent) ?? []) {
      if (emitted.has(p.id)) continue // a parent cycle would otherwise recurse forever
      emitted.add(p.id)
      tree.push(node(p, depth))
      walk(p.id, depth + 1)
    }
  }
  walk('', 0)
  // A page inside its own subtree is in no walk from the root. It is still in
  // the file and still linkable, so it must appear here — an outline that
  // silently omits pages is worse than no outline. validate() names the cycle.
  for (const p of doc.pages) if (!emitted.has(p.id)) tree.push(node(p, 0))

  return {
    title: doc.title,
    docId: doc.docId,
    pages: doc.pages.length,
    blocks: doc.pages.reduce((n, p) => n + p.blocks.length, 0),
    words: tree.reduce((n, t) => n + t.words, 0),
    tree,
  }
}

// ---------------------------------------------------------------------------
// stats()
// ---------------------------------------------------------------------------

export interface AssetStat { key: string; bytes: number; mime: string; used: number }

export interface StatsResult {
  pages: number
  archived: number
  blocks: number
  words: number
  characters: number
  blockTypes: Record<string, number>
  todos: { done: number; total: number }
  assets: { count: number; bytes: number; orphans: number; orphanBytes: number }
  /** UTF-8 bytes of the document JSON. The shell adds a fixed ~600 KB on top. */
  bytes: { document: number; assets: number; text: number }
  /** the ten largest assets, biggest first */
  biggest: AssetStat[]
}

/**
 * Where the weight is — the call that answers "why is this file 30MB".
 *
 * Prose is free (2,000 pages of it is ~5MB); images are the entire story, and
 * an asset nothing references costs exactly as much as one that does. So the
 * breakdown is by asset, largest first, with a use count beside each.
 */
export function statsDoc(doc: SpacesDoc): StatsResult {
  const assets = doc.assets ?? {}
  const blockTypes: Record<string, number> = {}
  const use = new Map<string, number>()
  const todos = { done: 0, total: 0 }
  let blocks = 0
  let wordCount = 0
  let characters = 0
  let textBytes = 0

  for (const p of doc.pages) {
    for (const b of p.blocks) {
      blocks++
      blockTypes[b.type] = (blockTypes[b.type] ?? 0) + 1
      if (b.type === 'todo') { todos.total++; if (b.done) todos.done++ }
      const text = textOf(b.html)
      wordCount += words(text)
      characters += text.length
      textBytes += utf8len(b.html ?? '')
      for (const v of [b.src, (b as Record<string, unknown>).poster]) {
        if (typeof v === 'string' && v.startsWith('asset:')) {
          const k = v.slice(6)
          use.set(k, (use.get(k) ?? 0) + 1)
        }
      }
    }
    // the cover is a reference too, and one that is not on any block
    for (const k of pageAssetKeys(p)) use.set(k, (use.get(k) ?? 0) + 1)
  }
  for (const f of doc.fonts ?? []) use.set(f.asset, (use.get(f.asset) ?? 0) + 1)

  let assetBytes = 0
  const each: AssetStat[] = []
  for (const [key, value] of Object.entries(assets)) {
    // a data: URI is ASCII, so length IS bytes and this stays O(1) per asset
    const bytes = value.length
    assetBytes += bytes
    each.push({ key, bytes, mime: /^data:([^;,]+)/.exec(value)?.[1] ?? 'unknown', used: use.get(key) ?? 0 })
  }
  each.sort((a, b) => b.bytes - a.bytes)
  const orphans = each.filter((a) => !a.used)

  return {
    pages: doc.pages.length,
    archived: doc.pages.filter((p) => p.archived).length,
    blocks,
    words: wordCount,
    characters,
    blockTypes,
    todos,
    assets: {
      count: each.length,
      bytes: assetBytes,
      orphans: orphans.length,
      orphanBytes: orphans.reduce((n, a) => n + a.bytes, 0),
    },
    bytes: { document: utf8len(JSON.stringify(doc)), assets: assetBytes, text: textBytes },
    biggest: each.slice(0, 10),
  }
}

// ---------------------------------------------------------------------------
// the write verbs
// ---------------------------------------------------------------------------

export type Plan<T> = ({ ok: true; apply: () => void } & T) | PlanError

export interface PlanError {
  ok: false
  /** machine-readable: 'readonly' | 'no-such-block' | 'no-such-page' | 'bad-patch' |
   *  'immutable' | 'not-serializable' | 'cycle' | 'last-page' */
  err: string
  detail?: string
}

const fail = (err: string, detail?: string): PlanError => ({ ok: false, err, ...(detail ? { detail } : {}) })

const isPatch = (v: unknown): v is Record<string, unknown> =>
  !!v && typeof v === 'object' && !Array.isArray(v)

/** Split a patch into writes and deletes; `null`/`undefined` means delete. */
function splitPatch(patch: Record<string, unknown>): { sets: Record<string, unknown>; dels: string[] } | PlanError {
  const sets: Record<string, unknown> = {}
  const dels: string[] = []
  for (const [k, v] of Object.entries(patch)) {
    if (v === null || v === undefined) { dels.push(k); continue }
    if (!jsonSafe(v)) {
      return fail('not-serializable', `"${k}" holds something JSON cannot carry (a function, a DOM node, a Date, a cycle). It would vanish or throw at save time.`)
    }
    sets[k] = v
  }
  return { sets, dels }
}

/**
 * Insert blocks into a page. Ids are minted here, never taken from the caller,
 * so an agent cannot collide with an id that already exists in the document.
 *
 * Because the ids are re-minted, a block in the batch could not previously name
 * another block in the same batch as its `parent` — the id it would have to
 * name does not exist yet. So `parent` is REMAPPED against the batch's own
 * supplied ids: send a toggle and its body in one call and the nesting holds.
 * A parent that resolves to neither the batch nor the page is dropped, because
 * a dangling parent renders un-nested and is deleted at the next load anyway.
 *
 * `afterId` naming a block that is not on the page is an ERROR, not an append.
 * It used to append silently, which put the content somewhere the agent did not
 * ask for and reported success.
 */
/**
 * A `prop` block's readable form, re-derived from its value. ALWAYS.
 *
 * The degradation guarantee — "an older build, a thumbnailer, a grep and the
 * markdown export all see 'Status: In progress'" — was claimed by setField and
 * enforced nowhere else. Measured on this build: `updateBlock(id,{value:'doing'})`
 * left `html:'Status: Todo'`, so the file SAID Todo while its value said doing;
 * and `insertBlocks` with a prop block wrote no `html` at all. A guarantee that
 * one writer keeps and three writers break is not a guarantee.
 *
 * So it is applied where blocks are WRITTEN, not where fields are set: every
 * verb goes through here, and a verb added later gets it without knowing.
 * An unknown key has no spec and keeps whatever it was given — that is a value
 * from a newer build, not an error.
 */
function syncProp(doc: SpacesDoc, b: Block): void {
  if (b.type !== 'prop') return
  const key = String((b as Record<string, unknown>).key ?? '')
  const f = key ? fieldByKey(doc, key) : undefined
  if (!f || typeof f.label !== 'string') return
  ;(b as Record<string, unknown>).html = propHtml(f, (b as Record<string, unknown>).value)
}

export function planInsertBlocks(
  doc: SpacesDoc, pageId: string, afterId: string | null, blocks: unknown,
): Plan<{ ids: string[]; page: string }> {
  if (!Array.isArray(blocks)) return fail('bad-patch', 'pass an array of blocks')
  const page = doc.pages.find((p) => p.id === pageId)
  if (!page) return fail('no-such-page', String(pageId))
  if (afterId != null && !page.blocks.some((b) => b.id === afterId)) {
    return fail('no-such-block', `"${afterId}" is not a block on page "${pageId}"`)
  }

  const remap = new Map<string, string>()
  const made: Block[] = []
  for (const raw of blocks) {
    if (raw != null && !jsonSafe(raw)) return fail('not-serializable', 'a block holds something JSON cannot carry')
    const src = isPatch(raw) ? raw : {}
    const type = typeof src.type === 'string' && src.type ? src.type : 'p'
    const b = { ...src, id: uid('b'), type } as Block
    if (typeof src.id === 'string' && src.id) remap.set(src.id, b.id)
    if (typeof b.html === 'string') b.html = normalizeHtml(b.html, type)
    syncProp(doc, b)   // a field value is nothing without its readable form
    made.push(b)
  }
  for (const b of made) {
    if (typeof b.parent !== 'string') continue
    const within = remap.get(b.parent)
    if (within) b.parent = within
    else if (!page.blocks.some((x) => x.id === b.parent)) delete b.parent
  }

  return {
    ok: true, ids: made.map((b) => b.id), page: page.id,
    apply() {
      const at = afterId == null ? page.blocks.length : page.blocks.findIndex((b) => b.id === afterId) + 1
      page.blocks.splice(at, 0, ...made)
    },
  }
}

/**
 * Change fields on one block. `null` deletes a field.
 *
 * `id` is refused rather than ignored: a silent no-op on the one field that
 * links, backlinks and undo all key on is how an agent ends up believing it
 * renamed something.
 */
export function planUpdateBlock(doc: SpacesDoc, id: string, patch: unknown): Plan<{ id: string; page: string }> {
  if (!isPatch(patch)) return fail('bad-patch', 'patch must be an object of block fields')
  const at = findBlock(doc, id)
  if (!at) return fail('no-such-block', id)
  if ('id' in patch) return fail('immutable', 'a block id never changes — links, backlinks and undo key on it')

  const { block, page } = at
  const type = 'type' in patch ? patch.type : block.type
  if (typeof type !== 'string' || !type) return fail('bad-patch', 'type must be a non-empty string')

  if ('parent' in patch && patch.parent != null) {
    const owner = String(patch.parent)
    if (owner === id) return fail('cycle', 'a block cannot be its own parent')
    if (!page.blocks.some((b) => b.id === owner)) return fail('no-such-block', `parent "${owner}" is not a block on page "${page.id}"`)
    if (descendants(page, id).has(owner)) return fail('cycle', `parent "${owner}" is nested inside "${id}"`)
  }

  const split = splitPatch(patch)
  if ('ok' in split) return split
  const { sets, dels } = split
  if (dels.includes('type')) return fail('bad-patch', 'type cannot be deleted; set it to another type instead')

  if (typeof sets.html === 'string') sets.html = normalizeHtml(sets.html, type)
  else if (sets.type && typeof block.html === 'string' && (sets.type === 'code') !== (block.type === 'code')) {
    // code stores escaped text and everything else stores inline html, so a
    // retype in either direction has to re-normalize what is already there
    sets.html = normalizeHtml(block.html, type)
  }

  return {
    ok: true, id, page: page.id,
    apply() {
      for (const k of dels) delete (block as Record<string, unknown>)[k]
      const retyped = typeof sets.type === 'string' && sets.type !== block.type
      Object.assign(block, sets)
      syncProp(doc, block)   // value and readable form move together, always
      // A TYPE CHANGE RUNS THE REGISTRY'S init, exactly as the editor's setType
      // does. Without it an agent-written callout has no `tone` and an
      // agent-written to-do has no `done` — documents the app itself could not
      // have produced, from the API whose whole promise is that it produces
      // documents the app could have produced.
      if (retyped) SPEC.get(block.type)?.init?.(block)
    },
  }
}

/**
 * Remove blocks, with anything nested under them.
 *
 * The cascade is not a convenience: a toggle's body is `parent`-linked, so
 * deleting the toggle alone would leave blocks pointing at an id that no longer
 * exists — loading re-homes them and they reappear, un-nested, in a document
 * the agent believed it had emptied.
 *
 * A page emptied down to nothing gets one fresh paragraph, because the editor's
 * caret, gutter and / menu all hang off a block: a page with none can never be
 * typed into again.
 */
export function planRemoveBlocks(doc: SpacesDoc, ids: unknown): Plan<{ removed: string[]; missing: string[]; added: string[] }> {
  if (!Array.isArray(ids)) return fail('bad-patch', 'pass an array of block ids')
  const perPage = new Map<Page, Set<string>>()
  const missing: string[] = []
  const removed: string[] = []

  for (const raw of ids) {
    const id = String(raw)
    const at = findBlock(doc, id)
    if (!at) { missing.push(id); continue }
    const set = perPage.get(at.page) ?? new Set<string>()
    perPage.set(at.page, set)
    for (const victim of [id, ...descendants(at.page, id)]) {
      if (!set.has(victim)) { set.add(victim); removed.push(victim) }
    }
  }

  const refills: Array<[Page, Block]> = []
  for (const [page, set] of perPage) {
    if (page.blocks.every((b) => set.has(b.id))) refills.push([page, newBlock('p')])
  }

  return {
    ok: true, removed, missing, added: refills.map(([, b]) => b.id),
    apply() {
      for (const [page, set] of perPage) page.blocks = page.blocks.filter((b) => !set.has(b.id))
      for (const [page, fresh] of refills) page.blocks.push(fresh)
    },
  }
}

export interface MoveTarget {
  /** the page to move to; omit to stay on the current one */
  pageId?: string
  /** place it after this block */
  afterId?: string
  /** place it before this block (wins over afterId) */
  beforeId?: string
  /** re-nest under this block; null clears nesting */
  parent?: string | null
}

/**
 * Move a block, with its nested blocks, within or across pages.
 *
 * Neither anchor given = the end of the page, which is what `insertBlocks(page,
 * null, …)` already means. `beforeId` exists because otherwise the first
 * position in a page is unreachable.
 */
export function planMoveBlock(doc: SpacesDoc, id: string, to: unknown): Plan<{ id: string; pageId: string; moved: string[] }> {
  if (to !== undefined && !isPatch(to)) return fail('bad-patch', 'pass { pageId?, afterId?, beforeId?, parent? }')
  const spec = (to ?? {}) as MoveTarget
  const at = findBlock(doc, id)
  if (!at) return fail('no-such-block', id)
  const from = at.page

  const dest = spec.pageId ? doc.pages.find((p) => p.id === spec.pageId) : from
  if (!dest) return fail('no-such-page', String(spec.pageId))

  const kin = descendants(from, id)
  const group = from.blocks.filter((b) => b.id === id || kin.has(b.id))
  const anchorId = spec.beforeId ?? spec.afterId
  if (anchorId != null) {
    if (kin.has(String(anchorId)) || String(anchorId) === id) return fail('cycle', 'a block cannot be moved inside its own subtree')
    if (!dest.blocks.some((b) => b.id === anchorId)) return fail('no-such-block', `"${anchorId}" is not a block on page "${dest.id}"`)
  }

  let parent: string | null | undefined = spec.parent
  if (parent != null) {
    const owner = String(parent)
    if (owner === id || kin.has(owner)) return fail('cycle', 'a block cannot be nested under itself')
    if (!dest.blocks.some((b) => b.id === owner)) return fail('no-such-block', `parent "${owner}" is not a block on page "${dest.id}"`)
  } else if (parent === undefined) {
    // keep the nesting only while it still names something on the destination
    // page — carried across pages it would be a parent that does not exist,
    // which renders un-nested and is dropped at the next load
    parent = at.block.parent && dest.blocks.some((b) => b.id === at.block.parent) ? at.block.parent : null
  }

  return {
    ok: true, id, pageId: dest.id, moved: group.map((b) => b.id),
    apply() {
      from.blocks = from.blocks.filter((b) => !group.includes(b))
      if (parent) at.block.parent = parent
      else delete at.block.parent
      const anchor = anchorId != null ? dest.blocks.findIndex((b) => b.id === anchorId) : -1
      const cut = anchor < 0 ? dest.blocks.length : spec.beforeId != null ? anchor : anchor + 1
      dest.blocks.splice(cut, 0, ...group)
    },
  }
}

/**
 * Change a page's own fields. `blocks` is refused — block structure goes
 * through insertBlocks/updateBlock/removeBlocks/moveBlock, each of which keeps
 * ids, nesting and undo coherent; assigning the array wholesale keeps none of
 * them.
 */
export function planUpdatePage(doc: SpacesDoc, id: string, patch: unknown): Plan<{ id: string }> {
  if (!isPatch(patch)) return fail('bad-patch', 'patch must be an object of page fields')
  const page = doc.pages.find((p) => p.id === id)
  if (!page) return fail('no-such-page', id)
  if ('id' in patch) return fail('immutable', 'a page id never changes — every #p/ link and backlink keys on it')
  if ('blocks' in patch) return fail('immutable', 'use insertBlocks / updateBlock / removeBlocks / moveBlock for block structure')

  const split = splitPatch(patch)
  if ('ok' in split) return split
  const { sets, dels } = split

  if ('title' in sets) {
    if (badTitle(sets.title)) return fail('bad-title', 'title must be a string')
    // the title renders as textContent, so markup in it would show literally
    sets.title = plainTitle(sets.title)
  }
  if ('parent' in sets) {
    const owner = String(sets.parent)
    if (owner === id) return fail('cycle', 'a page cannot contain itself')
    if (!doc.pages.some((p) => p.id === owner)) return fail('no-such-page', `parent "${owner}"`)
    // BOUNDED. A cycle already in the document (A.parent=B, B.parent=A)
    // survives parseDoc — it only drops parents that name no page — so it
    // arrives from any hand-edited or mailed file, and this walk ran forever:
    // measured, the call never returns and the tab dies with every unsaved edit
    // in it. The reachable sequence is the RECOMMENDED one — validate() reports
    // `page-cycle`, the agent re-homes a page to fix it, and that call hangs.
    // validateDoc next door already carries this set.
    const seen = new Set<string>()
    for (let up: string | undefined = owner; up && !seen.has(up); up = doc.pages.find((p) => p.id === up)?.parent) {
      seen.add(up)
      if (up === id) return fail('cycle', `"${owner}" is inside "${id}"`)
    }
    sets.parent = owner
  }
  if ('archived' in sets) {
    // the editor DELETES the key rather than writing false, and two spellings
    // of "not archived" in saved files is the kind of drift that costs a
    // format its simplicity
    if (sets.archived) sets.archived = true
    else { delete sets.archived; dels.push('archived') }
  }

  return {
    ok: true, id,
    apply() {
      for (const k of dels) delete (page as Record<string, unknown>)[k]
      Object.assign(page, sets)
    },
  }
}

export interface RemovePageOpts {
  /** delete the pages nested under it too; default re-homes them a level up */
  descendants?: boolean
}

/**
 * Remove a page.
 *
 * Children are re-homed to the removed page's parent by default — the editor's
 * rule, and for its reason: deleting a middle page should not silently take a
 * subtree nobody was looking at. `{ descendants: true }` is the explicit way to
 * take the subtree.
 *
 * `links` in the result counts the inbound links that just went dead. There is
 * no undoing someone else's expectation of what a link meant, so the number is
 * reported rather than the removal refused.
 */
export function planRemovePage(doc: SpacesDoc, id: string, opts: RemovePageOpts = {}): Plan<{ removed: string[]; rehomed: number; links: number }> {
  const page = doc.pages.find((p) => p.id === id)
  if (!page) return fail('no-such-page', id)
  if (doc.pages.length <= 1) return fail('last-page', 'a space needs at least one page')

  const doomed = new Set<string>([id])
  if (opts.descendants) {
    let grew = true
    while (grew) {
      grew = false
      for (const p of doc.pages) {
        if (p.parent && doomed.has(p.parent) && !doomed.has(p.id)) { doomed.add(p.id); grew = true }
      }
    }
  }
  if (doomed.size >= doc.pages.length) return fail('last-page', 'that would remove every page in the space')

  const rehome = opts.descendants ? [] : doc.pages.filter((p) => p.parent === id)
  const ix = buildIndex(doc)
  let links = 0
  for (const gone of doomed) {
    for (const ref of ix.backlinks.get(gone) ?? []) if (!doomed.has(ref.pageId)) links++
  }

  return {
    ok: true, removed: [...doomed], rehomed: rehome.length, links,
    apply() {
      for (const p of rehome) {
        if (page.parent) p.parent = page.parent
        else delete p.parent
      }
      doc.pages = doc.pages.filter((p) => !doomed.has(p.id))
      if (doc.home && doomed.has(doc.home)) delete doc.home
    },
  }
}

// ---------------------------------------------------------------------------
// the tracker: the schema, the values, the backlog
// ---------------------------------------------------------------------------
//
// AN ISSUE IS A PAGE (docs/DECISIONS.md, 2026-08-05). Its field values are
// `prop` BLOCKS; the schema they draw on is `doc.fields`. Nothing here is a
// page-level key and nothing is a new page type.
//
// WHY THESE VERBS EXIST AT ALL. An agent could already write a prop block by
// hand through insertBlocks — and get the `html` wrong, which is the one thing
// that must never happen: that string is what an older build, a thumbnailer, a
// grep and the markdown export see, and it is ALL they see. A value written
// without it is a value those readers cannot read. So the only supported way to
// set a value goes through fields.ts propHtml(), exactly as the editor's own
// field picker does, and the two cannot drift because they are the same call.

/** The schema in force, as data. */
export function fieldsReport(doc: SpacesDoc): FieldSpec[] {
  // A COPY. `fieldsOf` hands back DEFAULT_FIELDS itself when the document
  // declares no schema of its own, and that array is module state shared by
  // every document opened in this session — one `bento.fields()[0].options.pop()`
  // would edit the schema of documents that have not been loaded yet.
  return JSON.parse(JSON.stringify(fieldsOf(doc))) as FieldSpec[]
}

export interface FieldWarning {
  code: 'unknown-option'
  key: string
  detail: string
  /** the ids that ARE options, so the caller can correct itself */
  options: string[]
}

/**
 * Is this a value the field's own options know?
 *
 * DELIBERATELY A WARNING, NOT A REFUSAL. The format is permanent and additive:
 * a status a NEWER build declared must round-trip through this one verbatim,
 * and a verb that refused it would make an older build unable to edit a
 * document a newer one wrote — the exact failure the additivity rule exists to
 * prevent. But an agent typing 'In progress' where the option id is 'doing' has
 * made a mistake, and silence would leave it believing otherwise: the value
 * would be stored, the board would file it under "Other", and nothing would
 * have said so. So it is written AND reported, with the ids listed.
 *
 * An empty value is "not set", never an unknown option — the editor itself
 * writes `''` for a select with no default (fields.ts `def`), so flagging it
 * would fire on documents this build produced.
 */
function optionWarning(f: FieldSpec, value: unknown): FieldWarning | undefined {
  if (f.vt !== 'select' || value === '' || value === null || value === undefined) return undefined
  if (optionOf(f, value)) return undefined
  const options = (f.options ?? []).map((o) => o.id)
  return {
    code: 'unknown-option', key: f.key, options,
    detail: `"${String(value)}" is not one of ${f.key}'s options (${options.join(', ')}). It was written unchanged — the format keeps a value a newer build may have declared — but if you meant an existing option, use its id, not its label.`,
  }
}

/** ONE refusal, worded once: both write verbs reject the same mistake. */
const noSuchField = (k: string, schema: FieldSpec[]): PlanError =>
  fail('no-such-field', `"${k}" is not a field in this space. The schema is doc.fields, which declares: ${schema.map((x) => x.key).join(', ')}. Add the field there first — a value whose field nothing declares cannot be labelled, edited or grouped by.`)

export interface SetFieldResult {
  pageId: string
  key: string
  value: unknown
  /** the readable form written with it — what an older build shows */
  html?: string
  /** the prop blocks that now hold the value (or that were just removed) */
  blocks: string[]
  /** the page had no value for this field and one was added to the header */
  created: boolean
  /** the value was cleared: those prop blocks are gone */
  removed: boolean
  warning?: FieldWarning
}

/**
 * Set one field on one page — the ONE undoable step that writes a field value.
 *
 * `null` (or `undefined`) CLEARS the field: the prop block goes, which is the
 * convention the patch verbs already use, and is how a page stops being an
 * issue (clear its status and it is a document again, body intact). Clearing a
 * field that is not set is not an error; the call is idempotent.
 *
 * The page need not already be an issue. Setting `status` on any page is
 * precisely what makes it one — there is no flag to set and no type to change.
 */
export function planSetField(doc: SpacesDoc, pageId: string, key: unknown, value: unknown): Plan<SetFieldResult> {
  const page = doc.pages.find((p) => p.id === pageId)
  if (!page) return fail('no-such-page', String(pageId))
  const k = String(key ?? '')
  const schema = fieldsOf(doc)
  const f = schema.find((x) => x.key === k)
  if (!f) return noSuchField(k, schema)
  if (value !== null && value !== undefined && !jsonSafe(value)) {
    return fail('not-serializable', `the value for "${k}" holds something JSON cannot carry (a function, a DOM node, a Date, a cycle). It would vanish or throw at save time.`)
  }

  // Normally exactly one. A page carrying TWO prop blocks for one key is a
  // defect validate() reports as `duplicate-prop` — and while it exists a
  // reader takes the LAST (fields.ts valuesOf), so writing only the first would
  // be a set that changes nothing anyone can see, and reports success.
  const mine = page.blocks.filter((b) => b.type === 'prop' && (b as { key?: unknown }).key === k)

  if (value === null || value === undefined) {
    return {
      ok: true, pageId: page.id, key: k, value: null,
      blocks: mine.map((b) => b.id), created: false, removed: true,
      apply() { page.blocks = page.blocks.filter((b) => !mine.includes(b)) },
    }
  }

  const html = propHtml(f, value)
  const fresh = mine.length ? null : propBlock(f, value, uid('b'))
  const warning = optionWarning(f, value)
  return {
    ok: true,
    pageId: page.id, key: k, value, html,
    blocks: fresh ? [fresh.id] : mine.map((b) => b.id),
    created: !!fresh, removed: false,
    ...(warning ? { warning } : {}),
    apply() {
      // VALUE AND html TOGETHER, always, through propHtml — the whole reason
      // this verb exists instead of an insertBlocks the caller writes itself.
      for (const b of mine) {
        ;(b as Record<string, unknown>).value = value
        b.html = html
      }
      // A new value joins the HEADER STRIP: prop blocks before the first
      // non-prop block are the header, by position (render.ts), so appending
      // one to the end of the page would leave a field stranded under the prose.
      if (fresh) page.blocks.splice(headerLength(page), 0, fresh)
    },
  }
}

export interface IssueReport {
  id: string
  title: string
  /** the href an inline link would use: `#p/<id>` */
  url: string
  archived?: true
  /**
   * The PHASE of its status (FieldOption.group) — what makes "open" mean
   * something without anyone configuring a filter. `'unknown'` when the status
   * names no option this schema declares: never silently folded in with the
   * rest, because that is exactly the value a newer build wrote.
   */
  group?: string
  /** every field value on the page, by key */
  fields: Record<string, unknown>
}

export interface IssueQuery {
  /**
   * Field equality. `{ status: 'todo' }`, an array for any-of
   * (`{ status: ['backlog', 'todo'] }`), `null` for "not set" — which covers
   * both an absent prop block and an empty one, because the editor writes `''`
   * for a field it has seeded and nobody has filled in.
   */
  where?: Record<string, unknown>
  /**
   * Status phase: 'unstarted' | 'started' | 'done' | 'cancelled' | 'unknown',
   * an array of those, or 'open'.
   */
  group?: string | string[]
  /** include archived issues too; they are excluded by default */
  archived?: boolean
}

const FINISHED = new Set(['done', 'cancelled'])

/** Compared as TEXT, so `3` and `"3"` are the same estimate. This document is
 *  hand-written JSON as often as not, and a filter that missed on the type of a
 *  number would look exactly like an empty backlog. */
function matches(actual: unknown, want: unknown): boolean {
  if (Array.isArray(want)) return want.some((w) => matches(actual, w))
  if (want === null || want === undefined) return actual === undefined || actual === null || actual === ''
  return String(actual ?? '') === String(want)
}

/**
 * The backlog, as data.
 *
 * One call rather than a page-by-page scan: "everything unstarted and
 * unassigned" is `issues({ group: 'open', where: { assignee: null } })`.
 */
export function issuesReport(doc: SpacesDoc, query: IssueQuery = {}): IssueReport[] {
  const status = fieldsOf(doc).find((f) => f.key === 'status')
  const want = query.group == null ? null
    : (Array.isArray(query.group) ? query.group : [query.group]).map(String)
  const out: IssueReport[] = []

  for (const page of doc.pages) {
    if (!isIssue(page)) continue
    if (page.archived && !query.archived) continue
    const values = valuesOf(page)
    const raw = values.get('status')
    const opt = status && optionOf(status, raw)
    // An UNSET status is not an UNKNOWN one. Reporting 'unknown' for a field
    // nobody has filled in tells an agent the value came from a build we do not
    // understand, when in fact there is no value — and those want opposite
    // handling: one is "leave it alone", the other is "this needs triaging".
    const group = raw === undefined || raw === null || raw === ''
      ? undefined
      : opt ? opt.group : 'unknown'

    // OPEN MEANS NOT FINISHED — one predicate, so a status with no group and a
    // status this build has never heard of both count as work. That is the safe
    // direction: an issue wrongly shown in a backlog costs a glance, an issue
    // wrongly hidden from one costs the issue.
    if (want && !want.some((g) => (g === 'open' ? !(group && FINISHED.has(group)) : g === group))) continue

    let keep = true
    for (const [k, w] of Object.entries(query.where ?? {})) {
      if (!matches(values.get(k), w)) { keep = false; break }
    }
    if (!keep) continue

    out.push({
      id: page.id, title: page.title, url: `#p/${page.id}`,
      ...(page.archived ? { archived: true as const } : {}),
      ...(group ? { group } : {}),
      fields: Object.fromEntries(values),
    })
  }
  return out
}

export interface NewIssueResult {
  id: string
  blocks: string[]
  warnings?: FieldWarning[]
}

/**
 * A new issue: one page, its fields already on it, in ONE undoable step.
 *
 * `title` and `parent` are the page's; every OTHER key is a field key, and one
 * that is not in the schema is REFUSED rather than parked on the page. Unknown
 * keys in a DOCUMENT are a feature — they are how a future build's data
 * survives this one — but an unknown key in an ARGUMENT is a typo, and an agent
 * that wrote `{ prioritty: 'high' }` would otherwise be told it had set a
 * priority it had not set.
 *
 * The page ends with an empty paragraph, exactly as ⌘⇧I does: a page whose
 * every block is a prop has nowhere to put a caret and nowhere to write the
 * issue down.
 */
export function planNewIssue(doc: SpacesDoc, spec: unknown): Plan<NewIssueResult> {
  if (spec !== undefined && !isPatch(spec)) return fail('bad-patch', 'pass { title?, parent?, ...fieldValues }')
  const src = (spec ?? {}) as Record<string, unknown>
  if (badTitle(src.title)) return fail('bad-title', 'title must be a string')
  const parent = src.parent == null ? '' : String(src.parent)
  if (parent && !doc.pages.some((p) => p.id === parent)) return fail('no-such-page', `parent "${parent}"`)

  const schema = fieldsOf(doc)
  const values: Record<string, unknown> = {}
  const warnings: FieldWarning[] = []
  for (const [k, v] of Object.entries(src)) {
    if (k === 'title' || k === 'parent') continue
    const f = schema.find((x) => x.key === k)
    if (!f) return noSuchField(k, schema)
    if (v !== null && v !== undefined && !jsonSafe(v)) return fail('not-serializable', `the value for "${k}" holds something JSON cannot carry`)
    values[k] = v ?? ''
    const w = optionWarning(f, values[k])
    if (w) warnings.push(w)
  }

  const page = newPage(plainTitle(src.title) || 'New issue', parent ? { parent } : {})
  // The SEED LIST is fields.ts's, never a second copy here: a fresh issue from
  // an agent and a fresh issue from ⌘⇧I must carry the same fields, or one of
  // them makes an issue a human cannot assign — there is no "add a field"
  // gesture, because `prop` is unlisted in the / menu on purpose.
  const seed = schema.filter((f) => ISSUE_FIELDS.includes(f.key) || f.key in values)

  // A NEW ISSUE MUST BE AN ISSUE. A space that declares its own schema without
  // a `status` seeded nothing recognisable: the verb returned ok, and the page
  // it made was invisible to issues(), to every board, and to a follow-up
  // setField('status') that then failed `no-such-field`. Reporting success for
  // a page that is not an issue is worse than refusing to make one.
  if (!seed.some((f) => f.key === 'status')) {
    return fail('no-status-field',
      'this space declares no `status` field, and a page is an issue because it has one — '
      + 'add a status field to doc.fields (see bento.fields()) before creating issues')
  }

  const props = seed
    .map((f) => propBlock(f, f.key in values ? values[f.key] : (f.def ?? ''), uid('b')))
  page.blocks = [...props, newBlock('p')]

  return {
    ok: true, id: page.id, blocks: page.blocks.map((b) => b.id),
    ...(warnings.length ? { warnings } : {}),
    apply() { doc.pages.push(page) },
  }
}


// ---------------------------------------------------------------------------
// review comments
// ---------------------------------------------------------------------------

/** One thread, with the anchor spelled out rather than implied by where it sat. */
export interface CommentReport {
  id: string
  /** 'block' = about that block, 'page' = about the page as a whole */
  anchor: 'block' | 'page'
  pageId: string
  pageTitle: string
  /** present only for an anchor of 'block' */
  blockId?: string
  /** the href that reaches the page it is on */
  url: string
  author: string
  at: string
  /** PLAIN TEXT (model.ts CommentEntry) — never html, in or out */
  text: string
  resolved: boolean
  replies: Array<{ id: string; author: string; at: string; text: string }>
}

export interface CommentQuery {
  /** only open threads (`false`) or only settled ones (`true`) */
  resolved?: boolean
  /** one page's threads */
  pageId?: string
}

/**
 * Every review thread in the space, flat, with a TYPED ANCHOR.
 *
 * This is the entry point for an agent working through what a human flagged:
 * one call gives the whole backlog of remarks, in document order, each one
 * saying what it is about. Flat rather than nested because the caller's
 * question is "what is outstanding", not "what does this page hold" — and
 * because the two anchors live in two places in the file, which is a storage
 * decision (model.ts explains why) and no business of the reader's.
 *
 * Defensive about every field: a comment arrives in a file somebody mailed
 * you, so a hostile or hand-edited `replies: 3` must read as no replies rather
 * than throw inside a report an agent is about to branch on.
 */
export function commentsReport(doc: SpacesDoc, query: CommentQuery = {}): CommentReport[] {
  const str = (v: unknown): string => (typeof v === 'string' ? v : '')
  const out: CommentReport[] = []
  for (const page of doc.pages) {
    if (query.pageId && page.id !== query.pageId) continue
    for (const at of commentsOn(page)) {
      const c = at.comment
      const resolved = c.resolved === true
      if (query.resolved !== undefined && query.resolved !== resolved) continue
      out.push({
        id: c.id,
        anchor: at.blockId ? 'block' : 'page',
        pageId: page.id,
        pageTitle: page.title,
        ...(at.blockId ? { blockId: at.blockId } : {}),
        url: `#p/${page.id}`,
        author: str(c.author),
        at: str(c.at),
        text: str(c.text),
        resolved,
        replies: (Array.isArray(c.replies) ? c.replies : [])
          .filter((r) => r && typeof r === 'object')
          .map((r) => ({ id: str(r.id), author: str(r.author), at: str(r.at), text: str(r.text) })),
      })
    }
  }
  return out
}