Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

51.4 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// The bento/spaces document model. This JSON is what lives inside the
// #bento-doc block — the format IS the product (docs/PLATFORM.md §3).
//
// ONE FILE = ONE SPACE: a tree of pages, each holding a flat pre-order list of
// blocks. Links are same-document fragments (`#p/<pageId>`) resolved against a
// map built from this block, so they work from file://, from a mail
// attachment, on iOS, and in 2036 (docs/DECISIONS.md, 2026-08-03).
//
// ADDITIVE FOREVER (PLATFORM §3): unknown top-level fields, unknown per-node
// fields and unknown block TYPES all survive parse → serialize. An older build
// meeting a future 'kanban' block keeps it and renders its html fallback.
// There is no server; a break here is permanent.

import type { CollabCreds } from './sync/crdt.ts'
// Type-only, and therefore erased: no runtime dependency, no import cycle.
import type { PageTemplate } from './templates.ts'
import type { SpacesRevision } from './history.ts'
import { esc, externalHref } from './sanitize.ts'
// A VALUE import, and the cycle it looks like is not one: embed.ts imports
// only TYPES from here, and a type import is erased before anything runs.
import { isPageRef } from './embed.ts'
import { projectForCopy, docContentKey as kernelContentKey } from '../../kernel/src/docfields.ts'
import { SPACES_FIELDS, SPACES_NOT_EDIT } from './docclass.ts'
// A LEAF module (no imports at all), which is what lets the parser call into
// it: the dotted-key fold has to run before anything else sees the document.
import { foldDottedMapKeys } from './docmaps.ts'
// Type-only, and therefore erased: no runtime dependency, no import cycle.
import type { Trail } from './trail.ts'
import type { Periods } from './periods.ts'

export const FORMAT = 'bento/spaces'
export const FORMAT_VERSION = 1

/**
 * Rules that could ever CHANGE are pinned as VALUES, never inferred from
 * `version` — the SYNC_V lesson: discard what you cannot read rather than
 * misread it. The OPEN half of the union is load-bearing: an unrecognised
 * policy must PARSE, so the file opens and round-trips byte-exact with
 * canonicalization and id repair disabled.
 */
export type Policy = 'bento-spaces-1' | (string & {})

/**
 * A block.
 *
 * PROPERTIES ARE FLAT, not nested under a `props` object, and that is a
 * correctness decision rather than a style one. Under collaboration each
 * (node, key) pair is one last-writer-wins register. With a nested `props` the
 * whole object is ONE register: measured, one author ticking `done` while
 * another sets a second field loses one of the two edits SILENTLY. Slides'
 * elements are flat for the same reason and keep both. Flattening costs
 * nothing now and is unrecoverable later, because the shape is in every file
 * ever saved.
 *
 * `html` is inline-only rich text (see sanitize.ts). Block STRUCTURE is
 * `type`, never markup — the renderer emits the semantic tag.
 */
export interface Block {
  id: string
  type: string
  /** inline-only html; canonicalised at typing-run close */
  html?: string
  /** nesting WITHIN a page: the id of the block that owns this one */
  parent?: string

  // ---- per-type fields, deliberately flat -------------------------------
  /** todo */
  done?: boolean
  /** code */
  lang?: string
  /** toggle: fold state AS SAVED is authorial intent, so it is document data.
   *  Toggles always PRINT expanded — silently omitting content from a printed
   *  handbook is a data-loss-shaped bug. */
  open?: boolean
  /** image, media: 'asset:<key>' | data: | https: */
  src?: string
  alt?: string
  caption?: string
  /**
   * media: 'video' | 'audio'.
   *
   * ONE block type with a kind, not two types, because everything else about
   * them is identical — the same hybrid src, the same remote-consent gate, the
   * same still in print and preview, the same playback flags. Two types would
   * mean two registry entries, two renderer cases and two exporters that have
   * to be kept saying the same thing.
   *
   * An OPEN string, like `type` and `tone`: a kind a future build adds must
   * round-trip through this one. Anything that is not 'audio' is drawn as
   * video, which is the shape that degrades usefully — a video element with an
   * audio file in it plays the audio.
   */
  kind?: string
  /** media: a still frame, same three src forms. Shown before play, and it is
   *  what print and the file-manager preview draw instead of a player. */
  poster?: string
  /** media: playback controls for the reader. Absent = shown. */
  controls?: boolean
  /** media: repeat at the end. */
  loop?: boolean
  /** media: start silent. */
  muted?: boolean
  /**
   * media: RECORDED, NEVER HONOURED. See blocks.ts mediaPlayback().
   *
   * A space has no surface that owns playback the way slides' present mode
   * does — it has an editor, a reading view, a printout and a file-manager
   * still, and a clip that starts itself is wrong in all four. The field
   * exists so a document written by a build that DOES have such a surface
   * round-trips untouched (PLATFORM §3), and so that the rule has somewhere to
   * be written down. It is not read by this app.
   */
  autoplay?: boolean
  /** image width as a PERCENTAGE of the text column (10..100). No block
   *  carries absolute px — the column width is a theme concern. */
  width?: number
  /** intrinsic px at insert: holds the aspect box while the image decodes */
  w?: number
  h?: number
  /**
   * pagelink, embed: the target page id.
   *
   * ONE FIELD FOR BOTH, because both mean the identical thing — "this block
   * refers to that page" — and every sweep in the app that follows a page
   * reference (backlinks, extract, graft, validate, the graph) then extends by
   * a name in one condition instead of growing a second concept it could
   * forget. embed.ts `isPageRef` is that condition.
   */
  page?: string
  /**
   * embed: the heading inside the target page to show, instead of all of it.
   *
   * Absent = the whole page, which is the common case and therefore the case
   * that stores no bytes. Matched by NAME, case- and whitespace-insensitively,
   * never by position: a section moved up the page is still that section, and
   * an index would silently show the wrong one. A name that matches nothing is
   * reported, never quietly widened back to the whole page.
   */
  anchor?: string

