Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

38.5 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Boot sequence for bento/spaces. Order matters: configure the app, then
// capture the pristine document BEFORE any DOM mutation — the captured copy is
// what gets re-serialized on save.

import { SaveQueue } from '../../kernel/src/savequeue.ts'
import { saveRevision } from './saving'
import './styles.css'
// AFTER styles.css: a design rule and the base rule it restyles often tie on
// specificity, and the tie goes to the later sheet.
import './designs.css'
import { configureApp } from '../../kernel/src/app.ts'
import { startTheme } from '../../kernel/src/theme.ts'
import {
  capturePristine, readEmbeddedDoc, serializeFile, serializeAuto, registerPreview,
  saveFile, parseEnvelope, canWriteInPlace, decryptEnvelope, setEncryptionPassword,
  writeUpdatedFileAs, suggestedFileName,
  isBodySealed,
} from '../../kernel/src/save.ts'
import { setTabTitle, setNeutralTabTitle } from './tabtitle.ts'
import { putRecovery, getRecovery, clearRecovery, clearVersions, pruneOld, addVersion } from '../../kernel/src/autosave.ts'
import { APP_VERSION, applyUpdateInPlace } from '../../kernel/src/update.ts'
import { t, locale, applyDirection } from './i18n'
import { i18nApi } from '../../kernel/src/i18n.ts'
import { parseDoc, uid, newPage, type SpacesDoc, type ParseResult } from './model'
import { recoveryOffered, recoverInto, replaceFromJson } from './restoregate'
import { recoveryBanner, wireRecoveryOff, type RecoveryAction } from './recoverynotice'
import { recordTrail } from './observe.ts'
import { protectedDays } from './periods.ts'
import {
  validateDoc, outlineDoc, statsDoc,
  planInsertBlocks, planUpdateBlock, planRemoveBlocks, planMoveBlock, planUpdatePage, planRemovePage,
  fieldsReport, issuesReport, planSetField, planNewIssue, commentsReport,
  plainTitle, badTitle,
  type Plan, type PlanError, type IssueQuery, type CommentQuery,
} from './agent'
import { starterDoc } from './starter'
import { mentionsOf, mentionIndex } from './mentions.ts'
import { todayISO, isISO, journalFor } from './journal'
import { textOf } from './sanitize'
import { evaluate, format, pageContext } from './calc'
import { buildSpacePreview } from './preview'
import { Store } from './store'
import { Editor } from './editor'
import { SyncSession } from './sync/session.ts'
import { isReaderCopy, stampSync } from './share.ts'
import { recordOnSave } from './history.ts'
import { projectForCopy } from '../../kernel/src/docfields.ts'
import { SPACES_FIELDS } from './docclass.ts'
import { downloadMarkdown, launchUpdateCheck } from './about'

configureApp({
  appId: 'bento-spaces',
  appName: 'bento/spaces',
  manifestUrl: 'https://bento.page/releases/spaces/manifest.json',
})

// Every save writes a still render of the home page into the shell, for the
// readers that run no script: macOS QuickLook, iOS Files, bento/home, and any
// preview pane that renders HTML without executing it. Without this the runtime
// never inflates, the splash is never removed, and a saved space shows a boot
// animation where its content should be. See preview.ts.
registerPreview((doc) => buildSpacePreview(doc as unknown as SpacesDoc))

capturePristine()

// The interface theme: AFTER capturePristine, before the first paint.
//
// AFTER, because capturePristine clones the LIVE document and every save
// re-serializes that clone — so `data-theme` and `color-scheme` must not be on
// <html> yet, or a reader's preference would ride inside every file they save
// and land on whoever they sent it to. Exactly the ordering applyDirection
// depends on for dir/lang, one line below, and for the same reason.
//
// BEFORE the paint, because applying it later paints the interface light and
// then flips it, which reads as a bug rather than as a preference. Nothing
// here lays anything out: it sets two attributes on the root element.
startTheme()
applyDirection()

const embedded = readEmbeddedDoc()

const envelope = embedded ? parseEnvelope(embedded) : null

