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
// The boot-time recovery offer: the READ half of auto-save.
//
// dash has been writing `putRecovery(store.doc)` on every debounced edit since
// the autosave landed (main.ts) and has never once called `getRecovery`. That
// is the worst shape a backstop can have: snapshots accumulate in IndexedDB,
// the browser reports storage used, and the work is offered back to nobody. A
// crash, a closed tab, an OS update at 3am — the file on disk is stale, the
// recovered document is sitting in the database, and the reader is told
// nothing. Slides shows a Restore/Discard banner; this is dash's.
//
// THREE RULES, each of which is a way this could do harm rather than good:
//
// 1. NEVER OFFER WHAT IS ALREADY IN THE FILE. The snapshot is compared to the
// loaded document by CONTENT (`contentKey`), not by timestamp: autosave
// fires 2.5s after the last keystroke and a save usually follows, so the
// snapshot is almost always present and almost always identical. A banner
// on every single open is a banner nobody reads, and the one time it means
// something it will be dismissed by reflex.
// 2. NEVER FOR AN ENCRYPTED WORKBOOK. main.ts refuses to snapshot one
// (plaintext to disk is what the password exists to prevent), so any row
// under this docId was written BEFORE the password was set — pre-encryption
// plaintext, which restoring would put back on screen and, at the next ⌘S,
// back into the file. `mountRecovery` therefore does not even read the
// store when a password is held, and `decide` refuses on the same flag so
// the rule is provable without a browser.
// 3. NEVER INTO A WORKBOOK THIS BUILD REFUSES TO WRITE. A document frozen by
// an unknown policy or a future format version opens read-only precisely so
// nothing is lost; restoring over it is a write.
//
// RESTORING IS NOT ⌘Z-ABLE, and that is dash's shape rather than a shortcut:
// `Store.replaceDoc` empties both undo stacks (store.ts) because history here
// is typed inverses, not document snapshots, and an inverse minted against
// another document is meaningless. So the caller holds the pre-restore document
// itself and offers ONE explicit "Undo restore" — which is the guarantee the
// user actually wants, spelled where they can see it, rather than a keystroke
// that would silently do nothing.
//
// THAT OFFER IS `offerUndoRestore`, AND IT IS EXPORTED. About's version history
// is the other surface that replaces a whole workbook, and it used to disagree
// with this one about whether that could be taken back: it asked a `confirm()`
// reading "this cannot be undone" and then made that true, because nothing kept
// the document it was replacing. Two answers to one question is a bug on its
// own, and `confirm()` is the weaker of them regardless — it asks BEFORE, when
// the reader cannot yet see what they would be agreeing to. One function, two
// callers, so they cannot drift apart again.
import './recovery.css'
import { getRecovery, clearRecovery, clearVersions, recoveryLooksOlder, type Snapshot } from '../../kernel/src/autosave.ts'
import { isBodySealed } from '../../kernel/src/save.ts'
import { planReplace } from './about.ts'
import { parseDoc, type DashDoc } from './model.ts'
import type { Store } from './store.ts'
import { FROM_LIVE } from '../../kernel/src/docfields.ts'
import { t } from './i18n.ts'
// --- the content key ---------------------------------------------------------
/**
* Top-level fields that churn WITHOUT anybody editing anything, and so must not
* make a snapshot look different from the file it came from.
*
* · `modified` — a save stamps it; two identical documents saved a minute
* apart differ here and nowhere else.
* · `collab` — sync state is stamped into the file on save (PLATFORM §5).
* dash mints no credentials yet, but the field is in the model, a
* hand-written or imported workbook can arrive carrying one, and adding it
* to this list later would not reach snapshots already written.
*
* Everything else counts, INCLUDING fields this build does not know. The format
* is additive forever (PLATFORM §3): an unknown top-level key is somebody's
* data, written by a newer build or an agent, and a change to it is a change.
* A whitelist — which is what slides uses — would call that "no edits found".
*/
export const VOLATILE_KEYS = ['modified', 'collab'] as const
/**
* A stable string for "what this document SAYS", ignoring the volatile fields.
*
* Object keys are sorted, which plain `JSON.stringify` does not do. The two
* documents being compared reach here by different routes — one parsed from the
* #bento-doc block at boot, one parsed from a snapshot written in an earlier
* session and then run through `parseDoc` again — and key ORDER is an
* artefact of how each object was built. Without the sort, a reordering that
* changes nothing at all shows the user a banner claiming unsaved work, they
* click Restore, and the app swaps in a document identical to the one already
* open. Cheap enough to be uninteresting: the sort touches object keys, and a
* workbook's bulk is arrays of values, which are left in order (order IS the
* data there — row 3 is row 3).
*/
export function contentKey(doc: DashDoc): string {
const skip = new Set<string>(VOLATILE_KEYS)
const rest: Record<string, unknown> = {}
for (const [k, v] of Object.entries(doc)) if (!skip.has(k)) rest[k] = v
return stable(rest)
}
function stable(v: unknown): string {
if (v === null || typeof v !== 'object') return JSON.stringify(v) ?? 'null'
if (Array.isArray(v)) return `[${v.map(stable).join(',')}]`
const o = v as Record<string, unknown>
const keys = Object.keys(o).sort()
// `undefined` is not JSON and JSON.stringify drops such keys from an object;
// dropping them here too keeps `{a:1}` and `{a:1,b:undefined}` equal, which
// is what a round trip through the snapshot's JSON makes of them anyway.
return `{${keys.filter((k) => o[k] !== undefined)
.map((k) => `${JSON.stringify(k)}:${stable(o[k])}`).join(',')}}`
}
// --- the decision ------------------------------------------------------------
/** Why an offer was withheld. Named rather than boolean so the rig can tell a
* deliberate refusal from a snapshot that merely matched. */
export type NoOfferReason =
| 'none' // nothing in the store for this docId
| 'encrypted' // rule 2 — the snapshot predates the password, if it exists at all
| 'read-only' // rule 3 — this build will not write this workbook
| 'unreadable' // the snapshot is not a workbook this build can open
| 'other-doc' // defensive: a snapshot filed under another docId
| 'same' // rule 1 — the file already has these edits
export type RecoveryDecision =
/**
* `older`: the snapshot predates the file that loaded (kernel
* `recoveryLooksOlder`). A SIGNAL for the banner's wording, never a reason
* not to offer (maintainer ruling 2026-10-15): two devices' clocks can make
* a newer copy look older, and a hidden offer is unrecoverable work.
*/
| { offer: true; doc: DashDoc; at: number; older: boolean }
| { offer: false; why: NoOfferReason }
export interface DecideInput {
snapshot: Snapshot | null
/** the workbook that actually loaded from the file */
doc: DashDoc
/** the body is sealed on disk, by a password or the identity seal — `isBodySealed()` at the call site */
encrypted: boolean
/** the store refuses commits (frozen doc, or a `readonly` copy) */
readOnly: boolean
}
/**
* The whole of the offer/no-offer question, with no DOM and no IndexedDB in it,
* so every branch above is provable in `scripts/test-dash-recovery.ts`.
*
* The snapshot is run through `parseDoc` rather than trusted: it is this app's
* own JSON, but it was written by an EARLIER build, may predate an id repair,
* and may declare a policy this build refuses. A snapshot that cannot be opened
* is not offered — the alternative is a Restore button that hands the app a
* document it will then refuse, which is a dead end wearing a live button.
*/
/**
* The fields a restore takes from the LIVE workbook, never from the snapshot.
*
* A recovery entry or a kept version is a CONTENT snapshot of THIS workbook,
* not a new file — so who it is (`docId`), which room it shares into and with
* which keys (`collab`), and what it may do (`readonly`, `template`) are facts
* about the workbook on screen. The snapshot's copies of them are not
* evidence: on file:// every local document shares one IndexedDB origin, and
* the store is keyed by docId, so any page opened in the same browser can
* write an entry under this workbook's docId. Before this, that entry's
* `collab` rode `parseDoc` straight into `replaceDoc`, and one Restore click
* moved the workbook into the writer's room.
*
* `template` is dash's own: restored, it would stop the automatic save to the
* file (writeback.ts refuses a template) and make the next open re-mint the
* identity. Same class as the other three — and all four are the shared kernel
* list now (kernel/src/docfields.ts), re-exported here.
*
* Opening a FILE and Replace from JSON do not come through here. A file
* carries its own capability by design; Replace from JSON keeps the live room
* already (about.ts).
*/
export { FROM_LIVE }
/** The snapshot's content under the live workbook's identity. */
export function keepLiveIdentity(next: DashDoc, live: DashDoc): DashDoc {
const out = { ...next } as Record<string, unknown>
const from = live as unknown as Record<string, unknown>
for (const k of FROM_LIVE) {
if (from[k] !== undefined) out[k] = from[k]
else delete out[k]
}
return out as unknown as DashDoc
}
/**
* A stored snapshot, parsed and put under the live workbook's identity — the
* ONE way a recovery entry or a kept version becomes a document. Both the
* banner (`decide`) and Version history (about.ts) call this, so neither can
* forget the identity half. `null` when the snapshot cannot be opened.
*/
export function restoredWorkbook(json: string, live: DashDoc): DashDoc | null {
const res = parseDoc(json)
return res.ok ? keepLiveIdentity(res.doc, live) : null
}
export function decide(input: DecideInput): RecoveryDecision {
if (input.encrypted) return { offer: false, why: 'encrypted' }
if (input.readOnly) return { offer: false, why: 'read-only' }
if (!input.snapshot) return { offer: false, why: 'none' }
if (input.snapshot.docId !== input.doc.docId) return { offer: false, why: 'other-doc' }
// Identity from the live workbook BEFORE the comparison, so a snapshot that
// differs only in its room is not even offered.
const doc = restoredWorkbook(input.snapshot.json, input.doc)
if (!doc) return { offer: false, why: 'unreadable' }
if (contentKey(doc) === contentKey(input.doc)) return { offer: false, why: 'same' }
// Read against the workbook AS LOADED: `modified` is stamped on every edit,
// so asking after the reader has typed would compare against their typing.
return { offer: true, doc, at: input.snapshot.at, older: recoveryLooksOlder(input.snapshot, input.doc) }
}
// --- swapping a whole workbook in -------------------------------------------
/**
* What a module needs in order to put a different workbook on screen.
*
* `showingSheet`/`showSheet` are the grid's, and they are not optional: see
* `planReplace` (about.ts) — `Grid.sheet` THROWS when the sheet id it holds is
* missing from the document, and it reads it from a `doc` listener registered
* before every other one, so an incoming workbook with different sheet ids
* takes the dirty flag and the chart down with it and leaves the app half
* swapped.
*/
export interface WorkbookHost {
store: Store
showingSheet: () => string
showSheet: (id: string) => void
/**
* The document changed underneath the chrome main.ts owns — the title field
* is set once at boot and only rewritten by its own `input` handler, so
* without this it keeps showing the name of the workbook that was replaced.
*/
afterSwap?: (doc: DashDoc) => void
}
/**
* Swap `next` in without tripping the grid. False when the incoming workbook
* has no table sheet to show, or when this build will not write this document.
*
* This is `replaceWorkbook` from about.ts, which is private to that module.
* Deliberately re-stated rather than reached for: about.ts's copy is coupled to
* `AboutHooks` (it also carries `onDirty`, which is about document PROPERTIES
* and has nothing to do with a swap). What must not diverge is `planReplace`,
* and that is imported, not copied.
*/
export function swapWorkbook(host: WorkbookHost, next: DashDoc): boolean {
// `replaceDoc` does NOT check `store.readOnly` — it is the load path, not an
// edit path — so a frozen workbook has to be defended by every caller.
if (host.store.readOnly) return false
const plan = planReplace(next, host.showingSheet())
if (!plan) return false
if (plan.carry) {
const carried = host.store.doc.sheets.find((s) => s.id === host.showingSheet())
host.store.replaceDoc(carried ? { ...next, sheets: [...next.sheets, carried] } : next)
host.showSheet(plan.show)
}
host.store.replaceDoc(next)
host.afterSwap?.(next)
return true
}
// --- the banner --------------------------------------------------------------
/**
* Check for unsaved work and, if there is any, offer it back. Call once, after
* the Store exists and the grid is mounted.
*
* Resolves to what was decided, so a caller (and the rig's DOM half, if one is
* ever written) can assert on it. Never throws: a failure here must not be able
* to take down a boot that has otherwise succeeded.
*/
/**
* The listener main.ts hands to the kernel's `onRecoveryOff`: says, for THIS
* workbook only, that crash recovery is off (maintainer wording 2026-10-15).
* Here rather than inline so the rig can drive the exact function the app uses.
*/
export function recoveryOffNotice(store: Store, say: (message: string) => void): (docId: string) => void {
return (docId) => {
if (docId !== store.doc.docId) return
say(t('Crash recovery is off for this workbook — it’s too large to keep a backup copy. Save often.'))
}
}
export async function mountRecovery(host: WorkbookHost): Promise<NoOfferReason | 'offered'> {
const doc = host.store.doc
// Rule 2, enforced before the read as well as inside `decide`: a sealed
// body never offers a plaintext copy, and never keeps one. Copies this
// browser kept for THIS workbook in an earlier, unsealed session are
// deleted; every other workbook's copies are untouched.
if (isBodySealed()) {
try { await Promise.all([clearRecovery(doc.docId), clearVersions(doc.docId)]) } catch { /* store unavailable: nothing kept there */ }
return 'encrypted'
}
let snapshot: Snapshot | null = null
try { snapshot = await getRecovery(doc.docId) } catch { return 'none' }
const d = decide({ snapshot, doc, encrypted: false, readOnly: host.store.readOnly })
if (!d.offer) return d.why
showRecoveryBanner(host, d.doc, d.at, d.older)
return 'offered'
}
/**
* The offer. Exported for the rig, with `clear` injectable so it can PROVE
* which answers delete the snapshot — "Keep the file" must not, ever.
*/
export function showRecoveryBanner(
host: WorkbookHost, recovered: DashDoc, at: number, older = false,
clear: (docId: string) => unknown = clearRecovery,
): void {
document.querySelector('.dxr-bar')?.remove()
const bar = document.createElement('div')
bar.className = 'dxr-bar'
bar.setAttribute('role', 'status')
const when = new Date(at).toLocaleString([], {
month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
})
const msg = document.createElement('span')
msg.className = 'dxr-msg'
// THE OLDER CASE WARNS AND KEEPS THE FILE BY DEFAULT — slides' banner,
// word for word (maintainer ruling 2026-10-15). It still OFFERS the copy:
// "older" comes from two clocks that need not agree, so it only changes the
// advice. No "newer"/"safe" wording in the ordinary case: when there is no
// warning the banner says what was found and nothing about which to trust.
msg.textContent = older
? t('This recovered copy looks older than the file you opened. Keep the file unless you know it’s newer.')
: t('Unsaved changes from {when} were found in this browser.', { when })
const restore = btn(older ? t('Restore anyway') : t('Restore'), older ? '' : 'dxr-primary')
const discard = btn(t('Discard'))
const x = closeBtn(bar, t('Dismiss — the changes stay in this browser'))
restore.addEventListener('click', () => {
// Held BEFORE the swap: `replaceDoc` empties the undo stacks, so this
// object is the only route back to what is on screen right now.
const before = host.store.doc
if (!swapWorkbook(host, recovered)) {
msg.textContent = t('Those changes could not be restored into this workbook.')
restore.remove()
return
}
// The snapshot stays in IndexedDB deliberately. If the restore turns out to
// be wrong and the window is closed without saving, the next open must
// still find it — clearing here would burn the only copy at the exact
// moment the user is least sure.
//
// A WHOLE NEW BAR, not this one edited. Mutating it in place meant removing
// two buttons and splicing a third in before the ✕, and the ✕ was the one
// node that had to survive the transition — appending a fresh one left two
// side by side (measured in the browser, and exactly the kind of thing that
// only shows up once the second state is reached). Building the offer from
// scratch has no transition to get wrong, and it is the same call About's
// version restore makes, which is the point.
offerUndoRestore(host, before, t('Restored the unsaved changes from {when}.', { when }))
})
discard.addEventListener('click', () => {
void clear(host.store.doc.docId)
bar.remove()
})
if (older) {
// "Keep the file" DISMISSES; it does not delete. A false "older" (clock
// skew) must never cost the copy — it stays for the next open, exactly
// like ✕. Discard is not offered here: deleting is the one answer the
// advice does not support. Keep comes first and takes focus.
const keep = btn(t('Keep the file'), 'dxr-primary')
keep.addEventListener('click', () => bar.remove())
bar.append(msg, keep, restore)
document.body.append(bar)
keep.focus?.()
return
}
bar.append(msg, restore, discard, x)
document.body.append(bar)
}
/**
* Dismiss WITHOUT discarding — the third answer, and the only honest one for
* "not now". Discard deletes the snapshot; ✕ leaves it where it is, so the
* offer comes back on the next open. A banner whose only exit is destructive
* gets clicked by people who meant "go away".
*
* The title is passed in because the two bars are dismissing different things:
* on the offer it means "the changes stay in this browser", and on the
* post-restore bar it means "I am keeping the restore". One string for both
* would be wrong on one of them.
*/
function closeBtn(bar: HTMLElement, title: string): HTMLElement {
const b = btn('✕', 'dxr-x')
b.title = title
b.setAttribute('aria-label', title)
b.addEventListener('click', () => bar.remove())
return b
}
// --- the way back from a restore ---------------------------------------------
/**
* A workbook was just swapped in; here is the ONE way back.
*
* SHARED WITH ABOUT'S VERSION HISTORY, and that is the whole reason it is
* exported. The two paths that replace a whole document used to disagree about
* whether doing so was reversible: the recovery banner held the pre-restore
* document and offered "Undo restore", while About asked a `confirm()` reading
* "this cannot be undone" and then made it true. Two answers to one question,
* and `confirm()` is the weaker of them regardless — it asks BEFORE, when the
* reader cannot yet see what they are agreeing to, instead of offering a way
* back AFTER, when they can.
*
* `Store.replaceDoc` empties both undo stacks (store.ts) because history here
* is typed inverses and an inverse minted against another document is
* meaningless — so ⌘Z genuinely does not reach across a restore, and the caller
* holding `before` is the only route back. This makes that route a button.
*
* The bar REPLACES whatever `.dxr-bar` is on screen. It is dismissible and
* never auto-hides: a reader who has just had their whole workbook replaced
* should not be racing a timer to change their mind.
*/
export function offerUndoRestore(host: WorkbookHost, before: DashDoc, message: string): void {
document.querySelector('.dxr-bar')?.remove()
const bar = document.createElement('div')
bar.className = 'dxr-bar'
bar.setAttribute('role', 'status')
const msg = document.createElement('span')
msg.className = 'dxr-msg'
msg.textContent = message
const undo = btn(t('Undo restore'))
undo.addEventListener('click', () => {
// If this fails there is nothing useful left to say and nothing to retry —
// the document on screen is the restored one either way — so the bar goes
// rather than sitting there with a button that does nothing.
swapWorkbook(host, before)
bar.remove()
})
bar.append(msg, undo, closeBtn(bar, t('Dismiss — keep the restored workbook')))
document.body.append(bar)
}
function btn(label: string, cls = ''): HTMLButtonElement {
const b = document.createElement('button')
b.type = 'button'
b.className = `dx-btn dxr-btn${cls ? ` ${cls}` : ''}`
b.textContent = label
return b
}