  /**
   * table: the cells, row-major, each one INLINE HTML.
   *
   * A cell is a bare string rather than slides' `{html, color, bg, bold}`
   * object, and that is the one real divergence from the model this is
   * otherwise copied from. Slides' cells carry presentation because a canvas
   * has no cascade — every table there paints its own colours. A space has a
   * theme and a stylesheet, so the only thing left in a cell is its content,
   * and its content is already rich: **bold** in a cell is `<b>`, exactly as in
   * every other block, through the same allowlist. Nothing is lost and the
   * whole style object goes away.
   *
   * Row 0 is the header unless `header` is false — see below.
   *
   * UNDER COLLABORATION this whole field is one last-writer-wins register, so
   * two people editing DIFFERENT cells at the same time keep only one of the
   * two edits. Slides' table has the identical limitation and documents it;
   * the fix (a node per cell) is a format change, so it is written down here
   * rather than half-built.
   */
  rows?: string[][]
  /**
   * table: fractional column weights, one per column. Absent = equal columns.
   *
   * FRACTIONS, never pixels, for the reason `Block.width` is a percentage: the
   * text column is a theme concern and the same file is read at 320px and at
   * 1600px. Dragging a column boundary changes two weights and nothing else.
   */
  cols?: number[]
  /**
   * table: per-COLUMN text alignment — '' | 'left' | 'center' | 'right'.
   *
   * Per column, not per cell, because that is what a pipe table can say: GFM
   * encodes alignment in the `:---:` rule row and nowhere else. Per-cell
   * alignment would export as a lie on every second row.
   */
  colAlign?: string[]
  /**
   * table: false when the first row is ordinary data.
   *
   * ABSENT MEANS TRUE, which is the opposite of every other boolean here and is
   * deliberate: a GFM pipe table always has a header, so the header case is
   * what a table imported from markdown, written by an agent, or hand-authored
   * with the two fields above will be — and it should be the case that needs no
   * field. A headerless table says so, and exports with an empty header row.
   */
  header?: boolean

  /**
   * link: the address the card opens. `https:`, `http:` or `mailto:` only —
   * anything else is not made clickable (see `linkCard`).
   */
  url?: string
  /** link: the headline. Absent falls back to the url itself, never to a blank
   *  box — an empty field must still leave a working link. */
  title?: string
  /** link: the author's one-line description of what is at the other end. */
  desc?: string
  /** link: the site's name. Absent is DERIVED from the url's host, which needs
   *  no network — it is string parsing, not a lookup. */
  site?: string
  /**
   * link: a thumbnail, `asset:<key>` or `data:` and NOTHING ELSE.
   *
   * A remote thumbnail is the tracking pixel of the 2026-08-03 decision wearing
   * a card for a hat: it would fire on open, in a document whose whole premise
   * is that you can mail it. `linkCard` drops one rather than deferring it
   * behind a placeholder, because an image block's placeholder stands in for
   * the block's entire content while a card's thumbnail is decoration — there
   * is nothing for a reader to consent to and nothing lost by its absence.
   */
  image?: string
  /**
   * callout: which kind of callout this is — one of blocks.ts CALLOUT_TONES.
   *
   * An OPEN string, like `type`, and for the same reason: a tone a future build
   * adds must survive this one untouched. An unrecognised tone renders with the
   * neutral treatment and spells ITSELF out as its label, so the reader is told
   * the truth rather than shown a note that is really a warning.
   */
  tone?: string
  /**
   * callout: an emoji (or a name from the icon set) REPLACING the tone's own
   * mark.
   *
   * Absent is the normal case and is not a missing value — the mark is DERIVED
   * from the tone, so every warning in a document looks like every other one,
   * and a document written today is not frozen to today's glyphs. The override
   * exists because "🎉 we shipped" is a callout too, and it never changes what
   * the tone MEANS: the tone is still the tone, in the styling and in the
   * markdown export.
   */
  icon?: string

  /**
   * Review threads anchored to THIS block. See `Comment` below for why they
   * live on the block rather than in one list on the page.
   */
  comments?: Comment[]

  [extra: string]: unknown
}

/** One message in a thread. The first one IS the thread (`Comment` extends it). */
export interface CommentEntry {
  id: string
  author: string
  /** ISO datetime */
  at: string
  /**
   * PLAIN TEXT, never html, and the only field in this format that is.
   *
   * A block's `html` earns its markup and pays for it with sanitize.ts. A
   * comment has nothing to gain from bold — and it arrives in a file somebody
   * mailed you, from a person who is by definition not the author of the
   * document. So the answer is not "sanitize it too" but "there is nothing to
   * sanitize": it is stored as a string and written to the screen with
   * `textContent`, so `<img onerror>` in a comment is four words a reader can
   * see rather than a parse this app has to be careful about.
   */
  text: string
}

/**
 * A review thread. Saved in the file so it travels with the document, and
 * EDITOR-ONLY: `render.ts` never emits one, so it cannot reach the reading
 * view or the printed page. A comment is workspace, not document.
 *
 * WHERE A THREAD LIVES IS ITS ANCHOR. A deck is a canvas, so slides can point
 * at an (x, y); a space is a tree of pages of blocks, and the block is the
 * thing that already has a durable identity — ids are unique document-wide and
 * are never reused, which is exactly what links and backlinks key on. So there
 * are two anchors and no third: `Block.comments` is a thread about that block,
 * `Page.comments` is a thread about the page. A text RANGE inside a block is
 * deliberately not one: an offset pair has no meaning after the concurrent
 * edit that moved it, and inventing one now would freeze the wrong answer into
 * every file.
 *
 * Storing a block thread ON THE BLOCK is a collaboration decision, not a
 * filing one. Under the CRDT every non-container property is one
 * last-writer-wins register (kernel/src/sync/crdt.ts), so one `Page.comments`
 * array would make every thread on a page contend for a single register: two
 * people commenting on two different paragraphs at the same moment, and one
 * comment is gone with nothing said. Per block, that case converges. What
 * remains — two people commenting on the SAME block, or on the same page,
 * concurrently — is still last-writer-wins, exactly as slides' table `rows`
 * is, and is written down rather than pretended away.
 */
export interface Comment extends CommentEntry {
  resolved?: boolean
  replies?: CommentEntry[]
}

