Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Document state, undo history, and the TYPING RUN.
//
// Slides sidesteps commit granularity because canvas text commits on blur. A
// notes app may never blur, so this one policy sets undo granularity, autosave
// churn, the dirty flag, and later the collaboration op rate.
//
// A TYPING RUN is consecutive input in ONE block with no structural op between.
// It takes ONE checkpoint, at its first input; later inputs mutate in place. It
// closes on idle, on the caret leaving the block, on any structural change, on
// save, and on replaceDoc. One run = one undo entry = later, one text batch.
type Scope = 'doc' | 'page'
import { type SpacesDoc, type Page, type Block, buildIndex, type SpaceIndex, homePage } from './model'
import { buildTagIndex, type TagIndex } from './tags.ts'
import {
FROM_LIVE, applyRestore, validateRestoreRules, type RestoreDirection, type RestoreRules,
} from '../../kernel/src/docfields.ts'
import { SPACES_FIELDS } from './docclass.ts'
import { trailRecover } from './trail.ts'
import { revisionsRecover } from './history.ts'
type Listener = () => void
type Event = 'doc' | 'page' | 'tree' | 'selection' | 'dirty'
/** Idle that closes a run. Autosave debounces longer, so no snapshot lands mid-run. */
const RUN_IDLE_MS = 600
/** Undo is bounded by BYTES, not entries: at 200 pages, 100 whole-document
* snapshots retain tens of MB. Assets are excluded from snapshots entirely. */
const UNDO_BUDGET = 24 * 1024 * 1024
/**
* Top-level keys a whole-document restore ALWAYS takes from the LIVE document,
* never from what it restores: undo, redo, and every replaceDoc (version
* history, the recovery banner, Replace from JSON, bento.loadDoc).
*
* These are who the space IS and what this copy may do, not what it says:
* · `docId` — identity (PLATFORM §3). A snapshot taken before "Duplicate as
* a new space" or pasted from another file must not make this
* space claim somebody else's id, its versions and its room.
* · `collab` — the live-session capability and its on/off switch. A
* snapshot from before Stop sharing would silently rejoin the
* room; one from before Rotate keys would resurrect a revoked key.
* · `readonly` — the file's sealed-reading-copy mode. Undo must not unfreeze it.
* · `template` — a file mode that RE-MINTS `docId` on every open (model.ts),
* so it governs identity: pasted or restored, it would make
* this space a new document each time it is opened.
*
* NOT on the list, deliberately: `theme` (and any design setting) is content
* and undoes like content; `format`/`version`/`policy` describe how the content
* is encoded and travel with it; `assets` is kept by undo/redo for a different
* reason — snapshots omit it for size (UNDO_RULES) — and a replaceDoc brings
* its own.
*
* The list is the kernel's (kernel/src/docfields.ts) and is re-exported here;
* what ENFORCES it now is the field map's classes (identity / mode /
* capability, docclass.ts) through `applyRestore`, whose floor keeps those
* classes live in every direction and refuses an override that says otherwise.
*/
export { FROM_LIVE }
/**
* THE restore rules: one map, one call (`applyRestore`), two directions.
*
* 'back' — undo, redo, a version restore (either timeline), Replace from
* JSON and bento.loadDoc. Content follows what is restored (an
* ABSENT content field is dropped — a restored version is the
* whole document); identity, modes, capability AND history keep
* the live value. History is a LOG of the space (`revisions`,
* `trail`), not its content: without that, ⌘Z after a save
* un-recorded the revision that save wrote, a paste of Copy
* document JSON (which carries no history) deleted it, and a
* pasted or restored document could INSTALL a forged one.
* 'recover' — the crash-recovery banner only. The snapshot is a NEWER copy of
* this space, so history is reconciled with it rather than kept:
* `revisions` follows the snapshot when it carries a READABLE
* list, is REMOVED when the snapshot has none (a whole snapshot
* without it was CLEARED — the kernel's default since #726), and
* a foreign list on either side keeps live (history.ts
* `revisionsRecover`); `trail` unions by day (trail.ts
* `trailRecover`), so an absent trail keeps the live rows.
* Content absent from the snapshot was removed and stays removed
* (RECOVER_RULES, wholeSnapshot).
*
* Identity, mode and capability are live in BOTH directions; the kernel's floor
* holds that even against a mistaken override.
*/
export const RESTORE_RULES: RestoreRules = {
classes: SPACES_FIELDS,
recover: { trail: trailRecover, revisions: revisionsRecover },
}
validateRestoreRules(RESTORE_RULES)
/**
* The recovery banner's rules: RESTORE_RULES with `wholeSnapshot: true`,
* stated EXPLICITLY although the kernel (#716) defaults to it. The recovery
* snapshot is kernel autosave's `contentOnly(doc)` — the WHOLE document — so a
* content or unknown key absent from it is one the person REMOVED after the
* last save (a design, footnotes, a journal template), and it must stay
* removed rather than come back from the file. History is exempt in the
* kernel (an absent `trail`/`revisions` still keeps live), and the identity /
* mode / capability floor is unchanged. Only 'recover' reads the flag; every
* 'back' path already drops an absent field.
*/
export const RECOVER_RULES: RestoreRules = {
...RESTORE_RULES,
wholeSnapshot: true,
// Since kernel #726 a whole snapshot REMOVES an absent history key (absent =
// the person cleared it). That is right for `revisions` — cleared history
// must stay cleared, so it is deliberately NOT listed here — but not for
// `trail`: nobody "clears" a trail by omission; a snapshot without one means
// "no rows yet" (recorded nothing before the crash), and the live rows are
// observations nobody can recompute. ONLY 'trail', never 'revisions'.
// This list is the ONE thing keeping cleared history cleared on recovery
// (spaces no longer normalises an absent `revisions` itself):
// scripts/test-spaces-restore.ts pins it to exactly ['trail'] and proves a
// variant listing 'revisions' brings cleared drafts back.
keepLiveWhenAbsent: ['trail'],
}
validateRestoreRules(RECOVER_RULES)
/** The rules a direction restores by: the recovery banner's for 'recover'
* (the only caller of that direction), the shared ones for 'back'. */
export const rulesFor = (direction: RestoreDirection): RestoreRules =>
direction === 'recover' ? RECOVER_RULES : RESTORE_RULES
/**
* Undo and redo only. Their checkpoints OMIT `assets` (the largest thing in the
* document, and unchanged by an ordinary edit — see `snapshot()`), and
* `applyRestore` on 'back' reads an absent content field as DROPPED. Fed a
* checkpoint as-is it would delete every embedded image. So on this one path
* the pool keeps the LIVE value — exactly what undo did before the kernel took
* over: undoing an image insert removes the block's `asset:` reference, never
* the bytes (the pool is pruned on save, where nothing else can still be
* pointing at it). Version restore and Replace from JSON carry their own pool,
* so there `assets` follows like any content.
*/
const UNDO_RULES: RestoreRules = { ...RESTORE_RULES, keepLive: { assets: 'live' } }
validateRestoreRules(UNDO_RULES)
/** The whole-doc times a recover hook compares, as epoch ms on both sides
* (kernel `RecoverHook`): the live document's `modified`, and the snapshot's
* own time. A live space with no `modified` gives `live: undefined`, which the
* hook treats as OLDER. */
export function restoreAt(live: SpacesDoc, incomingAt?: number): { live?: number; incoming?: number } {
const l = typeof live.modified === 'string' ? Date.parse(live.modified) : NaN
return {
live: Number.isFinite(l) ? l : undefined,
incoming: typeof incomingAt === 'number' && Number.isFinite(incomingAt) ? incomingAt : undefined,
}
}
/** History-class keys (docclass.ts: `revisions`, `trail`), read from the map so
* a history field added later is omitted from undo checkpoints the same way. */
const HISTORY_KEYS: readonly string[] = Object.entries(SPACES_FIELDS)
.filter(([, cls]) => cls === 'history').map(([k]) => k)
/**
* One undoable step.
*
* A `page` entry holds ONE page's JSON; a `doc` entry holds the whole document
* minus its assets. The distinction is the difference between an undo history
* that survives a real document and one that does not: measured on a 200-page,
* 2.5 MB handbook, whole-document entries gave a depth of NINE — fifty edits,
* and you can take back the last nine — because every checkpoint stringified
* 2.5 MB against a 24 MB budget. The same budget holds hundreds of page
* entries, and a page entry costs ~12 KB rather than 2.5 MB to take.
*
* DOC IS THE DEFAULT, and page scope is opted into. A page entry restores one
* page by id and leaves the rest of the document alone, so it is only correct
* when the mutation touched nothing else — the caller knows that and the store
* cannot cheaply check it. Defaulting the other way would corrupt undo for any
* caller that forgot.
*/
type Entry =
| { kind: 'doc'; json: string; viewId: string }
| { kind: 'page'; pageId: string; json: string; viewId: string }
export class Store {
doc: SpacesDoc
index: SpaceIndex
/**
* Every `#tag` in the prose, derived and LAZY.
*
* Lazy because `touch()` reindexes on every keystroke of a typing run, and a
* tag index is a second full scan of every block in the document. Nothing
* reads it per-keystroke — the chips a render draws come from the text in
* front of them, not from here — so it is built when something asks (a view
* sourced on a tag, ⌘K, the graph, the tag sheet) and dropped whenever the
* document changes. Same derived-never-stored rule as `index`, one less full
* pass per keystroke.
*/
get tags(): TagIndex { return (this.tagIx ??= buildTagIndex(this.doc)) }
private tagIx: TagIndex | null = null
/** the page being viewed */
pageId: string
/** blocks currently selected at block level (Esc from text editing) */
selection: string[] = []
readOnly = false
/**
* Unsaved changes.
*
* The header comment above has claimed since 0.1.0 that this policy sets
* "the dirty flag", and there was no dirty flag — so the Save button could
* not say whether it needed pressing, which in a format whose whole promise
* is "the file IS the document" is the one thing it should say.
*/
dirty = false
/** Every mutation, even within a typing run or while already dirty. */
revision = 0
private undoStack: Entry[] = []
private redoStack: Entry[] = []
private listeners = new Map<Event, Set<Listener>>()
private runBlock: string | null = null
private runTimer: ReturnType<typeof setTimeout> | undefined
constructor(doc: SpacesDoc) {
this.doc = doc
this.index = buildIndex(doc)
this.pageId = homePage(doc)?.id ?? ''
}
// ---- events -------------------------------------------------------------
on(ev: Event, fn: Listener): () => void {
const set = this.listeners.get(ev) ?? new Set()
set.add(fn)
this.listeners.set(ev, set)
return () => set.delete(fn)
}
emit(ev: Event): void {
if (ev === 'doc') this.revision++
for (const fn of this.listeners.get(ev) ?? []) fn()
}
// ---- reads --------------------------------------------------------------
get page(): Page | undefined {
return this.index.page.get(this.pageId)
}
block(id: string): Block | undefined {
return this.index.block.get(id)?.block
}
/** Pages in sidebar order: a depth-first walk of the page tree. */
/**
* The page tree, for the sidebar and the Markdown export.
*
* `seen` is not defensive tidiness. `buildIndex` bins pages by `parent` with
* no position test, and two people concurrently dragging pages onto each
* other converge on A.parent=B, B.parent=A — legal for each of them, a cycle
* together. Neither page is then reachable from the root, so BOTH VANISH from
* the sidebar and from the Markdown export while still sitting in the file,
* and nothing says so. Worse, a subtree call from inside the cycle recurses
* until the stack gives out.
*
* A cyclic group is surfaced at the ROOT rather than hidden: pages you can
* see and re-home beat pages that quietly stopped existing.
*/
tree(parent = '', depth = 0, seen: Set<string> = new Set()): Array<{ page: Page; depth: number }> {
const out: Array<{ page: Page; depth: number }> = []
for (const p of this.index.children.get(parent) ?? []) {
if (seen.has(p.id)) continue
seen.add(p.id)
out.push({ page: p, depth })
out.push(...this.tree(p.id, depth + 1, seen))
}
// Anything a cycle kept off the root walk, listed rather than lost.
if (parent === '' && depth === 0) {
for (const p of this.doc.pages) {
if (p.archived || seen.has(p.id)) continue
seen.add(p.id)
out.push({ page: p, depth: 0 })
}
}
return out
}
// ---- writes -------------------------------------------------------------
/**
* A structural change: one undoable step. Closes any open typing run first,
* so the run's text and the structural edit never merge into one entry.
*/
commit(mutate: () => void, opts: { structure?: boolean; scope?: Scope } = {}): void {
if (this.readOnly) return
this.endRun()
this.checkpoint(opts.scope ?? 'doc')
mutate()
this.dirty = true
this.reindex()
this.emit('doc')
if (opts.structure !== false) this.emit('tree')
}
/**
* An input inside a typing run. The FIRST input in a block checkpoints;
* every later one mutates in place.
*/
runEdit(blockId: string, mutate: () => void): void {
if (this.readOnly) return
if (this.runBlock !== blockId) {
this.endRun()
// A typing run is one block in the page in view, by definition — the
// cheapest and by far the most common checkpoint there is.
this.checkpoint('page')
this.runBlock = blockId
}
mutate()
this.touch()
clearTimeout(this.runTimer)
this.runTimer = setTimeout(() => this.endRun(), RUN_IDLE_MS)
}
/** Close the current run, if any. Idempotent. */
endRun(): void {
clearTimeout(this.runTimer)
if (!this.runBlock) return
const id = this.runBlock
this.runBlock = null
this.emit('doc')
void id
}
/** Model changed without a new undo entry (mid-run). */
touch(): void {
this.revision++
// A typing run deliberately does NOT emit 'doc' per keystroke — that is the
// whole point of the run. But the FIRST keystroke changes something the
// reader can see: the file now differs from the disk. Announce that once,
// on the transition only, or the unsaved dot does not appear until the run
// closes 600ms later and the button lies for as long as you keep typing.
const wasClean = !this.dirty
this.dirty = true
this.doc.modified = new Date().toISOString()
this.reindex()
if (wasClean) this.emit('doc')
}
/**
* Set the unsaved flag from outside a commit.
*
* The kernel session calls this after applying a REMOTE change: the document
* on screen now differs from the file on disk, which is true however the
* change arrived. It is deliberately separate from the `doc` event — this
* app reads `doc` as "you edited something" and paints "Edited" from it, so
* a colleague's keystroke must move the dot without claiming to be yours.
*/
setDirty(v: boolean): void {
// Remote apply calls this even when the dirty flag is already set.
if (v) this.revision++
if (this.dirty === v) return
this.dirty = v
// NOT 'doc'. The editor reads 'doc' as "you edited something" and paints
// "Edited" from it; a colleague's keystroke must move the unsaved dot
// without claiming to be yours. 'dirty' carries the dot and nothing else.
this.emit('dirty')
}
/**
* Rebuild the id index, and fall back to the home page if the page being
* viewed no longer exists.
*
* PUBLIC because a remote collaborator's edit lands on `doc` directly —
* bypassing commit, deliberately, so it never joins this person's undo
* stack — and every `block(id)` / `page` read after that would otherwise
* answer from a stale index. sync/session.ts calls it. It was private while
* the only writer was the store itself.
*/
reindex(): void {
this.index = buildIndex(this.doc)
this.tagIx = null
if (!this.index.page.has(this.pageId)) this.pageId = homePage(this.doc)?.id ?? ''
}
// ---- history ------------------------------------------------------------
private snapshot(): string {
// assets are excluded: they are the largest thing in the document and never
// change during an ordinary edit, so snapshotting them 100 times is waste.
// History fields are excluded too; 'back' keeps them live (RESTORE_RULES).
// That includes `trail`: a row is an OBSERVATION written outside any
// commit, so an undo that restored it could put a stale row over a newer
// one. `periods` is content, NOT excluded: starting a period is something a
// person did, inside a commit, and ⌘Z takes it back like any other edit.
const { assets: _assets, ...rest } = this.doc as Record<string, unknown>
for (const k of HISTORY_KEYS) delete rest[k]
return JSON.stringify(rest)
}
/** An entry for the state as it is NOW, at the requested scope. */
private entry(scope: Scope): Entry {
if (scope === 'page') {
const page = this.index.page.get(this.pageId)
// no page in view is not a page-scoped edit — fall back rather than
// record an entry that restores nothing
if (page) return { kind: 'page', pageId: page.id, json: JSON.stringify(page), viewId: this.pageId }
}
return { kind: 'doc', json: this.snapshot(), viewId: this.pageId }
}
checkpoint(scope: Scope = 'doc'): void {
if (this.readOnly) return
this.undoStack.push(this.entry(scope))
this.redoStack.length = 0
let bytes = 0
for (let i = this.undoStack.length - 1; i >= 0; i--) {
bytes += this.undoStack[i].json.length
if (bytes > UNDO_BUDGET) { this.undoStack.splice(0, i + 1); break }
}
}
private restore(entry: Entry): void {
this.dirty = true
if (entry.kind === 'page') {
const at = this.doc.pages.findIndex((p) => p.id === entry.pageId)
// The page can be gone if a later doc-level step removed it. Undo runs in
// order, so the step that removed it is undone FIRST and the page is back
// by the time this entry is reached — but a hand-built history could
// reach here, and dropping the entry is better than throwing.
if (at >= 0) this.doc.pages[at] = JSON.parse(entry.json) as Page
} else {
// CONTENT moves, identity does not: the snapshot's docId/collab/readonly
// are whatever they were when it was taken, and Stop sharing, a key
// rotation or a mode change since then must survive ⌘Z and ⌘⇧Z alike.
// 'back', with the pool kept live: the checkpoint has no `assets` key
// (UNDO_RULES says why), and absent-means-dropped would empty it.
this.doc = applyRestore(this.doc, JSON.parse(entry.json) as SpacesDoc, 'back', UNDO_RULES)
}
this.pageId = entry.viewId
this.reindex()
this.emit('doc')
this.emit('tree')
this.emit('page')
}
undo(): void {
if (this.readOnly) return
this.endRun()
const entry = this.undoStack.pop()
if (!entry) return
// the inverse entry is taken at the SAME scope, or redo would restore a
// whole document over a one-page change
this.redoStack.push(this.entry(entry.kind))
this.restore(entry)
}
redo(): void {
if (this.readOnly) return
this.endRun()
const entry = this.redoStack.pop()
if (!entry) return
this.undoStack.push(this.entry(entry.kind))
this.restore(entry)
}
get canUndo(): boolean { return this.undoStack.length > 0 }
get canRedo(): boolean { return this.redoStack.length > 0 }
// ---- navigation ---------------------------------------------------------
goToPage(id: string, opts: { push?: boolean } = {}): void {
if (!this.index.page.has(id) || id === this.pageId) return
this.pageId = id
this.selection = []
this.endRun()
if (opts.push !== false && typeof history !== 'undefined') {
// pushState with a FRAGMENT is legal from an opaque origin; pushState
// with a PATH throws SecurityError there. Measured — this is why links
// are fragments (docs/DECISIONS.md, 2026-08-03).
try { history.pushState(null, '', `#p/${id}`) } catch { /* opaque origin edge */ }
}
this.emit('page')
this.emit('tree')
}
select(ids: string[]): void {
this.selection = ids
this.emit('selection')
}
/**
* Replace the whole document — the AI round-trip, version restore and
* recovery path. Content is replaced; identity is not (FROM_LIVE): a version
* from before Stop sharing or Rotate keys, or JSON pasted from another space,
* never brings its own docId, room credentials or file mode with it.
*
* `direction` is REQUIRED, so no caller gets one by default: 'recover' for
* the crash-recovery banner (with `at` from `restoreAt`), 'back' for
* everything else (RESTORE_RULES). Untrusted input is gated BEFORE it gets
* here (restoregate.ts); this only decides which side each field comes from.
*/
replaceDoc(next: SpacesDoc, direction: RestoreDirection, at: { live?: number; incoming?: number } = {}): void {
this.dirty = true
this.endRun()
this.checkpoint()
this.doc = applyRestore(this.doc, next, direction, rulesFor(direction), at)
this.reindex()
this.pageId = homePage(next)?.id ?? ''
this.emit('doc')
this.emit('tree')
this.emit('page')
}
}