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 block-type registry: ONE declaration per type.
//
// Adding a block type used to mean editing four files in five places — the
// renderer's tag map and list map, the / menu, the markdown-autoformat table,
// and the markdown exporter — with nothing connecting them. A type added to
// four of the five looked finished and silently exported as a bare paragraph.
//
// Now each type is one entry here and every consumer derives from it. That is
// worth stating as a rule rather than a convenience: several people (and
// several agents) add block types in parallel, and a registry turns four
// simultaneous edits to the same hot files into four independent entries.
//
// PURE DATA — no DOM, no imports from render.ts or editor.ts. That keeps the
// dependency arrow one-way (consumers import the registry, never the reverse)
// and lets a node test read it directly.
//
// Types with genuinely custom layout (image, todo, toggle, pagelink, code,
// divider) still have their rendering in render.ts and say so with
// `custom: true`; everything the registry can express lives here.
import type { Block } from './model'
import { effectiveParents, tableOf, writeTable, linkCard } from './model.ts'
import { anchorOf, embedToMd } from './embed.ts'
import type { IconName } from './icons'
export interface BlockSpec {
type: string
/**
* Menu label and hint, in ENGLISH.
*
* Not translated here: t() at module scope freezes the string at import,
* before the reader's locale is known (CLAUDE.md). English IS the key, so
* consumers call t(spec.label) at render time.
*/
label: string
hint: string
icon: IconName
/**
* Markdown prefixes that turn the block being typed into this type.
*
* A LIST, because the real ones have aliases: `- ` and `* ` both start a
* bullet, `[] ` and `[ ] ` both start a to-do. Collapsing those to one
* pattern each would quietly drop half the triggers people already use.
*/
md?: RegExp[]
/**
* Fields a block of this type needs beyond id/type.
*
* MUST NOT CLOBBER a value that is already there: this runs both on a fresh
* block and when an EXISTING block is converted (editor.setType), and a
* bullet turned into a to-do must not lose a `done` someone had already
* ticked. `m` is the markdown trigger's match, so a trigger can carry a
* value — `[!warning] ` sets the tone it named.
*/
init?: (b: Block, m?: RegExpMatchArray) => void
/** Semantic element, when the default renderer (tag + inline text) applies. */
tag?: string
/** Adjacent siblings of the same kind share one list element. */
list?: 'ul' | 'ol'
/**
* This type owns the blocks whose `parent` is its id, and the renderer gives
* it a body element to hold them.
*
* `'fold'` means the body is hidden unless `open` — the `toggle` idiom.
* `'always'` means it is never hidden, which is the whole difference between
* a callout and a toggle and is why this is a value rather than a boolean.
*/
container?: 'always' | 'fold'
/**
* In markdown, this type's whole subtree lives inside its blockquote.
*
* A GitHub alert is a blockquote: the box ends at the first line that does
* not start with `>`, and everything after it renders as loose prose. So a
* container that exports as one needs every descendant line marked, which is
* what mdLayout() below works out.
*/
mdQuoteChildren?: boolean
/**
* In markdown, this type is an html `<details>` element and its subtree
* sits between its `<summary>` and the closing `</details>` that mdLayout()
* places after the last descendant. The children are NOT indented further
* than the block itself: indenting a paragraph inside `<details>` would make
* GitHub read it as a nested list's continuation, or at four columns as code.
*/
mdDetails?: boolean
/**
* In markdown, this type's children are written at ITS OWN indent, not one
* level in: they are delimited some other way (a `</details>`, a counted
* fence), and indenting them only invites a renderer to read them as a
* nested list or code.
*/
mdLevelChildren?: boolean
/** Rendered by a dedicated case in render.ts, not by tag + inline host. */
custom?: boolean
/** Carries editable inline html. False for divider, image, pagelink. */
text?: boolean
/** Hidden from the / menu (a type reachable only another way). */
unlisted?: boolean
/**
* Markdown export. `text` is the block's inline html already converted to
* inline markdown; `indent` is set for a nested block. Absent = the text
* alone, which is also what an UNKNOWN type gets.
*/
toMd?: (b: Block, text: string, indent: string, ctx: MdCtx) => string[]
}
/**
* What the exporter can answer for a block that describes OTHER content.
*
* A pagelink needs one title; a view needs the issues it stands for. Both are
* questions about the document, and a block cannot see the document — so they
* arrive here rather than as a second export path that would drift from this
* one. A context object rather than a growing parameter list, because the next
* derived block type will want a third question.
*/
export interface MdCtx {
titleOf: (id: string) => string | undefined
/** the rows a `view` block stands for, already filtered and ordered */
rowsOf: (b: Block) => Array<{ id: string; title: string; group?: string; fields: string }>
/**
* Inline html → inline markdown.
*
* The exporter hands every block its own `html` already converted, which is
* the whole of the text for every type that HAS one string of it. A table has
* one per cell, and the converter needs a DOM (about.ts htmlToMd parses
* inert), which this file deliberately does not — so it arrives through the
* context, exactly like the two questions above.
*/
inline: (html: string) => string
/** a canvas's cards' positions, in order: `[x, y]`, or null for a card
* with none (it takes a slot at read time) */
cardsOf?: (b: Block) => Array<[number, number] | null>
}
export const SPECS: BlockSpec[] = [
{
type: 'p', label: 'Text', hint: 'Plain paragraph', icon: 'text',
tag: 'p', text: true,
},
{
type: 'h1', label: 'Heading 1', hint: '#', icon: 'h1',
tag: 'h1', text: true, md: [/^# $/],
toMd: (_b, text) => [`# ${text}`],
},
{
type: 'h2', label: 'Heading 2', hint: '##', icon: 'h2',
tag: 'h2', text: true, md: [/^## $/],
toMd: (_b, text) => [`## ${text}`],
},
{
type: 'h3', label: 'Heading 3', hint: '###', icon: 'h3',
tag: 'h3', text: true, md: [/^### $/],
toMd: (_b, text) => [`### ${text}`],
},
{
type: 'bullet', label: 'Bulleted list', hint: '-', icon: 'bullet',
tag: 'li', list: 'ul', text: true, md: [/^- $/, /^\* $/],
toMd: (_b, text, indent) => [`${indent}- ${text}`],
},
{
type: 'number', label: 'Numbered list', hint: '1.', icon: 'number',
tag: 'li', list: 'ol', text: true, md: [/^1\. $/],
toMd: (_b, text, indent) => [`${indent}1. ${text}`],
},
{
type: 'todo', label: 'To-do', hint: '[]', icon: 'todo',
tag: 'li', list: 'ul', text: true, custom: true,
md: [/^\[\] $/, /^\[ \] $/],
init: (b) => { if (b.done === undefined) b.done = false },
toMd: (b, text, indent) => [`${indent}- [${b.done ? 'x' : ' '}] ${text}`],
},
{
type: 'toggle', label: 'Toggle', hint: 'Collapsible section', icon: 'toggle',
tag: 'div', text: true, custom: true, container: 'fold', mdDetails: true, mdLevelChildren: true,
init: (b) => { if (b.open === undefined) b.open = true },
// A TOGGLE IS `<details>`, which GitHub, Obsidian and every browser render
// as the same fold — the one piece of html a Markdown reader already knows
// as "collapsible". `open` is written only when the block is open (the
// renderer reads an absent `open` as folded, and so does html). The
// summary is the block's text as inline MARKDOWN, so it reads back through
// the same converter as every other line; GitHub shows `**` literally in a
// summary, which is the price of one converter instead of two.
//
// The children follow as ordinary markdown and mdLayout() writes the
// closing `</details>` after the last of them. Exported as `- text` before
// this, and read back as a bullet: the fold and its state were lost.
toMd: (b, text, indent) => [`${indent}<details${b.open === true ? ' open' : ''}>`, `${indent}<summary>${text}</summary>`],
},
{
type: 'callout', label: 'Callout', hint: 'A note, tip or warning', icon: 'callout',
// <aside> is the semantic element, and inside our <article class="sp-page">
// it maps to role=generic rather than to a `complementary` LANDMARK (that
// mapping only applies to a top-level aside). So a page of callouts does
// not fill a screen-reader's landmark list with fifteen entries.
tag: 'aside', text: true, custom: true, container: 'always', mdQuoteChildren: true,
// `> ` converts to a quote at the space, so `> [!NOTE] ` can never be typed
// as one trigger — MEASURED, the block is already a quote by the time the
// bracket arrives. The trigger is therefore the tag ALONE, which fires just
// as well in the quote it lands in as on an empty paragraph.
md: [/^\[!(note|tip|important|warning|caution)\] $/i],
init: (b, m) => {
const named = m?.[1]?.toLowerCase()
if (named) b.tone = named
else if (b.tone === undefined) b.tone = 'note'
},
toMd: (b, text) => {
// The tone comes from a file someone MAILED you. A newline or a `]` in it
// would end the alert tag early and turn the rest of the callout into
// prose, so the exported tag is the sanitised form — while `b.tone` in
// the document is left exactly as it was found.
const tag = String(b.tone ?? 'note').toUpperCase().replace(/[^A-Z0-9_-]/g, '').slice(0, 24) || 'NOTE'
// one `> ` per LINE: htmlToMd turns <br> into a newline, and a bare
// newline inside a blockquote ends it
return [`> [!${tag}]`, ...(text ? text.split('\n') : ['']).map((l) => (l ? `> ${l}` : '>'))]
},
},
{
type: 'quote', label: 'Quote', hint: '>', icon: 'quote',
tag: 'blockquote', text: true, md: [/^> $/],
// `> ` on EVERY line, like the callout above. htmlToMd turns <br> into a
// newline, and a second line without its marker is a LAZY continuation:
// GitHub still draws it inside the quote, but it is the one spelling that
// stops at the next blank line — so `a<br><br>b` came back as a quote and a
// loose paragraph. A bare `>` keeps a blank line inside the box.
toMd: (_b, text) => text.split('\n').map((l) => (l ? `> ${l}` : '>')),
},
{
type: 'code', label: 'Code', hint: '``` ', icon: 'code',
tag: 'div', text: true, custom: true,
// The fence CARRIES ITS LANGUAGE: ```py, ```sh, ```json.
//
// Completed by a SPACE, where a bare ``` used to convert on the third
// backtick. A deliberate change to an existing trigger: every other rule
// here is space-completed (`# `, `- `, `> `, `--- `), and while ```
// converted instantly there was no keystroke left in which to type the
// language — which is the muscle memory everyone brings from GitHub and
// every other markdown box.
//
// The tag is stored VERBATIM, never normalised. `lang` is document data, so
// a language this build cannot highlight still round-trips, still exports
// as ```rust, and lights up by itself the day the lexer learns it.
md: [/^```(\w*) $/],
init: (b, m) => { const lang = m?.[1]; if (lang) b.lang = lang },
toMd: (b, text) => ['```' + String(b.lang ?? ''), text, '```'],
},
{
type: 'divider', label: 'Divider', hint: '---', icon: 'divider',
tag: 'div', custom: true, md: [/^--- $/],
toMd: () => ['---'],
},
{
// A CONTENT table: rows and columns of inline html, no formulas and nothing
// that recalculates (working/design/spaces-design.md §2.6). Custom, because a
// <table> is structure the default tag-plus-inline-host renderer cannot
// express, and `text: false` because its editable text lives in the CELLS —
// a block-level inline host beside them would be a second place to type
// that nothing displays.
type: 'table', label: 'Table', hint: 'Rows and columns', icon: 'table',
tag: 'div', custom: true,
// Also the CONVERSION path (editor.setType), so it must not clobber: a
// table turned into a paragraph and back keeps its rows. A paragraph turned
// INTO a table keeps its words, in the first header cell — the alternative
// is a block menu entry that silently discards the line you typed.
init: (b) => {
if (Array.isArray(b.rows) && b.rows.length) return
const first = typeof b.html === 'string' ? b.html : ''
writeTable(b, {
rows: [[first, '', ''], ['', '', ''], ['', '', '']],
cols: [1, 1, 1], colAlign: ['', '', ''], header: true,
})
},
toMd: (b, _text, indent, ctx) => tableToMd(b, indent, ctx.inline),
},
{
type: 'pagelink', label: 'Link to page', hint: 'A card that opens a page', icon: 'link',
tag: 'div', custom: true,
// `[[Title]]` ALONE ON ITS LINE: a wikilink, which Obsidian and Foam read
// as a link to that note, and which this app's importer reads back as a
// page card (markdown.ts). A title a wikilink cannot spell — one holding
// `[`, `]`, `|`, `#`, `^` or a newline — and a card to a missing page keep
// the old `→ [[…]]` form, which reads back as the paragraph it is.
toMd: (b, _text, _indent, ctx) => {
const title = ctx.titleOf(String(b.page))
return title && title.trim() === title && /^[^[\]|#^\n]+$/.test(title) ? [`[[${title}]]`] : [`→ [[${title ?? '?'}]]`]
},
},
{
// TRANSCLUSION — the pagelink's other half. A pagelink says where
// something is; an embed shows it, live, from the source.
//
// `text: false` for the reason a pagelink has none: the block's content is
// somewhere else, and an editable line beside it would be a second place
// to type that nothing displays. Its `html` is written by the editor as a
// plain link to the target, which is what a build that predates this type
// renders (render.ts default case) — the additivity fallback, not a copy.
type: 'embed', label: 'Embed a page', hint: 'A live view of another page', icon: 'page',
tag: 'div', custom: true,
// BACK TO THE SYNTAX IT CAME FROM. markdown.ts parses Obsidian's
// `![[Page]]` and, before this type existed, silently turned every one
// into a plain link — so a vault lost every embed on the way in and the
// export had nothing to write back. The two halves are one round trip and
// scripts/test-spaces-model.ts asserts it in both directions.
toMd: (b, _text, _indent, ctx) => [embedToMd(ctx.titleOf(String(b.page)), anchorOf(b))],
},
{
// A LINK TO SOMEWHERE ON THE WEB — the outward-facing sibling of pagelink.
//
// Every field is STORED. Notion and Slack build this card by fetching the
// url on a server and reading its OpenGraph tags; there is no server here
// and there is not going to be one, so what the card shows is what the
// author typed. See docs/DECISIONS.md for why not even an editor-time,
// opt-in fetch is on the table.
type: 'link', label: 'Link to the web', hint: 'A card for an address you type', icon: 'globe',
tag: 'div', custom: true,
// A LINK CARD IN MARKDOWN IS A LINK. Not a table, not a blockquote, not an
// html <div> — every one of those is a card-shaped thing that stops being a
// link the moment it leaves this app, and the ONE fact a link card carries
// that cannot be reconstructed is where it points.
//
// Built from the FIELDS rather than from `text`. `html` holds the same
// link, so the default export would already be close — but `html` is a
// fallback for old builds, and an export that reads it would silently
// export nothing at all for a card an agent wrote fields-only.
//
// WHAT MAKES IT A CARD, and not a paragraph that happens to be one link, is
// a trailing html comment: `<!-- bento:card site="…" image="…" -->`.
// GitHub, Obsidian and every html renderer hide a comment, so the page
// reads as the link and its description and nothing else — where a Pandoc
// `{.card site=…}` would print as text after every card, and a data: image
// in it as kilobytes of it. An UNMARKED lone link is not read as a card:
// that would turn every README line that is just a link into one. The
// fields the visible line cannot say (site, icon, image; title and desc
// for a card with no url) ride in the comment. See cardComment().
toMd: (b) => {
const c = linkCard(b)
const meta = ` ${cardComment(b, c.url)}`
// no url, no link: a card that is not clickable must not export as
// something a reader will click
if (!c.url) return [[c.title, c.desc].filter(Boolean).join(' — ') + meta]
const tail = c.desc ? ` — ${c.desc.replace(/\s*\n\s*/g, ' ')}` : ''
// `[` and `]` in a title end the link text early and leave the url as
// loose parenthesised prose (and a backslash would escape the bracket
// after it); a url holding a space or a bracket needs the angle form,
// which is what <> is FOR in CommonMark
const label = c.title.replace(/\s*\n\s*/g, ' ').replace(/([\\[\]])/g, '\\$1')
const href = /[\s()<>]/.test(c.url) ? `<${c.url}>` : c.url
return [`[${label}](${href})${tail}${meta}`]
},
},
{
// A FIELD VALUE on a page. Unlisted: fields are added from the issue header,
// not the / menu — "Field" in a block list would be a block whose value you
// then have to go and find somewhere else.
//
// It renders its own `html` on any build that does not know the type, which
// is the whole reason values are blocks rather than page keys.
type: 'prop', label: 'Field', hint: 'A typed value on this page', icon: 'tag',
tag: 'div', custom: true, unlisted: true,
// FROM THE READABLE FORM, not from the raw value. `html` already says
// "Status: In progress" — that string is the entire reason a prop block
// degrades instead of vanishing, and exporting `**status:** doing` from
// beside it published the option ID to the one audience that has no schema
// to look it up in. `text` is that html, already converted.
//
// The label is bolded by splitting at the first ": " the readable form
// itself uses; anything unexpected is emitted whole rather than guessed at.
toMd: (b, text) => {
const at = text.indexOf(': ')
const raw = String((b as { value?: unknown }).value ?? '')
if (at < 0) return [`**${text || String((b as { key?: unknown }).key ?? 'field')}**`]
const shown = text.slice(at + 2)
return [`**${text.slice(0, at)}:** ${shown || raw || '—'}`]
},
},
{
// A SAVED VIEW — a board or a list of the issues in this space. Also just a
// block, so it lives on a page, moves, duplicates, deletes and prints like
// anything else, and an older build shows its description instead.
type: 'view', label: 'Board or list', hint: 'Issues, grouped or listed', icon: 'board',
tag: 'div', custom: true,
// THE ISSUES, not the word "Issues". A board exported as its own italic
// title and nothing else — so a tracker downloaded as Markdown showed a
// heading where the work was, and a reader had to reconstruct the board
// from the pages that follow. The rows are derived (the export applies the
// same filter and sort the screen does), which is why they arrive through
// the context rather than off the block.
//
// A ```` ```bento-view ```` FENCE: the view's settings as one JSON line
// (fenceJson), which is what makes it a view again on the way back in —
// then THE ISSUES, as `//` lines the importer ignores — never `#`, which a
// tool splitting a file at its headings cuts on. The rows are derived
// (the export applies the same filter and sort the screen does), which is
// why they arrive through the context rather than off the block, and why
// they are regenerated rather than read back. Outside this app the fence is
// a code block: the settings and a readable list of the work.
toMd: (b, text, _indent, ctx) => {
const rows = ctx.rowsOf(b)
const out = ['```bento-view', fenceJson(b, text)]
if (!rows.length) out.push('// No issues.')
let group: string | undefined
for (const r of rows) {
// grouped exactly as the board groups, and a flat list when it is one
if (r.group !== undefined && r.group !== group) {
group = r.group
out.push(`// ${oneLine(group)}`)
}
const meta = r.fields ? ` — ${r.fields}` : ''
out.push(`// - ${oneLine(r.title + meta)}`)
}
return [...out, '```']
},
},
{
// A CHART OF THE TRAIL — burndown, burnup, cumulative flow.
//
// NOT A `view` LAYOUT, and the distinction is the rule rather than a filing
// preference: THE HOST FOLLOWS THE DATA SOURCE. A view reads pages live, so
// `source`/`filter`/`sort` genuinely narrow it at read time. These read
// `doc.trail`, whose rows are counts written at aggregation time — the
// pages that made a stored 47 are deliberately not in the record, so a
// `filter` key here would look like it narrowed the chart and silently
// would not. What DOES narrow it is frozen onto the period at commit
// (src/charts.ts).
//
// `text: false` and a readable `html`: the block carries its own sentence
// — "Burndown — Sprint 12 (1–14 Sept)" — which is what an older build, a
// grep, a markdown export and the static preview see. Same degradation rule
// every `prop` block follows.
type: 'chart', label: 'Chart of progress', hint: 'Burndown, burnup or cumulative flow', icon: 'board',
tag: 'div', custom: true,
init: (b) => { if (b.kind === undefined) b.kind = 'burndown' },
// MARKDOWN HAS NO CHART, and the honest export is the sentence the block
// already carries rather than a picture-shaped thing that is not a picture.
toMd: (_b, text) => [`**${text || 'Chart'}**`],
},
{
// A SPATIAL SURFACE — a storyboard, a roadmap, a mind map. Its cards are
// the blocks whose `parent` is its id, exactly like a callout's body, and
// each one carries where it sits as two flat numbers. The whole argument
// for that shape (rather than an array of cards on this block) is at the
// top of canvas.ts; the short version is that a card is a block, so it is
// already searchable, exportable, backlinked and individually mergeable.
//
// `text: true`: the canvas's own `html` is its NAME. That is also what a
// build with no `canvas` type renders — and because the cards fall out to
// the top level on such a build (renderBlocks opens no container for an
// unknown type), the name must NOT duplicate them. A table's fallback has
// to hold its cells' text and pays for it in bytes; a canvas's does not.
type: 'canvas', label: 'Canvas', hint: 'Cards you place by hand', icon: 'canvas',
tag: 'div', text: true, custom: true, container: 'always', mdLevelChildren: true,
// THE NAME, then the cards — which arrive on their own, as the indented
// lines of the blocks they are. A canvas is a picture and Markdown has no
// pictures, so the honest export is the list of what is on it, in document
// order. Positions are what does not survive, and saying so in the export
// would be a comment in someone else's document.
//
// A ```` ```bento-canvas ```` FENCE holding the canvas's settings and each
// card's position, in order (fenceJson); the cards follow it as their own
// lines, and the importer hands it the next `cards.length` blocks at its
// level. Outside this app: a code block, then the cards as text.
toMd: (b, text, _indent, ctx) => ['```bento-canvas', fenceJson(b, text, ctx.cardsOf?.(b)), '```'],
},
{
type: 'image', label: 'Image', hint: 'Embedded in the file', icon: 'image',
tag: 'div', custom: true,
// The caption is the link TITLE — `` — which the
// importer already read and this used to drop, so every captioned image
// lost its caption on the way out. Written verbatim (it is the same inline
// html both ways), with `"` and `\` escaped as CommonMark spells them in a
// title, and on one line: a newline would end the image.
//
// Its SIZE follows as a Pandoc attribute list, `{width=60% w=640 h=300}`:
// Pandoc and markdown-it-attrs read it, GitHub and Obsidian show it as
// literal text after the picture — the one visible cost, paid only by a
// sized image. Absent fields write nothing, so an unsized image exports
// exactly as it did before.
toMd: (b) => {
const cap = String(b.caption ?? '').replace(/\s*\n\s*/g, ' ')
const title = cap ? ` "${cap.replace(/["\\]/g, '\\$&')}"` : ''
return [`}${title})${sizeAttrs(b)}`]
},
},
{
type: 'media', label: 'Video or audio', hint: 'Plays in the page', icon: 'play',
tag: 'div', custom: true,
// A fresh block has no src yet — the renderer draws a chooser and the
// editor wires it. `kind` is set the moment a file or a link arrives, from
// what the file actually IS, so the default here only has to be the shape
// that degrades usefully.
init: (b) => { if (b.kind === undefined) b.kind = 'video' },
// MARKDOWN HAS NO VIDEO, so a clip leaves as the html element every
// Markdown renderer that allows html already plays — `<video>` or
// `<audio>` — WITH A LINK INSIDE IT:
//
// <video src="clip.mp4" controls loop title="The demo"><a href="clip.mp4">The demo</a></video>
//
// A renderer that plays media hides the link (it is the element's fallback
// content); a renderer that strips the tag keeps its content, which is
// the link this block used to export as. So it degrades to exactly the
// old export, and in Obsidian or a browser it plays.
//
// `autoplay` is written as `data-autoplay`: the block RECORDS it and this
// app never obeys it (mediaPlayback), and an exported file must not make
// some other renderer obey it on our behalf. The fields with no html
// attribute (the column percentage, the caption) ride as data-*;
// `width`/`height` are the intrinsic pixels, which is what those html
// attributes mean.
//
// The target is `src` verbatim, `asset:` and data: included, exactly as
// the image exporter already writes it. That does not resolve outside the
// space — which is the truth about an embedded clip.
toMd: (b) => {
const video = String(b.kind ?? 'video') !== 'audio'
const kind = video ? 'Video' : 'Audio'
const src = String(b.src ?? '')
if (!src) return [`_${kind}_`]
const alt = String(b.alt ?? '')
const at = (k: string, v: unknown) => (typeof v === 'string' && v ? ` ${k}="${attrValue(v)}"` : '')
const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined)
const tag = video ? 'video' : 'audio'
let a = ` src="${attrValue(src)}"`
if (b.controls !== false) a += ' controls'
if (b.loop === true) a += ' loop'
if (b.muted === true) a += ' muted'
if (b.autoplay === true) a += ' data-autoplay'
a += at('poster', b.poster) + at('title', alt)
const w = num(b.w), h = num(b.h)
if (w !== undefined && h !== undefined && Number.isInteger(w) && Number.isInteger(h)) a += ` width="${w}" height="${h}"`
const width = num(b.width)
if (width !== undefined) a += ` data-width="${width}"`
a += at('data-caption', b.caption)
const label = (alt || kind).replace(/\s*\n\s*/g, ' ')
return [`<${tag}${a}><a href="${attrValue(src)}">${attrValue(label)}</a></${tag}>`]
},
},
]
/**
* A block's size as a Pandoc attribute list, or '' when it has none.
*
* ONLY NUMBERS LEAVE. `width` is a percentage and `w`/`h` pixel counts; a
* field holding anything else — a string out of a hand-edited file — is not
* written, so nothing a file says can end the list early or add a key.
* `extra` is appended inside the braces (a block id, in a later family).
*/
export function sizeAttrs(b: Block, extra: string[] = []): string {
const num = (v: unknown): number | undefined =>
typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined
const parts = [...extra]
const width = num(b.width)
if (width !== undefined) parts.push(`width=${width}%`)
const w = num(b.w), h = num(b.h)
if (w !== undefined && h !== undefined && Number.isInteger(w) && Number.isInteger(h)) parts.push(`w=${w}`, `h=${h}`)
return parts.length ? `{${parts.join(' ')}}` : ''
}
/**
* A block id Markdown may carry: `{#id}` after the block's line. Ids are only
* WRITTEN for blocks something points at — a review thread anchored to the
* block, or a `#p/<page>/<block>` link — so a space with neither exports
* exactly as it always has, and the ids that do appear are the ones whose
* loss would orphan something.
*/
export const BLOCK_ID = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/
/** The id goes on the FIRST line of these (a fence's info line, the
* `<details>` tag), the LAST non-empty line of anything else. */
const ID_ON_FIRST = new Set(['code', 'toggle', 'view', 'canvas'])
/** A trailing `{#id}` would break these: a table row becomes a ragged row,
* a `---` stops being a rule. Their ids are not written (a known loss). */
export const NO_MD_ID = new Set(['table', 'divider'])
export function withBlockId(b: Block, lines: string[]): string[] {
if (NO_MD_ID.has(b.type) || !BLOCK_ID.test(b.id) || b.id in Object.prototype) return lines
let k = ID_ON_FIRST.has(b.type) ? 0 : -1
if (k < 0) for (let j = lines.length - 1; j >= 0; j--) if (lines[j].replace(/^[>\s]*/, '')) { k = j; break }
if (k < 0) return lines
const out = [...lines]
out[k] = `${out[k]} {#${b.id}}`
return out
}
/** A readable `//` line inside a fence: one line, and never a fence of its own. */
const oneLine = (s: string): string => s.replace(/\s*\n\s*/g, ' ').replace(/`/g, "'")
/**
* A view's or a canvas's fence body: ONE JSON line. `name` is the block's text
* as inline markdown, `cards` a canvas's card positions, and every other key a
* field of the block — all of them, so a field a newer build adds round-trips.
* Fields named `name` or `cards` would collide and are not written.
*/
export function fenceJson(b: Block, text: string, cards?: Array<[number, number] | null>): string {
const out: Record<string, unknown> = { name: text }
for (const [k, v] of Object.entries(b)) {
if (['id', 'type', 'parent', 'html', 'comments', 'name', 'cards'].includes(k) || v === undefined) continue
out[k] = v
}
if (cards && cards.some((c) => c)) out.cards = cards
return JSON.stringify(out)
}
/** An html attribute value (and element text): `&`, `"`, `<`, `>` as
* entities, one line. markdown.ts decodes exactly these four. */
export const attrValue = (v: string): string =>
v.replace(/&/g, '&').replace(/"/g, '"').replace(/</g, '<').replace(/>/g, '>').replace(/\s*\n\s*/g, ' ')
/**
* A data: image larger than this is left out of a card's comment. It would be
* invisible on GitHub, but not in a plain editor, where a thumbnail's worth of
* base64 after every card is the whole screen. The loss is pinned in
* scripts/test-spaces-md-strict.ts.
*/
export const CARD_IMAGE_MD_BUDGET = 512
/**
* A comment-safe attribute value. `&` first, so the others are unambiguous;
* `"` so the value cannot end early; `<` and `>` so no tag and no `-->` can
* form; and `--` because it is what ends a comment. Undone in reverse by
* markdown.ts cardFields().
*/
export const commentValue = (v: string): string =>
v.replace(/&/g, '&').replace(/"/g, '"').replace(/</g, '<').replace(/>/g, '>')
.replace(/--/g, '--').replace(/\s*\n\s*/g, ' ')
/** The marker that makes a link line a link card, with the fields the line
* itself cannot carry. Raw stored fields, never the derived fallbacks. */
export function cardComment(b: Block, url: string): string {
const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '')
const parts: string[] = []
const put = (k: string, v: string) => { if (v) parts.push(`${k}="${commentValue(v)}"`) }
if (!url) { put('title', str(b.title)); put('desc', str(b.desc)) }
put('site', str(b.site))
put('icon', str(b.icon))
const image = str(b.image)
if (!(image.startsWith('data:') && image.length > CARD_IMAGE_MD_BUDGET)) put('image', image)
return `<!-- bento:card${parts.map((p) => ` ${p}`).join('')} -->`
}
/** The `:---:` rule row's four forms, which are the whole of what GFM can say
* about alignment — and the reason `colAlign` is per column, not per cell. */
const RULE: Record<string, string> = { left: ':---', center: ':---:', right: '---:' }
/**
* A table as a GitHub-flavoured pipe table.
*
* THE HEADER ROW IS NOT OPTIONAL IN GFM: a table without one is not a table,
* it is three lines of prose full of pipes. So a `header: false` table exports
* with an EMPTY header row, which is the form every generator uses and which
* this app's own importer reads back as `header: false`.
*
* Two characters end a cell early and both can arrive from a file someone
* mailed you: a literal `|` (escaped) and a newline, which `<br>` in a cell
* becomes on the way through the inline converter (turned back into `<br>`,
* which GFM renders inside a cell — a real newline would end the row).
* An EMPTY cell is emitted as a space: `||` is a column count nobody meant.
*/
export function tableToMd(b: Block, indent: string, inline: (html: string) => string): string[] {
const t = tableOf(b)
const cell = (html: string): string =>
inline(html).replace(/\|/g, '\\|').replace(/\n/g, '<br>').trim() || ' '
const line = (cells: string[]): string => `${indent}| ${cells.join(' | ')} |`
const head = t.header ? t.rows[0] : Array<string>(t.w).fill('')
const body = t.header ? t.rows.slice(1) : t.rows
return [
line(head.map(cell)),
line(t.colAlign.map((a) => RULE[a] ?? '---')),
...body.map((r) => line(r.map(cell))),
]
}
/**
* THE PLAYBACK FLAGS A SURFACE MAY APPLY — and the one it may not.
*
* `autoplay` IS ALWAYS FALSE HERE, whatever the block says. Slides learned
* this the expensive way: autoplay set at render time fires on the editing
* canvas and in every thumbnail, so it lives in present mode, which is the one
* surface that owns playback. A space has no such surface. It has an editor, a
* reading view, a printout and a file-manager still, and a clip that starts
* itself is wrong in every one of them — the reading view because a page you
* scrolled past should not start talking, the still because it is a picture.
*
* So the rule is not "the renderer happens not to set it" — that is a property
* of one function that the next surface would have to rediscover. It is this
* function, which every surface goes through, and which cannot return true.
* `Block.autoplay` still round-trips (PLATFORM §3); it is simply not obeyed.
*
* Pure and DOM-free, so scripts/test-spaces-model.ts pins it directly.
*/
export interface MediaPlayback {
kind: 'video' | 'audio'
/** absent = shown: a player with no controls is a rectangle you cannot use */
controls: boolean
loop: boolean
/** browsers require muted for video autoplay — kept as a plain author choice
* here, because nothing in this app autoplays for it to unlock */
muted: boolean
/** ALWAYS false. See above. */
autoplay: false
}
export function mediaPlayback(b: Block): MediaPlayback {
return {
kind: String(b.kind ?? 'video') === 'audio' ? 'audio' : 'video',
controls: b.controls !== false,
loop: b.loop === true,
muted: b.muted === true,
autoplay: false,
}
}
/**
* Callout tones — a PERMANENT vocabulary.
*
* These five are GitHub's alert types, spelled exactly as GitHub spells them,
* so `tone` → `> [!TONE]` and back is the IDENTITY function. Every other
* candidate set (Docusaurus's note/tip/info/warning/danger, MkDocs' thirteen)
* needs a mapping table in the exporter, and a mapping table is a thing that
* can be got wrong once and then cannot be corrected — the wrong tone would
* already be in files on disks.
*
* FIVE, not thirteen, and no `success`: the format is additive, so a sixth tone
* can be added later and older builds will render it neutrally and keep both
* the word and its spelling (render.ts). Removing or renaming one is
* impossible. When a decision is one-way, ship the smaller set.
*
* The MARK IS A SHAPE, not a hue: circle, bulb, square, triangle, octagon. With
* the tone's name spelled out beside it, a callout is identifiable with no
* colour vision at all, on a black-and-white printout, and at a glance. The
* tints are decoration and carry no meaning on their own — deliberately, since
* amber/red/green are the pair-of-hues most readers cannot separate.
*
* There is deliberately no `label` here. The i18n sweep reads t() calls with a
* LITERAL STRING out of the source, so a label sitting in a data table ships
* English in all eight locales — which is exactly what has happened to the
* block MENU labels above. Tone names are written out as t() calls in render.ts,
* and a check in scripts/test-spaces-model.ts fails if a tone here has no case
* there.
*/
export interface ToneSpec {
tone: string
icon: IconName
}
export const CALLOUT_TONES: ToneSpec[] = [
{ tone: 'note', icon: 'toneNote' },
{ tone: 'tip', icon: 'toneTip' },
{ tone: 'important', icon: 'toneImportant' },
{ tone: 'warning', icon: 'toneWarning' },
{ tone: 'caution', icon: 'toneCaution' },
]
export const TONE: ReadonlyMap<string, ToneSpec> = new Map(CALLOUT_TONES.map((t) => [t.tone, t]))
/** Lookup by type. An UNKNOWN type returns undefined and must still render — a
* file written by a newer build opens here, and it opens as text. */
export const SPEC: ReadonlyMap<string, BlockSpec> = new Map(SPECS.map((s) => [s.type, s]))
/** The / menu and the Insert dropdown, in declaration order. */
export const MENU_SPECS = SPECS.filter((s) => !s.unlisted)
/** Markdown autoformat rules, derived so a type cannot have a menu entry and
* no trigger by accident — or a trigger nobody can find in a menu. */
export type MdRule = [RegExp, string, (b: Block, m?: RegExpMatchArray) => void]
export const MD_SPECS: MdRule[] =
SPECS.flatMap((s) => (s.md ?? []).map((re) => [re, s.type, s.init ?? (() => {})] as MdRule))
/**
* `type -> semantic element`, for EVERY type.
*
* `custom` says the renderer fills the element itself; it does not change what
* the element IS. `todo` is both custom and an `li` — filtering custom types
* out of this map would silently move to-do items out of their list.
*/
export const TAG_OF: Record<string, string> =
Object.fromEntries(SPECS.filter((s) => s.tag).map((s) => [s.type, s.tag!]))
/** Types whose adjacent siblings share one <ul>/<ol>. */
export const LIST_OF: Record<string, 'ul' | 'ol'> =
Object.fromEntries(SPECS.filter((s) => s.list).map((s) => [s.type, s.list!]))
/**
* How each block's markdown lines are decorated, for one page's flat list.
*
* The three parts a line needs that a single block cannot know on its own:
* `quote` (the `> ` markers that keep it inside the alert it belongs to),
* `indent` (list nesting), and `sep` (what goes BETWEEN this block and the
* next — a blank line normally, but a bare `>` inside an alert, because a blank
* line closes a blockquote and would split one callout into a box followed by
* loose text).
*
* It lives here, not in the exporter, for two reasons: it is derived entirely
* from registry facts (`mdQuoteChildren`), and about.ts drags in the kernel's
* update and save modules, so a node test cannot import it to check any of
* this. This is the part with the edge cases, so this is the part that has to
* be reachable from a test.
*/
export interface MdLine { quote: string; indent: string; sep: string; close: Array<{ quote: string; line: string }> }
export function mdLayout(blocks: Block[]): MdLine[] {
const byId = new Map(blocks.map((b) => [b.id, b]))
// HOP-CAPPED: `parent` is a plain id in a file anyone can hand-edit, so two
// blocks can name each other. The renderer is a pre-order pass and cannot
// loop; an ancestor walk can, and would hang an export of a document that
// displays perfectly well.
// The ancestor chain, by model.ts's ONE rule — `parent` must exist in this
// page AND appear strictly earlier. This followed the raw `parent` graph with
// a hop cap of 32, which is a cap because the graph can cycle; under the
// positional rule it cannot, so the walk terminates by construction and the
// cap is gone. (Held: an EXPORT that silently truncated at depth 32 would
// have been a quiet wrong answer, not an error.)
const eff = effectiveParents({ blocks } as never)
const owners = (b: Block): Block[] => {
const chain: Block[] = []
for (let id = eff.get(b.id); id; id = eff.get(id)) {
const o = byId.get(id)
if (!o) break
chain.push(o)
}
return chain
}
const wraps = (b: Block | undefined): boolean => !!b && SPEC.get(b.type)?.mdQuoteChildren === true
const alert = (b: Block): string | undefined => owners(b).find(wraps)?.id
const depth = (b: Block): number => owners(b).filter(wraps).length
const folds = (b: Block | undefined): boolean => !!b && SPEC.get(b.type)?.mdDetails === true
const out: MdLine[] = []
const at = new Map(blocks.map((b, i) => [b.id, i]))
blocks.forEach((b, i) => {
const parent = b.parent ? byId.get(b.parent) : undefined
// Inside a callout a child is the alert's BODY, not a nested list item.
// Indenting it makes GitHub read it as a nested list — or, at four spaces,
// as a code block. Inside a `<details>` fold it sits at the fold's own
// indent, for the same reason. (Effective parent for the fold case: the
// fold's line is already laid out, because a parent is always earlier.)
const effParent = eff.get(b.id)
const level = (x: Block | undefined): boolean => !!x && SPEC.get(x.type)?.mdLevelChildren === true
const fold = effParent !== undefined && level(byId.get(effParent)) ? at.get(effParent) : undefined
const indent = fold !== undefined ? out[fold].indent : parent && !wraps(parent) ? ' ' : ''
const next = blocks[i + 1]
// "same alert" compares the alert the NEXT block is in against the alert
// this one IS or is in, so a callout and its first child are joined, and so
// are two children of one callout — but two adjacent callouts are not.
const mine = wraps(b) ? b.id : alert(b)
const sep = next && alert(next) && alert(next) === mine ? '> '.repeat(depth(next)).trimEnd() : ''
// EVERY FOLD WHOSE SUBTREE ENDS HERE closes here, innermost first: this
// block itself if it is a fold with no children, then each fold above it
// that the next block is not inside.
const nextOwners = next ? new Set(owners(next).map((o) => o.id)) : new Set<string>()
const close: MdLine['close'] = []
for (const f of [b, ...owners(b)]) {
if (!folds(f) || nextOwners.has(f.id)) continue
const q = '> '.repeat(depth(f))
close.push({ quote: q, line: '' }, { quote: q, line: `${out[at.get(f.id)!]?.indent ?? indent}</details>` })
}
out.push({ quote: '> '.repeat(depth(b)), indent, sep, close })
})
return out
}