export interface Page {
  id: string
  title: string
  /** page-tree nesting; absent = a root page */
  parent?: string
  /** one emoji, never a URL — a URL would be a network dependency */
  icon?: string
  /**
   * A picture across the top of the page.
   *
   * `asset:<key>` or a `data:` URI, and NEVER a URL — for exactly the reason
   * `icon` is not one. PLATFORM §1: opening a document must not touch the
   * network, and a cover is the field most likely to tempt someone into a
   * link, because that is how every hosted notes app does it. A file that
   * arrives carrying a remote cover keeps the field (additivity) and renders
   * NOTHING, which `coverSrc` is the single place that decides.
   *
   * Absent on every page written before this, so an older build renders the
   * page it always did and round-trips the field untouched.
   */
  cover?: string
  /** flat, pre-order; nesting via Block.parent */
  blocks: Block[]
  /**
   * This page IS the daily entry for an ISO `YYYY-MM-DD` date.
   *
   * The DATE, not the title, is what makes a journal a journal — see
   * src/journal.ts. Logseq derives the same thing from a formatted page title
   * and their tracker carries the data loss that follows when the format
   * changes; a title is display and this is data. Absent on every other page,
   * so a build that predates journals renders an ordinary page and round-trips
   * the field untouched.
   */
  journal?: string
  /**
   * How wide this page's column is: absent = the theme measure (prose),
   * 'wide' = room for a board, 'full' = the whole window.
   *
   * ON THE PAGE, not on the theme. `theme.measure` is one number for the whole
   * document, and the right answer genuinely differs per page: a page of notes
   * wants a comfortable line, a board wants the room. The renderer ALREADY
   * knew that — a page carrying a `view` block silently jumped to 1500px — but
   * it decided for you and offered no way to disagree. This makes that rule
   * explicit and overridable in one field: a board page with no `width` still
   * gets its room, and a board page set to normal now gets to be narrow.
   *
   * Additive. Absent on every page written before this, and an unknown value
   * falls back to the measure rather than to nothing.
   */
  width?: 'wide' | 'full'
  /**
   * Other names this page answers to — `[[NYC]]` and `[[New York]]` reaching
   * the same page.
   *
   * A LINK-TIME notion, deliberately. An alias is resolved where a name
   * becomes a page id (src/mentions.ts `nameIndex`, read by the `[[…]]`
   * resolver, ⌘K and the page picker), so the link that gets written is an
   * ordinary `#p/<id>` href and the backlink index, the graph, export and
   * collaboration never learn that aliases exist. Nothing downstream has a
   * second way to name a page.
   *
   * Additive: absent on every page written before this, and an ABSENT key is
   * the default — clearing the last alias deletes the field rather than
   * storing `[]`, so a page that never had one is byte-identical to a page
   * that had one and lost it. A build that predates this round-trips the
   * array untouched and simply does not resolve by it.
   *
   * Two pages may claim the same alias; nothing here prevents it, because a
   * file arrives already written. `nameIndex` resolves it deterministically
   * (titles before aliases, then document order) and validate() reports it —
   * see `alias-collision` in agent.ts.
   */
  aliases?: string[]
  /**
   * This page's own design (DECISIONS 2026-09-26, per-page addendum): a
   * built-in name or a key of `doc.designs`, exactly as `doc.design` is.
   *
   * ABSENT = INHERIT: the nearest ancestor's, then the space's, then today's
   * look — so setting one on a section restyles its whole subtree. Returning
   * to inherit DELETES the key. An unknown name renders the DEFAULT look (it
   * does not fall through to the parent's), round-trips untouched, and is
   * named by validate(). Older builds ignore it and show the space's design.
   */
  design?: string
  /** the one page daily entries hang from, so the sidebar stays a tree */
  journalHome?: boolean
  /** out of the sidebar, still searchable and linkable, and ENUMERATED at
   *  share time — an author archived a page precisely because it was sensitive */
  archived?: boolean
  /** review threads about the page as a whole — see `Comment` */
  comments?: Comment[]
  created?: string
  edited?: string
  [extra: string]: unknown
}

export interface Theme {
  background: string
  color: string
  accent: string
  fontFamily: string
  headingFamily?: string
  /** text column width in px — DOCUMENT data: the same for every reader */
  measure?: number
  /** BASE direction of page CONTENT (PLATFORM §8's two-layer pin) */
  dir?: 'ltr' | 'rtl'
}

