mdeck 2.3.0

package/src/editor/useDeckDocument.js

@@ -0,0 +1,67 @@
+// The deck file as both editor pages see it: loaded once, edited through
+// `edit`, saved in the background, and kept in step with changes on disk,
+// including those the other page makes.
+import { useEffect, useMemo, useReducer, useRef, useState } from 'preact/hooks'
+import { reduce, initialState } from './state.js'
+import { loadDeck, saveSource, onServerEvent } from './api.js'
+import { createSaveQueue } from './saveQueue.js'
+
+export function useDeckDocument() {
+  const [state, dispatch] = useReducer(reduce, initialState)
+  const stateRef = useRef(state)
+  stateRef.current = state
+  const [loadError, setLoadError] = useState(null)
+  const [previewKey, setPreviewKey] = useState(0)
+
+  const queue = useMemo(() => createSaveQueue({
+    save: saveSource,
+    onSaving: () => dispatch({ type: 'saving' }),
+    onSaved: info => dispatch({ type: 'saved', ...info }),
+    onConflict: error => dispatch({ type: 'conflict', source: error.source, hash: error.hash }),
+    onError: error => dispatch({ type: 'saveError', message: error.message }),
+  }), [])
+
+  const load = async () => {
+    try {
+      const payload = await loadDeck()
+      dispatch({ type: 'load', ...payload })
+      queue.setBase(payload.hash)
+      setLoadError(null)
+    } catch (error) { setLoadError(error.message) }
+  }
+
+  useEffect(() => {
+    load()
+    const offChanged = onServerEvent('mdeck:deck-changed', async ({ hash }) => {
+      if (hash === stateRef.current.hash || hash === queue.base()) return
+      try {
+        const payload = await loadDeck()
+        if (stateRef.current.status === 'saved') queue.setBase(payload.hash)
+        dispatch({ type: 'externalChange', source: payload.source, hash: payload.hash })
+      } catch {}
+    })
+    // Extension files changed on disk (by an editor page or another program):
+    // refresh the registry and reload the preview frame, never the page.
+    const offExtensions = onServerEvent('mdeck:extensions-changed', async () => {
+      try { const payload = await loadDeck(); dispatch({ type: 'setRegistry', registry: payload.registry }) } catch {}
+      setPreviewKey(key => key + 1)
+    })
+    const flush = () => { if (queue.pending()) queue.flush() }
+    const hidden = () => { if (document.visibilityState === 'hidden') flush() }
+    window.addEventListener('beforeunload', flush)
+    document.addEventListener('visibilitychange', hidden)
+    return () => { offChanged(); offExtensions(); window.removeEventListener('beforeunload', flush); document.removeEventListener('visibilitychange', hidden) }
+  }, [])
+
+  useEffect(() => { if (state.loaded && state.status === 'unsaved') queue.push(state.source) }, [state.source, state.status, state.loaded])
+
+  const edit = (apply, options = {}) => dispatch({ type: 'edit', apply, ...options })
+  const resolve = choice => {
+    const conflict = stateRef.current.conflict
+    dispatch({ type: 'resolveConflict', choice })
+    if (choice === 'overwrite') queue.overwrite(conflict.hash)
+    else queue.reload(conflict.hash)
+  }
+  const reloadPreview = () => setPreviewKey(key => key + 1)
+  return { state, stateRef, dispatch, edit, resolve, loadError, previewKey, reloadPreview }
+}

package/src/extensions/appearance.js

