Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

305 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// The bento/spaces editor.
//
// The keyboard IS the interface here, so the keymap is specified rather than
// discovered, and every block is its own contentEditable host — never one big
// editable container. That is what keeps Selection block-scoped, so splitting
// and merging blocks can never re-mint an id, and ids are what links,
// backlinks and (later) collaboration key on.

import {
  type Block, type Page, type TableShape, type SpacesDoc, newBlock, newPage, effectiveParents, isRemote,
  tableOf, writeTable, TABLE_MAX_COLS, TABLE_MAX_ROWS, linkCard, linkCardHtml, unresolvedOn,
  parseDoc, uid,
} from './model'
import { CommentsUi, commentBadge } from './comments.ts'
import * as collabUi from './collabui.ts'
import { syncNoticeText } from './syncnotice.ts'
import { Store } from './store'
import { renderPage, toneLabel, paintCode } from './render'
import { notesOnPage } from './footnotes.ts'
import { wireCanvas, placeNewCard } from './canvas.ts'
import { enableTouchDrag } from './touch.ts'
import { wireCharts } from './charts.ts'
import { CODE_LANGS, langLabel, normLang } from './highlight'
import { canonicalize, escText, sanitizeInline, textOf } from './sanitize'
import { FormatBar } from './formatbar'
import type { MarkTag } from './marks'
import { MD_SPECS, SPEC, CALLOUT_TONES } from './blocks'
import { insertFamilies, insertSections, type InsertItem } from './inserts.ts'
import {
  fieldByKey, fieldsOf, propHtml, propBlock, propBlockOf, isIssue, headerLength,
  reorderPages, columnMoves, ISSUE_FIELDS, withField, freeFieldKey, fieldTypeLabel, FIELD_TYPES,
  cycleSort, nextLayout, layoutOf,
  type DropAim, type FieldSpec, type ViewFilter, type ViewSort,
} from './fields'
import { bucketField } from './workload.ts'
import { nextSpan } from './calendar.ts'
import {
  clausesOf, clauseSummary, isAny, opsFor, opLabel, numberOpLabel, windowLabel,
  DATE_WINDOWS, type Clause, type QueryOp,
} from './query.ts'
import { planImport, type SourceFile } from './markdown'
import { extractSpace, planGraft } from './portable'
import { headingsOf } from './embed.ts'
import { countOutsideTags, replaceOutsideTags } from './findreplace'
import { asksForAnswer, evaluate, format, pageContext } from './calc'
import { t, locale, localeChoices, setLocale, applyDirection } from './i18n'
import { openAbout, downloadMarkdown } from './about'
import { applyDesign, adoptDesign, resolveDesign, resolvePageDesign, type Resolved, type DesignPreview } from './designs.ts'
import { openDesignPanel, fillPageDesignMenu, designLabel } from './designpanel'
import { saveRows, type DocHost } from './doccmds.ts'
import { openGraphView } from './graph.ts'
import { pageToDeck, type DeckNote, type DeckNoteCode } from './todeck.ts'
import {
  redecorateTags, readInline, matchTags, pagesWithTag, tagList, keysUnder, ancestorsOf,
  type TagEntry,
} from './tags.ts'
import {
  todayISO, stepDay, journalLabel, journalShort, isJournal, planJournal,
} from './journal'
import { applyTemplate, journalTemplate } from './templates.ts'
import {
  type TemplateHost, openTemplates, openNewPagePicker, savePageAsTemplate,
} from './templateui.ts'
import { canWriteInPlace, parseEnvelope } from '../../kernel/src/save.ts'
import { offlineEnabled } from '../../kernel/src/net.ts'
import { withoutCaps } from '../../kernel/src/docfields.ts'
import { startSharing } from '../../kernel/src/sync/online.ts'
import * as shareModule from './share.ts'
import { readerNav, readingCopy } from './reading.ts'
import { ICONS, type IconName } from './icons'
import { barMenu, anchoredMenu, row, caption, extra, keys, type Menu } from './menus.ts'
import { createTopbarFit, type TopbarFit } from './topbar.ts'
import { createDialog, type Dialog } from '../../kernel/src/ui/dialog.ts'
import '../../kernel/src/ui/dialog.css'
import { createPanel, type Panel } from '../../kernel/src/ui/panel.ts'
import '../../kernel/src/ui/panel.css'
import { PropsPanel } from './props'
import {
  SEAT_SEL, seatsIn, lineBoxes, caretBox, onEdgeLine, stepSeat, tableStep, nearestByX,
  placeCaretAtX, caretToStart, caretToEndOf, atEndOf,
} from './caret'
import { indentTarget, canOutdent } from './nesting'
import { blockFormatRow } from './blockbar'
import {
  nameIndex, namesOf, mentionsOf, linkMention, type Mention,
} from './mentions.ts'
import {
  internAsset, prepareImage, humanBytes, IMAGE_EMBED_BUDGET, MEDIA_EMBED_BUDGET, blobToDataUri,
} from './assets'
import { setTabTitle } from './tabtitle.ts'

const CTRL = navigator.platform.toLowerCase().includes('mac') ? 'metaKey' : 'ctrlKey'

// Markdown autoformat and the / menu both come from the block registry
// (blocks.ts), so a type cannot end up with a menu entry and no trigger, or a
// trigger that no menu mentions.
const AUTOFORMAT = MD_SPECS

/** The four keys caret.ts answers for. A Set so the keymap's hot path is one lookup. */
const ARROWS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'])
/**
 * A page made into a slides deck, as it leaves the app (copied or downloaded).
 * pageToDeck builds a FRESH deck that carries no capability block today, but
 * a hand-out goes through the same stripper as every other one, so a deck
 * that ever grew a `collab` could not take it onto the clipboard
 * (scripts/test-export-secrets.ts: "a clipboard copy goes through a stripper").
 */
const deckForExport = <T extends object>(deck: T): T => withoutCaps(deck)
/**
 * Below this width both side panels are DRAWERS over the page, not columns.
 * One number, handed to the kernel panel as `drawerBelow` (D6: the breakpoint
 * is a per-app parameter of the shared primitive). Spaces' is 820, not slides'
 * 700: a reading column needs more room beside a panel than a canvas does
 * (DECISIONS 2026-08-10, "the drawer breakpoint, not 720").
 */
const DRAWER_BELOW = 820
/**
 * A block's markdown trigger, when its hint IS one ("#", "1.", "```") — the
 * shortcut an Insert row prints right-aligned. A hint that is a description
 * ("Collapsible section") is not a key, and a command list does not repeat it.
 */
const mdTrigger = (hint: string): string | undefined =>
  /^[^\p{L}\s]{1,4}\s*$/u.test(hint) ? hint.trim() : undefined
/** What counts as a note when a folder is dropped on the app. */
const NOTE_EXT = /\.(md|markdown|mdown|mkd)$/i
/** …and what counts as another SPACE: a saved shell, or the bare document JSON
 *  the AI round-trip hands around. Both carry the same `#bento-doc` payload. */
const SPACE_EXT = /\.(html|htm|json)$/i

/**
 * When an import stops embedding images by itself and ASKS.
 *
 * A vault's attachment folder is unbounded — 400MB of screenshots is ordinary
 * — and a space is something you mail. But the house rule for size is warn,
 * never block (assets.ts SPACE_WEIGHT_WARN), so this is one question at one
 * threshold, not a ceiling: answer yes and the rest embed too.
 */
const IMPORT_IMAGE_BUDGET = 12 * 1024 * 1024

/** A picked or dropped file, with the path it had on disk. */
interface PickedFile { path: string; file: File }


/**
 * This reader's preferred page width, or undefined for the built-in default.
 *
 * VIEWER-SCOPED, in localStorage beside the language and the pane width, and
 * never in the document: it describes the screen somebody is sitting at, not
 * anything about the space. Two people opening one file on a laptop and a
 * 27-inch monitor should each get their own answer, and neither should write
 * theirs into a file the other opens.
 */
export function readerWidth(): 'wide' | 'full' | undefined {
  try {
    const v = localStorage.getItem('bento-sp-width')
    return v === 'wide' || v === 'full' ? v : undefined
  } catch { return undefined }
}

export function setReaderWidth(v: 'wide' | 'full' | undefined): void {
  try {
    if (v) localStorage.setItem('bento-sp-width', v)
    else localStorage.removeItem('bento-sp-width')
  } catch { /* a locked-down origin just gets the default */ }
}

export class Editor {
  readonly store: Store
  private root: HTMLElement
  private main!: HTMLElement
  private sidebar!: HTMLElement
  private statusEl!: HTMLElement
  private overlay: HTMLElement | null = null
  /**
   * Undo EVERYTHING the open overlay attached — its away-listener, its Escape
   * handler, its resize reflow, a graph's animation frame. A list, not one
   * slot: the single slot held the resize reflow, so the away-listener could
   * never be put in it, and every popover closed by anything but a click away
   * left its listener on the document to close the NEXT overlay on its first
   * mousedown (measured: Escape a block menu, ⌘K, click inside the search
   * card — the search closed).
   */
  private overlayOff: Array<() => void> = []
  /** set while the editor is writing the DOM, so input handlers stand down */
  private painting = false
  /** reading view: the document without the machinery for changing it */
  private reading = false
  /**
   * This FILE is a reading copy (`doc.readonly`), not a view someone toggled.
   *
   * The difference is whether there is anything to go back to. A reading view
   * is a mode you leave; a reading copy has no editing to return to, so the eye
   * and the ways to write this file go away entirely rather than sitting there
   * doing nothing. See reading.ts for what such a copy carries.
   */
  private sealed = false
  /**
   * The column ↑/↓ are aiming for, in viewport px, or null.
   *
   * Held across CONSECUTIVE vertical steps and dropped by anything else — a
   * horizontal key, a click, and also a vertical step we hand to the browser,
   * because inside one host the browser keeps its own goal column and two
   * memories of the same thing is how they start to disagree.
   */
  private goalX: number | null = null
  /**
   * Remote image urls this READER has agreed to load, this session only.
   *
   * Never persisted and never written to the document: consent belongs to the
   * person opening the file, and saving it would carry one reader's decision to
   * everyone the file is forwarded to. Re-opening asks again, which is the
   * correct default for something that leaks an IP address.
   */
  private allowedRemote = new Set<string>()
  private undoB: HTMLButtonElement | null = null
  private readB: HTMLButtonElement | null = null
  private redoB!: HTMLButtonElement
  private dirtyDot!: HTMLElement
  private pagesPanel: Panel | null = null
  private inspPanel: Panel | null = null
  private static readonly PANE_MIN = 150
  private static readonly PANE_MAX = 420
  private static readonly PANE_DEFAULT = 244
  private paneW = Editor.PANE_DEFAULT
  private paneClosed = false

  // The properties panel — the reader's, like the page list, and CLOSED unless
  // this reader has opened it. See props.ts on why the default is that way
  // round.
  private inspector!: HTMLElement
  private props: PropsPanel | null = null
  private static readonly INSP_MIN = 200
  private static readonly INSP_MAX = 420
  private static readonly INSP_DEFAULT = 280
  private inspW = Editor.INSP_DEFAULT
  private inspClosed = true
  /** the block the panel is describing: the last one the caret or a click was in */
  private inspOn: string | null = null
  /** the page list's + ▾ menu, rebuilt with the list (destroy the last one) */
  private newPageMenu: Menu | null = null
  /** review threads — markers in the end margin, badges in the tree */
  private comments: CommentsUi
  private format!: FormatBar
  onSave: (() => void) | null = null
  onSaveAs: ((suffix: string) => void) | null = null
  /**
   * Write a DIFFERENT document out as its own file — the page extract.
   *
   * Supplied by main.ts, because serializing a shell is a boot-time concern
   * (the pristine capture) and the editor has no business holding it. It is
   * separate from `onSaveAs` on purpose: every suffix there writes THIS
   * document, and an export that went through it would have to smuggle the
   * extract in through a global.
   */
  onExportSpace: ((doc: SpacesDoc) => Promise<boolean>) | null = null
  /**
   * Write a SHARE copy — a different document, under this space's name plus a
   * suffix that says which kind of copy it is.
   *
   * Separate from `onExportSpace` (which names the file after the extracted
   * page) and from `onSaveAs` (every suffix there serializes THIS document,
   * credentials and all — which is precisely how "Invite someone…" came to
   * hand out the owner key). A share copy is always a derived document, so it
   * needs a writer that takes one.
   */
  onShareCopy: ((doc: SpacesDoc, suffix: string) => Promise<boolean>) | null = null
  onPrint: (() => void) | null = null
  /** About's "Update this file" — supplied by main.ts, which owns the save queue */
  onUpdateInPlace: ((release: import('../../kernel/src/update.ts').ReleaseInfo) =>
    Promise<import('../../kernel/src/update.ts').InPlaceOutcome | null>) | null = null

  constructor(root: HTMLElement, store: Store) {
    this.root = root
    this.store = store
    // the reader's panel, restored — never the document's
    try {
      const w = Number(localStorage.getItem('bento-sp-pane'))
      if (Number.isFinite(w) && w > 0) this.paneW = Math.min(Editor.PANE_MAX, Math.max(Editor.PANE_MIN, w))
      this.paneClosed = localStorage.getItem('bento-sp-pane-closed') === '1'
      const iw = Number(localStorage.getItem('bento-sp-insp'))
      if (Number.isFinite(iw) && iw > 0) this.inspW = Math.min(Editor.INSP_MAX, Math.max(Editor.INSP_MIN, iw))
      // ABSENT MEANS CLOSED. Only an explicit '0' — this reader opened it once —
      // gives the panel any width, so a fresh file opens as the page and nothing
      // else.
      this.inspClosed = localStorage.getItem('bento-sp-insp-closed') !== '0'
    } catch { /* storage throws on a locked-down origin; the defaults are fine */ }
    this.build()
    // AFTER build(): `main` exists by then, and the marker layer is painted
    // into whatever the page paint just produced.
    this.comments = new CommentsUi({
      store: this.store,
      main: () => this.main,
      popover: (anchor, build) => this.popover(anchor, (pop) => build(pop, () => this.closeOverlay())),
      paintTree: () => this.paintTree(),
    })
    // Also after build(). `editable()` is asked on every selectionchange, and
    // it is the ONE place the bar is kept out of the reading view, out of a
    // readonly/reader-role file, and out from under an open modal.
    this.format = new FormatBar({
      store: this.store,
      main: () => this.main,
      editable: () => !this.store.readOnly && !this.reading && !this.overlay,
    })
    this.props = new PropsPanel(this.inspector, {
      store: this.store,
      target: () => this.inspOn,
      locked: () => this.store.readOnly || this.reading,
      repaint: () => this.paintPage(),
      pickPoster: (id) => void this.pickPoster(id),
      pickCover: (pageId) => void this.pickCover(pageId),
      removeCover: (pageId) => this.removeCover(pageId),
      pickMedia: (id) => void this.pickMedia(id),
      openIconPicker: (pageId, anchor) => this.openIconPicker(pageId, anchor),
      openAddProperty: (pageId, anchor) => this.openAddProperty(pageId, anchor),
      openPageDesign: (pageId, anchor) => this.openPageDesign(pageId, anchor),
      pageIcon: (icon) => pageIcon(icon),
      openLinkCard: (id) => this.openLinkCard(id),
      addTableRow: (id, at) => this.addTableRow(id, at),
      removeTableRow: (id, at) => this.removeTableRow(id, at),
      addTableCol: (id, at) => this.addTableCol(id, at),
      removeTableCol: (id, at) => this.removeTableCol(id, at),
    })
    this.store.on('tree', () => this.paintTree())
    this.store.on('page', () => { this.paintPage(); this.paintTree() })
    this.store.on('doc', () => { this.status(t('Edited')); this.syncHistoryButtons(); this.syncDirty(); this.syncDesign() })
    // A REMOTE change moves the unsaved dot without claiming you made it —
    // 'doc' paints "Edited", 'dirty' paints only the dot. See store.setDirty.
    this.store.on('dirty', () => this.syncDirty())
    window.addEventListener('popstate', () => this.fromHash())
    this.fromHash()
  }

  // ---- chrome -------------------------------------------------------------
  private build(): void {
    this.root.innerHTML = ''
    this.root.className = 'sp-app'
    // build() rewrites className outright, so the mode has to be re-applied or
    // anything that repaints the shell (About's onRepaint, a language change)
    // silently drops the reader back into the editor.
    if (this.reading) this.root.classList.add('sp-reading')
    if (this.sealed) this.root.classList.add('sp-sealed')

    const bar = el('header', 'sp-bar')
    // THE SUITE'S MARK, and the way into About — the same control slides has.
    // A wordmark that is only decoration wastes the one place everyone looks
    // for "what is this file, and what version": there was no route to About
    // except a ⋯ menu nobody opens.
    const mark = el('button', 'sp-mark')
    ;(mark as HTMLButtonElement).type = 'button'
    mark.innerHTML =
      '<svg class="sp-mark-svg" viewBox="0 0 32 32" width="20" height="20" aria-hidden="true">' +
      '<rect width="32" height="32" rx="7" fill="#16273E"/>' +
      '<rect x="5" y="5" width="7" height="22" rx="2.5" fill="#5E7699"/>' +
      '<rect x="14" y="5" width="13" height="10" rx="2.5" fill="#FF9E8A"/>' +
      '<rect x="14" y="17" width="13" height="10" rx="2.5" fill="#F0EBE0"/>' +
      '</svg><b class="sp-mark-word">bento<span>/</span>spaces</b>'
    // slides' wording with spaces' name: what the mark opens, and what is in it
    mark.title = t('About bento/spaces — version, updates, licenses')
    mark.setAttribute('aria-label', t('About bento/spaces — version, updates, licenses'))
    mark.addEventListener('click', () => this.openAbout())

    // THE UPDATE CHIP — slides' peach pill beside the wordmark, present ONLY
    // when the launch check found a newer version. Its click opens About on a
    // fresh check, which is where updating happens.
    const chip = iconBtn('sync', '', () => this.openAbout(true))
    chip.classList.add('sp-update')
    chip.hidden = !this.updateVersion
    if (this.updateVersion) this.paintUpdateChip(chip, this.updateVersion)
    this.updateChip = chip

    // Pages panel toggle — on every width, like slides' Slides/Format toggles.
    // A sidebar you cannot put away is a sidebar you resent on a laptop.
    const pagesB = iconBtn('panelLeft', t('Pages — show or hide the page list'), () => this.toggleSidebar())
    pagesB.classList.add('sp-panel-toggle')

    const title = document.createElement('input')
    title.className = 'sp-doctitle'
    title.value = this.store.doc.title
    title.setAttribute('aria-label', t('Space name'))
    title.addEventListener('input', () => {
      this.store.runEdit('__title', () => { this.store.doc.title = title.value })
      setTabTitle(title.value)
    })
    this.statusEl = el('span', 'sp-status')

    // THE INSERT GROUP — slides' shape (DECISIONS 2026-09-26): one button per
    // kind of thing, each opening a small menu only when the kind has variants,
    // and Comment last, as slides ends its group. The families are inserts.ts,
    // which the / menu reads too, so the two cannot offer different things.
    // New pages are not inserted into a page: they are on the page list's + ▾.
    const insertGroup = el('div', 'sp-group sp-group-insert')
    for (const f of insertFamilies()) {
      if (f.items.length === 1) {
        const item = f.items[0]
        const b = labelBtn(ICONS[f.icon], t(f.label), t(f.tip), () => this.insertItem(item))
        b.dataset.insert = item.key
        insertGroup.append(b)
        continue
      }
      insertGroup.append(barMenu({
        icon: ICONS[f.icon], label: t(f.label), tip: t(f.tip), className: 'sp-insmenu',
        fill: (m) => this.insertRows(m, f.items),
      }).root)
    }
    insertGroup.append(labelBtn(ICONS.comment, t('Comment'), t('Comment — on the block with the caret, or on this page'),
      () => this.commentHere()))

    this.undoB = iconBtn('undo', t('Undo (⌘Z)'), () => { this.store.undo(); this.repaint() })
    this.redoB = iconBtn('redo', t('Redo (⇧⌘Z)'), () => { this.store.redo(); this.repaint() })
    const search = iconBtn('search', t('Search all pages (⌘K)'), () => this.openSearch())

    // WHERE A COMMAND LIVES — slides' map, command for command, so the two
    // apps do not teach two different toolbars:
    //
    //   · The bar carries what you reach for while working, and the output
    //     buttons slides keeps there (its PDF button is Print here).
    //   · Save ▾ carries everything that acts on the FILE: copy, duplicate,
    //     export, password, then the timeline and the JSON round trip
    //     (doccmds.ts, in slides' order).
    //   · The insert group carries what you add to a page, one button per
    //     kind, as slides' does (inserts.ts); new PAGES are on the page
    //     list's + ▾, because a page is added to the space, not to a page.
    //   · ⋯ exists only once the bar has FOLDED, as slides' does: the bar
    //     controls it had to give up, in slides' order, then the Save list.
    //   · About is reached from the wordmark, as in slides.
    //
    // A command slides has no equivalent for goes where slides would put one
    // of its kind (DECISIONS 2026-09-26): "Make this page an issue" acts on
    // one page, so it is in the page's own menu; Import Markdown… is the
    // document arriving as data, so it sits under Save beside Replace from JSON.
    //
    // THE BAR CARRIES LESS THAN IT DID (maintainer, 2026-10-20): Reading view
    // is a floating button at the page's bottom-end corner, where slides keeps
    // its Slideshow pill; Properties is the inspector's own chevron, `]` and,
    // folded, a row in ⋯; Graph is a view of the TREE, so it sits in the page
    // list's header. Search stays.
    type BarAction = {
      icon: IconName
      label: string
      kbd?: string
      run: () => void
      keep?: (b: HTMLButtonElement) => void
    }
    const barActions: BarAction[] = [
      { icon: 'print', label: t('Export PDF (print)'), kbd: keys('mod', 'P'), run: () => this.openPrint() },
    ]

    // In the bar's corner as in slides — the globe and the `?` — and in ⋯ only
    // once the bar has folded them away.
    const helpB = iconBtn('help', t('Shortcuts & tips (?)'), () => this.openHelp())
    helpB.classList.add('sp-help')
    // slides' glyph — a bold `?`, the key it stands for — not a circled icon
    helpB.innerHTML = '<b class="sp-help-q" aria-hidden="true">?</b>'
    const lang = barMenu({
      icon: ICONS.globe, label: '', tip: t('Language'), end: true, scroll: true, className: 'sp-lang',
      fill: (m) => this.fillLanguages(m),
    }).root

    const inlineSecondary = barActions.map((a) => {
      const b = iconBtn(a.icon, a.kbd ? `${a.label} (${a.kbd})` : a.label, a.run)
      b.classList.add('sp-sec')
      a.keep?.(b)
      return b
    })

    // The file's own commands (D2: a consequence menu). One list for the caret
    // and for the folded ⋯, so the two can never offer different things.
    const saveList = (m: Menu) => saveRows(m, this.docHost())

    const more = barMenu({
      icon: ICONS.more, label: '', tip: t('More actions'), end: true, scroll: true, className: 'sp-more',
      fill: (m) => {
        // Slides' folded ⋯: the controls the bar gave up, in the bar's own
        // order, then the Save list. The list SCROLLS (`scroll`): folded it is
        // taller than a phone, and its last rows are the ONLY way to save a
        // copy or export there.
        // A SEALED reading copy has nothing to undo, set or go back to, so
        // those rows are absent here as their buttons are in the bar.
        if (!this.sealed) {
          row(m, { icon: ICONS.undo, label: t('Undo'), kbd: keys('mod', 'Z'), off: !this.store.canUndo,
            run: () => { this.store.undo(); this.repaint() } })
          row(m, { icon: ICONS.redo, label: t('Redo'), kbd: keys('shift', 'mod', 'Z'), off: !this.store.canRedo,
            run: () => { this.store.redo(); this.repaint() } })
        }
        // …then the insert group, folded: each family with variants under its
        // caption, the one-member kinds set apart by a rule (inserts.ts), and
        // Comment last, as the group ends in the bar
        if (this.canInsert()) {
          for (const sec of insertSections()) {
            if (sec.caption) caption(m, t(sec.caption))
            else if (sec.rule) m.separator()
            this.insertRows(m, sec.items)
          }
          row(m, { icon: ICONS.comment, label: t('Comment'), run: () => this.commentHere() })
          m.separator()
        }
        if (!this.sealed) row(m, { icon: ICONS.panelRight, label: t('Properties'), kbd: ']', run: () => this.toggleInsp() })
        for (const a of barActions) row(m, { icon: ICONS[a.icon], label: a.label, kbd: a.kbd, run: a.run })
        // The globe's list, one tap further: a menu cannot hold a menu, so
        // the row opens the same list as its own popup (a sheet on a phone).
        const moreB = m.trigger
        row(m, { icon: ICONS.globe, label: t('Language'), run: () => {
          queueMicrotask(() => anchoredMenu(moreB, (lm) => this.fillLanguages(lm),
            { label: t('Language'), sheet: this.isDrawer(), returnFocus: moreB }))
        } })
        row(m, { icon: ICONS.help, label: t('Shortcuts & tips'), kbd: '?', run: () => this.openHelp() })
        m.separator()
        saveList(m)
      },
    }).root

    // The live control is replaced in place once the session exists
    // (connectSync). A placeholder rather than a conditional build, so the
    // bar's widths do not shift when a document turns out to be shared — and
    // on a REBUILD (a language change) the session already exists, so the
    // button goes straight in. It used to stay a placeholder: switching
    // language in About took the Share control out of the bar until reload.
    this.liveSlot = this.collab ? this.collab.button() : el('span', 'sp-live-slot')

    // save is a split control, as in slides: the common action, and the
    // less-common ways of writing this document somewhere else
    const saveB = iconBtn('save', t('Save (⌘S)'), () => this.onSave?.())
    saveB.classList.add('sp-primary')
    const saveLabel = document.createElement('span')
    saveLabel.className = 'sp-savelabel'
    saveLabel.textContent = t('Save')
    saveB.append(saveLabel)
    // The unsaved dot lives ON Save, as in slides: the place you look to find
    // out whether you need to press it is the button itself.
    this.dirtyDot = el('span', 'sp-dirty')
    this.dirtyDot.title = canWriteInPlace()
      ? t('Unsaved changes — ⌘S rewrites this file')
      : t('Unsaved changes — ⌘S downloads an updated copy')
    saveB.append(this.dirtyDot)
    const saveMore = barMenu({
      // slides' caret is the ▾ glyph at 10px, not a 12px chevron icon
      icon: '<span class="sp-caret-g" aria-hidden="true">▾</span>', label: '', tip: t('Save as… — copy, new space, password'), end: true, className: 'sp-caret sp-savemenu',
      scroll: true, fill: saveList,
    }).root

    // LEFT = the document (mark · title · save state · history), RIGHT = doing
    // things with it. Same grouping as slides, so the two apps do not teach two
    // different toolbars.
    const history = el('div', 'sp-group sp-group-history')
    history.append(this.undoB, this.redoB)
    const saveGroup = el('div', 'sp-split')
    saveGroup.append(saveB, saveMore)

    // Slides' layout, group for group (chrome-unification §2.1): LEFT is the
    // document (mark · title · history), then the insert tools — here the one
    // + Insert, which is right for a document — then the RIGHT group, doing
    // things with it, ending in the language globe and `?` as slides' does.
    // ⋯ closes the row once the bar has folded — only then, as in slides — and
    // last is where slides' folded bar puts it.
    const right = el('div', 'sp-group sp-group-right')
    right.append(search, ...inlineSecondary, this.liveSlot, saveGroup, lang, helpB, more)

    // The status goes AFTER the history and the insert tools, never before.
    // It is transient text that grows from nothing to a whole sentence, and
    // anything downstream of it in the flex flow gets shoved sideways every
    // time it changes — measured at 36px on a plain edit and 246px entering
    // reading view, so undo landed where redo just was. Here it grows into the
    // slack the right group's margin-auto already holds, and nothing before it
    // can move. Reported against slides as #300.
    //
    // The Pages button (drawer widths only) follows the title, as slides'
    // Slides button does: the corner is the suite's mark, at every width.
    bar.append(mark, chip, title, pagesB, history, insertGroup, this.statusEl, right)

    // Drive the fit now, and again whenever the bar's size or its CONTENT
    // changes — topbar.ts, slides' algorithm with its tiers, its 120px title
    // floor and its 700px phone. A rebuilt bar gets a fresh fit; the old one's
    // observers and its window listener go with it.
    this.barFit?.destroy()
    this.barFit = createTopbarFit(bar, {
      tiers: ['sp-bar-compact', 'sp-bar-tight', 'sp-bar-fold'],
      title: () => bar.querySelector<HTMLElement>('.sp-doctitle'),
      // Re-fitting starts by UNFOLDING, which would slam shut a menu somebody
      // is reading — and ⋯'s contents depend on the tier, so rebuilding it
      // mid-read would change it under them. The next resize runs it again.
      busy: () => !!this.overlay || !!bar.querySelector('.bkm-open'),
      bottomVar: '--sp-bar-bottom',
      varHost: this.root,
    })

    this.sidebar = el('nav', 'sp-side')
    this.sidebar.setAttribute('aria-label', t('Pages'))
    this.main = el('main', 'sp-main')

    this.inspector = el('aside', 'sp-insp')
    this.inspector.setAttribute('aria-label', t('Properties'))

    const body = el('div', 'sp-body')
    this.pagesPanel = this.makePanel(this.sidebar, {
      side: 'start', label: t('Pages'),
      def: Editor.PANE_DEFAULT, min: Editor.PANE_MIN, max: Editor.PANE_MAX,
      width: this.paneW, collapsed: this.paneClosed,
      widthKey: 'bento-sp-pane', closedKey: 'bento-sp-pane-closed',
      show: t('Show the page list ([)'), hide: t('Hide the page list ([)'),
    })
    // CLOSED UNLESS THIS READER OPENED IT (see the constructor): `collapsed`
    // is the stored preference, and absent means shut.
    this.inspPanel = this.makePanel(this.inspector, {
      side: 'end', label: t('Properties'),
      def: Editor.INSP_DEFAULT, min: Editor.INSP_MIN, max: Editor.INSP_MAX,
      width: this.inspW, collapsed: this.inspClosed,
      widthKey: 'bento-sp-insp', closedKey: 'bento-sp-insp-closed',
      show: t('Show properties (])'), hide: t('Hide properties (])'),
    })
    // READING VIEW FLOATS, as slides' Slideshow pill does: the same pill, in
    // the same corner — bottom-END of the page (slides' bottom-right; spaces
    // has no zoombar to share it with). The corner is a zero-width box after
    // the page, so the pill hangs off the page's own edge and moves with the
    // properties panel instead of covering it. It is the way back out of
    // reading view as well as in, so it stays there; a SEALED copy has no
    // editing to go back to, so there it is absent (styles.css).
    const corner = el('div', 'sp-corner')
    this.readB = labelBtn(ICONS.eye, t('Reading view'), t('Reading view'), () => this.toggleReading())
    this.readB.classList.add('sp-readfab', 'sp-readtoggle')
    this.readB.setAttribute('aria-pressed', String(this.reading))
    if (this.reading) this.readB.classList.add('sp-on')
    corner.append(this.readB)
    body.append(this.pagesPanel.root, this.main, corner, this.inspPanel.root)
    this.root.append(bar, body)

    // WHICH BLOCK THE PANEL MEANS. Capture-phase on the page, because the
    // interesting blocks are the ones with no editable host to focus — a table,
    // an image, a clip, a card. `focusin` alone would answer for text and stay
    // silent for exactly the types that have settings worth a panel.
    //
    // `mousedown` rather than `pointerdown`: a real click fires both, so the
    // two are the same to a user, but only the mouse event is reliably what a
    // driven click produces — CLAUDE.md's testing note records the same wall in
    // slides, where synthetic pointer events never reach Gesto. Choosing the
    // one both a hand and a rig emit costs nothing.
    for (const ev of ['focusin', 'mousedown'] as const) {
      this.main.addEventListener(ev, (e: Event) => {
        const n = e.target as Node | null
        const host = (n instanceof HTMLElement ? n : n?.parentElement)
          ?.closest<HTMLElement>('[data-block-id]')
        this.inspOn = host?.dataset.blockId ?? null
        this.props?.retarget()
      }, true)
    }

    // A FINGER GETS THE DRAGS A MOUSE HAD. Blocks, page rows and issue cards
    // are all `[draggable="true"]`, and HTML5 dnd never fires from a touch —
    // so press-and-hold replays the same dnd events those handlers already
    // listen for. One call, delegated at the root, so anything draggable this
    // editor grows later is covered without a second edit. See touch.ts.
    enableTouchDrag(this.root)

    this.paintTree()
    this.paintPage()
    this.syncHistoryButtons()
    this.syncDirty()
    document.addEventListener('keydown', (e) => this.onKey(e), true)
    // A POINTER ENDS THE VERTICAL RUN. Found in the browser, not by reading the
    // code: the goal column was cleared by every key except ↑ and ↓ and by
    // nothing else, so after clicking somewhere new the first ↓ still aimed at
    // the column of the run before it — measured entering a table three times
    // at three different columns and landing in the first one every time.
    const dropGoal = () => { this.goalX = null }
    document.addEventListener('mousedown', dropGoal, true)
    document.addEventListener('touchstart', dropGoal, { capture: true, passive: true })

    // Dropping notes anywhere on the app imports them — the sidebar, the
    // topbar, the grey around the page. The page's own drop handler takes
    // images and stands down for markdown, so the two never both fire.
    this.root.addEventListener('dragover', (e) => {
      if (e.dataTransfer?.types.includes('Files')) e.preventDefault()
    })
    this.root.addEventListener('drop', (e) => {
      if (!isImportDrop(e.dataTransfer)) return
      e.preventDefault()
      const picked = collectDrop(e.dataTransfer)
      void picked.then((files) => this.importFiles(files))
    })
  }

  /**
   * Reading view.
   *
   * Not a separate renderer — the SAME renderer with `editable` off, so what a
   * reader sees is what an editor sees minus the machinery. A second read-only
   * renderer would drift, and the drift would only show up in the view nobody
   * develops in.
   *
   * It is a VIEW, never a document state: nothing about it is written to the
   * file, so a space does not arrive locked because its author was reading when
   * they saved.
   */
  private toggleReading(force?: boolean): void {
    // A sealed copy has one state, and it is this one.
    this.reading = this.sealed ? true : (force ?? !this.reading)
    this.root.classList.toggle('sp-reading', this.reading)
    this.readB?.classList.toggle('sp-on', this.reading)
    this.readB?.setAttribute('aria-pressed', String(this.reading))
    document.querySelector('.sp-findbar')?.remove()
    this.paintPage()
    this.props?.refresh()
    this.status(this.reading ? t('Reading view — press Esc or the eye to edit') : t('Editing'))
  }

  /**
   * This file was saved for reading — so open it as a document.
   *
   * Called once, from boot, for a `doc.readonly` file that is NOT a live
   * view-only copy (main.ts asks about the reader role first). The lock on the
   * store is separate and already applied (main.ts); this is the surface half.
   */
  enterReadingCopy(): void {
    this.sealed = true
    this.root.classList.add('sp-sealed')
    this.toggleReading(true)
    this.status('')
  }

  /** Undo/redo must LOOK unavailable when they are, or they read as broken. */
  /** The dot on Save, and the only place the file's state is visible. */
  syncDirty(): void {
    this.dirtyDot?.classList.toggle('sp-on', this.store.dirty)
  }

  private syncHistoryButtons(): void {
    if (this.undoB) this.undoB.disabled = !this.store.canUndo
    if (this.redoB) this.redoB.disabled = !this.store.canRedo
  }