export interface SpacesDoc {
  format: typeof FORMAT
  version: number
  /** absent ⇒ bento-spaces-1 */
  policy?: Policy
  /** minted once at creation/load, NEVER regenerated (PLATFORM §3) */
  docId: string
  title: string
  modified?: string
  /** flat, pre-order; nesting via Page.parent */
  pages: Page[]
  /** the page shown on open; absent ⇒ pages[0] */
  home?: string
  theme: Theme
  /**
   * The page design the AUTHOR chose (DECISIONS 2026-09-26): a built-in name
   * (designs.ts BUILT_INS) or a key of `designs`. ABSENT = the default look,
   * and returning to the default DELETES the key. An unknown name renders the
   * default and round-trips untouched. A page's own `Page.design` (or its
   * nearest ancestor's) overrides this — designs.ts resolvePageDesign.
   */
  design?: string
  /**
   * Designs this document carries itself, by name: overrides on a built-in
   * base, every value validated before use (designs.ts resolveData). A name
   * that is also a built-in's is never used.
   */
  designs?: Record<string, unknown>
  assets?: Record<string, string>
  /**
   * FOOTNOTES, by label → inline html. See src/footnotes.ts for the whole
   * design; the two things that belong in the FORMAT's own file are these.
   *
   * DOC-LEVEL AND KEYED, which is bento/type's shape (type/src/model.ts) and
   * is chosen for its reason: a note has to be able to outlive the paragraph
   * that points at it, and keying it by label means moving a paragraph between
   * pages carries the reference and nothing else.
   *
   * NO NUMBER IS STORED HERE OR ANYWHERE. Footnotes are numbered by order of
   * appearance, so the number is a fact about the page and not about the note;
   * it is derived at render time, the way calc.ts derives an answer and slides
   * derives a page number. The LABEL is an identifier — `[^1]` is what pandoc
   * and Obsidian store too, and it can perfectly well render as "3".
   *
   * The REFERENCE is the literal text `[^label]` inside a block's html: a text
   * token, so it moves with the prose through every edit, sanitize pass,
   * canonicalisation and CRDT merge, and so no allowlist in sanitize.ts had to
   * change for it. An older build shows the sentence with `[^1]` in it and
   * round-trips this key untouched — absent means no footnotes, which is the
   * behaviour every build shipped before this one already has.
   */
  footnotes?: Record<string, string>
  fonts?: Array<{ family: string; asset: string; weight?: string; style?: string }>
  readonly?: boolean
  /** WHOLE-FILE share export: re-mints docId on open. Not a page template —
   *  see `templates` below, and src/templates.ts for why the two are separate. */
  template?: boolean
  /**
   * Page templates: saved page shapes new pages can start from.
   *
   * A SEPARATE COLLECTION, not pages carrying a flag — the reasoning, and what
   * that costs, is in src/templates.ts. Additive: absent on every file written
   * before this, and an older build round-trips it untouched.
   */
  templates?: PageTemplate[]
  /** the template id new daily notes start from; absent ⇒ a blank entry */
  journalTemplate?: string
  /**
   * Collaboration credentials (PLATFORM §2).
   *
   * Was `unknown` and marked RESERVED "unused until collab ships". It has:
   * sync/session.ts binds this app to the kernel session. The type is the
   * KERNEL's so there is one definition of what a room, a key and an invite
   * chain are — the deployed relay verifies against that shape, and a second
   * local description of it is how a client and the worker drift apart.
   * `import type` is erased, so this adds no runtime dependency.
   */
  collab?: CollabCreds
  /**
   * In-file history (kernel field class 'history', docfields.ts): kept by the
   * file, a duplicate and an invite; dropped from every reader-tier copy and
   * from Copy document JSON; never synced.
   *
   * `revisions` is the space's VERSION HISTORY — oldest first, each entry the
   * kernel's `Revision` envelope around the change from the one before it.
   * The engine, its budget and the reasoning live in history.ts; every entry
   * read from a file is validated there before anything folds it. Absent when
   * there is none — never `revisions: []`. `import type`, so no runtime cycle.
   *
   * `trail` is THE RECORD: what was true on a day, for the tracker's burndown,
   * burnup and cumulative-flow charts (trail.ts). Written while editing, never
   * on open; each replica keeps its own. A row holds COUNTS and nothing else —
   * no page ids, no assignee breakdown, no per-issue anything: that is a budget
   * rule and a privacy rule at once, written here so a later session does not
   * add the surveillance shape as the obvious next step.
   */
  revisions?: SpacesRevision[]
  trail?: Trail
  /**
   * The windows the charts are about (periods.ts) — CONTENT, not history: a
   * period is something a person decided, referenced by a chart block, undone
   * by ⌘Z and synced (per key, `DOC_MAPS`). Totals only, never page ids.
   * Absent until a period is started; deleted rather than emptied.
   */
  periods?: Periods
  [extra: string]: unknown
}

/**
 * The document with its collaboration SECRETS removed, for anything a person
 * copies, pastes or hands to somebody else.
 *
 * `doc.collab` is minted at creation, so EVERY space has one from its first
 * save — and it holds the read capability (`key`), the write capability
 * (`writerPriv`), the owner key that can also revoke (`ownerPriv`) and any
 * invite's private half. "Copy document JSON" put all of that on the
 * clipboard, under a note inviting exactly that copy ("the whole document is
 * plain JSON in this file"), and the natural next step is pasting it into a
 * chat window. bento/slides had this same bug, fixed it, and wrote a rig to
 * stop it coming back — the rig only ever looked at slides/.
 *
 * BUILT FROM EMPTY by the kernel's copy table (docfields.ts projectForCopy,
 * tier 'copyJSON', this app's map in docclass.ts): `collab` is a capability
 * and is dropped whole — `room` and `key` too, since together they ARE the
 * read capability. The modes (readonly, template), the in-file history and
 * any top-level key this build does not declare are dropped as well: the
 * clipboard is a hand-out, and an undeclared key is exactly the field nobody
 * has decided is safe to hand out. Content and the docId travel.
 */
export function docForExport(doc: SpacesDoc): SpacesDoc {
  return projectForCopy(doc, SPACES_FIELDS, 'copyJSON')
}

export const uid = (p = 'b'): string => {
  const r = globalThis.crypto?.randomUUID?.()
  return r ? `${p}-${r.slice(0, 8)}` : `${p}-${Math.random().toString(36).slice(2, 10)}`
}

const newDocId = (): string => globalThis.crypto?.randomUUID?.() ?? uid('doc')

/**
 * Parse result — TAGGED, never null.
 *
 * `parseDoc` returning null let the caller fall back to the starter, which
 * means opening a slides file, or a document with one hand-edited typo, gave
 * you an EMPTY space over live data — and the first ⌘S wrote it to disk. The
 * only path to the starter is an absent or empty block.
 *
 * `frozen` means this build must not canonicalize html or repair ids: the file
 * declares rules this build does not have, so it round-trips byte-exact.
 * Sanitize still runs — that is a security control, not an interpretation.
 */
export type ParseResult =
  | { ok: true; doc: SpacesDoc; repaired: string[]; frozen?: 'policy' | 'version' }
  | { ok: false; err: 'empty' }
  | { ok: false; err: 'json' | 'format' | 'shape'; detail: string; found?: string }

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

/**
 * Deterministic id repair.
 *
 * Two readers of one file must agree on every id, so a replacement is derived
 * from the BYTES — never from `Math.random` (which diverges two readers, and
 * two future CRDT replicas on a node key) and never from `docId` (which
 * `template: true` re-mints on every open, so a docId-derived id gives two
 * readers of one file DIFFERENT ids: exactly the failure repair exists to
 * prevent).
 *
 * EXPORTED because the subtree import needs exactly this and must not invent a
 * second scheme: an arriving id that collides with one this space already uses
 * is renamed here, under the same derivation and the same reasoning
 * (src/portable.ts planGraft).
 */
export function repairId(scope: string, ordinal: number, content: string, salt = 0): string {
  let h = 0x811c9dc5
  const s = `${scope}${ordinal}${content}${salt}`
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i)
    h = Math.imul(h, 0x01000193) >>> 0
  }
  return `r-${h.toString(36)}`
}