if (envelope) {
  // MOUNTED, though locked. The shell's loader (scripts/postbuild-compress.mjs)
  // decides whether this app started by looking for `window.bento`; a space
  // waiting at its password gate has no document to publish yet, so without
  // this every loader path read as a failure, each one ran the app AGAIN (a
  // second and third gate), and the loader's failure card covered the lot — an
  // encrypted space could not be opened at all. `locked` is the suite's agreed
  // shape (slides and type set the same); the real object replaces it on unlock.
  ;(window as unknown as { bento: unknown }).bento = { format: 'bento/spaces', locked: true }
  void passwordGate()
} else {
  const res = parseDoc(embedded ?? '')
  if (res.ok) {
    if (!res.doc.docId) res.doc.docId = uid('doc')
    boot(res.doc, res.repaired, res.frozen)
  } else if (res.err === 'empty') {
    // THE ONLY path to the starter. Anything else that failed to parse is
    // someone's data, and replacing it with an empty space would be a loss the
    // first ⌘S makes permanent.
    const doc = starterDoc()
    doc.docId = uid('doc')
    boot(doc, [], undefined)
  } else {
    // MOUNTED, though refused — the same reason as `locked` above: without it
    // the loader reads "no app", runs the app again on every path (one refusal
    // card per path) and paints its own failure over the explanation this file
    // owes its reader. `refused` is the suite's shape (DECISIONS 2026-10-17).
    ;(window as unknown as { bento: unknown }).bento = { format: 'bento/spaces', refused: true }
    refuse(res)
  }
}

/**
 * An encrypted space: ask, then boot.
 *
 * This MUST exist for as long as the About dialog can set a password —
 * otherwise encrypting a space locks its author out of it permanently, which
 * is the worst bug this app could have. The password is held in memory so
 * every later save stays encrypted.
 */
async function passwordGate(): Promise<void> {
  // neutral title while sealed, matching the saved file's title
  setNeutralTabTitle()
  document.getElementById('bento-splash')?.remove()
  const wrap = document.createElement('div')
  wrap.className = 'sp-gate'
  const card = document.createElement('div')
  card.className = 'sp-gate-card'
  card.innerHTML = `<h1>${t('This space is locked')}</h1>` +
    `<p>${t('Enter the password to open it.')}</p>`
  const input = document.createElement('input')
  input.type = 'password'
  input.className = 'sp-find'
  input.autocomplete = 'current-password'
  const go = document.createElement('button')
  go.className = 'sp-btn sp-primary'
  go.textContent = t('Unlock')
  const err = document.createElement('p')
  err.className = 'sp-note'
  card.append(input, go, err)
  wrap.append(card)
  document.body.append(wrap)
  input.focus()

  const tryUnlock = async () => {
    const pass = input.value
    if (!pass) return
    go.disabled = true
    const json = await decryptEnvelope(envelope!, pass)
    go.disabled = false
    if (json === null) { err.textContent = t('Wrong password — try again'); input.select(); return }
    const res = parseDoc(json)
    if (!res.ok) { err.textContent = t('Unlocked, but the document inside could not be read.'); return }
    // held in memory so ⌘S and autosave keep writing encrypted
    setEncryptionPassword(pass)
    wrap.remove()
    if (!res.doc.docId) res.doc.docId = uid('doc')
    boot(res.doc, res.repaired, res.frozen)
  }
  go.addEventListener('click', () => { void tryUnlock() })
  input.addEventListener('keydown', (e) => { if (e.key === 'Enter') void tryUnlock() })
}

/**
 * A document we cannot read is NOT a reason to show an empty one.
 *
 * No editor, no autosave, and two ways out that do not require us to have
 * understood the file: keep the bytes exactly as they are, or take the JSON
 * somewhere else.
 */
function refuse(res: Extract<ParseResult, { ok: false }>): void {
  const detail = 'detail' in res ? res.detail : ''
  const what = res.err === 'format'
    ? t('This is not a bento/spaces document — {detail}.', { detail })
    : res.err === 'json'
      ? t('The document block is not valid JSON — {detail}.', { detail })
      : t('The document block is not shaped like a space — {detail}.', { detail })

  gate(t('This file could not be opened'), what, [
    [t('Save an untouched copy…'), () => {
      // the bytes as they are, NOT a re-serialization: we did not understand
      // this document, so we must not rewrite it
      const html = `<!DOCTYPE html>\n${document.documentElement.outerHTML}`
      const a = document.createElement('a')
      a.href = URL.createObjectURL(new Blob([html], { type: 'text/html' }))
      a.download = 'untouched-copy.bento.html'
      a.click()
    }],
    [t('Copy the document JSON'), () => { void navigator.clipboard?.writeText(embedded ?? '') }],
  ])

  const pre = document.createElement('pre')
  pre.className = 'sp-gate-raw'
  pre.textContent = (embedded ?? '').slice(0, 400)
  document.querySelector('.sp-gate-card')?.append(pre)
}

