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
//
// Page designs: the author's choice of how the reading surface looks.
//
// THE RULING THIS IMPLEMENTS (docs/DECISIONS.md, 2026-09-26). The author picks
// the design; the reader's light/dark setting picks between the design's two
// palettes; the app chrome stays the reader's. That reverses the 2026-08-22
// entry that made the reading surface chrome, and puts spaces where slides
// already was — a slide's background has always been document data.
//
// A DESIGN IS DATA, NOT A STYLESHEET. Every design, built in or carried by a
// document, is the same shape: two palettes, four font roles and a closed set
// of switches. ONE base stylesheet (designs.css) reads the custom properties
// and data attributes this module writes, so adding a built-in is a data entry
// here and never new CSS. When a look needs structure the tokens cannot
// express, the answer is a new SWITCH that every design can use — not a
// bespoke sheet for one of them.
//
// VALIDATED, NOT SANITIZED. A document can carry its own designs
// (`doc.designs`), and every value in one is checked against a closed rule
// before it goes anywhere near a style: a colour must be a hex colour, a
// number must sit in its range, a switch must be one of its words, a font must
// be a name from FONT_STACKS or an embedded font asset. Anything else is
// DROPPED to the base design's value and named by validate(). No author text
// ever becomes CSS — the stacks are this file's own strings, the numbers are
// numbers, and the words are attribute values the stylesheet matches exactly.
//
// RAW AUTHOR CSS DOES NOT SHIP. The security review of 2026-09-26 kept custom
// designs token-only: a stylesheet in a mailed file can fetch (tracking) and
// can overlay Save or the password gate. If that is ever revisited it arrives
// as its own field with its own sanitizer and review — never through this
// module, whose whole guarantee is that nothing here is free text.
//
// PURE AT MODULE LEVEL, DOM ONLY IN FUNCTIONS. scripts/test-spaces-model.ts
// imports this in node, so nothing here may touch `document` at import time,
// and imports carry `.ts` extensions.
import type { SpacesDoc } from './model.ts'
// ---- the shape ---------------------------------------------------------------
/** Colour roles. Every palette names all of them. */
export const PALETTE_KEYS = [
'paper', 'ink', 'muted', 'rule', 'soft',
'accent', 'accentInk', 'onAccent',
'tile', 'tileInk', 'cell1', 'cell2', 'cell3',
'toneNote', 'toneTip', 'toneImportant', 'toneWarning', 'toneCaution',
] as const
export type PaletteKey = (typeof PALETTE_KEYS)[number]
export type Palette = Record<PaletteKey, string>
/**
* The five callout tones are PALETTE ROLES, one colour each, per mode.
*
* TONE IS MEANING: a warning must not look like a tip. The first cut had a
* `tones: accent` switch that gave all five the design's one colour — and
* Studio, Almanac and Typescript drew five identical boxes, the Note reading
* "the blue one" in coral. So each design now names five hues of its own
* character, and the validator holds them pairwise apart (TONE_MIN_DISTANCE).
*/
export const TONE_KEYS = ['toneNote', 'toneTip', 'toneImportant', 'toneWarning', 'toneCaution'] as const
type ToneKey = (typeof TONE_KEYS)[number]
/** styles.css's own tone hues — the default a design inherits unless it names its own */
const APP_TONES: Record<ToneKey, string> = {
toneNote: '#7d9cbd', toneTip: '#4f9e79', toneImportant: '#8a72cc', toneWarning: '#d9a326', toneCaution: '#cd6a63',
}
type PaletteIn = Omit<Palette, ToneKey> & Partial<Pick<Palette, ToneKey>>
const pal = (p: PaletteIn): Palette => ({ ...APP_TONES, ...p })
/** Where a face is used: titles and headings, prose, labels, code/numerals. */
export const FONT_ROLES = ['display', 'body', 'label', 'mono'] as const
export type FontRole = (typeof FONT_ROLES)[number]
/**
* The font NAME LIST. A design names one of these, or an embedded font asset.
*
* SYSTEM STACKS ONLY: nothing can be fetched at runtime (PLATFORM §1), and a
* real face would travel inside every file. Whether the built-ins ever ship
* their intended faces is the maintainer's call (DECISIONS, 2026-09-26); until
* then each stack reaches for the closest face a reader's machine already has.
*/
export const FONT_STACKS: Readonly<Record<string, string>> = {
system: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
grotesk: "'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif",
humanist: "'Avenir Next', Avenir, 'Segoe UI', 'Trebuchet MS', system-ui, sans-serif",
condensed: "'Avenir Next Condensed', 'DIN Condensed', 'Arial Narrow', 'Roboto Condensed', sans-serif",
transitional: "Charter, 'Bitstream Charter', 'Sitka Text', Cambria, Georgia, serif",
oldstyle: "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', Georgia, serif",
news: "Georgia, 'Times New Roman', Times, 'Liberation Serif', serif",
mono: "ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace",
typewriter: "'American Typewriter', 'Courier Prime', 'Courier New', Courier, monospace",
rounded: "ui-rounded, 'SF Pro Rounded', 'Arial Rounded MT Bold', system-ui, sans-serif",
}
type NumRule = { kind: 'num'; min: number; max: number; unit: string }
type EnumRule = { kind: 'enum'; values: readonly string[] }
const num = (min: number, max: number, unit = ''): NumRule => ({ kind: 'num', min, max, unit })
const oneOf = (...values: string[]): EnumRule => ({ kind: 'enum', values })
/**
* Every switch and metric a design may set, with the ONLY values it may take.
*
* Numbers become custom properties (`--d-<name>`); words become data
* attributes (`data-sd-<name>`) that designs.css matches exactly. Adding a
* switch = a row here + the rules that read it in designs.css + its labels in
* designpanel.ts. Nothing else.
*/
export const PROPS = {
size: num(0.85, 1.25),
leading: num(1.3, 2),
titleSize: num(1.4, 4, 'em'),
titleWeight: num(300, 900),
titleTracking: num(-0.06, 0.04, 'em'),
titleLeading: num(0.85, 1.4),
headWeight: num(300, 900),
radius: num(0, 24, 'px'),
rule: num(1, 4, 'px'),
headStyle: oneOf('normal', 'italic'),
headCase: oneOf('none', 'upper'),
label: oneOf('plain', 'caps', 'smallcaps', 'italic'),
labelInk: oneOf('ink', 'accent'),
h2: oneOf('none', 'above', 'double', 'bar', 'under'),
dropCap: oneOf('off', 'on'),
callout: oneOf('tint', 'outline', 'rules', 'fill', 'shadow'),
quote: oneOf('plain', 'bar', 'display', 'pull', 'tile', 'indent'),
table: oneOf('grid', 'rules', 'bands'),
numerals: oneOf('lining', 'mono', 'oldstyle'),
check: oneOf('native', 'square', 'round'),
tile: oneOf('off', 'on'),
shadow: oneOf('none', 'hard'),
justify: oneOf('off', 'on'),
divider: oneOf('rule', 'ink', 'double', 'asterism', 'short'),
bullet: oneOf('disc', 'dash', 'square'),
} as const satisfies Record<string, NumRule | EnumRule>
export type PropKey = keyof typeof PROPS
export const PROP_KEYS = Object.keys(PROPS) as PropKey[]
type PropValue<K extends PropKey> = (typeof PROPS)[K] extends NumRule ? number
: (typeof PROPS)[K] extends { values: readonly (infer V)[] } ? V : never
export type Props = { [K in PropKey]: PropValue<K> }
/** A fully resolved design: every value present and valid. */
export interface Design {
light: Palette
dark: Palette
/** a FONT_STACKS name, or `asset:<key>` for a face embedded in the file */
fonts: Record<FontRole, string>
props: Props
}
/**
* What a document carries in `doc.designs[name]`: overrides on a base.
*
* Only what differs from the base is stored, so a document stays small and a
* built-in's later refinements still reach a fork of it. Unknown keys survive
* untouched (format additivity) and are ignored here.
*/
export interface DesignData {
label?: string
/** a built-in name; absent = the default look expressed as a design */
base?: string
light?: Partial<Palette>
dark?: Partial<Palette>
fonts?: Partial<Record<FontRole, string>>
props?: Partial<Props>
[extra: string]: unknown
}
// ---- the built-ins -----------------------------------------------------------
/**
* The default look, expressed as a design.
*
* NOT SELECTABLE and never written as `design:` — the default is the ABSENCE
* of the key, which renders the untouched stylesheet byte for byte. This is
* only the base a custom design starts from when it names no built-in, so a
* fork of "no design" begins where the reader already was. Its values are
* styles.css's own light and dark tokens.
*/
export const PLAIN: Design = {
light: pal({
paper: '#ffffff', ink: '#1e2a3a', muted: '#5b6472', rule: '#e3e8ef', soft: '#f5f7fa',
accent: '#f7a600', accentInk: '#7a5200', onAccent: '#1e2a3a',
tile: '#1e2a3a', tileInk: '#ffffff', cell1: '#3b6fd4', cell2: '#f7a600', cell3: '#eceff4',
}),
dark: pal({
paper: '#14181e', ink: '#e7eaf0', muted: '#8b95a4', rule: '#2e353f', soft: '#1e232b',
accent: '#f7a600', accentInk: '#f0b74e', onAccent: '#1e2a3a',
tile: '#0d1015', tileInk: '#e7eaf0', cell1: '#3b6fd4', cell2: '#f7a600', cell3: '#272d36',
}),
fonts: { display: 'system', body: 'system', label: 'system', mono: 'mono' },
props: {
size: 1, leading: 1.65, titleSize: 2.06, titleWeight: 700, titleTracking: -0.02, titleLeading: 1.18,
headWeight: 700, radius: 10, rule: 1,
headStyle: 'normal', headCase: 'none', label: 'plain', labelInk: 'ink', h2: 'none', dropCap: 'off',
callout: 'tint', quote: 'plain', table: 'grid', numerals: 'lining', check: 'native', tile: 'off',
shadow: 'none', justify: 'off', divider: 'rule', bullet: 'disc',
},
}
const make = (over: { light: PaletteIn; dark: PaletteIn; fonts: Design['fonts']; props: Partial<Props> }): Design =>
({ ...over, light: pal(over.light), dark: pal(over.dark), props: { ...PLAIN.props, ...over.props } })
/**
* The built-in designs. Each is defensible from a real publishing tradition,
* and each differs in STRUCTURE, not only in palette.
*
* ORDER IS THE PICKER'S ORDER. Names are permanent once a file says them.
*/
export const BUILT_INS: Readonly<Record<string, Design>> = {
// LEDGER — the financial report and the Swiss grid: a grotesque, numbers as
// first-class citizens in a monospace, heavy rules above sections, cobalt as
// the single signal colour, square corners everywhere.
ledger: make({
light: {
paper: '#f7f8fa', ink: '#111418', muted: '#5a616c', rule: '#d5d9e0', soft: '#eceef3',
accent: '#2743d6', accentInk: '#2743d6', onAccent: '#ffffff',
tile: '#111418', tileInk: '#f7f8fa', cell1: '#2743d6', cell2: '#d5d9e0', cell3: '#eceef3',
},
dark: {
paper: '#0e1116', ink: '#e8eaee', muted: '#9199a6', rule: '#262c36', soft: '#171b22',
accent: '#8492ff', accentInk: '#9aa6ff', onAccent: '#0e1116',
tile: '#050608', tileInk: '#e8eaee', cell1: '#8492ff', cell2: '#262c36', cell3: '#171b22',
},
fonts: { display: 'grotesk', body: 'grotesk', label: 'mono', mono: 'mono' },
props: {
titleSize: 3.1, titleWeight: 800, titleTracking: -0.035, titleLeading: 0.98, headWeight: 750,
radius: 0, rule: 2, label: 'caps', labelInk: 'accent', h2: 'above', callout: 'outline',
quote: 'bar', table: 'rules', numerals: 'mono', check: 'square', divider: 'ink', bullet: 'square',
},
}),
// ALMANAC — the literary quarterly and the seed catalogue: an old-style
// serif set large, italic heads with a short rule under them, a drop cap on
// the opening paragraph, and marigold as the one accent. The callout tones
// keep five hues of their own, in the same earthy register.
almanac: make({
light: {
paper: '#edf0e7', ink: '#1c2a21', muted: '#56645a', rule: '#cdd4c4', soft: '#e2e7da',
// #b07800, not the specimen's #c98a0b: the drop cap and a done box are
// marks that carry meaning, and #c98a0b was 2.56:1 on this paper
accent: '#b07800', accentInk: '#7f5600', onAccent: '#0f1510',
tile: '#1c2a21', tileInk: '#edf0e7', cell1: '#b07800', cell2: '#cdd4c4', cell3: '#e2e7da',
// an editorial set around the marigold: slate, sage, plum, marigold, rust
toneNote: '#5f7f8c', toneTip: '#6b8f4e', toneImportant: '#8a6a9a', toneWarning: '#b07800', toneCaution: '#b0503a',
},
dark: {
paper: '#141a16', ink: '#e3e8dd', muted: '#a1ad9f', rule: '#2c3730', soft: '#1b231e',
accent: '#e4b04a', accentInk: '#edc574', onAccent: '#141a16',
tile: '#0b0f0c', tileInk: '#e3e8dd', cell1: '#e4b04a', cell2: '#2c3730', cell3: '#1b231e',
toneNote: '#8fb0bc', toneTip: '#9cc07c', toneImportant: '#b89ac8', toneWarning: '#e4b04a', toneCaution: '#e0806a',
},
fonts: { display: 'oldstyle', body: 'transitional', label: 'transitional', mono: 'mono' },
props: {
size: 1.09, leading: 1.6, titleSize: 3.2, titleWeight: 500, titleTracking: -0.02, titleLeading: 1,
headWeight: 500, radius: 2, headStyle: 'italic', label: 'caps', labelInk: 'accent', h2: 'bar',
dropCap: 'on', callout: 'rules', quote: 'display', table: 'rules', numerals: 'oldstyle',
check: 'round', divider: 'short',
},
}),
// STUDIO — the Bento mark as layout grammar: a navy tile holding slate,
// coral and cream compartments. A canvas and a gallery become that tile;
// a quote is a navy card; a callout is a filled compartment.
studio: make({
light: {
paper: '#ffffff', ink: '#16273e', muted: '#566781', rule: '#dde3ec', soft: '#f0ebe0',
accent: '#ff9e8a', accentInk: '#b84a34', onAccent: '#16273e',
tile: '#16273e', tileInk: '#f0ebe0', cell1: '#5e7699', cell2: '#ff9e8a', cell3: '#f0ebe0',
// filled boxes, so the five hues are saturated enough to stay five
// things at a 40% fill (closest pair 42 apart)
toneNote: '#3f7fd0', toneTip: '#2fae6f', toneImportant: '#a45ee0', toneWarning: '#f5c542', toneCaution: '#ff5f4f',
},
dark: {
paper: '#0b1320', ink: '#eef1f6', muted: '#9aa8be', rule: '#223149', soft: '#16273e',
accent: '#ff9e8a', accentInk: '#ffb5a5', onAccent: '#16273e',
tile: '#1b3050', tileInk: '#f0ebe0', cell1: '#5e7699', cell2: '#ff9e8a', cell3: '#f0ebe0',
toneNote: '#3f7fd0', toneTip: '#2fae6f', toneImportant: '#a45ee0', toneWarning: '#f5c542', toneCaution: '#ff5f4f',
},
fonts: { display: 'humanist', body: 'humanist', label: 'humanist', mono: 'mono' },
props: {
size: 1.03, titleSize: 3.4, titleWeight: 800, titleTracking: -0.04, titleLeading: 0.95,
headWeight: 780, radius: 14, callout: 'fill', quote: 'tile', table: 'bands', check: 'round',
tile: 'on',
},
}),
// BROADSHEET — the newspaper: a bold news serif under thick-and-thin
// double rules, justified columns, small-caps section labels in the
// masthead red, and a pull quote set between rules.
broadsheet: make({
light: {
paper: '#f7f5ee', ink: '#141414', muted: '#57534b', rule: '#d6d1c4', soft: '#edeade',
accent: '#b3261e', accentInk: '#a3231b', onAccent: '#ffffff',
tile: '#141414', tileInk: '#f7f5ee', cell1: '#b3261e', cell2: '#d6d1c4', cell3: '#edeade',
},
dark: {
paper: '#161513', ink: '#ece8de', muted: '#a7a196', rule: '#35322c', soft: '#1f1d1a',
accent: '#ef6a5f', accentInk: '#f4877d', onAccent: '#161513',
tile: '#0b0b0a', tileInk: '#ece8de', cell1: '#ef6a5f', cell2: '#35322c', cell3: '#1f1d1a',
},
fonts: { display: 'news', body: 'news', label: 'grotesk', mono: 'mono' },
props: {
size: 1.03, leading: 1.55, titleSize: 2.9, titleWeight: 800, titleTracking: -0.015, titleLeading: 1.04,
headWeight: 800, radius: 0, rule: 1, label: 'caps', labelInk: 'accent', h2: 'double',
callout: 'outline', quote: 'pull', table: 'rules', check: 'square', justify: 'on',
divider: 'double', bullet: 'square',
},
}),
// TYPESCRIPT — the manuscript and the RFC: every face a typewriter, double
// spacing, headings in capitals and underlined as a typist would, a
// two-colour ribbon (black and red), asterisms between sections.
typescript: make({
light: {
paper: '#faf8f2', ink: '#1c1b19', muted: '#5e5b54', rule: '#cbc6ba', soft: '#f0ece2',
accent: '#c0392b', accentInk: '#a5301f', onAccent: '#ffffff',
tile: '#1c1b19', tileInk: '#faf8f2', cell1: '#c0392b', cell2: '#cbc6ba', cell3: '#f0ece2',
// the ribbon's red for caution; the other four as typed inks
toneNote: '#6b6760', toneTip: '#4f7a5c', toneImportant: '#5a5a9e', toneWarning: '#b8862b', toneCaution: '#c0392b',
},
dark: {
paper: '#121212', ink: '#e4e1d8', muted: '#9d998f', rule: '#33312d', soft: '#1c1b19',
accent: '#ff7a6b', accentInk: '#ff9285', onAccent: '#121212',
tile: '#050505', tileInk: '#e4e1d8', cell1: '#ff7a6b', cell2: '#33312d', cell3: '#1c1b19',
toneNote: '#a8a399', toneTip: '#7fb08d', toneImportant: '#9c9ce0', toneWarning: '#e0b25a', toneCaution: '#ff7a6b',
},
fonts: { display: 'typewriter', body: 'typewriter', label: 'typewriter', mono: 'typewriter' },
props: {
size: 0.95, leading: 1.85, titleSize: 1.6, titleWeight: 700, titleTracking: 0.02, titleLeading: 1.3,
headWeight: 700, radius: 0, rule: 1, headCase: 'upper', h2: 'under', callout: 'outline',
quote: 'indent', table: 'grid', check: 'square', divider: 'asterism', bullet: 'dash',
},
}),
// RISO — the risograph zine: two spot inks (federal blue and fluorescent
// pink) on cream stock, heavy capital headlines, hard offset shadows where
// the second drum mis-registers, and cards that tile in spot colours.
riso: make({
light: {
paper: '#f5f0e6', ink: '#1e2b6e', muted: '#4e5584', rule: '#cec7dc', soft: '#f6e1ea',
accent: '#ff48b0', accentInk: '#b8157d', onAccent: '#101848',
tile: '#1e2b6e', tileInk: '#f5f0e6', cell1: '#ff48b0', cell2: '#ffe800', cell3: '#00a95c',
},
dark: {
paper: '#15172e', ink: '#f3eee4', muted: '#a7a9cc', rule: '#2e3160', soft: '#1f2244',
accent: '#ff6bc1', accentInk: '#ff94d2', onAccent: '#15172e',
tile: '#232766', tileInk: '#f3eee4', cell1: '#ff48b0', cell2: '#ffe800', cell3: '#00a95c',
},
fonts: { display: 'condensed', body: 'grotesk', label: 'grotesk', mono: 'mono' },
props: {
titleSize: 3.3, titleWeight: 900, titleTracking: -0.01, titleLeading: 0.95, headWeight: 900,
radius: 0, rule: 2, headCase: 'upper', label: 'caps', h2: 'none', callout: 'shadow',
quote: 'tile', table: 'grid', check: 'square', tile: 'on', shadow: 'hard', bullet: 'square',
},
}),
}
export const BUILT_IN_NAMES: readonly string[] = Object.keys(BUILT_INS)
export const isBuiltIn = (name: unknown): name is string =>
typeof name === 'string' && Object.hasOwn(BUILT_INS, name)
/** A doc-local design name: short, lowercase, and safe as an attribute value. */
export const DESIGN_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/
// ---- validation ---------------------------------------------------------------
const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
const ASSET_FONT = /^asset:[A-Za-z0-9_~.-]{1,80}$/
/** A hex colour, normalised to #rrggbb lowercase, or null. */
export function parseColour(v: unknown): string | null {
if (typeof v !== 'string') return null
const s = v.trim()
if (!HEX.test(s)) return null
const h = s.slice(1).toLowerCase()
return `#${h.length === 3 ? h.split('').map((c) => c + c).join('') : h}`
}
/** The data: URI an `asset:<key>` font resolves to in this document, or null. */
export function fontAssetUri(doc: SpacesDoc, ref: string): string | null {
if (!ASSET_FONT.test(ref)) return null
const key = ref.slice(6)
const assets = doc.assets
if (!assets || !Object.hasOwn(assets, key)) return null
const v = assets[key]
// a font, and only a font: an image or a clip under a font role is a mistake
// the reader would see as a silent fallback, so it is refused here and named
return typeof v === 'string' && /^data:(?:font\/|application\/(?:x-)?font-|application\/vnd\.ms-fontobject)/i.test(v) ? v : null
}
/** Whether `v` is a font value this document can honour. */
export function validFont(doc: SpacesDoc, v: unknown): v is string {
if (typeof v !== 'string') return false
if (Object.hasOwn(FONT_STACKS, v)) return true
return fontAssetUri(doc, v) !== null
}
export function validProp(key: PropKey, v: unknown): boolean {
const rule: NumRule | EnumRule = PROPS[key]
if (rule.kind === 'num') return typeof v === 'number' && Number.isFinite(v) && v >= rule.min && v <= rule.max
return typeof v === 'string' && rule.values.includes(v)
}
/** One thing wrong with a document's design data, for validate(). */
export interface DesignProblem {
code: string
path: string
message: string
/** the page whose `design` this is about; absent = the space */
page?: string
}
const isObj = (v: unknown): v is Record<string, unknown> =>
!!v && typeof v === 'object' && !Array.isArray(v)
/** The doc-local designs, as an object (absent or malformed = none). */
export function localDesigns(doc: SpacesDoc): Record<string, unknown> {
const d = (doc as { designs?: unknown }).designs
return isObj(d) ? d : {}
}
/**
* A custom design's data over its base, with every invalid value dropped.
*
* `problems` collects what was dropped, so validate() can name each one — the
* renderer never needs to, because a dropped value simply falls to the base.
*/
export function resolveData(doc: SpacesDoc, name: string, data: unknown, problems: DesignProblem[] = []): Design {
const at = `designs.${name}`
if (!isObj(data)) {
problems.push({ code: 'bad-design', path: at, message: `designs.${name} is not an object, so it resolves to the default look.` })
return PLAIN
}
let base = PLAIN
if (data.base !== undefined) {
if (isBuiltIn(data.base)) base = BUILT_INS[data.base]
else problems.push({ code: 'unknown-design-base', path: `${at}.base`,
message: `base "${String(data.base)}" is not a built-in design (${BUILT_IN_NAMES.join(', ')}); the default look is used as the base.` })
}
const out: Design = {
light: { ...base.light }, dark: { ...base.dark },
fonts: { ...base.fonts }, props: { ...base.props },
}
for (const mode of ['light', 'dark'] as const) {
const pal = data[mode]
if (pal === undefined) continue
if (!isObj(pal)) { problems.push({ code: 'bad-design-value', path: `${at}.${mode}`, message: `${at}.${mode} is not an object and was ignored.` }); continue }
for (const [k, v] of Object.entries(pal)) {
if (!(PALETTE_KEYS as readonly string[]).includes(k)) {
problems.push({ code: 'unknown-design-key', path: `${at}.${mode}.${k}`, message: `"${k}" is not a colour role (${PALETTE_KEYS.join(', ')}); it is kept in the file and ignored.` })
continue
}
const c = parseColour(v)
if (c) out[mode][k as PaletteKey] = c
else problems.push({ code: 'bad-design-value', path: `${at}.${mode}.${k}`,
message: `${at}.${mode}.${k} = ${JSON.stringify(v)} is not a #rgb or #rrggbb colour; the base design's ${base[mode][k as PaletteKey]} is used.` })
}
}
if (data.fonts !== undefined) {
if (!isObj(data.fonts)) problems.push({ code: 'bad-design-value', path: `${at}.fonts`, message: `${at}.fonts is not an object and was ignored.` })
else for (const [k, v] of Object.entries(data.fonts)) {
if (!(FONT_ROLES as readonly string[]).includes(k)) {
problems.push({ code: 'unknown-design-key', path: `${at}.fonts.${k}`, message: `"${k}" is not a font role (${FONT_ROLES.join(', ')}); it is kept in the file and ignored.` })
continue
}
if (validFont(doc, v)) out.fonts[k as FontRole] = v
else problems.push({ code: 'bad-design-value', path: `${at}.fonts.${k}`,
message: `${at}.fonts.${k} = ${JSON.stringify(v)} is neither a font name (${Object.keys(FONT_STACKS).join(', ')}) nor an embedded font asset; the base design's "${base.fonts[k as FontRole]}" is used.` })
}
}
if (data.props !== undefined) {
if (!isObj(data.props)) problems.push({ code: 'bad-design-value', path: `${at}.props`, message: `${at}.props is not an object and was ignored.` })
else for (const [k, v] of Object.entries(data.props)) {
if (!Object.hasOwn(PROPS, k)) {
problems.push({ code: 'unknown-design-key', path: `${at}.props.${k}`, message: `"${k}" is not a design switch this build knows; it is kept in the file and ignored.` })
continue
}
const key = k as PropKey
if (validProp(key, v)) (out.props as Record<string, unknown>)[key] = v
else {
const rule: NumRule | EnumRule = PROPS[key]
const allowed = rule.kind === 'num' ? `a number from ${rule.min} to ${rule.max}` : `one of ${rule.values.join(', ')}`
problems.push({ code: 'bad-design-value', path: `${at}.props.${k}`,
message: `${at}.props.${k} = ${JSON.stringify(v)} is not ${allowed}; the base design's ${JSON.stringify(base.props[key])} is used.` })
}
}
}
// A NEW GROUND BRINGS ITS OWN INK. Picking a dark teal accent over a base
// whose text-on-accent is near-black would otherwise fail the floor and
// throw the accent away — the author's one choice, discarded for the
// sake of a value they never touched. So an ink the data did NOT set is
// re-chosen for the ground it did.
for (const mode of ['light', 'dark'] as const) {
const set = isObj(data[mode]) ? data[mode] as Record<string, unknown> : {}
const pal = out[mode]
const best = (bg: string, ...cands: string[]) => cands.reduce((a, c) => (contrast(bg, c) > contrast(bg, a) ? c : a))
if (set.accent !== undefined && set.onAccent === undefined) pal.onAccent = best(pal.accent, base[mode].onAccent, pal.ink, pal.paper, '#ffffff', '#000000')
if (set.tile !== undefined && set.tileInk === undefined) pal.tileInk = best(pal.tile, base[mode].tileInk, pal.ink, pal.paper, '#ffffff')
}
enforceFloors(out, base, at, problems)
return out
}
/**
* THE FLOORS: no design may hide text.
*
* `design`/`designs` are ordinary collaborative registers, so any writer in a
* live space can restyle every reader's page as they type. That is accepted —
* a writer can already edit the words — but a design must never make words
* DISAPPEAR, which a palette can do with nothing but colours (ink = paper).
* So every text-on-ground pair a design paints is held to a contrast floor,
* and a pair under it falls back to the base design's colours:
*
* text, secondary text and accent text on paper ......... 4.5:1
* text on wells (code, table heads, board columns) ....... 4.5:1
* text on the accent fill, text on the tile .............. 4.5:1
* each tile cell against the ink chosen for it ........... 4.5:1
*
* The OTHER floors are in PROPS: text size never under 0.85 of the reading
* size (13.6px at the smallest), line spacing never under 1.3, the title
* never under 1.4em. And there is deliberately NO switch for display,
* visibility, opacity or generated text — the only `content` in designs.css
* is decoration on a divider, a checkbox tick and a heading bar, all constant.
*/
export const CONTRAST_FLOORS: ReadonlyArray<readonly [fg: PaletteKey, bg: PaletteKey, min: number]> = [
['ink', 'paper', 4.5], ['muted', 'paper', 4.5], ['accentInk', 'paper', 4.5],
['ink', 'soft', 4.5], ['onAccent', 'accent', 4.5], ['tileInk', 'tile', 4.5],
]
function enforceFloors(out: Design, base: Design, at: string, problems: DesignProblem[]): void {
for (const mode of ['light', 'dark'] as const) {
const pal = out[mode]
const was = { ...pal }
const failing = (): Array<readonly [PaletteKey, PaletteKey, number]> =>
CONTRAST_FLOORS.filter(([fg, bg, min]) => contrast(pal[fg], pal[bg]) < min)
// Fall back the CUSTOM member of a failing pair — foreground first, then
// its ground — and re-check everything, because restoring a ground can
// break a pair that was passing against the custom one.
for (let pass = 0; pass < 4 && failing().length; pass++) {
for (const [fg, bg, min] of failing()) {
if (contrast(pal[fg], pal[bg]) >= min) continue
if (pal[fg] !== base[mode][fg]) pal[fg] = base[mode][fg]
if (contrast(pal[fg], pal[bg]) < min && pal[bg] !== base[mode][bg]) pal[bg] = base[mode][bg]
}
}
// the base passes every floor (the model rig asserts it), so this is the
// end of the line: a palette that still fails is the base's, whole
if (failing().length) Object.assign(pal, base[mode])
for (const c of ['cell1', 'cell2', 'cell3'] as const) {
if (contrast(pal[c], cellInk(pal[c], out)) < 4.5) pal[c] = base[mode][c]
}
// A FILLED callout puts the design's ink on a mix of the tone and the
// paper (designs.css, FILL_MIX). A custom accent can make that mix too
// dark for the ink — measured: 4.27:1 on a teal fork in dark — so the
// mix is checked here, where the numbers are, and the accent falls back.
if (out.props.callout === 'fill' && !fillReadable(pal)) for (const k of TONE_KEYS) pal[k] = base[mode][k]
// TONE IS MEANING: five tones a reader cannot tell apart are one tone
if (!tonesDistinct(pal, out.props.callout)) for (const k of TONE_KEYS) pal[k] = base[mode][k]
for (const k of PALETTE_KEYS) {
if (pal[k] === was[k]) continue
problems.push({ code: 'design-contrast', path: `${at}.${mode}.${k}`,
message: `${at}.${mode}.${k} = ${was[k]} would leave text under its contrast floor (${CONTRAST_FLOORS.filter(([f, b]) => f === k || b === k).map(([f, b, m]) => `${f} on ${b} ${m}:1`).join(', ') || 'callout fill or tile cell 4.5:1, or five tones a reader must tell apart'}); the base design's ${pal[k]} is used.` })
}
}
// …and if the base's own colours cannot carry a fill either, the SWITCH
// falls back instead: a design never gets to put text on a ground it fails.
if (out.props.callout === 'fill' && !(fillReadable(out.light) && fillReadable(out.dark))) {
const to = base.props.callout === 'fill' ? 'tint' : base.props.callout
problems.push({ code: 'design-contrast', path: `${at}.props.callout`,
message: `${at}.props.callout = "fill" puts text under 4.5:1 with these colours; "${to}" is used.` })
out.props.callout = to
}
}
/** How much of the tone a FILLED callout's ground is. designs.css says the same number. */
export const FILL_MIX = 0.4
/**
* The app's five callout tone hues (styles.css --tone-*, identical in both
* themes). Restated because a fill's legibility is decided HERE; the model rig
* asserts the two lists agree.
*/
export const TONE_HUES = ['#7d9cbd', '#4f9e79', '#8a72cc', '#d9a326', '#cd6a63'] as const
/** color-mix(in srgb, a p, b) — the same arithmetic the browser does. */
export function mixHex(a: string, b: string, p: number): string {
const [x, y] = [channels(a), channels(b)]
return '#' + x.map((c, i) => Math.round((c * p + y[i] * (1 - p)) * 255).toString(16).padStart(2, '0')).join('')
}
function fillReadable(pal: Palette): boolean {
return TONE_KEYS.every((k) => contrast(pal.ink, mixHex(pal[k], pal.paper, FILL_MIX)) >= 4.5)
}
/**
* What tells one tone from another ON THE PAGE, per callout style: a filled
* box is told by its fill; every other style draws the tone's own hue as a
* rule, a start bar or a shadow, and colours its label from it.
*/
export function toneSignature(pal: Palette, callout: Props['callout']): string[] {
return TONE_KEYS.map((k) => (callout === 'fill' ? mixHex(pal[k], pal.paper, FILL_MIX) : pal[k]))
}
/** Smallest sRGB distance (0–441) two tones' signatures may sit apart. */
export const TONE_MIN_DISTANCE = 24
export function rgbDistance(a: string, b: string): number {
const [x, y] = [channels(a), channels(b)]
return Math.hypot(...x.map((c, i) => (c - y[i]) * 255))
}
export function tonesDistinct(pal: Palette, callout: Props['callout']): boolean {
const s = toneSignature(pal, callout)
for (let i = 0; i < s.length; i++) for (let j = i + 1; j < s.length; j++) if (rgbDistance(s[i], s[j]) < TONE_MIN_DISTANCE) return false
return true
}
export interface Resolved {
/** the name as the document says it */
name: string
design: Design
/** carried by this document rather than built in */
custom: boolean
}
/**
* The design this document asks for, or null for the default look.
*
* NULL covers three cases and all three render the untouched stylesheet: no
* `design` key, a design name this build does not know (a newer built-in, or a
* typo — the key round-trips and validate() names it), and a non-string.
*
* A doc-local design SHADOWS NOTHING: a `doc.designs.ledger` is ignored because
* `ledger` means the built-in in every file, and validate() says so.
*
* `name` may be passed to resolve something other than `doc.design` — the
* picker's hover preview, and (later) a per-page `design`, which is why this
* takes a name rather than reading a fixed field.
*/
export function resolveDesign(doc: SpacesDoc, name: unknown = (doc as { design?: unknown }).design): Resolved | null {
if (typeof name !== 'string' || !name) return null
if (isBuiltIn(name)) return { name, design: BUILT_INS[name], custom: false }
if (!DESIGN_NAME.test(name)) return null
const local = localDesigns(doc)
if (!Object.hasOwn(local, name)) return null
return { name, design: resolveData(doc, name, local[name]), custom: true }
}
// ---- per page ----------------------------------------------------------------
//
// A PAGE MAY NAME ITS OWN DESIGN (DECISIONS 2026-09-26, per-page addendum).
// `page.design` is the same kind of value as `doc.design` — a built-in name or
// a key of `doc.designs` — and it is ADDITIVE: absent means inherit, and an
// older build that has never heard of it renders the space's design and
// round-trips the key untouched.
//
// PRECEDENCE, nearest first: the page's own key, then the nearest ancestor
// that has one, then `doc.design`, then today's look. THE NEAREST KEY DECIDES,
// even when it names nothing this build knows: an unknown name renders the
// default look (exactly as an unknown `doc.design` does) rather than silently
// falling through to a design further up, which would make a typo look like a
// deliberate choice of the parent's.
/**
* A look at a design that is not written down: the picker's hover, and the
* customise panel's unsaved draft. NEVER document data.
*
* `page` + `name` tries a name at one page (null = the key removed, i.e.
* inherit); `name` alone tries it at the space. `draft` stands in for a
* doc-local design wherever that name resolves.
*/
export interface DesignPreview {
page?: string
name?: string | null
draft?: Resolved
}
/** Where a page's design comes from, before it is resolved. */
export interface DesignSource {
/** the raw value that decides (undefined = nobody set one) */
name: unknown
from: 'page' | 'ancestor' | 'space' | 'none'
/** the page whose key decided, for 'page' and 'ancestor' */
pageId?: string
}
type PageRec = { id: string; parent?: unknown; design?: unknown }
/**
* Where `pageId`'s design comes from. `skipSelf` answers "what would this page
* inherit" — the picker's "Same as parent" row.
*
* Cycle-guarded, and a parent that does not resolve ends the walk at the
* space, the same way the tree shows such a page at the root.
*/
export function designSource(doc: SpacesDoc, pageId: string | null | undefined, opts: { skipSelf?: boolean; preview?: DesignPreview } = {}): DesignSource {
const pv = opts.preview
const pages = (doc.pages ?? []) as PageRec[]
const byId = new Map(pages.map((p) => [p.id, p]))
const seen = new Set<string>()
let p = pageId ? byId.get(pageId) : undefined
let first = true
while (p && !seen.has(p.id)) {
seen.add(p.id)
if (!(first && opts.skipSelf)) {
const v = pv && pv.page === p.id && pv.name !== undefined ? (pv.name ?? undefined) : p.design
if (v !== undefined) return { name: v, from: first ? 'page' : 'ancestor', pageId: p.id }
}
first = false
p = typeof p.parent === 'string' ? byId.get(p.parent) : undefined
}
const d = pv && pv.page === undefined && pv.name !== undefined ? (pv.name ?? undefined) : (doc as { design?: unknown }).design
return d !== undefined ? { name: d, from: 'space' } : { name: undefined, from: 'none' }
}
/**
* The design a page renders in, or null for the default look.
*
* THIS IS THE ONE PLACE A PAGE'S LOOK IS DECIDED. The editor's surface, the
* page root renderPage builds, print and the static preview all ask it, so
* none of them can disagree about which design a page wears.
*/
export function resolvePageDesign(doc: SpacesDoc, pageId: string | null | undefined, preview?: DesignPreview, skipSelf = false): Resolved | null {
const src = designSource(doc, pageId, { skipSelf, preview })
// null, never undefined: resolveDesign's default parameter reads doc.design
const r = resolveDesign(doc, src.name === undefined ? null : src.name)
if (r && preview?.draft && preview.draft.name === r.name) return preview.draft
return r
}
/**
* Set or clear ONE PAGE's design. Returning to inherit DELETES the key, so a
* page that tried a design and went back is byte-identical to one that never
* did — the same rule `setDesign` keeps for the space.
*/
export function setPageDesign(page: { design?: unknown }, name: string | null): void {
if (name) page.design = name
else delete page.design
}
/** Every design name the space or any page names explicitly. */
export function namedDesigns(doc: SpacesDoc): string[] {
const out = new Set<string>()
const d = (doc as { design?: unknown }).design
if (typeof d === 'string' && d) out.add(d)
for (const p of (doc.pages ?? []) as PageRec[]) if (typeof p.design === 'string' && p.design) out.add(p.design)
return [...out]
}
/** Everything validate() should say about `design` and `designs`. */
export function designProblems(doc: SpacesDoc): DesignProblem[] {
const out: DesignProblem[] = []
// A PAGE's design is named the same way the space's is, on that page
for (const p of (doc.pages ?? []) as PageRec[]) {
if (p.design === undefined) continue
if (typeof p.design !== 'string' || !p.design) {
out.push({ code: 'bad-design', path: 'design', page: p.id,
message: `design = ${JSON.stringify(p.design)} is not a design name, so this page shows the default look. The value is kept.` })
} else if (!resolveDesign(doc, p.design)) {
out.push({ code: 'unknown-design', path: 'design', page: p.id,
message: `design "${p.design}" is neither a built-in (${BUILT_IN_NAMES.join(', ')}) nor defined in designs, so this page shows the default look (it does not fall through to its parent's). The value is kept.` })
}
}
const raw = doc as { design?: unknown; designs?: unknown }
if (raw.designs !== undefined && !isObj(raw.designs)) {
out.push({ code: 'bad-design', path: 'designs', message: 'designs is not an object of named designs; it is kept in the file and ignored.' })
}
const local = localDesigns(doc)
for (const [name, data] of Object.entries(local)) {
if (isBuiltIn(name)) {
out.push({ code: 'design-shadows-builtin', path: `designs.${name}`,
message: `designs.${name} has a built-in design's name, so it is never used — "${name}" always means the built-in.` })
continue
}
if (!DESIGN_NAME.test(name)) {
out.push({ code: 'bad-design-name', path: `designs.${name}`,
message: `"${name}" is not a usable design name (lowercase letters, digits and hyphens, up to 32), so it can never be selected.` })
continue
}
if (isObj(data) && data.label !== undefined && (typeof data.label !== 'string' || !data.label.trim() || data.label.length > 60)) {
out.push({ code: 'bad-design-value', path: `designs.${name}.label`, message: `designs.${name}.label must be a short string; the name is shown instead.` })
}
resolveData(doc, name, data, out)
}
if (raw.design !== undefined) {
if (typeof raw.design !== 'string' || !raw.design) {
out.push({ code: 'bad-design', path: 'design', message: `design = ${JSON.stringify(raw.design)} is not a design name, so the default look is shown.` })
} else if (!resolveDesign(doc)) {
out.push({ code: 'unknown-design', path: 'design',
message: `design "${raw.design}" is neither a built-in (${BUILT_IN_NAMES.join(', ')}) nor defined in designs, so the default look is shown. The value is kept.` })
}
}
return out
}
/** Asset keys the designs reference, so an embedded face never reads as an orphan. */
export function designAssetKeys(doc: SpacesDoc): string[] {
const keys: string[] = []
for (const data of Object.values(localDesigns(doc))) {
if (!isObj(data) || !isObj(data.fonts)) continue
for (const v of Object.values(data.fonts)) if (typeof v === 'string' && ASSET_FONT.test(v)) keys.push(v.slice(6))
}
return keys
}
/** What the picker calls a doc-local design. */
export function localLabel(doc: SpacesDoc, name: string): string {
const data = localDesigns(doc)[name]
const l = isObj(data) && typeof data.label === 'string' ? data.label.trim() : ''
return l && l.length <= 60 ? l : name
}
/** A fresh doc-local name that collides with nothing. */
export function freshDesignName(doc: SpacesDoc): string {
const local = localDesigns(doc)
for (let n = 1; ; n++) {
const name = n === 1 ? 'custom' : `custom-${n}`
if (!Object.hasOwn(local, name) && !isBuiltIn(name)) return name
}
}
// ---- writing it down ---------------------------------------------------------
/**
* Set or clear the document's design.
*
* RETURNING TO THE DEFAULT DELETES THE KEY — never `design: ''` or `null` —
* so a document that tried a design and went back is byte-identical to one
* that never did, and an older build sees nothing it has to preserve.
*/
export function setDesign(doc: SpacesDoc, name: string | null): void {
const d = doc as { design?: unknown }
if (name) d.design = name
else delete d.design
}
// ---- Markdown front matter -----------------------------------------------------
/**
* The front matter an export opens with, or [] when there is nothing to say.
*
* THE SMALLEST CORRECT FRONT MATTER: `design:` names it, and when a design is
* one this document carries, `designs:` holds its entry as a single line of
* JSON — which is YAML flow syntax, so any YAML reader accepts it and no YAML
* parser is needed to read it back. A space with no design exports with no
* front matter at all, exactly as before.
*
* TWO SCOPES. With no `pageId` this is the WHOLE-SPACE export's header:
* `design:` is the space's, and `designs:` carries every doc-local design the
* space or any page names, so the registry travels whole. With a `pageId` it
* is ONE PAGE's note: `design:` only when that page sets one EXPLICITLY — an
* inherited design is not written, because the note would then pin a look the
* page never chose — and `designs:` only the entry that page names.
*/
export function designFrontMatter(doc: SpacesDoc, pageId?: string): string[] {
const local = localDesigns(doc)
let name: unknown
let carried: string[]
if (pageId === undefined) {
name = (doc as { design?: unknown }).design
carried = namedDesigns(doc)
} else {
name = ((doc.pages ?? []) as PageRec[]).find((p) => p.id === pageId)?.design
carried = typeof name === 'string' && name ? [name] : []
}
carried = carried.filter((n) => !isBuiltIn(n) && Object.hasOwn(local, n))
const named = typeof name === 'string' && name ? name : ''
if (!named && !carried.length) return []
const lines = ['---']
if (named) lines.push(`design: ${/^[A-Za-z0-9_-]+$/.test(named) ? named : JSON.stringify(named)}`)
if (carried.length) lines.push(`designs: ${JSON.stringify(Object.fromEntries(carried.map((n) => [n, local[n]])))}`)
lines.push('---', '')
return lines
}
export interface FrontMatterDesign {
design?: string
designs?: Record<string, unknown>
/** every line was ours, so the front matter is consumed rather than kept */
onlyOurs: boolean
}
/** Read `design:` and `designs:` out of front matter text (the lines between the fences). */
export function readDesignFrontMatter(yaml: string): FrontMatterDesign {
const out: FrontMatterDesign = { onlyOurs: true }
for (const line of yaml.split('\n')) {
if (!line.trim()) continue
const d = /^design:\s*(.*?)\s*$/.exec(line)
if (d) {
let v = d[1]
if (v.startsWith('"')) { try { v = String(JSON.parse(v)) } catch { v = '' } }
else if (v.startsWith("'") && v.endsWith("'") && v.length > 1) v = v.slice(1, -1)
if (v) out.design = v
continue
}
const ds = /^designs:\s*(\{.*\})\s*$/.exec(line)
if (ds) {
try {
const parsed: unknown = JSON.parse(ds[1])
if (isObj(parsed)) out.designs = parsed
} catch { out.onlyOurs = false }
continue
}
out.onlyOurs = false
}
return out
}
/**
* Adopt what arrived with imported notes. Mutates `doc`; call it inside the
* import's one commit.
*
* CONSERVATIVE BY DESIGN: a doc-local entry is added only under a name this
* space does not already use, and `design` is set only when the space has
* none and the name resolves.
*
* PER PAGE NOW (2026-09-26 addendum): planImport sets a note's `design:` on
* THAT note's page, so the editor passes no `design` here and an import never
* restyles the rest of the space — it only brings the REGISTRY entries the
* notes carried. Returns the space-level name adopted, if any.
*/
export function adoptDesign(doc: SpacesDoc, design: string | undefined, designs: Record<string, unknown> | undefined): string | null {
const d = doc as { design?: unknown; designs?: Record<string, unknown> }
for (const [name, data] of Object.entries(designs ?? {})) {
if (isBuiltIn(name) || !DESIGN_NAME.test(name) || !isObj(data)) continue
if (Object.hasOwn(localDesigns(doc), name)) continue
d.designs = { ...localDesigns(doc), [name]: data }
}
if (!design || d.design !== undefined) return null
if (!resolveDesign(doc, design)) return null
d.design = design
return design
}
// ---- colour arithmetic (for readable ink on tile cells) -----------------------
function channels(hex: string): [number, number, number] {
const h = (parseColour(hex) ?? '#000000').slice(1)
return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255) as [number, number, number]
}
export function luminance(hex: string): number {
const [r, g, b] = channels(hex).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
return 0.2126 * r + 0.7152 * g + 0.0722 * b
}
export function contrast(a: string, b: string): number {
const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p)
return (x + 0.05) / (y + 0.05)
}
/**
* The ink for a tile cell: whichever of the design's own dark inks, or white,
* reads best on it. Chosen, not stored, so a custom palette that darkens a
* cell does not need a second edit — and the cells are brand colours that do
* not flip with the reader's theme, so the LIGHT inks are the candidates in
* both palettes.
*/
export function cellInk(bg: string, d: Pick<Design, 'light'>): string {
let best = '#ffffff'
for (const c of [d.light.ink, d.light.onAccent]) if (contrast(bg, c) > contrast(bg, best)) best = c
return best
}
// ---- to CSS values -------------------------------------------------------------
const kebab = (k: string): string => k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
/** A family name for an embedded face: derived from its key, never from author text. */
export function assetFamily(ref: string): string {
let h = 0x811c9dc5
for (let i = 0; i < ref.length; i++) { h ^= ref.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0 }
return `bento-face-${h.toString(36)}`
}
/** The fallback stack a role falls to when its embedded face is missing. */
const ROLE_FALLBACK: Record<FontRole, string> = { display: 'system', body: 'system', label: 'system', mono: 'mono' }
export function fontStack(value: string, role: FontRole): string {
if (Object.hasOwn(FONT_STACKS, value)) return FONT_STACKS[value]
return `'${assetFamily(value)}', ${FONT_STACKS[ROLE_FALLBACK[role]]}`
}
/**
* The attributes and custom properties that put a design on a surface.
*
* EVERY VALUE HERE IS ONE THIS MODULE CHOSE OR CHECKED: palette values passed
* parseColour, numbers passed their range, words are PROPS entries, stacks are
* FONT_STACKS strings or a family name derived from an asset key. That is the
* whole of the injection argument, and the model rig asserts each part.
*/
export function designStyle(r: Resolved): { attrs: Record<string, string>; vars: Record<string, string> } {
const d = r.design
const attrs: Record<string, string> = { 'data-sp-design': r.name }
const vars: Record<string, string> = {}
for (const [mode, pre] of [['light', '--dl-'], ['dark', '--dd-']] as const) {
const pal = d[mode]
for (const k of PALETTE_KEYS) vars[`${pre}${kebab(k)}`] = pal[k]
// tile cells get their own ink, chosen for contrast rather than stored:
// a custom palette that makes a cell dark should not need a second edit
for (const c of ['cell1', 'cell2', 'cell3'] as const) vars[`${pre}${c}-ink`] = cellInk(pal[c], d)
// THE MARK: the accent wherever a mark carries meaning (a done box, a
// drop cap, a bar), unless the accent is too pale to be read as one on
// this paper — then its ink twin. Studio's coral is 2.0:1 on white: fine
// as a fill under navy text, not fine as the only sign a task is done.
vars[`${pre}mark`] = contrast(pal.accent, pal.paper) >= 3 ? pal.accent : pal.accentInk
}
for (const role of FONT_ROLES) vars[`--d-${role}`] = fontStack(d.fonts[role], role)
for (const k of PROP_KEYS) {
const rule: NumRule | EnumRule = PROPS[k]
const v = d.props[k]
if (rule.kind === 'num') vars[`--d-${kebab(k)}`] = `${v}${rule.unit}`
else attrs[`data-sd-${k.toLowerCase()}`] = String(v)
}
return { attrs, vars }
}
/** Every attribute a design can put on a surface, so clearing one is complete. */
const ALL_ATTRS = ['data-sp-design', ...PROP_KEYS.filter((k) => PROPS[k].kind === 'enum').map((k) => `data-sd-${k.toLowerCase()}`)]
// ---- the DOM side -----------------------------------------------------------
/** Faces already handed to document.fonts, by family. */
const registered = new Set<string>()
/**
* Load a design's embedded faces through the FontFace API.
*
* NO STYLESHEET TEXT: the bytes go to `new FontFace(family, buffer)`, so an
* embedded face never produces an @font-face rule that author data could
* shape, and nothing is fetched — the bytes are already in the file.
*/
function loadFaces(doc: SpacesDoc, d: Design): void {
const fonts = (globalThis as { document?: Document }).document?.fonts
if (!fonts || typeof FontFace === 'undefined') return
for (const role of FONT_ROLES) {
const ref = d.fonts[role]
if (Object.hasOwn(FONT_STACKS, ref)) continue
const family = assetFamily(ref)
if (registered.has(family)) continue
const uri = fontAssetUri(doc, ref)
if (!uri) continue
registered.add(family)
try {
const b64 = uri.slice(uri.indexOf(',') + 1)
const bin = atob(b64)
const bytes = new Uint8Array(bin.length)
for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
const face = new FontFace(family, bytes)
fonts.add(face)
void face.load().catch(() => { /* a broken file falls back to the stack */ })
} catch { /* not base64 — the stack's fallback is what shows */ }
}
}
/**
* Put the document's design on a surface — or take every trace of one off.
*
* With no design the surface carries NO attribute and NO custom property,
* which is what makes "no design" the untouched stylesheet byte for byte:
* every rule in designs.css is keyed under `[data-sp-design]`.
*/
export function applyDesign(el: HTMLElement, doc: SpacesDoc, override?: Resolved | null): void {
const r = override === undefined ? resolveDesign(doc) : override
for (const a of ALL_ATTRS) el.removeAttribute(a)
for (const p of Array.from(el.style)) if (p.startsWith('--dl-') || p.startsWith('--dd-') || p.startsWith('--d-')) el.style.removeProperty(p)
if (!r) return
const { attrs, vars } = designStyle(r)
for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v)
for (const [k, v] of Object.entries(vars)) el.style.setProperty(k, v)
loadFaces(doc, r.design)
}
// ---- the still preview ---------------------------------------------------------
/** One preview rule: elements under the preview box, and the declarations for them. */
export type PreviewRule = [selector: string, decls: Record<string, string>]
/**
* The design, for preview.ts, in its LIGHT palette — as INLINE STYLES, never
* as a <style> element.
*
* The preview is written into every saved shell, and a design's values in a
* <style> block there would be author data inside raw text that the HTML
* parser ends at the first `</style>`. Validation already makes that string
* impossible (a hex colour, a number, a word from PROPS, a stack from
* FONT_STACKS) — and this does not lean on it: preview.ts writes each
* declaration through `style.setProperty`, so the CSSOM parses the value,
* drops anything that is not one value of that property, and the serializer
* escapes what is left as an attribute. Two independent guards.
*
* Light, because a thumbnail has no reader to ask and is the document's face.
* No custom properties or color-mix(): QuickLook's conservative WebKit is who
* reads this. Embedded faces are not drawn (their bytes would blow the
* preview's budget); the role's fallback stack stands in.
*/
export function previewRules(r: Resolved): PreviewRule[] {
const d = r.design
const p = d.light
const P = d.props
const f = (role: FontRole) => fontStack(d.fonts[role], role)
const label: Record<string, string> = P.label === 'caps' ? { 'text-transform': 'uppercase', 'letter-spacing': '.08em' }
: P.label === 'smallcaps' ? { 'font-variant-caps': 'all-small-caps', 'letter-spacing': '.05em' }
: P.label === 'italic' ? { 'font-style': 'italic' } : {}
const rules: PreviewRule[] = [
['', { background: p.paper, color: p.ink, 'font-family': f('body') }],
['.bp-col', { 'font-size': `${16 * P.size}px`, 'line-height': String(P.leading) }],
['h1, h2, h3', { 'font-family': f('display'), 'font-weight': String(P.headWeight),
...(P.headStyle === 'italic' ? { 'font-style': 'italic' } : {}),
...(P.headCase === 'upper' ? { 'text-transform': 'uppercase' } : {}) }],
['h1.sp-title', { 'font-size': `${((33 * P.titleSize) / 2.06).toFixed(1)}px`, 'font-weight': String(P.titleWeight),
'letter-spacing': `${P.titleTracking}em`, 'line-height': String(P.titleLeading), 'font-style': 'normal' }],
['h3, th', { 'font-family': f('label'), color: P.labelInk === 'accent' ? p.accentInk : p.ink, ...label }],
['pre, code', { 'font-family': f('mono') }],
['blockquote', { 'border-inline-start-color': p.accent, color: p.ink }],
['aside', { background: p.soft, 'border-color': p.rule, 'border-inline-start-color': p.accent, 'border-radius': `${P.radius}px` }],
['pre', { background: p.soft, 'border-radius': `${P.radius}px` }],
['hr', { 'border-top': `${P.rule}px solid ${P.divider === 'rule' ? p.rule : p.ink}` }],
['th', { background: p.soft }],
['th, td', { 'border-color': p.rule }],
['a', { 'border-bottom-color': p.accent }],
['li.sp-done, figcaption, .sp-media-badge', { color: p.muted }],
]
if (P.h2 === 'above' || P.h2 === 'double') {
rules.push(['h2', { 'border-top': `${P.h2 === 'double' ? `${P.rule * 3 + 1}px double` : `${P.rule}px solid`} ${p.ink}`, 'padding-top': '8px' }])
} else if (P.h2 === 'under') {
rules.push(['h2', { 'text-decoration': 'underline' }])
}
if (P.callout === 'outline') rules.push(['aside', { background: 'none', border: `${Math.max(1, P.rule)}px solid ${p.ink}` }])
else if (P.callout === 'rules') rules.push(['aside', { background: 'none', border: '0', 'border-top': `1px solid ${p.accent}`, 'border-bottom': `1px solid ${p.accent}`, 'border-radius': '0', 'padding-left': '0', 'padding-right': '0' }])
else if (P.callout === 'fill') rules.push(['aside', { background: p.accent, color: p.onAccent, border: '0' }])
else if (P.callout === 'shadow') rules.push(['aside', { background: p.paper, border: `2px solid ${p.ink}`, 'box-shadow': `5px 5px 0 ${p.accent}` }])
if (P.quote === 'tile') rules.push(['blockquote', { background: p.tile, color: p.tileInk, border: '0', padding: '16px 20px', 'border-radius': `${P.radius + 6}px` }])
else if (P.quote === 'display' || P.quote === 'pull') rules.push(['blockquote', { border: '0', padding: '0', 'font-family': f('display'), 'font-style': 'italic', 'font-size': '1.3em' }])
if (P.justify === 'on') rules.push(['p', { 'text-align': 'justify' }])
return rules
}
/** Apply previewRules under `box` (a selector of '' means the box itself). */
export function applyPreviewRules(box: HTMLElement, rules: PreviewRule[]): void {
for (const [sel, decls] of rules) {
const els = sel ? Array.from(box.querySelectorAll<HTMLElement>(sel)) : [box]
for (const el of els) for (const [k, v] of Object.entries(decls)) el.style.setProperty(k, v)
}
}