@@ -0,0 +1,79 @@
+// Pure appearance resolution shared by the runtime and tests.
+//
+// Colours come from exactly one place, the palette: the deck's `palette`, or
+// the theme's default. A palette has a light and a dark variant; the deck's
+// `appearance` (else the theme's) picks the one for the slides, and the other
+// one is available to inverted slides as --inverse-bg, --inverse-ink, …
+// Theme tokens (type, spacing, fonts) and theme parameters come on top.
+import { tokensToCss, COLOR_ROLES, APPEARANCES, palettesFor } from './tokens.js'
+
+// Code highlighting and logos on dark slides, unless the palette says otherwise.
+export const DARK_TOKENS = {
+  '--logo-filter':    'invert(1)',
+  '--token-default':  '#e2e8f0',
+  '--token-comment':  '#718096',
+  '--token-string':   '#68d391',
+  '--token-number':   '#fc8181',
+  '--token-keyword':  '#90cdf4',
+  '--token-function': '#d6bcfa',
+  '--token-operator': '#fbd38d',
+  // The drawing pen's red, blue and green, lighter for dark slides.
+  '--pen-red':        '#fb7185',
+  '--pen-blue':       '#60a5fa',
+  '--pen-green':      '#4ade80',
+}
+
+const other = appearance => appearance === 'dark' ? 'light' : 'dark'
+
+/**
+ * Which palette and variant a deck gets: `{ palette, appearance, warnings }`.
+ * An unknown palette, or one the theme does not offer, falls back to the
+ * theme's default with a warning (mdeck check reports these as errors).
+ */
+export function resolvePalette({ theme, palettes = {}, palette: requested, appearance: requestedAppearance } = {}) {
+  const warnings = []
+  const offered = palettesFor(theme, palettes)
+  let palette = requested ? palettes[requested] : null
+  if (requested && !palette) warnings.push(`Unknown palette "${requested}". Available: ${offered.map(p => p.id).join(', ')}`)
+  else if (palette && !offered.includes(palette)) { warnings.push(`The theme "${theme.id}" does not offer the palette "${requested}". Available: ${offered.map(p => p.id).join(', ')}`); palette = null }
+  palette ??= palettes[theme.palette] ?? offered[0] ?? null
+  let appearance = requestedAppearance || theme.appearance || 'light'
+  if (!APPEARANCES.includes(appearance)) { warnings.push(`appearance must be one of: ${APPEARANCES.join(', ')}`); appearance = theme.appearance ?? 'light' }
+  return { palette, appearance, warnings }
+}
+
+/** The CSS custom properties of a palette in one appearance, with the other one as --inverse-*. */
+export function paletteTokens(palette, appearance = 'light') {
+  if (!palette) return {}
+  const main = palette[appearance], inverse = palette[other(appearance)]
+  const tokens = { ...(appearance === 'dark' ? DARK_TOKENS : {}), ...main }
+  for (const role of COLOR_ROLES) tokens[`--inverse-${role.slice(2)}`] = inverse[role]
+  return tokens
+}
+
+export function buildAppearance({ theme, palettes = {}, palette, appearance, params = {}, meta = {}, offline = false } = {}) {
+  if (!theme) throw new Error('A theme manifest is required')
+  const resolved = resolvePalette({ theme, palettes, palette, appearance })
+  const warnings = [...resolved.warnings]
+  const themeCss = tokensToCss(theme.tokens)
+  const paletteCss = tokensToCss({ 'color-scheme': resolved.appearance, ...paletteTokens(resolved.palette, resolved.appearance) })
+
+  const overrides = {}
+  for (const [name, value] of Object.entries(params ?? {})) {
+    const param = theme.params?.[name]
+    if (param) overrides[param.token] = value
+    else warnings.push(`Theme "${theme.id}" has no parameter "${name}"`)
+  }
+  for (const [key, value] of Object.entries(meta ?? {})) overrides[`--meta-${key}`] = JSON.stringify(String(value))
+  const overridesCss = tokensToCss(overrides)
+
+  // Offline-ready builds deliberately use the declared system-font fallbacks.
+  const fonts = offline ? [] : theme.fonts ?? []
+  return { themeCss, paletteCss, overridesCss, fonts, warnings, palette: resolved.palette?.id ?? null, appearance: resolved.appearance }
+}
+
+/** A colour of the palette a deck gets, for previews and swatches. */
+export function paletteColor(token, { theme, palettes = {}, palette, appearance } = {}) {
+  const resolved = resolvePalette({ theme, palettes, palette, appearance })
+  return resolved.palette?.[resolved.appearance]?.[token] ?? null
+}

package/src/extensions/contrast.js

