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 bento/type document model. This JSON is what lives inside the #bento-doc
// block — the format IS the product (docs/PLATFORM.md §3).
//
// The shape of a document here is deliberately narrow: a flat, ordered list of
// blocks, each holding PLAIN TEXT plus marks over character ranges (see
// inline.ts for why that spine and not HTML). No nesting, no inline nodes, no
// tree. A word processor's document is a stream of prose that gets poured into
// pages; the structure lives in the block kinds and in the pagination, not in
// the container.
import { normalize, shift as shiftMarks, type Mark } from './inline.ts';
import { withoutCaps, projectForCopy } from '../../kernel/src/docfields.ts';
import { TYPE_FIELDS } from './docclass.ts';
import { sigId } from './canon.ts';
// value import is safe: xref.ts imports only TYPES from this module, precisely
// so the core can call into it without a cycle
import { shiftRefs } from './xref.ts';
// same arrangement, same reason: fields.ts imports only TYPES from this module,
// so the core can call into it without a value-level cycle. See fields.ts.
import { readFieldRefs, shiftFields, type FieldRef } from './fields.ts';
import { readThreadsRaw, reconcileThreads } from './comments.ts';
export const FORMAT = 'bento/type';
export const VERSION = 1;
/** The kinds of block a document is made of. */
export type BlockKind = 'para' | 'h1' | 'h2' | 'h3' | 'quote' | 'ul' | 'ol' | 'cell' | 'image' | 'caption' | 'toc' | 'math' | 'embed';
/**
* Where a table cell sits. Carried on EVERY cell of the table, not on a table
* block — because there is no table block.
*
* A CELL IS A BLOCK, for the same reason a list item is one, and here the
* reason is sharper: the redline aligns on block ids, so per-cell blocks give
* per-cell review. A table as a single block would report "the payment table
* changed" when one figure moved — which is precisely the failure that makes
* line diffs useless on prose, and the limitation bento/slides documents for
* its own tables. For an app whose differentiator is redlining contracts, that
* is the wrong trade.
*
* `cols` is repeated on every cell rather than stored once. It is redundant and
* that is the point: there is no header block to lose, so a grid can always be
* rebuilt from any run of cells, and a file that disagrees with itself is
* repaired to the majority rather than being unreadable.
*/
export interface CellRef {
/** which table this cell belongs to — consecutive cells sharing it group */
table: string;
/** the table's column count */
cols: number;
/** cells of the first row, rendered as <th> */
head?: boolean;
}
/**
* A picture in the document.
*
* `src` is a data: URI (embedded, so the file stays self-contained) or an
* external URL (referenced, so the file stays small). Embedding is the default
* because the whole promise is that one file IS the document — a reference that
* breaks when the document is emailed is a worse failure than a large file.
*
* `w` is a fraction of the text measure (0–1), not pixels: the page size is a
* document property that can change, and an image sized in pixels would stop
* fitting the moment somebody switched to A4.
*/
export interface ImageRef {
src: string;
alt?: string;
/** width as a fraction of the text column, default 1 */
w?: number;
align?: 'left' | 'center' | 'right';
}
/**
* A caption, and what it captions.
*
* A BLOCK, not a field on the table — because there IS no table block to hang
* one on (a table is a run of `cell` blocks sharing an id), and a caption needs
* its own stable id anyway: that id is what a reference points at, and what the
* redline aligns on so an edited caption reports as an edited caption.
*/
export interface CaptionRef { kind: 'table' | 'figure'; of?: string }
/**
* A citation: an atom at an offset, like a footnote anchor.
*
* `keys` is a LIST because "(Knuth 1984; Lamport 1994)" is one citation at one
* position, not two adjacent ones.
*/
export interface CiteRef { at: number; keys: string[]; locator?: string; suppressAuthor?: boolean }
/** A cross-reference: an atom at an offset, exactly like a footnote anchor. */
export interface XrefRef { to: string; at: number; style?: 'label' | 'page' | 'both' }
/** Above this an embedded image is refused, and a URL offered instead. */
export const IMAGE_EMBED_BUDGET = 4 * 1024 * 1024;
/**
* Sources an image may have.
*
* A document is UNTRUSTED INPUT (docs/DECISIONS.md), and `src` goes straight
* into an <img>. `javascript:` is the obvious attack and is not the only one —
* anything that is not plainly an image reference is refused rather than
* guessed at.
*/
export const SAFE_IMG = /^(data:image\/(png|jpe?g|gif|webp|avif|svg\+xml)[;,]|https?:\/\/|\.{0,2}\/)/i;
/** The list kinds, which are the ones that carry `level` and group when rendered. */
export const LIST_KINDS: ReadonlySet<BlockKind> = new Set<BlockKind>(['ul', 'ol']);
export const isList = (k: BlockKind): boolean => LIST_KINDS.has(k);
/** How deep a list item may be nested. Beyond this the indents stop reading as
* structure and start reading as a mistake. */
export const MAX_LIST_LEVEL = 5;
/** Columns beyond this stop being a table and start being a spreadsheet. */
export const MAX_TABLE_COLS = 20;
/** A footnote reference anchored INTO a block's text, by character offset. */
export interface NoteRef { id: string; at: number }
/**
* A review comment: a thread anchored to a RANGE of a block's text.
*
* Doc-level and keyed by id, like `footnotes`, because a thread must be able to
* outlive the block it points at — the conversation about a deleted clause is
* exactly the conversation you still need.
*/
export interface CommentMsg { id: string; author: string; at: string; text: string }
export interface CommentThread {
id: string; block: string; from: number; to: number;
quote: string; messages: CommentMsg[];
resolved?: boolean; orphan?: boolean;
}
export interface Block {
/** stable identity: the redline aligns on it, so it must never be re-minted
* for a block the author considers the same paragraph */
id: string;
kind: BlockKind;
/** the block's text, with no markup of any kind in it */
text: string;
/** formatting over character ranges; absent means none */
marks?: Mark[];
/** footnote references, by offset into `text` */
notes?: NoteRef[];
/** authoring role, for restyling and for a table of contents */
role?: string;
/**
* Nesting depth for a list item, 0-based. Absent means 0, and it means
* nothing on a block that is not a list.
*
* A LIST ITEM IS A BLOCK, and the list itself is not in the model at all —
* runs of adjacent `ul`/`ol` blocks are grouped into real <ul>/<ol> elements
* at RENDER time. That keeps the document flat, which is not a stylistic
* preference: the redline aligns on block ids, the caret is (blockId,
* offset), and pagination measures line boxes through a tree walker. A
* nested list model would have put a tree under all three, and each of them
* is correct today because there is no tree.
*/
level?: number;
/** table placement; only meaningful on a `cell` block */
cell?: CellRef;
/** the picture; only meaningful on an `image` block */
image?: ImageRef;
/** caption placement; only meaningful on a `caption` block */
caption?: CaptionRef;
/** cross-references, by offset into `text` — atoms, like `notes` */
refs?: XrefRef[];
/** citations, by offset into `text` — atoms, like `notes` */
cites?: CiteRef[];
/**
* Fields — text the document computes rather than stores — by offset into
* `text`, atoms like `notes`. `{{page}}`, `{{title}}`, and the merge columns
* a mail merge binds. See fields.ts for why a field is an atom in this app
* and a literal token in bento/slides.
*/
fields?: FieldRef[];
/**
* A named style this block carries BY REFERENCE — see docstyles.ts.
*
* Absent means "whatever `kind` implies by default", which is itself a named
* style (docstyles.ts's built-ins, keyed by kind) rather than special-cased —
* so editing "Heading 1" restyles every h1 that never set this field, which
* is the whole point of a styles system. A block that sets `styleId` opts
* INTO a different named look than its kind's default; it does not opt out
* of styling altogether.
*/
styleId?: string;
// ---- paragraph layout. ABSENT MEANS "the document's default", never a
// value: a paragraph with no `align` is justified because the DOCUMENT says
// so, and setting the current default deletes the field rather than writing
// it. That is what keeps a restyled document from carrying ten thousand
// copies of its own defaults.
align?: 'left' | 'center' | 'right' | 'justify';
/** space before, px */ sb?: number;
/** space after, px */ sa?: number;
/** line spacing, a multiple of the font size */ lh?: number;
/** first-line indent, px */ ind?: number;
keepNext?: true; keepTogether?: true; breakBefore?: true;
/** Unknown fields ride through untouched — format additivity, PLATFORM §3. */
[extra: string]: unknown;
}
/** Page geometry, in CSS px at 96dpi. US Letter by default. */
export interface PageSpec {
width: number; height: number;
marginX: number; marginTop: number; marginBottom: number;
/** absent means `marginX`, so a symmetric page keeps writing one field */
marginLeft?: number; marginRight?: number;
}
export const LETTER: PageSpec = {
width: 816, height: 1056, marginX: 104, marginTop: 104, marginBottom: 104,
};
/**
* A font stack a document may carry, by GRAMMAR: a comma-separated list of
* names, each quoted ("Iowan Old Style", 'Iowan Old Style') or bare (Georgia,
* serif), made of letters, digits, spaces, hyphens, dots and underscores.
* Anything else is REFUSED (undefined), never trimmed into shape: nothing that
* could end a CSS declaration or rule (`;` `{` `}`), a string, or an HTML
* element (`<` `>`) can pass. Every consumer interpolates this into CSS —
* print and the preview into HTML strings — and a SYNCED value never passes
* parseDoc, so the consumers call it too, not only parseDoc.
*/
export function safeFontFamily(v: unknown): string | undefined {
if (typeof v !== 'string' || v.length > 300) return undefined;
const NAME = /^(?:"[A-Za-z0-9 ._-]+"|'[A-Za-z0-9 ._-]+'|[A-Za-z0-9][A-Za-z0-9 ._-]*)$/;
const parts = v.split(',').map(p => p.trim());
return parts.every(p => NAME.test(p)) ? parts.join(', ') : undefined;
}
/** Page geometry from a file — or from a synced doc, which never passed
* parseDoc: print and the preview call this too. NUMBERS, or the default. Every consumer
* interpolates these into CSS (print into an HTML string), so a string here
* could end the element it is written into. Unknown keys ride along. */
export function readPage(raw: Record<string, unknown>): PageSpec {
const num = (v: unknown, lo: number, hi: number): number | undefined =>
typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : undefined;
const out = { ...LETTER, ...raw } as PageSpec & Record<string, unknown>;
out.width = num(raw.width, 100, 20000) ?? LETTER.width;
out.height = num(raw.height, 100, 20000) ?? LETTER.height;
out.marginX = num(raw.marginX, 0, 5000) ?? LETTER.marginX;
out.marginTop = num(raw.marginTop, 0, 5000) ?? LETTER.marginTop;
out.marginBottom = num(raw.marginBottom, 0, 5000) ?? LETTER.marginBottom;
for (const k of ['marginLeft', 'marginRight'] as const) {
const v = num(raw[k], 0, 5000);
if (v === undefined) delete out[k]; else out[k] = v;
}
return out;
}
export interface Signature {
alg: 'ES256';
/** raw P-256 public key, base64url — the identity. The name is only a claim. */
pub: string;
/** self-asserted, shown beside the signature and NOT proof of anything */
name: string;
/** digest of the canonical CONTENT at the moment of signing (canon.ts SIGNED_EXCLUDE) */
content: string;
/** salted commitment to the history at the moment of signing (canon.ts
* historyCommitment). Reveals nothing about the revisions without the
* document's historySalt, so it travels in view-only copies. */
history: string;
/** the SigId (canon.ts sigId) of the signature this one follows — ORDERING
* only (ruling 7): a signature is valid on its own, whatever this says. A
* signature made before ids existed holds the earlier signature's bytes. */
prev: string;
sig: string;
/** self-asserted wall clock. Display only — order comes from `prev`. */
at?: string;
}
/** A recorded revision, kept so a redline can be produced with no server. */
export interface Revision {
id: string; at: string; label: string;
body: Block[];
}
/**
* A named paragraph style — what Word calls "Heading 1": a bundle of
* typography a block can carry BY REFERENCE (`Block.styleId`) instead of by
* repeating every property on itself. See docstyles.ts for resolution
* (built-ins, kind defaults, the panel that edits these) and render.ts /
* print.ts for where the bundle becomes CSS.
*
* `align`/`sb`/`sa`/`lh`/`ind` are the SAME vocabulary `Block` already has —
* a style is those five properties stored once and shared, not a parallel
* dialect. `family`/`size`/`weight`/`italic`/`color` are new: nothing before
* this let a document say what a heading looks like at all.
*/
export interface DocStyle {
id: string;
name: string;
/** the block kind this style is FOR — informs the panel, never enforced:
* nothing stops a style meant for h2 being applied to a quote */
kind: BlockKind;
/** a CSS font stack, like `TypeDoc.type.family` — no font files, no downloads */
family?: string;
/** px */ size?: number;
/** 100–900, CSS `font-weight` */ weight?: number;
italic?: boolean;
/** a CSS colour — hex, rgb()/rgba(), hsl()/hsla(), or a named colour */
color?: string;
align?: Block['align'];
/** space before, px */ sb?: number;
/** space after, px */ sa?: number;
/** line spacing, a multiple of the font size */ lh?: number;
/** first-line indent, px */ ind?: number;
}
export interface TypeDoc {
format: typeof FORMAT;
version: number;
/** minted once at creation, NEVER regenerated (PLATFORM §3) */
docId: string;
title: string;
subtitle?: string;
meta?: { author?: string; company?: string; subject?: string; keywords?: string };
page: PageSpec;
body: Block[];
/** note id → note text. Kept out of the blocks so a note can outlive a
* re-flow of the paragraph that references it. */
footnotes: Record<string, string>;
/** review threads, by id — see CommentThread */
comments?: Record<string, CommentThread>;
/** document-wide paragraph defaults; absent means the built-in ones */
layout?: { align?: Block['align']; sb?: number; sa?: number; lh?: number; ind?: number };
/**
* Named styles, by id — see DocStyle.
*
* Absent means every kind renders through docstyles.ts's built-in table,
* which is derived from styles.css exactly, so a document that never opened
* the Styles panel prints byte-for-byte what it always did. An entry here
* OVERRIDES the built-in of the same id (materialized the first time a
* built-in is edited); a document may also define ids the built-ins do not.
*/
styles?: Record<string, DocStyle>;
/**
* The document's typeface and base size.
*
* A DOCUMENT property, not a viewer preference: a contract is typeset, and
* the person who wrote it chose how it reads on paper. The theme follows the
* reader; the typeface does not.
*
* `family` is a CSS font stack, not a single name, and the choices are stacks
* that resolve on every platform without shipping a font file — a
* self-contained document cannot rely on a download, and an embedded face is
* the separate `fonts` field. `size` is px, the unit the page geometry is
* already in.
*/
type?: { family?: string; size?: number };
/**
* Optical margin alignment — hanging punctuation. See micro.ts.
*
* ABSENT MEANS ON, which is the one place this format deliberately does not
* render an old file exactly as it rendered before. What an old file promises
* is its PAGINATION, and that is untouched: the offsets are applied in
* rendering space (`position: relative`), never fed back into line breaking,
* and the pass verifies per paragraph that no line boundary moved. Only
* `false` is stored, because the default carries no information.
*/
optical?: boolean;
revisions: Revision[];
/** 128-bit, base64url. Salts the history commitment every signature carries.
* Minted at first sign, NEVER rotated, never synced (canon.ts newHistorySalt). */
historySalt?: string;
/**
* Keyed by SigId (canon.ts sigId: derived from what was signed), so each
* signature syncs as its OWN key and concurrent signers both survive (ruling
* 7). An entry under any key but its own SigId is invalid.
*/
signatures: Record<string, Signature>;
/**
* Is the document recording edits as tracked changes?
*
* DOCUMENT-level, not a viewer preference — unlike the locale, reduced motion
* or hidden comments. Whether edits are recorded is a property of the
* agreement everyone is working on: if it were per-viewer, one collaborator
* would silently make untracked edits to a document another believes is
* fully tracked, which is the one failure a tracked document cannot have.
*
* Absent means off, so every file written before this existed is untracked
* and reads identically.
*/
track?: boolean;
/**
* What a mail merge bound this document to — see merge.ts.
*
* ON THE OUTPUT, not on the template: an emitted letter carries the row it
* was made from, so its FIELDS still resolve and it is still a document
* rather than a rendering of one. Additive and optional, so a document that
* never merged has nothing here and reads exactly as it always did.
*/
merge?: { source?: string; columns?: string[]; row?: Record<string, string> };
fonts?: Array<{ family: string; asset: string; weight?: string; style?: string }>;
assets?: Record<string, string>;
readonly?: boolean;
template?: boolean;
/** volatile, never signed */
modified?: string;
/**
* Live-collaboration credentials (bento-sync), minted AT CREATION so any
* copy of the file can join once sharing is turned on. `room` is the relay
* WebSocket URL (a random id committed to the owner pubkey — never derived
* from docId), `key` the base64url AES-GCM room read key. `on` gates
* auto-join: absent = true. `sync` is the saved CRDT state, stamped at
* save-time on shared documents, so an offline-edited copy rejoins as a
* true fork. See docs/collab-design.md and type/src/sync/session.ts.
*
* type mints v2 (fine-grained access) credentials ONLY — there is no
* pre-v2 history to carry forward, unlike bento/slides. The room commits to
* an OWNER pubkey; a shared copy carries an owner-signed INVITE instead of
* `ownerPriv`, and each device mints its own member identity (kept in
* localStorage, never in the file).
*/
collab?: {
room: string;
key: string;
on?: boolean;
sync?: import('./sync/crdt.ts').SyncStateJSON;
v?: number;
owner?: string;
ownerPriv?: string;
/**
* What this COPY may do. Absent or 'writer' = it writes. 'reader' = a live
* viewer: receives updates, never sends. 'audience' = a live-SHOW member
* (kernel sync, #454): its key is the show key and its transport is
* receive-only. Typed to match the kernel's own union (sync/crdt.ts) — it
* was narrower here, which is how a role the kernel can hand us came to be
* read as a writer by collab.ts. See `copyCanWrite`.
*/
role?: 'writer' | 'reader' | 'audience';
invite?: {
pub: string;
priv: string;
role: 'writer' | 'commenter' | 'audience';
/** unix ms expiry; 0/absent = no expiry */
exp?: number;
/** owner's signature over `inv.${pub}.${role}.${exp||0}` */
sig: string;
};
/**
* The LEGACY (pre-v2) shared writer keypair. bento/type never mints one —
* its rooms are owner-keyed — but a document can ARRIVE holding one, and
* parseDoc keeps `collab` verbatim. Declared so the code that must strip
* the private half can name it: undeclared, it was the one key the share
* stripper left in every view-only copy. Matches kernel sync/crdt.ts.
*/
writerPub?: string;
writerPriv?: string;
};
/** unknown fields are PRESERVED — format additivity (PLATFORM §3) */
[extra: string]: unknown;
}
/**
* May THIS COPY write to its room?
*
* An ALLOWLIST, and the shape is the point. collab.ts used to ask
* `role !== 'reader'`, which answers "yes" for every role invented after it —
* so when the kernel added 'audience' (a live-show member whose transport is
* receive-only), type labelled that copy an Editor and offered it "Invite to
* edit…", contradicting the transport underneath. Failing CLOSED is the safe
* direction: a future role that can write would show view-only chrome until
* someone teaches this function about it, which is a visible, harmless bug;
* the old shape's failure was an invisible, misleading one.
*
* Absent means writer because every file older than the role field is one.
*/
export function copyCanWrite(collab: TypeDoc['collab'] | undefined): boolean {
if (!collab) return false;
return collab.role === undefined || collab.role === 'writer';
}
/**
* Is this a RECEIVE-ONLY copy — one that follows a room and must not edit it?
*
* Not simply `!copyCanWrite`: a document with no `collab` at all is a local
* document and is perfectly editable; `copyCanWrite` answers "no" for it only
* because there is no room to write TO. This is the question the edit lock
* asks, and it is the same one bento/slides' `canWriteDeck` answers.
*/
export function copyIsReceiveOnly(collab: TypeDoc['collab'] | undefined): boolean {
return !!collab && !copyCanWrite(collab);
}
/**
* The document as it should leave this app — WITHOUT its collaboration
* credentials.
*
* `doc.collab` carries `ownerPriv`, `writerPriv` and the room key: private
* keys and a read capability. Anything that leaves the app as text — the
* clipboard, an agent hand-off — must not carry them, or pasting "the
* document JSON" into a chat hands over write access to a live room, which is
* not revocable by deleting the message.
*
* Built FROM EMPTY by the kernel's copy table at tier 'copyJSON'
* (`projectForCopy`, with docclass.ts's TYPE_FIELDS): the whole capability
* block goes, and so does history — every revision (a WHOLE earlier draft),
* comment and signature. Text that leaves the app is a copy for someone else,
* whoever pastes it. A key this build does not declare is dropped too, so a
* field added later fails closed rather than riding out on the clipboard.
* scripts/test-export-secrets.ts asserts the credential half across every app
* with a clipboard export; scripts/test-type-share.ts asserts the rest.
*
* Mail merge (merge.ts) builds every per-recipient file from this, then mints a
* fresh docId per output — see the tier-gap note there.
*/
export function docForExport(doc: TypeDoc): TypeDoc {
return projectForCopy(withoutEmbeddedCaps(withoutCaps(doc)), TYPE_FIELDS, 'copyJSON');
}
/**
* An embedded document keeps its content, never its capabilities — at any depth.
*
* An `embed` block carries a copy of another Bento document (embed.ts), so that
* a reader can open the original. Its `collab` block is that document's sharing
* keys, and has no business inside ours. `withoutCaps` (kernel docfields.ts,
* the one shared list of capability fields) removes them from the document
* itself; this ALSO walks into bento/type's own embed blocks, because an
* embedded bento/type document can hold embeds of its own and the kernel helper
* is shallow. The walk follows bento/type's own nesting: the `body` of each
* embedded document, and the `embed` blocks within it.
*
* Pure — returns a new document where anything changed, never mutating the
* input, because one caller (docForExport) is handed the LIVE document.
*/
export function embedSafe<T>(doc: T, depth = 0): T {
if (!doc || typeof doc !== 'object') return doc;
return scrubEmbeds(withoutCaps(doc as object) as Record<string, unknown>, depth) as T;
}
/** The same walk for a document whose OWN collab is somebody else's business
* (a share-copy builder decides that) — only its embeds are made safe. */
export function withoutEmbeddedCaps<T>(doc: T): T {
if (!doc || typeof doc !== 'object') return doc;
return scrubEmbeds(doc as Record<string, unknown>, 0) as T;
}
/** Nesting deeper than this is not a real document. Past it an embed loses its
* copy of the source rather than keeping one unscrubbed: fail closed. */
const EMBED_DEPTH = 16;
function scrubEmbeds(doc: Record<string, unknown>, depth: number): Record<string, unknown> {
const body = doc.body;
if (!Array.isArray(body)) return doc;
let changed = false;
const next = body.map((b: unknown) => {
const blk = b as { kind?: unknown; embed?: { doc?: unknown } } | null;
if (!blk || blk.kind !== 'embed' || !blk.embed || !blk.embed.doc || typeof blk.embed.doc !== 'object') return b;
changed = true;
if (depth >= EMBED_DEPTH) {
const { doc: _drop, ...embed } = blk.embed;
return { ...blk, embed };
}
return { ...blk, embed: { ...blk.embed, doc: embedSafe(blk.embed.doc, depth + 1) } };
});
return changed ? { ...doc, body: next } : doc;
}
/** A footnote id a FILE may carry: what uid() mints and nothing that could
* leave an attribute. Render escapes ids too — a synced op never passes here. */
const NOTE_ID = /^[A-Za-z0-9_.:-]{1,80}$/;
/** A named style's id (`~` joins a duplicate's key, see parseDoc). */
const STYLE_ID = /^[A-Za-z0-9_.:~-]{1,160}$/;
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)}`;
};
export const newDocId = (): string => globalThis.crypto?.randomUUID?.() ?? uid('doc');
export function emptyDoc(): TypeDoc {
return {
format: FORMAT, version: VERSION, docId: newDocId(),
title: 'Untitled', page: { ...LETTER },
body: [{ id: uid(), kind: 'para', text: '' }],
footnotes: {}, revisions: [], signatures: {},
};
}
/**
* Parse result — TAGGED, never null.
*
* Following bento/spaces, which learned this the hard way: a `parseDoc` that
* returns null lets the caller fall back to the starter document, so opening a
* file from another app, or one with a single hand-edited typo, silently
* presents an EMPTY document over live data — and the first ⌘S writes it to
* disk. The only path to a starter is an absent or empty block.
*/
export type ParseResult =
| { ok: true; doc: TypeDoc; repaired: string[] }
| { 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);
/**
* Read a document, repairing what can be repaired from the BYTES ALONE.
*
* Repairs are deterministic so that two readers of one file agree on every id —
* the redline aligns blocks by id, and two parties whose copies disagree would
* see phantom changes.
*/
/**
* The `signatures` map, from whatever the file holds (ruling 7).
* - the per-signature map: kept as it is, entries that are not objects
* dropped; a key that is not its entry's own SigId is left for verify to
* report as invalid, never silently re-keyed;
* - an OLD array (before ruling 7): each entry keyed by its derived SigId,
* once, here — the same act of signing gets the same key on every replica;
* - absent or anything else: none.
* The docId is the FILE's: a SigId commits to it.
*/
function readSignatures(raw: unknown, docId: string): Record<string, Signature> {
const out: Record<string, Signature> = {};
const usable = (v: unknown): v is Signature =>
isObj(v) && typeof v.pub === 'string' && typeof v.sig === 'string';
if (Array.isArray(raw)) {
for (const v of raw) {
if (!usable(v)) continue;
let id: string;
try { id = sigId(docId, v); } catch { continue; }
if (!Object.hasOwn(out, id)) out[id] = v;
}
} else if (isObj(raw)) {
for (const [k, v] of Object.entries(raw)) if (usable(v)) out[k] = v;
}
return out;
}
export function parseDoc(raw: string): ParseResult {
const trimmed = raw.trim();
if (!trimmed) return { ok: false, err: 'empty' };
let json: unknown;
try { json = JSON.parse(trimmed); }
catch (e) { return { ok: false, err: 'json', detail: (e as Error).message }; }
if (!isObj(json)) return { ok: false, err: 'shape', detail: 'the document is not an object' };
const found = typeof json.format === 'string' ? json.format : undefined;
if (found !== FORMAT) {
return { ok: false, err: 'format',
detail: `this file is ${found ? `a ${found} document` : 'not a Bento document'}`, found };
}
if (!Array.isArray(json.body)) return { ok: false, err: 'shape', detail: 'body is missing' };
const repaired: string[] = [];
const seen = new Set<string>();
const body: Block[] = [];
(json.body as unknown[]).forEach((b, i) => {
if (!isObj(b)) { repaired.push(`dropped a block at ${i} that was not an object`); return; }
const kind: BlockKind = ['para', 'h1', 'h2', 'h3', 'quote', 'ul', 'ol', 'cell', 'image', 'caption', 'toc', 'math', 'embed'].includes(b.kind as string)
? b.kind as BlockKind : 'para';
if (kind !== b.kind) repaired.push(`block ${i}: unknown kind ${JSON.stringify(b.kind)} read as a paragraph`);
const text = typeof b.text === 'string' ? b.text : '';
// ids must be unique: the redline aligns on them, so a duplicate makes one
// paragraph invisible to review. Derive the replacement from position, so
// every reader of these bytes repairs it identically.
let id = typeof b.id === 'string' && b.id ? b.id : `b${i}`;
if (seen.has(id)) { id = `${id}~${i}`; repaired.push(`block ${i}: duplicate id repaired to ${id}`); }
seen.add(id);
const marks = Array.isArray(b.marks)
? normalize((b.marks as Mark[]).filter(m => isObj(m) && typeof m.from === 'number'
&& typeof m.to === 'number' && typeof m.t === 'string'), text.length)
: undefined;
const notes = Array.isArray(b.notes)
? (b.notes as NoteRef[]).filter(n => isObj(n) && typeof n.id === 'string' && NOTE_ID.test(n.id) && typeof n.at === 'number')
.map(n => ({ id: n.id, at: Math.max(0, Math.min(n.at, text.length)) }))
.sort((x, y) => x.at - y.at)
: undefined;
// START FROM THE INCOMING BLOCK, then overwrite what we validate.
//
// This used to be `{ id, kind, text }`, which silently DROPPED every
// block-level field this build does not know about — while doc-level
// unknowns survived on the object spread above. That breaks format
// additivity (PLATFORM §3) exactly where a word processor's additive
// fields land: a document written by a newer build, opened and saved by an
// older one, came back with its paragraph alignment, its page-break hints
// and anything else newer quietly deleted. Nothing announced it.
//
// Known fields are still validated and repaired below; unknown ones ride
// through untouched, which is the whole promise.
const out: Block = { ...(b as Partial<Block>), id, kind, text } as Block;
if (marks?.length) out.marks = marks; else delete out.marks;
if (notes?.length) out.notes = notes; else delete out.notes;
if (typeof b.role !== 'string') delete out.role;
// Now that these are KNOWN fields they are clamped like `level`, rather
// than riding through as unknowns. A generator can emit any of them.
const num = (v: unknown, lo: number, hi: number) =>
typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : undefined;
if (!['left', 'center', 'right', 'justify'].includes(out.align as string)) delete out.align;
for (const k of ['sb', 'sa', 'ind'] as const) {
const v = num(out[k], 0, 2000);
if (v === undefined) delete out[k]; else out[k] = v;
}
const lh = num(out.lh, 0.5, 4);
if (lh === undefined) delete out.lh; else out.lh = lh;
for (const k of ['keepNext', 'keepTogether', 'breakBefore'] as const) {
if (out[k] !== true) delete out[k];
}
// A styleId that resolves to nothing (a style since deleted, or a typo from
// hand-edited JSON) is kept rather than dropped, deliberately unlike a
// dangling footnote: docstyles.ts falls back to the block's KIND default
// when the id does not resolve, so an unknown id is never a rendering
// failure — only a "this named style no longer exists" the panel can show.
if (typeof b.styleId === 'string' && STYLE_ID.test(b.styleId)) out.styleId = b.styleId; else delete out.styleId;
delete out.level; delete out.cell; delete out.image; delete out.caption; delete out.refs; delete out.cites;
delete out.fields;
if (typeof b.role === 'string') out.role = b.role;
// `level` is clamped and only kept on list kinds. A level on a paragraph
// would be silently meaningless, and a level of 40 would render as a list
// indented off the page — both are files a generator can produce.
if (isList(kind) && typeof b.level === 'number' && Number.isFinite(b.level)) {
const lv = Math.max(0, Math.min(MAX_LIST_LEVEL, Math.floor(b.level)));
if (lv !== b.level) repaired.push(`block ${i}: list level ${b.level} clamped to ${lv}`);
if (lv > 0) out.level = lv;
}
// A cell without a usable `cell` ref is not a cell — it becomes a paragraph
// rather than a block the renderer has to guess about. Repaired loudly:
// silently dropping a table is worse than saying the table was lost.
if (kind === 'cell') {
const c = isObj(b.cell) ? b.cell as Partial<CellRef> : undefined;
const cols = typeof c?.cols === 'number' && c.cols >= 1 ? Math.min(Math.floor(c.cols), MAX_TABLE_COLS) : 0;
if (c && typeof c.table === 'string' && c.table && cols) {
out.cell = { table: c.table, cols };
if (c.head === true) out.cell.head = true;
if (cols !== c.cols) repaired.push(`block ${i}: table columns ${c.cols} clamped to ${cols}`);
} else {
out.kind = 'para';
repaired.push(`block ${i}: table cell with no usable placement read as a paragraph`);
}
}
// An image with no usable src is not an image. Repaired to a paragraph
// carrying its alt text, so the words survive even when the picture does
// not — a silently vanished figure is the worse outcome.
if (kind === 'image') {
const im = isObj(b.image) ? b.image as Partial<ImageRef> : undefined;
if (im && typeof im.src === 'string' && im.src && SAFE_IMG.test(im.src)) {
out.image = { src: im.src };
if (typeof im.alt === 'string') out.image.alt = im.alt;
if (typeof im.w === 'number' && im.w > 0 && im.w <= 1) out.image.w = im.w;
else if (im.w !== undefined) {
// Dropped rather than clamped: `w` is a FRACTION of the measure, so a
// value outside 0–1 is not a big number, it is a different unit —
// most likely pixels — and guessing which would be worse than
// falling back to full width. Reported, because a silent repair is
// one the author cannot learn from.
repaired.push(`block ${i}: image width ${JSON.stringify(im.w)} is not a fraction of the measure — using full width`);
}
if (im.align === 'left' || im.align === 'center' || im.align === 'right') out.image.align = im.align;
} else {
out.kind = 'para';
if (!out.text && typeof im?.alt === 'string') out.text = im.alt;
repaired.push(`block ${i}: image with no usable source read as a paragraph`);
}
}
if (kind === 'caption') {
const c = isObj(b.caption) ? b.caption as Partial<CaptionRef> : undefined;
out.caption = { kind: c?.kind === 'figure' ? 'figure' : 'table',
...(typeof c?.of === 'string' && c.of ? { of: c.of } : {}) };
}
// A dangling REFERENCE is kept, deliberately unlike a dangling note. A
// marker with no note behind it renders as a number pointing at nothing, so
// notes are dropped. A reference is the opposite case: the author wrote
// "see <that table>" and the table was deleted. Dropping it silently
// deletes the sentence's meaning and leaves prose reading "see ." Keeping
// it renders a visible ?? that says something must be fixed — the LaTeX
// behaviour, and the only safe one.
const refs = Array.isArray(b.refs)
? (b.refs as XrefRef[]).filter(r => isObj(r) && typeof r.to === 'string' && typeof r.at === 'number')
.map(r => ({ to: r.to, at: Math.max(0, Math.min(r.at, text.length)),
...(r.style === 'page' || r.style === 'both' ? { style: r.style } : {}) }))
.sort((x, y) => x.at - y.at)
: undefined;
if (refs?.length) out.refs = refs;
// No dangling-key sweep, deliberately, and for the same reason a dangling
// cross-reference is kept: a citation whose entry is missing must render
// visibly as [?key] so somebody fixes the bibliography. Dropping it deletes
// the author's claim to a source.
const cites = Array.isArray(b.cites)
? (b.cites as CiteRef[])
.filter(c => isObj(c) && typeof c.at === 'number' && Array.isArray(c.keys))
.map(c => ({
at: Math.max(0, Math.min(c.at, text.length)),
keys: c.keys.filter((k): k is string => typeof k === 'string' && !!k),
...(typeof c.locator === 'string' && c.locator ? { locator: c.locator } : {}),
...(c.suppressAuthor === true ? { suppressAuthor: true } : {}),
}))
.filter(c => c.keys.length)
.sort((x, y) => x.at - y.at)
: undefined;
if (cites?.length) out.cites = cites;
// A field whose name means nothing to this build is KEPT, like a dangling
// cross-reference and unlike a dangling footnote: an unbound field renders
// as its name in the editor and as nothing on paper (fields.ts), which is
// a visible hole somebody can fix. Dropping it would silently delete the
// author's intention to say a name there.
const fields = readFieldRefs(b.fields, text.length);
if (fields.length) out.fields = fields;
body.push(out);
});
if (!body.length) body.push({ id: uid(), kind: 'para', text: '' });
const footnotes: Record<string, string> = {};
if (isObj(json.footnotes)) {
for (const [k, v] of Object.entries(json.footnotes)) if (typeof v === 'string' && NOTE_ID.test(k)) footnotes[k] = v;
}
// a reference to a note that is not there would render as a marker with
// nothing behind it — drop the reference, keep the text
let dangling = 0;
for (const b of body) {
if (!b.notes) continue;
const keep = b.notes.filter(n => footnotes[n.id] !== undefined);
if (keep.length !== b.notes.length) dangling += b.notes.length - keep.length;
if (keep.length) b.notes = keep; else delete b.notes;
}
if (dangling) repaired.push(`dropped ${dangling} footnote reference(s) with no note behind them`);
// Named styles (DocStyle) — same repair philosophy as everything above:
// validate and clamp what is known, drop what is not, never let a bad style
// definition reach docstyles.ts, which trusts the shape it is handed.
//
// `color` is document data written straight into a `style` attribute
// (render.ts, print.ts) — the same class of hole `safeHref`/`safeFamily`
// guard in inline.ts. This is an ALLOW-LIST for the same reason theirs is:
// no `;`, no `(` beyond a bare `rgb(`/`hsl(` function, so neither a second
// declaration nor a `url()` can be formed.
const SAFE_STYLE_COLOR = /^(#[0-9a-fA-F]{3,8}|rgba?\([\d.,%\s]+\)|hsla?\([\d.,%\s]+\)|[a-zA-Z]{1,30})$/;
const numClamp = (v: unknown, lo: number, hi: number): number | undefined =>
typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : undefined;
const styles: Record<string, DocStyle> = {};
if (isObj(json.styles)) {
const usedIds = new Set<string>();
for (const [key, raw0] of Object.entries(json.styles)) {
if (!isObj(raw0)) continue;
const raw = raw0 as Record<string, unknown>;
let id = typeof raw.id === 'string' && raw.id ? raw.id : key;
// ids the app mints are block kinds; anything outside this charset is
// refused rather than carried into the style sheet (docstyles cssAttrId)
if (!STYLE_ID.test(id)) continue;
if (usedIds.has(id)) id = `${id}~${key}`;
if (!STYLE_ID.test(id)) continue;
usedIds.add(id);
const kind: BlockKind = ['para', 'h1', 'h2', 'h3', 'quote', 'ul', 'ol', 'cell', 'image', 'caption', 'toc', 'math', 'embed']
.includes(raw.kind as string) ? raw.kind as BlockKind : 'para';
const s: DocStyle = { id, name: typeof raw.name === 'string' && raw.name ? raw.name : id, kind };
if (typeof raw.family === 'string' && raw.family.trim()) s.family = raw.family.trim();
const size = numClamp(raw.size, 6, 96); if (size !== undefined) s.size = size;
const weight = numClamp(raw.weight, 100, 900); if (weight !== undefined) s.weight = Math.round(weight / 100) * 100;
if (raw.italic === true) s.italic = true;
if (typeof raw.color === 'string' && SAFE_STYLE_COLOR.test(raw.color.trim())) s.color = raw.color.trim();
if (['left', 'center', 'right', 'justify'].includes(raw.align as string)) s.align = raw.align as Block['align'];
const sb = numClamp(raw.sb, 0, 2000); if (sb !== undefined) s.sb = sb;
const sa = numClamp(raw.sa, 0, 2000); if (sa !== undefined) s.sa = sa;
const ind = numClamp(raw.ind, 0, 2000); if (ind !== undefined) s.ind = ind;
const lh = numClamp(raw.lh, 0.5, 4); if (lh !== undefined) s.lh = lh;
styles[id] = s;
}
}
const doc: TypeDoc = {
...(json as object) as TypeDoc, // unknown fields ride along
format: FORMAT,
version: typeof json.version === 'number' ? json.version : VERSION,
docId: typeof json.docId === 'string' && json.docId ? json.docId : newDocId(),
title: typeof json.title === 'string' ? json.title : 'Untitled',
page: isObj(json.page) ? readPage(json.page) : { ...LETTER },
body, footnotes,
revisions: Array.isArray(json.revisions) ? json.revisions as Revision[] : [],
...(json.track === true ? { track: true } : {}),
signatures: readSignatures(json.signatures, typeof json.docId === 'string' ? json.docId : ''),
};
// the document's default type: a filtered family and a size in range, or none
// (both are interpolated into CSS by every consumer — see readPage)
if (isObj(json.type)) {
const ty: { family?: string; size?: number } = {};
const f = safeFontFamily(json.type.family); if (f) ty.family = f;
const sz = json.type.size;
if (typeof sz === 'number' && Number.isFinite(sz) && sz >= 6 && sz <= 96) ty.size = sz;
if (Object.keys(ty).length) doc.type = ty; else delete doc.type;
} else delete doc.type;
if (Object.keys(styles).length) doc.styles = styles; else delete doc.styles;
// A salt is 16 bytes, base64url without padding: exactly 22 characters. Anything
// else is not a salt — dropped, so its signatures report the history MISSING
// rather than being checked against something that only looks like a salt.
if (typeof json.historySalt !== 'string' || !/^[A-Za-z0-9_-]{22}$/.test(json.historySalt)) delete doc.historySalt;
// only `false` is a value; anything else — including a junk one — is the default
if (json.optical === false) doc.optical = false; else delete doc.optical;
if (typeof json.docId !== 'string' || !json.docId) repaired.push('minted a missing docId');
// Comment threads: parse totally, THEN repair. The order matters and the
// feature's note says why — repairing before an anchor moves would clamp it
// against a body that has already changed.
const threads = reconcileThreads(readThreadsRaw(doc), body);
if (threads.length) doc.comments = Object.fromEntries(threads.map(t => [t.id, t]));
else delete doc.comments;
// Every document entering bento/type — a file opened, Replace from JSON,
// loadDoc, a restored snapshot — comes in with its EMBEDS made safe: an embed
// stored before intake was scrubbed, or pasted in by hand, does not carry
// another document's sharing keys into the live document. The document's own
// collab is untouched; that is this file's.
return { ok: true, doc: withoutEmbeddedCaps(doc), repaired };
}
/** The document's text, in order — what gets measured, searched and diffed. */
export const plainText = (doc: TypeDoc): string => doc.body.map(b => b.text).join('\n');
/**
* Words as a READER would count them: insertions in, tracked deletions out.
*
* A tracked deletion leaves its characters in `b.text` — that is what makes it
* rejectable — so counting the raw string reports words the document no longer
* says. Deleting a sentence would make the count go UP, since the struck text
* stays and the count has no way to know it is struck.
*
* This is the general hazard of the representation, and every other place that
* reads a block as prose has the same decision to make.
*/
export const wordCount = (doc: TypeDoc): number =>
doc.body.reduce((n, b) => {
const t = readerText(b).trim();
return n + (t ? t.split(/\s+/).length : 0);
}, 0);
/**
* `b.text` with tracked deletions removed — the prose a reader sees.
*
* It lives HERE, the module with no dependencies, rather than in track.ts,
* because track.ts imports this one and the reverse would be a cycle. track.ts
* re-exports it as textOf(). One implementation: a second copy would be two
* answers to "what does this document say", and they would diverge.
*/
export function readerText(b: Block): string {
const dels = (b.marks ?? []).filter(m => m.t === 'del').sort((x, y) => x.from - y.from);
if (!dels.length) return b.text;
let out = '', at = 0;
for (const d of dels) {
if (d.from > at) out += b.text.slice(at, d.from);
at = Math.max(at, d.to);
}
return out + b.text.slice(at);
}
/**
* Replace [at, at+removed) of a block's text with `added`, keeping marks and
* footnote anchors pointing at the same words.
*
* One function, because these two must move together: they are offsets into the
* same string, and a version of this that updated only one of them is exactly
* the bug that put a footnote marker in the middle of a word during the spike.
*/
export function spliceText(block: Block, at: number, removed: number, added: string): Block {
const text = block.text.slice(0, at) + added + block.text.slice(at + removed);
const out: Block = { ...block, text };
if (block.marks?.length) {
const m = shiftMarks(block.marks, at, removed, added.length, text.length);
if (m.length) out.marks = m; else delete out.marks;
}
if (block.cites?.length) {
const end = at + removed, delta = added.length - removed;
const c = block.cites
.filter(x => !(x.at > at && x.at < end))
.map(x => (x.at >= end ? { ...x, at: x.at + delta } : x));
if (c.length) out.cites = c; else delete out.cites;
}
if (block.refs?.length) {
const r = shiftRefs(block.refs, at, removed, added.length);
if (r.length) out.refs = r; else delete out.refs;
}
if (block.fields?.length) {
const f = shiftFields(block.fields, at, removed, added.length);
if (f.length) out.fields = f; else delete out.fields;
}
if (block.notes?.length) {
const end = at + removed;
const delta = added.length - removed;
const n = block.notes
.filter(x => !(x.at > at && x.at < end)) // its anchor text is gone
.map(x => x.at >= end ? { ...x, at: x.at + delta } : x);
if (n.length) out.notes = n; else delete out.notes;
}
return out;
}