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
//
// How each TOP-LEVEL field of a bento/spaces document is copied — the space's
// row in the kernel's field classification (kernel/src/docfields.ts).
//
// Not to be confused with fields.ts, which is a page's PROPERTIES (status,
// due date, assignee). This file is about the document's own keys: which of
// them a copy handed to someone else may carry.
//
// THE MAP IS EXHAUSTIVE, and the compiler holds it to that. `satisfies` over
// the document's DECLARED keys fails tsc on a key that is missing here and on
// one that is not a field, so a new field cannot reach a copy without
// somebody deciding what it is. A field that arrives without being declared at
// all (a newer build's, or an agent's) is unclassified, and the kernel drops it
// from every copy except the file itself and the owner's duplicate.
//
// Every copy for someone else is built by `projectForCopy(doc, SPACES_FIELDS,
// tier)` (share.ts, model.ts docForExport), which starts from an EMPTY object
// and carries a field only when the kernel's table says so for that tier.
import type { FieldClass, ModeFieldsOk } from '../../kernel/src/docfields.ts'
import type { SpacesDoc } from './model.ts'
/** The keys SpacesDoc declares — its index signature (`[extra: string]`)
* removed, which would otherwise make `keyof` plain `string` and the map
* exhaustive over nothing. */
type DeclaredKeys<T> = keyof {
[K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]
}
export const SPACES_FIELDS = {
// identity — re-minted on a duplicate, never on any other copy
docId: 'identity',
// mode — SET per copy by the kernel's MODE_FIELD_RULES (a reader copy is
// readonly, a template copy is a template), never simply stripped
readonly: 'mode',
template: 'mode',
// capability — every field under it is a bearer key; projected through the
// kernel's allowlists (collabForReader / collabForInvite), including `sync`
collab: 'capability',
// history — file-local version history: kept by the file, the duplicate and
// an invite; dropped from every reader-tier copy and from Copy document JSON
revisions: 'history',
trail: 'history',
// content — the document itself
format: 'content',
version: 'content',
policy: 'content',
title: 'content',
// content, but NOT an edit: excluded from the recovery key (model.ts)
modified: 'content',
pages: 'content',
home: 'content',
theme: 'content',
design: 'content',
designs: 'content',
// the asset pool
assets: 'content',
footnotes: 'content',
fonts: 'content',
templates: 'content',
journalTemplate: 'content',
// content, not history: a period is something a person DECIDED (a sprint's
// window and committed scope), named by a chart block in a page, undone by
// ⌘Z, and synced per key. Classing it history would drop it from a reader
// copy while the chart block that names it stays — a dangling reference —
// and would stop collaborators sharing the sprint. It holds totals at one
// instant (base), never page ids and never a series; the series is `trail`.
periods: 'content',
} satisfies Record<DeclaredKeys<SpacesDoc>, FieldClass>
/** tsc fails here if the fields classed 'mode' stop being exactly the kernel's
* two (readonly, template). */
const _modeOk: ModeFieldsOk<typeof SPACES_FIELDS> = true
void _modeOk
/** Fields that change without anyone editing — excluded from the recovery
* key so an autosave of an untouched space is not a phantom edit.
*
* `revisions` is here although the kernel's default counts history as
* unsaved work. That default exists for history a person makes BETWEEN saves
* (type's typed revisions, a signature), which only a recovery snapshot can
* keep. Spaces records a revision only inside a save's prepare step, into
* the bytes that save writes (history.ts) — so it is never unsaved work, and
* counting it would raise the recovery banner on every file reopened after a
* download-save, whose recovery snapshot predates the revision.
*
* `trail` is NOT listed, and must not be: it is written WHILE EDITING, on the
* 'doc' event (main.ts recordToday), outside any save. A row recorded since
* the last save is unsaved work only a recovery snapshot can keep, which is
* exactly the case the kernel's default exists for. */
export const SPACES_NOT_EDIT: ReadonlySet<string> = new Set(['modified', 'revisions'])