mdeck 2.3.0

package/src/build/slidesPlugin.js

@@ -0,0 +1,371 @@
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { resolve, dirname, basename, sep } from 'path'
+import { parseSlides } from '../core/parseSlides.js'
+import { validateDeck, formatDiagnostics } from '../core/validateDeck.js'
+import { loadRegistry, extensionRoots, manifestsOf } from '../extensions/discover.js'
+import { resolvePalette } from '../extensions/appearance.js'
+import { embedFonts } from './fonts.js'
+import { stripNotes as stripNotesFrom } from '../core/editDeck.js'
+import { componentFolders, componentFiles } from './components.js'
+import { inkFileFor, normalizeInk, emptyInk } from '../core/ink.js'
+import { isOwnWrite } from './ownWrites.js'
+import { fileURLToPath } from 'node:url'
+import { assertDrawings } from './drawings.js'
+import { marked } from 'marked'
+
+const VIRTUAL_ID = 'virtual:slides'
+const RESOLVED_ID = '\0virtual:slides'
+
+const COMPONENTS_ID = 'virtual:deck-components'
+const RESOLVED_COMPONENTS_ID = '\0virtual:deck-components'
+const EXTENSIONS_ID = 'virtual:mdeck-extensions'
+const RESOLVED_EXTENSIONS_ID = '\0virtual:mdeck-extensions'
+const INK_ID = 'virtual:deck-ink'
+const RESOLVED_INK_ID = '\0virtual:deck-ink'
+const SVGS_ID = 'virtual:deck-svgs'
+const RESOLVED_SVGS_ID = '\0virtual:deck-svgs'
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.mp4': 'video/mp4',
+  '.m4v': 'video/x-m4v',
+  '.webm': 'video/webm',
+  '.ogv': 'video/ogg',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+}
+
+function isLocalAssetRef(ref = '') {
+  return ref
+    && !/^([a-z]+:)?\/\//i.test(ref)
+    && !ref.startsWith('data:')
+    && !ref.startsWith('#')
+}
+
+function cleanAssetRef(ref) {
+  const q = ref.indexOf('?')
+  const h = ref.indexOf('#')
+  const end = [q, h].filter(i => i !== -1).sort((a, b) => a - b)[0] ?? ref.length
+  return ref.slice(0, end)
+}
+
+// An SVG picture that uses the theme's colour variables (var(--accent) …) is
+// drawn inline by the picture layouts, so it follows the theme and palette.
+// Inside an <img> it could not see them.
+const themedSvg = file => /\.svg$/i.test(file) && existsSync(file) && /var\(--/.test(readFileSync(file, 'utf8'))
+
+export function themedSvgs(deckFile, source = readFileSync(deckFile, 'utf8')) {
+  const svgs = {}
+  for (const ref of collectLocalAssetRefs(source)) {
+    const file = resolve(dirname(deckFile), ref)
+    if (themedSvg(file)) svgs[ref] = { file, markup: readFileSync(file, 'utf8').replace(/^\s*<\?xml[^>]*>\s*/, '').replace(/<!DOCTYPE[^>]*>\s*/i, '') }
+  }
+  return svgs
+}
+
+function toDataUrl(ref, baseDir) {
+  if (!isLocalAssetRef(ref)) return null
+  const cleanRef = cleanAssetRef(ref)
+  const abs = resolve(baseDir, cleanRef)
+  if (!existsSync(abs) || themedSvg(abs)) return null
+  const ext = cleanRef.toLowerCase().slice(cleanRef.lastIndexOf('.'))
+  const mime = MIME_BY_EXT[ext]
+  if (!mime) return null
+  const b64 = readFileSync(abs).toString('base64')
+  return `data:${mime};base64,${b64}`
+}
+
+function inlineMarkdownImages(markdown, baseDir) {
+  return markdown.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (m, alt, src, title) => {
+    const dataUrl = toDataUrl(src, baseDir)
+    if (!dataUrl) return m
+    return `![${alt}](${dataUrl}${title ? ` "${title}"` : ''})`
+  })
+}
+
+function inlineHtmlImgSources(markdown, baseDir) {
+  return markdown.replace(/(<img\b[^>]*\bsrc=)(["'])([^"']+)(\2)/gi, (m, pre, quote, src, endQuote) => {
+    const dataUrl = toDataUrl(src, baseDir)
+    if (!dataUrl) return m
+    return `${pre}${quote}${dataUrl}${endQuote}`
+  })
+}
+
+function inlineHtmlMediaSources(markdown, baseDir) {
+  return markdown.replace(/(<(?:video|audio|source|videoplayer)\b[^>]*\bsrc=)(["'])([^"']+)(\2)/gi, (m, pre, quote, src, endQuote) => {
+    const dataUrl = toDataUrl(src, baseDir)
+    if (!dataUrl) return m
+    return `${pre}${quote}${dataUrl}${endQuote}`
+  })
+}
+
+function inlineYamlImageFields(markdown, baseDir) {
+  return markdown.replace(/^(\s*)(image|logo):\s*(["']?)([^"'\n]+)\3\s*$/gm, (m, indent, key, quote, value) => {
+    const dataUrl = toDataUrl(value.trim(), baseDir)
+    if (!dataUrl) return m
+    const q = quote || '"'
+    return `${indent}${key}: ${q}${dataUrl}${q}`
+  })
+}
+
+export function collectLocalAssetRefs(markdown) {
+  const refs = new Set()
+  const add = ref => {
+    const clean = cleanAssetRef(String(ref || '').trim())
+    if (isLocalAssetRef(clean)) refs.add(clean)
+  }
+
+  const deck = parseSlides(markdown)
+  add(deck.deckConfig.meta?.logo)
+  for (const slide of deck.slides) {
+    add(slide.meta.image)
+    add(slide.meta.logo)
+    add(slide.meta.props?.image)
+    const bodies = [...Object.values(slide.regions).map(r => r.content), slide.meta.notes ?? '']
+    for (const body of bodies) {
+      if (typeof body !== 'string') continue
+      marked.walkTokens(marked.lexer(body), token => {
+        if (token.type === 'image') add(token.href)
+        if (token.type === 'html') {
+          for (const match of token.text.matchAll(/<(?:img|video|audio|source|videoplayer)\b[^>]*\bsrc=(["'])([^"']+)\1/gi)) add(match[2])
+        }
+      })
+    }
+  }
+
+  return [...refs]
+}
+
+// Applies fn to the text outside fenced code blocks, so a path shown in a code
+// example stays text instead of becoming an embedded file.
+function outsideCodeFences(markdown, fn) {
+  const lines = markdown.split('\n')
+  let out = '', text = '', fence = null
+  for (const [i, line] of lines.entries()) {
+    const chunk = line + (i < lines.length - 1 ? '\n' : '')
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1]
+    if (fence) {
+      out += chunk
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length && !line.trim().slice(marker.length).trim()) fence = null
+    } else if (marker) {
+      out += fn(text) + chunk
+      text = ''
+      fence = marker
+    } else text += chunk
+  }
+  return out + fn(text)
+}
+
+export function maybeInlineAssets(markdown, abs, { inlineImages, inlineMedia }) {
+  if (!inlineImages && !inlineMedia) return markdown
+  const baseDir = dirname(abs)
+  return outsideCodeFences(markdown, text => {
+    let out = text
+    if (inlineImages) out = inlineMarkdownImages(out, baseDir)
+    if (inlineImages) out = inlineHtmlImgSources(out, baseDir)
+    if (inlineImages) out = inlineYamlImageFields(out, baseDir)
+    if (inlineMedia) out = inlineHtmlMediaSources(out, baseDir)
+    return out
+  })
+}
+
+// ─── Extension registry module ────────────────────────────────────────────
+// Layouts, themes and palettes are discovered in Node and handed to the
+// browser as one generated module. Layout code and styles are imported
+// eagerly; theme stylesheets stay lazy so only the chosen theme is loaded.
+// Layout JSX is trusted code, not sandboxed data.
+
+export function generateExtensionsModule(registry) {
+  const imports = []
+  const layouts = Object.values(registry.layouts).map((t, i) => {
+    imports.push(`import L${i} from ${JSON.stringify(t.files.layout)}`, ...t.files.styles.map(s => `import ${JSON.stringify(s)}`))
+    return `${JSON.stringify(t.id)}: { manifest: ${JSON.stringify(t.manifest)}, render: L${i} }`
+  })
+  const themes = Object.values(registry.themes).map(t => {
+    const loads = t.files.styles.map(s => `import(${JSON.stringify(s + '?inline')})`)
+    return `${JSON.stringify(t.id)}: { manifest: ${JSON.stringify(t.manifest)}, load: () => Promise.all([${loads.join(', ')}]).then(mods => mods.map(m => m.default).join('\\n')) }`
+  })
+  const palettes = Object.values(registry.palettes).map(p => `${JSON.stringify(p.id)}: { manifest: ${JSON.stringify(p.manifest)} }`)
+  return `${imports.join('\n')}\nexport const layouts = {\n${layouts.join(',\n')}\n}\nexport const themes = {\n${themes.join(',\n')}\n}\nexport const palettes = {\n${palettes.join(',\n')}\n}\n`
+}
+
+// A file for readers carries only the deck's own theme and the palette it
+// shows: the reader view offers light and dark, nothing else, and only that
+// theme's fonts travel with the file.
+export function deckLookOnly(registry, deckConfig = {}) {
+  const theme = registry.themes[deckConfig.theme ?? 'neue']
+  if (!theme) return registry
+  const palettes = Object.fromEntries(Object.entries(registry.palettes).map(([id, record]) => [id, record.manifest]))
+  const { palette } = resolvePalette({ theme: theme.manifest, palettes, palette: deckConfig.palette })
+  return { ...registry, themes: { [theme.id]: theme }, palettes: palette ? { [palette.id]: registry.palettes[palette.id] } : {} }
+}
+
+// `editor` keeps the page alive while `mdeck edit` rewrites the deck: deck
+// changes only invalidate the module, validation errors are warnings, and
+// extension changes are announced instead of forcing a reload. `source` is
+// the deck's text where there is no file (`mdeck design`, on the sample deck);
+// `slidesPath` then only says where its folder is.
+export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = false, editor = false, stripNotes = false, ink = true, embedFonts: embedThemeFonts = false, deckLook = false, source: given = null } = {}) {
+  const abs = resolve(slidesPath)
+  const readDeck = () => given ?? readFileSync(abs, 'utf-8')
+  const watchDeck = context => { if (given === null) context.addWatchFile(abs) }
+  const sourceFor = raw => stripNotes ? stripNotesFrom(raw) : raw
+  const inkPath = inkFileFor(abs)
+  const extensionDirs = extensionRoots(abs).map(root => root.dir)
+  let componentDirs = componentFolders(abs, readDeck()).map(folder => folder.dir)
+  const watchDirs = () => [...extensionDirs, ...componentDirs]
+  const isWatched = file => watchDirs().some(dir => resolve(file).startsWith(dir + sep))
+  // A changed `components:` list takes effect without restarting the server.
+  const followComponentFolders = server => {
+    const next = componentFolders(abs, readDeck()).map(folder => folder.dir)
+    if (next.join('\n') === componentDirs.join('\n')) return false
+    componentDirs = next
+    server.watcher.add(next)
+    const allow = server.config.server.fs.allow
+    for (const dir of next) if (!allow.includes(dir)) allow.push(dir)
+    return true
+  }
+  const ALL_IDS = [RESOLVED_ID, RESOLVED_COMPONENTS_ID, RESOLVED_EXTENSIONS_ID, RESOLVED_INK_ID, RESOLVED_SVGS_ID]
+  const SOURCE_IDS = [RESOLVED_ID, RESOLVED_INK_ID, RESOLVED_SVGS_ID]
+  const invalidate = (server, ids) => {
+    for (const id of ids) {
+      const mod = server.moduleGraph.getModuleById(id)
+      if (mod) server.moduleGraph.invalidateModule(mod)
+    }
+  }
+  const reload = (server, ids, file) => {
+    invalidate(server, ids)
+    if (!editor) server.ws.send({ type: 'full-reload' })
+    else if (file) server.ws.send('mdeck:extensions-changed', { file })
+  }
+
+  return {
+    name: 'vite-plugin-slides',
+    configureServer(server) {
+      server.watcher.add([abs, inkPath, ...watchDirs()])
+      const refresh = file => {
+        if (isWatched(file)) reload(server, ALL_IDS, resolve(file))
+        else if (resolve(file) === inkPath && !(() => { try { return isOwnWrite(inkPath, readFileSync(inkPath, 'utf-8')) } catch { return false } })()) reload(server, [RESOLVED_INK_ID], inkPath)
+      }
+      for (const event of ['add', 'unlink', 'addDir', 'unlinkDir']) server.watcher.on(event, refresh)
+    },
+    resolveId(id) {
+      if (id === 'mdeck/template-api') throw new Error('mdeck/template-api is now mdeck/layout. Run mdeck migrate to update local imports.')
+      if (id === 'mdeck/layout') return fileURLToPath(new URL('../layouts/layoutApi.jsx', import.meta.url))
+      if (id === 'mdeck/live') return fileURLToPath(new URL('../live/client.js', import.meta.url))
+      if (id === VIRTUAL_ID) return RESOLVED_ID
+      if (id === COMPONENTS_ID) return RESOLVED_COMPONENTS_ID
+      if (id === EXTENSIONS_ID) return RESOLVED_EXTENSIONS_ID
+      if (id === INK_ID) return RESOLVED_INK_ID
+      if (id === SVGS_ID) return RESOLVED_SVGS_ID
+    },
+    load(id) {
+      if (id === RESOLVED_ID) {
+        watchDeck(this)
+        const raw = readDeck()
+        const registry = loadRegistry(abs)
+        for (const warning of registry.warnings) this.warn(warning)
+        const diagnostics = validateDeck(parseSlides(raw), {
+          layouts: manifestsOf(registry, 'layout'), themes: manifestsOf(registry, 'theme'), palettes: manifestsOf(registry, 'palette'),
+        })
+        const errors = diagnostics.filter(d => d.severity === 'error')
+        if (errors.length && !editor) throw new Error(formatDiagnostics(errors, abs))
+        if (diagnostics.length) this.warn(formatDiagnostics(diagnostics, abs))
+        const source = maybeInlineAssets(sourceFor(raw), abs, { inlineImages, inlineMedia })
+        return `export default ${JSON.stringify(source)}`
+      }
+      // The deck's saved ink (<deck>.drawings.json), scaled to its design size.
+      // Builds bundle it, so the reader view and PDFs show it too.
+      if (id === RESOLVED_INK_ID) {
+        if (ink) assertDrawings(abs)
+        // Only an existing file: Vite treats a missing watch file as a missing
+        // import. The dev server's watcher notices the file once it appears.
+        if (existsSync(inkPath)) this.addWatchFile(inkPath)
+        let size = {}
+        try { const config = parseSlides(readDeck()).deckConfig ?? {}; size = { width: config.width ?? 1920, height: config.height ?? 1080 } } catch {}
+        let data = emptyInk(size)
+        if (ink && existsSync(inkPath)) {
+          try { data = normalizeInk(JSON.parse(readFileSync(inkPath, 'utf-8')), size) } catch (error) { this.warn(`${inkPath}: ${error.message}; showing no ink`) }
+        }
+        return `export default ${JSON.stringify(data)}\nexport const inkFileName = ${JSON.stringify(basename(inkPath))}`
+      }
+      if (id === RESOLVED_SVGS_ID) {
+        watchDeck(this)
+        const svgs = themedSvgs(abs, sourceFor(readDeck()))
+        for (const { file } of Object.values(svgs)) this.addWatchFile(file)
+        return `export default ${JSON.stringify(Object.fromEntries(Object.entries(svgs).map(([ref, { markup }]) => [ref, markup])))}`
+      }
+      if (id === RESOLVED_EXTENSIONS_ID) {
+        const registry = loadRegistry(abs)
+        for (const record of registry.records) this.addWatchFile(record.file)
+        if (!deckLook) return generateExtensionsModule(registry)
+        let config = {}
+        try { config = parseSlides(readDeck()).deckConfig ?? {} } catch {}
+        return generateExtensionsModule(deckLookOnly(registry, config))
+      }
+      if (id === RESOLVED_COMPONENTS_ID) {
+        const files = componentFiles(abs, componentFolders(abs, readDeck()))
+        const imports = files
+          .map((f, i) => `import C${i} from ${JSON.stringify(f.file)}`)
+          .join('\n')
+        const entries = files
+          .map((f, i) => `  ${JSON.stringify(f.tag)}: C${i},`)
+          .join('\n')
+        return `${imports}\nexport default {\n${entries}\n}\n`
+      }
+    },
+    // The deck page carries the deck's language before any script runs, for
+    // screen readers, hyphenation and search engines.
+    // A single-file build also carries the theme's fonts (fonts.js).
+    async transformIndexHtml(html, context) {
+      if (!/(^|[\/])index\.html$/.test(context.filename ?? context.path ?? '')) return html
+      let config = {}
+      try { config = parseSlides(readDeck()).deckConfig ?? {} } catch {}
+      const lang = config.lang
+      if (typeof lang === 'string' && /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) html = html.replace(/<html lang="[^"]*"/, `<html lang="${lang}"`)
+      if (embedThemeFonts) {
+        const theme = loadRegistry(abs).themes[config.theme ?? 'neue']?.manifest
+        const { css, warnings } = await embedFonts(theme?.fonts ?? [])
+        for (const warning of warnings) console.warn(`  ! ${warning}`)
+        if (css) html = html.replace('</head>', `<style data-mdeck-fonts>\n${css}\n</style>\n</head>`)
+      }
+      return html
+    },
+    handleHotUpdate({ file, server }) {
+      const changed = resolve(file)
+      if (isWatched(changed)) {
+        reload(server, ALL_IDS, changed)
+        return []
+      }
+      // mdeck's own writes (saved ink, a new slide id) must not reload the
+      // windows mid-talk: the pages refresh their ink on `mdeck:ink` instead.
+      const own = [inkPath, abs].includes(changed) && (() => { try { return isOwnWrite(changed, readFileSync(changed, 'utf-8')) } catch { return false } })()
+      if (own) {
+        invalidate(server, changed === abs ? SOURCE_IDS : [RESOLVED_INK_ID])
+        return []
+      }
+      if (changed === inkPath) {
+        reload(server, [RESOLVED_INK_ID], changed)
+        return []
+      }
+      if (changed === abs) {
+        if (followComponentFolders(server)) {
+          reload(server, ALL_IDS, changed)
+          return []
+        }
+        // The deck sets the ink's design size and which SVGs are inlined.
+        invalidate(server, SOURCE_IDS)
+        if (editor) return []
+        server.ws.send({ type: 'full-reload' })
+      }
+    },
+  }
+}

package/src/build/themeCheck.js

@@ -0,0 +1,151 @@
+// Themes and palettes on the sample deck (src/editor/sampleDeck.js), in a
+// real browser: the check behind `npm run test:themes` and `mdeck themes
+// build --check`, and the preview pictures of the theme repository. Each
+// look is checked light and dark on every slide, and fails when content does
+// not fit, text is cut off at the slide's edge, text is hard to read on what
+// is behind it, or the page reports an error. Needs Chrome (MDECK_CHROME).
+import { execFileSync } from 'node:child_process'
+import { cpSync, mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+import { launchChrome } from './chrome.js'
+import { frameworkRoot } from '../paths.js'
+import { sampleDeck, SAMPLE_PICTURE } from '../editor/sampleDeck.js'
+
+// Runs in the page before the deck: keeps what the page reports.
+const RECORDER = `window.__report = [];
+for (const level of ['warn', 'error']) { const original = console[level]; console[level] = (...args) => { window.__report.push(level + ': ' + args.map(String).join(' ')); original.apply(console, args) } }
+addEventListener('error', event => window.__report.push('error: ' + event.message))
+addEventListener('unhandledrejection', event => window.__report.push('error: ' + (event.reason?.message ?? event.reason)))`
+
+// Runs in the page for the slide on screen: what is cut off or hard to read.
+const MEASURE = `(() => {
+  const slide = document.querySelector('deck-stage').querySelectorAll(':scope > section')[window.__index]
+  const problems = []
+  const frame = slide.getBoundingClientRect()
+  const scale = frame.width / slide.offsetWidth
+  const body = slide.querySelector('.slide-body')
+  if (body && body.scrollHeight > body.clientHeight + 2) problems.push('the content is ' + Math.round(body.scrollHeight - body.clientHeight) + 'px taller than its place')
+  const parse = value => { const m = value.match(/rgba?\\(([^)]+)\\)/); if (!m) return null; const [r, g, b, a = 1] = m[1].split(/[ ,/]+/).filter(Boolean).map(Number); return { r, g, b, a } }
+  const lum = ({ r, g, b }) => { const c = v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }; return 0.2126 * c(r) + 0.7152 * c(g) + 0.0722 * c(b) }
+  const ratio = (x, y) => { const [a, b] = [lum(x), lum(y)].sort((p, q) => q - p); return (a + 0.05) / (b + 0.05) }
+  // The colour behind an element, when it is a plain colour; null behind a
+  // picture or a gradient, where it cannot be told.
+  // The slide's own ::before and ::after fields (duet's chapter colour field),
+  // as rectangles in slide coordinates.
+  const fields = ['::before', '::after'].map(pseudo => getComputedStyle(slide, pseudo)).filter(drawn => drawn.content !== 'none' && drawn.position === 'absolute'
+    && (drawn.backgroundImage !== 'none' || (parse(drawn.backgroundColor)?.a ?? 0) > 0.05))
+    .map(drawn => { const left = parseFloat(drawn.left) || 0, top = parseFloat(drawn.top) || 0; return { left, top, right: left + (parseFloat(drawn.width) || slide.offsetWidth), bottom: top + (parseFloat(drawn.height) || slide.offsetHeight) } })
+  const behind = (element, box) => {
+    if (element.closest('.slide--full-bleed-image')) return null
+    const x = (box.left + box.width / 2 - frame.left) / scale, y = (box.top + box.height / 2 - frame.top) / scale
+    if (fields.some(field => x >= field.left && x <= field.right && y >= field.top && y <= field.bottom)) return null
+    for (let node = element; node && node !== document.documentElement; node = node.parentElement) {
+      const style = getComputedStyle(node)
+      // A field drawn by ::before or ::after (duet's chapter) is behind it too.
+      for (const pseudo of ['::before', '::after']) {
+        const drawn = getComputedStyle(node, pseudo)
+        const painted = drawn.backgroundImage !== 'none' || (parse(drawn.backgroundColor)?.a ?? 0) > 0.05
+        const area = (parseFloat(drawn.width) || 0) * (parseFloat(drawn.height) || 0)
+        if (node !== slide && drawn.content !== 'none' && painted && area >= 0.25 * node.offsetWidth * node.offsetHeight) return null
+      }
+      if (style.backgroundImage !== 'none' && !(node === slide && /radial-gradient/.test(style.backgroundImage) && !/linear/.test(style.backgroundImage))) return null
+      const colour = parse(style.backgroundColor)
+      if (colour && colour.a >= 0.95) return colour
+      if (colour && colour.a > 0.05) return null
+      if (node === slide) return colour
+    }
+    return null
+  }
+  const walker = document.createTreeWalker(slide, NodeFilter.SHOW_TEXT)
+  const seen = new Set()
+  for (let text = walker.nextNode(); text; text = walker.nextNode()) {
+    const element = text.parentElement
+    if (!text.textContent.trim() || seen.has(element) || element.closest('.slide-ink, .katex-mathml, [aria-hidden="true"], .slide--full-bleed-image .slide-bg')) continue
+    seen.add(element)
+    const style = getComputedStyle(element)
+    if (style.visibility === 'hidden' || Number(style.opacity) === 0 || element.closest('[data-step]:not([data-step-visible])')) continue
+    const range = document.createRange()
+    range.selectNodeContents(text)
+    const box = range.getBoundingClientRect()
+    if (!box.width || !box.height) continue
+    const words = text.textContent.trim().slice(0, 40)
+    if (box.left < frame.left - 2 * scale || box.right > frame.right + 2 * scale || box.top < frame.top - 2 * scale || box.bottom > frame.bottom + 2 * scale) problems.push('"' + words + '" is cut off at the edge')
+    const colour = parse(style.color), back = behind(element, box)
+    if (!colour || !back || colour.a < 0.5 || element.closest('.code-block, .katex')) continue
+    const large = parseFloat(style.fontSize) / scale >= 40 || (parseFloat(style.fontSize) / scale >= 30 && Number(style.fontWeight) >= 600)
+    const value = ratio(colour, back)
+    if (value < (large ? 2.6 : 3.4)) problems.push('"' + words + '" has a contrast of ' + value.toFixed(1) + ':1')
+  }
+  return problems
+})()`
+
+// Builds the sample deck with `extensions` ({ id: folder }) beside it and
+// opens it in Chrome for `use({ open, ids })`. Installed user extensions are
+// left out, so the result depends only on what is given.
+export async function withSampleDeck({ extensions = {} } = {}, use) {
+  const temp = mkdtempSync(resolve(tmpdir(), 'mdeck-sample-'))
+  try {
+    writeFileSync(resolve(temp, 'slides.md'), sampleDeck())
+    writeFileSync(resolve(temp, 'picture.svg'), SAMPLE_PICTURE)
+    for (const [id, dir] of Object.entries(extensions)) cpSync(dir, resolve(temp, 'extensions', id), { recursive: true })
+    mkdirSync(resolve(temp, 'home'))
+    execFileSync(process.execPath, [resolve(frameworkRoot, 'bin/mdeck.js'), 'build', resolve(temp, 'slides.md'), '-o', resolve(temp, 'out/index.html')],
+      { cwd: temp, stdio: 'pipe', env: { ...process.env, MDECK_HOME: resolve(temp, 'home') } })
+    const browser = await launchChrome({ dir: resolve(temp, 'out') })
+    try {
+      // A page with the deck in a look, recording what it reports.
+      const open = async ({ theme, palette = '', appearance = '' }) => {
+        const page = await browser.open('about:blank')
+        await page.send('Page.enable')
+        await page.send('Page.addScriptToEvaluateOnNewDocument', { source: RECORDER })
+        await page.send('Page.navigate', { url: `${browser.origin}/index.html?embedded=1&theme=${theme}&palette=${palette}&appearance=${appearance}#1` })
+        await page.waitFor("location.href.includes('index.html')")
+        await page.waitForDeck()
+        return page
+      }
+      return await use({ open })
+    } finally { await browser.close() }
+  } finally { rmSync(temp, { recursive: true, force: true }) }
+}
+
+const settle = page => page.evaluate('new Promise(done => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(done, 60))))')
+
+// Every slide of each look ({ theme, palette }), light and dark; returns the
+// problems found, one line each.
+export function checkLooks(looks, { extensions = {} } = {}) {
+  return withSampleDeck({ extensions }, async ({ open }) => {
+    const failures = []
+    for (const { theme, palette = '' } of looks) {
+      for (const appearance of ['light', 'dark']) {
+        const label = `${theme}${palette ? ` with ${palette}` : ''} (${appearance})`
+        const page = await open({ theme, palette, appearance })
+        await page.send('Emulation.setDeviceMetricsOverride', { width: 1600, height: 900, deviceScaleFactor: 1, mobile: false })
+        const count = await page.evaluate("document.querySelector('deck-stage').length")
+        for (let index = 0; index < count; index++) {
+          await page.evaluate(`window.__index = ${index}; document.querySelector('deck-stage').goTo(${index})`)
+          // Two frames: the stage shows the slide, then fit.js measures it.
+          await settle(page)
+          for (const problem of await page.evaluate(MEASURE)) failures.push(`${label}, slide ${index + 1}: ${problem}`)
+        }
+        for (const line of await page.evaluate('window.__report')) failures.push(`${label}: ${line}`)
+        await page.close()
+      }
+    }
+    return failures
+  })
+}
+
+// Pictures of looks on the sample deck, as WebP: { file, theme, palette,
+// slide } each, slide counting from 1.
+export function renderPreviews(shots, { extensions = {}, width = 960, height = 540 } = {}) {
+  return withSampleDeck({ extensions }, async ({ open }) => {
+    for (const { file, theme, palette = '', slide = 1 } of shots) {
+      const page = await open({ theme, palette })
+      if (slide > 1) { await page.evaluate(`document.querySelector('deck-stage').goTo(${slide - 1})`); await settle(page) }
+      mkdirSync(resolve(file, '..'), { recursive: true })
+      writeFileSync(file, await page.screenshot({ width, height, format: 'webp' }))
+      await page.close()
+    }
+  })
+}