@@ -0,0 +1,57 @@
+// Contrast between palette colours (WCAG 2 relative luminance), so a palette
+// that cannot be read is caught: in the tests for the built-in palettes, and
+// as warnings from `mdeck check` for a deck's own.
+
+function parseColor(text) {
+  const value = String(text).trim().toLowerCase()
+  let match = value.match(/^#([0-9a-f]{3,8})$/)
+  if (match) {
+    let hex = match[1]
+    if (hex.length === 3 || hex.length === 4) hex = [...hex].map(c => c + c).join('')
+    return [0, 2, 4].map(i => parseInt(hex.slice(i, i + 2), 16))
+  }
+  match = value.match(/^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/)
+  if (match) return match.slice(1, 4).map(Number)
+  return null
+}
+
+function luminance([r, g, b]) {
+  const channel = c => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4 }
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
+}
+
+/** The contrast ratio of two colours (1 to 21), or null when one is not a plain colour. */
+export function contrast(a, b) {
+  const x = parseColor(a), y = parseColor(b)
+  if (!x || !y) return null
+  const [light, dark] = [luminance(x), luminance(y)].sort((p, q) => q - p)
+  return (light + 0.05) / (dark + 0.05)
+}
+
+// What a slide needs to be read from the back of a room.
+const RULES = [
+  ['--ink', '--bg', 7, 'text'],
+  ['--ink-soft', '--bg', 4.5, 'secondary text'],
+  ['--muted', '--bg', 4.5, 'muted text'],
+  ['--accent', '--bg', 3, 'the accent'],
+  ['--accent-2', '--bg', 3, 'the second accent'],
+  ['--on-accent', '--accent', 3, 'text on the accent'],
+]
+
+/**
+ * Pairs of a palette's colours that are too close to read, as messages.
+ * A private palette (one theme's corporate colours) may use its accent as a
+ * surface only, so its accents are not checked as text.
+ */
+export function paletteProblems(palette) {
+  const problems = []
+  for (const appearance of ['light', 'dark']) {
+    const tokens = palette[appearance] ?? {}
+    for (const [fore, back, minimum, what] of RULES) {
+      if (palette.theme && (fore === '--accent' || fore === '--accent-2')) continue
+      const ratio = contrast(tokens[fore], tokens[back])
+      if (ratio != null && ratio < minimum) problems.push(`${appearance}: ${what} (${fore} on ${back}) has a contrast of ${ratio.toFixed(1)}:1; at least ${minimum}:1 is needed`)
+    }
+  }
+  return problems
+}

package/src/extensions/discover.js