export function parseDoc(json: string): ParseResult {
  if (!json || !json.trim()) return { ok: false, err: 'empty' }

  let raw: unknown
  try {
    raw = JSON.parse(json)
  } catch (e) {
    return { ok: false, err: 'json', detail: (e as Error).message }
  }
  if (!isObj(raw)) return { ok: false, err: 'shape', detail: 'the document block is not a JSON object' }

  // A PEER RUNNING AN OLDER SHAPE writes a doc-level map entry as a literal
  // top-level key: it receives `set k="periods.pd-1"`, cannot resolve
  // `periods` as a map, and stores the dotted name verbatim — which additivity
  // would then preserve forever. Folding it back is cheap, deterministic and
  // self-healing, and it repairs files that were damaged before this existed.
  // Done HERE rather than in a kernel handshake: the hazard belongs to any
  // future doc-level map, and six lines in a file this app owns beat a change
  // to shared machinery every app depends on.
  foldDottedMapKeys(raw)

  if (raw.format !== FORMAT) {
    return {
      ok: false,
      err: 'format',
      detail: `this document declares "${String(raw.format ?? '(nothing)')}"`,
      found: typeof raw.format === 'string' ? raw.format : undefined,
    }
  }
  if (!Array.isArray(raw.pages)) {
    return { ok: false, err: 'shape', detail: 'a bento/spaces document needs a "pages" array' }
  }

  const version = typeof raw.version === 'number' ? raw.version : FORMAT_VERSION
  const policy = typeof raw.policy === 'string' ? raw.policy : 'bento-spaces-1'
  const frozen: 'policy' | 'version' | undefined =
    version > FORMAT_VERSION ? 'version' : policy !== 'bento-spaces-1' ? 'policy' : undefined

  const repaired: string[] = []
  const seen = new Set<string>()
  /** first occurrence in pre-order keeps the id; later duplicates are repaired */
  const claim = (want: unknown, scope: string, ordinal: number, content: string): string => {
    const id = typeof want === 'string' && want ? want : ''
    if (id && !seen.has(id)) { seen.add(id); return id }
    if (frozen && id) return id // frozen: never rewrite, even a duplicate
    let salt = 0
    let next = repairId(scope, ordinal, content, salt)
    while (seen.has(next)) next = repairId(scope, ordinal, content, ++salt)
    seen.add(next)
    repaired.push(id || '(missing id)')
    return next
  }

  // Pages repair FIRST, in pre-order, so a block's owning page id is final
  // before its own replacement is derived from it.
  const pages: Page[] = (raw.pages as unknown[]).map((p, pi) => {
    const src = isObj(p) ? p : {}
    const title = typeof src.title === 'string' ? src.title : 'Untitled'
    const pid = claim(src.id, String(src.parent ?? ''), pi, title)
    const blocksRaw = Array.isArray(src.blocks) ? src.blocks : []
    const blocks: Block[] = blocksRaw.map((b, bi) => {
      const bs = isObj(b) ? b : {}
      const type = typeof bs.type === 'string' && bs.type ? bs.type : 'p'
      const html = typeof bs.html === 'string' ? bs.html : undefined
      return {
        ...bs,
        id: claim(bs.id, pid, bi, `${type}${html ?? ''}`),
        type,
        ...(html !== undefined ? { html } : {}),
      } as Block
    })
    return { ...src, id: pid, title, blocks } as Page
  })

  // A parent naming something that does not exist is DROPPED rather than left
  // dangling: an unreachable page is worse than a root one, and a block whose
  // owner is absent would never render at all.
  const pageIds = new Set(pages.map((p) => p.id))
  for (const p of pages) {
    if (p.parent && !pageIds.has(p.parent)) delete p.parent
    const own = new Set(p.blocks.map((b) => b.id))
    for (const b of p.blocks) if (b.parent && !own.has(b.parent)) delete b.parent
  }

  const doc: SpacesDoc = {
    ...raw,
    format: FORMAT,
    version,
    docId: typeof raw.docId === 'string' && raw.docId ? raw.docId : newDocId(),
    title: typeof raw.title === 'string' ? raw.title : 'Untitled space',
    pages,
    theme: { ...defaultTheme(), ...(isObj(raw.theme) ? raw.theme : {}) },
  } as SpacesDoc

  return { ok: true, doc, repaired, ...(frozen ? { frozen } : {}) }
}

export function defaultTheme(): Theme {
  return {
    background: '#FFFFFF',
    color: '#1E2A3A',
    accent: '#F7A600',
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
    measure: 720,
  }
}

export const newBlock = (type = 'p', extra: Partial<Block> = {}): Block =>
  ({ id: uid('b'), type, html: '', ...extra })

export const newPage = (title = 'Untitled', extra: Partial<Page> = {}): Page =>
  ({ id: uid('p'), title, blocks: [newBlock()], ...extra })

/** Content that matters for "did this change" — excludes volatile fields. */
export function docContentKey(doc: SpacesDoc): string {
  // The kernel's key (docfields.ts), over this app's field map: every declared
  // and undeclared top-level field that is PRESENT, sorted, except the
  // capability (`collab` — a key is not an edit), `modified`, and `revisions`
  // (recorded only into the bytes a save writes — docclass.ts SPACES_NOT_EDIT).
  //
  // So `footnotes` is in it (a note's text is somebody's writing and lives
  // nowhere else), the page templates and the journal template are in it
  // (saving one is an edit worth recovering after a crash), and so are
  // `design`/`designs` (a crash right after choosing one must still offer the
  // recovery). An ABSENT field is skipped, never null-padded, so a document
  // with no design keys exactly as it would with the field never invented.
  //
  // ONE return. Each field once arrived on its own branch with its own
  // `return` line, and a merge that kept both left the second one dead —
  // footnotes silently dropped out of recovery.
  return kernelContentKey(doc, SPACES_FIELDS, SPACES_NOT_EDIT)
}

// ---- derived, NEVER stored -------------------------------------------------
// Stale the moment anything else writes the document (an agent editing
// #bento-doc, a version restore, a future CRDT apply). Derived at load.

export interface SpaceIndex {
  page: Map<string, Page>
  /** page id → child pages in order; '' = root */
  children: Map<string, Page[]>
  block: Map<string, { block: Block; pageId: string }>
  /** target page id → the blocks that link to it */
  backlinks: Map<string, Array<{ pageId: string; blockId: string }>>
}