function gate(title: string, body: string, actions: Array<[string, () => void]>): void {
  document.getElementById('bento-splash')?.remove()
  const wrap = document.createElement('div')
  wrap.className = 'sp-gate'
  const card = document.createElement('div')
  card.className = 'sp-gate-card'
  const h = document.createElement('h1')
  h.textContent = title
  const p = document.createElement('p')
  p.textContent = body
  card.append(h, p)
  for (const [label, fn] of actions) {
    const b = document.createElement('button')
    b.className = 'sp-btn sp-primary'
    b.textContent = label
    b.addEventListener('click', fn)
    card.append(b)
  }
  wrap.append(card)
  document.body.append(wrap)
}

function boot(doc: SpacesDoc, repaired: string[], frozen?: 'policy' | 'version'): void {
  setTabTitle(doc.title)
  document.getElementById('bento-splash')?.remove()

  const store = new Store(doc)
  const saves = new SaveQueue({ getDocument: () => store.doc, getRevision: () => store.revision })
  // `doc.readonly` was declared in the format and read by NOTHING: a space
  // saved as a reading copy opened fully editable, so the one property the
  // sender chose was the one the file did not keep. It is not a security
  // boundary — anyone can edit the JSON — but a file that says it is a reading
  // copy must behave like one for the person who opens it.
  //
  // `frozen` is the other, unrelated reason to lock: this build does not
  // understand the file and must not rewrite it.
  //
  // A collab role that cannot write — 'reader', 'audience', or one this build
  // does not know (share.ts copyCanWrite, an allowlist) — is the THIRD, unrelated reason, and it is the
  // only one of the three that keeps receiving: a view-only copy follows the
  // live session and can never send to it. The lock here is a courtesy to the
  // person holding it — the ENFORCEMENT is the relay, which pins a verified
  // key per socket and drops op batches from a socket that presented none
  // (docs/collab-design.md, "Signed writes"). Remote ops still land, because
  // the kernel session applies them straight to `doc` rather than through
  // `commit()` — deliberately, so a colleague's edit never joins this
  // person's undo stack, and incidentally so `readOnly` cannot block it.
  if (frozen || doc.readonly || isReaderCopy(doc)) store.readOnly = true
  const editor = new Editor(document.getElementById('app')!, store)

  // Live collaboration. Constructing the session is enough to make same-machine
  // tabs of one file sync (BroadcastChannel, keyed on docId); the RELAY is not
  // dialled here — the kernel's shareEligible() gate decides that, and it says
  // connect only when the document ARRIVED carrying collab credentials (it was
  // saved or shared) or the user opted in this session. A fresh starter space
  // and a template tire-kicker stay dormant, which is the rule this app already
  // wrote down: "A space does not phone home when it is opened".
  const session = new SyncSession(store)
  editor.connectSync(session)

  // A view-only copy is asked about FIRST: the kernel's copy table marks it
  // `readonly` as well (share.ts readerCopy), so a build that knows no roles
  // still opens it locked — but it follows the session, and the banner says so.
  if (!frozen && isReaderCopy(doc)) {
    banner(t('This is a view-only copy — it follows the live session but can’t change this space.'))
  } else if (!frozen && doc.readonly) {
    // A FILE SAVED FOR READING OPENS AS ONE. `doc.readonly` alone only locked
    // the store, so a reading copy arrived as the full editor with every
    // control inert — which reads as a broken editor rather than as a
    // document. reading.ts says what such a copy carries and what it does not.
    // (A live view-only copy may carry `readonly` too, which is why the role is
    // asked first: it follows the session, and it keeps the follows-live view.)
    editor.enterReadingCopy()
    banner(t('This is a reading copy. It opens for reading; nothing you do here changes the file.'))
  }
  if (frozen) {
    banner(frozen === 'version'
      ? t('This file was written by a newer version of bento/spaces. It is open read-only so nothing is lost.')
      : t('This file declares rules this build does not know. It is open read-only so nothing is lost.'))
  }
  if (repaired.length) {
    banner(t('{n} duplicate or missing id(s) were repaired so links and pages resolve.', { n: repaired.length }))
  }

  editor.onSave = () => { void doSave() }
  editor.onSaveAs = (suffix: string) => {
    if (suffix === '__markdown') { downloadMarkdown(store); return }
    store.endRun()
    // "Save a copy…" must leave you editing the ORIGINAL. That is what the
    // label promises, and the file you go on typing into should never silently
    // become the backup you just took.
    //
    // This used to call saveFile(doc, true), under a comment claiming the
    // kernel kept the in-place handle pointed at the working file. It does the
    // opposite: saveFile ASSIGNS the picked handle to the module's in-place
    // handle (kernel/src/save.ts), so every later ⌘S wrote to the copy while
    // the original stayed frozen at the moment it was copied. The guarantee the
    // comment described lives in writeUpdatedFileAs, whose keepHandle defaults
    // to false — slides learned the same lesson when a share export became the
    // ⌘S target and the next save overwrote it with the full document.
    //
    // The status line was dead too: saveFile returns 'saved-as' down the
    // forcePicker path, never 'saved', so the confirmation never appeared.
    //
    // A copy of THIS space is this replica, so it carries the CRDT state like
    // ⌘S does: opened later, it rejoins as a fork rather than a fresh adopt.
    stampSync(store, session)
    // tier 'file' of the kernel's copy table: the owner's own whole file,
    // every field kept — taken through the table so no copy path is outside it
    const copy = projectForCopy(store.doc, SPACES_FIELDS, 'file')
    void serializeAuto(copy)
      .then((html) => writeUpdatedFileAs(html, copy, { suffix: suffix === 'copy' ? 'copy' : suffix }))
      .then((ok) => { if (ok) editor.status(t('Copy saved — you are still editing the original')) })
  }
  /**
   * Write a DIFFERENT document out as its own file — the page extract.
   *
   * `serializeAuto`, not `serializeFile`: it is the encryption-aware path, so
   * an extract taken out of a password-protected space is written encrypted
   * with the same password the author is already holding. A page pulled out of
   * an encrypted space arriving in the clear would defeat the encryption
   * silently, on a file whose whole point is that it does not.
   *
   * `keepHandle` stays false (the default), which is the lesson slides paid
   * for: an export that becomes the ⌘S target means the next save overwrites
   * the extract with the whole document.
   */
  editor.onExportSpace = async (out: SpacesDoc): Promise<boolean> => {
    const html = await serializeAuto(out)
    return writeUpdatedFileAs(html, out, { suggestedName: suggestedFileName(out) })
  }

  /**
   * Write a SHARE copy — the invite, or the view-only follower.
   *
   * `out` is a DERIVED document (share.ts), never `store.doc`: that is the
   * whole of the fix for "Invite someone…", which used to reach the ordinary
   * copy path and therefore handed every recipient `collab.ownerPriv`.
   *
   * `serializeAuto`, so an invite taken out of a password-protected space is
   * written encrypted with the password its author is already holding — a
   * shared copy arriving in the clear would defeat the encryption silently.
   *
   * `keepHandle` stays false (the default), and here it is load-bearing rather
   * than tidy: retaining the handle would make the NEXT ⌘S overwrite the copy
   * that just left with the full document — owner key included. Slides paid
   * for that lesson once already.
   */
  editor.onShareCopy = async (out: SpacesDoc, suffix: string): Promise<boolean> => {
    const html = await serializeAuto(out)
    return writeUpdatedFileAs(html, out, { suffix })
  }

  // Two minutes, as in slides. Short enough that a long writing session leaves
  // a usable trail, long enough that the cap is not spent on one afternoon.
  const VERSION_EVERY_MS = 120_000
  let lastVersionAt = 0

  async function doSave(): Promise<void> {
    // Every write of THIS file goes through `saves` (the in-place self-update
    // too, below): the queue keeps two writes from overlapping on one handle,
    // and saving.ts clears the dot only if nothing changed while the bytes were
    // being written. The copies and share exports stay outside it on purpose —
    // they write a DIFFERENT file and never keep its handle.
    // collab.sync is stamped in the queue's prepare step: after any write
    // ahead of this one, immediately before the snapshot is copied, so the
    // state describes exactly the bytes that reach the file (#594).
    //
    // The in-file revision is recorded in the SAME step for the same reason
    // (history.ts): it describes exactly the bytes written, and those bytes
    // contain it. It writes doc.revisions directly — not through commit — so
    // the store's revision does not move and this write is not made stale.
    // Unconditional on encryption: revisions live inside #bento-doc, so the
    // envelope encrypts them with the pages (unlike addVersion below).
    const out = await saveRevision(store, saves, (snapshot) => saveFile(snapshot),
      () => { stampSync(store, session); recordOnSave(store); editor.status(t('Saving…')) })
    if (out.kind === 'failed') {
      console.error('bento/spaces: save failed', out.error)
      editor.status(t('Save failed — see console'))
      return
    }
    if (out.kind !== 'written') { editor.status(''); return }
    // A SAVE IS THE MOMENT WORTH KEEPING. The throttle below catches long
    // editing runs, but the point somebody chose to write the file is the
    // point they would most want back, so it is never throttled away. The
    // version is the snapshot that was WRITTEN, not whatever is on screen now.
    // Sealed spaces (a password or the identity seal) keep nothing here, for the
    // reason putRecovery does not.
    if (!isBodySealed()) { void addVersion(out.doc); lastVersionAt = Date.now() }
    if (out.result === 'saved' && out.current) {
      // Only when the disk holds what is on screen: after a stale write the
      // recovery snapshot is the one copy of the newer edit.
      void clearRecovery(out.doc.docId)
      // "Saved" is doing real work here: on a browser without file-system
      // access this was a NEW download, and saying so is the difference
      // between understanding that and losing track of which copy is current
      editor.status(canWriteInPlace() ? t('Saved') : t('Saved a new copy'))
    } else {
      editor.status('')
    }
  }

  /**
   * The in-place self-update rewrites the SAME file ⌘S does, so it takes the
   * same queue: without it an update and a save could be open on one handle at
   * once, and whichever closed last would decide which shell the file ends up
   * as. It writes the queue's snapshot, and — like a save — clears the dot only
   * when that snapshot is still the document on screen.
   */
  editor.onUpdateInPlace = async (rel) => {
    // stamped and recorded in prepare, beside the snapshot, exactly as ⌘S is
    const saved = await saves.run(() => { store.endRun(); stampSync(store, session); recordOnSave(store) },
      (snapshot) => applyUpdateInPlace(rel, snapshot))
    if (!saved?.value) return null
    if (saved.isCurrent()) store.setDirty(false)
    return saved.value
  }

  /**
   * Today's row, if this space is a tracker and this copy may write at all.
   *
   * A READER COPY AND A SEALED READING COPY WRITE NOTHING. `store.readOnly`
   * covers both, and it is the same check every other writer in this app makes
   * — a trail row is a write, and "opening a file does not modify it" has no
   * exception for a write the app made up itself.
   */
  const recordToday = (): void => {
    if (store.readOnly) return
    const today = todayISO()
    recordTrail(store.doc, { today, protect: protectedDays(store.doc, today) })
  }

  // A recovery snapshot is the ONLY backstop on browsers with no file-system
  // access — which is every browser on iOS.
  //
  // NEVER for an encrypted space. The snapshot is the document as plain JSON,
  // so writing one puts in IndexedDB exactly what the password exists to keep
  // off the disk — and it would do it every few seconds, for the one author who
  // demonstrably cares. The kernel's putRecovery does not guard this; the
  // caller must (slides has the same contract).
  //
  // RECOVERY IS NOT HISTORY. putRecovery keeps ONE snapshot per space — the
  // answer to "the tab died", and nothing else. It is overwritten every few
  // seconds, so it cannot answer "put back what I had before lunch", and undo
  // cannot either: the undo stack lives in memory and dies with the reload.
  // Spaces shipped with only the first of those, while slides and dash both
  // keep a timeline. For the app people write PROSE in, that was the wrong one
  // to leave out — a paragraph rewritten badly an hour ago was unrecoverable by
  // any means the app offered.
  //
  // So a version is added on a throttle while editing, and unthrottled on save.
  // The kernel caps and prunes the timeline; both stores stay empty while the
  // body is sealed (a password or the identity seal).
  let timer: ReturnType<typeof setTimeout> | undefined
  store.on('doc', () => {
    clearTimeout(timer)
    // THE TRAIL IS WRITTEN ON CHANGE, NEVER ON OPEN, and on the debounce that
    // already exists rather than on a second one. It runs BEFORE the encryption
    // guard below, on purpose: `doc.trail` is a document field, so it is inside
    // the `bento/enc` envelope and encrypted by the same pass over the same
    // JSON. There is no plaintext artefact beside the ciphertext, so — unlike a
    // recovery snapshot — there is nothing to refuse. An encrypted space keeps
    // its charts.
    //
    // Outside `store.commit` deliberately: a record of an observation is not an
    // editing step and does not belong in anybody's undo stack (store.ts's
    // snapshot excludes it — `trail` is history class). It is never synced
    // either (the kernel's sync shape skips history fields): each replica keeps
    // its own record of what it saw, as each keeps its own `revisions`.
    //
    // Written DURING editing, not at save — so, unlike `revisions`, it counts
    // toward the recovery key (docclass.ts SPACES_NOT_EDIT does not list it).
    recordToday()
    // isBodySealed, not isEncryptionActive: an identity-sealed space has no
    // password, and its snapshot would be the same plaintext on disk.
    if (isBodySealed()) return
    timer = setTimeout(() => {
      void putRecovery(store.doc)
      if (Date.now() - lastVersionAt > VERSION_EVERY_MS) {
        lastVersionAt = Date.now()
        void addVersion(store.doc)
      }
    }, 2500)
  })
  void pruneOld()
  void offerRecovery(doc, store, editor)
  // A host that refuses the recovery copy (too large) turns crash recovery off
  // for this space; say so once, where the save status shows, held long enough
  // to read (slides holds it 8s). Never for a sealed space.
  //
  // `encrypted: isBodySealed` is redundant today: the autosave guard above
  // (`if (isBodySealed()) return`) means a sealed space never asks for a
  // recovery copy, so the kernel never fires for it. Kept on purpose; a
  // mutation of this line alone stays green because that guard covers it,
  // which is not a gap.
  wireRecoveryOff({
    docId: () => store.doc.docId,
    encrypted: isBodySealed,
    say: (msg) => editor.status(msg, 8000),
  })

  // ---- the AI round-trip (PLATFORM §7) -----------------------------------
  //
  // Every write verb is ONE undoable step, and every one of them runs its plan
  // FIRST: `store.commit` checkpoints undo before it mutates, so planning
  // inside the commit would leave an undo entry behind for a patch that was
  // refused. A refused patch changes nothing at all, including history.
  function run<T extends object>(plan: Plan<T>): ({ ok: true } & T) | PlanError {
    if (store.readOnly) {
      return { ok: false, err: 'readonly', detail: 'this file is open read-only; nothing was changed' }
    }
    if (!plan.ok) return plan
    const { apply, ...rest } = plan
    store.commit(apply)
    editor.repaint()
    return rest as { ok: true } & T
  }

  ;(window as any).bento = {
    format: doc.format,
    get doc() { return store.doc },
    get readonly() { return store.readOnly },
    serialize: () => serializeFile(store.doc),
    serializeAuto: () => serializeAuto(store.doc),
    undo: () => { store.undo(); editor.repaint() },
    redo: () => { store.redo(); editor.repaint() },
    updates: { version: APP_VERSION },
    /**
     * i18n: t/locale/setLocale/choices, as slides exposes it.
     *
     * setLocale('x-pseudo') is the SWEEP AUDIT: every string that reached t()
     * comes back bracketed and accented, so anything still in plain English is
     * a string the extractor never saw and no catalog will ever carry. That is
     * not hypothetical here — two aria-labels were sitting untranslated in this
     * app, and the packer reported 100% the whole time, because a key that is
     * never swept is a key the percentage cannot know about.
     *
     * Chrome only: page titles and block text are the document and must stay
     * exactly as written.
     */
    i18n: i18nApi,
    /** open the graph view — the same thing the ⋯ menu opens */
    graph: () => { editor.openGraph() },
    /** every page, flat — the shape an agent wants before it reads anything */
    pages: () => store.doc.pages.map((p) => ({
      id: p.id, title: p.title, parent: p.parent, archived: !!p.archived, blocks: p.blocks.length,
    })),
    getPage: (id: string) => store.doc.pages.find((p) => p.id === id) ?? null,
    search: (q: string) => {
      const needle = String(q).toLowerCase()
      const out: Array<{ pageId: string; title: string; blockId: string }> = []
      for (const p of store.doc.pages) {
        for (const b of p.blocks) {
          // textOf DECODES entities; a tag-strip does not. On a block reading
          // "a &amp; b" the old regex searched "a &amp; b", so it missed the
          // text the reader can see and matched text that is not there.
          const text = textOf(b.html)
          if (text.toLowerCase().includes(needle)) out.push({ pageId: p.id, title: p.title, blockId: b.id })
        }
      }
      return out
    },
    /** what is WRONG or SUSPECT — see agent.ts */
    validate: (target?: SpacesDoc) => validateDoc(target ?? store.doc),
    /** the whole space as a tree, for orienting in one call */
    outline: (target?: SpacesDoc) => outlineDoc(target ?? store.doc),
    /**
     * Where this space names a page without linking to it.
     *
     * With a page id, that page's unlinked mentions; with none, every page's,
     * as `{ pageId: Mention[] }`. READ ONLY — it reports, it does not link.
     * Deciding that a sentence meant the page is a judgement, and an agent
     * that silently rewrote a hundred blocks' html on a guess would be
     * unreviewable. Link them with `updateBlock`, or leave them for the panel.
     */
    mentions: (pageId?: string) => pageId
      ? mentionsOf(store.doc, store.index, pageId)
      : Object.fromEntries(mentionIndex(store.doc)),
    /** where the bytes are */
    stats: (target?: SpacesDoc) => statsDoc(target ?? store.doc),
    /**
     * What a human flagged: every review thread, flat, each with a typed
     * anchor ('block' with a `blockId`, or 'page').
     *
     * READ ONLY, deliberately. The verbs beside it change the document an
     * agent was asked to work on; a comment is the other half of a
     * CONVERSATION, and an agent quietly resolving the remark it was supposed
     * to act on is the one move that makes the record untrue. Filter with
     * `comments({ resolved: false })` for the outstanding ones.
     */
    comments: (query?: CommentQuery) => commentsReport(store.doc, query ?? {}),

    /**
     * ONE undoable step. Without this an agent appending a paragraph has to
     * rewrite and reparse the whole space through loadDoc — clobbering
     * concurrent edits and flattening undo to a single entry.
     *
     * Keeps its original return shape (new ids, or null) because it shipped
     * that way; the verbs below it return tagged results.
     */
    insertBlocks: (pageId: string, afterId: string | null, blocks: unknown[]) => {
      const res = run(planInsertBlocks(store.doc, pageId, afterId ?? null, blocks))
      return res.ok ? res.ids : null
    },
    updateBlock: (id: string, patch: unknown) => run(planUpdateBlock(store.doc, id, patch)),
    removeBlocks: (ids: unknown) => run(planRemoveBlocks(store.doc, ids)),
    moveBlock: (id: string, to: unknown) => run(planMoveBlock(store.doc, id, to)),
    updatePage: (id: string, patch: unknown) => run(planUpdatePage(store.doc, id, patch)),
    removePage: (id: string, opts?: { descendants?: boolean }) =>
      run(planRemovePage(store.doc, id, opts ?? {})),

    // ---- the tracker: an issue is a page ---------------------------------
    /** the schema in force — the option IDS a value must use */
    fields: () => fieldsReport(store.doc),
    /** the backlog as data, filtered by field value or by status phase */
    issues: (query?: IssueQuery) => issuesReport(store.doc, query ?? {}),
    /**
     * One field, one undoable step, `value` and its readable `html` written
     * TOGETHER — the only supported way to set a value, because a prop block
     * written by hand through insertBlocks gets that pairing wrong, and it is
     * the one thing that must never happen.
     */
    setField: (pageId: string, key: string, value: unknown) =>
      run(planSetField(store.doc, pageId, key, value)),
    newIssue: (spec?: unknown) => run(planNewIssue(store.doc, spec)),

    /**
     * A page carries one empty paragraph, exactly as the editor's own New page
     * does. A page with no blocks has nothing to put a caret in — no gutter, no
     * / menu, no way to type — so an agent creating one would hand a human a
     * page they cannot write in.
     */
    /**
     * Today's entry, or any day's — created if it does not exist yet.
     *
     * The same path the button and ⌘⇧J take, so an agent writing a daily note
     * lands in the same page a person would, and calling it twice in a day
     * returns the same page rather than making a second one.
     *
     * `date` is an ISO `YYYY-MM-DD`. Anything else is refused rather than
     * guessed at: "06/08/2026" is two different days depending on who wrote it.
     */
    journal: (date?: string) => {
      if (store.readOnly) return null
      const iso = date === undefined ? todayISO() : String(date)
      if (!isISO(iso)) return null
      editor.openJournal(iso)
      return journalFor(store.doc, iso)?.id ?? null
    },
    /**
     * Work out an expression the way a line ending in `=` would.
     *
     * `bento.calc('20% of 340')` → 68. With a page id, the names defined on
     * that page are in scope, so an agent sees exactly what a reader sees.
     * Returns null for anything the grammar does not fully understand — the
     * same refusal the page makes, rather than a guess.
     */
    calc: (expr: string, pageId?: string) => {
      const page = pageId ? store.index.page.get(pageId) : undefined
      const ctx = page
        ? pageContext(page.blocks.map((b) => ({ id: b.id, text: textOf(b.html ?? '') })), '')
        : {}
      const v = evaluate(String(expr ?? ''), ctx)
      return v ? { value: v.n, text: format(v, locale()) } : null
    },
    newPage: (title: string, parent?: string) => {
      if (store.readOnly) return null
      // A TITLE, not something that stringifies into one. This takes a string
      // where the verbs beside it take an object, so `newPage({ title: 'x' })`
      // is the natural mistake — and it used to make a page called
      // "[object Object]" and hand back its id, which is the exact failure the
      // rest of this surface exists to avoid.
      if (badTitle(title)) return null
      // a parent that names nothing would silently make this a ROOT page; say
      // no instead, so the caller finds out now rather than in the sidebar
      if (parent && !store.doc.pages.some((p) => p.id === parent)) return null
      const page = newPage(plainTitle(title) || 'Untitled', parent ? { parent } : {})
      store.commit(() => { store.doc.pages.push(page) })
      editor.repaint()
      return page.id
    },
    loadDoc: (json: string): boolean => {
      if (store.readOnly) return false
      // Replace from JSON's own path ('back': content, never identity or history)
      if (!replaceFromJson(store, json)) return false
      editor.repaint()
      return true
    },
  }

  if (!canWriteInPlace()) {
    // stated rather than discovered — the product-defining limitation on iOS
    console.info('[bento/spaces] this browser cannot write back to the file; every save makes a new copy')
  }

  /**
   * Ask the release server whether this app is current — and NOTHING else.
   *
   * This is the one request bento/spaces makes on its own, and it is worth
   * being precise about how it sits beside "A space does not phone home when
   * it is opened" (DECISIONS, 2026-08-03). That rule is about the DOCUMENT: an
   * author who mails you a file must not learn your address and the moment you
   * opened it, which is what a remote `<img>` delivers. This is the APP asking
   * its own release origin for a signed manifest, on the reader's behalf and
   * under the reader's switch — the same check slides has run at launch since
   * v0.9, reading the same `bento-auto-check` preference, so turning it off in
   * one app turns it off in both. It sends no id, carries nothing from the
   * document, and is the mechanism by which a file that will outlive its
   * browser ever learns that it should be updated.
   *
   * Never fatal, and never in the way: the result only changes a sentence in
   * the About dialog.
   */
  // A found update also puts slides' peach chip beside the wordmark, and says
  // so once — the one launch result a reader must not miss (D3's pill). "Up to
  // date" stays a sentence in About, where slides' toast also repeats it.
  void launchUpdateCheck()
    .then((r) => { if (r?.status === 'update') editor.updateFound(r.release.version) })
    .catch(() => { /* an unreachable server is not an error here */ })
}