  /**
   * A side panel: the kernel's (kernel/src/ui/panel.ts). The strip on its inner
   * edge resizes it (double-click resets), the chevron on the strip collapses
   * it, it docks flush when shut, it widens the other way under RTL, and below
   * the drawer breakpoint it is an overlay rather than a column — every one of
   * which spaces had hand-built, twice over (one copy per panel).
   *
   * WHAT STAYS HERE, deliberately:
   *   · PERSISTENCE. The primitive persists its collapsed state in drawer mode
   *     too, and a phone drawer shut by following a link would then leave the
   *     page list shut on the desktop, for good — the bug `closeDrawer` exists
   *     to prevent. So no `storageKey`: the editor writes the reader's own keys
   *     (`bento-sp-pane`, `bento-sp-insp` and their `-closed`) and only when the
   *     change was made to a column (not merely when the viewport now is one —
   *     see `wasDrawer` below). The keys are the ones every reader already has, so
   *     nothing is migrated and nobody's layout resets.
   *   · The SCRIM behind a drawer (the primitive has none): a drawer you can
   *     only shut from the button that opened it is one people leave open over
   *     the page they wanted to read.
   *   · The chevron's words — the primitive is language-free.
   */
  private makePanel(content: HTMLElement, o: {
    side: 'start' | 'end'; label: string; def: number; min: number; max: number
    width: number; collapsed: boolean; widthKey: string; closedKey: string
    show: string; hide: string
  }): Panel {
    const p = createPanel({
      content, side: o.side, label: o.label,
      defaultWidth: o.def, minWidth: o.min, maxWidth: o.max,
      collapsed: o.collapsed, drawerBelow: DRAWER_BELOW,
    })
    p.setWidth(o.width)
    p.resizer.title = t('Drag to resize · double-click to reset')
    const chev = p.resizer.querySelector<HTMLElement>('.bkp-toggle')
    // GATED ON THE MODE THE CHANGE CAME FROM, not on the viewport now. Asking
    // only "is this a column?" let a phone drawer's state leak into the desktop
    // keys: crossing out of drawer width, the primitive fires onChange with the
    // drawer's collapsed state still in force (it boots shut, and the scrim or
    // a followed page shuts it again), the media query already says column, and
    // that state was written as the reader's desktop choice — measured: a 390
    // session, any drawer close or none at all, then a resize to 1440, left
    // `bento-sp-pane-closed` and `bento-sp-insp-closed` at '1' and both columns
    // shut on every later load. So the panel remembers which mode it was last
    // in and the desktop preference (`desk`), writes only a change made AS a
    // column, and on the way back out of drawer width restores `desk` rather
    // than keeping the drawer's state.
    let wasDrawer = this.isDrawer()
    let desk = o.collapsed
    const sync = () => {
      const label = p.collapsed ? o.show : o.hide
      if (chev) { chev.title = label; chev.setAttribute('aria-label', label) }
      const drawer = this.isDrawer()
      const crossed = drawer !== wasDrawer
      wasDrawer = drawer
      if (crossed && !drawer && p.collapsed !== desk) {
        // back to a column: put the desktop preference back. collapse/expand
        // fires onChange again, and that pass (no crossing now) writes it.
        if (desk) p.collapse(); else p.expand()
        return
      }
      if (!drawer && !crossed) {
        desk = p.collapsed
        try {
          localStorage.setItem(o.widthKey, String(p.width))
          // '0' is OPEN and '1' is shut, for both panels: the page list reads
          // '1' as shut and the properties panel reads anything but '0' as shut
          localStorage.setItem(o.closedKey, p.collapsed ? '1' : '0')
        } catch { /* storage can throw; the defaults are fine */ }
      }
      this.syncScrim()
    }
    p.onChange(sync)
    sync()
    return p
  }

  /** The dim behind an open drawer, and the tap that shuts it. */
  private syncScrim(): void {
    const open = this.isDrawer() &&
      ((this.pagesPanel && !this.pagesPanel.collapsed) || (this.inspPanel && !this.inspPanel.collapsed))
    let scrim = document.querySelector<HTMLElement>('.sp-scrim')
    if (!open) { scrim?.remove(); return }
    if (scrim) return
    scrim = el('div', 'sp-scrim')
    scrim.addEventListener('click', () => { this.pagesPanel?.collapse(); this.inspPanel?.collapse() })
    document.body.append(scrim)
  }

  /** Collapse or restore the properties panel — a column, or on a phone a drawer. */
  toggleInsp(force?: boolean): void {
    const p = this.inspPanel
    if (!p) return
    if (force === undefined) p.toggle()
    else if (force) p.expand()
    else p.collapse()
  }

  /** Collapse or restore the page list — a column, or on a phone a drawer. */
  togglePane(force?: boolean): void {
    const p = this.pagesPanel
    if (!p) return
    if (force === undefined) p.toggle()
    else if (force) p.expand()
    else p.collapse()
  }

  private isDrawer(): boolean {
    return window.matchMedia(`(max-width: ${DRAWER_BELOW}px)`).matches
  }

  /**
   * The language list — the globe's, and ⋯'s once the bar has folded. The same
   * rows slides' globe shows: every language this build carries, each in its
   * own name, the one in force checked. Language follows the READER, never
   * the file (PLATFORM §8): nothing here touches the document.
   */
  private fillLanguages(m: Menu): void {
    const now = locale()
    for (const c of localeChoices()) {
      const b = row(m, { label: c.label, selected: c.code === now, run: () => this.chooseLanguage(c.code) })
      b.setAttribute('role', 'menuitemradio')
      b.setAttribute('aria-checked', String(c.code === now))
      b.lang = c.code
      b.classList.toggle('sp-lang-on', c.code === now)
    }
  }

  private chooseLanguage(code: string): void {
    if (code === locale()) return
    setLocale(code)
    applyDirection()
    // the chrome is built in the reader's language, so it is built again
    this.build()
  }

  /**
   * Dismiss the PHONE DRAWER after navigating. On anything wider this does
   * nothing, deliberately.
   *
   * Following a page link used to call `toggleSidebar(false)` directly, which
   * reads as "close the sidebar" and is right on a phone — the drawer covers
   * the page you just asked for. But above the drawer breakpoint
   * `toggleSidebar` delegates to `togglePane`, so on a desktop it collapsed the
   * page-list COLUMN on every click, and `togglePane` persists that to
   * localStorage: the list stayed shut on the next open, and on every open
   * after it. The column is not in the way of anything, and a list you have to
   * reopen to use twice is not a list.
   */
  private closeDrawer(): void {
    if (this.isDrawer()) this.toggleSidebar(false)
  }

  /** One page-list control for every width: the panel is a column or a drawer by itself. */
  private toggleSidebar(force?: boolean): void {
    this.togglePane(force)
  }

  /**
   * Bind the live session to the UI.
   *
   * Called once from main.ts with the session that already exists — the
   * session is constructed whether or not anyone shares, because two tabs of
   * one file sync locally regardless; what this adds is the ability to SEE it.
   */
  connectSync(session: import('./sync/session.ts').SyncSession): void {
    const { CollabUi } = collabUi
    this.session = session
    this.collab = new CollabUi({
      store: this.store,
      session,
      status: (m) => this.status(m),
      paintTree: () => this.paintTree(),
      popover: (anchor, build) => this.popover(anchor, (pop) => build(pop, () => this.closeOverlay())),
      goToPage: (id) => { this.store.goToPage(id); this.closeDrawer() },
      shareCopy: (kind) => { void this.shareCopy(kind) },
      goLive: () => this.goLive(),
    })
    session.onPeers(() => this.collab?.onPeersChanged())
    // The relay refuses things the user can act on — too large, room full. For
    // the permanent codes their change stays in this copy and reaches nobody,
    // which they must be told rather than left to discover.
    session.onNotice((n) => this.notice(syncNoticeText(n)))
    this.collab.tryJoin()
    // a document REPLACED under us (Replace-from-JSON, a restored version) may
    // be a different document with different credentials
    this.store.on('doc', () => this.collab?.tryJoin())
    if (this.liveSlot) this.liveSlot.replaceWith(this.collab.button())
  }

  /**
   * THE SECOND LEVEL (D3): a message the reader must not miss — a refusal, a
   * failure, an outcome that happened out of view (a copy written, the relay
   * refusing a change). It was the same 12px `--muted` whisper in the bar as
   * "Edited", which fades in under two seconds and on a phone sits over the
   * title strip; "Every page opens wide on this screen from now on" is a
   * sentence nobody could read before it left. A pill at the foot of the
   * window, above everything (a dialog included), announced politely, as
   * slides' toast is. The status line keeps the ambient first level.
   */
  notice(msg: string): void {
    if (!msg) return
    let n = document.querySelector<HTMLElement>('.sp-notice')
    if (!n) {
      n = el('div', 'sp-notice')
      n.setAttribute('role', 'status')
      n.setAttribute('aria-live', 'polite')
      document.body.append(n)
    }
    n.textContent = msg
    n.classList.add('sp-on')
    clearTimeout((n as any)._t)
    ;(n as any)._t = setTimeout(() => n?.classList.remove('sp-on'), 3600)
  }

  /** The transient save status. `ms` is how long it stays up: a sentence the
   *  author must read (crash recovery is off) needs longer than "Saved". */
  status(msg: string, ms = 1800): void {
    this.statusEl.textContent = msg
    this.statusEl.classList.add('sp-on')
    clearTimeout((this.statusEl as any)._t)
    ;(this.statusEl as any)._t = setTimeout(() => {
      this.statusEl.classList.remove('sp-on')
      // The word must LEAVE the bar, not just fade out of it. This span is
      // nowrap, so once "Edited" had been written once it held ~40px of the
      // topbar for the rest of the session — and on a phone that width came
      // out of the controls beside it. Cleared after the fade, never during.
      setTimeout(() => {
        if (!this.statusEl.classList.contains('sp-on')) this.statusEl.textContent = ''
      }, 260)
    }, ms)
  }