@@ -0,0 +1,126 @@
+// One discovery layer for layouts, themes and palettes. The same registry
+// backs `mdeck check`, CLI listings, the dev server and builds.
+import { palettesFor } from './tokens.js'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { resolve, dirname, relative } from 'node:path'
+import { homedir } from 'node:os'
+import { MANIFEST_FILENAME, ManifestError, KINDS, parseManifestText, validateManifest } from './manifest.js'
+import { builtinExtensionsRoot } from '../paths.js'
+
+const SKIP = name => name.startsWith('.') || name === 'node_modules'
+
+// Extensions installed for one user (`mdeck themes install --global`), for
+// every deck: ~/.mdeck/extensions, or $MDECK_HOME/extensions.
+export function userExtensionsDir() {
+  return resolve(process.env.MDECK_HOME || resolve(homedir(), '.mdeck'), 'extensions')
+}
+
+// Built-in, then the user's, then the deck's own: a deck's extension replaces
+// a user one with the same id.
+export function extensionRoots(slidesPath, { builtinRoot = builtinExtensionsRoot, userRoot = userExtensionsDir() } = {}) {
+  const deckDir = dirname(resolve(slidesPath))
+  return [
+    { dir: builtinRoot, source: 'built-in' },
+    ...(userRoot ? [{ dir: userRoot, source: 'user' }] : []),
+    { dir: resolve(deckDir, 'extensions'), source: 'local' },
+  ]
+}
+
+function sortedEntries(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !SKIP(entry.name))
+    .sort((a, b) => a.name.localeCompare(b.name, 'en'))
+}
+
+// A folder holding extension.toml is an extension; any other folder is a
+// grouping folder and is searched further. Folder names must equal the id.
+function* walk(dir) {
+  for (const entry of sortedEntries(dir)) {
+    const sub = resolve(dir, entry.name)
+    const file = resolve(sub, MANIFEST_FILENAME)
+    if (existsSync(file)) yield { dir: sub, file, folderName: entry.name }
+    else yield* walk(sub)
+  }
+}
+
+function readLayout(record) {
+  const starter = record.files.starter ? readFileSync(record.files.starter, 'utf8') : `:::meta\nlayout: ${record.id}\n:::\n`
+  return { ...record, manifest: { ...record.manifest, starter } }
+}
+
+function loadManifest({ dir, file, folderName }) {
+  const raw = parseManifestText(readFileSync(file, 'utf8'), file)
+  const record = validateManifest(raw, { file, dir, folderName })
+  return record.kind === 'layout' ? readLayout(record) : record
+}
+
+export function discoverExtensions(roots) {
+  const registry = { layouts: {}, themes: {}, palettes: {}, records: [], warnings: [] }
+  const byKey = new Map()
+  const add = (record, source) => {
+    const key = `${record.kind}:${record.id}`
+    const existing = byKey.get(key)
+    const entry = { ...record, source }
+    if (existing?.source === 'user' && source === 'local') {
+      registry.warnings.push(`The ${record.kind} "${record.id}" in this deck's extensions replaces the one installed in ${dirname(existing.dir)}`)
+      registry.records.splice(registry.records.indexOf(existing), 1)
+    } else if (existing) throw new ManifestError(`Duplicate ${record.kind} "${record.id}" is also defined in ${existing.file}. Extension IDs must be unique within their kind.`, { file: record.file })
+    byKey.set(key, entry)
+    registry.records.push(entry)
+    registry[`${record.kind}s`][record.id] = entry
+  }
+  for (const root of roots) {
+    if (!existsSync(root.dir) || !statSync(root.dir).isDirectory()) continue
+    for (const found of walk(root.dir)) add(loadManifest(found), root.source)
+  }
+  checkPaletteReferences(registry)
+  return registry
+}
+
+// Themes and palettes name each other across files: a theme's default palette
+// and its list must exist and fit it, a private palette's theme must exist.
+function checkPaletteReferences(registry) {
+  for (const theme of Object.values(registry.themes)) {
+    const offered = palettesFor(theme.manifest, manifestsOf(registry, 'palette'))
+    for (const id of theme.manifest.palettes ?? []) {
+      if (!registry.palettes[id]) throw new ManifestError(`palettes names "${id}", which is not a palette. Available: ${Object.keys(registry.palettes).join(', ')}`, { file: theme.file, path: 'palettes' })
+      const owner = registry.palettes[id].manifest.theme
+      if (owner && owner !== theme.id) throw new ManifestError(`palette "${id}" belongs to the theme "${owner}"`, { file: theme.file, path: 'palettes' })
+    }
+    if (!registry.palettes[theme.manifest.palette]) throw new ManifestError(`palette "${theme.manifest.palette}" does not exist. Available: ${Object.keys(registry.palettes).join(', ')}`, { file: theme.file, path: 'palette' })
+    if (!offered.some(palette => palette.id === theme.manifest.palette)) throw new ManifestError(`palette "${theme.manifest.palette}" belongs to another theme`, { file: theme.file, path: 'palette' })
+  }
+  for (const palette of Object.values(registry.palettes)) {
+    const owner = palette.manifest.theme
+    if (owner && !registry.themes[owner]) throw new ManifestError(`theme "${owner}" does not exist, so nothing could use this palette`, { file: palette.file, path: 'theme' })
+  }
+}
+
+// The extensions that come with mdeck, alone.
+export function builtInRegistry() {
+  return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }])
+}
+
+export function loadRegistry(slidesPath, options) {
+  return discoverExtensions(extensionRoots(slidesPath, options))
+}
+
+export function manifestsOf(registry, kind) {
+  return Object.fromEntries(Object.entries(registry[`${kind}s`]).map(([id, record]) => [id, record.manifest]))
+}
+
+export function layoutManifests(slidesPath, options) {
+  return manifestsOf(loadRegistry(slidesPath, options), 'layout')
+}
+
+// Serializable listing for `mdeck list --json` and future editors.
+export function serializeRegistry(registry, { relativeTo } = {}) {
+  const out = { schema: 2, warnings: registry.warnings }
+  for (const kind of KINDS) {
+    out[`${kind}s`] = Object.values(registry[`${kind}s`]).map(record => ({
+      ...record.manifest, kind, source: record.source,
+      file: relativeTo ? relative(relativeTo, record.file) : record.file,
+    }))
+  }
+  return out
+}

