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/slides document model. This JSON is what lives inside the
// <script type="application/bento+json"> block of a .bento.html file.
export const FORMAT = 'bento/slides'
export const FORMAT_VERSION = 1
export type TransitionKind = 'none' | 'fade' | 'slide' | 'zoom' | 'morph'
export interface ElementBase {
/** Stable per-slide identity: `data-el-id`, selection, connector/comment
* anchors, and the CRDT node key. Also the DEFAULT morph key — elements
* sharing an id across adjacent slides morph into each other (the
* duplicate-a-slide idiom). Never mutate it to re-pair a morph; set
* `morphId` instead so identity stays stable. */
id: string
/** Optional morph-key override. When set, this element morphs with elements
* whose effective morph key (`morphId ?? id`) matches — letting two
* independently-created elements on different slides be paired without
* touching either's `id`. Omitted = fall back to `id` (the common case).
* Must not collide with another element's effective key on the SAME slide. */
morphId?: string
x: number
y: number
w: number
h: number
/** degrees, clockwise */
rotation: number
opacity: number
/**
* Drop shadow(s), rendered with CSS drop-shadow so they follow the
* element's alpha shape (rounded corners, ellipses, glyphs, image
* cutouts). An array stacks: e.g. a dark elevation shadow plus a soft
* white glow.
*/
shadow?: ShadowSpec | ShadowSpec[]
/** Gaussian blur ON this element, in px. Composed into the SAME CSS `filter`
* as `shadow` (both apply). Survives PDF/print, unlike backdrop blur. */
blur?: number
/** CSS mix-blend-mode for this element ('screen' for neon light glows,
* 'multiply'/'overlay' for editorial duotones). Omitted/'' = normal. */
blend?: string
/** Frosted-glass backdrop blur behind this element, in px (0/undefined = off).
* Screen-only: browser print/PDF drops backdrop-filter (pair with a
* translucent `fill` so PDFs show a graceful flat panel). */
backdropFilter?: number
/** presentation effects, run in present mode only */
fx?: {
/** entrance animation when the slide is shown. fade-* nudge ~16px; slide-*
* sweep ~120px in from an edge (slide-left starts to the right, etc.) */
enter?: 'fade-up' | 'fade' | 'fade-down' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down'
/** entrance duration in seconds; omitted = the per-kind default
* (slide-* 0.75s, fade-* 0.55s). Lower = snappier, higher = more languid. */
enterDur?: number
/** stagger step within the entrance sequence; equal values enter together */
order?: number
/**
* Reveal step ("animate on click", discussion #282): 1 or more means the
* element is HIDDEN when the slide appears and revealed on the n-th → —
* running its `enter` then, or a plain fade when it has none; ← hides it
* again; → leaves the slide only once every step is shown. Arriving
* backward shows every step. Absent/0 = shown with the slide. Presentation
* state, not slides: one slide, one page number, one morph pairing. An
* older shell shows every element at once. Decisions in src/steps.ts.
*/
step?: number
/** animate numeric parts of the text from 0 to their final value */
countUp?: boolean
/** continuous ambient motion (slow zoom, for full-bleed photos) */
ambient?: 'kenburns'
/**
* Ken-burns tuning. dir 'drift' (default) is the endless slow yoyo zoom;
* 'out' and 'in' play ONCE per slide entry — 'out' starts zoomed by
* `scale` and settles to rest (the classic title-photo effect).
* `scale` is the far end of the zoom (e.g. 1.06), `duration` in seconds.
*/
ken?: { dir?: 'drift' | 'out' | 'in'; scale?: number; duration?: number }
/** code only: the text types in a character at a time when it appears (present) */
typeWriter?: boolean
/** continuous looping animation */
loop?:
| { type: 'dash-march'; distance?: number; duration?: number }
| {
type: 'motion-path'
path: string
duration: number
delay?: number
/** easing over each lap (default 'none' = constant tempo) */
ease?: string
/** per-anchor speed multipliers (1 = normal, <1 dwells, >1 rushes);
* length matches the path's anchor count. Warps the arc-length map
* so the element can linger at some points and rush between others. */
speeds?: number[]
}
}
/** while presenting, clicking this element jumps to the slide with this id */
/**
* Click target while presenting: a slide id (jump there — the state-slide
* idiom), or an http(s) URL (opens in a NEW tab, never navigating the deck
* away; `isWebUrl` is the whole scheme test, so `javascript:` and `data:`
* are not links). Discussion #373/#374. Editor clicks never follow it.
*/
link?: string
/** semantic group tag — hover focus and multi-element behaviours target it */
group?: string
/**
* Editor grouping: elements sharing a groupId select and move as one
* (click any member → whole group; Alt-click digs to the individual).
* Distinct from `group`, which carries presentation semantics.
*/
groupId?: string
/**
* In-slide hover reveal: this element is only visible while an element
* whose `group` equals this value is hovered (slide.hover type 'reveal').
* The slide's hover.default set is shown when nothing is hovered.
*/
showOnHover?: string
/**
* Layout role — what this element IS on the slide ('title', 'subtitle',
* 'body', 'kicker'). Applying a different layout moves content between
* same-role elements, PowerPoint-placeholder style. Free-form string;
* those four are the conventions the built-in layouts use.
*/
role?: string
/**
* Where this element's colours came from, keyed by property path within the
* element — `fill`, `shadow.color`, `fillGradient.stops.0.color`.
*
* The literal ALWAYS stays in place; this records the palette slot it was
* derived from, so editing the palette can rewrite it. A reader that knows
* nothing about this field sees an ordinary deck of ordinary colours, which
* is exactly the point: it is additive, and property absence gains no new
* meaning. See `palette.ts`.
*/
themeRefs?: Record<string, string>
}
export interface ShadowSpec {
x?: number
y?: number
blur: number
color: string
}
export interface TextElement extends ElementBase {
type: 'text'
/** Rich text as sanitized inline HTML (b/i/u/br/span only). */
html: string
fontSize: number
fontFamily: string
fontWeight: number
color: string
/** When set (and stops non-empty), painted into the glyphs; wins over `color`. */
colorGradient?: GradientFill
align: 'left' | 'center' | 'right'
valign: 'top' | 'middle' | 'bottom'
lineHeight: number
/** px; optional tracking for letter-spaced caps labels */
letterSpacing?: number
/** Outline / hollow glyphs via -webkit-text-stroke. `fill:'none'` makes the
* interior transparent (the classic hollow section-break word); default keeps
* the solid `color` fill and just adds an outline. */
textStroke?: { width: number; color: string; fill?: string }
/**
* Layout placeholder prompt ("Click to add title"). While the element's
* html is empty: the editor shows this dimmed; present and print hide the
* element entirely. Cleared content brings the prompt back.
*/
placeholder?: string
}
export interface CodeElement extends ElementBase {
type: 'code'
/** Subset of properties of TextElement. */
fontSize: number
fontFamily: string
align: 'left' | 'center' | 'right'
valign: 'top' | 'middle' | 'bottom'
lineHeight: number
/** Determines the color of the code snippet prior to a themeId getting picked. */
color: string
/** The raw code snippets. */
content: string
/** The asset id of the grammar to use. */
grammarAssetId?: string
/** The name of the grammar */
grammarName?: string
/** The asset id of the theme to use. */
themeAssetId?: string
/** The name of the theme. */
themeName?: string
}
export type ShapeKind = 'rect' | 'ellipse' | 'triangle' | 'arrow' | 'line' | 'path'
/** Linear gradient fill. Colors are any CSS color, including rgba(). */
export interface GradientFill {
/** degrees, CSS convention: 0 = bottom→top, 90 = left→right */
angle: number
/** ordered stops; `at` is 0..1 along the gradient line */
stops: Array<{ at: number; color: string }>
}
/** Decoration at a line's tip. Sized relative to the stroke width. The
* catalogue — geometry, insets, panel labels — is slides/src/tips.ts; the
* seven kinds after `bar` arrived in 1.1.1 (#303) and are additive: an older
* shell that does not know one draws that end plain. */
export type LineEnding = 'none' | 'arrow' | 'dot' | 'bar' | 'arrow-open' | 'triangle' | 'triangle-open' | 'diamond' | 'diamond-open' | 'square' | 'circle-open'
export interface ShapeElement extends ElementBase {
type: 'shape'
shape: ShapeKind
fill: string
/** when set, wins over `fill` (which is kept as the solid fallback) */
fillGradient?: GradientFill
stroke: string
strokeWidth: number
/** corner radius, rect only */
radius: number
/** arrow only (v1.1.1, #304): 2 = a head at both ends. Absent = one head.
* A property, not a shape kind, on purpose: a shipped shell's renderer
* switches on `shape` with no default and would throw on a kind it does
* not know — an unknown property it simply ignores, so 1.1.0 draws the
* single arrow instead of failing the slide. */
heads?: 2
/** dash length in px; 0/undefined = solid stroke (legacy — see strokeStyle) */
strokeDash?: number
/** stroke pattern; wins over strokeDash when set */
strokeStyle?: 'solid' | 'dashed' | 'dotted'
/** line and (v1.1.1, #302) open path shapes: tip decorations. On a path
* the tip points along the curve's end tangent. */
lineStart?: LineEnding
lineEnd?: LineEnding
/** path only: SVG path data in the coordinate space given by pathBox */
d?: string
/** path only: [x, y, w, h] viewBox the path was authored in */
pathBox?: [number, number, number, number]
/**
* Connector anchoring (line/path only): the start (`from`) and/or end (`to`)
* of the shape follow another element. The geometry is DERIVED — the editor's
* syncConnectors() recomputes the endpoint on that element's border toward the
* other end whenever anything moves. A dangling ref (element deleted) is
* dropped and the endpoint becomes free.
*/
from?: ConnectorEnd
to?: ConnectorEnd
}
/** One anchored end of a connector. `side:'auto'` picks the nearest border. */
export interface ConnectorEnd {
el: string
side?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
}
/**
* Which part of a picture shows inside its frame (discussion #319). The frame
* is the element box; the picture is scaled to COVER it, then `scale` (≥ 1)
* enlarges it further and `x`/`y` (0..1) say which edge of the enlarged
* picture the frame is aligned to — 0 = left/top, 0.5 = centred, 1 =
* right/bottom. Absent = the element's `fit` alone, exactly as before, so a
* shell that predates this field shows the whole cover-fitted picture
* (centred) and never a blank frame. Rendered with plain CSS (crop.ts).
*/
export interface ImageCrop {
x: number
y: number
scale: number
}
export interface ImageElement extends ElementBase {
type: 'image'
/** data: URI, or "asset:<key>" referencing doc.assets */
src: string
fit: 'contain' | 'cover' | 'fill'
radius: number
/** Absent or true: a resize keeps the image's proportions (Shift frees it
* for one drag). false: width and height move independently — the frame
* can be stretched, and Shift holds the ratio for one drag instead.
* Re-locking keeps whatever shape the image has at that moment. */
keepAspectRatio?: boolean
/** pan + zoom inside the frame; absent = `fit` alone (crop.ts) */
crop?: ImageCrop
}
export interface SvgElement extends ElementBase {
type: 'svg'
/** key into doc.assets holding raw SVG markup (preferred: dedupes) */
asset?: string
/** raw inline SVG markup, used when asset is unset */
markup?: string
/**
* CSS injected inside the svg — hover states, focus dims, and animations
* live here and stay self-contained (svg <style> scopes to its svg).
*/
css?: string
}
/**
* Data chart rendered by ECharts. `option` is a PURE-JSON ECharts option
* (template-string formatters only — never functions): static SVG snapshots
* on the editor canvas/thumbnails/print, a live interactive instance
* (tooltips, dataZoom) while presenting.
*/
export interface ChartElement extends ElementBase {
type: 'chart'
/** preset key the panel offers to re-seed from (bar/line/pie/scatter) */
preset?: string
option: Record<string, unknown>
/** live data binding: xAxis labels + series values track this table element */
source?: { tableId: string }
}
/** One cell of a table. `html` is the same sanitized inline subset as text. */
export interface TableCell {
html: string
align?: 'left' | 'center' | 'right'
/** per-cell overrides (default from the table's style) */
color?: string
bg?: string
bold?: boolean
}
export interface TableRow {
cells: TableCell[]
}
/** Table-wide look. Cohesion lives here; cells carry only overrides. */
export interface TableStyle {
headerBg: string
headerColor: string
/** stripe colour for alternate body rows; absent = no zebra */
zebra?: string
borderColor: string
borderWidth: number
cellPadX: number
cellPadY: number
fontSize: number
fontFamily?: string
/** default body-cell text colour */
color: string
/** outer corner radius (px) */
radius: number
}
/**
* A data table rendered as a real HTML <table> (table-layout: fixed) by the
* shared renderer — identical on the editor canvas, thumbnails, present and
* print. Column widths are fractional weights, normalised at render. Morphs
* as a box (position/size + style colours); cell CONTENT does not morph.
*/
export interface TableElement extends ElementBase {
type: 'table'
/** fractional column weights; length = column count */
columns: Array<{ w: number }>
rows: TableRow[]
/** treat row 0 as a styled header row */
header: boolean
style: TableStyle
}
/**
* Audio or video. Hybrid storage: `src` is a data: URI (embedded — travels
* inside the .bento.html), an external URL / relative path (referenced — keeps
* the file small but needs the network / a sibling file), or "asset:<key>".
* The editor embeds small clips and warns above MEDIA_EMBED_BUDGET, offering a
* URL instead. Autoplay only fires in PRESENT mode (never on the canvas or in
* thumbnails).
*/
export interface MediaElement extends ElementBase {
type: 'media'
kind: 'video' | 'audio'
src: string
/** video only: a still shown before playback (data:/asset:/URL) */
poster?: string
/** video only: fit within the element box */
fit?: 'contain' | 'cover' | 'fill'
radius?: number
autoplay?: boolean
loop?: boolean
muted?: boolean
controls?: boolean
}
/**
* An embedded artifact, built to the `bento/embed` shape
* (docs/DECISIONS.md, 2026-08-19) so it round-trips through upstream shells.
* Three tiers, and the ORDER is the design: `view` is a static render that
* ALWAYS paints, with no extra code, in any app; `doc` is the source, so the
* embed is not a screenshot; a live sandboxed iframe is OPT-IN per element.
*
* `app: 'web'` with a `url` is a live web surface on a slide. The
* frame is created only while online AND with the offline switch off
* (render.ts:liveFrameAllowed); otherwise the view shows. Unknown `app`
* values are RENDERED (their view), never rejected.
*/
/**
* The one scheme test for anything that opens or loads a web page — an
* embed's `url` (the paste gate and the live-frame gate), an element `link`,
* a text `<a href>` — shared so no surface is looser than another. http and
* https only, bounded, no quote or angle bracket (attribute breakout); a URL
* that is merely well-formed but `javascript:`/`data:`/`file:` is not one.
*/
export const isWebUrl = (v: unknown): v is string =>
// (the quote characters are written as escapes: a bare quote inside a regex
// literal reads as an unterminated string to the source-shape rigs' masker)
typeof v === 'string' && v.length <= 2048 && /^https?:\/\/[^\s\x22\x27<>]+$/i.test(v)
export interface EmbedElement extends ElementBase {
type: 'embed'
/** the app that made it: 'bento/dash', 'bento/type', … or 'web' for a page */
app: string
/** the static render: raw <svg> markup, or "asset:<key>" holding it */
view: string
/** the source, when there is one: pure JSON, or "asset:<key>" */
doc?: unknown
/** app 'web' only: the page the live frame loads (http(s) only) */
url?: string
/** opt in to a sandboxed live iframe over the view while online */
live?: boolean
}
export type SlideElement =
| TextElement | ShapeElement | ImageElement | SvgElement | ChartElement | TableElement | MediaElement | CodeElement
| EmbedElement
/**
* A review comment thread. Editor-only metadata: never rendered while
* presenting or printing, but saved in the file so it travels with the
* document when people pass it around.
*/
export interface Comment {
id: string
/** element the thread is anchored to; absent (or dangling) = the slide */
elementId?: string
/** point anchor in slide coordinates — used when no elementId is set */
x?: number
y?: number
author: string
text: string
/** ISO datetime */
at: string
resolved?: boolean
replies?: Array<{ id: string; author: string; text: string; at: string }>
}
export interface Slide {
id: string
background: string
transition: TransitionKind
elements: SlideElement[]
notes: string
/** palette references for the slide's own colours — `background`. See palette.ts. */
themeRefs?: Record<string, string>
/** optional friendly name (link pickers, state badges) */
name?: string
/**
* Interactive state: this slide is a variant of the slide with the given
* id. It is hidden from linear navigation — reachable only via element
* links (and morphs smoothly when element ids are shared with its parent).
* While on a state: ArrowLeft returns to the parent, ArrowRight continues
* after the parent.
*/
stateOf?: string
/**
* Hidden from the show: skipped by linear navigation, left out of PDF
* export, and never chosen as the file's thumbnail — but still an ordinary
* slide you can edit, and still reachable by an element `link`, which is
* what makes it useful for backup and appendix material you jump to only
* if asked.
*
* Distinct from `stateOf`: a state is a VARIANT OF another slide (← returns
* to its parent, and it morphs with it). Hidden carries no such
* relationship — it is simply out of the linear flow.
*
* By default a hidden slide does not consume a page number either, so the
* audience sees 1..N with no gaps; `doc.present.numberHidden` restores the
* office-suite behaviour of counting it.
*/
hidden?: boolean
/**
* In the walk, but takes no page number. The arrow keys reach it like any
* slide; `{{page}}` on it shows the number of the slide before it, so it
* reads as a CONTINUATION of that page. For a build — three recommendations
* revealed one slide at a time with `morph` — the audience sees "18" three
* times instead of 18, 19, 20 (discussion #282); equally for an interstitial
* or a section card that should not count. Distinct from `hidden` (out of
* the walk) and from `stateOf` (a variant reached by link): this is the
* third answer to `paginates`, and the ONLY one that stays in `inLinearFlow`.
* Absent = counts, so every existing file is unchanged.
*/
unnumbered?: boolean
/**
* present-mode hover behaviour:
* - focus-group: dim every element outside the hovered element's group
* - reveal: show the showOnHover set matching the hovered group
* (`default` names the set visible when nothing is hovered)
*/
hover?: { type: 'focus-group' | 'reveal'; dim?: number; default?: string }
/** review comment threads (editor-only; see Comment) */
comments?: Comment[]
}
export interface BentoDoc {
format: typeof FORMAT
version: number
/**
* Stable per-document identity (uuid), minted at creation and preserved
* for the document's whole life — the rendezvous key for future
* sync / share / merge features. Never derived from content.
*/
docId: string
title: string
/**
* Optional document properties for template fields ({{author}}, {{company}},
* {{subject}}, {{event}}) and general provenance. All optional → old files
* simply lack it and every token resolves to empty. `title` stays top-level
* (load-bearing) and remains the source of {{title}}.
*/
meta?: {
author?: string
company?: string
subject?: string
event?: string
keywords?: string
}
/** slide coordinate space, px */
size: { width: number; height: number }
theme: {
background: string
color: string
accent: string
fontFamily: string
/**
* Heading face. Body text stays on `fontFamily`; this is the display face,
* mirroring OOXML's major/minor pair. Absent = headings use `fontFamily`.
*/
headingFamily?: string
/**
* The document's named brand slots, mirroring OOXML's colour scheme so an
* importer maps 1:1. Elements point at these through `themeRefs`, and
* editing a slot re-derives every literal that references it.
*
* `background`, `color` and `accent` above REMAIN the canonical values for
* `bg1`, `tx1` and `accent1` — they are not superseded, so every existing
* reader keeps working and a document with no palette still resolves those
* three. `paletteOf()` is the only thing that should assemble this.
*/
palette?: {
bg2?: string; tx2?: string
accent2?: string; accent3?: string; accent4?: string
accent5?: string; accent6?: string
hlink?: string; folHlink?: string
}
/** ordered series colours for new charts; derived from accent when absent */
chartPalette?: string[]
/** defaults for newly inserted tables; omitted decks keep the standard look */
table?: Partial<TableStyle>
/** Code Palette (Tier-0). */
codePalette?: {
// comment
c?: string,
// string
s?: string,
// number
n?: string,
// keyword
k?: string,
// function calls
f?: string,
// punctutations
p?: string,
// diff: additions
a?: string,
// diff: deletions / removals
d?: string,
}
}
/** present-mode chrome; decks with built-in chrome can turn Reveal's off */
present?: {
/**
* Count hidden slides in {{page}}/{{pages}} and the presenter's counter.
*
* Default (absent/false): they are skipped, matching interactive states —
* one rule, "skipped means uncounted", and contiguous numbering falls out
* of it. True restores what PowerPoint and Keynote do, where a hidden
* slide keeps its number so the visible ones do not renumber as you toggle
* slides in and out during rehearsal.
*/
numberHidden?: boolean
slideNumber?: boolean
controls?: boolean
progress?: boolean
/**
* Seconds a morph transition takes. Absent = 0.65, which is tuned for the
* usual case: a title sliding, a shape growing, distances of hundreds of
* pixels. Code token morphs move a single line-height — about 40px — and at
* the default that reads as a blink rather than as travel, so a deck built
* around them wants a slower beat. Clamped on read.
*/
morphSeconds?: number
/**
* Typewriter pace, in seconds per character. Absent = 0.08; clamped to
* 0.08–1 on read, and a whole run never takes longer than 6 seconds.
*/
typeWriterSeconds?: number
}
/** shared assets (raw SVG markup or data URIs), referenced by key */
assets?: Record<string, string>
/**
* Live-collab blob references for LARGE assets (docs/blob-offload.md).
*
* An asset over BLOB_INLINE_MAX cannot travel as a CRDT op — a Durable
* Object storage value caps near 2MB — so its bytes go to the relay's blob
* store and only this tiny reference is synced. Receiving peers fetch,
* decrypt and materialise the asset into `assets` themselves.
*
* NOT part of the document at rest in any meaningful sense: a saved file
* carries the real bytes in `assets`, and opening it standalone ignores this
* map entirely. It is additive and optional — older builds simply preserve
* it as an unknown field.
*/
blobs?: Record<string, { key: string; mime: string; size: number }>
/**
* embedded fonts: each entry becomes an @font-face at boot, with the font
* data living in assets (data: URI). Elements then use `family` normally.
* `asset` may instead name a face the shell carries (`builtin:…`, see
* fonts.ts BUILTIN_FONTS) — no bytes in the file; a shell that does not
* know the key renders the family with its fallback stack.
*/
fonts?: Array<{ family: string; asset: string; weight?: string; style?: string }>
/**
* Slide layouts: slide-shaped templates that live outside slides[].
* Instantiating one deep-copies its elements KEEPING their ids — slides
* born from the same layout share ids, so their common chrome morphs
* across transitions and stays traceable for a future re-apply merge.
* When absent, the editor offers its built-in starter layouts.
*/
layouts?: Slide[]
/**
* Live-collaboration credentials (bento-sync), minted AT CREATION so any
* copy of the file can join once sharing is turned on ("send the file
* first, share later" just works). `room` is the relay WebSocket URL
* (random id — never derived from docId), `key` the base64url AES-GCM
* room key. `on` gates auto-join: absent = true (v0.8.0 files only carried
* collab while actively shared). Possession of a copy IS the capability;
* "Rotate keys" re-mints both to cut old copies off. `sync` is the saved
* CRDT state (registers/liveness/text) stamped at save-time on shared
* documents — it is what lets an offline-edited copy rejoin as a true
* fork and merge both ways. Never transmitted as sync ops.
*/
collab?: {
room: string
key: string
on?: boolean
sync?: import('./sync/crdt').SyncStateJSON
/**
* Signed writes (v0.9.18+): the WRITE capability is an ECDSA P-256 keypair,
* distinct from the symmetric `key` (the READ capability). `writerPub`
* (raw, base64url) travels in EVERY copy so the relay can verify authorship;
* `writerPriv` (PKCS#8, base64url) travels ONLY in writer copies. A
* read-only copy is a writer copy with `writerPriv` stripped — the relay
* (for `w`-scheme rooms) then drops any op it tries to send. Absent on
* legacy `r`-scheme rooms, which stay permissive. See docs/collab-design.md.
*/
writerPub?: string
writerPriv?: string
/** 'reader' = this copy is a live viewer: receives updates, never sends. */
role?: 'writer' | 'reader' | 'audience'
/**
* Fine-grained access (v1.0.3+, `v: 2`): per-person keys. The room id
* commits to the OWNER's pubkey. A member copy carries an INVITE — an
* owner-signed delegation keypair — and each device mints its own identity
* key (kept in localStorage, never in the file); the chain
* owner → invite → member is what the blind relay verifies. `ownerPriv`
* travels ONLY in the owner's own copy. See docs/collab-design.md roadmap.
*/
v?: number
owner?: string
ownerPriv?: string
invite?: {
pub: string
priv: string
/** 'audience' (live broadcast) admits a receive-only socket for the
* duration of a show; it travels only in audience copies, whose `key`
* is the show key rather than the room key (see src/audience.ts). */
role: 'writer' | 'commenter' | 'audience'
/** unix ms expiry; 0/absent = no expiry */
exp?: number
/** owner's signature over `inv.${pub}.${role}.${exp||0}` */
sig: string
}
/**
* Live broadcast tickets (PRESENTER's copy only; additive, old shells
* preserve it). Minted once by "Save audience copy…" and reused for every
* show until "Issue new tickets" re-mints both halves, which kills every
* outstanding audience copy: `invite` is the owner-signed audience
* invite the relay admits on, `key` the per-show symmetric key the
* presenter double-encrypts under while live. Never in an audience copy
* (that copy carries the invite and has `key` AS its collab.key).
*/
audience?: {
invite: { pub: string; priv: string; role: 'audience'; exp?: number; sig: string }
key: string
}
}
/**
* Template file (.dotx-style): every OPEN instantiates a fresh document —
* parseDoc strips this flag, mints a new docId and drops collab, so each
* person who opens the template gets an independent deck with its own
* identity and credentials. The template file itself never changes (there
* is no file handle until the user's first save-as).
*/
template?: boolean
/**
* A read-only PLAYER file: boots straight into the presentation and never
* shows the editor. Honor-system (the JSON is right there), but it makes a
* hand-out copy present-only for everyone who doesn't go digging.
*/
readonly?: boolean
slides: Slide[]
modified: string
}
let counter = 0
export const uid = (prefix = 'el') =>
`${prefix}-${Date.now().toString(36)}-${(counter++).toString(36)}${Math.random().toString(36).slice(2, 6)}`
export const FONT_STACK =
"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
export const MONOSPACE_FONT_STACK =
"ui-monospace, 'SFMono-Regular', 'Berkeley Mono', 'Menlo', 'Consolas', monospace"
/**
* An element's effective morph key: the `morphId` override when set, else its
* own `id`. THE single definition — render.ts stamps it into `data-flip-id`,
* present.ts pairs and looks up model frames by it, and the panel uses it for
* collision checks. Computing it inline in more than one place is exactly how
* issue #54 happened: present.ts's model map keyed by `id` while every lookup
* passed a flip id, so any element carrying a `morphId` silently missed and
* never morphed. Route every morph-key read through here.
*/
export function morphKey(el: Pick<ElementBase, 'id' | 'morphId'>): string {
return el.morphId || el.id
}
/** True when a background reads as light (so it wants dark text on top). Accepts
* a #rrggbb hex; for a gradient/CSS string it samples the first hex it finds and
* falls back to "light" (the safe assumption for the model's dark default ink). */
export function isLightBg(bg: string): boolean {
const hex = /#([0-9a-fA-F]{6})/.exec(bg || '')
if (!hex) return true
const n = parseInt(hex[1], 16)
const r = (n >> 16) & 255, g = (n >> 8) & 255, b = n & 255
return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255 > 0.55 // sRGB relative luminance
}
/** A text colour that stays legible on the given background — new text/tables use
* this so a fresh element is never invisible on a dark deck. */
export function readableInk(bg: string): string {
return isLightBg(bg) ? '#1E2A3A' : '#F5F7FA'
}
export function defaultText(partial: Partial<TextElement> = {}): TextElement {
return {
id: uid('t'),
type: 'text',
x: 340, y: 300, w: 600, h: 120,
rotation: 0, opacity: 1,
html: 'Double-click to edit',
fontSize: 32,
fontFamily: FONT_STACK,
fontWeight: 400,
color: '#1E2A3A',
align: 'center',
valign: 'middle',
lineHeight: 1.25,
...partial,
}
}
// --- chart palette -----------------------------------------------------------
// New charts should wear the deck's colours, not a stock palette. A deck can
// declare theme.chartPalette; otherwise we synthesise a harmonious set from the
// single accent (accent + a cool structural counterpart, each with a light and
// deep tint) so any deck gets on-brand charts out of the box.
function hexToHsl(hex: string): [number, number, number] {
const m = hex.replace('#', '')
const r = parseInt(m.slice(0, 2), 16) / 255
const g = parseInt(m.slice(2, 4), 16) / 255
const b = parseInt(m.slice(4, 6), 16) / 255
const max = Math.max(r, g, b), min = Math.min(r, g, b)
let h = 0, s = 0; const l = (max + min) / 2
if (max !== min) {
const d = max - min
s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
if (max === r) h = (g - b) / d + (g < b ? 6 : 0)
else if (max === g) h = (b - r) / d + 2
else h = (r - g) / d + 4
h *= 60
}
return [h, s * 100, l * 100]
}
function hslToHex(h: number, s: number, l: number): string {
h = ((h % 360) + 360) % 360; s = Math.max(0, Math.min(100, s)) / 100; l = Math.max(0, Math.min(100, l)) / 100
const c = (1 - Math.abs(2 * l - 1)) * s
const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
const mm = l - c / 2
let r = 0, g = 0, b = 0
if (h < 60) { r = c; g = x } else if (h < 120) { r = x; g = c }
else if (h < 180) { g = c; b = x } else if (h < 240) { g = x; b = c }
else if (h < 300) { r = x; b = c } else { r = c; b = x }
const to = (v: number) => Math.round((v + mm) * 255).toString(16).padStart(2, '0')
return `#${to(r)}${to(g)}${to(b)}`
}
export function deriveChartPalette(accent: string): string[] {
let h: number, s: number, l: number
try { [h, s, l] = hexToHsl(accent) } catch { return ['#5470c6', '#91cc75', '#fac858', '#ee6666'] }
const coolH = h + 190
return [
accent,
hslToHex(coolH, Math.max(20, s * 0.5), Math.min(56, Math.max(44, l))), // cool counterpart
hslToHex(h, s * 0.92, Math.min(84, l + 14)), // accent light
hslToHex(coolH, Math.max(16, s * 0.38), Math.min(74, l + 20)), // cool light
hslToHex(h, s, Math.max(28, l - 16)), // accent deep
hslToHex(coolH, Math.max(24, s * 0.55), Math.max(26, l - 6)), // cool deep
]
}
// --- table → chart data extraction (shared by creation + live binding) -------
const stripCell = (html: string) =>
html.replace(/<[^>]*>/g, '').replace(/&[a-z]+;/gi, '').replace(/,/g, '').trim()
/** First column = x labels; each mostly-numeric column after = a data series. */
export function tableChartColumns(table: TableElement): { labels: string[]; cols: Array<{ name: string; data: number[]; isPct: boolean }> } {
const bodyRows = table.header ? table.rows.slice(1) : table.rows
const headerRow = table.header ? table.rows[0] : null
const labels = bodyRows.map((r) => stripCell(r.cells[0]?.html ?? ''))
const cols: Array<{ name: string; data: number[]; isPct: boolean }> = []
for (let c = 1; c < table.columns.length; c++) {
const raw = bodyRows.map((r) => r.cells[c]?.html ?? '')
const parsed = raw.map((h) => parseFloat(stripCell(h)))
if (parsed.filter((n) => !Number.isNaN(n)).length < Math.ceil(bodyRows.length / 2)) continue
cols.push({
name: headerRow ? stripCell(headerRow.cells[c]?.html ?? '') : '',
data: parsed.map((n) => (Number.isNaN(n) ? 0 : n)),
isPct: /%/.test(headerRow ? stripCell(headerRow.cells[c]?.html ?? '') : '') ||
raw.filter((h) => /%/.test(h)).length >= Math.ceil(bodyRows.length / 2),
})
}
return { labels, cols }
}
/**
* Push a linked table's current values into a chart's option IN PLACE,
* preserving the chart's styling/axis config (only xAxis labels + each series'
* data change). Returns true if anything changed. Series map to numeric columns
* by position; extra series/columns are left untouched.
*/
export function syncLinkedChart(chart: ChartElement, table: TableElement): boolean {
const before = JSON.stringify(chart.option)
const { labels, cols } = tableChartColumns(table)
const opt = chart.option as { xAxis?: any; series?: any }
if (opt.xAxis && !Array.isArray(opt.xAxis) && typeof opt.xAxis === 'object') opt.xAxis.data = labels
const series: any[] = Array.isArray(opt.series) ? opt.series : opt.series ? [opt.series] : []
series.forEach((s, i) => {
if (!s || !cols[i]) return
if (s.type === 'pie') s.data = labels.map((name, j) => ({ name, value: cols[i].data[j] ?? 0 }))
else s.data = cols[i].data
})
return JSON.stringify(chart.option) !== before
}
export function chartColorsFor(theme: BentoDoc['theme']): string[] {
return theme.chartPalette?.length ? theme.chartPalette.slice() : deriveChartPalette(theme.accent)
}
/** Give a chart option the deck's palette unless it already sets explicit colours. */
export function applyChartPalette<T extends Record<string, unknown>>(option: T, theme: BentoDoc['theme']): T {
const cur = (option as { color?: unknown }).color
if (!Array.isArray(cur) || cur.length === 0) (option as { color?: string[] }).color = chartColorsFor(theme)
return option
}
export function defaultChart(option: Record<string, unknown>, partial: Partial<ChartElement> = {}): ChartElement {
return {
id: uid('c'),
type: 'chart',
x: 400, y: 190, w: 800, h: 520,
rotation: 0, opacity: 1,
preset: 'bar',
option,
...partial,
}
}
export function defaultCode(partial: Partial<CodeElement> = {}): CodeElement {
return {
id: uid('code'),
type: 'code',
x: 235, y: 95, w: 800, h: 520,
rotation: 0, opacity: 1,
fontSize: 32,
fontFamily: MONOSPACE_FONT_STACK,
color: '#1E2A3A',
align: 'left',
valign: 'middle',
lineHeight: 1.25,
content: 'Double-click to edit',
...partial,
}
}
const DEFAULT_TABLE_STYLE: TableStyle = {
headerBg: '#1E2A3A',
headerColor: '#FFFFFF',
zebra: 'rgba(30,42,58,0.05)',
borderColor: 'rgba(30,42,58,0.14)',
borderWidth: 1,
cellPadX: 16,
cellPadY: 11,
fontSize: 18,
color: '#1E2A3A',
radius: 10,
}
/** Resolve a new table's style from built-in defaults and optional deck overrides. */
export function tableStyleFor(theme?: BentoDoc['theme']): TableStyle {
return { ...DEFAULT_TABLE_STYLE, ...(theme?.table ?? {}) }
}
export function defaultTable(
partial: Partial<TableElement> = {},
theme?: BentoDoc['theme'],
): TableElement {
const cell = (html: string): TableCell => ({ html })
return {
id: uid('tbl'),
type: 'table',
x: 240, y: 220, w: 800, h: 260,
rotation: 0, opacity: 1,
header: true,
columns: [{ w: 1 }, { w: 1 }, { w: 1 }],
rows: [
{ cells: [cell('Column A'), cell('Column B'), cell('Column C')] },
{ cells: [cell('Row 1'), cell('—'), cell('—')] },
{ cells: [cell('Row 2'), cell('—'), cell('—')] },
],
style: tableStyleFor(theme),
...partial,
}
}
export function defaultShape(shape: ShapeKind, partial: Partial<ShapeElement> = {}): ShapeElement {
return {
id: uid('s'),
type: 'shape',
shape,
x: 490, y: 260, w: 300, h: 200,
rotation: 0, opacity: 1,
fill: '#F7A600',
stroke: 'transparent',
strokeWidth: 0,
radius: shape === 'rect' ? 12 : 0,
...partial,
}
}
export function defaultImage(src: string, partial: Partial<ImageElement> = {}): ImageElement {
return {
id: uid('i'),
type: 'image',
x: 440, y: 210, w: 400, h: 300,
rotation: 0, opacity: 1,
src,
fit: 'contain',
radius: 0,
...partial,
}
}
/** Park an embedded data URI in `doc.assets` and return an `asset:` ref.
*
* Every embed goes through here so there is exactly ONE place binary content
* lives. That matters beyond tidiness: live collab offloads large `assets`
* entries to the relay's blob store, so an image written straight onto
* `el.src` was invisible to the offload and rode inline in an op batch far
* too big for a frame — it reached collaborators as nothing at all.
*
* Identical bytes reuse the same key, so duplicating an image (or pasting the
* same photo twice) costs one copy in the file and one upload on the wire.
* A URL or an existing `asset:` ref passes straight through — only `data:`
* is interned. Callers MUST run this inside a `store.commit` so the assets
* write is part of the same undo step and the same sync batch. */
export function internAsset(doc: BentoDoc, src: string): string {
if (!src.startsWith('data:')) return src
const assets = (doc.assets ??= {})
for (const k in assets) if (assets[k] === src) return `asset:${k}`
const key = uid('a')
assets[key] = src
return `asset:${key}`
}
/** Soft ceiling for embedding media as a data URI (bytes). Above this the
* editor warns — a big embed makes the .bento.html slow to open and save. */
export const MEDIA_EMBED_BUDGET = 8 * 1024 * 1024 // 8 MB
/**
* Hard ceiling for the static first-page preview every save writes into the
* shell (src/preview.ts), in bytes of serialized markup.
*
* Unlike MEDIA_EMBED_BUDGET this is not a warning the author can wave through
* — there is no author in the loop, it is spent silently on every ⌘S, and it
* is spent on a THUMBNAIL. A text page costs 2–5 KB. The thing that can blow
* up is a full-bleed photo, whose data URI would be duplicated: once in the
* document, once in the preview.
*
* 64 KB is ~10% of the shipped shell (~640 KB compressed): invisible against a
* file that size, and enough for a real page plus a logo or an icon-sized
* image. Measured: the starter deck's page one costs 25 KB (2.6% of it). Over
* it, preview.ts degrades — first dropping raster payloads, then falling back
* to a title card — rather than growing the file.
*/
export const PREVIEW_BUDGET = 64 * 1024 // 64 KB
export function defaultMedia(
kind: 'video' | 'audio',
src: string,
partial: Partial<MediaElement> = {},
): MediaElement {
const audio = kind === 'audio'
return {
id: uid('m'),
type: 'media',
kind,
x: 440, y: 210,
w: audio ? 460 : 560, h: audio ? 56 : 315,
rotation: 0, opacity: 1,
src,
fit: 'contain',
radius: audio ? 12 : 8,
controls: true,
// video defaults muted so present-mode autoplay is permitted by browsers
muted: !audio,
loop: false,
autoplay: false,
...partial,
}
}
export function emptySlide(partial: Partial<Slide> = {}): Slide {
return {
id: uid('slide'),
background: '#FFFFFF',
transition: 'fade',
elements: [],
notes: '',
...partial,
}
}
// ---------------------------------------------------------------------------
// Layouts. A layout is a Slide that lives in doc.layouts (or the built-in
// set below). Element ids are deterministic per layout and are KEPT when a
// layout is instantiated: slides born from the same layout share ids, so
// their common chrome morphs across transitions.
const ph = (
id: string,
placeholder: string,
frame: { x: number; y: number; w: number; h: number },
type: Partial<TextElement> = {},
): TextElement => ({
id,
type: 'text',
...frame,
rotation: 0, opacity: 1,
html: '',
placeholder,
fontSize: 32,
fontFamily: FONT_STACK,
fontWeight: 400,
color: '#1E2A3A',
align: 'left',
valign: 'top',
lineHeight: 1.25,
...type,
})
const bar = (id: string, frame: { x: number; y: number; w: number; h: number }): ShapeElement => ({
id, type: 'shape', shape: 'rect', ...frame,
rotation: 0, opacity: 1, fill: '#F7A600', stroke: 'transparent', strokeWidth: 0, radius: 2,
})
/** A card backdrop: a soft panel grouped with the text that sits on it. */
const card = (id: string, frame: { x: number; y: number; w: number; h: number }, role: string): ShapeElement => ({
id, type: 'shape', shape: 'rect', ...frame,
rotation: 0, opacity: 1, fill: '#F3F0EA', stroke: 'transparent', strokeWidth: 0, radius: 16,
groupId: `l3c-g${role.slice(-1)}`,
})
/**
* The canvas the built-in layout geometry below is authored against.
*
* It is NOT the model default (1280x720) — these layouts were drawn for a
* 1600x900 stage, so on a default deck every one of them used to hang off the
* right edge (`lt-title` ran to x=1440 on a 1280-wide slide) and the
* title+content body overflowed the bottom by 88px. `builtinLayouts(size)`
* scales them to the deck instead, which also makes them correct for the
* custom page sizes the slide panel offers.
*/
const LAYOUT_BASE = { width: 1600, height: 900 }
/** Rescale a built-in layout from LAYOUT_BASE onto an arbitrary canvas. */
function scaleLayout(ly: Slide, sx: number, sy: number): Slide {
// Type scales with the SMALLER axis: on a squarer canvas the limiting
// dimension is what decides whether a heading still fits its box.
const st = Math.min(sx, sy)
return {
...ly,
elements: ly.elements.map((el) => {
const next = {
...el,
x: Math.round(el.x * sx), y: Math.round(el.y * sy),
w: Math.round(el.w * sx), h: Math.round(el.h * sy),
} as SlideElement
if (next.type === 'text') {
const txt = next as TextElement
if (txt.fontSize) txt.fontSize = Math.max(8, Math.round(txt.fontSize * st))
if (txt.letterSpacing) txt.letterSpacing = Math.round(txt.letterSpacing * st * 10) / 10
}
return next
}),
}
}
/**
* The layouts every document offers out of the box (not persisted until edited).
* Pass the deck's page size to get geometry that fits it; omit it only when the
* caller just wants the element ids.
*/
export function builtinLayouts(size?: { width: number; height: number }): Slide[] {
const base: Slide[] = [
{
id: 'layout-title', name: 'Title', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
bar('lt-bar', { x: 160, y: 380, w: 72, h: 8 }),
ph('lt-title', 'Click to add title', { x: 160, y: 404, w: 1280, h: 140 },
{ fontSize: 76, fontWeight: 700, valign: 'middle', role: 'title' }),
ph('lt-sub', 'Click to add subtitle', { x: 160, y: 556, w: 1100, h: 60 },
{ fontSize: 28, color: '#45566B', valign: 'middle', role: 'subtitle' }),
],
},
{
id: 'layout-title-content', name: 'Title + content', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
ph('ltc-title', 'Click to add title', { x: 120, y: 72, w: 1360, h: 84 },
{ fontSize: 44, fontWeight: 700, valign: 'middle', role: 'title' }),
bar('ltc-rule', { x: 120, y: 168, w: 1360, h: 3 }),
ph('ltc-body', 'Click to add content', { x: 120, y: 208, w: 1360, h: 600 },
{ fontSize: 26, color: '#586A80', valign: 'top', lineHeight: 1.5, role: 'body' }),
],
},
{
id: 'layout-two-col', name: 'Two columns', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
ph('l2c-title', 'Click to add title', { x: 120, y: 72, w: 1360, h: 84 },
{ fontSize: 44, fontWeight: 700, valign: 'middle', role: 'title' }),
bar('l2c-rule', { x: 120, y: 168, w: 1360, h: 3 }),
ph('l2c-left', 'Left column', { x: 120, y: 208, w: 660, h: 600 },
{ fontSize: 24, valign: 'top', lineHeight: 1.5, role: 'body' }),
ph('l2c-right', 'Right column', { x: 820, y: 208, w: 660, h: 600 },
{ fontSize: 24, valign: 'top', lineHeight: 1.5, role: 'body' }),
],
},
{
id: 'layout-section', name: 'Section divider', background: '#1E2A3A', transition: 'fade', notes: '', elements: [
bar('lsec-bar', { x: 160, y: 396, w: 72, h: 8 }),
ph('lsec-title', 'Section title', { x: 160, y: 420, w: 1280, h: 120 },
{ fontSize: 64, fontWeight: 700, color: '#FFFFFF', valign: 'middle', role: 'title' }),
ph('lsec-kicker', 'PART 1', { x: 160, y: 350, w: 800, h: 40 },
{ fontSize: 18, fontWeight: 600, color: '#F7A600', letterSpacing: 3, valign: 'middle', role: 'kicker' }),
],
},
// Four layouts an agent reaches for (compact input: `layout` + `role`,
// compact.ts). Roles are the slot names; the card backdrops share a
// groupId per card so a card moves as one in the editor.
{
id: 'layout-three-cards', name: 'Three cards', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
ph('l3c-title', 'Click to add title', { x: 120, y: 72, w: 1360, h: 84 },
{ fontSize: 44, fontWeight: 700, valign: 'middle', role: 'title' }),
card('l3c-bg1', { x: 120, y: 220, w: 426, h: 560 }, 'card1'),
ph('l3c-card1', 'First card', { x: 152, y: 252, w: 362, h: 496 },
{ fontSize: 24, valign: 'top', lineHeight: 1.5, role: 'card1', groupId: 'l3c-g1' }),
card('l3c-bg2', { x: 587, y: 220, w: 426, h: 560 }, 'card2'),
ph('l3c-card2', 'Second card', { x: 619, y: 252, w: 362, h: 496 },
{ fontSize: 24, valign: 'top', lineHeight: 1.5, role: 'card2', groupId: 'l3c-g2' }),
card('l3c-bg3', { x: 1054, y: 220, w: 426, h: 560 }, 'card3'),
ph('l3c-card3', 'Third card', { x: 1086, y: 252, w: 362, h: 496 },
{ fontSize: 24, valign: 'top', lineHeight: 1.5, role: 'card3', groupId: 'l3c-g3' }),
],
},
{
id: 'layout-quote', name: 'Quote', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
bar('lq-bar', { x: 160, y: 300, w: 8, h: 300 }),
ph('lq-quote', 'Click to add a quote', { x: 208, y: 300, w: 1232, h: 300 },
{ fontSize: 48, fontWeight: 500, valign: 'middle', lineHeight: 1.3, role: 'quote' }),
ph('lq-attr', 'Who said it', { x: 208, y: 620, w: 1232, h: 44 },
{ fontSize: 24, color: '#586A80', valign: 'middle', role: 'attribution' }),
],
},
{
id: 'layout-image-left', name: 'Image left', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
ph('lil-image', 'Add an image', { x: 120, y: 120, w: 640, h: 660 },
{ fontSize: 24, color: '#8A98AB', align: 'center', valign: 'middle', role: 'image' }),
ph('lil-title', 'Click to add title', { x: 820, y: 120, w: 660, h: 120 },
{ fontSize: 44, fontWeight: 700, valign: 'middle', role: 'title' }),
ph('lil-body', 'Click to add content', { x: 820, y: 264, w: 660, h: 516 },
{ fontSize: 24, color: '#586A80', valign: 'top', lineHeight: 1.5, role: 'body' }),
],
},
{
id: 'layout-image-right', name: 'Image right', background: '#FFFFFF', transition: 'fade', notes: '', elements: [
ph('lir-title', 'Click to add title', { x: 120, y: 120, w: 660, h: 120 },
{ fontSize: 44, fontWeight: 700, valign: 'middle', role: 'title' }),
ph('lir-body', 'Click to add content', { x: 120, y: 264, w: 660, h: 516 },
{ fontSize: 24, color: '#586A80', valign: 'top', lineHeight: 1.5, role: 'body' }),
ph('lir-image', 'Add an image', { x: 840, y: 120, w: 640, h: 660 },
{ fontSize: 24, color: '#8A98AB', align: 'center', valign: 'middle', role: 'image' }),
],
},
{ id: 'layout-blank', name: 'Blank', background: '#FFFFFF', transition: 'fade', notes: '', elements: [] },
]
if (!size || (size.width === LAYOUT_BASE.width && size.height === LAYOUT_BASE.height)) return base
const sx = size.width / LAYOUT_BASE.width
const sy = size.height / LAYOUT_BASE.height
return base.map((ly) => scaleLayout(ly, sx, sy))
}
/** A fresh slide from a layout — new slide id, element ids KEPT (lineage). */
export function instantiateLayout(layout: Slide): Slide {
const copy: Slide = JSON.parse(JSON.stringify(layout))
return { ...copy, id: uid('slide'), name: undefined, stateOf: undefined, notes: '' }
}
const textHasContent = (e: SlideElement) =>
e.type !== 'text' || !!e.html.replace(/<br\s*\/?>/gi, '').replace(/\u200B/g, '').trim()
/**
* Apply a layout to an existing slide's elements. The matching ladder:
* 1. by id — re-applying the slide's own layout resets frames/typography
* while keeping content
* 2. by role — cross-layout: the slide's 'title' moves into the new
* layout's 'title' frame (same element type required;
* donors consumed in document order)
* Content (text html, link) rides along; the layout provides frame and
* typography. Leftover slide elements that belong to some KNOWN layout
* (old chrome, unfilled placeholders) are dropped; everything else is user
* content and survives on top of the new layout's elements.
*/
export function applyLayout(
slide: Slide,
layout: Slide,
knownLayoutElementIds: Set<string>,
): SlideElement[] {
const donors = slide.elements
const consumed = new Set<SlideElement>()
// An `image` slot is a text placeholder ("Add an image") that an IMAGE
// donor replaces outright — the picture takes the slot's frame and id, so
// slides from the same layout still morph their pictures.
const imageSlot = (lel: SlideElement) => lel.role === 'image' && lel.type === 'text'
const findDonor = (lel: SlideElement): SlideElement | undefined => {
const byId = donors.find((e) => !consumed.has(e) && e.id === lel.id)
if (byId) return byId
if (!lel.role) return undefined
return donors.find(
(e) => !consumed.has(e) && e.role === lel.role &&
((e.type === lel.type && textHasContent(e)) || (imageSlot(lel) && e.type === 'image')),
)
}
const out: SlideElement[] = layout.elements.map((lel) => {
const copy = JSON.parse(JSON.stringify(lel)) as SlideElement
const d = findDonor(lel)
if (d) {
consumed.add(d)
if (imageSlot(lel) && d.type === 'image') {
const pic = JSON.parse(JSON.stringify(d)) as SlideElement
return { ...pic, id: lel.id, x: lel.x, y: lel.y, w: lel.w, h: lel.h, rotation: lel.rotation, role: 'image' }
}
if (copy.type === 'text' && d.type === 'text' && textHasContent(d)) copy.html = d.html
if (copy.type === 'image' && d.type === 'image') {
copy.src = d.src
if (d.fit) copy.fit = d.fit
if (d.crop) copy.crop = d.crop
}
if (d.link) copy.link = d.link
}
return copy
})
for (const e of donors) {
if (consumed.has(e)) continue
// layout-owned leftovers: drop chrome and EMPTY placeholders, but text
// someone actually wrote is never silently lost — it rides along as-is
if (knownLayoutElementIds.has(e.id) && !(e.type === 'text' && textHasContent(e))) continue
out.push(e) // survives, painted above the layout
}
return out
}
/** Every element id owned by any known layout (built-ins + the document's). */
export function layoutElementIds(doc: BentoDoc): Set<string> {
const ids = new Set<string>()
for (const ly of [...builtinLayouts(), ...(doc.layouts ?? [])]) {
for (const e of ly.elements) ids.add(e.id)
}
return ids
}
/**
* Does this slide consume a page number?
*
* The single answer to that question — page fields, the presenter's counter,
* the sidebar — so they cannot disagree about which slide is "4". Interactive
* states never count; an `unnumbered` slide never counts (it continues the
* page before it); hidden slides count only when the deck opts into
* office-suite numbering.
*/
export const paginates = (s: Slide, doc: BentoDoc): boolean =>
!s.stateOf && !s.unnumbered && (!s.hidden || !!doc.present?.numberHidden)
/**
* Is this slide part of the linear walk?
*
* Deliberately NOT the same question as `paginates`. Navigation, PDF export and
* the file thumbnail all skip states and hidden slides unconditionally; only
* NUMBERING is configurable. Collapsing the two would make `numberHidden` walk
* the audience into a slide that was hidden on purpose.
*/
export const inLinearFlow = (s: Slide): boolean => !s.stateOf && !s.hidden
export const newDocId = (): string =>
typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : uid('doc')
export function newDoc(): BentoDoc {
return {
format: FORMAT,
version: FORMAT_VERSION,
docId: newDocId(),
title: 'Untitled',
size: { width: 1280, height: 720 },
theme: {
background: '#FFFFFF',
color: '#1E2A3A',
accent: '#F7A600',
fontFamily: FONT_STACK,
},
slides: [emptySlide()],
modified: new Date().toISOString(),
}
}
const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
/**
* The keys without which an element of a type cannot render — the renderer
* throws, rather than defaulting, when one is missing (see untrusted.ts for
* why the frame numbers, svg and embed are NOT here). Both gates use it:
* untrusted.ts drops a pasted element that lacks one, parseDoc drops a file's.
*/
export const REQUIRED_ELEMENT_KEYS: Readonly<Record<string, readonly string[]>> = {
text: ['html'],
shape: ['shape', 'fill'],
image: ['src'],
chart: ['option'],
table: ['columns', 'rows'],
media: ['kind', 'src'],
}
/** Can this element render? An object with a string `type` and every key its
* type requires. An element of a type this version does not know passes — a
* newer file's element is kept and saved back untouched. */
const renderableElement = (e: unknown): boolean =>
isRecord(e) && typeof e.type === 'string' &&
(REQUIRED_ELEMENT_KEYS[e.type] ?? []).every((k) => e[k] !== undefined && e[k] !== null)
/**
* Fill the fields the format REQUIRES but a hand- or agent-written document
* may omit: `title`, `version`, `size`, `theme` (and its four colour/face
* keys), on each slide `id`, `background`, `transition`, `elements` and
* `notes`, and a table element's `style`. A document that omitted `theme` passed parseDoc and then crashed
* the shell at boot — `undefined.palette` — leaving the reader on the splash
* for good; a missing `size` did the same on `width`. Each value comes from the
* editor's own defaults (newDoc, emptySlide), and ONLY where the field is
* absent or the wrong type: a value that is there is never touched, and keys
* this version does not know ride through untouched (format additivity — a
* newer file keeps everything). A slide that is not an object is dropped,
* since no version writes one, and so is an element that cannot render (not
* an object, no `type`, or missing a key its type requires — the same rule the
* paste gate applies); false when no slide is left. In place.
*/
function fillRequired(doc: Record<string, unknown>): boolean {
const base = newDoc()
if (typeof doc.title !== 'string') doc.title = base.title
if (typeof doc.version !== 'number') doc.version = base.version
const size = doc.size as Record<string, unknown> | undefined
if (!isRecord(size) || !(Number(size.width) > 0) || !(Number(size.height) > 0)) doc.size = { ...base.size }
if (!isRecord(doc.theme)) doc.theme = { ...base.theme }
else {
const theme = doc.theme
for (const k of ['background', 'color', 'accent', 'fontFamily'] as const) {
if (typeof theme[k] !== 'string') theme[k] = base.theme[k]
}
}
doc.slides = (doc.slides as unknown[]).filter(isRecord)
for (const s of doc.slides as Record<string, unknown>[]) {
const blank = emptySlide()
if (typeof s.id !== 'string' || !s.id) s.id = blank.id
if (typeof s.background !== 'string') s.background = blank.background
if (typeof s.transition !== 'string') s.transition = blank.transition
s.elements = Array.isArray(s.elements) ? s.elements.filter(renderableElement) : []
// A table's `style` is required by the type but not by renderableElement,
// and the properties panel reads it unguarded: a full document whose table
// omitted it opened, then crashed the panel when the table was selected.
// Fill it the way a new table gets it (the deck theme's table style), which
// is also what compact expansion gives a compact table.
for (const e of s.elements as Record<string, unknown>[]) {
if (e.type === 'table' && !isRecord(e.style)) e.style = tableStyleFor(doc.theme as BentoDoc['theme'])
}
if (typeof s.notes !== 'string') s.notes = blank.notes
}
return (doc.slides as unknown[]).length > 0
}
export function parseDoc(json: string): BentoDoc | null {
try {
const doc = JSON.parse(json)
if (doc && doc.format === FORMAT && Array.isArray(doc.slides) && doc.slides.length > 0) {
// The saved file names its schema (save.ts writes `$schema` first);
// it is a pointer for readers, not document data, so it never enters
// the live document — validate() would otherwise report it unknown.
delete doc.$schema
// Documents from before docId existed get one minted here; it persists
// on the next save and stays stable from then on.
if (typeof doc.docId !== 'string' || !doc.docId) doc.docId = newDocId()
if (doc.template) {
// template instantiation: this open IS a new document
delete doc.template
doc.docId = newDocId()
delete doc.collab
}
return fillRequired(doc) ? (doc as BentoDoc) : null
}
} catch {
/* fall through */
}
return null
}