/** A strip across the top. An action marked primary is styled as the default;
 *  one marked focus takes focus when the banner appears. The two are separate
 *  because slides' recovery banner separates them. */
function banner(text: string, actions: Array<[string, () => void, boolean?, boolean?]> = []): void {
  const bar = document.createElement('div')
  bar.className = 'sp-banner'
  const span = document.createElement('span')
  span.textContent = text
  bar.append(span)
  let focused: HTMLButtonElement | undefined
  for (const [label, fn, isPrimary, takesFocus] of actions) {
    const b = document.createElement('button')
    b.className = isPrimary ? 'sp-btn sp-primary' : 'sp-btn'
    b.textContent = label
    b.addEventListener('click', () => { fn(); bar.remove() })
    bar.append(b)
    if (takesFocus) focused ??= b
  }
  const close = document.createElement('button')
  close.className = 'sp-btn'
  close.textContent = '✕'
  close.setAttribute('aria-label', t('Dismiss'))
  close.addEventListener('click', () => bar.remove())
  bar.append(close)
  document.body.prepend(bar)
  focused?.focus()
}

/**
 * A snapshot that differs from the file we loaded means a crash lost work.
 *
 * The snapshot is FOREIGN INPUT (restoregate.ts): every file:// document shares
 * this IndexedDB, so it is offered only when it passes the gate, and compared as
 * it WOULD be restored. An entry that is not this space, not a document, or
 * that gates down to what is already open never shows a banner at all — like
 * slides' checkRecovery.
 */