/**
 * A table's cells as one string, for scanning only.
 *
 * Deliberately not `tableFallbackHtml`: this is never written anywhere, so it
 * needs no separator, no escaping and no shape — it exists so one regex can
 * find hrefs in cells the same way it finds them in prose. Tolerant of a
 * malformed `rows` because it runs on documents nobody has validated yet.
 */
function tableCellsText(rows: unknown[]): string {
  let out = ''
  for (const row of rows) {
    if (!Array.isArray(row)) continue
    for (const cell of row) if (typeof cell === 'string') out += cell + '\n'
  }
  return out
}

/** Every `#p/<id>` href in a block's html. */
const LINK_RE = /href="#p\/([^"]+)"/g

/**
 * The PAGE a `#p/…` target names.
 *
 * `#p/<page>` today; `#p/<page>/<block>` is already admissible under
 * sanitize.ts's allowlist, so it can appear in a file this build did not write.
 * Keyed on the whole string, a block link produced a backlink on the id
 * "p1/b2" — which is no page, so the target page listed nothing and the one
 * feature that makes a wiki worth having quietly failed on exactly the links a
 * newer build would write.
 *
 * `pages` is passed so an author-supplied id CONTAINING a slash still wins:
 * minted ids never contain one, but nothing stops a hand-written file.
 */
function linkTarget(raw: string, pages: Map<string, Page>): string {
  if (pages.has(raw)) return raw
  const cut = raw.lastIndexOf('/')
  return cut > 0 ? raw.slice(0, cut) : raw
}

const pushInto = <T>(m: Map<string, T[]>, k: string, v: T) => {
  const list = m.get(k)
  if (list) list.push(v)
  else m.set(k, [v])
}

/**
 * THE ONE ANSWER to "what is this block nested under".
 *
 * A block's effective parent is `b.parent` iff that block exists in the SAME
 * page and appears STRICTLY EARLIER in the array. Anything else — a parent that
 * is absent, that is the block itself, or that sits later — resolves to the
 * root. Settled in docs/DECISIONS.md (2026-08-03) and implemented here because
 * it was previously implemented four times, differently:
 *
 *   · render.ts walked a stack, which IS this rule (positional);
 *   · blocks.ts mdLayout followed `parent` as a graph, hop-capped at 32;
 *   · agent.ts descendants swept the graph to a fixed point, explicitly
 *     "rather than trusting the order";
 *   · editor.indent looked its owner up by id, anywhere in the page.
 *
 * They agree today only because the editor keeps the array in pre-order. That
 * is exactly the invariant collaboration breaks: `parent` is a last-writer-wins
 * register and order is a fractional position key, so two legal concurrent
 * edits — you indent a block, I move one — converge on an array where a child
 * precedes its parent. Measured on the merge rig: 52.4% of merged documents.
 * At that point "the tree" means four different things, and the graph readers
 * are the dangerous ones: a merged cycle makes `descendants` return the whole
 * connected component, so deleting one block deletes blocks nobody selected.
 *
 * POSITIONAL IS THE RULE BECAUSE IT CANNOT FAIL. A parent must be earlier, so
 * the result is ACYCLIC BY CONSTRUCTION — no visited set, no hop cap, no
 * fixed-point sweep, and no document can be authored or merged into a shape
 * that makes it loop. It is a pure READ-TIME function: it mutates nothing, so
 * two replicas that agree on the array agree on the tree without exchanging a
 * single extra op. Repairing the array instead would mint `ord` ops and two
 * replicas can ping-pong over them forever.
 */
export function effectiveParents(page: Page): Map<string, string | undefined> {
  const out = new Map<string, string | undefined>()
  const seenAt = new Map<string, number>()
  page.blocks.forEach((b, i) => {
    const p = typeof b.parent === 'string' ? b.parent : undefined
    // strictly earlier: `seenAt` only holds blocks already walked past
    out.set(b.id, p !== undefined && seenAt.has(p) ? p : undefined)
    seenAt.set(b.id, i)
  })
  return out
}

/**
 * Every block nested under `id`, at any depth — by the rule above, so it
 * terminates on any document and never reaches outside the subtree.
 */
export function descendantsOf(page: Page, id: string): Set<string> {
  const eff = effectiveParents(page)
  const out = new Set<string>()
  // one forward pass suffices: a child always follows its effective parent
  for (const b of page.blocks) {
    const p = eff.get(b.id)
    if (p !== undefined && (p === id || out.has(p))) out.add(b.id)
  }
  return out
}

export function buildIndex(doc: SpacesDoc): SpaceIndex {
  const page = new Map<string, Page>()
  const children = new Map<string, Page[]>()
  const block = new Map<string, { block: Block; pageId: string }>()
  const backlinks = new Map<string, Array<{ pageId: string; blockId: string }>>()

  for (const p of doc.pages) page.set(p.id, p)
  for (const p of doc.pages) {
    // a parent that does not resolve shows at root, never disappears
    pushInto(children, p.parent && page.has(p.parent) ? p.parent : '', p)
    for (const b of p.blocks) {
      block.set(b.id, { block: b, pageId: p.id })
      // WHERE A BLOCK'S LINKS LIVE. Normally in `html`. A table keeps its
      // content in `rows` and mirrors it into `html` as a readable fallback,
      // and `writeTable` is the one writer that keeps the two in step — so for
      // a table the editor produced, scanning `html` finds the cells' links.
      //
      // It does not for a table that arrives any other way. A hand-written
      // document, an agent calling updateBlock, an import: `rows` is set,
      // `html` is absent, and a link in a cell then WORKS WHEN CLICKED and
      // appears in no "Linked from" — the one failure a backlink index has,
      // and silent. Measured before this: 0 backlinks, against 1 for the same
      // table through writeTable.
      //
      // `rows` is read ONLY when `html` is absent. With both present they are
      // the same links by construction, and scanning both would report every
      // cell link twice — which is why extending this to always scan `rows`
      // was tried during the starter work and reverted.
      const linkSrc = b.html || (Array.isArray(b.rows) ? tableCellsText(b.rows) : '')
      if (linkSrc) {
        for (const m of linkSrc.matchAll(LINK_RE)) {
          pushInto(backlinks, linkTarget(m[1], page), { pageId: p.id, blockId: b.id })
        }
      }
      // AN EMBED IS A REFERENCE, so it backlinks exactly as a pagelink does.
      // "Linked from" is how an author finds out who depends on a page before
      // rewriting it, and an embed is the strongest dependency in the model —
      // the page it names is not merely mentioned, it is being SHOWN
      // somewhere else. Leaving embeds out would make the one reference you
      // most need to be warned about the one the panel does not list.
      if (isPageRef(b)) {
        pushInto(backlinks, String(b.page), { pageId: p.id, blockId: b.id })
      }
    }
  }
  return { page, children, block, backlinks }
}

