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
// Boot sequence for bento/spaces. Order matters: configure the app, then
// capture the pristine document BEFORE any DOM mutation — the captured copy is
// what gets re-serialized on save.
import { SaveQueue } from '../../kernel/src/savequeue.ts'
import { saveRevision } from './saving'
import './styles.css'
// AFTER styles.css: a design rule and the base rule it restyles often tie on
// specificity, and the tie goes to the later sheet.
import './designs.css'
import { configureApp } from '../../kernel/src/app.ts'
import { startTheme } from '../../kernel/src/theme.ts'
import {
capturePristine, readEmbeddedDoc, serializeFile, serializeAuto, registerPreview,
saveFile, parseEnvelope, canWriteInPlace, decryptEnvelope, setEncryptionPassword,
writeUpdatedFileAs, suggestedFileName,
isBodySealed,
} from '../../kernel/src/save.ts'
import { setTabTitle, setNeutralTabTitle } from './tabtitle.ts'
import { putRecovery, getRecovery, clearRecovery, clearVersions, pruneOld, addVersion } from '../../kernel/src/autosave.ts'
import { APP_VERSION, applyUpdateInPlace } from '../../kernel/src/update.ts'
import { t, locale, applyDirection } from './i18n'
import { i18nApi } from '../../kernel/src/i18n.ts'
import { parseDoc, uid, newPage, type SpacesDoc, type ParseResult } from './model'
import { recoveryOffered, recoverInto, replaceFromJson } from './restoregate'
import { recoveryBanner, wireRecoveryOff, type RecoveryAction } from './recoverynotice'
import { recordTrail } from './observe.ts'
import { protectedDays } from './periods.ts'
import {
validateDoc, outlineDoc, statsDoc,
planInsertBlocks, planUpdateBlock, planRemoveBlocks, planMoveBlock, planUpdatePage, planRemovePage,
fieldsReport, issuesReport, planSetField, planNewIssue, commentsReport,
plainTitle, badTitle,
type Plan, type PlanError, type IssueQuery, type CommentQuery,
} from './agent'
import { starterDoc } from './starter'
import { mentionsOf, mentionIndex } from './mentions.ts'
import { todayISO, isISO, journalFor } from './journal'
import { textOf } from './sanitize'
import { evaluate, format, pageContext } from './calc'
import { buildSpacePreview } from './preview'
import { Store } from './store'
import { Editor } from './editor'
import { SyncSession } from './sync/session.ts'
import { isReaderCopy, stampSync } from './share.ts'
import { recordOnSave } from './history.ts'
import { projectForCopy } from '../../kernel/src/docfields.ts'
import { SPACES_FIELDS } from './docclass.ts'
import { downloadMarkdown, launchUpdateCheck } from './about'
configureApp({
appId: 'bento-spaces',
appName: 'bento/spaces',
manifestUrl: 'https://bento.page/releases/spaces/manifest.json',
})
// Every save writes a still render of the home page into the shell, for the
// readers that run no script: macOS QuickLook, iOS Files, bento/home, and any
// preview pane that renders HTML without executing it. Without this the runtime
// never inflates, the splash is never removed, and a saved space shows a boot
// animation where its content should be. See preview.ts.
registerPreview((doc) => buildSpacePreview(doc as unknown as SpacesDoc))
capturePristine()
// The interface theme: AFTER capturePristine, before the first paint.
//
// AFTER, because capturePristine clones the LIVE document and every save
// re-serializes that clone — so `data-theme` and `color-scheme` must not be on
// <html> yet, or a reader's preference would ride inside every file they save
// and land on whoever they sent it to. Exactly the ordering applyDirection
// depends on for dir/lang, one line below, and for the same reason.
//
// BEFORE the paint, because applying it later paints the interface light and
// then flips it, which reads as a bug rather than as a preference. Nothing
// here lays anything out: it sets two attributes on the root element.
startTheme()
applyDirection()
const embedded = readEmbeddedDoc()
const envelope = embedded ? parseEnvelope(embedded) : null
if (envelope) {
// MOUNTED, though locked. The shell's loader (scripts/postbuild-compress.mjs)
// decides whether this app started by looking for `window.bento`; a space
// waiting at its password gate has no document to publish yet, so without
// this every loader path read as a failure, each one ran the app AGAIN (a
// second and third gate), and the loader's failure card covered the lot — an
// encrypted space could not be opened at all. `locked` is the suite's agreed
// shape (slides and type set the same); the real object replaces it on unlock.
;(window as unknown as { bento: unknown }).bento = { format: 'bento/spaces', locked: true }
void passwordGate()
} else {
const res = parseDoc(embedded ?? '')
if (res.ok) {
if (!res.doc.docId) res.doc.docId = uid('doc')
boot(res.doc, res.repaired, res.frozen)
} else if (res.err === 'empty') {
// THE ONLY path to the starter. Anything else that failed to parse is
// someone's data, and replacing it with an empty space would be a loss the
// first ⌘S makes permanent.
const doc = starterDoc()
doc.docId = uid('doc')
boot(doc, [], undefined)
} else {
// MOUNTED, though refused — the same reason as `locked` above: without it
// the loader reads "no app", runs the app again on every path (one refusal
// card per path) and paints its own failure over the explanation this file
// owes its reader. `refused` is the suite's shape (DECISIONS 2026-10-17).
;(window as unknown as { bento: unknown }).bento = { format: 'bento/spaces', refused: true }
refuse(res)
}
}
/**
* An encrypted space: ask, then boot.
*
* This MUST exist for as long as the About dialog can set a password —
* otherwise encrypting a space locks its author out of it permanently, which
* is the worst bug this app could have. The password is held in memory so
* every later save stays encrypted.
*/
async function passwordGate(): Promise<void> {
// neutral title while sealed, matching the saved file's title
setNeutralTabTitle()
document.getElementById('bento-splash')?.remove()
const wrap = document.createElement('div')
wrap.className = 'sp-gate'
const card = document.createElement('div')
card.className = 'sp-gate-card'
card.innerHTML = `<h1>${t('This space is locked')}</h1>` +
`<p>${t('Enter the password to open it.')}</p>`
const input = document.createElement('input')
input.type = 'password'
input.className = 'sp-find'
input.autocomplete = 'current-password'
const go = document.createElement('button')
go.className = 'sp-btn sp-primary'
go.textContent = t('Unlock')
const err = document.createElement('p')
err.className = 'sp-note'
card.append(input, go, err)
wrap.append(card)
document.body.append(wrap)
input.focus()
const tryUnlock = async () => {
const pass = input.value
if (!pass) return
go.disabled = true
const json = await decryptEnvelope(envelope!, pass)
go.disabled = false
if (json === null) { err.textContent = t('Wrong password — try again'); input.select(); return }
const res = parseDoc(json)
if (!res.ok) { err.textContent = t('Unlocked, but the document inside could not be read.'); return }
// held in memory so ⌘S and autosave keep writing encrypted
setEncryptionPassword(pass)
wrap.remove()
if (!res.doc.docId) res.doc.docId = uid('doc')
boot(res.doc, res.repaired, res.frozen)
}
go.addEventListener('click', () => { void tryUnlock() })
input.addEventListener('keydown', (e) => { if (e.key === 'Enter') void tryUnlock() })
}
/**
* A document we cannot read is NOT a reason to show an empty one.
*
* No editor, no autosave, and two ways out that do not require us to have
* understood the file: keep the bytes exactly as they are, or take the JSON
* somewhere else.
*/
function refuse(res: Extract<ParseResult, { ok: false }>): void {
const detail = 'detail' in res ? res.detail : ''
const what = res.err === 'format'
? t('This is not a bento/spaces document — {detail}.', { detail })
: res.err === 'json'
? t('The document block is not valid JSON — {detail}.', { detail })
: t('The document block is not shaped like a space — {detail}.', { detail })
gate(t('This file could not be opened'), what, [
[t('Save an untouched copy…'), () => {
// the bytes as they are, NOT a re-serialization: we did not understand
// this document, so we must not rewrite it
const html = `<!DOCTYPE html>\n${document.documentElement.outerHTML}`
const a = document.createElement('a')
a.href = URL.createObjectURL(new Blob([html], { type: 'text/html' }))
a.download = 'untouched-copy.bento.html'
a.click()
}],
[t('Copy the document JSON'), () => { void navigator.clipboard?.writeText(embedded ?? '') }],
])
const pre = document.createElement('pre')
pre.className = 'sp-gate-raw'
pre.textContent = (embedded ?? '').slice(0, 400)
document.querySelector('.sp-gate-card')?.append(pre)
}
function gate(title: string, body: string, actions: Array<[string, () => void]>): void {
document.getElementById('bento-splash')?.remove()
const wrap = document.createElement('div')
wrap.className = 'sp-gate'
const card = document.createElement('div')
card.className = 'sp-gate-card'
const h = document.createElement('h1')
h.textContent = title
const p = document.createElement('p')
p.textContent = body
card.append(h, p)
for (const [label, fn] of actions) {
const b = document.createElement('button')
b.className = 'sp-btn sp-primary'
b.textContent = label
b.addEventListener('click', fn)
card.append(b)
}
wrap.append(card)
document.body.append(wrap)
}
function boot(doc: SpacesDoc, repaired: string[], frozen?: 'policy' | 'version'): void {
setTabTitle(doc.title)
document.getElementById('bento-splash')?.remove()
const store = new Store(doc)
const saves = new SaveQueue({ getDocument: () => store.doc, getRevision: () => store.revision })
// `doc.readonly` was declared in the format and read by NOTHING: a space
// saved as a reading copy opened fully editable, so the one property the
// sender chose was the one the file did not keep. It is not a security
// boundary — anyone can edit the JSON — but a file that says it is a reading
// copy must behave like one for the person who opens it.
//
// `frozen` is the other, unrelated reason to lock: this build does not
// understand the file and must not rewrite it.
//
// A collab role that cannot write — 'reader', 'audience', or one this build
// does not know (share.ts copyCanWrite, an allowlist) — is the THIRD, unrelated reason, and it is the
// only one of the three that keeps receiving: a view-only copy follows the
// live session and can never send to it. The lock here is a courtesy to the
// person holding it — the ENFORCEMENT is the relay, which pins a verified
// key per socket and drops op batches from a socket that presented none
// (docs/collab-design.md, "Signed writes"). Remote ops still land, because
// the kernel session applies them straight to `doc` rather than through
// `commit()` — deliberately, so a colleague's edit never joins this
// person's undo stack, and incidentally so `readOnly` cannot block it.
if (frozen || doc.readonly || isReaderCopy(doc)) store.readOnly = true
const editor = new Editor(document.getElementById('app')!, store)
// Live collaboration. Constructing the session is enough to make same-machine
// tabs of one file sync (BroadcastChannel, keyed on docId); the RELAY is not
// dialled here — the kernel's shareEligible() gate decides that, and it says
// connect only when the document ARRIVED carrying collab credentials (it was
// saved or shared) or the user opted in this session. A fresh starter space
// and a template tire-kicker stay dormant, which is the rule this app already
// wrote down: "A space does not phone home when it is opened".
const session = new SyncSession(store)
editor.connectSync(session)
// A view-only copy is asked about FIRST: the kernel's copy table marks it
// `readonly` as well (share.ts readerCopy), so a build that knows no roles
// still opens it locked — but it follows the session, and the banner says so.
if (!frozen && isReaderCopy(doc)) {
banner(t('This is a view-only copy — it follows the live session but can’t change this space.'))
} else if (!frozen && doc.readonly) {
// A FILE SAVED FOR READING OPENS AS ONE. `doc.readonly` alone only locked
// the store, so a reading copy arrived as the full editor with every
// control inert — which reads as a broken editor rather than as a
// document. reading.ts says what such a copy carries and what it does not.
// (A live view-only copy may carry `readonly` too, which is why the role is
// asked first: it follows the session, and it keeps the follows-live view.)
editor.enterReadingCopy()
banner(t('This is a reading copy. It opens for reading; nothing you do here changes the file.'))
}
if (frozen) {
banner(frozen === 'version'
? t('This file was written by a newer version of bento/spaces. It is open read-only so nothing is lost.')
: t('This file declares rules this build does not know. It is open read-only so nothing is lost.'))
}
if (repaired.length) {
banner(t('{n} duplicate or missing id(s) were repaired so links and pages resolve.', { n: repaired.length }))
}
editor.onSave = () => { void doSave() }
editor.onSaveAs = (suffix: string) => {
if (suffix === '__markdown') { downloadMarkdown(store); return }
store.endRun()
// "Save a copy…" must leave you editing the ORIGINAL. That is what the
// label promises, and the file you go on typing into should never silently
// become the backup you just took.
//
// This used to call saveFile(doc, true), under a comment claiming the
// kernel kept the in-place handle pointed at the working file. It does the
// opposite: saveFile ASSIGNS the picked handle to the module's in-place
// handle (kernel/src/save.ts), so every later ⌘S wrote to the copy while
// the original stayed frozen at the moment it was copied. The guarantee the
// comment described lives in writeUpdatedFileAs, whose keepHandle defaults
// to false — slides learned the same lesson when a share export became the
// ⌘S target and the next save overwrote it with the full document.
//
// The status line was dead too: saveFile returns 'saved-as' down the
// forcePicker path, never 'saved', so the confirmation never appeared.
//
// A copy of THIS space is this replica, so it carries the CRDT state like
// ⌘S does: opened later, it rejoins as a fork rather than a fresh adopt.
stampSync(store, session)
// tier 'file' of the kernel's copy table: the owner's own whole file,
// every field kept — taken through the table so no copy path is outside it
const copy = projectForCopy(store.doc, SPACES_FIELDS, 'file')
void serializeAuto(copy)
.then((html) => writeUpdatedFileAs(html, copy, { suffix: suffix === 'copy' ? 'copy' : suffix }))
.then((ok) => { if (ok) editor.status(t('Copy saved — you are still editing the original')) })
}
/**
* Write a DIFFERENT document out as its own file — the page extract.
*
* `serializeAuto`, not `serializeFile`: it is the encryption-aware path, so
* an extract taken out of a password-protected space is written encrypted
* with the same password the author is already holding. A page pulled out of
* an encrypted space arriving in the clear would defeat the encryption
* silently, on a file whose whole point is that it does not.
*
* `keepHandle` stays false (the default), which is the lesson slides paid
* for: an export that becomes the ⌘S target means the next save overwrites
* the extract with the whole document.
*/
editor.onExportSpace = async (out: SpacesDoc): Promise<boolean> => {
const html = await serializeAuto(out)
return writeUpdatedFileAs(html, out, { suggestedName: suggestedFileName(out) })
}
/**
* Write a SHARE copy — the invite, or the view-only follower.
*
* `out` is a DERIVED document (share.ts), never `store.doc`: that is the
* whole of the fix for "Invite someone…", which used to reach the ordinary
* copy path and therefore handed every recipient `collab.ownerPriv`.
*
* `serializeAuto`, so an invite taken out of a password-protected space is
* written encrypted with the password its author is already holding — a
* shared copy arriving in the clear would defeat the encryption silently.
*
* `keepHandle` stays false (the default), and here it is load-bearing rather
* than tidy: retaining the handle would make the NEXT ⌘S overwrite the copy
* that just left with the full document — owner key included. Slides paid
* for that lesson once already.
*/
editor.onShareCopy = async (out: SpacesDoc, suffix: string): Promise<boolean> => {
const html = await serializeAuto(out)
return writeUpdatedFileAs(html, out, { suffix })
}
// Two minutes, as in slides. Short enough that a long writing session leaves
// a usable trail, long enough that the cap is not spent on one afternoon.
const VERSION_EVERY_MS = 120_000
let lastVersionAt = 0
async function doSave(): Promise<void> {
// Every write of THIS file goes through `saves` (the in-place self-update
// too, below): the queue keeps two writes from overlapping on one handle,
// and saving.ts clears the dot only if nothing changed while the bytes were
// being written. The copies and share exports stay outside it on purpose —
// they write a DIFFERENT file and never keep its handle.
// collab.sync is stamped in the queue's prepare step: after any write
// ahead of this one, immediately before the snapshot is copied, so the
// state describes exactly the bytes that reach the file (#594).
//
// The in-file revision is recorded in the SAME step for the same reason
// (history.ts): it describes exactly the bytes written, and those bytes
// contain it. It writes doc.revisions directly — not through commit — so
// the store's revision does not move and this write is not made stale.
// Unconditional on encryption: revisions live inside #bento-doc, so the
// envelope encrypts them with the pages (unlike addVersion below).
const out = await saveRevision(store, saves, (snapshot) => saveFile(snapshot),
() => { stampSync(store, session); recordOnSave(store); editor.status(t('Saving…')) })
if (out.kind === 'failed') {
console.error('bento/spaces: save failed', out.error)
editor.status(t('Save failed — see console'))
return
}
if (out.kind !== 'written') { editor.status(''); return }
// A SAVE IS THE MOMENT WORTH KEEPING. The throttle below catches long
// editing runs, but the point somebody chose to write the file is the
// point they would most want back, so it is never throttled away. The
// version is the snapshot that was WRITTEN, not whatever is on screen now.
// Sealed spaces (a password or the identity seal) keep nothing here, for the
// reason putRecovery does not.
if (!isBodySealed()) { void addVersion(out.doc); lastVersionAt = Date.now() }
if (out.result === 'saved' && out.current) {
// Only when the disk holds what is on screen: after a stale write the
// recovery snapshot is the one copy of the newer edit.
void clearRecovery(out.doc.docId)
// "Saved" is doing real work here: on a browser without file-system
// access this was a NEW download, and saying so is the difference
// between understanding that and losing track of which copy is current
editor.status(canWriteInPlace() ? t('Saved') : t('Saved a new copy'))
} else {
editor.status('')
}
}
/**
* The in-place self-update rewrites the SAME file ⌘S does, so it takes the
* same queue: without it an update and a save could be open on one handle at
* once, and whichever closed last would decide which shell the file ends up
* as. It writes the queue's snapshot, and — like a save — clears the dot only
* when that snapshot is still the document on screen.
*/
editor.onUpdateInPlace = async (rel) => {
// stamped and recorded in prepare, beside the snapshot, exactly as ⌘S is
const saved = await saves.run(() => { store.endRun(); stampSync(store, session); recordOnSave(store) },
(snapshot) => applyUpdateInPlace(rel, snapshot))
if (!saved?.value) return null
if (saved.isCurrent()) store.setDirty(false)
return saved.value
}
/**
* Today's row, if this space is a tracker and this copy may write at all.
*
* A READER COPY AND A SEALED READING COPY WRITE NOTHING. `store.readOnly`
* covers both, and it is the same check every other writer in this app makes
* — a trail row is a write, and "opening a file does not modify it" has no
* exception for a write the app made up itself.
*/
const recordToday = (): void => {
if (store.readOnly) return
const today = todayISO()
recordTrail(store.doc, { today, protect: protectedDays(store.doc, today) })
}
// A recovery snapshot is the ONLY backstop on browsers with no file-system
// access — which is every browser on iOS.
//
// NEVER for an encrypted space. The snapshot is the document as plain JSON,
// so writing one puts in IndexedDB exactly what the password exists to keep
// off the disk — and it would do it every few seconds, for the one author who
// demonstrably cares. The kernel's putRecovery does not guard this; the
// caller must (slides has the same contract).
//
// RECOVERY IS NOT HISTORY. putRecovery keeps ONE snapshot per space — the
// answer to "the tab died", and nothing else. It is overwritten every few
// seconds, so it cannot answer "put back what I had before lunch", and undo
// cannot either: the undo stack lives in memory and dies with the reload.
// Spaces shipped with only the first of those, while slides and dash both
// keep a timeline. For the app people write PROSE in, that was the wrong one
// to leave out — a paragraph rewritten badly an hour ago was unrecoverable by
// any means the app offered.
//
// So a version is added on a throttle while editing, and unthrottled on save.
// The kernel caps and prunes the timeline; both stores stay empty while the
// body is sealed (a password or the identity seal).
let timer: ReturnType<typeof setTimeout> | undefined
store.on('doc', () => {
clearTimeout(timer)
// THE TRAIL IS WRITTEN ON CHANGE, NEVER ON OPEN, and on the debounce that
// already exists rather than on a second one. It runs BEFORE the encryption
// guard below, on purpose: `doc.trail` is a document field, so it is inside
// the `bento/enc` envelope and encrypted by the same pass over the same
// JSON. There is no plaintext artefact beside the ciphertext, so — unlike a
// recovery snapshot — there is nothing to refuse. An encrypted space keeps
// its charts.
//
// Outside `store.commit` deliberately: a record of an observation is not an
// editing step and does not belong in anybody's undo stack (store.ts's
// snapshot excludes it — `trail` is history class). It is never synced
// either (the kernel's sync shape skips history fields): each replica keeps
// its own record of what it saw, as each keeps its own `revisions`.
//
// Written DURING editing, not at save — so, unlike `revisions`, it counts
// toward the recovery key (docclass.ts SPACES_NOT_EDIT does not list it).
recordToday()
// isBodySealed, not isEncryptionActive: an identity-sealed space has no
// password, and its snapshot would be the same plaintext on disk.
if (isBodySealed()) return
timer = setTimeout(() => {
void putRecovery(store.doc)
if (Date.now() - lastVersionAt > VERSION_EVERY_MS) {
lastVersionAt = Date.now()
void addVersion(store.doc)
}
}, 2500)
})
void pruneOld()
void offerRecovery(doc, store, editor)
// A host that refuses the recovery copy (too large) turns crash recovery off
// for this space; say so once, where the save status shows, held long enough
// to read (slides holds it 8s). Never for a sealed space.
//
// `encrypted: isBodySealed` is redundant today: the autosave guard above
// (`if (isBodySealed()) return`) means a sealed space never asks for a
// recovery copy, so the kernel never fires for it. Kept on purpose; a
// mutation of this line alone stays green because that guard covers it,
// which is not a gap.
wireRecoveryOff({
docId: () => store.doc.docId,
encrypted: isBodySealed,
say: (msg) => editor.status(msg, 8000),
})
// ---- the AI round-trip (PLATFORM §7) -----------------------------------
//
// Every write verb is ONE undoable step, and every one of them runs its plan
// FIRST: `store.commit` checkpoints undo before it mutates, so planning
// inside the commit would leave an undo entry behind for a patch that was
// refused. A refused patch changes nothing at all, including history.
function run<T extends object>(plan: Plan<T>): ({ ok: true } & T) | PlanError {
if (store.readOnly) {
return { ok: false, err: 'readonly', detail: 'this file is open read-only; nothing was changed' }
}
if (!plan.ok) return plan
const { apply, ...rest } = plan
store.commit(apply)
editor.repaint()
return rest as { ok: true } & T
}
;(window as any).bento = {
format: doc.format,
get doc() { return store.doc },
get readonly() { return store.readOnly },
serialize: () => serializeFile(store.doc),
serializeAuto: () => serializeAuto(store.doc),
undo: () => { store.undo(); editor.repaint() },
redo: () => { store.redo(); editor.repaint() },
updates: { version: APP_VERSION },
/**
* i18n: t/locale/setLocale/choices, as slides exposes it.
*
* setLocale('x-pseudo') is the SWEEP AUDIT: every string that reached t()
* comes back bracketed and accented, so anything still in plain English is
* a string the extractor never saw and no catalog will ever carry. That is
* not hypothetical here — two aria-labels were sitting untranslated in this
* app, and the packer reported 100% the whole time, because a key that is
* never swept is a key the percentage cannot know about.
*
* Chrome only: page titles and block text are the document and must stay
* exactly as written.
*/
i18n: i18nApi,
/** open the graph view — the same thing the ⋯ menu opens */
graph: () => { editor.openGraph() },
/** every page, flat — the shape an agent wants before it reads anything */
pages: () => store.doc.pages.map((p) => ({
id: p.id, title: p.title, parent: p.parent, archived: !!p.archived, blocks: p.blocks.length,
})),
getPage: (id: string) => store.doc.pages.find((p) => p.id === id) ?? null,
search: (q: string) => {
const needle = String(q).toLowerCase()
const out: Array<{ pageId: string; title: string; blockId: string }> = []
for (const p of store.doc.pages) {
for (const b of p.blocks) {
// textOf DECODES entities; a tag-strip does not. On a block reading
// "a & b" the old regex searched "a & b", so it missed the
// text the reader can see and matched text that is not there.
const text = textOf(b.html)
if (text.toLowerCase().includes(needle)) out.push({ pageId: p.id, title: p.title, blockId: b.id })
}
}
return out
},
/** what is WRONG or SUSPECT — see agent.ts */
validate: (target?: SpacesDoc) => validateDoc(target ?? store.doc),
/** the whole space as a tree, for orienting in one call */
outline: (target?: SpacesDoc) => outlineDoc(target ?? store.doc),
/**
* Where this space names a page without linking to it.
*
* With a page id, that page's unlinked mentions; with none, every page's,
* as `{ pageId: Mention[] }`. READ ONLY — it reports, it does not link.
* Deciding that a sentence meant the page is a judgement, and an agent
* that silently rewrote a hundred blocks' html on a guess would be
* unreviewable. Link them with `updateBlock`, or leave them for the panel.
*/
mentions: (pageId?: string) => pageId
? mentionsOf(store.doc, store.index, pageId)
: Object.fromEntries(mentionIndex(store.doc)),
/** where the bytes are */
stats: (target?: SpacesDoc) => statsDoc(target ?? store.doc),
/**
* What a human flagged: every review thread, flat, each with a typed
* anchor ('block' with a `blockId`, or 'page').
*
* READ ONLY, deliberately. The verbs beside it change the document an
* agent was asked to work on; a comment is the other half of a
* CONVERSATION, and an agent quietly resolving the remark it was supposed
* to act on is the one move that makes the record untrue. Filter with
* `comments({ resolved: false })` for the outstanding ones.
*/
comments: (query?: CommentQuery) => commentsReport(store.doc, query ?? {}),
/**
* ONE undoable step. Without this an agent appending a paragraph has to
* rewrite and reparse the whole space through loadDoc — clobbering
* concurrent edits and flattening undo to a single entry.
*
* Keeps its original return shape (new ids, or null) because it shipped
* that way; the verbs below it return tagged results.
*/
insertBlocks: (pageId: string, afterId: string | null, blocks: unknown[]) => {
const res = run(planInsertBlocks(store.doc, pageId, afterId ?? null, blocks))
return res.ok ? res.ids : null
},
updateBlock: (id: string, patch: unknown) => run(planUpdateBlock(store.doc, id, patch)),
removeBlocks: (ids: unknown) => run(planRemoveBlocks(store.doc, ids)),
moveBlock: (id: string, to: unknown) => run(planMoveBlock(store.doc, id, to)),
updatePage: (id: string, patch: unknown) => run(planUpdatePage(store.doc, id, patch)),
removePage: (id: string, opts?: { descendants?: boolean }) =>
run(planRemovePage(store.doc, id, opts ?? {})),
// ---- the tracker: an issue is a page ---------------------------------
/** the schema in force — the option IDS a value must use */
fields: () => fieldsReport(store.doc),
/** the backlog as data, filtered by field value or by status phase */
issues: (query?: IssueQuery) => issuesReport(store.doc, query ?? {}),
/**
* One field, one undoable step, `value` and its readable `html` written
* TOGETHER — the only supported way to set a value, because a prop block
* written by hand through insertBlocks gets that pairing wrong, and it is
* the one thing that must never happen.
*/
setField: (pageId: string, key: string, value: unknown) =>
run(planSetField(store.doc, pageId, key, value)),
newIssue: (spec?: unknown) => run(planNewIssue(store.doc, spec)),
/**
* A page carries one empty paragraph, exactly as the editor's own New page
* does. A page with no blocks has nothing to put a caret in — no gutter, no
* / menu, no way to type — so an agent creating one would hand a human a
* page they cannot write in.
*/
/**
* Today's entry, or any day's — created if it does not exist yet.
*
* The same path the button and ⌘⇧J take, so an agent writing a daily note
* lands in the same page a person would, and calling it twice in a day
* returns the same page rather than making a second one.
*
* `date` is an ISO `YYYY-MM-DD`. Anything else is refused rather than
* guessed at: "06/08/2026" is two different days depending on who wrote it.
*/
journal: (date?: string) => {
if (store.readOnly) return null
const iso = date === undefined ? todayISO() : String(date)
if (!isISO(iso)) return null
editor.openJournal(iso)
return journalFor(store.doc, iso)?.id ?? null
},
/**
* Work out an expression the way a line ending in `=` would.
*
* `bento.calc('20% of 340')` → 68. With a page id, the names defined on
* that page are in scope, so an agent sees exactly what a reader sees.
* Returns null for anything the grammar does not fully understand — the
* same refusal the page makes, rather than a guess.
*/
calc: (expr: string, pageId?: string) => {
const page = pageId ? store.index.page.get(pageId) : undefined
const ctx = page
? pageContext(page.blocks.map((b) => ({ id: b.id, text: textOf(b.html ?? '') })), '')
: {}
const v = evaluate(String(expr ?? ''), ctx)
return v ? { value: v.n, text: format(v, locale()) } : null
},
newPage: (title: string, parent?: string) => {
if (store.readOnly) return null
// A TITLE, not something that stringifies into one. This takes a string
// where the verbs beside it take an object, so `newPage({ title: 'x' })`
// is the natural mistake — and it used to make a page called
// "[object Object]" and hand back its id, which is the exact failure the
// rest of this surface exists to avoid.
if (badTitle(title)) return null
// a parent that names nothing would silently make this a ROOT page; say
// no instead, so the caller finds out now rather than in the sidebar
if (parent && !store.doc.pages.some((p) => p.id === parent)) return null
const page = newPage(plainTitle(title) || 'Untitled', parent ? { parent } : {})
store.commit(() => { store.doc.pages.push(page) })
editor.repaint()
return page.id
},
loadDoc: (json: string): boolean => {
if (store.readOnly) return false
// Replace from JSON's own path ('back': content, never identity or history)
if (!replaceFromJson(store, json)) return false
editor.repaint()
return true
},
}
if (!canWriteInPlace()) {
// stated rather than discovered — the product-defining limitation on iOS
console.info('[bento/spaces] this browser cannot write back to the file; every save makes a new copy')
}
/**
* Ask the release server whether this app is current — and NOTHING else.
*
* This is the one request bento/spaces makes on its own, and it is worth
* being precise about how it sits beside "A space does not phone home when
* it is opened" (DECISIONS, 2026-08-03). That rule is about the DOCUMENT: an
* author who mails you a file must not learn your address and the moment you
* opened it, which is what a remote `<img>` delivers. This is the APP asking
* its own release origin for a signed manifest, on the reader's behalf and
* under the reader's switch — the same check slides has run at launch since
* v0.9, reading the same `bento-auto-check` preference, so turning it off in
* one app turns it off in both. It sends no id, carries nothing from the
* document, and is the mechanism by which a file that will outlive its
* browser ever learns that it should be updated.
*
* Never fatal, and never in the way: the result only changes a sentence in
* the About dialog.
*/
// A found update also puts slides' peach chip beside the wordmark, and says
// so once — the one launch result a reader must not miss (D3's pill). "Up to
// date" stays a sentence in About, where slides' toast also repeats it.
void launchUpdateCheck()
.then((r) => { if (r?.status === 'update') editor.updateFound(r.release.version) })
.catch(() => { /* an unreachable server is not an error here */ })
}
/** A strip across the top. An action marked primary is styled as the default;
* one marked focus takes focus when the banner appears. The two are separate
* because slides' recovery banner separates them. */
function banner(text: string, actions: Array<[string, () => void, boolean?, boolean?]> = []): void {
const bar = document.createElement('div')
bar.className = 'sp-banner'
const span = document.createElement('span')
span.textContent = text
bar.append(span)
let focused: HTMLButtonElement | undefined
for (const [label, fn, isPrimary, takesFocus] of actions) {
const b = document.createElement('button')
b.className = isPrimary ? 'sp-btn sp-primary' : 'sp-btn'
b.textContent = label
b.addEventListener('click', () => { fn(); bar.remove() })
bar.append(b)
if (takesFocus) focused ??= b
}
const close = document.createElement('button')
close.className = 'sp-btn'
close.textContent = '✕'
close.setAttribute('aria-label', t('Dismiss'))
close.addEventListener('click', () => bar.remove())
bar.append(close)
document.body.prepend(bar)
focused?.focus()
}
/**
* A snapshot that differs from the file we loaded means a crash lost work.
*
* The snapshot is FOREIGN INPUT (restoregate.ts): every file:// document shares
* this IndexedDB, so it is offered only when it passes the gate, and compared as
* it WOULD be restored. An entry that is not this space, not a document, or
* that gates down to what is already open never shows a banner at all — like
* slides' checkRecovery.
*/
async function offerRecovery(doc: SpacesDoc, store: Store, editor: Editor): Promise<void> {
if (store.readOnly) return // a reading copy, a view-only follower or a frozen file is never rewritten
// A SEALED SPACE IS NEVER OFFERED A PLAINTEXT COPY, and the ones an unsealed
// session left for this docId are deleted: the recovery snapshot and every
// version. boot() runs after the seal is in place (the identity seal is set
// in capturePristine, the password before boot), so isBodySealed() here is
// the proven state. Only this docId's entries; never another document's.
if (isBodySealed()) {
await clearRecovery(doc.docId)
await clearVersions(doc.docId)
return
}
const snap = await getRecovery(doc.docId)
if (!snap || !recoveryOffered(snap.json, doc, snap.at)) return
// What the banner SAYS is recoverynotice.ts: when the snapshot looks older
// than the file it warns, and "Keep the file" is the default — but the
// snapshot is still offered, and keeping the file deletes nothing.
const spec = recoveryBanner(snap, store.doc)
const run: Record<RecoveryAction, () => void> = {
restore: () => {
// re-gated against the space as it is NOW (recoverInto). A refusal
// applies nothing and keeps the entry; only Discard deletes it.
// 'recover': the snapshot is a newer copy of this space, so its history
// is reconciled (trail unioned by day) rather than kept from the file.
if (!recoverInto(store, snap)) { editor.status(t('That version could not be read')); return }
editor.repaint()
},
discard: () => { void clearRecovery(doc.docId) },
// a clock-skewed "older" must never cost work: the entry stays
keep: () => {},
}
banner(spec.text, spec.buttons.map((b) => [b.label, run[b.action], b.primary, b.focus]))
}