  // ---- the page tree ------------------------------------------------------
  private paintTree(): void {
    const s = this.store
    this.sidebar.innerHTML = ''
    const head = el('div', 'sp-side-head')
    head.append(el('span', 'sp-side-title', t('Pages')))
    // Import used to sit here, beside "new page", on the reasoning that the
    // moment somebody wants it is the moment they see an empty sidebar next to
    // a folder of notes. Two things undid that: a fresh space is not empty any
    // more (the starter fills it), and About now has a "Bring notes in"
    // section beside the ways out — so this was a second copy of a control, in
    // the header of the page LIST, reading as a way to add a page. It lives
    // with the other secondary actions instead, which puts it in the ⋯ menu on
    // a phone from one list rather than two. Dropping a folder on the window
    // still works and is how most people will actually find it.
    //
    // NEW PAGES START HERE, on the list they join — a + ▾ split, as slides'
    // Save is a split: the common action (New page), and its caret holding
    // the other ways a page arrives, with their shortcuts. They used to sit at
    // the foot of the bar's + Insert, among the blocks, where a page is not a
    // thing you insert into the page you are on.
    const split = el('div', 'sp-newsplit')
    // Once the space HAS templates, + offers them; with none it makes a blank
    // page as it always did (openNewPagePicker returns false and the fallback
    // runs). The caret beside it holds the other ways a page arrives.
    const plus = iconBtn('plus', t('New page (⌘⌥N)'), () => {
      if (!openNewPagePicker(this.templateHost, plus, () => this.newPage())) this.newPage()
    })
    plus.classList.add('sp-newpage')
    this.newPageMenu?.destroy()
    this.newPageMenu = barMenu({
      icon: '<span class="sp-caret-g" aria-hidden="true">▾</span>', label: '',
      tip: t('New… — page, journal, issue'), end: true, className: 'sp-caret sp-newmenu',
      fill: (m) => this.pageRows(m),
    })
    split.append(plus, this.newPageMenu.root)
    // GRAPH IS A VIEW OF THE TREE, so it sits on the tree's header (maintainer,
    // 2026-10-20) — beside + ▾, and still there in reading view, where + ▾
    // is not: a reader uses the graph to find their way.
    const graphB = iconBtn('graph', t('Graph'), () => { this.closeDrawer(); this.openGraph() })
    graphB.classList.add('sp-graphbtn')
    const acts = el('div', 'sp-side-acts')
    acts.append(graphB, split)
    head.append(acts)
    this.sidebar.append(head)

    const list = el('ul', 'sp-tree')
    for (const { page, depth } of s.tree()) {
      if (page.archived) continue
      const li = document.createElement('li')
      li.style.paddingInlineStart = `${depth * 14}px`
      const a = document.createElement('a')
      a.href = `#p/${page.id}`
      const here = page.id === s.pageId
      a.className = 'sp-treelink' + (here ? ' sp-here' : '')
      // WEIGHT IS NOT AN ANNOUNCEMENT. sp-here says "you are here" in 600
      // against 400, which a sighted reader gets for free and a screen reader
      // is told nothing about — the tree reads as a flat list of links with no
      // indication of which one you are on. aria-current is the one attribute
      // that carries it.
      if (here) a.setAttribute('aria-current', 'page')
      const ico = el('span', 'sp-tree-ico')
      ico.innerHTML = pageIcon(page.icon)
      const label = document.createElement('span')
      label.textContent = this.pageLabel(page)
      a.append(ico, label)
      // who else is reading this page. A space is a TREE, so "where is
      // everyone" is a question about pages, not about carets — this is the
      // spaces answer to the cursors slides paints on its canvas.
      const dots = this.collab?.dotsFor(page.id)
      if (dots) a.append(dots)
      // Unresolved threads badge the page they are on: the tree is the only
      // place you can see that another page is waiting on you.
      const badge = commentBadge(unresolvedOn(page))
      if (badge) a.append(badge)
      a.draggable = true
      a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.closeDrawer() })
      a.addEventListener('dragstart', (e) => e.dataTransfer?.setData('text/bento-page', page.id))
      a.addEventListener('dragover', (e) => {
        // a sidebar row accepts PAGES; a card dragged over it lit up and
        // promised a nesting it would never perform
        if (!e.dataTransfer?.types.includes('text/bento-page')) return
        e.preventDefault(); a.classList.add('sp-drop')
      })
      a.addEventListener('dragleave', () => a.classList.remove('sp-drop'))
      a.addEventListener('drop', (e) => {
        e.preventDefault(); a.classList.remove('sp-drop')
        const moved = e.dataTransfer?.getData('text/bento-page')
        if (moved && moved !== page.id) this.reparentPage(moved, page.id)
      })
      const more = document.createElement('button')
      more.className = 'sp-rowmore'
      more.type = 'button'
      more.innerHTML = ICONS.more
      more.title = t('Page options')
      more.setAttribute('aria-label', t('Page options'))
      more.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); this.openPageMenu(page.id, more) })
      a.append(more)

      li.append(a)
      list.append(li)
    }
    if (!list.childElementCount) list.append(el('li', 'sp-side-empty', t('No pages yet')))
    this.sidebar.append(list)

    // Archived pages are OUT OF THE WAY, never invisible: they are still
    // searchable and linkable, and someone about to share the file needs to be
    // able to see what is going with it.
    const archived = s.doc.pages.filter((p) => p.archived)
    if (archived.length) {
      const det = document.createElement('details')
      det.className = 'sp-archived'
      const sum = document.createElement('summary')
      sum.textContent = t('Archived ({n})', { n: archived.length })
      det.append(sum)
      const al = el('ul', 'sp-tree')
      for (const page of archived) {
        const li = document.createElement('li')
        const a = document.createElement('a')
        a.href = `#p/${page.id}`
        const hereA = page.id === s.pageId
        a.className = 'sp-treelink sp-arch-row' + (hereA ? ' sp-here' : '')
        if (hereA) a.setAttribute('aria-current', 'page')
        const ico = el('span', 'sp-tree-ico')
        ico.innerHTML = pageIcon(page.icon)
        const label = document.createElement('span')
        label.textContent = this.pageLabel(page)
        a.append(ico, label)
        a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.closeDrawer() })
        const un = document.createElement('button')
        un.className = 'sp-rowmore'
        un.type = 'button'
        un.innerHTML = ICONS.unarchive
        un.title = t('Restore to the page list')
        un.setAttribute('aria-label', t('Restore to the page list'))
        un.addEventListener('click', (e) => {
          e.preventDefault(); e.stopPropagation()
          s.commit(() => { const p = s.index.page.get(page.id); if (p) delete p.archived })
        })
        a.append(un)
        li.append(a)
        al.append(li)
      }
      det.append(al)
      this.sidebar.append(det)
    }

    // dropping on the empty area below the tree makes a page top-level again
    list.addEventListener('dragover', (e) => e.preventDefault())
    this.sidebar.addEventListener('drop', (e) => {
      if ((e.target as HTMLElement).closest('.sp-treelink')) return
      e.preventDefault()
      const moved = e.dataTransfer?.getData('text/bento-page')
      if (moved) this.reparentPage(moved, '')
    })
  }

  /** Re-parent a page, refusing a move that would make it its own ancestor. */
  private reparentPage(id: string, parent: string): void {
    if (id === parent) return
    for (let p: string | undefined = parent; p; p = this.store.index.page.get(p)?.parent) {
      if (p === id) { this.notice(t('A page cannot contain itself')); return }
    }
    this.store.commit(() => {
      const page = this.store.index.page.get(id)
      if (!page) return
      if (parent) page.parent = parent
      else delete page.parent
    })
  }

  /**
   * The reader's own name for a page.
   *
   * An entry stores its title as the ISO date — locale-neutral in the file, the
   * same for every reader, and what search and the Markdown export see. The
   * SIDEBAR shows it in the reader's own format, because "2026-08-06" is a key
   * and "Thu 6 Aug" is a date. An entry the author has RENAMED keeps its name:
   * the rename was the point.
   */
  pageLabel(page: { title: string; journal?: unknown }): string {
    if (isJournal(page as never) && page.title === page.journal) {
      return journalShort(String(page.journal), locale())
    }
    return page.title || t('Untitled')
  }

  /**
   * Open a day's entry, creating it if this is the first note of the day.
   *
   * ONE COMMIT for the whole plan (the Journal page and the entry, when both
   * are new), so ⌘Z takes back "I opened today's journal" in a single step
   * rather than leaving a stray empty parent behind.
   */
  openJournal(iso = todayISO()): void {
    const s = this.store
    if (s.readOnly) return
    const plan = planJournal(s.doc, iso)
    if (plan.add.length) {
      // THE ENTRY'S OWN DATE, not today's: stepping to tomorrow's note has to
      // write tomorrow's date into it, or a template with {{date}} in it lies
      // on every entry but the one made on the day. Inside the SAME commit as
      // the pages, so ⌘Z still takes back "I opened today's journal" in one
      // step. The Journal parent page, when it is new too, is never templated —
      // it is furniture, not an entry.
      const tpl = journalTemplate(s.doc)
      if (tpl) applyTemplate(plan.page, tpl, { date: iso, locale: locale() }, true)
      s.commit(() => {
        for (const { page, after } of plan.add) {
          const at = after ? s.doc.pages.findIndex((p) => p.id === after) : -1
          if (at >= 0) s.doc.pages.splice(at + 1, 0, page)
          else s.doc.pages.push(page)
        }
      })
    }
    s.goToPage(plan.page.id)
    this.status(journalLabel(iso, locale()))
  }

  /** The day before or after the entry in view. */
  stepJournal(n: number): void {
    const cur = this.store.page
    if (!cur || !isJournal(cur)) return
    this.openJournal(stepDay(String(cur.journal), n))
  }

  /**
   * The narrow contract src/templateui.ts gets — the store operations it
   * needs, and nothing else. Rebuilt on every read so `page` is never a stale
   * reference to a page that has since been deleted.
   */
  private get templateHost(): TemplateHost {
    const s = this.store
    return {
      get doc() { return s.doc },
      get readOnly() { return s.readOnly },
      get page() { return s.page },
      commit: (fn: () => void) => { s.commit(fn) },
      goToPage: (id: string) => { s.goToPage(id) },
      status: (msg: string) => { this.status(msg) },
      afterCreate: () => {
        this.repaint()
        afterPaint(() => {
          const h = this.main.querySelector<HTMLElement>('[data-page-title]')
          h?.focus()
          if (h) selectAll(h)
        })
      },
      pageIcon: (icon: string | undefined) => pageIcon(icon),
      dialog: (title, build) => { this.openOverlay(title, build) },
      menu: (anchor, label, fill) => { this.menuAt(anchor, label, fill) },
    }
  }

  newPage(parent?: string): void {
    const page = newPage(t('Untitled'))
    if (parent) page.parent = parent
    this.store.commit(() => { this.store.doc.pages.push(page) })
    this.store.goToPage(page.id)
    afterPaint(() => {
      const h = this.main.querySelector<HTMLElement>('[data-page-title]')
      h?.focus()
      if (h) selectAll(h)
    })
  }

  /**
   * Repaint if — and only if — this page's footnote NUMBERING has changed.
   *
   * DERIVE, DO NOT COMMIT: the same shape slides uses for linked charts and
   * connectors. Nothing is written to the document here; the section at the
   * foot of the page is a function of the references in the blocks, so the
   * only thing that can be stale is the DOM. The signature is the ordered
   * label list, which is exactly what the section and every marker are drawn
   * from — so an unconditional repaint on blur would be a caret-losing
   * flicker on every click, and no repaint at all would leave a note the
   * author just referenced with nowhere to write it.
   */
  private syncFootnotes(): void {
    const page = this.store.page
    if (!page) return
    const sig = notesOnPage(this.store.doc, page).order.join('\u001F')
    if (sig === this.fnSig) return
    this.fnSig = sig
    this.paintPage()
  }

  private fnSig = ''

  // ---- the page -----------------------------------------------------------
  /**
   * The design the picker is showing on hover, or undefined for none.
   * A preview is never document data: it is painted, never committed.
   */
  private designPreview: DesignPreview | undefined = undefined
  /** the page root renderPage built for the page in view */
  private pageRoot: HTMLElement | null = null

  /**
   * Put THE PAGE IN VIEW's design (or the one being previewed) on the reading
   * surface. The surface is `.sp-main` and the page root inside it, and
   * nothing else — the bar, both panels and every popover stay the reader's
   * (DECISIONS, 2026-09-26). Both get the SAME resolved design, so the two
   * nested roots can never disagree (designs.css matches by ancestor).
   */
  syncDesign(): Resolved | null {
    const s = this.store
    const r = resolvePageDesign(s.doc, s.page?.id, this.designPreview)
    applyDesign(this.main, s.doc, r)
    if (this.pageRoot?.isConnected) applyDesign(this.pageRoot, s.doc, r)
    return r
  }

  /** Show a design on the page without writing it; `undefined` ends the preview. */
  previewDesign(pv: DesignPreview | undefined): void {
    this.designPreview = pv
    this.syncDesign()
  }

  /**
   * One page's design choices, as a menu — from the page ⋯ menu and from the
   * properties panel's Design row (designpanel.ts fillPageDesignMenu). A
   * kernel menu through menuAt, so Escape, a press outside and the arrow keys
   * are the primitive's.
   *
   * THE PREVIEW ENDS WITH THE MENU, however the menu goes: a row, Escape, a
   * press outside, another menu opening. `onClose` is the one callback that
   * hears all of them (menus.ts anchoredMenu) — a hover preview that outlives
   * its menu is a design on screen that is not in the file.
   */
  openPageDesign(pageId: string, anchor: HTMLElement): void {
    const s = this.store
    if (!s.index.page.get(pageId)) return
    const end = () => this.previewDesign(undefined)
    const m = this.menuAt(anchor, t('Design'), (mm) => fillPageDesignMenu(mm, {
      store: s,
      pageId,
      preview: (pv) => this.previewDesign(pv),
      openPanel: (id) => openDesignPanel(s, (pv) => this.previewDesign(pv), id),
    }), { onClose: end })
    // leaving the whole menu ends any preview, whichever row the pointer left from
    m.menu.addEventListener('mouseleave', end)
  }

  private paintPage(): void {
    const s = this.store
    const page = s.page
    const design = this.syncDesign()
    // the baseline `syncFootnotes` compares against — set here so switching
    // pages can never leave the previous page's signature behind
    this.fnSig = page ? notesOnPage(s.doc, page).order.join('\u001F') : ''
    // The bar holds a reference to the block host it is floating over, and this
    // is about to replace every one of them.
    this.format?.close()
    this.main.innerHTML = ''
    if (!page) { this.main.append(el('p', 'sp-empty', t('This space has no pages.'))); return }

    this.painting = true
    const trail: string[] = []
    for (let p = page.parent; p; p = s.index.page.get(p)?.parent) {
      const owner = s.index.page.get(p)
      if (!owner) break
      trail.unshift(owner.id)
      if (trail.length > 4) break
    }
    const view = renderPage(page, s.doc, {
      editable: !s.readOnly && !this.reading,
      titleOf: (id) => s.index.page.get(id)?.title,
      allowRemote: (src) => this.allowedRemote.has(src),
      readerWidth: readerWidth(),
      // the same resolution the surface just took, preview included
      design,
    })
    this.pageRoot = view
    // the icon lives beside the title, where changing it is discoverable
    const inner = view.querySelector('.sp-page-inner')
    if (inner && !s.readOnly && !this.reading) {
      const pick = document.createElement('button')
      pick.className = 'sp-pageicon'
      pick.type = 'button'
      pick.innerHTML = pageIcon(page.icon)
      pick.title = t('Change this page\'s icon')
      pick.setAttribute('aria-label', t('Change this page\'s icon'))
      pick.addEventListener('click', () => this.openIconPicker(page.id, pick))
      inner.prepend(pick)
    }

    // A DAY HAS A DAY EITHER SIDE OF IT. Without this, reaching yesterday means
    // finding it in the sidebar, which is the one navigation a journal should
    // never need. The strip carries the reader's own long-form date because the
    // title above it is the ISO key, and a date nobody can read at a glance is
    // not much of a journal.
    if (inner && isJournal(page)) {
      const iso = String(page.journal)
      const nav = el('div', 'sp-jnav')
      const step = (n: number, glyph: string, title: string) => {
        const b = document.createElement('button')
        b.type = 'button'
        b.className = 'sp-jstep'
        b.textContent = glyph
        b.title = title
        b.setAttribute('aria-label', title)
        b.addEventListener('click', () => this.stepJournal(n))
        return b
      }
      nav.append(step(-1, '‹', t('The day before')), step(1, '›', t('The day after')))
      if (iso !== todayISO()) {
        const today = document.createElement('button')
        today.type = 'button'
        today.className = 'sp-jstep sp-jtoday'
        today.textContent = t('Today')
        today.addEventListener('click', () => this.openJournal())
        nav.append(today)
      }
      inner.prepend(nav)

      // THE HEADING READS AS A DATE, not as a key. The title is stored as the
      // ISO string so the file is locale-neutral and sorts — but "2026-08-01"
      // as a page's own H1 is a filename, not a day.
      //
      // Slides solves the same shape for dynamic fields by swapping the RAW
      // token back while editing, and that is deliberately NOT copied here: a
      // `{{page}}` token is something the author means to keep, whereas an ISO
      // date is a key nobody wants to type. Someone renaming an entry starts
      // from the date they can read and appends to it — which is the rename
      // they were going to make anyway. The date itself lives in `journal` and
      // is untouched by any of it, so a renamed entry is still that day's.
      const h = inner.querySelector<HTMLElement>('[data-page-title]')
      if (h && page.title === iso) h.textContent = journalLabel(iso, locale())
    }

    if (trail.length) {
      const crumb = el('nav', 'sp-crumb')
      crumb.setAttribute('aria-label', t('Breadcrumb'))
      trail.forEach((id, i) => {
        if (i) crumb.append(Object.assign(document.createElement('span'), { textContent: '›' }))
        const a = document.createElement('a')
        a.href = `#p/${id}`
        a.textContent = s.index.page.get(id)?.title || t('Untitled')
        a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(id) })
        crumb.append(a)
      })
      view.querySelector('.sp-page-inner')?.prepend(crumb)
    }
    this.main.append(view)
    this.wire(view)
    view.querySelector('.sp-page-inner')?.append(this.backlinks(page.id))
    // Unlinked mentions sit BESIDE the backlinks and below them: "what links
    // here" is a fact about the space, "what could have" is a suggestion, and
    // a suggestion above a fact reads as one.
    view.querySelector('.sp-page-inner')?.append(this.unlinked(page.id))
    // The reader's way through the space. Only in reading mode: an editor has
    // the sidebar, the gutters and ⌘K, and a pair of chapter links under every
    // page would be furniture in the way of the writing.
    if (this.reading) {
      const rnav = readerNav(s.doc, page.id, (id) => s.goToPage(id))
      if (rnav) view.querySelector('.sp-page-inner')?.append(rnav)
    }
    // Comments are EDITOR-ONLY. The gate is here rather than in comments.ts
    // because this is the object that knows which view it is in — and the
    // renderer, which print and the reading view share, has never heard of
    // them at all.
    if (!this.reading) this.comments?.refresh()
    this.painting = false
  }

  /**
   * The hover gutter.
   *
   * A block editor with no visible affordances is a guessing game: nothing on
   * screen says a block can be moved or that a new one can go here. These sit
   * OUTSIDE the text column so they never reflow the prose, and only appear on
   * hover so a page at rest is just the writing.
   */
  private addGutter(node: HTMLElement, blockId: string): void {
    const g = el('div', 'sp-gutter')
    const add = document.createElement('button')
    // Named, because a phone drops it: there is only room for ONE control in a
    // 44px margin, and "Add below" is the second item of the grip's own menu.
    add.className = 'sp-ghost sp-ghost-add'
    add.type = 'button'
    add.innerHTML = ICONS.plus
    add.title = t('Add a block below')
    add.setAttribute('aria-label', t('Add a block below'))
    add.addEventListener('click', () => this.insertAfter(blockId))

    const grip = document.createElement('button')
    grip.className = 'sp-ghost'
    grip.type = 'button'
    grip.draggable = true
    grip.innerHTML = ICONS.grip
    grip.title = t('Drag to move, click for block options')
    grip.setAttribute('aria-label', t('Block options'))
    grip.addEventListener('click', () => this.openBlockMenu(blockId, grip))
    grip.addEventListener('dragstart', (e) => {
      e.dataTransfer?.setData('text/bento-block', blockId)
      node.classList.add('sp-dragging')
    })
    grip.addEventListener('dragend', () => node.classList.remove('sp-dragging'))

    node.addEventListener('dragover', (e) => {
      // ONLY a block drag. A view block is a block node, so an issue card
      // dragged across the board lit the blue "block moves here" bar under the
      // whole view at the same time as the column's outline — two things
      // claiming one drop, from different owners. The payload says which
      // gesture this is; ask it.
      if (!e.dataTransfer?.types.includes('text/bento-block')) return
      e.preventDefault()
      node.classList.add('sp-dropline')
    })
    node.addEventListener('dragleave', () => node.classList.remove('sp-dropline'))
    node.addEventListener('drop', (e) => {
      e.preventDefault()
      node.classList.remove('sp-dropline')
      const moved = e.dataTransfer?.getData('text/bento-block')
      if (moved && moved !== blockId) this.moveBlock(moved, blockId)
    })

    g.append(add, grip)
    node.prepend(g)
  }

  private insertAfter(blockId: string): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const fresh = newBlock('p')
    const owner = s.block(blockId)
    if (owner?.parent) fresh.parent = owner.parent
    // a block born inside a canvas is born somewhere ON it
    placeNewCard(page, fresh)
    s.commit(() => {
      page.blocks.splice(page.blocks.findIndex((b) => b.id === blockId) + 1, 0, fresh)
    })
    this.paintPage()
    this.focusBlock(fresh.id)
  }

  /** Whether the page in view takes new blocks from the bar at all. */
  private canInsert(): boolean {
    return !!this.store.page && !this.store.readOnly && !this.reading
  }

  /**
   * The block the caret (or the last click) is in, if it is on this page.
   *
   * `inspOn` is set on focusin and mousedown inside the page, and pressing a
   * bar button changes neither, so it still names the block you were in when
   * you reached for the bar. A click on the page's blank space clears it.
   */
  private caretBlock(): Block | undefined {
    const id = this.inspOn
    return id ? this.store.page?.blocks.find((b) => b.id === id) : undefined
  }

  /** Rows for one family's members, with the family's own rules. */
  private insertRows(m: Menu, items: InsertItem[]): void {
    for (const item of items) {
      if (item.rule) m.separator()
      const r = row(m, { icon: ICONS[item.icon], label: t(item.label), kbd: mdTrigger(item.hint), run: () => this.insertItem(item) })
      // the item's key, so a rig can hold the bar and the / menu to one list
      r.dataset.insert = item.key
    }
  }

  /**
   * INSERT ONE THING from the bar — where slides puts a new element: where you
   * are working. It goes AFTER the block holding the caret, as that block's
   * sibling and after anything nested in it; with no caret on the page it goes
   * at the end. One commit, so one undo takes it away, and the caret lands in
   * it — or the thing that fills it opens (the picker, the link card, the
   * first cell).
   */
  insertItem(item: InsertItem): void {
    const s = this.store
    const page = s.page
    if (!page || !this.canInsert()) return
    const at = this.caretBlock()
    const make = (): Block => {
      const fresh = newBlock(item.type)
      SPEC.get(item.type)?.init?.(fresh)
      item.init?.(fresh)
      if (at?.parent) fresh.parent = at.parent
      // a block born inside a canvas is born somewhere ON it
      placeNewCard(page, fresh)
      return fresh
    }
    const put = (fresh: Block) => {
      s.commit(() => {
        if (!at) { page.blocks.push(fresh); return }
        const i = page.blocks.findIndex((b) => b.id === at.id)
        // past the anchor's whole subtree: its children follow it in the list
        let end = i + 1
        const inside = new Set([at.id])
        while (end < page.blocks.length && page.blocks[end].parent && inside.has(page.blocks[end].parent!)) {
          inside.add(page.blocks[end].id)
          end++
        }
        page.blocks.splice(end, 0, fresh)
      })
      this.paintPage()
    }
    // A page card is made whole or not at all: the picker comes FIRST, so the
    // one commit writes a card that points somewhere, and Escape inserts
    // nothing — never a card pointing at no page.
    // …and so is an embed: its own picker (a page, or one section of it)
    if (item.type === 'embed') {
      this.insertEmbed(at?.id ?? page.id, (pageId, anchor) => {
        const fresh = make()
        this.embedFields(fresh, pageId, anchor)
        put(fresh)
      })
      return
    }
    if (item.type === 'pagelink') {
      this.openPagePicker(at?.id ?? page.id, null, (pageId) => {
        const fresh = make()
        fresh.page = pageId
        fresh.html = ''
        put(fresh)
      })
      return
    }
    const fresh = make()
    put(fresh)
    // the block is already a `link`: dismissing the dialog leaves an empty
    // card with its own way back in, never a half-made block
    if (item.type === 'link') this.openLinkCard(fresh.id)
    else if (item.type === 'image') void this.pickImage(fresh.id)
    // a table's text is in its cells: the caret belongs in the first one
    else if (item.type === 'table') this.focusCell(fresh.id, 0, 0)
    // straight to the picker, like Image; cancelling leaves the block's own
    // chooser (render.ts 'media')
    else if (item.type === 'media') void this.pickMedia(fresh.id)
    else this.focusBlock(fresh.id)
  }

  /** The bar's Comment: on the block holding the caret, or on the page. */
  private commentHere(): void {
    if (!this.canInsert()) return
    this.comments.openNew(this.caretBlock()?.id)
  }

  /** Move a block (and anything nested under it) to sit after another. */
  /**
   * What you can do to a block, declared ONCE.
   *
   * Four of these existed NOWHERE, on any device: move up, move down,
   * duplicate, delete. Deletion was Backspace-into-the-previous-block and
   * reordering was drag-only — and the drag gutter is hidden on touch, so on a
   * phone a block could not be reordered or removed at all.
   *
   * One list, so the desktop menu and the touch sheet cannot drift — the same
   * reasoning as the topbar's secondary actions.
   */
  private blockActions(id: string): Array<{ icon: IconName; label: string; kbd?: string; run: () => void; off?: boolean }> {
    const s = this.store
    const page = s.page
    const blocks = page?.blocks ?? []
    const at = blocks.findIndex((b) => b.id === id)
    // a block moves past its SIBLINGS; a child cannot jump out of its parent by
    // stepping, which would silently re-home it
    const owner = blocks[at]?.parent
    const sibs = blocks.filter((b) => b.parent === owner)
    const si = sibs.findIndex((b) => b.id === id)

    return [
      // FIRST, and only for a link card. The card's own edit button appears on
      // hover, which is a gesture a touch screen does not have — this menu is
      // the touch sheet too, so without an entry here a card could be made on a
      // phone and never changed.
      ...(blocks[at]?.type === 'link'
        ? [{ icon: 'globe' as const, label: t('Edit this link card'),
          run: () => this.openLinkCard(id) }]
        : []),
      { icon: 'text', label: t('Turn into…'),
        run: () => this.openSlash(id) },
      { icon: 'plus', label: t('Add below'), kbd: '↵', run: () => this.insertAfter(id) },
      { icon: 'up', label: t('Move up'), off: si <= 0,
        run: () => { if (si > 0) this.moveBefore(id, sibs[si - 1].id) } },
      { icon: 'down', label: t('Move down'), off: si < 0 || si >= sibs.length - 1,
        run: () => { if (si >= 0 && si < sibs.length - 1) this.moveBlock(id, sibs[si + 1].id) } },
      { icon: 'copy', label: t('Duplicate'), run: () => this.duplicateBlock(id) },
      // The gutter holds two controls and a phone fits one, so commenting
      // lives in the menu BOTH of them open — which is also the touch sheet.
      { icon: 'comment', label: t('Comment'), run: () => this.comments.openNew(id) },
      { icon: 'trash', label: t('Delete'), kbd: '⌫', run: () => this.deleteBlock(id) },
    ]
  }

  /**
   * Change one field's value.
   *
   * Writes `value` AND `html` together, always. The readable form is what an
   * older build, a thumbnailer, a grep and the markdown export see, so a value
   * written without it is a value those readers cannot see at all — which is
   * the entire reason field values are blocks rather than page keys.
   */
  private setField(blockId: string, value: unknown): void {
    const s = this.store
    const at = s.index.block.get(blockId)
    if (!at) return
    const f = fieldByKey(s.doc, String((at.block as { key?: unknown }).key ?? ''))
    if (!f) return
    // PAGE SCOPE ONLY WHEN THE VALUE IS ON THE PAGE IN VIEW. The store's page
    // entry snapshots `store.pageId` by definition (store.ts entry()), and a
    // status changed from a BOARD lives on another page — so a page-scoped
    // checkpoint would record the board, and undo would restore the board while
    // leaving the changed status exactly where it was. Cheap when it is right,
    // silently wrong when it is not.
    const scope = at.pageId === s.pageId ? 'page' : 'doc'
    s.commit(() => this.applyField(at.block, f, value), { scope })
    this.paintPage()
  }

  /**
   * THE ONE WRITER for a field value. `value` and `html` move together, always,
   * because the readable form is the only thing an older build, a thumbnailer,
   * a grep and the markdown export can see. Every path that sets a value —
   * the header chip, the board's card button, a drag between columns — goes
   * through here, so there is one place for the two to fall out of step and it
   * is three lines long.
   */
  private applyField(b: Block, f: FieldSpec, value: unknown): void {
    ;(b as Record<string, unknown>).value = value
    b.html = propHtml(f, value)
  }

  /**
   * Set a field ON A PAGE, adding the prop block when the page does not carry
   * one — the case a board drop already had and a table cell now has too.
   *
   * A page can be in a view without carrying every field the view shows: a
   * board grouped by something an issue never had, or a table column that
   * exists because SOME other row has it. The value arrives in the header strip
   * where the others are, through propBlock, so the readable `html` is written
   * with it. A value written without its readable form is a value an older
   * build, a thumbnailer, a grep and the markdown export all see as nothing.
   *
   * Not a commit of its own: the caller decides what one user action was.
   */
  private putField(page: Page, f: FieldSpec, value: unknown): void {
    const own = propBlockOf(page, f.key)
    if (own) this.applyField(own, f, value)
    else page.blocks.splice(headerLength(page), 0, propBlock(f, value, newBlock('prop').id))
  }

  /**
   * A TABLE CELL, opened for editing. The same picker the page's own header
   * strip opens, over the same writer a board drop uses.
   *
   * Addressed by PAGE AND KEY rather than by block id, because the interesting
   * cell is the empty one: the page has no prop block for that column, and the
   * edit is what creates it. Looking the block up here — after the value is
   * chosen, in setCell — also means an opened-and-dismissed picker writes
   * nothing at all.
   */
  private openCellPicker(pageId: string, key: string, anchor: HTMLElement): void {
    const s = this.store
    if (s.readOnly || this.reading) return
    const page = s.index.page.get(pageId)
    const f = fieldByKey(s.doc, key)
    if (!page || !f) return
    const own = propBlockOf(page, key)
    this.fieldPicker(f, own ? (own as { value?: unknown }).value : undefined, anchor,
      (v) => this.setCell(pageId, key, v))
  }

  /**
   * Write one cell. Nothing happens when the value did not change: a picker
   * opened and closed on the value already there must not be a step you press
   * ⌘Z past.
   *
   * PAGE SCOPE ONLY WHEN THE ROW IS THE PAGE IN VIEW, for the reason setField
   * carries: a page-scoped checkpoint snapshots `store.pageId`, and a cell in a
   * table almost always belongs to ANOTHER page — undo would restore the page
   * holding the view and leave the changed value exactly where it was.
   */
  private setCell(pageId: string, key: string, value: unknown): void {
    const s = this.store
    const page = s.index.page.get(pageId)
    const f = fieldByKey(s.doc, key)
    if (!page || !f || s.readOnly || this.reading) return
    const own = propBlockOf(page, key)
    if (own && (own as { value?: unknown }).value === value) return
    const scope = pageId === s.pageId ? 'page' : 'doc'
    s.commit(() => this.putField(page, f, value), { scope })
    this.paintPage()
  }

  private openFieldPicker(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    if (s.readOnly || this.reading) return
    const b = s.block(blockId)
    const f = b && fieldByKey(s.doc, String((b as { key?: unknown }).key ?? ''))
    if (!b || !f) return
    this.fieldPicker(f, (b as { value?: unknown }).value, anchor, (v) => this.setField(blockId, v))
  }

  /**
   * THE ONE PICKER for a field value: a list of options for a select, one input
   * for anything else.
   *
   * Takes a WRITER rather than a block id, and that is the whole reason it was
   * split out of openFieldPicker. A table cell can stand for a value that does
   * not exist yet — the page carries no such prop block — so there is no id to
   * hand it. Everything else about choosing a value has to stay identical
   * across the header strip, the board's card chip and a cell, or the same
   * gesture reads as three different controls.
   */
  private fieldPicker(
    f: FieldSpec, cur: unknown, anchor: HTMLElement, write: (v: unknown) => void,
  ): void {
    if (f.vt === 'select' && f.options?.length) {
      const now = String(cur ?? '')
      const options = f.options
      this.menuAt(anchor, f.label, (m) => {
        for (const o of options) {
          const b = row(m, { label: o.label, selected: o.id === now, run: () => write(o.id) })
          // the option's colour is the author's data: a style PROPERTY, never
          // markup handed to the row's icon slot
          const ico = el('span', 'bkm-ico')
          const dot = el('span', 'sp-prop-dot')
          if (o.color) dot.style.background = o.color
          ico.append(dot)
          b.prepend(ico)
        }
      })
      return
    }
    this.closeOverlay()
    const pop = el('div', 'sp-pop')
    {
      // free text, a number or a date: one field, committed on Enter
      const input = document.createElement('input')
      input.className = 'sp-find'
      input.type = f.vt === 'number' ? 'number' : f.vt === 'date' ? 'date' : 'text'
      input.value = String(cur ?? '')
      input.placeholder = f.label
      input.addEventListener('keydown', (e) => {
        if (e.key === 'Enter') {
          e.preventDefault()
          const raw = input.value.trim()
          this.closeOverlay()
          write(f.vt === 'number' ? (raw === '' ? '' : Number(raw)) : raw)
        }
      })
      input.setAttribute('aria-label', f.label)
      pop.append(input)
      afterPaint(() => input.focus())
    }
    this.float(pop, anchor, { role: 'dialog', label: f.label, onEscape: () => anchor.focus?.() })
  }

  /**
   * THE BOARD, made to work — with a mouse and with a finger.
   *
   * Three affordances over one writer:
   *   · DRAG a card to another column — that column's option becomes the value.
   *   · DRAG within a column — the pages move, because the order of the board
   *     IS the order of `doc.pages`. No stored per-view order: that would be a
   *     new permanent format field, and a drag handler is not the place to
   *     settle one (docs/DECISIONS.md, 2026-08-05).
   *   · TAP the status on a card — a phone cannot drag an HTML5 draggable at
   *     all, and the board is the tracker's main screen. It opens the SAME
   *     picker the issue's own header strip opens.
   *
   * Everything here is wired only when the document is editable: the renderer
   * emits no card button in reading view, in a locked space or on paper, and
   * this is not called there, so there is no half-live board anywhere.
   */
  private wireBoard(root: HTMLElement): void {
    const s = this.store
    if (s.readOnly || this.reading) return
    for (const v of root.querySelectorAll<HTMLElement>('.sp-view')) {
      const vb = s.block(v.dataset.blockId ?? '')
      const groupKey = String((vb as { groupBy?: unknown } | undefined)?.groupBy ?? 'status')

      v.querySelector<HTMLElement>('[data-view-open]')?.addEventListener('click', () => {
        this.editViewFilter(v.dataset.blockId!, (f) => { if (f.open) delete f.open; else f.open = true })
      })
      const fb = v.querySelector<HTMLElement>('[data-view-filter]')
      fb?.addEventListener('click', () => this.openViewFilter(v.dataset.blockId!, fb))
      const lb = v.querySelector<HTMLElement>('[data-view-layout]')
      lb?.addEventListener('click', () => this.toggleViewLayout(v.dataset.blockId!))
      const spb = v.querySelector<HTMLElement>('[data-view-span]')
      spb?.addEventListener('click', () => this.toggleViewSpan(v.dataset.blockId!))
      const gb = v.querySelector<HTMLElement>('[data-view-group]')
      gb?.addEventListener('click', () => this.openViewGroup(v.dataset.blockId!, gb))
      const sb = v.querySelector<HTMLElement>('[data-view-sort]')
      sb?.addEventListener('click', () => this.openViewSort(v.dataset.blockId!, sb))
      const srcB = v.querySelector<HTMLElement>('[data-view-source]')
      srcB?.addEventListener('click', () => this.openViewSource(v.dataset.blockId!, srcB))

      // A SORTED BOARD HAS NO HAND ORDER TO DROP INTO. The sort decides where a
      // card sits, so offering a drop position would write an order into
      // doc.pages that the very next paint discards — a gesture that appears to
      // do nothing, and a stray undo step. The column still accepts the card;
      // only the position within it stops being a question.
      const sorted = Array.isArray((vb as { sort?: unknown } | undefined)?.sort)
        && ((vb as { sort?: unknown[] }).sort!).length > 0

      for (const btn of v.querySelectorAll<HTMLElement>('[data-set-field]')) {
        btn.addEventListener('click', (e) => {
          e.preventDefault()
          this.openFieldPicker(btn.dataset.setField!, btn)
        })
      }

      // THE TABLE, made to work. A header is a control and a cell is a control,
      // both real <button>s from the renderer, so the keyboard reaches them and
      // Enter fires this same click — there is no second key path to keep in
      // step with the pointer one.
      for (const h of v.querySelectorAll<HTMLElement>('[data-sort-col]')) {
        h.addEventListener('click', () => {
          // ascending -> descending -> none, written into the view's OWN sort.
          // The third state deletes the key rather than storing an empty array,
          // so a table sorted and unsorted is byte-identical to one nobody
          // touched — the rule filter, source and layout all follow.
          const now = this.store.block(v.dataset.blockId ?? '')
          this.editView(v.dataset.blockId!, 'sort',
            cycleSort((now as { sort?: unknown } | undefined)?.sort, h.dataset.sortCol!))
        })
      }
      for (const c of v.querySelectorAll<HTMLElement>('[data-cell-field]')) {
        c.addEventListener('click', (e) => {
          e.preventDefault()
          this.openCellPicker(c.dataset.cellPage!, c.dataset.cellField!, c)
        })
      }

      // NO BOARD, NO DRAG. A list has cards but no columns, so a draggable card
      // there is an affordance that promises something nothing can accept.
      const board = v.querySelector('.sp-board')
      if (!board) continue

      const marks = () => {
        for (const n of v.querySelectorAll('.sp-drop, .sp-dropend, .sp-dropbefore')) {
          n.classList.remove('sp-drop', 'sp-dropend', 'sp-dropbefore')
        }
      }
      for (const card of v.querySelectorAll<HTMLElement>('.sp-issue[data-issue]')) {
        card.draggable = true
        // A LINK DRAGS ITSELF, carrying its href, and that gesture would beat
        // the card's. Told not to, the drag belongs to the nearest draggable
        // ancestor, which is the card.
        card.querySelector('a')?.setAttribute('draggable', 'false')
        card.addEventListener('dragstart', (e) => {
          e.dataTransfer?.setData('text/bento-issue', card.dataset.issue!)
          card.classList.add('sp-dragging')
        })
        card.addEventListener('dragend', () => { card.classList.remove('sp-dragging'); marks() })
      }

      // THE COLUMN UNDER THE POINTER, never a guess — cleared on the way DOWN
      // (capture, on the board) and re-marked on the way up (the column the
      // pointer is actually inside). So the mark is where the pointer is and
      // nowhere else, including over the "Other" column, which accepts no drop
      // and must therefore not leave the last real column looking like a target.
      //
      // `dragleave` cannot do this: it bubbles from every child, so moving
      // across a card inside a column reports leaving the column.
      board.addEventListener('dragover', (e) => {
        if ((e as DragEvent).dataTransfer?.types.includes('text/bento-issue')) marks()
      }, true)
      for (const col of v.querySelectorAll<HTMLElement>('.sp-col[data-group]')) {
        col.addEventListener('dragover', (e) => {
          if (!e.dataTransfer?.types.includes('text/bento-issue')) return
          e.preventDefault()
          col.classList.add('sp-drop')
          if (sorted) return
          const aim = this.aimAt(col, e.clientY)
          if (aim.before) col.querySelector(`[data-issue="${CSS.escape(aim.before)}"]`)?.classList.add('sp-dropbefore')
          else col.classList.add('sp-dropend')
        })
        col.addEventListener('drop', (e) => {
          const moved = e.dataTransfer?.getData('text/bento-issue')
          if (!moved) return
          e.preventDefault()
          const aim = sorted ? null : this.aimAt(col, e.clientY)
          marks()
          this.dropIssue(moved, groupKey, col.dataset.group!, aim)
        })
      }
    }
  }

  /** Where in this column a drop at `y` lands: before a card, or after the last. */
  private aimAt(col: HTMLElement, y: number): DropAim {
    const cards = [...col.querySelectorAll<HTMLElement>('.sp-issue[data-issue]')]
    for (const c of cards) {
      const r = c.getBoundingClientRect()
      if (y < r.top + r.height / 2) return { before: c.dataset.issue }
    }
    return { after: cards[cards.length - 1]?.dataset.issue }
  }

  /**
   * A card landed. Set its value, move its page, or — if it landed where it
   * already was — do NOTHING: no commit, no undo entry, no dirty flag. A drag
   * that changes nothing must not be a step you have to press ⌘Z past.
   *
   * Both halves are ONE commit, because one drag is one user action.
   */
  private dropIssue(pageId: string, key: string, optId: string, aim: DropAim | null): void {
    const s = this.store
    const page = s.index.page.get(pageId)
    const f = fieldByKey(s.doc, key)
    if (!page || !f || s.readOnly) return
    const own = propBlockOf(page, key)
    const setting = !own || String((own as { value?: unknown }).value ?? '') !== optId
    // The no-op test is about the COLUMN, not the page array — those are
    // different orders the moment a board has two columns, and judging by page
    // adjacency let a drop that visibly did nothing rewrite doc.pages.
    //
    // A null aim is a SORTED board: there is no position to land in, so the
    // drop is only ever the value change.
    const cards = [...document.querySelectorAll<HTMLElement>(`.sp-col[data-group="${CSS.escape(optId)}"] .sp-issue[data-issue]`)]
      .map((c) => c.dataset.issue!)
    const moves = !!aim && columnMoves(cards, pageId, aim)
    const order = moves && aim ? reorderPages(s.doc.pages, pageId, aim) : null
    if (!setting && !order) return

    s.commit(() => {
      if (setting) this.putField(page, f, optId)
      if (order) s.doc.pages = order
    })
    this.repaint()
  }

  /**
   * Narrow a view. The filter lives on the `view` block, so it is saved, shared
   * and permanent.
   *
   * Rules an edit here must not break: unknown keys are a NEWER build's and are
   * never touched, and a filter that narrows nothing is DELETED rather than
   * stored empty — so a view someone filtered and unfiltered is byte-identical
   * to one that never was.
   */
  private editViewFilter(blockId: string, edit: (f: ViewFilter) => void): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    s.commit(() => {
      const next = { ...((b as { filter?: ViewFilter }).filter ?? {}) }
      edit(next)
      if (Object.keys(next).length) (b as { filter?: ViewFilter }).filter = next
      else delete (b as { filter?: ViewFilter }).filter
    }, { scope: 'page' })
    this.paintPage()
  }

  /**
   * A small menu anchored to a button — a bottom sheet on a phone.
   *
   * Four of these had grown the same twelve lines of boilerplate (build, trap,
   * sheet-or-place, dismiss on a click away), which is three copies too many
   * for something whose dismissal behaviour has to be identical everywhere:
   * a menu that closes differently from the one beside it reads as a bug.
   */
  private popover(anchor: HTMLElement, build: (pop: HTMLElement) => void): void {
    this.closeOverlay()
    const pop = el('div', 'sp-pop')
    // A panel of CONTROLS — the share panel, a comment thread — not a list of
    // commands. It announced itself as role=menu and held a textarea; a screen
    // reader then promised menu items and found a form. Menus go through
    // menuAt() and the kernel primitive.
    pop.tabIndex = -1
    build(pop)
    this.float(pop, anchor, { role: 'dialog', onEscape: () => anchor.focus?.() })
    // the keyboard lands inside, unless the popover already put it somewhere
    afterPaint(() => { if (!pop.contains(document.activeElement)) pop.focus() })
  }

  /**
   * Edit a key on a `view` block — layout, groupBy, sort.
   *
   * The same discipline as editViewFilter: an edit that says "the default"
   * DELETES the key rather than storing it, so a view somebody switched to a
   * list and back is byte-identical to one that was never touched, and a file
   * written before this control existed stays that way.
   */
  private editView(blockId: string, key: 'layout' | 'groupBy' | 'sort' | 'source' | 'span', value: unknown): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    s.commit(() => {
      const rec = b as unknown as Record<string, unknown>
      if (value === undefined || value === null) delete rec[key]
      else rec[key] = value
    }, { scope: 'page' })
    this.paintPage()
  }

  /** Board ⇄ list. `board` is the default, so it is stored as an ABSENT key. */
  /**
   * WHICH PAGES A VIEW HOLDS.
   *
   * The answer used to be one thing — every page carrying a `status` — which
   * is why a space could hold a backlog and nothing else. Two selectors now,
   * and only two: the pages carrying a given property, or the pages under a
   * given page. With a flat vocabulary where each page carries only the fields
   * it uses, "has an Author" IS "is a book".
   *
   * Issues stays the ABSENT key, so every view written before this keeps
   * showing the backlog and a view set back to Issues is byte-identical to one
   * that never moved.
   */
  private openViewSource(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b) return
    const set = (src: { has?: string; under?: string; tag?: string } | undefined) => this.editView(blockId, 'source', src)
    this.menuAt(anchor, t('Which pages'), (m) => {
      caption(m, t('Which pages'))
      row(m, { icon: ICONS.board, label: t('Issues'), hint: t('Every page with a status'), run: () => set(undefined) })

      // A property somebody invented is the interesting case, so it comes
      // first among the fields and lists every one the vocabulary has.
      for (const f of fieldsOf(s.doc)) {
        row(m, { icon: ICONS.tag, label: f.label, hint: t('Pages that have this property'), run: () => set({ has: f.key }) })
      }

      // Nesting is how a space is already organised, so the current page and
      // its ancestors are the ones worth offering rather than every page.
      const here = s.page
      if (here) {
        caption(m, t('Nested under'))
        row(m, { icon: ICONS.page, label: here.title || t('Untitled'), hint: t('Pages nested under this one'),
          run: () => set({ under: here.id }) })
      }

      // The tags the space ACTUALLY HAS, most-used first — never a free-text
      // box. A tag that has not been written selects nothing, and a picker
      // that let you ask for one would be a view that is empty for a reason
      // you cannot see. Capped, because this is a menu, not the tag index.
      const tags = tagList(s.tags).slice(0, 12)
      if (tags.length) {
        caption(m, t('Tagged'))
        for (const e of tags) {
          row(m, { icon: ICONS.tag, label: '#' + e.label, hint: t('Pages carrying this tag'),
            run: () => set({ tag: e.key }) })
        }
      }
    })
  }

  private toggleViewLayout(blockId: string): void {
    const b = this.store.block(blockId)
    // Board -> list -> table -> gallery -> calendar -> gantt -> workload ->
    // board, from fields.ts — the ONE place the cycle is written. It used to be written here and again in
    // render.ts, and when the prototype-lookup bug was found only this copy was
    // hardened, so the button went on rendering
    // `function toString() { [native code] }` as its label from the other one.
    //
    // `board` is the ABSENT key, never a stored 'board': a view cycled all the
    // way round is byte-identical to one nobody ever touched, which is the same
    // rule filter and source follow. nextLayout returns the WORD; turning
    // 'board' back into a deletion is the writer's job, and this is the writer.
    const to = nextLayout((b as { layout?: unknown } | undefined)?.layout)
    this.editView(blockId, 'layout', to === 'board' ? undefined : to)
  }

  /**
   * MONTH ⇄ AGENDA, the calendar's own second shape (stored as `span:
   * 'timeline'` — the agenda's on-disk name; see calendar.ts CAL_SPANS).
   *
   * A parameter of one layout, like `groupBy` — not a sixth entry in the layout
   * cycle, whose cost is one click for everybody every time they pass it. Same
   * writer discipline as every other view key: `month` is the DEFAULT, so it is
   * stored as an ABSENT key and a view toggled to the agenda and back is
   * byte-identical to one nobody touched.
   */
  private toggleViewSpan(blockId: string): void {
    const b = this.store.block(blockId)
    const to = nextSpan((b as { span?: unknown } | undefined)?.span)
    this.editView(blockId, 'span', to === 'month' ? undefined : to)
  }

  /**
   * Which field the columns come from.
   *
   * Only fields with declared options are offered for a BOARD. A board's
   * columns ARE the option list — grouping by a free-text field would make one
   * column per distinct string, which is a pivot table wearing a board's
   * clothes.
   *
   * A WORKLOAD CHART IS THAT PIVOT TABLE, DELIBERATELY, so it offers person and
   * text fields too: "how much is each person holding" is exactly one bar per
   * distinct string, and that is the whole shape. Same key, same writer, one
   * extra line — which is what it costs when a chart is a layout rather than a
   * second block type with a vocabulary of its own.
   */
  private openViewGroup(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    const shape = layoutOf((b as { layout?: unknown }).layout)
    const bars = shape === 'workload'
    const now = String((b as { groupBy?: unknown }).groupBy
      ?? (bars ? (bucketField(s.doc)?.key ?? '') : 'status'))
    const groupable = fieldsOf(s.doc).filter((f) =>
      f.options?.length || (bars && (f.vt === 'person' || f.vt === 'text')))
    // The DEFAULT for this shape is what absence already means, so choosing it
    // clears the key rather than writing it down — the rule filter, source and
    // sort all follow, and what keeps a view that was fiddled with and put back
    // byte-identical to one nobody touched.
    const dflt = bars ? bucketField(s.doc)?.key : 'status'
    this.menuAt(anchor, t('Group'), (m) => {
      for (const f of groupable) {
        row(m, { icon: ICONS.board, label: f.label, selected: f.key === now,
          run: () => this.editView(blockId, 'groupBy', f.key === dflt ? undefined : f.key) })
      }
      if (!groupable.length) extra(m, el('div', 'sp-fgroup', t('No field here has options to group by')))
    })
  }

  /**
   * The order. One key, though the format holds a list — see fields.ts.
   *
   * "Manual order" is the ABSENCE of a sort, not a sort called manual: it is
   * the page order, which is the order somebody arranged by dragging, and it
   * has to be reachable from here or a board is one click away from being
   * un-arrangeable forever.
   */
  private openViewSort(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    const cur = (Array.isArray((b as { sort?: unknown }).sort)
      ? ((b as { sort?: ViewSort[] }).sort ?? [])[0] : undefined) as ViewSort | undefined
    this.menuAt(anchor, t('Sort'), (m) => {
      row(m, { icon: ICONS.grip, label: t('Manual order'), selected: !cur,
        run: () => this.editView(blockId, 'sort', undefined) })
      caption(m, t('Sort'))
      for (const f of fieldsOf(s.doc)) {
        const mine = cur?.key === f.key
        // clicking the field you are already sorted by REVERSES it — the second
        // thing you want after "sort by priority" is "…the other way", and a
        // separate direction control for a one-key sort is a control nobody
        // finds
        const dir: 'asc' | 'desc' = mine && cur?.dir !== 'desc' ? 'desc' : 'asc'
        const hint = mine ? (cur?.dir === 'desc' ? t('Ascending') : t('Descending')) : ''
        row(m, { icon: ICONS.arrowDown, label: f.label, hint: hint || undefined, selected: mine,
          run: () => this.editView(blockId, 'sort', [dir === 'asc' ? { key: f.key } : { key: f.key, dir }]) })
      }
    })
  }

  /** Toggle one value of one field in a view's filter. */
  private toggleViewValue(blockId: string, key: string, id: string): void {
    this.editViewFilter(blockId, (f) => {
      const is: Record<string, string[]> = { ...(f.is ?? {}) }
      const had = is[key] ?? []
      const next = had.filter((v) => v !== id)
      if (next.length === had.length) next.push(id)
      if (next.length) is[key] = next
      else delete is[key]
      if (Object.keys(is).length) f.is = is
      else delete f.is
    })
  }

  /** Add, remove or re-combine a view's typed conditions. */
  private editClauses(blockId: string, edit: (list: Clause[]) => Clause[]): void {
    this.editViewFilter(blockId, (f) => {
      const next = edit(clausesOf(f))
      // an empty list is DELETED, never stored: the same rule `is` and `open`
      // follow, and what keeps a view conditioned and then cleared
      // byte-identical to one nobody ever touched
      if (next.length) f.where = next
      else { delete f.where; delete f.any }
      // `any` over one clause is a distinction without a difference, and a
      // stored key that changes nothing is a key somebody has to explain
      if (next.length < 2) delete f.any
    })
  }

  /**
   * Build one condition: a field, an operator, a value.
   *
   * A FORM, not a three-step menu chain. The three parts are one thought and
   * picking them through three popovers is the interaction that makes a filter
   * builder unusable — and the form is four native controls, which is what
   * makes it fit a phone sheet without a layout of its own.
   *
   * The operator list follows the FIELD TYPE (query.ts `opsFor`), because "is
   * more than" on a date and "is after" on a number are both questions nobody
   * asks, and the value control follows the OPERATOR: options for a select, a
   * window for `in`, a date picker for a date, nothing at all for `is empty`.
   */
  private openAddCondition(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    if (!s.block(blockId) || s.readOnly || this.reading) return
    const fields = fieldsOf(s.doc)
    this.popover(anchor, (pop) => {
      pop.append(el('div', 'sp-pop-title', t('Add a condition')))

      const wrap = (labelText: string, control: HTMLElement) => {
        const row = el('div', 'sp-field')
        row.append(el('label', 'sp-field-lbl', labelText), control)
        return row
      }
      const opt = (sel: HTMLSelectElement, value: string, label: string) => {
        const o = document.createElement('option')
        o.value = value
        o.textContent = label
        sel.append(o)
      }

      const keySel = document.createElement('select')
      keySel.className = 'sp-input'
      opt(keySel, ':title', t('Title'))
      for (const f of fields) opt(keySel, f.key, f.label)

      const opSel = document.createElement('select')
      opSel.className = 'sp-input'

      const valBox = el('div', 'sp-field')
      const valLbl = el('label', 'sp-field-lbl', t('Value'))

      const fieldNow = () => fields.find((f) => f.key === keySel.value)
      const buildOps = () => {
        opSel.textContent = ''
        const f = fieldNow()
        for (const o of opsFor(f?.vt)) opt(opSel, o, f?.vt === 'number' ? numberOpLabel(o) : opLabel(o))
      }
      const buildValue = () => {
        valBox.textContent = ''
        const f = fieldNow()
        const op = opSel.value
        // `is empty` and `is not empty` are the two questions with no operand,
        // so the control is ABSENT rather than disabled — a greyed box invites
        // somebody to try to type in it
        if (op === 'empty' || op === 'notEmpty') return
        valBox.append(valLbl)
        if (op === 'in') {
          const sel = document.createElement('select')
          sel.className = 'sp-input'
          for (const w of DATE_WINDOWS) opt(sel, w, windowLabel(w))
          valBox.append(sel)
        } else if (f?.options?.length && (op === 'eq' || op === 'ne')) {
          const sel = document.createElement('select')
          sel.className = 'sp-input'
          for (const o of f.options) opt(sel, o.id, o.label)
          valBox.append(sel)
        } else {
          const input = document.createElement('input')
          input.className = 'sp-input'
          input.type = f?.vt === 'number' ? 'number' : f?.vt === 'date' ? 'date' : 'text'
          valBox.append(input)
        }
      }
      keySel.addEventListener('change', () => { buildOps(); buildValue() })
      opSel.addEventListener('change', buildValue)
      buildOps()
      buildValue()

      pop.append(wrap(t('Field'), keySel), wrap(t('Condition'), opSel), valBox)

      const add = document.createElement('button')
      add.type = 'button'
      add.className = 'sp-btn sp-primary'
      add.textContent = t('Add condition')
      add.addEventListener('click', () => {
        const op = opSel.value as QueryOp
        const input = valBox.querySelector('select, input') as HTMLInputElement | HTMLSelectElement | null
        const raw = input ? input.value : ''
        // a condition with nothing in its box narrows nothing and would count
        // for nothing on the chip — so it is not added at all rather than
        // stored as a rule that does not apply
        if (!input || raw !== '') {
          const c: Clause = { key: keySel.value, op }
          if (input) c.v = fieldNow()?.vt === 'number' && Number.isFinite(Number(raw)) ? Number(raw) : raw
          this.editClauses(blockId, (list) => [...list, c])
        }
        this.closeOverlay()
      })
      pop.append(add)
      // The popover's keyboard trap focuses the POP, which is right for a list
      // of menu items and wrong for a form: you would arrive on a container and
      // have to Tab three times to reach the box you opened this to fill in.
      // Measured before this line: after clicking Add condition,
      // `document.activeElement` was `div.sp-pop`, and typing put the text
      // nowhere. The trap runs on its own tick, so this has to as well.
      setTimeout(() => keySel.focus(), 0)
    })
  }

  /**
   * The filter picker: the options of every select field as toggles, and the
   * typed conditions under them.
   *
   * IT USED TO BE TOGGLES ONLY, and the comment here said so as a decision:
   * "deliberately NOT a query builder… it cannot grow a language that then has
   * to be supported forever." Half of that stands and half of it did not
   * survive contact with the app. What stands is the shape — a FLAT list of
   * conditions, one all/any switch, no nesting, so the popover is still a list
   * you read top to bottom on a phone. What did not is the scope: a view with
   * five layouts over a filter that can only ask "which of these values" cannot
   * ask what its own layouts exist for — a calendar over dates that cannot say
   * "this week", a table over numbers that cannot say "more than". The
   * value-toggle list stays FIRST and unchanged, because it is still the one
   * question a board is asked most.
   */
  private openViewFilter(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    const cur = ((b as { filter?: ViewFilter }).filter ?? {}) as ViewFilter
    this.menuAt(anchor, t('Filter'), (m) => {
      for (const f of fieldsOf(s.doc)) {
        if (!f.options?.length) continue
        caption(m, f.label)
        for (const o of f.options) {
          const on = (cur.is?.[f.key] ?? []).includes(o.id)
          // the menu STAYS OPEN (keepOpen): picking three labels is one
          // thought, and reopening a menu between each is the thing that makes
          // filters unusable. Each toggle is still its own undo step.
          const item: HTMLButtonElement = row(m, { label: o.label, keepOpen: true, run: () => {
            const next = item.getAttribute('aria-checked') !== 'true'
            item.setAttribute('aria-checked', String(next))
            item.classList.toggle('bkm-selected', next)
            this.toggleViewValue(blockId, f.key, o.id)
          } })
          item.setAttribute('role', 'menuitemcheckbox')
          item.setAttribute('aria-checked', String(on))
          item.classList.toggle('bkm-selected', on)
          const ico = el('span', 'bkm-ico')
          const dot = el('span', 'sp-prop-dot')
          if (o.color) dot.style.background = o.color
          ico.append(dot)
          item.prepend(ico)
        }
      }
      m.separator()
      const conds = clausesOf(cur)
      caption(m, t('Conditions'))
      for (let i = 0; i < conds.length; i++) {
        const at = i
        // the row IS the remove control — a summary with a separate ✕ needs a
        // layout of its own, and every other list in this menu is already one
        // tap = one change
        row(m, { icon: ICONS.trash, label: clauseSummary(s.doc, conds[at]), hint: t('Remove'),
          run: () => this.editClauses(blockId, (list) => list.filter((_, j) => j !== at)) })
      }
      row(m, { icon: ICONS.plus, label: t('Add condition'), run: () => this.openAddCondition(blockId, anchor) })
      if (conds.length > 1) {
        const any = isAny(cur)
        // ONE switch for the whole list. Per-clause and/or is a tree, and a tree
        // needs a UI that can show one; this is the 90% and it reads in a line.
        row(m, { icon: ICONS.toggle, label: any ? t('Match any condition') : t('Match all conditions'),
          hint: t('Switch between all and any'),
          run: () => this.editViewFilter(blockId, (f) => { if (any) delete f.any; else f.any = true }) })
      }

      m.separator()
      // unknown keys survive: this clears what this build put there
      row(m, { icon: ICONS.trash, label: t('Clear filter'),
        run: () => this.editViewFilter(blockId, (f) => { delete f.is; delete f.open; delete f.where; delete f.any }) })
    })
  }

  /**
   * Turn the current page into an issue, or make a new one.
   *
   * There is no "issue type" — a page WITH A STATUS is an issue, so this adds
   * the fields and nothing else. Remove the status later and it is a document
   * again, with its body, links and history intact.
   */
  makeIssue(pageId?: string): void {
    const s = this.store
    const page = pageId ? s.index.page.get(pageId) : s.page
    if (!page || s.readOnly) return
    if (isIssue(page)) { this.notice(t('Already an issue')); return }
    const fields = fieldsOf(s.doc).filter((f) => ISSUE_FIELDS.includes(f.key))
    s.commit(() => {
      page.blocks.unshift(...fields.map((f) => propBlock(f, f.def ?? '', newBlock('prop').id)))
    })
    this.paintPage()
    this.status(t('Now an issue'))
  }

  /** A new issue: a page that starts with its fields, ready to be titled. */
  newIssue(): void {
    const s = this.store
    if (s.readOnly) return
    const page = newPage(t('New issue'))
    const fields = fieldsOf(s.doc).filter((f) => ISSUE_FIELDS.includes(f.key))
    page.blocks = [
      ...fields.map((f) => propBlock(f, f.def ?? '', newBlock('prop').id)),
      newBlock('p'),
    ]
    s.commit(() => { s.doc.pages.push(page) })
    s.goToPage(page.id)
    this.repaint()
    // the title is what you actually want to type first
    afterPaint(() => {
      const h = this.main.querySelector<HTMLElement>('[data-page-title]')
      h?.focus()
      if (h) { const r = document.createRange(); r.selectNodeContents(h); getSelection()?.removeAllRanges(); getSelection()?.addRange(r) }
    })
  }

  /** The block actions, as a menu. Anchored on a wide screen, a sheet on a phone. */
  private openBlockMenu(id: string, anchor: HTMLElement): void {
    if (this.store.readOnly || this.reading) return
    this.menuAt(anchor, t('Block options'), (m) => {
      // FIRST, above the actions: the block's own format. blockbar.ts records
      // why these are here and not in the selection toolbar.
      const page = this.store.page
      const blk = this.store.block(id)
      if (page && blk) {
        extra(m, blockFormatRow({
          type: String(blk.type ?? 'p'),
          canIndent: indentTarget(page.blocks, id).ok,
          canOutdent: canOutdent(effectiveParents(page), id),
          indentRefusal: t('a block nests under the one above it'),
          setType: (type) => { m.close(); this.setType(id, type) },
          // NOT closed first when the gesture is refused: `indent` answers with
          // the reason, and closing the menu would take the disabled control
          // away at the moment it is explaining itself.
          indent: (deeper) => {
            const allowed = deeper ? indentTarget(page.blocks, id).ok : canOutdent(effectiveParents(page), id)
            if (allowed) m.close()
            this.indent(id, deeper)
          },
        }))
      }
      for (const a of this.blockActions(id)) {
        row(m, { icon: ICONS[a.icon], label: a.label, kbd: a.kbd, off: a.off, run: a.run })
      }
    })
  }

  /** Move `id` to sit BEFORE `target` — the inverse of moveBlock's "after". */
  private moveBefore(id: string, target: string): void {
    const page = this.store.page
    if (!page) return
    const before = page.blocks.findIndex((b) => b.id === target)
    // the block that precedes the target is what `after` needs; at the top of a
    // sibling run there is none, so splice to the front instead
    const prev = page.blocks.slice(0, before).reverse().find((b) => b.parent === page.blocks[before]?.parent)
    if (prev) this.moveBlock(id, prev.id)
    else this.moveToFront(id)
  }

  private duplicateBlock(id: string): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const at = page.blocks.findIndex((b) => b.id === id)
    if (at < 0) return
    // the SUBTREE, with fresh ids and the parent links rewritten to match, or a
    // duplicated toggle's copy would adopt the original's children
    const remap = new Map<string, string>()
    const group: Block[] = []
    const take = (owner: string) => {
      for (const b of page.blocks) {
        if (b.parent !== owner) continue
        group.push(b)
        take(b.id)
      }
    }
    group.push(page.blocks[at])
    take(id)
    const copies = group.map((b) => {
      const fresh = { ...JSON.parse(JSON.stringify(b)), id: newBlock(b.type).id } as Block
      remap.set(b.id, fresh.id)
      return fresh
    })
    for (const c of copies) if (c.parent && remap.has(c.parent)) c.parent = remap.get(c.parent)
    s.commit(() => { page.blocks.splice(at + group.length, 0, ...copies) })
    this.paintPage()
    this.focusBlock(copies[0].id)
  }

  private deleteBlock(id: string): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const at = page.blocks.findIndex((b) => b.id === id)
    if (at < 0) return
    // children go with their owner, or they re-home at the top of the page and
    // reappear in a document the author believed they had emptied
    const doomed = new Set([id])
    let grew = true
    while (grew) {
      grew = false
      for (const b of page.blocks) {
        if (b.parent && doomed.has(b.parent) && !doomed.has(b.id)) { doomed.add(b.id); grew = true }
      }
    }
    const before = page.blocks[at - 1]?.id
    s.commit(() => {
      page.blocks = page.blocks.filter((b) => !doomed.has(b.id))
      // a page is never left with nothing to type into
      if (!page.blocks.length) page.blocks.push(newBlock('p'))
    })
    this.paintPage()
    this.focusBlock(before ?? page.blocks[0]?.id)
  }

  private moveToFront(id: string): void {
    const page = this.store.page
    if (!page) return
    const at = page.blocks.findIndex((b) => b.id === id)
    if (at <= 0) return
    this.store.commit(() => {
      const [b] = page.blocks.splice(at, 1)
      page.blocks.unshift(b)
    })
    this.paintPage()
  }

  private moveBlock(moved: string, after: string): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const from = page.blocks.findIndex((b) => b.id === moved)
    if (from < 0) return
    // a subtree travels with its owner, or its children would be orphaned
    const kids: string[] = []
    const collect = (id: string) => {
      for (const b of page.blocks) if (b.parent === id) { kids.push(b.id); collect(b.id) }
    }
    collect(moved)
    if (kids.includes(after)) return // never drop a block inside its own subtree
    s.commit(() => {
      const group = [moved, ...kids].map((id) => page.blocks.find((b) => b.id === id)!).filter(Boolean)
      for (const b of group) page.blocks.splice(page.blocks.indexOf(b), 1)
      // AFTER the target's whole SUBTREE, not merely after the target.
      // Landing immediately after a container put the block between that
      // container and its children — the array stayed pre-order but the child
      // no longer followed its parent contiguously, so the renderer's forward
      // pass popped the open container and drew the child at root. Measured:
      // moving the first block down past a toggle un-nested the toggle's body.
      const tgt = page.blocks.findIndex((b) => b.id === after)
      let at = tgt + 1
      if (tgt >= 0) {
        const under = new Set([after])
        while (at < page.blocks.length) {
          const p = page.blocks[at].parent
          if (!p || !under.has(p)) break
          under.add(page.blocks[at].id)
          at++
        }
      }
      page.blocks.splice(at, 0, ...group)
    })
    this.paintPage()
  }

  /** the block whose ghost answer is currently showing, if any */
  private ghostFor: string | null = null

  private clearGhost(): void {
    this.main.querySelectorAll('.sp-preview').forEach((n) => n.remove())
    this.ghostFor = null
  }

  /**
   * While you type, show what the answer WOULD be.
   *
   * The answer is not in the document yet and must not look as though it is:
   * it renders muted, beside the line, and says how to keep it. Pressing Tab
   * appends the `=` — so committing is one keystroke, and ignoring it is none,
   * which is the right balance for something that appears while you are
   * writing prose.
   *
   * Nothing is shown for a line that already asks (the real answer is there),
   * for a line that does not fully parse, or for a bare number — `42` on its
   * own is not a calculation anybody needs confirming.
   */
  private ghost(id: string, host: HTMLElement): void {
    const s = this.store
    if (this.ghostFor && this.ghostFor !== id) this.clearGhost()
    const block = s.block(id)
    const page = s.page
    if (!block || !page) return
    const line = textOf(host.innerHTML)
    const holder = host.parentElement
    if (!holder) return
    holder.querySelectorAll('.sp-preview').forEach((n) => n.remove())
    this.ghostFor = null
    if (asksForAnswer(line) || !/[-+*/^%=]|\bin\b|\bof\b/.test(line)) return

    const ctx = pageContext(page.blocks.map((x) => ({ id: x.id, text: textOf(x.html ?? '') })), id)
    const v = evaluate(line, ctx)
    // a bare number is not a calculation; neither is a line that only names a
    // value already defined
    if (!v || /^\s*[\d.,_]+\s*$/.test(line)) return

    const g = document.createElement('span')
    g.className = 'sp-preview'
    g.contentEditable = 'false'
    g.setAttribute('aria-hidden', 'true')
    g.textContent = `= ${format(v, locale())}`
    const kbd = document.createElement('kbd')
    kbd.textContent = 'Tab'
    g.appendChild(kbd)
    holder.appendChild(g)
    this.ghostFor = id
  }

  /**
   * Keep the ghost answer: append the `=` that asks for it.
   *
   * The ANSWER is not written — only the question. That is the whole design:
   * the document holds `budget * 0.3 =` and the number is derived every time
   * the page is drawn, so changing `budget` above updates this line too.
   * Writing the number here would freeze it, and a frozen number that no
   * longer matches its own expression is worse than no number at all.
   */
  private commitAnswer(id: string): boolean {
    const s = this.store
    const b = s.block(id)
    if (!b || s.readOnly) return false
    const html = `${(b.html ?? '').replace(/\s+$/, '')} =`
    s.commit(() => { b.html = html })
    this.clearGhost()
    this.paintPage()
    afterPaint(() => {
      const h = this.main.querySelector<HTMLElement>(`[data-edit="${CSS.escape(id)}"]`)
      // caret at the END, not selecting the line: you asked for the answer,
      // you did not ask to replace what you wrote
      if (!h) return
      h.focus()
      const r = document.createRange()
      r.selectNodeContents(h)
      r.collapse(false)
      const sel = getSelection()
      sel?.removeAllRanges()
      sel?.addRange(r)
    })
    return true
  }

  /**
   * Attach behaviour to a freshly painted page.
   *
   * EMBEDDED CONTENT IS PARKED FOR THE DURATION, and that is not tidiness.
   * Everything below sweeps the painted page by class or attribute — every
   * `.sp-check`, every `.sp-b-code`, every table cell — and hangs a handler
   * that commits through `store.block(id)`, which resolves ANY id in the
   * document. An embed draws ANOTHER page's blocks inside this one, so without
   * this a tick in an embedded checklist would commit to a page the editor is
   * not showing, and a language chip would be appended into somebody else's
   * paragraph. The renderer already strips `data-block-id` from that subtree;
   * this closes the half that keys on classes instead.
   *
   * Detached and restored rather than filtered at each of the fifteen sweeps:
   * one guarantee in one place cannot be forgotten by the sixteenth.
   */
  private wire(view: HTMLElement): void {
    const parked: Array<[HTMLElement, Comment]> = []
    for (const body of view.querySelectorAll<HTMLElement>('.sp-embed-body')) {
      const mark = document.createComment('embed')
      body.replaceWith(mark)
      parked.push([body, mark])
    }
    try { this.wireOwn(view) } finally {
      for (const [body, mark] of parked) mark.replaceWith(body)
    }
  }

  private wireOwn(view: HTMLElement): void {
    const s = this.store

    const title = view.querySelector<HTMLElement>('[data-page-title]')
    if (title) {
      title.dataset.ph = t('Untitled')
      if (!title.textContent?.trim()) title.dataset.empty = '1'
      title.addEventListener('input', () => { if (title.textContent?.trim()) delete title.dataset.empty; else title.dataset.empty = '1' })
    }
    title?.addEventListener('input', () => {
      if (this.painting) return
      const id = title.dataset.pageTitle!
      s.runEdit(`title:${id}`, () => {
        const p = s.index.page.get(id)
        if (p) p.title = title.textContent ?? ''
      })
      this.paintTreeSoon()
    })

    for (const node of view.querySelectorAll<HTMLElement>('[data-block-id]')) {
      if (!s.readOnly && !this.reading) this.addGutter(node, node.dataset.blockId!)
    }

    for (const host of view.querySelectorAll<HTMLElement>('[data-edit]')) {
      const id = host.dataset.edit!
      // A code block's host holds TEXT, not inline html, and carries colour
      // that must never reach the model. It gets its own wiring.
      if (s.block(id)?.type === 'code') { this.wireCode(id, host); continue }
      host.dataset.ph = t('Type / for blocks, [[ to link a page')
      host.addEventListener('input', () => {
        if (this.painting) return
        delete host.dataset.empty
        s.runEdit(id, () => {
          const b = s.block(id)
          // readInline, NOT innerHTML: a render drew `#tag` chips into this
          // host and the model must never learn they happened (tags.ts).
          if (b) b.html = readInline(host)
        })
        this.autoformat(id, host)
        this.ghost(id, host)
      })
      host.addEventListener('blur', () => {
        if (this.painting) return
        this.clearGhost()
        s.endRun()
        const b = s.block(id)
        if (b && b.html !== undefined) {
          const clean = canonicalize(b.html)
          if (clean !== b.html) { b.html = clean; host.innerHTML = clean }
        }
        // Chips settle on BLUR, never during a run: redrawing them per
        // keystroke would replace the nodes the caret is standing in. Blur is
        // also when a chip that grew (a caret at its end is INSIDE the <a>, so
        // typing there appends to it) is taken apart and re-read.
        redecorateTags(host)
        // A FOOTNOTE REFERENCE TYPED INTO THIS BLOCK CHANGES THE PAGE.
        //
        // The section at the foot is derived from every block's references, so
        // adding or deleting a `[^1]` renumbers the notes and adds or removes a
        // row. Repainting on `input` would do it a keystroke sooner and take
        // the caret with it — half of `[^1` is not a reference, so every one of
        // those keystrokes is a signature change. Blur is the first moment the
        // caret is not the thing being protected.
        this.syncFootnotes()
      })
    }

    // FOOTNOTE BODIES. `data-edit-note` and not `data-edit`: the generic
    // handler above writes its host's html to a BLOCK, and a note is not one.
    // The label is the key into doc.footnotes and it is derived from the text —
    // so a note is created by the first keystroke into an empty slot and the
    // slot itself came from a `[^label]` somebody typed.
    if (!s.readOnly && !this.reading) {
      for (const body of view.querySelectorAll<HTMLElement>('[data-edit-note]')) {
        const label = body.dataset.editNote!
        body.addEventListener('input', () => {
          if (this.painting) return
          s.runEdit(`fn:${label}`, () => {
            const table = (s.doc.footnotes ??= {})
            table[label] = body.innerHTML
          })
        })
        body.addEventListener('blur', () => {
          if (this.painting) return
          s.endRun()
          const table = s.doc.footnotes
          if (!table || !Object.hasOwn(table, label)) return
          const clean = canonicalize(table[label])
          // AN EMPTIED NOTE IS DELETED, not stored as ''. An empty string is a
          // note that exists and says nothing, which reads to validate() as a
          // satisfied reference and prints as a blank numbered line; deleting
          // the key puts the reference back to dangling, which is the truth and
          // is what the author just did.
          if (!clean.trim()) delete table[label]
          else if (clean !== table[label]) { table[label] = clean; body.innerHTML = clean }
        })
      }
    }

    for (const box of view.querySelectorAll<HTMLInputElement>('.sp-check')) {
      box.addEventListener('change', () => {
        const id = (box.closest('[data-block-id]') as HTMLElement).dataset.blockId!
        s.commit(() => { const b = s.block(id); if (b) b.done = box.checked }, { structure: false })
        box.closest('[data-block-id]')!.classList.toggle('sp-done', box.checked)
      })
    }

    // the callout's own mark and name ARE the control that changes them — a
    // tone buried in a menu is a tone nobody ever changes
    // Reading view is READ-ONLY, and this loop is the one that forgot: the
    // renderer already emits an inert <span> when !opts.editable, so the wiring
    // contradicted the renderer's own intent and a click in reading view
    // committed a tone change — undo entry, dirty flag and all. The gutter and
    // language loops guard the same way.
    if (!this.store.readOnly && !this.reading) {
      for (const chip of view.querySelectorAll<HTMLElement>('.sp-callout-chip')) {
        chip.addEventListener('click', (e) => {
          e.preventDefault()
          const id = (chip.closest('[data-block-id]') as HTMLElement).dataset.blockId!
          this.openTonePicker(id, chip)
        })
      }
    }

    for (const tw of view.querySelectorAll<HTMLElement>('.sp-twist')) {
      tw.addEventListener('click', () => {
        const id = (tw.closest('[data-block-id]') as HTMLElement).dataset.blockId!
        s.commit(() => { const b = s.block(id); if (b) b.open = !b.open })
        this.paintPage()
      })
    }

    // FIELD CHIPS. Changing a status is the loop a tracker exists for, so it is
    // one click from the issue and one from the board — never a form.
    if (!this.store.readOnly && !this.reading) {
      for (const chip of view.querySelectorAll<HTMLElement>('[data-edit-field]')) {
        chip.addEventListener('click', (e) => {
          e.preventDefault()
          const id = (chip.closest('[data-block-id]') as HTMLElement).dataset.blockId!
          this.openFieldPicker(id, chip)
        })
      }
      this.wireBoard(view)
      this.wireTables(view)
      // Charts keep their own wiring in their own file, like the canvas: one
      // control (which period) over data this file knows nothing about.
      wireCharts(view, {
        block: (id) => this.store.block(id),
        doc: () => this.store.doc,
        commit: (fn) => this.store.commit(fn),
        repaint: () => this.paintPage(),
        today: () => todayISO(),
        uid: () => uid('pd'),
        menu: (anchor, label, fill) => { this.menuAt(anchor, label, fill) },
      })
      // The canvas keeps its own wiring in its own file: the drag, the cards
      // and the shape button are one feature and touch nothing else here.
      wireCanvas(view, {
        block: (id) => this.store.block(id),
        page: () => this.store.page,
        commit: (fn, opts) => this.store.commit(fn, opts),
        repaint: () => this.paintPage(),
        pickPage: (then) => this.openPagePicker('', null, then),
      })
    }

    // "Load this image" — the reader's consent to contact one remote host.
    // NOT a commit: nothing about the document changed, so this must not touch
    // undo, the dirty flag or autosave. It is view state, and it dies with the
    // session (see allowedRemote).
    for (const btn of view.querySelectorAll<HTMLElement>('[data-load-remote]')) {
      btn.addEventListener('click', (e) => {
        e.preventDefault()
        this.allowedRemote.add(btn.dataset.loadRemote!)
        this.paintPage()
      })
    }

    // an image can arrive by paste or by drop, not only through a menu
    view.addEventListener('paste', (e) => {
      const cur = this.blockAt(document.activeElement)
      if (e.clipboardData?.files?.length) {
        e.preventDefault()
        void this.fileFromTransfer(e.clipboardData, cur?.id)
      }
    })
    view.addEventListener('dragover', (e) => {
      if (e.dataTransfer?.types.includes('Files')) { e.preventDefault(); view.classList.add('sp-filedrop') }
    })
    view.addEventListener('dragleave', () => view.classList.remove('sp-filedrop'))
    view.addEventListener('drop', (e) => {
      if (!e.dataTransfer?.types.includes('Files')) return
      view.classList.remove('sp-filedrop')
      // markdown (or a folder) is an IMPORT: leave it for the app-level
      // handler rather than rummaging through it for an image
      if (isImportDrop(e.dataTransfer)) return
      e.preventDefault()
      const near = (e.target as HTMLElement)?.closest?.('[data-block-id]') as HTMLElement | null
      void this.fileFromTransfer(e.dataTransfer, near?.dataset.blockId)
    })

    // The language chip. It belongs to the EDITOR, not the renderer: a reader
    // and a printed page get the colours, not the control that changes them.
    if (!s.readOnly && !this.reading) {
      for (const node of view.querySelectorAll<HTMLElement>('.sp-b-code')) {
        const id = node.dataset.blockId!
        const chip = document.createElement('button')
        chip.className = 'sp-btn sp-langchip'
        chip.type = 'button'
        // the RAW tag when this build cannot highlight it, so a `rust` block
        // says "rust" and its plain rendering reads as a gap, not a bug
        chip.textContent = langLabel(s.block(id)?.lang) || t('Plain text')
        chip.title = t('Language — what this block is highlighted as')
        chip.setAttribute('aria-label', t('Language — what this block is highlighted as'))
        chip.addEventListener('click', () => this.openLangPicker(id, chip))
        node.append(chip)
      }
    }

    for (const fig of view.querySelectorAll<HTMLElement>('.sp-b-image')) {
      const id = fig.dataset.blockId!
      const b = s.block(id)
      const tools = el('div', 'sp-imgtools')
      const sizeBtn = document.createElement('button')
      sizeBtn.className = 'sp-btn'
      sizeBtn.type = 'button'
      sizeBtn.textContent = `${b?.width ?? 100}%`
      sizeBtn.title = t('Width in the text column')
      sizeBtn.addEventListener('click', () => {
        const steps = [100, 75, 50, 33]
        const cur = Number(b?.width ?? 100)
        const next = steps[(steps.indexOf(cur) + 1) % steps.length]
        s.commit(() => { const bb = s.block(id); if (bb) bb.width = next })
        this.paintPage()
      })
      tools.append(sizeBtn)
      // a re-encoded image says so, and offers the untouched bytes back
      if (b && b.original === false) {
        const badge = document.createElement('button')
        badge.className = 'sp-btn sp-badge'
        badge.type = 'button'
        badge.textContent = t('Resized')
        badge.title = t('This image was resized to keep the file small. Click to replace it with the original.')
        badge.addEventListener('click', () => void this.pickImage(id))
        tools.append(badge)
      }
      fig.append(tools)
    }

    // VIDEO AND AUDIO. The chooser on an empty block, and the playback
    // switches on a full one. All of it is editor chrome, deliberately: the
    // renderer draws the clip, and a reader, a printout and a locked space get
    // the clip without the switches that change it — the same rule the callout
    // chip and the language chip follow.
    for (const node of view.querySelectorAll<HTMLElement>('.sp-b-media')) {
      const id = node.dataset.blockId!
      for (const btn of node.querySelectorAll<HTMLElement>('[data-pick-media]')) {
        btn.addEventListener('click', () => void this.pickMedia(id))
      }
      for (const btn of node.querySelectorAll<HTMLElement>('[data-link-media]')) {
        btn.addEventListener('click', () => this.linkMedia(id))
      }
      const b = s.block(id)
      if (s.readOnly || this.reading || !b || !b.src) continue
      const kind = String(b.kind ?? 'video') === 'audio' ? 'audio' : 'video'
      const tools = el('div', 'sp-mediatools')
      const flip = (label: string, title: string, on: boolean, set: (v: boolean) => void) => {
        const btn = document.createElement('button')
        btn.className = 'sp-btn' + (on ? ' sp-on' : '')
        btn.type = 'button'
        btn.textContent = label
        btn.title = title
        btn.setAttribute('aria-pressed', String(on))
        btn.addEventListener('click', () => {
          s.commit(() => { const bb = s.block(id); if (bb) set(!on) })
          this.paintPage()
        })
        tools.append(btn)
      }

      // WIDTH IS A VIDEO QUESTION. An <audio> is a control bar of the
      // browser's own height; a percentage of the measure would only make it
      // a shorter control bar.
      if (kind === 'video') {
        const sizeBtn = document.createElement('button')
        sizeBtn.className = 'sp-btn'
        sizeBtn.type = 'button'
        sizeBtn.textContent = `${b.width ?? 100}%`
        sizeBtn.title = t('Width in the text column')
        sizeBtn.addEventListener('click', () => {
          const steps = [100, 75, 50, 33]
          const cur = Number(b.width ?? 100)
          const next = steps[(steps.indexOf(cur) + 1) % steps.length]
          s.commit(() => { const bb = s.block(id); if (bb) bb.width = next })
          this.paintPage()
        })
        tools.append(sizeBtn)

        const poster = document.createElement('button')
        poster.className = 'sp-btn' + (b.poster ? ' sp-on' : '')
        poster.type = 'button'
        poster.textContent = t('Poster…')
        poster.title = t('A still frame, shown before play — and what a printout or a file preview shows')
        poster.addEventListener('click', () => void this.pickPoster(id))
        tools.append(poster)

        flip(t('Muted'), t('Start silent'), b.muted === true,
          (v) => { const bb = s.block(id); if (bb) bb.muted = v })
      }
      flip(t('Loop'), t('Repeat when it reaches the end'), b.loop === true,
        (v) => { const bb = s.block(id); if (bb) bb.loop = v })
      // absent means shown, so the OFF state is the one that is written down
      flip(t('Controls'), t('Show playback controls to the reader'), b.controls !== false,
        (v) => { const bb = s.block(id); if (bb) { if (v) delete bb.controls; else bb.controls = false } })

      const replace = document.createElement('button')
      replace.className = 'sp-btn'
      replace.type = 'button'
      replace.textContent = t('Replace…')
      replace.title = t('Choose a different file')
      replace.addEventListener('click', () => void this.pickMedia(id))
      tools.append(replace)

      // a linked clip says so, because it is the one that stops working on a
      // train — and the badge is the only place that fact is visible
      if (typeof b.src === 'string' && isRemote(b.src)) {
        const badge = document.createElement('span')
        badge.className = 'sp-btn sp-badge'
        badge.textContent = t('Linked')
        badge.title = t('Not in this file: it needs the network, and the site is told when someone opens the page')
        tools.append(badge)
      }
      node.append(tools)
    }
    // A link card OPENS its link, so its editing control is a separate button —
    // rendered only where there is an editor (render.ts), wired here.
    view.addEventListener('click', (e) => {
      const btn = (e.target as HTMLElement).closest<HTMLElement>('[data-edit-link]')
      if (!btn) return
      e.preventDefault()
      this.openLinkCard(btn.dataset.editLink!)
    })

    // intra-space links navigate without leaving the document
    view.addEventListener('click', (e) => {
      const a = (e.target as HTMLElement).closest('a')
      if (!a) return
      // A tag chip is an <a> with no href (tags.ts explains why it has none),
      // so it is caught HERE, before the href test — and caught by the same
      // listener, because the whole point of a chip is that it behaves like
      // the link it visually is, inside a contenteditable where the browser
      // would follow nothing anyway.
      const tag = a.dataset.tag
      if (tag) { e.preventDefault(); this.openTag(tag); return }
      const href = a.getAttribute('href') ?? ''
      if (!href.startsWith('#p/')) return
      // through the same resolver as the address bar, so a block anchor
      // navigates to its page instead of doing nothing at all
      e.preventDefault()
      const id = this.resolveAnchor(href)
      if (id) s.goToPage(id)
    })
  }

  /**
   * A code block's editable host.
   *
   * TWO THINGS DIFFER from every other block, and both are load-bearing.
   *
   * The MODEL takes `textContent`, not `innerHTML`. The host now contains
   * colour spans; reading innerHTML would write them into `b.html` and the
   * document would carry presentation — a format change, permanent, for a
   * feature that is supposed to be render-only. What is stored is the same
   * html-escaped plain text a code block has always stored, so files written
   * before highlighting existed and files written after are indistinguishable.
   *
   * The COLOUR is repainted synchronously on input, and `paintCode` reconciles
   * rather than replacing — see its comment. Measured on the built shell: an
   * insertion in the middle of a line changes no token boundary, so the paint
   * performs zero DOM mutations and the caret is untouched. Only a keystroke
   * that restructures the token stream costs a caret restore, and then the
   * offset is exact because the reconcile is the only thing that moved it.
   *
   * Canonicalization is deliberately NOT run here (the generic host runs it on
   * blur): it exists to tidy inline markup, and a code block has none.
   */
  private wireCode(id: string, host: HTMLElement): void {
    const s = this.store
    // An IME composition lives in nodes the engine owns; re-tokenising
    // mid-composition destroys them and drops the half-typed word. The model
    // keeps up regardless — only the colour waits for compositionend.
    let composing = false
    const sync = (paint: boolean): void => {
      const text = host.textContent ?? ''
      s.runEdit(id, () => { const b = s.block(id); if (b) b.html = escText(text) })
      if (!paint) return
      const at = caretIndexIn(host)
      if (paintCode(host, text, s.block(id)?.lang) && at !== null) caretToOffset(host, at)
    }
    host.addEventListener('compositionstart', () => { composing = true })
    host.addEventListener('compositionend', () => { composing = false; sync(true) })
    host.addEventListener('input', () => { if (!this.painting) sync(!composing) })
    host.addEventListener('blur', () => { if (!this.painting) s.endRun() })
  }

  // ---- tables -------------------------------------------------------------
  //
  // A block editor edits a table differently from a canvas: there is no
  // properties panel to put row and column controls in, and the block IS the
  // table, so the controls ride on the block the way the image tools do. What
  // is copied from slides is the MODEL (fractional weights, rows of cells, a
  // header flag, whole-value LWW under collab); what is not is any of this.

  /** The cell the caret is in — `data-cell` is the block, `data-r`/`data-c` the
   *  seat. Deliberately NOT `data-edit`: that name means "this element's html
   *  IS the block's html", and the generic input handler would then write one
   *  cell over the whole table. */
  private cellAt(node: Node | null): { id: string; r: number; c: number; td: HTMLElement } | null {
    const td = (node instanceof HTMLElement ? node : node?.parentElement)?.closest<HTMLElement>('[data-cell]')
    if (!td) return null
    return { id: td.dataset.cell!, r: Number(td.dataset.r), c: Number(td.dataset.c), td }
  }

  private focusCell(id: string, r: number, c: number): void {
    afterPaint(() => {
      const td = this.main.querySelector<HTMLElement>(
        `[data-cell="${CSS.escape(id)}"][data-r="${r}"][data-c="${c}"]`)
      if (!td) return
      td.focus()
      caretToEnd(td)
    })
  }

  /**
   * Change a table's shape, then put the caret back where the change means it
   * should be.
   *
   * Every table write goes through here and through model.writeTable, so the
   * derived `html` fallback — the thing a build that predates tables shows —
   * can never drift from the cells. It is a `commit`, so it is one undo step.
   */
  private editTable(id: string, fn: (t: TableShape) => { r: number; c: number } | void): void {
    const s = this.store
    const b = s.block(id)
    if (!b || s.readOnly || this.reading) return
    let seat: { r: number; c: number } | undefined
    const shape = tableOf(b)
    s.commit(() => { seat = fn(shape) || undefined; writeTable(b, shape) })
    this.paintPage()
    // where the change means the caret should be, or where it already was —
    // clamped, because the row it was in may be the row that just went
    const here = this.cell?.id === id ? this.cell : null
    const to = seat ?? here
    if (!to) return
    const t = tableOf(b)
    this.focusCell(id, Math.min(to.r, t.h - 1), Math.min(to.c, t.w - 1))
  }

  /** The last cell the caret was in, so a toolbar button knows which row and
   *  column it means. A toolbar click blurs the cell, so this cannot be read
   *  from the Selection at the moment the button fires. */
  private cell: { id: string; r: number; c: number } | null = null

  /** A fresh row or column of the right width. */
  private static blank(n: number): string[] { return Array<string>(n).fill('') }

  addTableRow(id: string, at?: number): void {
    this.editTable(id, (t) => {
      if (t.h >= TABLE_MAX_ROWS) return
      const r = at === undefined ? t.h : at + 1
      t.rows.splice(r, 0, Editor.blank(t.w))
      return { r, c: 0 }
    })
  }

  addTableCol(id: string, at?: number): void {
    this.editTable(id, (t) => {
      if (t.w >= TABLE_MAX_COLS) return
      const c = at === undefined ? t.w : at + 1
      for (const row of t.rows) row.splice(c, 0, '')
      t.cols.splice(c, 0, t.cols[Math.min(c, t.cols.length - 1)] ?? 1)
      t.colAlign.splice(c, 0, '')
      return { r: 0, c }
    })
  }

  /** A table always keeps one row and one column: a table with none is not an
   *  empty table, it is a block with nothing to click on and no way back. */
  removeTableRow(id: string, at: number): void {
    this.editTable(id, (t) => {
      if (t.h <= 1) return
      t.rows.splice(Math.min(at, t.h - 1), 1)
      return { r: Math.max(0, Math.min(at, t.rows.length - 1)), c: 0 }
    })
  }

  removeTableCol(id: string, at: number): void {
    this.editTable(id, (t) => {
      if (t.w <= 1) return
      const c = Math.min(at, t.w - 1)
      for (const row of t.rows) row.splice(c, 1)
      t.cols.splice(c, 1)
      t.colAlign.splice(c, 1)
      return { r: 0, c: Math.max(0, c - 1) }
    })
  }

  /**
   * Attach a table's editing behaviour: the cells, the tools, the grips.
   *
   * Called only when the document is editable — the renderer already emits
   * inert `<td>`s in the reading view and in print, so wiring them anyway would
   * contradict it, which is the exact mistake the callout chip made once.
   */
  private wireTables(view: HTMLElement): void {
    const s = this.store

    for (const td of view.querySelectorAll<HTMLElement>('[data-cell]')) {
      const id = td.dataset.cell!
      const r = Number(td.dataset.r), c = Number(td.dataset.c)
      td.addEventListener('focus', () => { this.cell = { id, r, c } })
      td.addEventListener('input', () => {
        if (this.painting) return
        // ONE RUN PER CELL, not per block: the run key carries the seat, so
        // moving to the next cell closes the run and Tab-typing across a row is
        // five undo steps rather than one that swallows the whole row.
        s.runEdit(`${id}:${r}:${c}`, () => {
          const b = s.block(id)
          if (!b) return
          const t = tableOf(b)
          if (!t.rows[r]) return
          t.rows[r][c] = readInline(td)
          writeTable(b, t)
        })
      })
      td.addEventListener('blur', () => {
        if (this.painting) return
        s.endRun()
        const b = s.block(id)
        if (!b) return
        const t = tableOf(b)
        const clean = canonicalize(t.rows[r]?.[c] ?? '')
        if (clean === t.rows[r]?.[c]) return
        t.rows[r][c] = clean
        writeTable(b, t)
        td.innerHTML = clean
        redecorateTags(td)
      })
    }

    for (const node of view.querySelectorAll<HTMLElement>('.sp-b-table')) {
      const id = node.dataset.blockId!
      const b = s.block(id)
      if (!b) continue
      const shape = tableOf(b)
      const tools = el('div', 'sp-tb-tools')
      const btn = (label: string, title: string, run: () => void, on = false) => {
        const x = document.createElement('button')
        x.type = 'button'
        x.className = 'sp-btn' + (on ? ' sp-on' : '')
        x.textContent = label
        x.title = title
        x.setAttribute('aria-label', title)
        // mousedown, not click: a click would first blur the cell, and `this.cell`
        // is read to decide WHICH row the button means. Blur still runs (the
        // cell's own handler closes its typing run) — it just runs after the
        // seat has been used.
        x.addEventListener('mousedown', (e) => { e.preventDefault(); run() })
        return x
      }
      const seat = () => (this.cell?.id === id ? this.cell : null)
      tools.append(
        btn('+', t('Add a row below'), () => this.addTableRow(id, seat()?.r)),
        btn('+|', t('Add a column after'), () => this.addTableCol(id, seat()?.c)),
        btn('-', t('Remove this row'), () => this.removeTableRow(id, seat()?.r ?? shape.h - 1)),
        btn('-|', t('Remove this column'), () => this.removeTableCol(id, seat()?.c ?? shape.w - 1)),
        btn('H', t('Header row'), () => this.editTable(id, (x) => { x.header = !x.header }), shape.header),
      )
      node.append(tools)

      // COLUMN GRIPS on the first row's cells, all but the last: a boundary
      // moves two columns, and there is no boundary after the last one.
      // COLUMN GRIPS. They live in the WRAPPER, absolutely positioned over each
      // boundary — NOT inside the first row's cells, which is where they went
      // first and which was wrong in two ways at once, both measured in the
      // browser: the cell's `innerHTML` is the model, so every grip was written
      // into the document as the cell's content; and `caretToEnd` put the caret
      // INSIDE the trailing <button>, so the first word typed into a column
      // landed in the button and was then eaten by the sanitizer on blur (a
      // <button> is not on the inline allowlist, so it goes with its text).
      // Editor chrome never belongs inside an editable host. The image tools and
      // the language chip sit outside theirs for the same reason.
      const wrap = node.querySelector<HTMLElement>('.sp-tb-wrap')
      const table = node.querySelector<HTMLElement>('.sp-tb')
      if (!wrap || !table || shape.w < 2) continue
      const grips: HTMLElement[] = []
      // `offsetLeft` is measured against the WRAP (the nearest positioned
      // ancestor), which is also what the grips are positioned in — so the two
      // agree inside the horizontal scroller as well, and scroll together.
      const place = () => {
        const row = [...node.querySelectorAll<HTMLElement>('[data-cell][data-r="0"]')]
        grips.forEach((g, c) => {
          const td = row[c]
          if (!td) return
          // physical `left`, to match the physical `offsetLeft` it comes from
          g.style.left = `${td.offsetLeft + td.offsetWidth - 3}px`
          g.style.height = `${table.offsetHeight}px`
        })
      }
      for (let c = 0; c < shape.w - 1; c++) {
        const grip = document.createElement('button')
        grip.type = 'button'
        grip.className = 'sp-tb-grip'
        grip.tabIndex = -1
        grip.setAttribute('aria-label', t('Drag to resize this column'))
        grip.addEventListener('mousedown', (down) => this.startColResize(down, id, c, node, place))
        grips.push(grip)
        wrap.append(grip)
      }
      place()
      // the column boundaries move when the window does, and a grip that is no
      // longer over its boundary is worse than no grip
      new ResizeObserver(place).observe(table)
    }
  }

  /**
   * Drag a column boundary.
   *
   * The DOM is updated live and the model ONLY on release — a commit per
   * mousemove would be sixty undo steps for one drag, and repainting the page
   * under the cursor would drop the pointer capture on the first frame.
   *
   * Two adjacent weights are traded so the total is unchanged: `cols` are
   * fractions of the table's own width (model.ts), so a drag can never make a
   * table that does not add up.
   */
  private startColResize(down: MouseEvent, id: string, c: number, node: HTMLElement, place: () => void): void {
    down.preventDefault()
    const table = node.querySelector<HTMLElement>('.sp-tb')
    const b = this.store.block(id)
    if (!table || !b) return
    const shape = tableOf(b)
    const cols = [...table.querySelectorAll<HTMLElement>('col')]
    const width = table.getBoundingClientRect().width || 1
    const total = shape.cols.reduce((s, n) => s + n, 0) || shape.w
    const startX = down.clientX
    const a0 = shape.cols[c], b0 = shape.cols[c + 1]
    // a column never shrinks past a width you could still grab
    const min = (total * 40) / width
    document.body.classList.add('sp-col-resizing')

    const move = (m: MouseEvent) => {
      const d = ((m.clientX - startX) / width) * total
      const a = Math.max(min, Math.min(a0 + b0 - min, a0 + d))
      shape.cols[c] = a
      shape.cols[c + 1] = a0 + b0 - a
      for (let i = 0; i < cols.length; i++) {
        cols[i].style.width = `${((shape.cols[i] / total) * 100).toFixed(3)}%`
      }
      // the grips follow the boundaries they ARE; the table's own size does not
      // change during a column drag, so the ResizeObserver never fires for this
      place()
    }
    const up = () => {
      window.removeEventListener('mousemove', move)
      window.removeEventListener('mouseup', up)
      document.body.classList.remove('sp-col-resizing')
      this.store.commit(() => { writeTable(b, shape) }, { structure: false })
    }
    window.addEventListener('mousemove', move)
    window.addEventListener('mouseup', up)
  }

  /**
   * The keymap INSIDE a cell. Returns true when it handled the key.
   *
   * Tab and Enter walk the grid, and Tab off the last cell appends a row —
   * exactly what slides' canvas table does, because it is what every table in
   * every application does and muscle memory is not a thing to be clever with.
   * Shift+Enter is the line break, since plain Enter is spent on navigation.
   */
  private tableKey(e: KeyboardEvent, at: { id: string; r: number; c: number }): boolean {
    const b = this.store.block(at.id)
    if (!b) return false
    const t = tableOf(b)
    const go = (r: number, c: number) => { e.preventDefault(); this.focusCell(at.id, r, c) }

    if (e.key === 'Tab') {
      const next = at.c + (e.shiftKey ? -1 : 1)
      if (next >= 0 && next < t.w) { go(at.r, next); return true }
      if (e.shiftKey) {
        if (at.r === 0) { e.preventDefault(); return true }
        go(at.r - 1, t.w - 1)
        return true
      }
      if (at.r + 1 < t.h) { go(at.r + 1, 0); return true }
      // off the end: a new row, which is how a table is filled in
      e.preventDefault()
      this.addTableRow(at.id)
      return true
    }
    if (e.key === 'Enter') {
      if (e.shiftKey) {
        // the browser inserts a <div> or a <p> into a td left to itself, and
        // block structure is never markup here — insertLineBreak is a <br>
        e.preventDefault()
        document.execCommand('insertLineBreak')
        return true
      }
      if (at.r + 1 < t.h) { go(at.r + 1, at.c); return true }
      e.preventDefault()
      this.addTableRow(at.id)
      return true
    }
    if (e.key === 'Escape') {
      e.preventDefault()
      ;(document.activeElement as HTMLElement | null)?.blur()
      return true
    }
    return false
  }

  /** Choose what a code block is highlighted as. */
  private openLangPicker(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    if (s.readOnly || this.reading) return
    // An UNKNOWN tag matches NO row. `rust` renders plain, but it is not the
    // same thing as plain: ticking "Plain text" for it would say the tag is
    // already gone, and the next click would quietly delete it.
    const raw = String(s.block(blockId)?.lang ?? '').trim()
    const cur = normLang(raw)
    const unknown = !!raw && !cur
    this.menuAt(anchor, t('Language'), (m) => {
      for (const { id, label } of CODE_LANGS) {
        row(m, { label: label || t('Plain text'), selected: !unknown && id === cur, run: () => {
          s.commit(() => {
            const blk = s.block(blockId)
            if (!blk) return
            if (id) blk.lang = id
            else delete blk.lang
          })
          this.paintPage()
        } })
      }
    })
  }

  private collab: import('./collabui.ts').CollabUi | null = null
  /** the live session, once main.ts has handed it over (connectSync) */
  private session: import('./sync/session.ts').SyncSession | null = null
  private liveSlot!: HTMLElement
  private barFit: TopbarFit | null = null
  private treeTimer: ReturnType<typeof setTimeout> | undefined
  private paintTreeSoon(): void {
    clearTimeout(this.treeTimer)
    this.treeTimer = setTimeout(() => this.paintTree(), 250)
  }

  /** What links here — derived, never stored. */
  private backlinks(pageId: string): HTMLElement {
    const s = this.store
    const refs = s.index.backlinks.get(pageId) ?? []
    const box = el('section', 'sp-backlinks')
    if (!refs.length) return box
    box.append(el('h2', 'sp-backlinks-h', t('Linked from')))
    const seen = new Set<string>()
    const ul = el('ul', 'sp-backlink-list')
    for (const r of refs) {
      if (seen.has(r.pageId)) continue
      seen.add(r.pageId)
      const from = s.index.page.get(r.pageId)
      if (!from) continue
      const li = document.createElement('li')
      const a = document.createElement('a')
      a.href = `#p/${from.id}`
      a.textContent = from.title || t('Untitled')
      a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(from.id) })
      const snippet = textOf(s.index.block.get(r.blockId)?.block.html).slice(0, 120)
      li.append(a)
      if (snippet) li.append(el('span', 'sp-snippet', snippet))
      ul.append(li)
    }
    box.append(ul)
    return box
  }

  /**
   * WHAT COULD LINK HERE — this page's names, found as plain words elsewhere.
   *
   * Derived at paint like the backlinks above it, never stored: a count
   * written into the file goes stale in somebody else's copy the moment they
   * type. `mentionsOf` makes ONE pass over the document for THIS page's names,
   * so the cost does not grow with the number of pages — see mentions.ts.
   *
   * A reader with nothing to link gets nothing at all: an empty "Unlinked
   * mentions (0)" heading on every page is chrome that only ever says no.
   */
  private unlinked(pageId: string): HTMLElement {
    const s = this.store
    const box = el('section', 'sp-mentions')
    let found: Mention[]
    // A malformed page (a title that is somehow not a string, an `aliases`
    // shape nobody anticipated) must cost the reader a panel, never the page.
    try { found = mentionsOf(s.doc, s.index, pageId) } catch { return box }
    if (!found.length) return box

    box.append(el('h2', 'sp-backlinks-h', t('Unlinked mentions')))
    const ul = el('ul', 'sp-backlink-list')
    for (const m of found) {
      const from = s.index.page.get(m.fromPage)
      if (!from) continue
      const li = document.createElement('li')
      const a = document.createElement('a')
      a.href = `#p/${from.id}`
      a.textContent = from.title || t('Untitled')
      a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(from.id) })
      li.append(a, el('span', 'sp-snippet', m.snippet))
      // The whole point of the panel: one click turns the words into the link
      // somebody meant to make. Hidden in a locked/reader copy, where the
      // mentions are still worth SEEING and the button would only fail.
      if (!(this.store.readOnly || this.reading)) {
        const btn = document.createElement('button')
        btn.className = 'sp-btn sp-mention-link'
        btn.type = 'button'
        btn.textContent = t('Link')
        btn.title = t('Turn these words into a link to this page')
        btn.addEventListener('click', () => this.linkMentionNow(m, pageId))
        li.append(btn)
      }
      ul.append(li)
    }
    box.append(ul)
    return box
  }

  /**
   * Turn one unlinked mention into a real link.
   *
   * The offsets were computed when the panel was painted, and the document may
   * have moved since — a collaborator's op, an undo, an edit in another tab.
   * `linkMention` returns null rather than splicing into a stale offset, and
   * this repaints instead of writing, which re-derives the mention from the
   * text as it now is. Silently writing the wrong span would corrupt a block.
   */
  private linkMentionNow(m: Mention, targetId: string): void {
    const s = this.store
    if (s.readOnly) return
    const found = s.index.block.get(m.fromBlock)
    const next = found ? linkMention(String(found.block.html ?? ''), m, targetId) : null
    if (next === null) {
      this.status(t('That text has changed — nothing was linked'))
      this.paintPage()
      return
    }
    s.commit(() => { const b = s.block(m.fromBlock); if (b) b.html = sanitizeInline(next) })
    this.paintPage()
  }

  // ---- editing ------------------------------------------------------------
  private blockAt(node: Node | null): { id: string; host: HTMLElement } | null {
    const host = (node instanceof HTMLElement ? node : node?.parentElement)?.closest<HTMLElement>('[data-edit]')
    return host ? { id: host.dataset.edit!, host } : null
  }

  private focused(): { id: string; host: HTMLElement } | null {
    return this.blockAt(document.activeElement)
  }

  /**
   * Markdown prefixes convert the block as they are typed.
   *
   * THE TRAILING SPACE IS NOT A SPACE. A space typed at the end of a
   * contenteditable line is inserted by the engine as U+00A0, so that it does
   * not collapse — measured in Chrome on the built shell: after typing "## ",
   * `host.textContent` is `['#','#',160]` and `/^## $/` does not match it.
   * Every space-completed trigger in the table above was therefore dead, which
   * is most of them. Normalising here (never in the model — the block's html is
   * cleared by the conversion anyway) fixes all of them at once.
   */
  private autoformat(id: string, host: HTMLElement): void {
    // A trailing space typed at the end of a contentEditable line is inserted
    // by the browser as U+00A0, not U+0020 — otherwise it would collapse and
    // the caret would appear not to move. So `/^## $/` never matched anything a
    // person typed, and every markdown trigger in this app was dead from the
    // first release: measured in the built shell, `# `, `## `, `- `, `1. `,
    // `> ` and `[] ` all arrived as [.., 160] and converted nothing.
    //
    // It survived a test because the test assigned `host.textContent` directly
    // — with a real space, which is a path no keystroke takes. Drive
    // autoformat with execCommand('insertText'), or it proves nothing.
    //
    // Normalised for the TEST only. The model keeps whatever the browser put
    // there; rewriting the author's text to make a pattern match would be a
    // cure worse than the disease.
    const text = (host.textContent ?? '').replace(/\u00a0/g, ' ')
    for (const [re, type, extra] of AUTOFORMAT) {
      // the MATCH, not just a test: a trigger may name a value, as
      // `[!warning] ` names the tone the callout is about to have
      const m = re.exec(text)
      if (!m) continue
      const s = this.store
      const b = s.block(id)
      // `b.type === type` alone would stop `[!caution] ` from re-toning a
      // callout that is already a callout
      if (!b) return
      if (b.type === type && m.length < 2) return
      s.commit(() => { b.type = type; b.html = ''; extra(b, m) })
      this.paintPage()
      this.focusBlock(id)
      return
    }
  }

  private focusBlock(id: string, atEnd = true): void {
    afterPaint(() => {
      const host = this.main.querySelector<HTMLElement>(`[data-edit="${CSS.escape(id)}"]`)
      if (!host) return
      host.focus()
      if (atEnd) caretToEnd(host)
    })
  }

  private onKey(e: KeyboardEvent): void {
    const s = this.store
    const mod = (e as any)[CTRL] as boolean

    // A MODAL OWNS THE KEYBOARD — all of it, shortcuts included. The shortcut
    // branch below used to run BEFORE the overlay test, and About, the key
    // sheet and every dialog built in about.ts never set `this.overlay` at
    // all: measured with About open, `[` collapsed the page list behind the
    // scrim (and saved that to the reader's preferences), `?` stacked the
    // shortcut sheet on top of About, and ⌘Z would have undone the page
    // underneath. The dialog's own handler still runs; this one stands down.
    if (document.querySelector('[aria-modal="true"]')) return

    // ⌘K IS TWO COMMANDS, decided by whether anything is selected — the same
    // split Notion and Confluence make, and the reason it is not a second
    // shortcut: on a selection it is "link these words", and with nothing
    // selected there is nothing to link, so it stays the quick-open it has
    // always been. `link()` answers false when the selection is not markable,
    // and the search opens as before.
    if (mod && e.key.toLowerCase() === 'k' && !e.shiftKey) {
      e.preventDefault()
      if (!this.format?.link()) this.openSearch()
      return
    }
    // `!e.shiftKey`: ⇧⌘S is strikethrough, and this branch had no shift test,
    // so without it the save dialog opened every time someone struck text out.
    if (mod && e.key.toLowerCase() === 's' && !e.shiftKey) { e.preventDefault(); this.onSave?.(); return }
    if (mod && e.key.toLowerCase() === 'p') { e.preventDefault(); this.openPrint(); return }
    // ⌘/ — the block menu, and THE ONLY KEYBOARD ROUTE TO IT. The menu hangs
    // off the gutter grip, the gutter is hover-revealed, and Tab inside a
    // block is indent — so without this key the block format row, and with it
    // every list, heading and indent control, is reachable by pointer only.
    if (mod && e.key === '/') {
      const at = this.focused() ?? this.cellAt(document.activeElement)
      const grip = at
        ? this.main.querySelector<HTMLElement>(
          `[data-block-id="${CSS.escape(at.id)}"] > .sp-gutter > .sp-ghost[draggable]`)
        : null
      if (at) { e.preventDefault(); this.openBlockMenu(at.id, grip ?? this.main) }
      return
    }
    if (mod && e.key.toLowerCase() === 'f') { e.preventDefault(); this.openFind(); return }
    if (mod && e.altKey && e.key.toLowerCase() === 'n') { e.preventDefault(); this.newPage(); return }
    if (mod && e.shiftKey && e.key.toLowerCase() === 'j') { e.preventDefault(); this.openJournal(); return }
    // `[` collapses the page list, `]` opens the properties panel — the pair
    // slides uses. BOTH ask the same question first.
    //
    // `[` did not, and the comment beside it claimed it did not need to
    // because "the text path returns above". The text path is ~90 lines BELOW
    // it, so every bare `[` was caught here, preventDefault()ed, and turned
    // into a sidebar toggle: `[[`, the way this app makes links and the thing
    // the starter space tells you to type, could not be typed at all. Shipped
    // since #237.
    //
    // ONE guard for both, not two. The panel work arrived with its own
    // `isTyping()` while this was being fixed with an `editingText()` — same
    // question, two names, and a second copy is how the two answers start to
    // differ. `isTyping` is the survivor because it also covers SELECT, which
    // takes a keystroke as readily as an input does.
    if (!mod && e.key === '[' && !isTyping()) { e.preventDefault(); this.togglePane(); return }
    if (!mod && e.key === ']' && !isTyping()) { e.preventDefault(); this.toggleInsp(); return }
    // Same guard as [ and ]: '?' is a character somebody is entitled to type.
    if (!mod && e.key === '?' && !isTyping()) { e.preventDefault(); this.openHelp(); return }
    if (mod && e.shiftKey && e.key.toLowerCase() === 'i') { e.preventDefault(); this.newIssue(); return }
    if (mod && e.key.toLowerCase() === 'z') {
      e.preventDefault()
      if (e.shiftKey) s.redo(); else s.undo()
      this.paintPage(); this.paintTree()
      return
    }
    if (e.key === 'Escape' && this.reading && !this.sealed && !this.overlay && !document.querySelector('.bkm-open')) { e.preventDefault(); this.toggleReading(false); return }
    if (this.overlay) return // the overlay owns the keyboard while it is open

    // A TABLE CELL IS NOT A BLOCK HOST, so the block keymap below does not
    // apply to it — the same ruling a code block gets, one level earlier.
    // ⏎ walks the grid rather than splitting a block, ⇥ walks it rather than
    // re-parenting, and neither has any meaning for a cell. This must come
    // before `focused()`, which looks for `[data-edit]` and finds nothing in a
    // cell — so without it every key here fell through to the browser, and ⏎
    // inserted a `<div>` into the cell's html.
    const inCell = this.cellAt(document.activeElement)
    if (inCell && !s.readOnly && !this.reading) {
      if (this.tableKey(e, inCell)) return
    }

    // ARROWS COME AFTER `tableKey` AND BEFORE `focused()`. After, because the
    // table owns ⏎ and ⇥ inside a cell and must get first refusal on every
    // key; before, because `focused()` looks for `[data-edit]` and a cell is
    // deliberately not one — so caret navigation would never run in a table at
    // all if it sat below. It handles the cell case itself.
    if (ARROWS.has(e.key)) {
      if (this.caretNav(e, inCell)) return
    } else if (!mod) {
      this.goalX = null
    }

    const cur = this.focused()
    if (!cur) return
    const b = s.block(cur.id)
    if (!b) return

    // native undo must never diverge from the store's history
    if (mod && (e.key.toLowerCase() === 'y')) { e.preventDefault(); s.redo(); this.paintPage(); return }

    // A CODE BLOCK IS TEXT, so the block-editor keymap does not apply to it.
    // Enter is a newline (not a block split), Tab is an indent (not a
    // re-parent — indenting the block in the page tree is never what someone
    // pressing Tab inside source code meant), and /, [[ and ⌘B are off.
    //
    // Enter is handled EXPLICITLY rather than left to the engine: what the
    // browser inserts into a contenteditable varies (a `\n`, a `<br>`, a
    // wrapping `<div>`), and only the first survives reading the host's
    // textContent, which is now how the model is written. execCommand keeps
    // the caret and fires the `input` event that repaints the colour.
    if (b.type === 'code') {
      // Shift is not a modifier here: there is no "soft break" in source code,
      // so both Enters are the same newline.
      if (e.key === 'Enter') { e.preventDefault(); insertText('\n'); return }
      if (e.key === 'Tab') { e.preventDefault(); if (!e.shiftKey) insertText('  '); return }
      if (e.key === '/' || e.key === '[') return
      if (markKey(e, mod)) { e.preventDefault(); return }
    }

    if (e.key === 'Enter' && !e.shiftKey && b.type !== 'code') {
      e.preventDefault()
      this.splitBlock(cur.id, cur.host)
      return
    }
    if (e.key === 'Backspace' && atStart(cur.host)) {
      const empty = !(cur.host.textContent ?? '').trim()
      if (b.type !== 'p' && empty) { e.preventDefault(); this.setType(cur.id, 'p'); return }
      // …and the way OUT of a container is the same key that got you in.
      // Without this, ⏎ puts a line inside a callout and backspace merges it
      // into the callout's own text, so the only exit is Shift-Tab — which
      // nobody finds. Empty line + backspace = out, as in every outliner.
      if (empty && b.parent && SPEC.get(s.block(b.parent)?.type ?? '')?.container === 'always') {
        e.preventDefault()
        this.indent(cur.id, false)
        return
      }
      e.preventDefault()
      this.mergeBack(cur.id)
      return
    }
    if (e.key === 'Tab') {
      e.preventDefault()
      // A GHOST ANSWER CLAIMS TAB, and only while it is showing. Committing is
      // then the keystroke your hand is already on, and ignoring it costs
      // nothing — you carry on typing and it goes away. Shift+Tab still
      // outdents, so the one gesture people use constantly is never stolen.
      if (!e.shiftKey && this.ghostFor === cur.id && this.commitAnswer(cur.id)) return
      this.indent(cur.id, !e.shiftKey)
      return
    }
    if (e.key === '/' && !(cur.host.textContent ?? '').trim()) {
      // a slash on an empty block opens the block menu
      setTimeout(() => this.openSlash(cur.id), 0)
      return
    }
    if (e.key === '[' && cur.host.textContent?.endsWith('[')) {
      setTimeout(() => this.openPagePicker(cur.id, cur.host), 0)
      return
    }
    const mark = markKey(e, mod)
    if (mark) {
      // ALWAYS preventDefault, even with nothing selected. ⌘B is a browser
      // command too, and letting it through would put contentEditable's own
      // `<b>` into the block — the exact non-canonical markup, from the exact
      // engine, that §2.4(b) forbids and that this replaced.
      e.preventDefault()
      this.format?.toggle(mark)
      return
    }
  }

  private splitBlock(id: string, host: HTMLElement): void {
    const s = this.store
    const b = s.block(id)
    if (!b) return
    const [before, after] = splitAtCaret(host)
    const heading = b.type === 'h1' || b.type === 'h2' || b.type === 'h3'
    // ⏎ INSIDE AN ALWAYS-OPEN CONTAINER GOES IN, not after.
    //
    // A callout's second line belongs in the callout; making a second empty
    // callout instead is what everyone who has used one expects not to happen,
    // and it is also the only thing that makes nesting discoverable without
    // knowing that Tab does it. Deliberately NOT extended to `toggle`: a fold
    // can be shut, and putting the caret inside a shut fold loses the line.
    const into = SPEC.get(b.type)?.container === 'always'
    const fresh = newBlock(heading || into ? 'p' : b.type, { html: after })
    SPEC.get(fresh.type)?.init?.(fresh)
    if (into) fresh.parent = b.id
    else if (b.parent) fresh.parent = b.parent
    if (s.page) placeNewCard(s.page, fresh)
    s.commit(() => {
      b.html = before
      const page = s.page!
      page.blocks.splice(page.blocks.indexOf(b) + 1, 0, fresh)
    })
    this.paintPage()
    this.focusBlock(fresh.id, false)
  }

  private mergeBack(id: string): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const i = page.blocks.findIndex((x) => x.id === id)
    if (i <= 0) return
    const prev = page.blocks[i - 1]
    const b = page.blocks[i]
    if (prev.type === 'divider') { s.commit(() => { page.blocks.splice(i - 1, 1) }); this.paintPage(); this.focusBlock(id); return }
    const at = (prev.html ?? '').length
    s.commit(() => {
      prev.html = (prev.html ?? '') + (b.html ?? '')
      // a merged-away parent would orphan its children — re-home them
      for (const child of page.blocks) if (child.parent === b.id) child.parent = prev.id
      page.blocks.splice(i, 1)
    })
    this.paintPage()
    afterPaint(() => {
      const host = this.main.querySelector<HTMLElement>(`[data-edit="${CSS.escape(prev.id)}"]`)
      if (host) { host.focus(); caretToOffset(host, at) }
    })
  }

  /**
   * ↑ ↓ ← → across blocks. True when it handled the key.
   *
   * The rules, in the order they are asked:
   *
   *  - A held Shift or ⌥ is a SELECTION or a word jump; both are the browser's
   *    and neither should jump a block. A non-collapsed selection likewise.
   *  - ← and → only do anything at the very edge of the seat; everywhere else
   *    the browser is already right.
   *  - ↑ and ↓ only do anything on the seat's edge VISUAL LINE, which is why
   *    caret.ts measures boxes rather than counting characters: a wrapped
   *    paragraph is several lines and the first ↓ in it means the second line.
   *  - The goal column is remembered across consecutive vertical steps, so
   *    down-through-a-short-line-and-out comes back near the original x.
   */
  private caretNav(e: KeyboardEvent, inCell: ReturnType<Editor['cellAt']>): boolean {
    if (e.shiftKey || e.altKey || (e as any)[CTRL]) { this.goalX = null; return false }
    const active = document.activeElement as HTMLElement | null
    const host = active?.closest<HTMLElement>(SEAT_SEL) ?? null
    if (!host || !this.main.contains(host)) return false
    const sel = getSelection()
    if (!sel || !sel.rangeCount || !sel.isCollapsed) { this.goalX = null; return false }

    const seats = seatsIn(this.main)
    const i = seats.indexOf(host)
    if (i < 0) return false
    const dir: -1 | 1 = e.key === 'ArrowUp' || e.key === 'ArrowLeft' ? -1 : 1
    const vertical = e.key === 'ArrowUp' || e.key === 'ArrowDown'

    if (!vertical) {
      this.goalX = null
      // at the edge, ← leaves for the END of the seat before and → for the
      // START of the seat after — which is exactly what the caret would have
      // done had the page been one editable rather than many
      if (dir < 0 ? !atStart(host) : !atEndOf(host)) return false
      const j = stepSeat(seats.length, i, dir)
      if (j < 0) return false
      e.preventDefault()
      const next = seats[j]
      next.focus()
      if (dir < 0) caretToEndOf(next); else caretToStart(next)
      return true
    }

    const caret = caretBox(host)
    if (!caret) return false
    if (!onEdgeLine(caret, lineBoxes(host), dir)) { this.goalX = null; return false }
    const x = this.goalX ?? caret.left

    // INSIDE A TABLE the grid is the truth, not document order: cells are
    // row-major in the DOM, so the seat before (1,2) is (1,1) and stepping to
    // it would walk sideways along the row the reader was trying to leave.
    if (inCell) {
      const b = this.store.block(inCell.id)
      const shape = b ? tableOf(b) : null
      const to = shape ? tableStep(inCell, shape, dir) : null
      if (to) {
        e.preventDefault()
        this.goalX = x
        const td = this.main.querySelector<HTMLElement>(
          `[data-cell="${CSS.escape(inCell.id)}"][data-r="${to.r}"][data-c="${to.c}"]`)
        if (td) { placeCaretAtX(td, x, dir < 0 ? 'last' : 'first'); return true }
      }
      // off the top or the bottom of the grid: out of the table altogether,
      // past every one of its other cells
      const out = this.outOfTable(seats, i, dir, inCell.id)
      if (out < 0) return false
      e.preventDefault()
      this.goalX = x
      placeCaretAtX(seats[out], x, dir < 0 ? 'last' : 'first')
      return true
    }

    let j = stepSeat(seats.length, i, dir)
    if (j < 0) return false
    // ENTERING a table from outside lands on whichever cell of the entry row
    // the goal column is over, not on the first one in the DOM
    const cellId = seats[j].dataset.cell
    if (cellId !== undefined) {
      const row = seats.filter((sea) => sea.dataset.cell === cellId
        && sea.dataset.r === seats[j].dataset.r)
      const pick = nearestByX(row.map((sea) => sea.getBoundingClientRect()), x)
      if (pick >= 0) j = seats.indexOf(row[pick])
    }
    e.preventDefault()
    this.goalX = x
    placeCaretAtX(seats[j], x, dir < 0 ? 'last' : 'first')
    return true
  }

  /** The first seat after (dir 1) or before (dir -1) every cell of one table. */
  private outOfTable(seats: HTMLElement[], from: number, dir: -1 | 1, tableId: string): number {
    for (let j = from + dir; j >= 0 && j < seats.length; j += dir) {
      if (seats[j].dataset.cell !== tableId) return j
    }
    return -1
  }

  /**
   * Tab sets `parent` to the previous sibling — one field write.
   *
   * AND WHEN THERE IS NO PREVIOUS SIBLING IT SAYS SO. This loop used to fall
   * off its own end and return, so Tab on the first item of a list — the most
   * common list gesture there is — did nothing, showed nothing and explained
   * nothing. nesting.ts holds the argument for refusing rather than inventing
   * an indent level; what belongs here is that a refusal has to be VISIBLE, in
   * the status line the app already has (a second transient-message mechanism
   * in one app is one too many — collabui.ts) and as a nudge on the block, so
   * the answer arrives where the reader is looking.
   */
  private indent(id: string, deeper: boolean): void {
    const s = this.store
    const page = s.page
    if (!page) return
    const i = page.blocks.findIndex((x) => x.id === id)
    const b = page.blocks[i]
    if (!b) return
    if (deeper) {
      const aim = indentTarget(page.blocks, id)
      if (!aim.ok) {
        if (aim.why === 'first') {
          this.status(t('A block nests under the one above it — this one has nothing above it'))
          this.nudge(id)
        }
        return
      }
    } else if (!canOutdent(effectiveParents(page), id)) {
      this.status(t('This block is not nested'))
      this.nudge(id)
      return
    }
    s.commit(() => {
      if (!deeper) {
        // by the EFFECTIVE parent (model.ts), not by whatever `parent` names:
        // on a merged document `parent` can point at a block that is absent or
        // that sits LATER, and outdenting through it would move this block
        // under something the renderer never nested it under
        const eff = effectiveParents(page)
        const owner = eff.get(b.id)
        if (!owner) { delete b.parent; return }
        const grand = eff.get(owner)
        if (grand) b.parent = grand
        else delete b.parent
        return
      }
      // the nearest preceding block at the same level becomes the owner
      for (let j = i - 1; j >= 0; j--) {
        if (page.blocks[j].parent === b.parent) { b.parent = page.blocks[j].id; return }
      }
    })
    this.paintPage()
    this.focusBlock(id)
  }

  /**
   * A refused gesture, shown where the reader is looking.
   *
   * The status line carries the WORDS and this carries the pointer: the block
   * you aimed at is the one that twitches, so a message in the topbar is not
   * left to be connected to a keystroke by guesswork. Purely a class the
   * stylesheet animates — nothing here touches the model, so a refusal can
   * never end up in the file or in an undo step.
   */
  private nudge(id: string): void {
    const node = this.main.querySelector<HTMLElement>(`[data-block-id="${CSS.escape(id)}"]`)
    if (!node) return
    node.classList.remove('sp-nudge')
    // reflow between the two writes, or the class never leaves and re-arrives
    void node.offsetWidth
    node.classList.add('sp-nudge')
    setTimeout(() => node.classList.remove('sp-nudge'), 400)
  }

  setType(id: string, type: string, variant?: (b: Block) => void): void {
    this.store.commit(() => {
      const b = this.store.block(id)
      if (!b) return
      b.type = type
      // the registry seeds the type's own fields (blocks.ts `init`), so a new
      // block type does not need a line here as well — this was the fifth place
      // a type had to be added, and the one that was easiest to forget
      SPEC.get(type)?.init?.(b)
      // …and the / row's variant (a view's layout, a clip's kind; inserts.ts)
      variant?.(b)
    })
    this.paintPage()
    // a table's text is in its cells, so there is no block host to put the
    // caret in — the first cell is the equivalent place
    if (type === 'table') this.focusCell(id, 0, 0)
    else this.focusBlock(id)
  }

  // ---- overlays -----------------------------------------------------------
  /**
   * A MODAL, on the kernel's dialog (kernel/src/ui/dialog.ts).
   *
   * The primitive brings what spaces' own overlay lacked, each measured on the
   * built shell before this: a focus TRAP (Tab left the import dialog 23 times
   * in 25), Escape on the document rather than on the backdrop (one click on
   * the card's blank space used to leave a dialog the keyboard could not
   * close), `aria-modal` + `aria-labelledby`, focus returned to the opener, and
   * a scrim above every menu. The title is the dialog's HEADING — 17px/650,
   * the D4 ruling — where each dialog used to open on an 11px uppercase
   * caption; captions are for sections.
   *
   * It is still the editor's one overlay: `this.overlay` gates the keymap, and
   * closeOverlay() takes it down with everything it registered.
   */
  private openOverlay(
    title: string, build: (body: HTMLElement, close: () => void) => void,
    o: { wide?: boolean; top?: boolean; className?: string } = {},
  ): Dialog {
    this.closeOverlay()
    const body = el('div', 'sp-dlg-body' + (o.className ? ' ' + o.className : ''))
    let d: Dialog | null = null
    const close = () => d?.close()
    build(body, close)
    d = createDialog({
      title, content: body,
      onClose: () => { if (d && this.overlay === d.root) this.closeOverlay() },
    })
    d.card.classList.add('sp-dlg')
    if (o.wide) d.card.classList.add('sp-dlg-wide')
    // a palette (search, find a page) sits high and grows downward, so its
    // results do not re-centre the card under the pointer on every keystroke
    if (o.top) d.root.classList.add('sp-dlg-top')
    d.open()
    this.overlay = d.root
    const dd = d
    this.overlayOff.push(() => dd.close())
    return d
  }

  /**
   * The shortcut list.
   *
   * Every shortcut here was read off the keydown handler rather than off the
   * documentation, because a help screen that lists a key the app does not
   * bind is worse than no help screen: it makes the reader doubt the keyboard
   * rather than the page. The starter space describes the same keys in prose,
   * but the starter is a document — the first thing many people do is delete
   * it, and the reference should not go with it.
   * (That is the sheet openHelp() builds, below the graph.)
   */
  /**
   * The space as a picture: pages, and the links between them.
   *
   * The DRAWING lives in graph.ts; the modal around it is the kernel dialog,
   * like every other one here. Teardown rides on `overlayOff`, which
   * closeOverlay() always runs: the graph has observers and an animation frame
   * to give back, and there is no second teardown path to forget about.
   */
  openGraph(): void {
    this.closeOverlay()
    const close = () => this.closeOverlay()
    const view = openGraphView({
      doc: this.store.doc,
      index: this.store.index,
      currentId: this.store.pageId,
      open: (id) => { close(); this.store.goToPage(id); this.repaint() },
      close,
    })
    let d: Dialog | null = null
    d = createDialog({
      label: t('Graph'), content: view.el,
      onClose: () => { if (d && this.overlay === d.root) this.closeOverlay() },
    })
    d.card.classList.add('sp-dlg', 'sp-dlg-graph')
    d.open()
    this.overlay = d.root
    const dd = d
    this.overlayOff.push(() => view.destroy(), () => dd.close())
  }

  openHelp(): void {
    // Every key below is written by keys(), the one place the suite's order
    // (⌃⌥⇧⌘, D8) lives. This sheet was typed by hand and disagreed with
    // itself — ⇧⌘S beside ⌘⇧J — and with the menus.
    const M = (...k: string[]) => keys(...k)
    const groups: Array<[string, Array<[string, string]>]> = [
      [t('Writing'), [
        ['↵', t('A new block')],
        [`Tab / ${M('shift')}Tab`, t('Indent, or move back out')],
        [M('mod', '/'), t('Block options — type, list, indent')],
        ['/', t('The block menu, on an empty line')],
        ['[[', t('Link to another page')],
        [`${M('mod', 'Z')} / ${M('shift', 'mod', 'Z')}`, t('Undo, redo')],
      ]],
      [t('Formatting'), [
        [M('mod', 'B'), t('Bold')],
        [M('mod', 'I'), t('Italic')],
        [M('mod', 'U'), t('Underline')],
        [M('shift', 'mod', 'S'), t('Strikethrough')],
        [M('mod', 'E'), t('Code')],
        [M('shift', 'mod', 'H'), t('Highlight')],
        [M('mod', 'K'), t('Link the selected words')],
      ]],
      [t('Getting around'), [
        ['↑ ↓', t('Between blocks, and between the lines of one')],
        ['← →', t('Off the edge of a block, into the next')],
        [M('mod', 'K'), t('Search all pages, with nothing selected')],
        [M('mod', 'F'), t('Find and replace')],
        [M('alt', 'mod', 'N'), t('New page')],
        [M('shift', 'mod', 'J'), t("Today's journal")],
        [M('shift', 'mod', 'I'), t('New issue')],
      ]],
      [t('The workspace'), [
        ['[', t('Show or hide the page list')],
        [']', t('Show or hide properties')],
        [M('mod', 'S'), t('Save')],
        [M('mod', 'P'), t('Export PDF (print)')],
        ['?', t('This list')],
        ['Esc', t('Leave the reading view')],
      ]],
    ]

    // Two columns where there is room. In one column the four groups run to
    // 23 rows and the last three fall off the bottom of the card — a help
    // screen that hides the help. The grid collapses to one column on a phone,
    // where scrolling a list is what you expect anyway.
    //
    // On the kernel dialog like every other modal: the card no longer takes
    // the focus itself, which painted a 2px ring round the whole sheet on
    // open, and `?` pressed again cannot stack a second copy.
    this.openOverlay(t('Shortcuts & tips'), (card) => {
      const grid = el('div', 'sp-keys-grid')
      for (const [title, rows] of groups) {
        const g = el('section', 'sp-keys-g')
        g.append(el('h3', 'sp-keys-h', title))
        const list = el('dl', 'sp-keys-list')
        for (const [key, what] of rows) {
          const dt = el('dt', '', '')
          dt.append(el('kbd', 'sp-kbd', key))
          list.append(dt, el('dd', '', what))
        }
        g.append(list)
        grid.append(g)
      }
      card.append(grid)
    }, { wide: true, className: 'sp-keys' })
  }

  /**
   * A MENU anchored to something that is not its trigger — a grip, a row's ⋯,
   * a board chip. The kernel's menu (menus.ts anchoredMenu), so it has the
   * primitive's Escape, arrow keys, outside-press and one shared listener pair;
   * a bottom sheet below the drawer breakpoint, where a thumb reaches it.
   *
   * It is the editor's ONE overlay while it is open, exactly as a popover was:
   * `this.overlay` gates the block keymap and the topbar refit.
   */
  private menuAt(
    anchor: HTMLElement | DOMRect, label: string, fill: (m: Menu) => void,
    o: { onClose?: () => void; role?: 'menu' | 'dialog' } = {},
  ): Menu {
    this.closeOverlay()
    const m: Menu = anchoredMenu(anchor, fill, {
      label, sheet: this.isDrawer(), role: o.role,
      onClose: () => {
        if (this.overlay === m.root) { this.overlay = null; this.overlayOff = [] }
        o.onClose?.()
      },
    })
    this.overlay = m.root
    this.overlayOff.push(() => m.close())
    return m
  }

  /**
   * A popover that is NOT a menu — a form, a thread, a picker grid, the /
   * filter. Anchored (or a sheet on a phone), dismissed by Escape or a press
   * outside, and EVERY listener it adds is registered for closeOverlay to take
   * back, however it closes. Before this, nine popovers each hand-rolled a
   * `mousedown` away-listener that only removed itself when it fired.
   */
  private float(
    pop: HTMLElement, anchor: HTMLElement | DOMRect | null,
    o: { sheet?: boolean; role?: string; label?: string; onEscape?: () => void } = {},
  ): void {
    const sheet = o.sheet ?? this.isDrawer()
    pop.classList.toggle('sp-sheet', sheet)
    if (o.role) pop.setAttribute('role', o.role)
    if (o.label) pop.setAttribute('aria-label', o.label)
    document.body.append(pop)
    this.overlay = pop
    if (sheet) {
      pop.classList.add('sp-sheet-in')
    } else if (anchor) {
      // place() answers for the window as it is NOW; keep it true on resize,
      // or a shrinking window clips the popover it sized for a bigger one
      place(pop, anchor)
      const reflow = () => place(pop, anchor)
      addEventListener('resize', reflow)
      this.overlayOff.push(() => removeEventListener('resize', reflow))
    }
    // Capture-phase so it wins over the page's own Escape; stopped here so the
    // editor's keymap does not also act on it.
    const onKey = (e: KeyboardEvent) => {
      if (e.key !== 'Escape' || this.overlay !== pop) return
      e.preventDefault()
      e.stopPropagation()
      this.closeOverlay()
      o.onEscape?.()
    }
    // armed a turn late, so the press that OPENED the popover does not close it
    const away = (ev: Event) => {
      if (this.overlay === pop && !pop.contains(ev.target as Node)) this.closeOverlay()
    }
    const t = setTimeout(() => document.addEventListener('pointerdown', away, true), 0)
    document.addEventListener('keydown', onKey, true)
    this.overlayOff.push(() => {
      clearTimeout(t)
      document.removeEventListener('pointerdown', away, true)
      document.removeEventListener('keydown', onKey, true)
    })
  }

  /**
   * Put a property on this page — and define it, if it does not exist yet.
   *
   * THE SCHEMA IS EDITED WHERE IT IS USED. `doc.fields` has been a per-document
   * vocabulary since the tracker shipped, and nothing has ever written it: the
   * only way to give a page a property was "Make this page an issue", which
   * adds Status, Priority, Assignee and Estimate together or not at all. So the
   * schema was configurable in the format and fixed in the app.
   *
   * A separate schema editor would have been the obvious fix and the wrong one.
   * DEFAULT_FIELDS says it in its own comment — "a tracker you have to design
   * before you can use it is the thing everybody hates about the alternatives"
   * — so a property is created in passing, at the moment somebody wants one,
   * and the vocabulary grows as a side effect of use. That is what lets one
   * space hold a reading list, a film log and a backlog at once: the fields are
   * a flat vocabulary and each page carries only the ones it uses.
   */
  openAddProperty(pageId: string, anchor: HTMLElement): void {
    const s = this.store
    if (s.readOnly) return
    const page = s.index.page.get(pageId)
    if (!page) return

    this.menuAt(anchor, t('Add a property'), (m) => {
      const has = new Set(page.blocks
        .filter((b) => b.type === 'prop')
        .map((b) => String((b as { key?: unknown }).key ?? '')))

      const put = (f: FieldSpec, fields?: FieldSpec[]) => {
        s.commit(() => {
          if (fields) (s.doc as { fields?: FieldSpec[] }).fields = fields
          const p = s.index.page.get(pageId)
          if (!p) return
          p.blocks.splice(headerLength(p), 0, propBlock(f, f.def ?? '', newBlock('prop').id))
        })
        m.close()
        this.repaint()
        this.status(t('Added {name}', { name: f.label }))
      }

      const spare = fieldsOf(s.doc).filter((f) => !has.has(f.key))
      if (spare.length) {
        caption(m, t('Add a property'))
        for (const f of spare) row(m, { icon: ICONS.tag, label: f.label, hint: fieldTypeLabel(f.vt), run: () => put(f) })
      }

      caption(m, t('New property'))
      const form = el('div', 'sp-newprop')
      const name = document.createElement('input')
      name.type = 'text'
      name.className = 'sp-input'
      name.placeholder = t('Name')
      const type = document.createElement('select')
      type.className = 'sp-select'
      for (const vt of FIELD_TYPES) {
        const o = document.createElement('option')
        o.value = vt
        o.textContent = fieldTypeLabel(vt)
        type.append(o)
      }
      type.value = 'text'
      const add = el('button', 'sp-btn sp-primary', t('Add'))
      const submit = () => {
        const label = name.value.trim()
        if (!label) { name.focus(); return }
        const spec: FieldSpec = { key: freeFieldKey(s.doc, label), label, vt: type.value as FieldSpec['vt'] }
        put(spec, withField(s.doc, spec))
      }
      add.addEventListener('click', submit)
      name.addEventListener('keydown', (e) => { if (e.key === 'Enter') { e.preventDefault(); submit() } })
      form.append(name, type, add)
      extra(m, form)
      afterPaint(() => name.focus())
    })
  }

  private closeOverlay(): void {
    const off = this.overlayOff
    this.overlayOff = []
    for (const fn of off) fn()
    this.overlay?.remove()
    this.overlay = null
  }

  /** ⌘K — search every page, including collapsed toggles and archived pages. */
  openSearch(): void {
    const s = this.store
    this.openOverlay(t('Search this space'), (card, close) => {
      const input = document.createElement('input')
      input.className = 'sp-find'
      input.placeholder = t('Search all pages…')
      const results = el('ul', 'sp-results')
      const run = () => {
        const q = input.value.trim().toLowerCase()
        results.innerHTML = ''
        if (!q) return
        // `#` SWITCHES THE QUESTION. Full text already finds `#recipe` — it is
        // literally in the prose — but it finds it the way it finds any other
        // word: a list of pages that happen to contain the string. A leading
        // hash asks the other question, "which tags exist", and answers with
        // the tag and how much of the space carries it.
        if (q.startsWith('#')) { runTags(q.slice(1)); return }
        let n = 0
        for (const p of s.doc.pages) {
          const hits: string[] = []
          if (p.title.toLowerCase().includes(q)) hits.push(p.title)
          // ⌘K FINDS A PAGE BY ITS ALIASES. An alias that reaches the `[[…]]`
          // resolver but not search is worse than no alias: you can link to
          // the page by the name you use for it and then cannot find it by
          // that name, which reads as the search being broken.
          for (const alias of namesOf(p).slice(1)) {
            if (alias.toLowerCase().includes(q)) hits.push(t('also called “{name}”', { name: alias }))
          }
          for (const b of p.blocks) {
            const text = textOf(b.html)
            if (text.toLowerCase().includes(q)) hits.push(text)
            if (hits.length > 2) break
          }
          if (!hits.length) continue
          if (++n > 30) break
          const li = document.createElement('li')
          const a = document.createElement('button')
          a.className = 'sp-result'
          a.innerHTML =
            `<span class="sp-result-ico">${ICONS.page}</span>` +
            `<span class="sp-result-txt"><strong>${escapeHtml(p.title || t('Untitled'))}` +
            (p.archived ? ` <em class="sp-arch">${t('archived')}</em>` : '') + `</strong>` +
            `<span>${escapeHtml(hits.slice(0, 2).join(' · ').slice(0, 140))}</span></span>`
          a.addEventListener('click', () => { close(); s.goToPage(p.id) })
          li.append(a)
          results.append(li)
        }
        if (!results.childElementCount) results.append(el('li', 'sp-noresult', t('Nothing found')))
        at = 0
        mark()
      }
      const runTags = (want: string) => {
        const hits = matchTags(s.tags, want)
        if (!hits.length) {
          results.append(el('li', 'sp-noresult', t('No tags match')))
          return
        }
        for (const e of hits.slice(0, 30)) {
          const li = document.createElement('li')
          const a = document.createElement('button')
          a.className = 'sp-result'
          const n = pagesWithTag(s.doc, s.tags, e.key).length
          a.innerHTML =
            `<span class="sp-result-ico">${ICONS.tag}</span>` +
            `<span class="sp-result-txt"><strong>#${escapeHtml(e.label)}</strong>` +
            `<span>${escapeHtml(t('{n} pages', { n: String(n) }))}</span></span>`
          a.addEventListener('click', () => { close(); this.openTag(e.key) })
          li.append(a)
          results.append(li)
        }
      }
      // THE ARROWS MOVE THE HIGHLIGHT, the query keeps the focus — the / menu's
      // pattern. They did nothing here: a result was reachable only by Tab,
      // which walks past it into the rest of the card.
      let at = 0
      const rows = () => [...results.querySelectorAll<HTMLElement>('.sp-result')]
      const mark = () => {
        rows().forEach((r, i) => {
          r.classList.toggle('sp-sel', i === at)
          r.setAttribute('aria-selected', String(i === at))
        })
        rows()[at]?.scrollIntoView({ block: 'nearest' })
      }
      input.setAttribute('aria-label', t('Search all pages…'))
      input.addEventListener('input', run)
      input.addEventListener('keydown', (e) => {
        const n = rows().length
        if (e.key === 'ArrowDown' && n) { e.preventDefault(); at = (at + 1) % n; mark() }
        else if (e.key === 'ArrowUp' && n) { e.preventDefault(); at = (at - 1 + n) % n; mark() }
        else if (e.key === 'Enter') rows()[at]?.click()
      })
      card.append(input, results)
    }, { top: true })
  }

  /**
   * THE TAG INDEX, reachable from the tag itself.
   *
   * A chip you cannot click is decoration; the whole reason to write `#recipe`
   * rather than the word "recipe" is that the tag is a way BACK to everything
   * else carrying it. So the chip, ⌘K's `#` mode and the graph all land here.
   *
   * Everything on this sheet is derived on open, from `store.tags`, which is
   * itself derived from the prose. Nothing here is stored, so a tag that stops
   * being written stops existing, with no orphaned entry to garbage-collect —
   * which is the whole argument for not keeping a `page.tags` array.
   *
   * NESTED TAGS get a row of their own at the top. `#project` shows the pages
   * that carry `#project/bento` too (that is what nesting means), and naming
   * the children is what stops that from looking like a bug.
   */
  openTag(key: string): void {
    const s = this.store
    this.openOverlay(t('Tag'), (card, close) => {
      const entry = s.tags.tags.get(key)
      const label = entry?.label ?? key
      card.append(el('h2', 'sp-card-h', '#' + label))

      // UP and DOWN, both as chips, because a hierarchy nobody can walk is a
      // naming convention rather than a hierarchy. `#project` is the case that
      // makes the up half necessary: if only `#project/bento` was ever
      // written, `#project` has no entry of its own, appears in no ⌘K listing
      // and would be reachable from nothing at all — while still being a
      // perfectly good thing to ask a view for.
      const rel = [...ancestorsOf(key), ...keysUnder(s.tags, key).filter((k) => k !== key)]
      if (rel.length) {
        const row = el('div', 'sp-tag-kids')
        for (const k of rel) {
          const b = el('button', 'sp-tag-chip', '#' + (s.tags.tags.get(k)?.label ?? k))
          b.addEventListener('click', () => { close(); this.openTag(k) })
          row.append(b)
        }
        card.append(row)
      }

      const pages = pagesWithTag(s.doc, s.tags, key)
      card.append(el('p', 'sp-tag-count', t('{n} pages', { n: String(pages.length) })))
      const ul = el('ul', 'sp-results')
      for (const page of pages) {
        const li = document.createElement('li')
        const a = document.createElement('button')
        a.className = 'sp-result'
        // The snippet is the FIRST block on that page that actually carries the
        // tag — not the first block of the page. "Why is this page here" is the
        // question a tag index has to answer, and the page's opening line
        // usually does not.
        const ref = (entry?.refs ?? []).find((r) => r.pageId === page.id)
        const snip = textOf(s.index.block.get(ref?.blockId ?? '')?.block.html).slice(0, 120)
        a.innerHTML =
          `<span class="sp-result-ico">${ICONS.page}</span>` +
          `<span class="sp-result-txt"><strong>${escapeHtml(page.title || t('Untitled'))}` +
          (page.archived ? ` <em class="sp-arch">${t('archived')}</em>` : '') + `</strong>` +
          `<span>${escapeHtml(snip)}</span></span>`
        a.addEventListener('click', () => { close(); s.goToPage(page.id) })
        li.append(a)
        ul.append(li)
      }
      if (!pages.length) ul.append(el('li', 'sp-noresult', t('Nothing found')))
      card.append(ul)
    })
  }

  /** Every tag in the space, for the ⌘K empty state and anything else asking. */
  allTags(): TagEntry[] { return tagList(this.store.tags) }

  /**
   * The block menu, anchored where you are.
   *
   * A centred modal for "turn this line into a heading" loses the thing you
   * were pointing at. This opens beside the caret (or the gutter button that
   * summoned it), is driven entirely by the keyboard, and filters as you type
   * so `/h2` reaches a heading without the hand leaving the keys.
   */
  private openSlash(blockId: string, anchor?: HTMLElement): void {
    this.closeOverlay()
    const pop = el('div', 'sp-pop')
    pop.setAttribute('role', 'listbox')
    const find = document.createElement('input')
    find.className = 'sp-find'
    find.placeholder = t('Filter blocks…')
    const list = el('ul', 'sp-results')
    pop.append(find, list)

    // The bar's insert families, in the bar's order and under its names
    // (inserts.ts): a family with variants under its caption, the one-member
    // kinds set apart by a rule. Filtering drops the captions — a match list
    // is one run.
    const sections = insertSections()
    const all = sections.flatMap((x) => x.items)
    let items = all
    let sel = 0
    const commit = (item: InsertItem) => {
      this.closeOverlay()
      const blk = this.store.block(blockId)
      // the "/" that opened the menu is a command, not content
      if (blk && (blk.html ?? '').trim() === '/') blk.html = ''
      if (item.type === 'pagelink') this.insertPageCard(blockId)
      else if (item.type === 'embed') this.insertEmbed(blockId)
      else if (item.type === 'link') { this.setType(blockId, 'link'); this.openLinkCard(blockId) }
      else this.setType(blockId, item.type, item.init)
    }
    const paint = () => {
      list.innerHTML = ''
      const filtered = items !== all
      items.forEach((item, i) => {
        if (!filtered) {
          const sec = sections.find((x) => x.items[0] === item)
          // not options: the listbox's arrows walk `items`, never these
          const deco = sec?.caption ? el('li', 'sp-results-cap', t(sec.caption)) : sec?.rule ? el('li', 'sp-results-rule') : null
          if (deco) { deco.setAttribute('role', 'presentation'); list.append(deco) }
        }
        const li = document.createElement('li')
        const b = document.createElement('button')
        b.className = 'sp-result' + (i === sel ? ' sp-sel' : '')
        b.type = 'button'
        b.setAttribute('role', 'option')
        b.dataset.insert = item.key
        b.innerHTML =
          `<span class="sp-result-ico">${ICONS[item.icon]}</span>` +
          `<span class="sp-result-txt"><strong>${escapeHtml(t(item.label))}</strong>` +
          `<span>${escapeHtml(t(item.hint))}</span></span>`
        b.addEventListener('click', () => commit(item))
        li.append(b)
        list.append(li)
      })
      if (!items.length) list.append(el('li', 'sp-noresult', t('No block matches')))
    }
    find.addEventListener('input', () => {
      const q = find.value.trim().toLowerCase()
      items = q ? all.filter((i) => t(i.label).toLowerCase().includes(q) || i.type.includes(q)) : all
      sel = 0
      paint()
    })
    find.addEventListener('keydown', (e) => {
      if (e.key === 'ArrowDown') { e.preventDefault(); sel = Math.min(sel + 1, items.length - 1); paint() }
      else if (e.key === 'ArrowUp') { e.preventDefault(); sel = Math.max(sel - 1, 0); paint() }
      else if (e.key === 'Enter') { e.preventDefault(); if (items[sel]) commit(items[sel]) }
      else if (e.key === 'Escape') { e.preventDefault(); this.closeOverlay(); this.focusBlock(blockId) }
    })
    paint()

    // a COMBOBOX, not a menu: the filter keeps the focus and the arrows move
    // the highlight, so it stays a popover. Anchored to the caret even on a
    // phone — a sheet at the bottom edge would sit under the soft keyboard.
    find.setAttribute('aria-label', t('Filter blocks…'))
    this.float(pop, anchor ?? caretRect(), { sheet: false, onEscape: () => this.focusBlock(blockId) })
    find.focus()
  }

  private insertPageCard(blockId: string): void {
    this.openPagePicker(blockId, null, (pageId) => {
      this.store.commit(() => {
        const b = this.store.block(blockId)
        if (b) { b.type = 'pagelink'; b.page = pageId; b.html = '' }
      })
      this.paintPage()
    })
  }

  /**
   * THE ONE WRITER for an embed's target — the same rule as a link card's
   * fields (applyLinkCard below), for the same reason.
   *
   * `html` is written alongside `page`, always, and it is a LINK to the target
   * rather than a copy of anything: a build that has never heard of `embed`
   * renders an unknown type's html (render.ts default case), so an older shell
   * opening this file shows a link to the source page instead of a blank box.
   * An embed written without it is a block that vanishes in last year's shell.
   *
   * A section returned to "the whole page" DELETES `anchor` rather than
   * storing an empty one — a default is never bytes in the file (PLATFORM §3).
   */
  private applyEmbed(blockId: string, pageId: string, anchor?: string): void {
    const s = this.store
    s.commit(() => {
      const b = s.block(blockId)
      if (b) this.embedFields(b, pageId, anchor)
    })
    this.paintPage()
  }

  /** An embed's fields, written together: what it shows, and its readable `html`. */
  private embedFields(b: Block, pageId: string, anchor?: string): void {
    const target = this.store.index.page.get(pageId)
    b.type = 'embed'
    b.page = pageId
    if (anchor) b.anchor = anchor
    else delete b.anchor
    b.html = `<a href="#p/${pageId}">${escapeHtml(target?.title || t('Untitled'))}</a>`
  }

  /**
   * Choose what an embed shows: a page, or one section of it.
   *
   * ITS OWN PICKER rather than openPagePicker with a flag, because the list is
   * a different list — every page AND every heading on it, so "show me the
   * Rollout section of the plan" is one gesture instead of choose-then-hunt.
   * The heading names come from embed.ts `headingsOf`, which is the same list
   * `sectionOf` matches against, so a section you can pick here is a section
   * that resolves.
   */
  private insertEmbed(blockId: string, then?: (pageId: string, anchor?: string) => void): void {
    // the bar makes the block only once a page is chosen (insertItem); the /
    // menu converts the block it was opened on
    const pick = (pageId: string, anchor?: string) => then ? then(pageId, anchor) : this.applyEmbed(blockId, pageId, anchor)
    const s = this.store
    if (s.readOnly || this.reading) return
    this.openOverlay(t('Embed a page'), (card, close) => {
      const input = document.createElement('input')
      input.className = 'sp-find'
      input.placeholder = t('Find a page or a section…')
      const list = el('ul', 'sp-results')
      const row = (label: string, sub: string, then: () => void) => {
        const li = document.createElement('li')
        const b = document.createElement('button')
        b.className = 'sp-result'
        b.type = 'button'
        b.innerHTML =
          `<span class="sp-result-ico">${ICONS.page}</span>` +
          `<span class="sp-result-txt"><strong>${escapeHtml(label)}</strong>` +
          (sub ? `<span>${escapeHtml(sub)}</span>` : '') + '</span>'
        b.addEventListener('click', () => { close(); then() })
        li.append(b)
        list.append(li)
      }
      const run = () => {
        const q = input.value.trim().toLowerCase()
        list.innerHTML = ''
        for (const p of s.doc.pages) {
          // A PAGE CANNOT EMBED ITSELF, so it is not offered. The renderer
          // stops that loop safely either way; offering it would be offering a
          // placeholder.
          if (p.id === s.pageId) continue
          const title = p.title || t('Untitled')
          const heads = headingsOf(p).filter((h) => !q || h.text.toLowerCase().includes(q))
          const hit = !q || title.toLowerCase().includes(q)
          if (hit) row(title, t('The whole page'), () => pick(p.id))
          for (const h of (hit ? headingsOf(p) : heads)) {
            row(`${title} › ${h.text}`, t('That section only'),
              () => pick(p.id, h.text))
          }
          if (list.childElementCount > 40) break
        }
        if (!list.childElementCount) list.append(el('li', 'sp-noresult', t('No page matches')))
      }
      input.addEventListener('input', run)
      card.append(input, list)
      run()
      setTimeout(() => input.focus(), 0)
    }, { top: true })
  }

  /**
   * THE ONE WRITER for a link card's fields.
   *
   * Fields and `html` move together, always — the same rule as a field value
   * (applyField above), for the same reason: `html` is what a build that has
   * never heard of `link` renders, and format additivity is a promise about
   * what OLD builds do. A card whose fields were written without it is a card
   * that vanishes when the file is opened in last year's shell.
   */
  private applyLinkCard(b: Block, next: Partial<Block>): void {
    b.type = 'link'
    for (const k of ['url', 'title', 'desc', 'site', 'icon', 'image'] as const) {
      const v = next[k]
      // an EMPTY field is an absent field: a card carrying `"desc": ""` is
      // bytes in every copy of the file that say nothing
      if (typeof v === 'string' && v.trim()) (b as Record<string, unknown>)[k] = v.trim()
      else delete (b as Record<string, unknown>)[k]
    }
    b.html = linkCardHtml(linkCard(b))
  }

  /**
   * The link card's editor — and the whole of this feature's honesty.
   *
   * A link card in Notion or Slack is a SERVER fetching the url and reading its
   * OpenGraph tags. There is no server here, and a fetch on this path would
   * break the one promise the format is built on. So the author fills the card
   * in, the dialog says so plainly, and nothing about opening a space ever
   * contacts the site it links to.
   */
  private openLinkCard(blockId: string): void {
    const s = this.store
    if (s.readOnly || this.reading) return
    const at = s.block(blockId)
    if (!at) return
    // a draft, so Escape leaves the block exactly as it was
    const draft: Record<string, string> = {
      url: String(at.url ?? ''), title: String(at.title ?? ''),
      desc: String(at.desc ?? ''), site: String(at.site ?? ''),
      icon: String(at.icon ?? ''), image: String(at.image ?? ''),
    }

    this.openOverlay(t('Link card'), (card, close) => {

      const why = document.createElement('p')
      why.className = 'sp-note'
      why.textContent = t('Nothing is fetched. A card shows what you type here — opening this space never contacts the site.')
      card.append(why)

      const field = (key: string, label: string, hint?: string): HTMLInputElement => {
        const wrap = el('div', 'sp-field')
        wrap.append(el('label', 'sp-field-lbl', label))
        const input = document.createElement('input')
        input.className = 'sp-input'
        input.value = draft[key]
        if (hint) input.placeholder = hint
        input.addEventListener('input', () => { draft[key] = input.value })
        wrap.append(input)
        card.append(wrap)
        return input
      }

      const url = field('url', t('Web address'), 'https://example.com')
      url.type = 'url'
      field('title', t('Title'), t('What this is'))
      field('desc', t('Description'), t('One line about what is there'))
      // the host is what shows when this is blank, so the placeholder is the
      // answer rather than an example
      field('site', t('Site name'), t('Taken from the address if blank'))
      field('icon', t('Icon'), t('One emoji'))

      // THE THUMBNAIL IS EMBEDDED, never linked. `prepareImage` downscales and
      // `internAsset` stores the bytes in the file, exactly as an image block
      // does — which is why a card can carry a picture at all without becoming
      // a request on open.
      const row = el('div', 'sp-actions')
      const pick = document.createElement('button')
      pick.className = 'sp-btn'
      pick.type = 'button'
      const paintPick = () => {
        pick.textContent = draft.image ? t('Replace picture') : t('Add a picture')
        drop.hidden = !draft.image
      }
      pick.addEventListener('click', () => {
        const input = document.createElement('input')
        input.type = 'file'
        input.accept = 'image/*'
        input.addEventListener('change', () => {
          const file = input.files?.[0]
          if (!file) return
          void (async () => {
            try {
              const prepared = await prepareImage(file)
              draft.image = await internAsset(s.doc, prepared.dataUri)
            } catch { this.notice(t('That file could not be read as an image')); return }
            paintPick()
          })()
        })
        input.click()
      })
      const drop = document.createElement('button')
      drop.className = 'sp-btn'
      drop.type = 'button'
      drop.textContent = t('Remove the picture')
      drop.addEventListener('click', () => { draft.image = ''; paintPick() })
      paintPick()
      row.append(pick, drop)
      card.append(row)

      const done = el('div', 'sp-actions')
      const save = document.createElement('button')
      save.className = 'sp-btn sp-primary'
      save.type = 'button'
      save.textContent = t('Save')
      save.addEventListener('click', () => {
        close()
        s.commit(() => { const b = s.block(blockId); if (b) this.applyLinkCard(b, draft) })
        this.paintPage()
      })
      done.append(save)
      card.append(done)
      url.focus()
    })
  }

  /** `[[` — pick a page, or make one, and link it inline. */
  private openPagePicker(blockId: string, host: HTMLElement | null, then?: (pageId: string) => void): void {
    const s = this.store
    this.openOverlay(t('Link to page'), (card, close) => {
      const input = document.createElement('input')
      input.className = 'sp-find'
      input.placeholder = t('Find or create a page…')
      const list = el('ul', 'sp-results')
      const choose = (pageId: string, title: string) => {
        close()
        if (then) { then(pageId); return }
        if (!host) return
        // the two "[" that opened the picker are not content
        const html = (host.innerHTML ?? '').replace(/\[?\[$/, '')
        const link = `<a href="#p/${pageId}">${escapeHtml(title)}</a>&nbsp;`
        s.commit(() => { const b = s.block(blockId); if (b) b.html = sanitizeInline(html + link) })
        this.paintPage()
        this.focusBlock(blockId)
      }
      const run = () => {
        const q = input.value.trim().toLowerCase()
        list.innerHTML = ''
        for (const p of s.doc.pages) {
          // `[[` FINDS A PAGE BY ITS ALIASES TOO — the third of the three
          // places an alias has to reach (the resolver, ⌘K, here). Typing
          // `[[NYC` must offer the page titled "New York", or the alias only
          // works for text somebody imported and never for text you type.
          const names = namesOf(p)
          const alias = q ? names.slice(1).find((n) => n.toLowerCase().includes(q)) : undefined
          if (q && !p.title.toLowerCase().includes(q) && !alias) continue
          const li = document.createElement('li')
          const b = document.createElement('button')
          b.className = 'sp-result'
          b.type = 'button'
          b.innerHTML =
            `<span class="sp-result-ico">${ICONS.page}</span>` +
            `<span class="sp-result-txt"><strong>${escapeHtml(p.title || t('Untitled'))}</strong>` +
            (alias ? `<span>${escapeHtml(t('also called “{name}”', { name: alias }))}</span>` : '') +
            `</span>`
          b.addEventListener('click', () => choose(p.id, p.title || t('Untitled')))
          li.append(b)
          list.append(li)
          if (list.childElementCount > 20) break
        }
        if (input.value.trim()) {
          const li = document.createElement('li')
          const b = document.createElement('button')
          b.className = 'sp-result sp-new'
          b.type = 'button'
          b.innerHTML =
            `<span class="sp-result-ico">${ICONS.plus}</span>` +
            `<span class="sp-result-txt"><strong>${escapeHtml(t('Create “{name}”', { name: input.value.trim() }))}</strong></span>`
          b.addEventListener('click', () => {
            const page = newPage(input.value.trim())
            s.commit(() => { s.doc.pages.push(page) })
            choose(page.id, page.title)
          })
          li.append(b)
          list.append(li)
        }
        at = 0
        mark()
      }
      // the same arrows-move-the-highlight as search and the / menu
      let at = 0
      const rows = () => [...list.querySelectorAll<HTMLElement>('.sp-result')]
      const mark = () => rows().forEach((r, i) => {
        r.classList.toggle('sp-sel', i === at)
        r.setAttribute('aria-selected', String(i === at))
        if (i === at) r.scrollIntoView({ block: 'nearest' })
      })
      input.setAttribute('aria-label', t('Find or create a page…'))
      input.addEventListener('input', run)
      input.addEventListener('keydown', (e) => {
        const n = rows().length
        if (e.key === 'ArrowDown' && n) { e.preventDefault(); at = (at + 1) % n; mark() }
        else if (e.key === 'ArrowUp' && n) { e.preventDefault(); at = (at - 1 + n) % n; mark() }
        else if (e.key === 'Enter' && n) { e.preventDefault(); rows()[at]?.click() }
      })
      card.append(input, list)
      run()
    }, { top: true })
  }

  /** Pick a page icon from the stylised set. */
  private openIconPicker(pageId: string, anchor: HTMLElement): void {
    this.closeOverlay()
    const pop = el('div', 'sp-pop sp-iconpop')
    for (const name of PAGE_ICONS) {
      const b = document.createElement('button')
      b.className = 'sp-iconopt'
      b.type = 'button'
      b.innerHTML = ICONS[name]
      b.title = name
      b.setAttribute('aria-label', name)
      b.addEventListener('click', () => {
        this.closeOverlay()
        this.store.commit(() => {
          const p = this.store.index.page.get(pageId)
          if (p) p.icon = name
        })
        this.paintPage()
      })
      pop.append(b)
    }
    // a GRID of choices, not a list — a popover, which Escape closes and which
    // the keyboard lands in
    this.float(pop, anchor, { sheet: false, role: 'dialog', label: t('Icon'), onEscape: () => anchor.focus?.() })
    afterPaint(() => pop.querySelector<HTMLElement>('button')?.focus())
  }

  /**
   * Which kind of callout this is, and (optionally) a glyph of your own.
   *
   * Five tones and one field, anchored on the chip you clicked. The icon is a
   * plain text box rather than an emoji grid: the system emoji picker is one
   * keystroke away on every platform this runs on, and a grid of our own would
   * be a few KB to ship a worse one.
   */
  private openTonePicker(blockId: string, anchor: HTMLElement): void {
    const s = this.store
    const b = s.block(blockId)
    if (!b || s.readOnly || this.reading) return
    const current = String(b.tone ?? 'note')
    this.menuAt(anchor, t('Callout'), (m) => {
      for (const tone of CALLOUT_TONES) {
        const btn = row(m, { icon: ICONS[tone.icon], label: toneLabel(tone.tone), selected: tone.tone === current,
          run: () => {
            s.commit(() => { const bb = s.block(blockId); if (bb) bb.tone = tone.tone })
            this.paintPage()
          } })
        btn.setAttribute('role', 'menuitemradio')
        btn.setAttribute('aria-checked', String(tone.tone === current))
        btn.querySelector('.bkm-ico')?.classList.add('sp-result-ico', `sp-tone-${tone.tone}`)
      }

      const iconRow = el('label', 'sp-tonerow')
      const icon = document.createElement('input')
      icon.className = 'sp-find sp-toneicon'
      icon.value = typeof b.icon === 'string' ? b.icon : ''
      icon.maxLength = 16
      icon.placeholder = t('Leave it empty to use the tone mark')
      icon.setAttribute('aria-label', t('Callout icon'))
      // `change`, not `input`: one commit when the field is done with, rather
      // than one undo entry per keystroke of a pasted emoji
      icon.addEventListener('change', () => {
        const v = icon.value.trim()
        s.commit(() => {
          const bb = s.block(blockId)
          if (!bb) return
          if (v) bb.icon = v
          else delete bb.icon
        })
        this.paintPage()
      })
      icon.addEventListener('keydown', (e) => {
        if (e.key === 'Enter') { e.preventDefault(); icon.blur(); m.close() }
      })
      iconRow.append(el('span', 'sp-tonelabel', t('Icon')), icon)
      m.separator()
      extra(m, iconRow)
    })
  }

  /** Rename, archive, or delete one page. */
  private openPageMenu(pageId: string, anchor: HTMLElement): void {
    const s = this.store
    const page = s.index.page.get(pageId)
    if (!page) return
    // A CONSEQUENCE menu (D2): the rows that change or remove something say
    // what, on the row. The ones that only go somewhere are a name.
    this.menuAt(anchor, t('Page options'), (m) => {
      row(m, { icon: ICONS.edit, label: t('Rename'), run: () => {
        s.goToPage(pageId)
        afterPaint(() => {
          const h = this.main.querySelector<HTMLElement>('[data-page-title]')
          if (h) { h.focus(); selectAll(h) }
        })
      } })

      row(m, { icon: ICONS.plus, label: t('New page inside'), run: () => this.newPage(pageId) })
      // Moved here from ⋯ (DECISIONS 2026-09-26): it acts on ONE page, and the
      // page's own menu is where slides keeps what acts on one slide. A
      // consequence row (D2): it adds four fields.
      if (!s.readOnly && !isIssue(page)) {
        row(m, { icon: ICONS.tag, label: t('Make this page an issue'), hint: t('Adds status, priority, assignee, estimate'),
          run: () => this.makeIssue(pageId) })
      }

      if (!s.readOnly) {
        row(m, { icon: ICONS.copy, label: t('Save as template'), hint: t('New pages can start as a copy of this one'),
          run: () => savePageAsTemplate(this.templateHost, page) })
      }

      // A thread about the PAGE — the second and last anchor. It is offered
      // where the page's own actions are, and only for the page in view,
      // because a thread is written into the page you are looking at.
      if (pageId === s.pageId && !s.readOnly) {
        row(m, { icon: ICONS.comment, label: t('Comment on this page'), run: () => this.comments.openNew() })
      }

      row(m, {
        icon: page.archived ? ICONS.unarchive : ICONS.archive,
        label: page.archived ? t('Restore to the page list') : t('Archive'),
        hint: page.archived ? undefined : t('Out of the sidebar, still searchable and linkable'),
        run: () => {
          s.commit(() => {
            const p = s.index.page.get(pageId)
            if (!p) return
            if (p.archived) delete p.archived
            else p.archived = true
          })
        },
      })

      // HOW WIDE THIS PAGE IS. The renderer already varied it — a page carrying
      // a board jumped to 1500px — but it decided for you silently. Measured at
      // a 1600px viewport: the default column is 720px with 631px of the page
      // left empty beside it, and nothing on the starter pages even reaches the
      // limit (0 of 15 blocks wrap). The line length was never the problem;
      // having no say was.
      caption(m, t('Width'))
      const current: 'normal' | 'wide' | 'full' =
        page.width === 'wide' ? 'wide' : page.width === 'full' ? 'full' : 'normal'
      const setWidth = (v: 'normal' | 'wide' | 'full') => {
        s.commit(() => {
          const pg = s.index.page.get(pageId)
          if (!pg) return
          // THE DEFAULT IS AN ABSENT KEY, never a stored 'normal'. A page
          // somebody set to wide and back is then byte-identical to one never
          // touched, and a file written before this control existed stays so.
          if (v === 'normal') delete pg.width
          else pg.width = v
        }, { scope: 'doc' })
        this.paintPage()
      }
      row(m, { icon: ICONS.widthNarrow, label: t('Column'), hint: t('Comfortable for reading'),
        selected: current === 'normal', run: () => setWidth('normal') })
      row(m, { icon: ICONS.widthWide, label: t('Wide'), hint: t('Room for a board or a table'),
        selected: current === 'wide', run: () => setWidth('wide') })
      row(m, { icon: ICONS.widthFull, label: t('Full width'), hint: t('Fills the window'),
        selected: current === 'full', run: () => setWidth('full') })

      // AND THE SAME CHOICE, FOR EVERY PAGE. Setting a width page by page
      // answers "this page needs the room"; it does not answer "I have a wide
      // screen", which is one fact about one person and was costing a visit to
      // every page in the space. This one is a VIEWER preference —
      // localStorage, never the file — so it follows the reader rather than
      // the document, and somebody opening the same space on a laptop is
      // unaffected.
      const pref = readerWidth()
      const applyAll = (v: 'wide' | 'full' | undefined) => {
        setReaderWidth(v)
        this.paintPage()
        this.notice(v ? t('Every page opens wide on this screen from now on')
                      : t('Pages open at their normal width again'))
      }
      row(m, {
        icon: pref ? ICONS.widthNarrow : ICONS.widthWide,
        label: pref ? t('Stop widening every page') : t('Use this width for every page'),
        hint: pref ? t('Only pages that ask for it') : t('On this screen only — it is not saved in the file'),
        run: () => applyAll(pref ? undefined : (current === 'full' ? 'full' : 'wide')),
      })

      // THIS PAGE'S DESIGN — the author's choice, per page, beside the width
      // (the other thing about how a page is set). The hint says what the page
      // wears NOW, inherited or its own, so the row answers before it opens.
      // Its choices open as their own menu, anchored where this one was.
      {
        const r = resolvePageDesign(s.doc, pageId)
        const wears = designLabel(s.doc, r?.name ?? null)
        const item = row(m, { icon: ICONS.palette, label: t('Design'),
          hint: page.design !== undefined ? wears : t('Inherited · {name}', { name: wears }),
          run: () => this.openPageDesign(pageId, anchor) })
        item.setAttribute('aria-haspopup', 'menu')
      }

      m.separator()
      row(m, { icon: ICONS.trash, label: t('Delete…'), hint: t('Links to it become dead'),
        run: () => this.deletePage(pageId) })
    })
  }

  /**
   * Delete a page.
   *
   * Its children are re-homed to ITS parent rather than deleted with it —
   * removing a middle page should not silently take a subtree the author was
   * not looking at. Inbound links are counted in the confirmation, because
   * "this will break 4 links" is the fact that decides it.
   */
  private deletePage(pageId: string): void {
    const s = this.store
    const page = s.index.page.get(pageId)
    if (!page) return
    if (s.doc.pages.length <= 1) { this.notice(t('A space needs at least one page')); return }
    const inbound = (s.index.backlinks.get(pageId) ?? []).length
    const kids = s.doc.pages.filter((p) => p.parent === pageId).length
    const parts = [t('Delete “{name}”?', { name: page.title || t('Untitled') })]
    if (inbound) parts.push(t('{n} link(s) to it will stop working.', { n: inbound }))
    if (kids) parts.push(t('{n} page(s) inside it move up a level.', { n: kids }))
    if (!confirm(parts.join('\n'))) return
    s.commit(() => {
      for (const p of s.doc.pages) if (p.parent === pageId) {
        if (page.parent) p.parent = page.parent
        else delete p.parent
      }
      s.doc.pages.splice(s.doc.pages.findIndex((p) => p.id === pageId), 1)
      if (s.doc.home === pageId) delete s.doc.home
    })
    this.repaint()
  }

  // ---- images --------------------------------------------------------------
  /** Choose a file and put it in the document. */
  async pickImage(blockId: string): Promise<void> {
    const input = document.createElement('input')
    input.type = 'file'
    input.accept = 'image/*'
    input.addEventListener('change', () => {
      const file = input.files?.[0]
      if (file) void this.placeImage(blockId, file)
    })
    input.click()
  }

  /**
   * Embed one image.
   *
   * Everything slow and asynchronous — reading, decoding, re-encoding, hashing
   * — happens BEFORE the commit, so the bytes and the reference land in ONE
   * synchronous mutation. That is what makes an image insert a single undo
   * step instead of a half-inserted block if something throws in between.
   */
  async placeImage(
    blockId: string | null,
    file: File | Blob,
    opts: { keepOriginal?: boolean; insertAfter?: string | null } = {},
  ): Promise<void> {
    const s = this.store
    this.status(t('Reading image…'))
    let prepared
    try {
      prepared = opts.keepOriginal
        ? { dataUri: await blobToDataUri(file), w: 0, h: 0, original: true, wasBytes: file.size }
        : await prepareImage(file)
    } catch {
      this.notice(t('That file could not be read as an image'))
      return
    }

    if (prepared.dataUri.length > IMAGE_EMBED_BUDGET) {
      const ok = confirm(t(
        'This image is {size} and travels inside the file, making it that much bigger for everyone you send it to. Embed it anyway?',
        { size: humanBytes(prepared.dataUri.length) },
      ))
      if (!ok) { this.status(''); return }
    }

    const ref = await internAsset(s.doc, prepared.dataUri)
    const fill = (b: Block) => {
      b.type = 'image'
      b.src = ref
      b.html = ''
      if (prepared.w) { b.w = prepared.w; b.h = prepared.h }
      if (!prepared.original) b.original = false
      else delete b.original
    }
    // ONE commit, whether the block already exists or is being created here.
    // Creating it in a separate commit would make an inserted image take TWO
    // undos, the second of which removes a block the author never saw.
    s.commit(() => {
      if (blockId) { const b = s.block(blockId); if (b) fill(b) ; return }
      const page = s.page
      if (!page) return
      const fresh = newBlock('image')
      fill(fresh)
      const at = opts.insertAfter ? page.blocks.findIndex((b) => b.id === opts.insertAfter) + 1 : page.blocks.length
      page.blocks.splice(at < 1 ? page.blocks.length : at, 0, fresh)
    })
    this.paintPage()
    this.status(prepared.original
      ? t('Image added ({size})', { size: humanBytes(prepared.dataUri.length) })
      : t('Image added, resized to fit ({from} → {to})', {
        from: humanBytes(prepared.wasBytes), to: humanBytes(prepared.dataUri.length),
      }))
  }

  /**
   * Drop or paste an image — or a clip — straight onto the page.
   *
   * Images win a tie. A drag that carries both (a screenshot alongside a
   * screen recording, which is what a Finder multi-select of a bug report
   * looks like) takes the image, because that is the one an author is far more
   * often reaching for and the one that costs nothing to be wrong about.
   */
  private async fileFromTransfer(dt: DataTransfer | null, afterId?: string): Promise<boolean> {
    const pick = (kind: string): File | undefined =>
      [...(dt?.files ?? [])].find((f) => f.type.startsWith(kind))
      ?? [...(dt?.items ?? [])].filter((i) => i.type.startsWith(kind)).map((i) => i.getAsFile())[0]
      ?? undefined
    if (!this.store.page) return false
    const img = pick('image/')
    if (img) { await this.placeImage(null, img, { insertAfter: afterId ?? null }); return true }
    const clip = pick('video/') ?? pick('audio/')
    if (!clip) return false
    await this.placeMedia(null, clip, { insertAfter: afterId ?? null })
    return true
  }

  // ---- video and audio -------------------------------------------------------
  /**
   * Choose a clip and put it in the document.
   *
   * `accept` names both kinds and the KIND IS READ BACK OFF THE FILE, never
   * asked for. A picker that made you say "video" first would be a question
   * the file already answers, and answers correctly for the odd cases — an
   * .m4a that a phone wrote as video/mp4 plays either way.
   */
  async pickMedia(blockId: string): Promise<void> {
    const input = document.createElement('input')
    input.type = 'file'
    input.accept = 'video/*,audio/*'
    input.addEventListener('change', () => {
      const file = input.files?.[0]
      if (file) void this.placeMedia(blockId, file)
    })
    input.click()
  }

  /**
   * Embed one clip.
   *
   * Shaped like placeImage and for the same reason: everything asynchronous —
   * reading the bytes, hashing them — happens BEFORE the commit, so the asset
   * and the reference land in one synchronous mutation and one undo step.
   *
   * NOTHING IS RE-ENCODED. prepareImage exists because a phone photo is 4000px
   * wide in a 720px column and the detail is invisible; there is no equivalent
   * cheap win for video, and transcoding in a browser tab means shipping an
   * encoder and taking minutes over it. So a clip is either small enough to
   * embed or a link — which is what MEDIA_EMBED_BUDGET asks about.
   */
  async placeMedia(
    blockId: string | null,
    file: File | Blob,
    opts: { insertAfter?: string | null } = {},
  ): Promise<void> {
    const s = this.store
    this.status(t('Reading file…'))
    let dataUri: string
    try {
      dataUri = await blobToDataUri(file)
    } catch {
      this.notice(t('That file could not be read'))
      return
    }
    const kind = (file as File).type?.startsWith('audio/') ? 'audio' : 'video'

    if (dataUri.length > MEDIA_EMBED_BUDGET) {
      // A browser file picker hands over BYTES, never a path, so "keep it on
      // disk and point at it" is not a thing this can offer. The honest
      // alternatives are: embed it anyway, or paste a URL — which is what the
      // block's own chooser offers, and where a no lands you.
      const go = confirm(t(
        'This clip is {size} and travels inside the file, making it that much bigger for everyone you send it to. Embed it anyway?',
        { size: humanBytes(dataUri.length) },
      ))
      if (!go) { this.status(''); return }
    }

    const ref = await internAsset(s.doc, dataUri)
    this.writeMedia(blockId, opts.insertAfter ?? null, (b) => { b.src = ref; b.kind = kind })
    this.status(t('Clip added ({size})', { size: humanBytes(dataUri.length) }))
  }

  /**
   * The escape hatch: a clip that lives somewhere else.
   *
   * The only way to have a small file with a big video in it, and the reason
   * `src` is hybrid at all. It is a real trade and it is stated at the point of
   * the decision — a linked clip needs the network to play, and asking for it
   * tells that host somebody opened the space, which is why the READER is
   * asked before it loads (render.ts).
   */
  linkMedia(blockId: string | null, insertAfter: string | null = null): void {
    const url = prompt(t('Address of a video or audio file'))?.trim()
    if (!url) return
    // http(s) only, and checked HERE as well as in the sanitizer: `src` is not
    // inline html, so it never passes through sanitize.ts at all — a
    // `javascript:` typed into this box would be written straight onto the
    // element. The allowlist is the test, never a `javascript:` blocklist.
    if (!/^https?:\/\//i.test(url)) { this.notice(t('That needs to be an http or https address')); return }
    const kind = /\.(mp3|m4a|aac|wav|ogg|oga|opus|flac|weba)(\?|#|$)/i.test(url) ? 'audio' : 'video'
    this.writeMedia(blockId, insertAfter, (b) => { b.src = url; b.kind = kind })
    this.status('')
  }

  /** ONE commit, whether the block exists already or is being created here —
   *  the placeImage rule: an inserted clip must not cost two undos. */
  private writeMedia(blockId: string | null, insertAfter: string | null, fill: (b: Block) => void): void {
    const s = this.store
    const apply = (b: Block) => {
      b.type = 'media'
      b.html = ''
      fill(b)
    }
    s.commit(() => {
      if (blockId) { const b = s.block(blockId); if (b) apply(b); return }
      const page = s.page
      if (!page) return
      const fresh = newBlock('media')
      apply(fresh)
      const at = insertAfter ? page.blocks.findIndex((b) => b.id === insertAfter) + 1 : page.blocks.length
      page.blocks.splice(at < 1 ? page.blocks.length : at, 0, fresh)
    })
    this.paintPage()
  }

  /** A still frame for a video — the same pipeline an image goes through, so
   *  it is downscaled and content-addressed like any other picture. */
  private async pickPoster(blockId: string): Promise<void> {
    const input = document.createElement('input')
    input.type = 'file'
    input.accept = 'image/*'
    input.addEventListener('change', () => {
      const file = input.files?.[0]
      if (!file) return
      void (async () => {
        this.status(t('Reading image…'))
        let prepared
        try { prepared = await prepareImage(file) } catch {
          this.notice(t('That file could not be read as an image')); return
        }
        const ref = await internAsset(this.store.doc, prepared.dataUri)
        this.store.commit(() => { const b = this.store.block(blockId); if (b) b.poster = ref })
        this.paintPage()
        this.status('')
      })()
    })
    input.click()
  }

  /**
   * The picture across the top of a page.
   *
   * The IMAGE pipeline, not a second one: prepareImage downscales a phone photo
   * before it travels, internAsset content-addresses the bytes so two pages
   * with the same cover store it once, and the same budget asks the same
   * question at the same size. A cover is the field most likely to be given a
   * 6MB photograph — inventing a separate policy for it is how one app ends up
   * with two answers to "how big is too big".
   */
  private async pickCover(pageId: string): Promise<void> {
    const input = document.createElement('input')
    input.type = 'file'
    input.accept = 'image/*'
    input.addEventListener('change', () => {
      const file = input.files?.[0]
      if (!file) return
      void (async () => {
        const s = this.store
        if (s.readOnly) return
        this.status(t('Reading image…'))
        let prepared
        try { prepared = await prepareImage(file) } catch {
          this.notice(t('That file could not be read as an image')); return
        }
        if (prepared.dataUri.length > IMAGE_EMBED_BUDGET) {
          const okay = confirm(t(
            'This image is {size} and travels inside the file, making it that much bigger for everyone you send it to. Embed it anyway?',
            { size: humanBytes(prepared.dataUri.length) },
          ))
          if (!okay) { this.status(''); return }
        }
        // hashed and interned BEFORE the commit, so the bytes and the reference
        // land in one synchronous mutation — one undo step, exactly as an image
        // block does it
        const ref = await internAsset(s.doc, prepared.dataUri)
        s.commit(() => {
          const p = s.index.page.get(pageId)
          if (p) p.cover = ref
        }, { scope: 'doc' })
        this.repaint()
        this.status(prepared.original
          ? t('Image added ({size})', { size: humanBytes(prepared.dataUri.length) })
          : t('Image added, resized to fit ({from} → {to})', {
            from: humanBytes(prepared.wasBytes), to: humanBytes(prepared.dataUri.length),
          }))
      })()
    })
    input.click()
  }

  /** No cover DELETES the key. A page whose cover was set and removed is
   *  byte-identical to one that never had one. The bytes stay in the asset
   *  table until nothing points at them — orphanAssets is what reports that,
   *  and it counts covers. */
  private removeCover(pageId: string): void {
    const s = this.store
    if (s.readOnly) return
    s.commit(() => {
      const p = s.index.page.get(pageId)
      if (p) delete p.cover
    }, { scope: 'doc' })
    this.repaint()
  }

  // ---- importing existing notes ---------------------------------------------
  /**
   * The way in.
   *
   * Two pickers rather than one, because a browser input is EITHER
   * `multiple` files OR `webkitdirectory` — there is no control that offers
   * both — and a folder is what a vault actually is. Dropping works for both
   * and is the gesture most people reach for first, so it is stated here
   * rather than left to be discovered.
   */
  openImport(): void {
    this.openOverlay(t('Bring notes in'), (card, close) => {

      const what = document.createElement('p')
      what.className = 'sp-note'
      what.textContent = t('Each .md file becomes a page, folders become the page tree, and [[wikilinks]] become real links. Pages are added — nothing here is replaced.')
      card.append(what)

      // WHERE the arriving pages land, and it governs BOTH ways in. An import
      // that can only append at the root is an import into a pile: the point of
      // a space is the tree, and "under the page I am reading" is what somebody
      // taking a second set of notes into a working space actually means.
      const under = document.createElement('select')
      under.className = 'sp-select'
      const top = document.createElement('option')
      top.value = ''
      top.textContent = t('Top level')
      under.append(top)
      for (const { page, depth } of this.store.tree()) {
        const o = document.createElement('option')
        o.value = page.id
        o.textContent = `${'· '.repeat(depth)}${page.title || t('Untitled')}`
        if (page.id === this.store.pageId) o.selected = true
        under.append(o)
      }
      const whereRow = el('div', 'sp-row')
      whereRow.append(el('span', '', t('Add pages under')), under)
      card.append(whereRow)
      const where = () => under.value || undefined

      const zone = el('div', 'sp-dropzone', t('Drop .md files or a folder here'))
      zone.addEventListener('dragover', (e) => { e.preventDefault(); zone.classList.add('sp-drop') })
      zone.addEventListener('dragleave', () => zone.classList.remove('sp-drop'))
      zone.addEventListener('drop', (e) => {
        e.preventDefault()
        e.stopPropagation()
        zone.classList.remove('sp-drop')
        const picked = collectDrop(e.dataTransfer)
        const at = where()
        close()
        void picked.then((files) => this.importFiles(files, { under: at }))
      })
      card.append(zone)

      const pick = (folder: boolean) => {
        const input = document.createElement('input')
        input.type = 'file'
        input.multiple = true
        if (folder) input.webkitdirectory = true
        else input.accept = '.md,.markdown,.mdown,.mkd,image/*'
        const at = where()
        input.addEventListener('change', () => {
          close()
          // webkitRelativePath is the folder tree; a plain multi-select has
          // none, and those files import as a flat set of pages
          void this.importFiles([...(input.files ?? [])]
            .map((file) => ({ path: file.webkitRelativePath || file.name, file })), { under: at })
        })
        input.click()
      }

      const pickSpace = () => {
        const input = document.createElement('input')
        input.type = 'file'
        input.accept = '.html,text/html,application/json'
        const at = where()
        input.addEventListener('change', () => {
          close()
          const file = input.files?.[0]
          if (file) void this.importSpace(file, at)
        })
        input.click()
      }

      const acts = el('div', 'sp-actions')
      acts.append(
        plainBtn(t('Choose .md files…'), () => pick(false), true),
        plainBtn(t('Choose a folder…'), () => pick(true)),
        plainBtn(t('Choose a space…'), pickSpace),
      )
      card.append(acts)

      const spaces = document.createElement('p')
      spaces.className = 'sp-note'
      spaces.textContent = t('Another bento/spaces file arrives as pages under the one you choose — its images come too, and the links inside it keep working.')
      card.append(spaces)

      const imgs = document.createElement('p')
      imgs.className = 'sp-note'
      // said BEFORE the import, because it is the one thing a browser cannot
      // do for them: it has no way to open `../attachments/x.png` itself
      imgs.textContent = t('Include the image files and they are embedded too. An image this browser cannot open is kept as its path rather than as a broken picture.')
      card.append(imgs)
    })
  }

  /**
   * Another space, grafted into this one — the way IN that answers the page
   * extract's way out.
   *
   * The file is UNTRUSTED and takes the ordinary load path, with no friendlier
   * door beside it: the document block is read out of an INERT parse (DOMParser
   * builds no browsing context, so no script runs and no resource loads),
   * `parseDoc` decides whether it is a space at all — refusing rather than
   * degrading, the same load contract main.ts boots under — and
   * `sanitizeInline` runs over every arriving block before any of it reaches
   * the document.
   */
  async importSpace(file: File, under?: string): Promise<void> {
    const s = this.store
    if (s.readOnly) { this.notice(t('This file is open read-only')); return }
    let text: string
    try { text = await file.text() } catch { this.notice(t('That file could not be read')); return }

    const body = spaceBlockOf(text)
    if (body === 'encrypted') {
      // The password is not ours to ask for, and the honest instruction is the
      // one that works: open the file where the password already is.
      this.notice(t('That space is password-protected. Open it, then export the pages you want.'))
      return
    }
    const res = parseDoc(body ?? '')
    if (!res.ok) {
      this.notice(res.err === 'format'
        ? t('That file is not a bento/spaces document')
        : t('That file could not be read'))
      return
    }

    const plan = planGraft(s.doc, res.doc, { under })
    // THE security gate, in the same place the Markdown import puts it.
    for (const page of plan.pages) {
      for (const b of page.blocks) if (b.html) b.html = sanitizeInline(b.html)
    }
    for (const [label, body] of Object.entries(plan.footnotes)) {
      plan.footnotes[label] = sanitizeInline(body)
    }

    // ONE step: pages, images and fonts land together or not at all.
    s.commit(() => {
      s.doc.pages.push(...plan.pages)
      if (Object.keys(plan.assets).length) Object.assign((s.doc.assets ??= {}), plan.assets)
      if (plan.fonts.length) (s.doc.fonts ??= []).push(...plan.fonts)
      // ADDITIONS ONLY here (unlike the Markdown path, whose plan starts from
      // this table): planGraft returns what the host does not already hold.
      if (Object.keys(plan.footnotes).length) Object.assign((s.doc.footnotes ??= {}), plan.footnotes)
    })
    if (plan.pages[0]) s.goToPage(plan.pages[0].id)
    this.repaint()

    this.openOverlay(t('Imported a space'), (card, close) => {
      const lines = [
        t('{pages} page(s) and {blocks} block(s) added from that space.',
          { pages: plan.stats.pages, blocks: plan.stats.blocks }),
      ]
      // Renaming is the outcome a reader cannot see for themselves, and the one
      // that would break every link if it were done carelessly — so it is
      // reported together with the repair that keeps the links pointing right.
      if (plan.stats.renamed) {
        lines.push(t('{n} id(s) were renamed because this space already used them, and the links inside the import follow them.',
          { n: plan.stats.renamed }))
      }
      if (plan.stats.dropped) {
        lines.push(t('{n} link(s) named pages that were not in that file, and are kept as text.', { n: plan.stats.dropped }))
      }
      if (plan.stats.assets) lines.push(t('{n} image(s) came too.', { n: plan.stats.assets }))
      lines.push(t('⌘Z removes the imported pages again.'))
      for (const line of lines) {
        const p = document.createElement('p')
        p.className = 'sp-note'
        p.textContent = line
        card.append(p)
      }
      card.append(plainBtn(t('Close'), close, true))
    })
  }

  /**
   * A page — and, by choice, what is under it — leaves as its own space.
   *
   * The counts come from the REAL extract and move as the choices do, rather
   * than being described in the abstract: how much travels, and how many links
   * point out of the selection and will become text. Those two facts are what
   * decide whether this is the extract somebody meant.
   */
  openExportSpace(): void {
    const s = this.store
    this.openOverlay(t('Export a page as a space'), (card, close) => {

      const what = document.createElement('p')
      what.className = 'sp-note'
      what.textContent = t('The page becomes a new file of its own: a whole space, with a new document id and none of this one’s sharing keys.')
      card.append(what)

      const pick = document.createElement('select')
      pick.className = 'sp-select'
      for (const { page, depth } of s.tree()) {
        const o = document.createElement('option')
        o.value = page.id
        o.textContent = `${'· '.repeat(depth)}${page.title || t('Untitled')}`
        if (page.id === s.pageId) o.selected = true
        pick.append(o)
      }
      const pageRow = el('div', 'sp-row')
      pageRow.append(el('span', '', t('Page')), pick)
      card.append(pageRow)

      const kids = document.createElement('input')
      kids.type = 'checkbox'
      kids.checked = true
      const kidsRow = el('div', 'sp-row')
      kidsRow.append(el('span', '', t('Include the pages nested under it')), kids)
      card.append(kidsRow)

      const summary = document.createElement('p')
      summary.className = 'sp-note'
      const recount = () => {
        const r = extractSpace(s.doc, pick.value, { subtree: kids.checked, docId: 'preview', now: '' })
        const parts = [t('{pages} page(s) and {blocks} block(s) will travel.',
          { pages: r.stats.pages, blocks: r.stats.blocks })]
        if (r.stats.unlinked) {
          parts.push(t('{n} link(s) point outside them and are kept as text naming the page they meant.',
            { n: r.stats.unlinked }))
        }
        if (r.stats.assets) parts.push(t('{n} image(s) go with them; the rest stay here.', { n: r.stats.assets }))
        summary.textContent = parts.join(' ')
      }
      pick.addEventListener('change', recount)
      kids.addEventListener('change', recount)
      recount()
      card.append(summary)

      const acts = el('div', 'sp-actions')
      acts.append(
        plainBtn(t('Export'), () => {
          const out = extractSpace(s.doc, pick.value, { subtree: kids.checked, docId: uid('doc') })
          close()
          void this.onExportSpace?.(out.doc).then((ok) => {
            if (ok) this.notice(t('Exported {n} page(s) as a new space', { n: out.stats.pages }))
          })
        }, true),
        plainBtn(t('Close'), close),
      )
      card.append(acts)
    })
  }

  /**
   * PAGE → DECK.
   *
   * What this hands over is the deck's DOCUMENT JSON, not a `.bento.html`
   * deck — src/todeck.ts explains why that is the honest scope from inside
   * this app. So the dialog's job is to say what the artefact IS and what to
   * do with it, and then to say, before anything is downloaded, exactly what
   * of this page did not survive the crossing. A silent lossy export is the
   * failure mode here; the summary is the feature.
   */
  openExportDeck(): void {
    const s = this.store
    this.openOverlay(t('Export a page as slides'), (card, close) => {
      card.append(el('h2', 'sp-card-h', t('Export a page as slides')))

      const what = document.createElement('p')
      what.className = 'sp-note'
      what.textContent = t('The page becomes a deck’s document. Open Bento Slides and use “Replace from JSON…” in its About dialog — or window.bento.loadDoc() from a script.')
      card.append(what)

      const pick = document.createElement('select')
      pick.className = 'sp-select'
      for (const { page, depth } of s.tree()) {
        const o = document.createElement('option')
        o.value = page.id
        o.textContent = `${'· '.repeat(depth)}${page.title || t('Untitled')}`
        if (page.id === s.pageId) o.selected = true
        pick.append(o)
      }
      const pageRow = el('div', 'sp-row')
      pageRow.append(el('span', '', t('Page')), pick)
      card.append(pageRow)

      const summary = document.createElement('p')
      summary.className = 'sp-note'
      const losses = document.createElement('ul')
      losses.className = 'sp-note'
      card.append(summary, losses)

      // Built from the REAL export, not described in the abstract — the same
      // choice openExportSpace makes, and for the same reason: the counts have
      // to move as the choice does or they are decoration.
      let out = pageToDeck(s.doc, pick.value)
      const recount = (): void => {
        out = pageToDeck(s.doc, pick.value)
        summary.textContent = t('{n} slide(s).', { n: out.slides })
        losses.textContent = ''
        if (!out.notes.length) return
        const head = document.createElement('li')
        head.textContent = t('What did not come across as it stands:')
        losses.append(head)
        for (const n of out.notes) {
          const li = document.createElement('li')
          li.textContent = n.n > 1 ? `${deckNoteText(n)} (×${n.n})` : deckNoteText(n)
          losses.append(li)
        }
      }
      pick.addEventListener('change', recount)
      recount()

      const name = (): string =>
        `${(s.doc.pages.find((p) => p.id === pick.value)?.title || 'deck').replace(/[^\w.-]+/g, '-')}.bento-slides.json`

      const copyB = plainBtn(t('Copy the deck JSON'), () => {
        navigator.clipboard?.writeText(JSON.stringify(deckForExport(out.doc), null, 2))
          .then(() => { copyB.textContent = t('Copied') })
          .catch(() => { copyB.textContent = t('Could not copy') })
          .finally(() => { setTimeout(() => { copyB.textContent = t('Copy the deck JSON') }, 1800) })
      })

      const acts = el('div', 'sp-actions')
      acts.append(
        plainBtn(t('Download the deck JSON'), () => {
          const blob = new Blob([JSON.stringify(deckForExport(out.doc), null, 2)], { type: 'application/json' })
          const a = document.createElement('a')
          a.href = URL.createObjectURL(blob)
          a.download = name()
          a.click()
          URL.revokeObjectURL(a.href)
          close()
          this.status(t('Exported {n} slide(s) as a deck', { n: out.slides }))
        }, true),
        copyB,
        plainBtn(t('Close'), close),
      )
      card.append(acts)
    })
  }

  /**
   * Import, in ONE undoable step.
   *
   * Everything slow or asynchronous — reading files, decoding and re-encoding
   * images, hashing them — happens BEFORE the commit, so the pages, the blocks
   * and the asset references land in one synchronous mutation. The same reason
   * `placeImage` is shaped this way: a half-applied import is not something a
   * single ⌘Z could put back.
   */
  async importFiles(picked: PickedFile[], opts: { under?: string } = {}): Promise<void> {
    const s = this.store
    if (s.readOnly) { this.notice(t('This file is open read-only')); return }
    const notes = picked.filter((p) => NOTE_EXT.test(p.path))
    if (!notes.length) {
      // A space is a legitimate thing to drop on the import, and it arrives by
      // the same gesture: one route in, whatever kind of notes they are.
      const space = picked.find((p) => SPACE_EXT.test(p.path))
      if (space) { await this.importSpace(space.file, opts.under); return }
      this.notice(t('No Markdown files in that selection'))
      return
    }
    if (notes.length > 500 &&
      !confirm(t('That is {n} files — importing them all may take a moment. Continue?', { n: notes.length }))) return

    this.status(t('Reading {n} file(s)…', { n: notes.length }))
    let files: SourceFile[]
    try {
      files = await Promise.all(notes.map(async (p) => ({ path: p.path, text: await p.file.text() })))
    } catch {
      this.notice(t('Those files could not be read'))
      return
    }

    // Pages this space already has, so an incremental import links INTO it —
    // BY EVERY NAME they answer to. `nameIndex` carries titles and aliases and
    // settles the ties, which is what makes `[[NYC]]` in an imported vault
    // land on the page already titled "New York": aliases have to reach the
    // resolver or they are an alias in name only.
    const existing = nameIndex(s.doc).byName
    // every id the space already uses, so a `{#id}` in a note never lands on
    // a second block (or a page) with the same id
    const usedIds = new Set<string>()
    for (const page of s.doc.pages) {
      usedIds.add(page.id)
      for (const b of page.blocks) usedIds.add(b.id)
    }
    const plan = planImport(files, {
      rootTitle: t('Imported notes'),
      resolveExisting: (target) => existing.get(target),
      // so an imported `[^1]` that would land on a note this space already has
      // is renamed, in the plan, along with the references to it
      existingNotes: s.doc.footnotes,
      idTaken: (id) => usedIds.has(id),
    })

    // ---- images ------------------------------------------------------------
    // A relative path in a .md file names a file on the author's disk, and a
    // browser cannot open it — no filesystem access, and the space will be
    // mailed away from that disk anyway. So it is resolved against what was
    // ACTUALLY selected, and when that fails the reference becomes visible
    // text instead of an <img> that can only ever be broken.
    const media = new Map<string, File>()
    const byName = new Map<string, File>()
    for (const p of picked) {
      if (NOTE_EXT.test(p.path)) continue
      const key = normPath(p.path)
      if (!media.has(key)) media.set(key, p.file)
      const name = key.slice(key.lastIndexOf('/') + 1)
      if (!byName.has(name)) byName.set(name, p.file)
    }

    let embedded = 0
    let embeddedBytes = 0
    let unresolved = 0
    let declined = 0
    let keepEmbedding = true
    let asked = false
    for (const img of plan.images) {
      const ref = decodePath(img.ref)
      const file = media.get(joinPath(img.dir, ref)) ?? byName.get(ref.slice(ref.lastIndexOf('/') + 1).toLowerCase())
      if (file && keepEmbedding && embeddedBytes > IMPORT_IMAGE_BUDGET && !asked) {
        asked = true
        keepEmbedding = confirm(t(
          'The images in these notes come to {size} so far, and they all travel inside the file. Keep embedding them?',
          { size: humanBytes(embeddedBytes) },
        ))
      }
      if (file && keepEmbedding) {
        try {
          const prepared = await prepareImage(file)
          img.block.src = await internAsset(s.doc, prepared.dataUri)
          if (prepared.w) { img.block.w = prepared.w; img.block.h = prepared.h }
          if (!prepared.original) img.block.original = false
          embedded++
          embeddedBytes += prepared.dataUri.length
          continue
        } catch { /* not a decodable image — fall through and say so */ }
      }
      // the two ways to arrive here are different facts, and the report says
      // which: we could not find/read it, or you asked us to stop
      if (file && !keepEmbedding) declined++
      else unresolved++
      img.block.type = 'p'
      delete img.block.src
      delete img.block.alt
      img.block.html = `<em>${escapeHtml(t('Image not imported'))}: </em><code>${escapeHtml(img.ref)}</code>`
    }

    // THE security gate. Everything above builds html from someone's files;
    // this is the app's real policy, with a real parser, run once over every
    // block before any of it reaches the document (see markdown.ts's header).
    for (const page of plan.pages) {
      for (const b of page.blocks) if (b.html) b.html = sanitizeInline(b.html)
    }
    // A NOTE IS INLINE HTML OUT OF SOMEBODY ELSE'S FILE and goes through the
    // same gate as a block's, in the same pass, for the same reason.
    for (const [label, body] of Object.entries(plan.footnotes)) {
      plan.footnotes[label] = sanitizeInline(body)
    }

    // The import already lands under exactly one root (planImport wraps a mixed
    // selection); re-homing that root is the whole of "add these under this
    // page", and it keeps the one-root, one-⌘Z shape intact.
    const under = opts.under && s.index.page.has(opts.under) ? opts.under : undefined
    if (under) {
      const arrived = new Set(plan.pages.map((p) => p.id))
      for (const page of plan.pages) if (!page.parent || !arrived.has(page.parent)) page.parent = under
    }

    // ONE commit, so ⌘Z takes the pages, their footnotes AND any design they
    // brought. A note's `design:` is already on ITS page (planImport); the
    // space's own design is never touched by an import — only the registry
    // entries the notes carried join it (designs.ts adoptDesign, called with no
    // space-level name).
    s.commit(() => {
      s.doc.pages.push(...plan.pages)
      // `plan.footnotes` STARTED from this document's own table and had the
      // imported notes merged into it, renaming collisions — so it is assigned
      // whole rather than spread over the existing one. Absent stays absent
      // when nothing has footnotes, so importing plain notes does not add an
      // empty key to the file.
      if (Object.keys(plan.footnotes).length) s.doc.footnotes = plan.footnotes
      adoptDesign(s.doc, undefined, plan.designs)
    })
    const designed = plan.pages.filter((p) => p.design !== undefined).length
    if (plan.pages[0]) s.goToPage(plan.pages[0].id)
    this.repaint()
    this.status(t('Imported'))

    this.openOverlay(t('Imported'), (card, close) => {
      const lines: string[] = [
        t('{pages} page(s) and {blocks} block(s) added from {files} file(s).',
          { pages: plan.stats.pages, blocks: plan.stats.blocks, files: plan.stats.files }),
      ]
      if (plan.stats.linked || plan.stats.dangling) {
        lines.push(t('{n} of {total} wikilink(s) resolved.',
          { n: plan.stats.linked, total: plan.stats.linked + plan.stats.dangling }))
        // two sentences, not one: "1 of 1 resolved, the rest are text" is a
        // sentence about nothing
        if (plan.stats.dangling) lines.push(t('The rest name notes that were not in the selection, and are left as text.'))
      }
      // A shared NAME is the one import outcome the reader cannot see for
      // themselves: the links look fine and point at the wrong note.
      if (plan.stats.duplicateNames) {
        lines.push(t('{n} note name(s) appear more than once, so links naming them all went to the first.',
          { n: plan.stats.duplicateNames }))
      }
      if (designed) lines.push(t('{n} page(s) arrived with a design of their own.', { n: designed }))
      if (plan.stats.frontmatter) {
        lines.push(t('{n} page(s) had frontmatter, kept verbatim in a folded block.', { n: plan.stats.frontmatter }))
      }
      if (plan.stats.tables) {
        lines.push(t('{n} table(s) imported, with their column alignment.', { n: plan.stats.tables }))
      }
      if (embedded) lines.push(t('{n} image(s) embedded ({size}).', { n: embedded, size: humanBytes(embeddedBytes) }))
      if (unresolved) {
        lines.push(t('{n} image(s) could not be opened, so their paths are kept as text. Import again with the image files included.', { n: unresolved }))
      }
      if (declined) {
        lines.push(t('{n} image(s) were left as paths because embedding stopped there.', { n: declined }))
      }
      if (plan.stats.remoteImages) {
        lines.push(t('{n} image(s) point at the web. Nothing loads until a reader asks.', { n: plan.stats.remoteImages }))
      }
      // "removes the pages", NOT "puts the space back exactly as it was".
      // Measured: after ⌘Z the pages are byte-identical to before, but the
      // image bytes stay — undo snapshots deliberately exclude `assets`
      // (store.ts), and pruning them on undo would break REDO, which
      // re-inserts blocks pointing at those very keys.
      lines.push(t('⌘Z removes the imported pages again.'))
      for (const line of lines) {
        const p = document.createElement('p')
        p.className = 'sp-note'
        p.textContent = line
        card.append(p)
      }
      card.append(plainBtn(t('Close'), close, true))
    })
  }

  // ---- find and replace ----------------------------------------------------
  /**
   * ⌘F is OURS, not the browser's.
   *
   * Native find cannot see a collapsed toggle's body, cannot see a page that is
   * not currently rendered, and cannot see an archived page at all — which is
   * most of a space. So this searches the MODEL, jumps to each hit, expands
   * whatever was folded around it, and can replace across every page in one
   * undoable step.
   */
  openFind(): void {
    const s = this.store
    document.querySelector('.sp-findbar')?.remove()
    const bar = el('div', 'sp-findbar')
    bar.setAttribute('role', 'search')

    const q = document.createElement('input')
    q.className = 'sp-find'
    q.placeholder = t('Find in this space…')
    q.setAttribute('aria-label', t('Find'))

    const rep = document.createElement('input')
    rep.className = 'sp-find'
    rep.placeholder = t('Replace with…')
    rep.setAttribute('aria-label', t('Replace with'))

    const count = el('span', 'sp-findcount')
    const mk = (icon: IconName, label: string, fn: () => void) => {
      const b = document.createElement('button')
      b.className = 'sp-btn'
      b.type = 'button'
      b.innerHTML = ICONS[icon]
      b.title = label
      b.setAttribute('aria-label', label)
      b.addEventListener('click', fn)
      return b
    }

    // ONE ENTRY PER OCCURRENCE, not per block. The readout, the stepper and the
    // replace-all confirmation then all quote the same number — and it is the
    // number of things that will actually change, because it comes from the
    // routine that changes them (countOutsideTags / replaceOutsideTags share
    // mapTextChunks). Counting blocks meant "2 found" above a dialog offering
    // to replace 2, which then replaced 4.
    let hits: Array<{ pageId: string; blockId: string }> = []
    let at = -1

    const scan = () => {
      const needle = q.value
      hits = []
      at = -1
      if (needle) {
        for (const p of s.doc.pages) {
          for (const b of p.blocks) {
            const n = countOutsideTags(b.html, needle)
            for (let i = 0; i < n; i++) hits.push({ pageId: p.id, blockId: b.id })
          }
        }
      }
      count.textContent = hits.length ? t('{n} found', { n: hits.length }) : (needle ? t('none') : '')
    }

    const jump = (dir: 1 | -1) => {
      if (!hits.length) return
      at = (at + dir + hits.length) % hits.length
      const hit = hits[at]
      count.textContent = t('{i} of {n}', { i: at + 1, n: hits.length })

      // Unfold FIRST, then navigate — one paint, and no dependence on when a
      // repaint happens to land. Doing it the other way round meant reveal ran
      // against whichever page the store had reached by the next frame, and
      // the fold stayed shut.
      const opened = this.revealBlock(hit.pageId, hit.blockId)
      if (hit.pageId !== s.pageId) s.goToPage(hit.pageId)
      else if (opened) this.paintPage()

      afterPaint(() => {
        const node = this.main.querySelector<HTMLElement>(`[data-block-id="${CSS.escape(hit.blockId)}"]`)
        node?.scrollIntoView({ block: 'center', behavior: 'smooth' })
        // two occurrences in one block are two stops: restart the flash, or
        // the second step looks like the stepper did nothing
        node?.classList.remove('sp-hit')
        void node?.offsetWidth
        node?.classList.add('sp-hit')
        setTimeout(() => node?.classList.remove('sp-hit'), 1400)
      })
    }

    const replaceAll = () => {
      const needle = q.value
      if (!needle || !hits.length) return
      if (!confirm(t('Replace {n} occurrence(s) across the whole space?', { n: hits.length }))) return
      // ONE commit for the whole sweep: a replace-all a user has to undo forty
      // times is not undoable in any sense they care about
      s.commit(() => {
        for (const p of s.doc.pages) {
          for (const b of p.blocks) {
            if (!countOutsideTags(b.html, needle)) continue
            b.html = replaceOutsideTags(b.html!, needle, rep.value)
          }
        }
      })
      this.repaint()
      scan()
      this.status(t('Replaced'))
    }

    q.addEventListener('input', scan)
    q.addEventListener('keydown', (e) => {
      if (e.key === 'Enter') { e.preventDefault(); jump(e.shiftKey ? -1 : 1) }
      if (e.key === 'Escape') { e.preventDefault(); bar.remove() }
    })
    rep.addEventListener('keydown', (e) => { if (e.key === 'Escape') bar.remove() })

    bar.append(q, mk('arrowUp', t('Previous (⇧⏎)'), () => jump(-1)),
      mk('arrowDown', t('Next (⏎)'), () => jump(1)), count,
      rep, mk('replace', t('Replace all'), replaceAll),
      mk('close', t('Close'), () => bar.remove()))
    this.root.append(bar)
    q.focus()
    scan()
  }

  /**
   * Open every toggle between a block and the top of its page, so a hit is
   * actually visible when we arrive at it.
   *
   * Takes the page id EXPLICITLY rather than reading the current page: the
   * caller may not have navigated yet, and depending on that ordering is what
   * broke this the first time. Returns whether anything changed, so the caller
   * can decide whether a repaint is owed.
   */
  private revealBlock(pageId: string, blockId: string): boolean {
    const s = this.store
    const page = s.index.page.get(pageId)
    if (!page) return false
    let changed = false
    let cur = page.blocks.find((b) => b.id === blockId)
    const guard = new Set<string>()
    while (cur?.parent && !guard.has(cur.parent)) {
      guard.add(cur.parent)
      const owner = page.blocks.find((b) => b.id === cur!.parent)
      if (!owner) break
      // ANY fold, from the registry — not a `type === 'toggle'` test. The
      // merge commit claimed containers were registry data; this one survived,
      // latent only because toggle is the sole 'fold' today. A ⌘K or ⌘F hit
      // inside the second fold type would land on a block nobody could see.
      if (SPEC.get(owner.type)?.container === 'fold' && !owner.open) { owner.open = true; changed = true }
      cur = owner
    }
    // a fold opened to show a search hit is a VIEW change, not an edit: it is
    // mutated directly rather than through commit(), so searching never lands
    // on the undo stack or marks the document modified
    return changed
  }

  // ---- print ---------------------------------------------------------------
  /**
   * Printing is the ONLY export-to-PDF path, so it is a contract rather than a
   * stylesheet: what goes in, in what order, and what happens to the things a
   * screen can hide.
   *
   * Collapsed toggles print EXPANDED, always. Silently omitting content from a
   * printed handbook is a data-loss-shaped bug — the reader has no way to know
   * a paragraph was folded away.
   */
  openPrint(): void {
    const s = this.store
    this.openOverlay(t('Print or save as PDF'), (card, close) => {

      const scope = document.createElement('div')
      scope.className = 'sp-choices'
      let whole = true
      const choice = (label: string, hint: string, on: boolean, pick: () => void) => {
        const b = document.createElement('button')
        b.className = 'sp-choice' + (on ? ' sp-sel' : '')
        b.type = 'button'
        b.innerHTML = `<strong>${escapeHtml(label)}</strong><span>${escapeHtml(hint)}</span>`
        b.addEventListener('click', () => {
          pick()
          for (const o of scope.querySelectorAll('.sp-choice')) o.classList.remove('sp-sel')
          b.classList.add('sp-sel')
        })
        return b
      }
      const pageCount = s.doc.pages.filter((p) => !p.archived).length
      scope.append(
        choice(t('The whole space'), t('{n} pages, in sidebar order, with a contents page', { n: pageCount }), true, () => { whole = true }),
        choice(t('This page only'), s.page?.title || t('Untitled'), false, () => { whole = false }),
      )
      card.append(scope)

      const opts = document.createElement('div')
      opts.className = 'sp-optlist'
      const check = (label: string, hint: string, on: boolean) => {
        const l = document.createElement('label')
        l.className = 'sp-opt'
        const i = document.createElement('input')
        i.type = 'checkbox'
        i.checked = on
        l.append(i, Object.assign(document.createElement('span'), {
          innerHTML: `<strong>${escapeHtml(label)}</strong><span>${escapeHtml(hint)}</span>`,
        }))
        opts.append(l)
        return i
      }
      const wantArchived = check(t('Include archived pages'), t('Off by default — they were archived for a reason'), false)
      const wantContents = check(t('Contents page'), t('A list of every page, in order'), true)
      card.append(opts)

      const note = document.createElement('p')
      note.className = 'sp-note'
      note.textContent = t('Collapsed toggles always print open. Your browser\'s print dialog has the "Save as PDF" option.')
      card.append(note)

      const go = document.createElement('button')
      go.className = 'sp-btn sp-primary'
      go.textContent = t('Print…')
      go.addEventListener('click', () => {
        close()
        this.printNow({ whole, archived: wantArchived.checked, contents: wantContents.checked })
      })
      card.append(go)
    })
  }

  /**
   * Build a print-only rendering, print it, and take it away again.
   *
   * The screen shows ONE page; print needs all of them, so this renders a
   * separate tree rather than trying to make the editor's DOM serve both. It
   * is removed in `afterprint`, so nothing about the editor is left changed.
   */
  private printNow(opts: { whole: boolean; archived: boolean; contents: boolean }): void {
    const s = this.store
    const host = el('div', 'sp-printroot')
    host.style.direction = 'ltr'
    // EACH PAGE PRINTS IN ITS OWN DESIGN, in its LIGHT palette (the dark
    // mapping is @media screen, so paper never matches it). The ROOT carries
    // NONE: renderPage stamps every page root with its own resolved design,
    // and a design on the root would reach any page that has none of its own
    // (designs.css matches by ancestor). The contents list is the space's, so
    // it wears the space's design.
    applyDesign(host, s.doc, null)

    const pages = opts.whole
      ? s.tree().map((n) => n.page).filter((p) => opts.archived || !p.archived)
      : (s.page ? [s.page] : [])

    if (opts.whole && opts.contents) {
      const toc = el('section', 'sp-toc')
      toc.append(el('h1', 'sp-toc-h', s.doc.title || t('Contents')))
      const ul = el('ul', 'sp-toc-list')
      for (const { page, depth } of s.tree()) {
        if (!opts.archived && page.archived) continue
        const li = document.createElement('li')
        li.style.paddingInlineStart = `${depth * 16}px`
        li.textContent = page.title || t('Untitled')
        ul.append(li)
      }
      toc.append(ul)
      applyDesign(toc, s.doc, resolveDesign(s.doc))
      host.append(toc)
    }

    for (const page of pages) {
      host.append(renderPage(page, s.doc, {
        editable: false, forceOpen: true, printing: true,
        titleOf: (id) => s.index.page.get(id)?.title,
        allowRemote: (src) => this.allowedRemote.has(src),
      }))
    }

    document.body.append(host)
    document.body.classList.add('sp-printing')
    const cleanup = () => {
      host.remove()
      document.body.classList.remove('sp-printing')
      window.removeEventListener('afterprint', cleanup)
    }
    window.addEventListener('afterprint', cleanup)
    // some engines return from print() before afterprint fires
    setTimeout(() => { if (document.body.contains(host)) cleanup() }, 60000)
    print()
  }

  private exportMarkdown(): void {
    this.onSaveAs?.('__markdown')
  }

  private async saveAs(suffix: string): Promise<void> {
    this.onSaveAs?.(suffix)
  }

  /**
   * Save a copy that carries a SCOPED capability — the two ways to let someone
   * into this space.
   *
   * Both go live first, because a copy that follows a session needs there to
   * be one, and because "share" should be one action rather than a session to
   * start and then a file to send.
   *
   * Both also write a DERIVED document (share.ts), never `store.doc`. That is
   * the whole of the fix: `saveAs('copy')` serializes the open document, so
   * inviting somebody used to hand them `collab.ownerPriv` — the root key of
   * the room, which writes AND revokes, the inviter included.
   */
  private async shareCopy(kind: import('./share.ts').ShareKind): Promise<void> {
    // A READING COPY IS SEALED, so it must not go live first — that is the one
    // thing the other two branches do that would be wrong here. Going live on
    // the way out would arm this space's session for a file that carries none
    // of its keys, which is a session nobody asked for.
    if (kind === 'reading') { await this.saveReadingCopy(); return }
    // An invite KEEPS the space's version history (the kernel's invite rule),
    // and history remembers text that was deleted. So when there is any, the
    // inviter is told before the copy is made and may leave it out. A space
    // with no history gets no extra step — nothing to disclose.
    let withHistory = true
    if (kind === 'invite' && shareModule.hasHistory(this.store.doc)) {
      const choice = await this.confirmInviteHistory()
      if (choice === null) return
      withHistory = choice
    }
    await this.goLive()
    // Committed first for the same reason slides commits its text edit: a
    // half-typed block that only exists in the DOM is not in the copy.
    this.store.endRun()
    // Copies rejoin as true FORKS: the stamped CRDT state is what lets an
    // offline edit on either side merge two-way rather than clobber.
    // (readerCopy clears it again — a viewer is not a fork.)
    shareModule.stampSync(this.store, this.session)
    const out = kind === 'invite'
      ? await shareModule.inviteCopy(this.store.doc, { withHistory })
      : shareModule.readerCopy(this.store.doc)
    if (!out) {
      this.notice(kind === 'invite'
        ? t('Only the owner of this space can invite people')
        : t('This space has no live session to follow'))
      return
    }
    const ok = await this.onShareCopy?.(out, kind)
    if (ok) {
      this.notice(kind === 'invite'
        ? t('Editor copy saved — recipients join live with edit access')
        : t('Read-only copy saved — it follows the live session, view only'))
    }
  }

  /**
   * The one step before an invite of a space that has history: say that the
   * copy carries it, and offer to leave it out (default: include). Resolves
   * true = include, false = leave out, null = cancelled. A kernel dialog via
   * openOverlay; the Save button is the user gesture the file picker needs.
   */
  private confirmInviteHistory(): Promise<boolean | null> {
    return new Promise((resolve) => {
      let answered = false
      const done = (v: boolean | null) => { if (!answered) { answered = true; resolve(v) } }
      const d = this.openOverlay(t('Invite to edit…').replace(/…$/, ''), (body, close) => {
        body.append(el('p', 'sp-note', t('This copy includes the space’s version history.')))
        const label = el('label', 'sp-ab-check')
        const cb = el('input', 'sp-invite-leaveout')
        cb.type = 'checkbox'
        label.append(cb, document.createTextNode(' ' + t('Leave version history out')))
        label.title = t('Versions include text that was deleted. This file keeps them either way.')
        body.append(label)
        const acts = el('div', 'sp-actions sp-dlg-actions')
        const cancel = el('button', 'sp-btn', t('Cancel'))
        cancel.type = 'button'
        cancel.addEventListener('click', () => { done(null); close() })
        const go = el('button', 'sp-btn sp-primary', t('Save invite…'))
        go.type = 'button'
        go.addEventListener('click', () => { done(!cb.checked); close() })
        acts.append(cancel, go)
        body.append(acts)
        queueMicrotask(() => go.focus())
      })
      d.card.classList.add('sp-dlg-narrow')
      // Escape, the scrim or another overlay: closing without an answer is a
      // cancel. closeOverlay() runs overlayOff on every close path.
      this.overlayOff.push(() => done(null))
    })
  }

  /**
   * Save a copy for somebody who is only going to read it.
   *
   * A DERIVED document (reading.ts, the kernel's `package` tier), never
   * `store.doc`: the whole point is what the copy does not contain — no
   * collaboration credentials at all, no history and no comment threads. What
   * it DOES keep is the space itself, so the recipient gets the pages, the
   * search and the tree, and no editing tools. No sync stamp either: the copy
   * carries no collab block to stamp into.
   */
  private async saveReadingCopy(): Promise<void> {
    // Committed first for the same reason the share copies commit: a half-typed
    // block that only exists in the DOM is not in the copy.
    this.store.endRun()
    const out = readingCopy(this.store.doc)
    const ok = await this.onShareCopy?.(out, 'reading')
    if (ok) this.notice(t('Reading copy saved — it opens as a document, with no keys and no comments'))
  }

  /** Turn the live session on (idempotent). Sharing a copy calls this first. */
  async goLive(): Promise<void> {
    if (!this.session || offlineEnabled()) return
    this.session.enableSharing()
    await startSharing(this.session, this.store)
    // A transport made just now is a NEW object with its own callback slot —
    // the one the boot-time watch was attached to no longer exists.
    this.collab?.watchStatus()
    this.collab?.sync()
  }

  /** About: what the app is, whether it is current, and the viewer's preferences. */
  private openAbout(runCheck = false): void {
    openAbout({
      store: this.store,
      onRepaint: () => this.build(),
      onStatus: (msg) => this.notice(msg),
      runCheck,
      onUpdateInPlace: (rel) => this.onUpdateInPlace?.(rel) ?? Promise.resolve(null),
      // both self-update writes carry this space's CRDT state, as ⌘S does
      onBeforeWrite: () => shareModule.stampSync(this.store, this.session),
      previewDesign: (pv) => this.previewDesign(pv),
      openDesignPanel: () => openDesignPanel(this.store, (pv) => this.previewDesign(pv)),
    })
  }

  /** What the Save menu's rows reach (doccmds.ts). One copy path: saveAs('copy'). */
  private docHost(): DocHost {
    return {
      store: this.store,
      openOverlay: (title, build, o) => this.openOverlay(title, build, o),
      repaint: () => this.repaint(),
      notice: (msg) => this.notice(msg),
      saveCopy: () => { void this.saveAs('copy') },
      exportMarkdown: () => this.exportMarkdown(),
      exportSpace: () => this.openExportSpace(),
      // "Duplicate as new space…" writes a DIFFERENT document, so it takes
      // the extract's writer rather than the copy path: that one keeps no file
      // handle, which is what leaves you editing this space afterwards.
      writeCopy: (out) => this.onExportSpace?.(out) ?? Promise.resolve(false),
      importMarkdown: () => this.openImport(),
      moreExports: (m) => {
        // THE PAGE IN VIEW as one note — the unit the importer reads back as
        // one page, so a page's own design (`design:`) round-trips with it
        const pageId = this.store.page?.id
        row(m, { icon: ICONS.markdown, label: t('Export page as Markdown…'), desc: t('This page as one .md note'),
          off: !pageId, run: () => { if (pageId) downloadMarkdown(this.store, pageId) } })
        row(m, { icon: ICONS.canvas, label: t('Export page as slides…'),
          desc: t('The page as a bento/slides deck, ready to paste into Bento Slides'), run: () => this.openExportDeck() })
      },
    }
  }

  /** The pages you can add — the page list's + ▾, in shortcut order. */
  private pageRows(m: Menu): void {
    row(m, { icon: ICONS.page, label: t('New page'), kbd: keys('alt', 'mod', 'N'), run: () => this.newPage() })
    row(m, { icon: ICONS.book, label: t("Today's journal"), kbd: keys('shift', 'mod', 'J'), run: () => this.openJournal() })
    row(m, { icon: ICONS.board, label: t('New issue'), kbd: keys('shift', 'mod', 'I'), run: () => this.newIssue() })
    row(m, { icon: ICONS.copy, label: t('Templates…'), run: () => openTemplates(this.templateHost) })
  }

  private updateVersion: string | null = null
  private updateChip: HTMLButtonElement | null = null

  /** The launch check found `version`: show slides' chip, and say so once (D3). */
  updateFound(version: string): void {
    this.updateVersion = version
    if (this.updateChip) { this.updateChip.hidden = false; this.paintUpdateChip(this.updateChip, version) }
    this.notice(t('Update available: v{v} — click the peach button to update', { v: version }))
  }

  private paintUpdateChip(b: HTMLButtonElement, version: string): void {
    b.innerHTML = `${ICONS.sync}<span>v${escapeHtml(version)}</span>`
    b.title = t('Version {v} is available — click to update', { v: version })
    b.setAttribute('aria-label', b.title)
  }

  // ---- routing ------------------------------------------------------------
  /**
   * `#p/<page>` today, and `#p/<page>/<block>` tolerated for later.
   *
   * The allowlist in sanitize.ts already ADMITS the two-segment form (its
   * pattern is `#p/`), so links of that shape can be written into a file right
   * now — and this resolver silently did nothing with them: `index.page.has`
   * failed on the whole string and the click did not even fall back to the
   * page. Every block link written by any future build would be dead in every
   * file saved before that build existed.
   *
   * Tolerance costs three lines and cannot be added later on the sender's
   * behalf: sanitize.ts records why a NEW fragment form is a one-way hazard —
   * an href written under a permissive build gets STRIPPED by a stricter one on
   * the next edit that touches the block. So it is accepted now and addressed
   * (scrolling to the block) whenever that ships.
   *
   * Prefer the WHOLE remainder as a page id: minted ids never contain a slash,
   * but an author-supplied one may.
   */
  private resolveAnchor(hash: string): string | null {
    const m = hash.match(/^#p\/(.+)$/)
    if (!m) return null
    const whole = m[1]
    if (this.store.index.page.has(whole)) return whole
    const cut = whole.lastIndexOf('/')
    if (cut > 0) {
      const page = whole.slice(0, cut)
      if (this.store.index.page.has(page)) return page
    }
    return null
  }

  private fromHash(): void {
    const id = this.resolveAnchor(location.hash)
    if (id) this.store.goToPage(id, { push: false })
  }

  repaint(): void { this.paintTree(); this.paintPage() }
}

/**
 * The mark a keystroke means, or null.
 *
 * ⌘B/⌘I/⌘U/⇧⌘S/⌘E/⇧⌘H, which is Notion's set — the only set most people who
 * will ever type them already have in their fingers. ⌘K is not here because it
 * is two commands (see onKey).
 *
 * `e.key` and not `e.code`: on a non-QWERTY layout the letter the person is
 * looking at is the one they mean, and ⌘B has to be the key marked B.
 */
function markKey(e: KeyboardEvent, mod: boolean): MarkTag | null {
  if (!mod || e.altKey) return null
  const k = e.key.toLowerCase()
  if (e.shiftKey) return k === 's' ? 's' : k === 'h' ? 'mark' : null
  return k === 'b' ? 'strong' : k === 'i' ? 'em' : k === 'u' ? 'u' : k === 'e' ? 'code' : null
}

// ---- small dom helpers ------------------------------------------------------
function el<K extends keyof HTMLElementTagNameMap>(tag: K, cls: string, text?: string): HTMLElementTagNameMap[K] {
  const n = document.createElement(tag)
  n.className = cls
  if (text) n.textContent = text
  return n
}

/**
 * Is a bare keystroke going to land in something the reader is writing in?
 *
 * The block hosts are contenteditable, the topbar title and the panel's own
 * fields are inputs, and every one of them takes `]` as a character. A
 * bare-key panel shortcut has to ask this first.
 */
function isTyping(): boolean {
  const a = document.activeElement as HTMLElement | null
  if (!a) return false
  return a.isContentEditable || a.tagName === 'INPUT' || a.tagName === 'TEXTAREA' || a.tagName === 'SELECT'
}

/**
 * A bar button with its word — slides' `btn(icon, label, run, title)`: the
 * label is a span the compact tier hides, the tooltip is the name a screen
 * reader hears once it has.
 */
function labelBtn(icon: string, label: string, tip: string, onClick: () => void): HTMLButtonElement {
  const b = document.createElement('button')
  b.className = 'sp-btn'
  b.type = 'button'
  b.innerHTML = icon
  const l = document.createElement('span')
  l.className = 'sp-btnlabel'
  l.textContent = label
  b.append(l)
  b.title = tip
  b.setAttribute('aria-label', tip)
  b.addEventListener('click', onClick)
  return b
}

function iconBtn(name: IconName, label: string, onClick: () => void): HTMLButtonElement {
  const b = document.createElement('button')
  b.className = 'sp-btn'
  b.type = 'button'
  b.innerHTML = ICONS[name]
  b.title = label
  b.setAttribute('aria-label', label)
  b.addEventListener('click', onClick)
  return b
}

const escapeHtml = (s: string): string =>
  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')

/** Type text at the caret, through the engine, so the caret and `input` follow. */
const insertText = (s: string): void => { document.execCommand('insertText', false, s) }

/** Where the caret is inside a host, as a character offset. Null if it is not. */
function caretIndexIn(host: HTMLElement): number | null {
  const sel = getSelection()
  if (!sel || !sel.rangeCount) return null
  const r = sel.getRangeAt(0)
  if (!r.collapsed || !host.contains(r.startContainer)) return null
  const probe = r.cloneRange()
  probe.selectNodeContents(host)
  probe.setEnd(r.startContainer, r.startOffset)
  return probe.toString().length
}

function plainBtn(label: string, onClick: () => void, primary = false): HTMLButtonElement {
  const b = document.createElement('button')
  b.className = 'sp-btn' + (primary ? ' sp-primary' : '')
  b.type = 'button'
  b.textContent = label
  b.addEventListener('click', onClick)
  return b
}

/**
 * One `DeckNote` in the reader's own language.
 *
 * A SWITCH OF LITERALS, deliberately, and not `t(TEXT[code])`. The i18n
 * extractor sweeps `t()` calls whose argument is a LITERAL STRING out of the
 * source; a lookup table would compile, run, report 100% coverage in the
 * packer, and ship English in all eight locales — which has already happened
 * once in this app, to the block menu labels. The document's own copy of these
 * sentences lives in todeck.ts and is deliberately English: a saved artefact's
 * words are its author's, not its next reader's browser's.
 */
function deckNoteText(n: DeckNote): string {
  const code: DeckNoteCode = n.code
  switch (code) {
    case 'image-remote': return t('A picture that lives on the web was left out — a deck never fetches.')
    case 'media-remote': return t('A clip that lives on the web was left out — a deck never fetches.')
    case 'media-embedded': return t('A clip travelled as embedded bytes, so the deck is large.')
    case 'link-flattened': return t('A link kept its words; a slide has nowhere to put the address.')
    case 'pagelink': return t('A card that opened another page became its title.')
    case 'toggle-open': return t('A fold is shown open — a slide cannot fold.')
    case 'callout-plain': return t('A callout kept its words and its kind, in a plain panel.')
    case 'canvas-flattened': return t('A canvas became a slide; the card sizes were chosen here.')
    case 'table-split': return t('A table was too tall for one slide and continues on the next.')
    case 'view-derived': return t('A board became a table of the rows it stood for.')
    case 'unknown-block': return t('A block this build does not know became its text.')
    case 'empty-block': return t('A block with nothing in it was left out.')
    case 'rtl': return t('This space reads right-to-left; a deck has no such setting.')
    case 'comments': return t('Review comments stayed behind, on purpose.')
    case 'icon-glyph': return t('The page’s icon is one of this app’s own glyphs, not an emoji, and did not travel.')
  }
}

// ---- dropped files ----------------------------------------------------------

const normPath = (p: string): string =>
  p.replace(/\\/g, '/').replace(/^\.?\//, '').replace(/\/+/g, '/').toLowerCase()

/** `dir` + a relative reference, with `..` and `.` collapsed. Lowercased: the
 *  case in a markdown link and the case on disk disagree often enough that
 *  matching exactly would fail for reasons nobody could see. */
function joinPath(dir: string, ref: string): string {
  const parts = (ref.startsWith('/') ? ref.slice(1) : `${dir}/${ref}`).split('/')
  const out: string[] = []
  for (const seg of parts) {
    if (!seg || seg === '.') continue
    if (seg === '..') out.pop()
    else out.push(seg)
  }
  return out.join('/').toLowerCase()
}

/**
 * The `#bento-doc` payload inside another Bento file.
 *
 * INERT: `DOMParser` builds a document with no browsing context, so nothing in
 * that html runs and nothing it references is fetched — the same reasoning
 * sanitize.ts records for `inertBody`, and the reason the file can be read
 * before anyone has decided to trust it. A bare `{` is the document JSON
 * itself (the AI round-trip's interchange unit), which needs no parse at all.
 *
 * An ENCRYPTED space is reported rather than guessed at: the bytes are there,
 * the password is not, and asking for one here would be asking for a password
 * to a file this space has no business holding.
 */
function spaceBlockOf(text: string): string | null | 'encrypted' {
  const body = /^\s*\{/.test(text)
    ? text
    : new DOMParser().parseFromString(text, 'text/html')
      .getElementById('bento-doc')?.textContent ?? null
  if (!body) return null
  return parseEnvelope(body) ? 'encrypted' : body
}

/** `my%20photo.png` is one file name, not two — editors percent-encode spaces. */
function decodePath(ref: string): string {
  try { return decodeURI(ref) } catch { return ref }
}

/**
 * Everything under a drop, including whole folders.
 *
 * `dataTransfer.items` is EMPTIED the moment this handler yields, so every
 * entry is taken synchronously and only then walked. `dataTransfer.files`
 * carries a dropped folder as one nameless entry, which is why the entry API
 * is used at all: without it, dragging a vault onto the window does nothing.
 */
async function collectDrop(dt: DataTransfer | null): Promise<PickedFile[]> {
  if (!dt) return []
  const entries = [...dt.items].map((i) => i.webkitGetAsEntry?.() ?? null).filter(Boolean) as FileSystemEntry[]
  // the fallback takes its path the same way the picker does, so the two
  // routes into importFiles cannot disagree about where a path comes from
  if (!entries.length) return [...dt.files].map((file) => ({ path: file.webkitRelativePath || file.name, file }))
  const out: PickedFile[] = []
  for (const entry of entries) await walkEntry(entry, '', out, 0)
  return out
}

async function walkEntry(entry: FileSystemEntry, base: string, out: PickedFile[], depth: number): Promise<void> {
  // .obsidian, .git, .trash: configuration and deleted notes, never the notes
  // someone means to import
  if (entry.name.startsWith('.')) return
  const path = base ? `${base}/${entry.name}` : entry.name
  if (entry.isFile) {
    const file = await new Promise<File | null>((res) =>
      (entry as FileSystemFileEntry).file(res, () => res(null)))
    if (file) out.push({ path, file })
    return
  }
  if (depth > 12) return   // a symlink loop is not worth hanging the tab for
  const reader = (entry as FileSystemDirectoryEntry).createReader()
  for (;;) {
    // readEntries hands back at most 100 at a time and signals the end with an
    // empty batch — reading it once silently truncates a folder of 300 notes
    const batch = await new Promise<FileSystemEntry[]>((res) =>
      reader.readEntries(res, () => res([])))
    if (!batch.length) break
    for (const child of batch) await walkEntry(child, path, out, depth + 1)
  }
}

/** Is this drop an IMPORT (markdown, or any folder) rather than an image? */
function isImportDrop(dt: DataTransfer | null): boolean {
  if (!dt) return false
  if ([...dt.files].some((f) => NOTE_EXT.test(f.name) || SPACE_EXT.test(f.name))) return true
  return [...dt.items].some((i) => i.webkitGetAsEntry?.()?.isDirectory)
}

function atStart(host: HTMLElement): boolean {
  const sel = getSelection()
  if (!sel || !sel.rangeCount) return false
  const r = sel.getRangeAt(0)
  if (!r.collapsed) return false
  const probe = r.cloneRange()
  probe.selectNodeContents(host)
  probe.setEnd(r.startContainer, r.startOffset)
  return probe.toString().length === 0
}

function caretToEnd(host: HTMLElement): void {
  const r = document.createRange()
  r.selectNodeContents(host)
  r.collapse(false)
  const sel = getSelection()
  sel?.removeAllRanges()
  sel?.addRange(r)
}

function caretToOffset(host: HTMLElement, offset: number): void {
  const walker = document.createTreeWalker(host, NodeFilter.SHOW_TEXT)
  let seen = 0
  let node: Node | null
  while ((node = walker.nextNode())) {
    const len = node.textContent?.length ?? 0
    if (seen + len >= offset) {
      const r = document.createRange()
      r.setStart(node, offset - seen)
      r.collapse(true)
      const sel = getSelection()
      sel?.removeAllRanges()
      sel?.addRange(r)
      return
    }
    seen += len
  }
  caretToEnd(host)
}

function selectAll(host: HTMLElement): void {
  const r = document.createRange()
  r.selectNodeContents(host)
  const sel = getSelection()
  sel?.removeAllRanges()
  sel?.addRange(r)
}

/** Split a block's html at the caret, returning [before, after]. */
function splitAtCaret(host: HTMLElement): [string, string] {
  const sel = getSelection()
  if (!sel || !sel.rangeCount) return [host.innerHTML, '']
  const r = sel.getRangeAt(0)
  const after = r.cloneRange()
  after.selectNodeContents(host)
  after.setStart(r.endContainer, r.endOffset)
  const tail = after.cloneContents()
  const before = r.cloneRange()
  before.selectNodeContents(host)
  before.setEnd(r.startContainer, r.startOffset)
  const head = before.cloneContents()
  const wrap = (f: DocumentFragment) => { const d = document.createElement('div'); d.append(f); return d.innerHTML }
  return [sanitizeInline(wrap(head)), sanitizeInline(wrap(tail))]
}

/** Where the caret is, in viewport coordinates. */
function caretRect(): DOMRect {
  const sel = getSelection()
  if (sel && sel.rangeCount) {
    const r = sel.getRangeAt(0).getBoundingClientRect()
    if (r.width || r.height || r.top) return r
  }
  return new DOMRect(80, 120, 0, 0)
}

/**
 * Place a popover near an anchor without letting it leave the viewport.
 *
 * THE HEIGHT IS THE ROOM IT ACTUALLY HAS, not a fraction of the window. The
 * CSS capped every popover at 44vh, which on a 900px-tall window is 396px —
 * and the share panel wants 543. Measured before this: 149px clipped, with
 * "Go live" and "Reset access…" both below the fold. The primary
 * action of the sharing panel was reachable only by noticing that a box with
 * no visible scrollbar scrolls. A laptop at 800px fares worse.
 *
 * So the cap is computed per placement: pick the side with more room, give the
 * popover that room, and only then measure to position it. The floor is 160px
 * because a popover squeezed under a control near the bottom edge should flip
 * rather than become a slot.
 */
function place(pop: HTMLElement, anchor: HTMLElement | DOMRect): void {
  const r = anchor instanceof HTMLElement ? anchor.getBoundingClientRect() : anchor
  // 4px off the anchor: slides' `.ed-menu` offset, which every popover here
  // now shares with the menus (the kernel's default is 6)
  const GAP = 4, EDGE = 8
  const below = innerHeight - r.bottom - GAP - EDGE
  const above = r.top - GAP - EDGE
  const useBelow = below >= above || below >= 320
  pop.style.maxHeight = `${Math.max(160, useBelow ? below : above)}px`
  // measured AFTER the cap, so a flip decides on the height the popover will
  // actually have rather than the one CSS would have forced on it
  const w = pop.offsetWidth || 260
  const h = pop.offsetHeight || 260
  // a popover hanging off a control at the bar's END grows inward and lines up
  // with it, as slides' share popover does (`inset-inline-end: 0`)
  let left = pop.classList.contains('sp-pop-end') ? r.right - w : r.left
  if (left + w > innerWidth - EDGE) left = Math.max(EDGE, innerWidth - w - EDGE)
  pop.style.left = `${Math.max(EDGE, left)}px`
  pop.style.top = `${useBelow ? r.bottom + GAP : Math.max(EDGE, r.top - h - GAP)}px`
}

/**
 * A page's icon.
 *
 * `icon` is a NAME from the stylised set. Older documents (and anything an
 * agent writes) may carry an emoji instead, so that still renders — but the
 * set is what the app offers, because a sidebar of twelve colour emoji reads
 * as a row of stickers rather than one interface.
 */
export function pageIcon(icon: string | undefined): string {
  if (!icon) return ICONS.page
  // hasOwn, not `in`: `'toString' in ICONS` is TRUE and resolves to a
  // FUNCTION, so an icon name of "toString" or "constructor" in a mailed file
  // returned native source text and skipped the escape below. Not markup, so
  // not an injection — but it is author-supplied data reaching the page
  // unescaped, and the next lookup table indexed this way might not be so lucky.
  if (Object.hasOwn(ICONS, icon)) return ICONS[icon as IconName]
  return escapeHtml(icon)   // an emoji, or anything else the file carried
}

/** The icons a page may choose from. */
export const PAGE_ICONS: IconName[] = [
  'page', 'note', 'book', 'folder', 'inbox', 'star', 'tag', 'hash',
  'compass', 'pen', 'scale', 'link', 'todo', 'code', 'image', 'archive',
]

/**
 * Replace text without touching markup.
 *
 * A naive string replace over `html` would happily rewrite a tag name or an
 * href — searching for "a" and replacing it would destroy every link on the
 * page. This walks the string and only substitutes OUTSIDE angle brackets.
 */

/**
 * Run after the next paint — but run REGARDLESS.
 *
 * `requestAnimationFrame` does not fire at all in a hidden tab, so anything
 * whose CORRECTNESS depends on it silently never happens: search a space,
 * switch tabs before the frame lands, come back, and the jump was never
 * completed. rAF is right when the page is visible (it is the only way to act
 * after layout); a timeout is the fallback that always arrives.
 */
export function afterPaint(fn: () => void): void {
  if (typeof document !== 'undefined' && document.visibilityState === 'hidden') { setTimeout(fn, 0); return }
  let done = false
  const once = () => { if (!done) { done = true; fn() } }
  requestAnimationFrame(once)
  setTimeout(once, 120)   // rAF starved (throttled tab, background window)
}