package/src/extensions/manifest.js

@@ -0,0 +1,209 @@
+// The extension manifest contract: one TOML format for layouts, themes and
+// palettes. Parsing and validation happen in Node; the normalized result is
+// plain data that the runtime, CLI and documentation can all share.
+import { existsSync } from 'node:fs'
+import { resolve, relative, isAbsolute, sep } from 'node:path'
+import { parse as parseToml, TomlError } from 'smol-toml'
+import { TOKEN_NAME_RE, COLOR_ROLES, APPEARANCES } from './tokens.js'
+import { propertyErrors } from '../layouts/layoutProps.js'
+
+export const SCHEMA_VERSION = 1
+export const KINDS = ['layout', 'theme', 'palette']
+export const ID_RE = /^[a-z][a-z0-9-]*$/
+export const MANIFEST_FILENAME = 'extension.toml'
+
+const FRAMES = ['standard', 'title', 'chapter', 'none']
+const PROPERTY_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object']
+const SHARED_KEYS = ['schema', 'kind', 'id', 'title', 'description']
+const KEYS = {
+  layout: [...SHARED_KEYS, 'frame', 'files', 'regions', 'properties'],
+  theme: [...SHARED_KEYS, 'palette', 'palettes', 'appearance', 'fonts', 'files', 'tokens', 'params'],
+  palette: [...SHARED_KEYS, 'theme', 'light', 'dark'],
+}
+const SCHEMA_KEYS = ['type', 'title', 'description', 'enum', 'required', 'default', 'minimum', 'maximum', 'minItems', 'maxItems', 'items']
+const RESERVED_NAMES = ['constructor', 'prototype', '__proto__']
+
+export class ManifestError extends Error {
+  constructor(message, { file, path, line, column } = {}) {
+    const where = [file, line, line && column].filter(Boolean).join(':')
+    super(`${where ? where + ': ' : ''}${path ? path + ': ' : ''}${message}`)
+    this.name = 'ManifestError'
+    Object.assign(this, { file, path, line, column, reason: message })
+  }
+}
+
+const isPlainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+export function parseManifestText(text, file) {
+  try {
+    return parseToml(text)
+  } catch (error) {
+    if (error instanceof TomlError) throw new ManifestError(error.message.split('\n')[0].replace(/^Invalid TOML document: /, ''), { file, line: error.line, column: error.column })
+    throw error
+  }
+}
+
+// Validates a raw manifest object and returns a normalized record:
+//   { kind, id, title, description, dir, file, manifest, files }
+// `manifest` is serializable public data; `files` holds absolute paths.
+export function validateManifest(raw, { file, dir, folderName, fileExists = existsSync } = {}) {
+  const fail = (message, path) => { throw new ManifestError(message, { file, path }) }
+  if (!isPlainObject(raw)) fail('The manifest must be a table of settings')
+
+  if (raw.schema !== SCHEMA_VERSION) fail(`schema must be ${SCHEMA_VERSION}${raw.schema == null ? ' (add "schema = 1" at the top)' : ''}`, 'schema')
+  if (raw.kind === 'template') fail('kind = \"template\" is now kind = \"layout\". Run mdeck migrate to update local manifests.', 'kind')
+  if (!KINDS.includes(raw.kind)) fail(`kind must be one of: ${KINDS.join(', ')}`, 'kind')
+  const kind = raw.kind
+  if (raw.name !== undefined) fail('name is not a setting; use id for the identifier and title for the display name', 'name')
+  // Colours used to live in themes and in a palette's single [tokens] table.
+  if (kind === 'theme' && raw.dark !== undefined) fail('dark is now appearance = "dark"; the colours come from the palette', 'dark')
+  if (kind === 'theme' && (raw.accent2 !== undefined || raw.accent2Preview !== undefined)) fail('a theme no longer sets colours; the second accent comes from the palette (--accent-2)', raw.accent2 !== undefined ? 'accent2' : 'accent2Preview')
+  if (kind === 'palette' && raw.tokens !== undefined) fail('a palette has a [light] and a [dark] table of colours instead of [tokens]', 'tokens')
+  for (const key of Object.keys(raw)) {
+    if (!KEYS[kind].includes(key)) fail(`Unknown setting for a ${kind}. Allowed: ${KEYS[kind].join(', ')}`, key)
+  }
+  if (typeof raw.id !== 'string' || !ID_RE.test(raw.id)) fail('id must use lowercase letters, digits and hyphens and start with a letter', 'id')
+  if (folderName != null && raw.id !== folderName) fail(`id "${raw.id}" must match the folder name "${folderName}"`, 'id')
+  if (typeof raw.title !== 'string' || !raw.title.trim()) fail('title is required', 'title')
+  if (raw.description != null && typeof raw.description !== 'string') fail('description must be text', 'description')
+
+  const files = resolveFiles(raw.files, kind, { dir, fail, fileExists })
+  const shared = { id: raw.id, title: raw.title.trim(), description: raw.description?.trim() || '' }
+  const manifest = kind === 'layout' ? validateLayout(raw, shared, fail)
+    : kind === 'theme' ? validateTheme(raw, shared, fail)
+    : validatePalette(raw, shared, fail)
+  return { kind, id: raw.id, title: shared.title, description: shared.description, dir, file, manifest, files }
+}
+
+const FILE_KEYS = { layout: ['layout', 'styles', 'starter'], theme: ['styles'], palette: [] }
+const FILE_DEFAULTS = { layout: { layout: 'layout.jsx', styles: 'styles.css', starter: 'starter.md' }, theme: { styles: 'styles.css' } }
+
+function resolveFiles(section, kind, { dir, fail, fileExists }) {
+  if (section != null && !isPlainObject(section)) fail('files must be a table', 'files')
+  const declared = section ?? {}
+  for (const key of Object.keys(declared)) {
+    if (!FILE_KEYS[kind].includes(key)) fail(FILE_KEYS[kind].length ? `Unknown file role for a ${kind}. Allowed: ${FILE_KEYS[kind].join(', ')}` : `A ${kind} has no supporting files`, `files.${key}`)
+  }
+  const resolveOne = (value, path) => {
+    if (typeof value !== 'string' || !value.trim()) fail('must be a file path inside the extension folder', path)
+    if (isAbsolute(value)) fail('must be relative to the extension folder', path)
+    const abs = resolve(dir ?? '.', value)
+    const rel = relative(dir ?? '.', abs)
+    if (rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('..')) fail(`"${value}" leaves the extension folder`, path)
+    if (!fileExists(abs)) fail(`"${value}" does not exist in ${dir ?? 'the extension folder'}`, path)
+    return abs
+  }
+  const files = {}
+  for (const key of FILE_KEYS[kind]) {
+    const path = `files.${key}`
+    const value = declared[key]
+    if (value === undefined) {
+      const fallback = FILE_DEFAULTS[kind]?.[key]
+      const abs = fallback ? resolve(dir ?? '.', fallback) : null
+      if (abs && fileExists(abs)) files[key] = key === 'styles' ? [abs] : abs
+      else if (kind === 'layout' && key === 'layout') fail(`layout.jsx is missing; add it or point files.layout at the layout file`, path)
+      else files[key] = key === 'styles' ? [] : null
+    } else if (key === 'styles') {
+      const list = Array.isArray(value) ? value : [value]
+      if (!list.length) fail('must name at least one stylesheet or be omitted', path)
+      files[key] = list.map((item, index) => resolveOne(item, Array.isArray(value) ? `${path}[${index}]` : path))
+    } else files[key] = resolveOne(value, path)
+  }
+  return files
+}
+
+function validateLayout(raw, shared, fail) {
+  if (raw.frame != null && !FRAMES.includes(raw.frame)) fail(`frame must be one of: ${FRAMES.join(', ')}`, 'frame')
+  if (!isPlainObject(raw.regions) || !Object.hasOwn(raw.regions, 'body')) fail('regions must include a [regions.body] table', 'regions')
+  const regions = {}
+  for (const [name, region] of Object.entries(raw.regions)) {
+    const path = `regions.${name}`
+    if (!ID_RE.test(name)) fail('region names use lowercase letters, digits and hyphens', path)
+    if (!isPlainObject(region)) fail('must be a table', path)
+    for (const key of Object.keys(region)) if (!['description', 'required'].includes(key)) fail('Unknown region setting. Allowed: description, required', `${path}.${key}`)
+    if (region.required != null && typeof region.required !== 'boolean') fail('must be true or false', `${path}.required`)
+    if (region.description != null && typeof region.description !== 'string') fail('must be text', `${path}.description`)
+    regions[name] = { ...(region.description ? { description: region.description } : {}), ...(region.required ? { required: true } : {}) }
+  }
+  if (raw.properties != null && !isPlainObject(raw.properties)) fail('properties must be a table', 'properties')
+  const properties = {}
+  for (const [name, schema] of Object.entries(raw.properties ?? {})) {
+    const path = `properties.${name}`
+    if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name) || RESERVED_NAMES.includes(name)) fail('property names use letters and digits and start with a letter', path)
+    properties[name] = validatePropertySchema(schema, path, fail)
+  }
+  return { ...shared, frame: raw.frame ?? 'standard', regions, properties }
+}
+
+function validatePropertySchema(schema, path, fail) {
+  if (!isPlainObject(schema)) fail('must be a table with a type', path)
+  for (const key of Object.keys(schema)) if (!SCHEMA_KEYS.includes(key)) fail(`Unknown property setting. Allowed: ${SCHEMA_KEYS.join(', ')}`, `${path}.${key}`)
+  if (!PROPERTY_TYPES.includes(schema.type)) fail(`type must be one of: ${PROPERTY_TYPES.join(', ')}`, `${path}.type`)
+  if (schema.enum != null && (!Array.isArray(schema.enum) || !schema.enum.length)) fail('must be a nonempty list', `${path}.enum`)
+  if (schema.required != null && typeof schema.required !== 'boolean') fail('must be true or false', `${path}.required`)
+  for (const key of ['title', 'description']) if (schema[key] != null && typeof schema[key] !== 'string') fail('must be text', `${path}.${key}`)
+  for (const key of ['minimum', 'maximum', 'minItems', 'maxItems']) {
+    if (schema[key] != null && (typeof schema[key] !== 'number' || !Number.isFinite(schema[key]))) fail('must be a number', `${path}.${key}`)
+  }
+  const normalized = { ...schema }
+  if (schema.items !== undefined) normalized.items = validatePropertySchema(schema.items, `${path}.items`, fail)
+  if (schema.default !== undefined) {
+    const errors = propertyErrors(schema.default, normalized, `${path}.default`)
+    if (errors.length) fail(errors.join('; ').replace(new RegExp(`${path.replace(/[.[\]]/g, '\\$&')}\\.default`, 'g'), 'default'), path)
+  }
+  return normalized
+}
+
+function validateTokens(table, path, fail, { required = false } = {}) {
+  if (!isPlainObject(table) || (required && !Object.keys(table).length)) fail(`a [${path}] table with at least one CSS custom property is required`, path)
+  const tokens = {}
+  for (const [name, value] of Object.entries(table)) {
+    if (!TOKEN_NAME_RE.test(name)) fail(`token names look like "--accent" (quote them in TOML: "--accent" = "#ff0000")`, `${path}.${name}`)
+    if (typeof value !== 'string' || !value.trim()) fail('token values are CSS text', `${path}.${name}`)
+    tokens[name] = value.trim()
+  }
+  return tokens
+}
+
+function validateTheme(raw, shared, fail) {
+  if (raw.fonts != null && (!Array.isArray(raw.fonts) || raw.fonts.some(url => typeof url !== 'string' || !url.trim()))) fail('must be a list of stylesheet URLs', 'fonts')
+  // Colours come from palettes only: a theme names its default palette, may
+  // limit which palettes fit it, and says whether it starts light or dark.
+  if (typeof raw.palette !== 'string' || !ID_RE.test(raw.palette)) fail('palette must name the palette this theme uses by default, such as palette = "lagoon"', 'palette')
+  if (raw.palettes != null && (!Array.isArray(raw.palettes) || !raw.palettes.length || raw.palettes.some(id => typeof id !== 'string' || !ID_RE.test(id)))) fail('palettes must be a nonempty list of palette ids, or be left out to offer every palette', 'palettes')
+  if (raw.palettes && !raw.palettes.includes(raw.palette)) fail(`palettes must include the default palette "${raw.palette}"`, 'palettes')
+  if (raw.appearance != null && !APPEARANCES.includes(raw.appearance)) fail(`appearance must be one of: ${APPEARANCES.join(', ')}`, 'appearance')
+  const tokens = validateTokens(raw.tokens ?? {}, 'tokens', fail)
+  for (const name of Object.keys(tokens)) if (COLOR_ROLES.includes(name)) fail(`${name} is a colour; colours come from the palette, not the theme`, `tokens.${name}`)
+  if (raw.params != null && !isPlainObject(raw.params)) fail('params must be a table', 'params')
+  const params = {}
+  for (const [name, param] of Object.entries(raw.params ?? {})) {
+    const path = `params.${name}`
+    if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name) || RESERVED_NAMES.includes(name)) fail('parameter names use letters and digits and start with a letter', path)
+    if (!isPlainObject(param)) fail('must be a table with a token', path)
+    for (const key of Object.keys(param)) if (!['token', 'title', 'description'].includes(key)) fail('Unknown parameter setting. Allowed: token, title, description', `${path}.${key}`)
+    if (typeof param.token !== 'string' || !Object.hasOwn(tokens, param.token)) fail(`token must name an entry of [tokens] (got ${JSON.stringify(param.token)})`, `${path}.token`)
+    for (const key of ['title', 'description']) if (param[key] != null && typeof param[key] !== 'string') fail('must be text', `${path}.${key}`)
+    params[name] = { token: param.token, default: tokens[param.token], ...(param.title ? { title: param.title } : {}), ...(param.description ? { description: param.description } : {}) }
+  }
+  return {
+    ...shared, palette: raw.palette, ...(raw.palettes ? { palettes: [...raw.palettes] } : {}),
+    appearance: raw.appearance ?? 'light', fonts: raw.fonts ?? [], tokens, params,
+  }
+}
+
+// A palette is a family of colours in two variants: [light] and [dark], each
+// with every colour role. Themes use one variant for the slides and the
+// other for inverted slides. `theme` makes a palette private to that theme.
+function validatePalette(raw, shared, fail) {
+  if (raw.theme != null && (typeof raw.theme !== 'string' || !ID_RE.test(raw.theme))) fail('theme must be the id of the only theme that may use this palette', 'theme')
+  const variants = {}
+  for (const appearance of APPEARANCES) {
+    if (!isPlainObject(raw[appearance])) fail(`a [${appearance}] table with the ${appearance} colours is required`, appearance)
+    const tokens = validateTokens(raw[appearance], appearance, fail, { required: true })
+    const missing = COLOR_ROLES.filter(role => !Object.hasOwn(tokens, role))
+    if (missing.length) fail(`missing colours: ${missing.join(', ')}`, appearance)
+    variants[appearance] = tokens
+  }
+  return { ...shared, ...(raw.theme ? { theme: raw.theme } : {}), light: variants.light, dark: variants.dark }
+}