/** A thread, with the anchor it was found at. `blockId` absent = the page. */
export interface CommentAt {
  comment: Comment
  pageId: string
  blockId?: string
}

/**
 * Every thread on a page, page-level first, then block threads in page order.
 *
 * The ONE reader of both anchors, so the badge, the marker layer and the agent
 * report cannot disagree about what a page holds. Defensive about the shape
 * because this data arrives in a file: `comments: "yes"` must be ignored, not
 * iterated.
 */
export function commentsOn(page: Page): CommentAt[] {
  const out: CommentAt[] = []
  const take = (list: unknown, blockId?: string) => {
    if (!Array.isArray(list)) return
    for (const c of list) {
      if (c && typeof c === 'object' && typeof (c as Comment).id === 'string') {
        out.push({ comment: c as Comment, pageId: page.id, ...(blockId ? { blockId } : {}) })
      }
    }
  }
  take(page.comments)
  for (const b of page.blocks) take(b.comments, b.id)
  return out
}

/** How many threads on this page are still open — the sidebar badge. */
export const unresolvedOn = (page: Page): number =>
  commentsOn(page).reduce((n, c) => n + (c.comment.resolved ? 0 : 1), 0)

/** The page a reader lands on. */
export const homePage =(doc: SpacesDoc): Page | undefined =>
  (doc.home ? doc.pages.find((p) => p.id === doc.home) : undefined) ?? doc.pages[0]

/**
 * Would loading this src touch the network?
 *
 * `asset:` is in the file and `data:` is the bytes themselves — neither leaves
 * the machine. Everything else does, INCLUDING a relative path (which resolves
 * against the document's own URL and is a real request on a static host), and
 * `//host/x`, and any scheme this build has never heard of. So the test is an
 * allowlist of the two local forms, not a blocklist of `http`.
 */
export function isRemote(src: string): boolean {
  if (!src) return false
  return !src.startsWith('asset:') && !src.startsWith('data:')
}

/**
 * The cover a page actually shows — '' when it has none, and '' when what it
 * has would reach the network.
 *
 * ONE PLACE decides that, because the rule has to hold for the page, the
 * gallery card, the asset sweep and anything added later. A remote cover is
 * not repaired and not deleted: the field round-trips, and validate() says so
 * out loud (agent.ts) rather than the picture silently not being there.
 */
export function coverSrc(page: Page): string {
  const c = (page as { cover?: unknown }).cover
  if (typeof c !== 'string' || !c) return ''
  return isRemote(c) ? '' : c
}

/** Every asset key a PAGE references outside its blocks — today, its cover. */
export function pageAssetKeys(page: Page): string[] {
  const c = (page as { cover?: unknown }).cover
  return typeof c === 'string' && c.startsWith('asset:') ? [c.slice(6)] : []
}

/**
 * What an `asset:` src actually points at, or the src itself.
 *
 * hasOwn, not a bare index: `assets['toString']` returns a FUNCTION, which is
 * truthy, so a `?? ''` never fires and the stringified function is what gets
 * assigned. Same class as the icon lookup — an author-supplied key reaching a
 * lookup table through the prototype chain.
 */
export function assetValue(src: string, doc: SpacesDoc): string {
  if (!src.startsWith('asset:')) return src
  const key = src.slice(6)
  const table = doc.assets
  return table && Object.hasOwn(table, key) ? String(table[key] ?? '') : ''
}

/**
 * Does loading this src reach off the machine — after the asset table has had
 * its say?
 *
 * `isRemote` answers about the string an author WROTE, and that was the whole
 * test until now. It has a hole one indirection deep: `asset:k` is local by
 * inspection, and `doc.assets.k` is whatever the file says it is. A document
 * carrying
 *
 *     "assets": { "k": "http://tracker.example/p.png" }
 *
 * and an image `src: "asset:k"` fetched it on open — measured on a shipped
 * build, with the request in the network log. The consent placeholder never
 * appeared, because the gate had already decided the src was local.
 *
 * Nothing can be promised about what is INSIDE a file somebody mails you. What
 * the app owes its reader is narrower and keepable: it makes no request on a
 * document's behalf until the reader asks for it. That promise is only as good
 * as the question this function answers, so it is asked about the URL that will
 * actually be fetched rather than the one that was typed.
 */
export function loadsRemotely(src: string, doc: SpacesDoc): boolean {
  return isRemote(assetValue(src, doc))
}

// ---- tables ----------------------------------------------------------------
// A table is CONTENT (working/design/spaces-design.md §2.6): no formulas, no
// recalculation, no cross-document references. The line the suite draws is
// "would you print it → folio; does it recalculate → dash; does it link to
// pages → spaces", and a table whose cells are inline html — so a cell can
// hold a `#p/` link — is squarely on this side of it. The DATABASE case already
// shipped, as the tracker (doc.fields + prop + view blocks), and is not this.

/** The upper bound on a table's shape. A file can be hand-edited or generated,
 *  and the renderer should not be asked for a hundred thousand cells. */
export const TABLE_MAX_COLS = 32
export const TABLE_MAX_ROWS = 400

export interface TableShape {
  rows: string[][]
  cols: number[]
  colAlign: string[]
  header: boolean
  /** columns and rows, after normalisation */
  w: number
  h: number
}

/**
 * ONE answer to "what shape is this table" — for the renderer, the editor and
 * the markdown exporter alike.
 *
 * Every table field is optional in the format, and the file may have been
 * written by hand, by an agent, or by a build that is not this one. So a ragged
 * `rows`, a `cols` of the wrong length, and a `rows` that is not an array at
 * all are ordinary inputs here rather than errors.
 *
 * It normalises AT READ TIME and never by rewriting the document — the same
 * choice `effectiveParents` makes, for the same reason: two readers of one file
 * agree without exchanging an op, and merely opening a space repairs nothing.
 */