async function offerRecovery(doc: SpacesDoc, store: Store, editor: Editor): Promise<void> {
  if (store.readOnly) return // a reading copy, a view-only follower or a frozen file is never rewritten
  // A SEALED SPACE IS NEVER OFFERED A PLAINTEXT COPY, and the ones an unsealed
  // session left for this docId are deleted: the recovery snapshot and every
  // version. boot() runs after the seal is in place (the identity seal is set
  // in capturePristine, the password before boot), so isBodySealed() here is
  // the proven state. Only this docId's entries; never another document's.
  if (isBodySealed()) {
    await clearRecovery(doc.docId)
    await clearVersions(doc.docId)
    return
  }
  const snap = await getRecovery(doc.docId)
  if (!snap || !recoveryOffered(snap.json, doc, snap.at)) return
  // What the banner SAYS is recoverynotice.ts: when the snapshot looks older
  // than the file it warns, and "Keep the file" is the default — but the
  // snapshot is still offered, and keeping the file deletes nothing.
  const spec = recoveryBanner(snap, store.doc)
  const run: Record<RecoveryAction, () => void> = {
    restore: () => {
      // re-gated against the space as it is NOW (recoverInto). A refusal
      // applies nothing and keeps the entry; only Discard deletes it.
      // 'recover': the snapshot is a newer copy of this space, so its history
      // is reconciled (trail unioned by day) rather than kept from the file.
      if (!recoverInto(store, snap)) { editor.status(t('That version could not be read')); return }
      editor.repaint()
    },
    discard: () => { void clearRecovery(doc.docId) },
    // a clock-skewed "older" must never cost work: the entry stays
    keep: () => {},
  }
  banner(spec.text, spec.buttons.map((b) => [b.label, run[b.action], b.primary, b.focus]))
}