export function tableOf(b: Block): TableShape {
  const raw = Array.isArray(b.rows) ? (b.rows as unknown[]) : []
  const asRow = (r: unknown): string[] =>
    (Array.isArray(r) ? r : []).slice(0, TABLE_MAX_COLS).map((c) => (typeof c === 'string' ? c : ''))
  let rows = raw.slice(0, TABLE_MAX_ROWS).map(asRow)
  const w = Math.max(1, ...rows.map((r) => r.length))
  rows = rows.map((r) => (r.length === w ? r : [...r, ...Array(w - r.length).fill('')]))
  if (!rows.length) rows = [Array(w).fill('')]
  const num = (v: unknown): number => (typeof v === 'number' && v > 0 && Number.isFinite(v) ? v : 1)
  const src = Array.isArray(b.cols) ? (b.cols as unknown[]) : []
  const cols = Array.from({ length: w }, (_, i) => num(src[i]))
  const al = Array.isArray(b.colAlign) ? (b.colAlign as unknown[]) : []
  const colAlign = Array.from({ length: w }, (_, i) =>
    al[i] === 'left' || al[i] === 'center' || al[i] === 'right' ? String(al[i]) : '')
  return { rows, cols, colAlign, header: b.header !== false, w, h: rows.length }
}

/**
 * What a build that has never heard of a `table` block shows.
 *
 * The format is additive forever, and for a block TYPE additive means the
 * unknown type falls back to rendering its `html` (spaces/README.md). So a
 * table keeps one — derived, rewritten on every edit, never authored.
 *
 * It is the cells' OWN INLINE HTML joined, not their plain text: a `#p/` link
 * in a cell then still produces a backlink (buildIndex reads `html`), still
 * turns up in ⌘F, and still exports from an older build as a link rather than
 * as a bare word.
 *
 * It costs a second copy of the table's text in the file, and that is the price
 * of a permanent format. The alternative is a table that VANISHES when the
 * space is opened by the build someone already has, which is not a trade worth
 * making for a few hundred bytes.
 */
export function tableFallbackHtml(rows: string[][]): string {
  return rows.map((r) => r.filter((c) => c.trim()).join(' · ')).filter(Boolean).join('<br>')
}

/**
 * Write a shape back onto a block — the ONE writer, so `html` can never drift
 * from `rows`.
 *
 * Defaults are OMITTED rather than written: equal columns store no `cols`, no
 * alignment stores no `colAlign`, a header stores no `header`. A table built
 * here and a table parsed out of a pipe table are then the same bytes, and the
 * minimal hand-written `{ type: 'table', rows: [[…]] }` is a first-class
 * document rather than something this build would "fix" on the next edit.
 */
export function writeTable(b: Block, t: Pick<TableShape, 'rows' | 'cols' | 'colAlign' | 'header'>): void {
  b.rows = t.rows
  if (t.cols.some((c) => c !== t.cols[0])) b.cols = t.cols
  else delete b.cols
  if (t.colAlign.some(Boolean)) b.colAlign = t.colAlign
  else delete b.colAlign
  if (t.header) delete b.header
  else b.header = false
  b.html = tableFallbackHtml(t.rows)
}

/** A link card, with every field already decided. */
export interface LinkCard {
  /** '' when the stored url is not an outward link — then the card is not clickable */
  url: string
  /** never '' when there is a url: it falls back to the url itself */
  title: string
  desc: string
  /** stored, else the url's host */
  site: string
  /** an emoji or a short mark, capped */
  icon: string
  /** '' unless the thumbnail is local (`asset:` or `data:`) */
  image: string
}

/**
 * What a `link` block SHOWS — resolved here, once, for every surface.
 *
 * EVERYTHING IS ALREADY IN THE FILE. There is no fetch on this path and there
 * cannot be one: PLATFORM §1 says a document needs no network to open, and
 * "A space does not phone home when it is opened" (DECISIONS, 2026-08-03) says
 * it in this app's own words. A link card in Notion or Slack is a server
 * fetching OpenGraph tags; a link card here is what the author typed. So this
 * function's whole job is falling back gracefully — a card with three empty
 * fields still has to be a working link, and a card with no url at all still
 * has to be something a reader can look at without wondering what broke.
 *
 * PURE and DOM-FREE, so the fallbacks are testable in node — including the
 * negative one, that a remote `image` yields no src for a renderer to load.
 */
export function linkCard(b: Block): LinkCard {
  const url = externalHref(b.url)
  const title = String(b.title ?? '').trim()
  const site = String(b.site ?? '').trim()
  const image = String(b.image ?? '')
  return {
    url,
    // the url is the honest headline for an untitled card: a reader can see
    // where it goes, which is the one thing a link has to say
    title: title || url,
    desc: String(b.desc ?? '').trim(),
    site: site || hostOf(url),
    // capped because it is drawn in a fixed slot and it comes from a file
    // someone mailed you — a 400-character "emoji" is a layout attack
    icon: String(b.icon ?? '').trim().slice(0, 8),
    image: image && !isRemote(image) ? image : '',
  }
}

/**
 * The card's READABLE FORM, as `Block.html`.
 *
 * The same contract a `prop` block keeps, for the same reason: `html` is what a
 * build that has never heard of this type renders (render.ts's default case),
 * so a card written today is still a working link in a shell built last year.
 * Format additivity is a promise about what OLD builds do, and it is only kept
 * by writing the fallback at the same moment as the fields.
 *
 * Every path that sets a card's fields goes through the one writer that also
 * calls this (editor.applyLinkCard), so the two cannot fall out of step.
 */
export function linkCardHtml(c: LinkCard): string {
  const tail = c.desc ? ` — ${esc(c.desc)}` : ''
  if (!c.url) return esc([c.title, c.desc].filter(Boolean).join(' — '))
  return `<a href="${esc(c.url)}">${esc(c.title || c.url)}</a>${tail}`
}

/** The host part of a url, or '' — parsing, never a lookup. */
function hostOf(url: string): string {
  if (!url) return ''
  try { return new URL(url).host.replace(/^www\./, '') } catch { return '' }
}