mdeck 2.3.0

package/src/build/chrome.js

@@ -0,0 +1,130 @@
+// Headless Chrome over the DevTools protocol, used for PDF rendering and
+// screenshots. Serves a folder over loopback so relative assets resolve.
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, mkdtempSync, rmSync, statSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { resolve, extname, relative, isAbsolute } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+const CANDIDATES = {
+  darwin: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+  linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
+  win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'],
+}
+const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp', '.mp4': 'video/mp4', '.webm': 'video/webm', '.woff2': 'font/woff2', '.woff': 'font/woff', '.pdf': 'application/pdf' }
+
+export function findChrome() {
+  if (process.env.MDECK_CHROME) return existsSync(process.env.MDECK_CHROME) ? process.env.MDECK_CHROME : null
+  return (CANDIDATES[process.platform] ?? []).find(existsSync) ?? null
+}
+
+export function serveDirectory(root) {
+  return createServer((request, response) => {
+    try {
+      const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname)
+      const file = resolve(root, '.' + pathname)
+      const rel = relative(root, file)
+      if (rel.startsWith('..') || isAbsolute(rel) || !statSync(file).isFile()) throw new Error('not found')
+      response.writeHead(200, { 'Content-Type': MIME[extname(file).toLowerCase()] ?? 'application/octet-stream' })
+      response.end(readFileSync(file))
+    } catch { response.writeHead(404); response.end() }
+  })
+}
+
+// Starts Chrome and a static server for `dir`. `open(path)` returns a page
+// with evaluate(), send() and waitFor(); call close() when done.
+export async function launchChrome({ dir, chrome = findChrome(), timeout = 90000 } = {}) {
+  if (!chrome) throw new Error('No Chrome or Chromium found. Set MDECK_CHROME to its executable path.')
+  const temp = mkdtempSync(resolve(tmpdir(), 'mdeck-chrome-'))
+  const server = serveDirectory(dir)
+  await new Promise(done => server.listen(0, '127.0.0.1', done))
+  const origin = `http://127.0.0.1:${server.address().port}`
+  const flags = ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--hide-scrollbars', '--remote-debugging-port=0', `--user-data-dir=${resolve(temp, 'profile')}`,
+    // Every tab keeps rendering, like the separate windows of a talk: Chrome
+    // otherwise pauses tabs behind the front one, and an input event or an
+    // animation frame there waited for a frame that did not come.
+    '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows']
+  // Chrome refuses to start as root with its sandbox on, as in CI containers.
+  if (process.getuid?.() === 0) flags.push('--no-sandbox')
+  const browser = spawn(chrome, [...flags, 'about:blank'], { stdio: ['ignore', 'ignore', 'pipe'] })
+  const pending = new Map()
+  let socket
+  // `timeout` limits each step (starting Chrome, each command), not the whole
+  // session: a long job with many quick steps must not fail at an arbitrary
+  // step once a total budget runs out.
+  const close = async () => {
+    for (const task of pending.values()) clearTimeout(task.timer)
+    socket?.close()
+    server.close()
+    if (browser.exitCode === null) { browser.kill(); await new Promise(done => browser.once('exit', done)) }
+    // Chrome's helper processes may still write to the profile for a moment
+    // after the browser exits; retry, and never fail a finished job over a
+    // temporary folder.
+    try { rmSync(temp, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }) } catch {}
+  }
+  try {
+    const endpoint = await new Promise((resolveEndpoint, reject) => {
+      let log = ''
+      const startup = setTimeout(() => reject(new Error('Timed out while starting Chrome')), timeout)
+      browser.on('error', reject)
+      browser.on('exit', code => reject(new Error(`Chrome exited early (${code})`)))
+      browser.stderr.on('data', data => { log += data; const match = log.match(/DevTools listening on (ws:\/\/\S+)/); if (match) { clearTimeout(startup); resolveEndpoint(match[1]) } })
+    })
+    socket = new WebSocket(endpoint)
+    await new Promise((done, reject) => { socket.addEventListener('open', done, { once: true }); socket.addEventListener('error', reject, { once: true }) })
+    let nextId = 0
+    socket.addEventListener('message', ({ data }) => {
+      const message = JSON.parse(data)
+      if (!message.id) return
+      const task = pending.get(message.id)
+      pending.delete(message.id)
+      clearTimeout(task?.timer)
+      if (message.error) task?.reject(new Error(message.error.message))
+      else task?.resolve(message.result)
+    })
+    const send = (method, params = {}, sessionId) => new Promise((resolveTask, reject) => {
+      const id = ++nextId
+      // Where the command came from, so a timeout names the step that hung.
+      const caller = new Error().stack?.split('\n').slice(2).find(line => !line.includes('/src/build/chrome.js'))?.trim() ?? ''
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Timed out while driving Chrome: ${method} did not answer within ${timeout / 1000} s ${caller}`)) }, timeout)
+      pending.set(id, { resolve: resolveTask, reject, timer })
+      socket.send(JSON.stringify({ id, method, params, sessionId }))
+    })
+    const open = async path => {
+      const url = path.startsWith('http') ? path : origin + '/' + path.replace(/^\//, '')
+      const { targetId } = await send('Target.createTarget', { url })
+      const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true })
+      const page = {
+        url, sessionId,
+        send: (method, params) => send(method, params, sessionId),
+        async evaluate(expression) {
+          const result = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, sessionId)
+          if (result.exceptionDetails) throw new Error(result.exceptionDetails.text)
+          return result.result.value
+        },
+        async waitFor(expression, { attempts = 600, interval = 100 } = {}) {
+          for (let attempt = 0; attempt < attempts; attempt++) {
+            if (await page.evaluate(expression)) return true
+            await delay(interval)
+          }
+          return false
+        },
+        // Waits until the deck stage exists, fonts are loaded and images decoded.
+        waitForDeck: () => page.waitFor("document.querySelector('deck-stage')?.length > 0 && document.fonts.status === 'loaded' && [...document.images].every(image => image.complete)"),
+        async screenshot({ width = 1600, height = 900, scale = 1, format = 'png' } = {}) {
+          await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: scale, mobile: false }, sessionId)
+          await delay(150)
+          const { data } = await send('Page.captureScreenshot', { format, ...(format === 'png' ? {} : { quality: 82 }), captureBeyondViewport: false }, sessionId)
+          return Buffer.from(data, 'base64')
+        },
+        close: () => send('Target.closeTarget', { targetId }),
+      }
+      return page
+    }
+    return { origin, open, close }
+  } catch (error) {
+    await close()
+    throw error
+  }
+}

package/src/build/components.js

@@ -0,0 +1,44 @@
+// Where a deck's own Preact components come from: its `components/` folder,
+// then the folders its `components:` setting lists, in order. Each `*.jsx`
+// file's default export is registered under its lowercased file name, so
+// `Tokenizer.jsx` becomes `<tokenizer>`. The first folder that has a name wins,
+// and all of them override built-ins of the same name.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve, dirname, basename } from 'node:path'
+import { parseSlides } from '../core/parseSlides.js'
+
+function expand(path, deckDir) {
+  if (path === '~' || path.startsWith('~/')) return resolve(homedir(), path.slice(2))
+  return resolve(deckDir, path)
+}
+
+// Folder paths as written in the deck, resolved; entries that are not strings
+// are left to validateDeck to report.
+export function componentFolders(slidesPath, source = readFileSync(slidesPath, 'utf8')) {
+  const abs = resolve(slidesPath)
+  const deckDir = dirname(abs)
+  let listed = []
+  try { listed = parseSlides(source).deckConfig?.components ?? [] } catch {}
+  return [
+    { dir: resolve(deckDir, 'components'), source: 'deck', path: 'components' },
+    ...(Array.isArray(listed) ? listed : []).filter(path => typeof path === 'string' && path.trim())
+      .map(path => ({ dir: expand(path.trim(), deckDir), source: 'shared', path: path.trim() })),
+  ]
+}
+
+export function isFolder(dir) {
+  try { return statSync(dir).isDirectory() } catch { return false }
+}
+
+export function componentFiles(slidesPath, folders = componentFolders(slidesPath)) {
+  const seen = new Map()
+  for (const folder of folders) {
+    if (!existsSync(folder.dir) || !isFolder(folder.dir)) continue
+    for (const name of readdirSync(folder.dir).filter(name => /\.jsx$/.test(name)).sort()) {
+      const tag = basename(name, '.jsx').toLowerCase()
+      if (!seen.has(tag)) seen.set(tag, { tag, file: resolve(folder.dir, name), source: folder.source, folder: folder.path })
+    }
+  }
+  return [...seen.values()]
+}

package/src/build/config.js

@@ -0,0 +1,61 @@
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import preact from '@preact/preset-vite'
+import { slidesPlugin } from './slidesPlugin.js'
+import { frameworkRoot, runtimeRoot } from '../paths.js'
+import { componentFolders } from './components.js'
+import { userExtensionsDir } from '../extensions/discover.js'
+
+// Resolve preact's entry points through Node so the package's `exports` map is
+// honoured — `preact/jsx-dev-runtime` has no directory of its own, so a
+// hand-written path alias would break the dev server. Exact-match regexes keep
+// `preact` from swallowing its own subpaths.
+const PREACT_ENTRIES = [
+  'preact',
+  'preact/hooks',
+  'preact/jsx-runtime',
+  'preact/jsx-dev-runtime',
+  'preact/compat',
+]
+
+function preactAliases() {
+  const aliases = []
+  for (const spec of PREACT_ENTRIES) {
+    let file
+    try {
+      file = fileURLToPath(import.meta.resolve(spec))
+    } catch {
+      continue // not installed in this framework copy — skip it
+    }
+    aliases.push({ find: new RegExp(`^${spec.replace(/\//g, '\\/')}$`), replacement: file })
+  }
+  return aliases
+}
+
+// ── Vite config ───────────────────────────────────────────────────────────────
+export function baseConfig(slidesPath, { selfContained = false, defaultView = 'deck', server = null, proxyControls = false, source = undefined } = {}) {
+  const abs = resolve(slidesPath)
+  return {
+    configFile: false,
+    root: runtimeRoot,
+    plugins: [preact(), slidesPlugin(abs, source === undefined ? {} : { source })],
+    // Deck-local components live outside the framework root and have no
+    // node_modules of their own, so their preact imports must resolve back to
+    // the framework's copy — and to the *same* instance, or hooks break.
+    resolve: {
+      dedupe: ['preact'],
+      alias: preactAliases(),
+    },
+    server: {
+      port: 5173,
+      strictPort: false,
+      fs: { allow: [frameworkRoot, dirname(abs), userExtensionsDir(), ...componentFolders(abs, source).map(folder => folder.dir)] },
+    },
+    define: {
+      __MDECK_SELF_CONTAINED__: JSON.stringify(selfContained),
+      __MDECK_DEFAULT_VIEW__: JSON.stringify(defaultView),
+      __MDECK_SERVER__: JSON.stringify(server),
+      __MDECK_PROXY_CONTROLS__: JSON.stringify(proxyControls),
+    },
+  }
+}

package/src/build/drawings.js

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { inkFileFor, oldInkFileFor } from '../core/ink.js'
+
+export function drawingsDiagnostic(slidesPath) {
+  const file = inkFileFor(resolve(slidesPath)), old = oldInkFileFor(resolve(slidesPath))
+  if (existsSync(old) && !existsSync(file)) return { severity: 'error', code: 'renamed-file', message: `${basename(old)} is now ${basename(file)}: run mdeck migrate to keep your drawings`, line: 1, column: 1 }
+  return null
+}
+
+export function assertDrawings(slidesPath) {
+  const problem = drawingsDiagnostic(slidesPath)
+  if (problem) throw new Error(problem.message)
+}

package/src/build/editorPlugin.js

@@ -0,0 +1,272 @@
+// Local editing API for `mdeck edit`. The server is a guarded file writer:
+// it only ever writes the one deck path, rejects stale writes with the
+// current content, and tells the editor when the file changed on disk.
+// Before its first write it copies the file into .mdeck-backups/ beside it.
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs'
+import { resolve, basename, dirname, relative } from 'node:path'
+import { builtInRegistry, loadRegistry, serializeRegistry } from '../extensions/discover.js'
+import { fetchIndex, findPack, installedPacks, installFromIndex, PackError } from '../extensions/packs.js'
+import { createRequire } from 'node:module'
+import { ManifestError, KINDS, ID_RE, MANIFEST_FILENAME, parseManifestText, validateManifest } from '../extensions/manifest.js'
+
+const VERSION = createRequire(import.meta.url)('../../package.json').version
+
+const BODY_LIMIT = 32 * 1024 * 1024
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+export function hashSource(source) {
+  return createHash('sha1').update(source, 'utf8').digest('hex')
+}
+
+export const BACKUP_DIR = '.mdeck-backups'
+const BACKUPS_KEPT = 10
+
+// Copies the deck as it is now to .mdeck-backups/<name>-<time>.md and keeps
+// the newest few copies of this deck.
+export function backupDeck(abs, source, now = new Date()) {
+  const dir = resolve(dirname(abs), BACKUP_DIR)
+  mkdirSync(dir, { recursive: true })
+  const name = basename(abs).replace(/\.md$/i, '')
+  const stamp = now.toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z')
+  const file = resolve(dir, `${name}-${stamp}.md`)
+  writeFileSync(file, source, 'utf8')
+  const prefix = `${name}-`
+  const copies = readdirSync(dir).filter(entry => entry.startsWith(prefix) && /^\d{4}-\d{2}-\d{2}T[\d-]+Z\.md$/.test(entry.slice(prefix.length))).sort()
+  for (const old of copies.slice(0, -BACKUPS_KEPT)) unlinkSync(resolve(dir, old))
+  return file
+}
+
+export function createDeckFile(abs, { backup = true } = {}) {
+  let lastWritten = null
+  let backupFile = null
+  const read = () => {
+    const source = readFileSync(abs, 'utf8')
+    return { source, hash: hashSource(source) }
+  }
+  return {
+    path: abs,
+    read,
+    write(source, base) {
+      if (!existsSync(abs)) return { ok: false, conflict: true, source: null, hash: null }
+      const current = read()
+      if (base !== current.hash) return { ok: false, conflict: true, ...current }
+      if (backup && !backupFile && source !== current.source) backupFile = backupDeck(abs, current.source)
+      writeFileSync(abs, source, 'utf8')
+      lastWritten = source
+      return { ok: true, hash: hashSource(source) }
+    },
+    isExternalChange(content) { return content !== lastWritten },
+    get backupFile() { return backupFile },
+  }
+}
+
+function hostname(host = '') {
+  const match = host.match(/^(\[[^\]]*\]|[^:]+)(?::\d+)?$/)
+  return match ? match[1].toLowerCase() : ''
+}
+
+// Names under .localhost always mean this computer and are never looked up
+// in DNS (RFC 6761), so local proxies such as `name.localhost` count too.
+const isLoopbackName = name => LOOPBACK.has(name) || name.endsWith('.localhost')
+
+// Browsers send Origin on cross-site requests; a page served by this server
+// has the same host. Everything else is refused, and only loopback hosts are
+// served at all.
+export const TUNNEL_MARK = 'x-mdeck-tunnel'
+
+export function isAllowedRequest(request) {
+  // Through `mdeck run --server` every request arrives from this computer; the
+  // tunnel marks them (src/build/tunnelClient.js), and they must show a paired
+  // device's token instead.
+  if (request.headers[TUNNEL_MARK] != null) return false
+  const peer = request.socket?.remoteAddress
+  if (peer && peer !== '::1' && !/^(?:::ffff:)?127\.\d+\.\d+\.\d+$/.test(peer)) return false
+  const host = request.headers.host ?? ''
+  if (!isLoopbackName(hostname(host))) return false
+  const origin = request.headers.origin
+  if (origin == null) return true
+  try { return new URL(origin).host.toLowerCase() === host.toLowerCase() } catch { return false }
+}
+
+export function send(response, status, body) {
+  const text = JSON.stringify(body)
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text), 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' })
+  response.end(text)
+}
+
+export function readJson(request) {
+  return new Promise((resolvePromise, reject) => {
+    const type = request.headers['content-type'] ?? ''
+    if (!/^application\/json\b/i.test(type)) return reject(Object.assign(new Error('Send JSON with Content-Type: application/json'), { status: 415 }))
+    const chunks = []
+    let size = 0
+    request.on('data', chunk => {
+      size += chunk.length
+      if (size > BODY_LIMIT) { reject(Object.assign(new Error('Request body too large'), { status: 413 })); request.destroy(); return }
+      chunks.push(chunk)
+    })
+    request.on('end', () => {
+      try { resolvePromise(JSON.parse(Buffer.concat(chunks).toString('utf8'))) } catch { reject(Object.assign(new Error('Request body is not valid JSON'), { status: 400 })) }
+    })
+    request.on('error', reject)
+  })
+}
+
+// ─── Deck-local extensions ────────────────────────────────────────────────
+// Extension folders beside the deck can be read, written and removed. Built-in
+// extensions are readable only. File names are plain basenames inside the
+// extension folder; the manifest must validate before anything is written.
+
+const FILE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const TEXT_FILE_RE = /\.(toml|jsx|js|css|md|txt|json)$/i
+
+export function createExtensionStore(deckDir, { registryFor }) {
+  const root = resolve(deckDir, 'extensions')
+  const folder = id => resolve(root, id)
+  const check = (kind, id) => {
+    if (!KINDS.includes(kind)) throw Object.assign(new Error('Unknown extension kind'), { status: 400 })
+    if (typeof id !== 'string' || !ID_RE.test(id)) throw Object.assign(new Error('Extension ids use lowercase letters, digits and hyphens and start with a letter'), { status: 400 })
+  }
+  const readFolder = dir => Object.fromEntries(readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && TEXT_FILE_RE.test(entry.name) && FILE_NAME_RE.test(entry.name))
+    .map(entry => [entry.name, readFileSync(resolve(dir, entry.name), 'utf8')]))
+  return {
+    root,
+    read(kind, id) {
+      check(kind, id)
+      const record = registryFor()[`${kind}s`][id]
+      if (!record) throw Object.assign(new Error(`No ${kind} "${id}"`), { status: 404 })
+      return { kind, id, source: record.source, dir: record.dir, files: readFolder(record.dir), manifest: record.manifest }
+    },
+    // Validates the manifest against the files that will exist, then writes.
+    write(kind, id, files) {
+      check(kind, id)
+      if (!files || typeof files !== 'object' || Array.isArray(files)) throw Object.assign(new Error('Expected files: { name: text | null }'), { status: 400 })
+      for (const [name, text] of Object.entries(files)) {
+        if (!FILE_NAME_RE.test(name) || !TEXT_FILE_RE.test(name)) throw Object.assign(new Error(`Cannot write "${name}"`), { status: 400 })
+        if (text !== null && typeof text !== 'string') throw Object.assign(new Error(`"${name}" must be text or null`), { status: 400 })
+      }
+      const registry = registryFor()
+      const existing = registry[`${kind}s`][id]
+      if (existing && existing.source !== 'local') throw Object.assign(new Error(`"${id}" is ${existing.source === 'user' ? 'installed for every deck' : 'built into mdeck'}; copy it into this deck under a new id to change it`), { status: 403 })
+      for (const other of KINDS.filter(k => k !== kind)) if (registry[`${other}s`][id]) throw Object.assign(new Error(`"${id}" is already a ${other}`), { status: 409 })
+      const dir = folder(id)
+      const current = existsSync(dir) ? readFolder(dir) : {}
+      const next = { ...current }
+      for (const [name, text] of Object.entries(files)) { if (text === null) delete next[name]; else next[name] = text }
+      if (typeof next[MANIFEST_FILENAME] !== 'string') throw Object.assign(new Error(`${MANIFEST_FILENAME} is required`), { status: 400 })
+      const manifestPath = resolve(dir, MANIFEST_FILENAME)
+      const record = validateManifest(parseManifestText(next[MANIFEST_FILENAME], manifestPath), {
+        file: manifestPath, dir, folderName: id, fileExists: path => Object.hasOwn(next, relative(dir, path)),
+      })
+      if (record.kind !== kind) throw Object.assign(new Error(`The manifest says kind = "${record.kind}", not "${kind}"`), { status: 400 })
+      mkdirSync(dir, { recursive: true })
+      for (const [name, text] of Object.entries(files)) {
+        const path = resolve(dir, name)
+        if (text === null) { if (existsSync(path)) unlinkSync(path) } else writeFileSync(path, text, 'utf8')
+      }
+      return { kind, id, dir, files: readFolder(dir) }
+    },
+    remove(kind, id) {
+      check(kind, id)
+      const record = registryFor()[`${kind}s`][id]
+      if (!record) throw Object.assign(new Error(`No ${kind} "${id}"`), { status: 404 })
+      if (record.source !== 'local') throw Object.assign(new Error(`"${id}" is ${record.source === 'user' ? 'installed for every deck; remove it with mdeck themes remove --global' : 'built into mdeck and cannot be removed'}`), { status: 403 })
+      rmSync(record.dir, { recursive: true, force: true })
+      return { kind, id }
+    },
+  }
+}
+
+export function editorMiddleware(deckFile, { registryFor, extensions = createExtensionStore(dirname(deckFile.path), { registryFor }) }) {
+  const extensionsDir = resolve(dirname(deckFile.path), 'extensions')
+  return async (request, response, next) => {
+    const pathname = new URL(request.url, 'http://localhost').pathname
+    if (!isAllowedRequest(request)) return send(response, 403, { error: 'Requests are only accepted from this editor on this computer' })
+    try {
+      const extension = pathname.match(/^\/extension\/([a-z]+)\/([^/]+)$/)
+      if (extension) {
+        const [, kind, id] = extension
+        if (request.method === 'GET') return send(response, 200, extensions.read(kind, id))
+        if (request.method === 'PUT') {
+          const body = await readJson(request)
+          const result = extensions.write(kind, id, body?.files)
+          return send(response, 200, { ...result, registry: serializeRegistry(registryFor()) })
+        }
+        if (request.method === 'DELETE') {
+          const result = extensions.remove(kind, id)
+          return send(response, 200, { ...result, registry: serializeRegistry(registryFor()) })
+        }
+        response.setHeader('Allow', 'GET, PUT, DELETE')
+        return send(response, 405, { error: 'Method not allowed' })
+      }
+      // The theme repository: what it offers, and installing a pack into the
+      // deck's extensions folder.
+      if (pathname === '/themes/index' && request.method === 'GET') {
+        const index = await fetchIndex()
+        return send(response, 200, { ...index, installed: installedPacks(extensionsDir) })
+      }
+      if (pathname === '/themes/install' && request.method === 'POST') {
+        const body = await readJson(request)
+        const index = await fetchIndex()
+        const registry = builtInRegistry()
+        const result = await installFromIndex(index, findPack(index, String(body?.id ?? '')), { root: extensionsDir, known: { themes: registry.themes, palettes: registry.palettes }, mdeckVersion: VERSION })
+        return send(response, 200, { ...result, registry: serializeRegistry(registryFor()) })
+      }
+      if (pathname === '/deck' && request.method === 'GET') {
+        const registry = registryFor()
+        const where = deckFile.designOnly ? { path: dirname(deckFile.path), name: basename(dirname(deckFile.path)), designOnly: true } : { path: deckFile.path, name: basename(deckFile.path) }
+        return send(response, 200, { ...where, ...deckFile.read(), registry: serializeRegistry(registry), warnings: registry.warnings })
+      }
+      if (pathname === '/source' && request.method === 'POST' && deckFile.designOnly) return send(response, 403, { error: 'There is no deck to save: the design page was started without one' })
+      if (pathname === '/source' && request.method === 'POST') {
+        const body = await readJson(request)
+        if (typeof body?.source !== 'string' || typeof body?.base !== 'string') return send(response, 400, { error: 'Expected { source: string, base: string }' })
+        const result = deckFile.write(body.source, body.base)
+        if (result.ok) return send(response, 200, { hash: result.hash })
+        return send(response, 409, { error: 'conflict', source: result.source, hash: result.hash })
+      }
+      if (['/deck', '/source'].includes(pathname)) { response.setHeader('Allow', pathname === '/deck' ? 'GET' : 'POST'); return send(response, 405, { error: 'Method not allowed' }) }
+      return next()
+    } catch (error) {
+      if (error instanceof PackError) return send(response, 400, { error: error.message })
+      if (error instanceof ManifestError) return send(response, 500, { error: error.message })
+      return send(response, error.status ?? 500, { error: error.message })
+    }
+  }
+}
+
+// A deck that is only text and is never written: what the design page shows
+// when `mdeck design` starts it without a deck. `abs` places it in the folder
+// whose extensions are edited.
+export function createSampleDeck(abs, source) {
+  return { path: abs, designOnly: true, read: () => ({ source, hash: hashSource(source) }), write: () => ({ ok: false, conflict: true, source, hash: hashSource(source) }), isExternalChange: () => false, backupFile: null }
+}
+
+// `source` is given for `mdeck design` without a deck: the editing API then
+// serves it read-only and only extensions are written.
+export function editorPlugin(slidesPath, { source = null } = {}) {
+  const abs = resolve(slidesPath)
+  const deckFile = source === null ? createDeckFile(abs) : createSampleDeck(abs, source)
+  return {
+    name: 'vite-plugin-mdeck-editor',
+    configureServer(server) {
+      server.middlewares.use('/__mdeck', editorMiddleware(deckFile, { registryFor: () => loadRegistry(abs) }))
+      if (source !== null) return
+      server.watcher.add(abs)
+      let timer
+      const changed = file => {
+        if (resolve(file) !== abs) return
+        clearTimeout(timer)
+        timer = setTimeout(() => {
+          let content
+          try { content = readFileSync(abs, 'utf8') } catch { return }
+          if (deckFile.isExternalChange(content)) server.ws.send('mdeck:deck-changed', { hash: hashSource(content) })
+        }, 75)
+      }
+      server.watcher.on('change', changed)
+      server.watcher.on('add', changed)
+    },
+  }
+}

package/src/build/editorServer.js

@@ -0,0 +1,36 @@
+// The `mdeck edit` server, also started on demand from the launch page. It
+// listens on loopback only and never reloads pages when the deck changes.
+// `open` is true for the editor, or the path of another page to open.
+import { createServer } from 'vite'
+import preact from '@preact/preset-vite'
+import { dirname, resolve } from 'node:path'
+import { baseConfig } from './config.js'
+import { slidesPlugin } from './slidesPlugin.js'
+import { editorPlugin, BACKUP_DIR } from './editorPlugin.js'
+import { sampleDeck, sampleDataUrl } from '../editor/sampleDeck.js'
+
+export function createEditorServer(slidesPath, { port = 5173, strictPort = false, open = false } = {}) {
+  const abs = resolve(slidesPath)
+  const base = baseConfig(abs)
+  return createServer({
+    ...base,
+    plugins: [preact(), slidesPlugin(abs, { editor: true }), editorPlugin(abs)],
+    publicDir: dirname(abs),
+    server: { ...base.server, host: '127.0.0.1', cors: false, port, strictPort, open: open === true ? '/editor.html' : open || false, watch: { ignored: [`**/${BACKUP_DIR}/**`] } },
+  })
+}
+
+// `mdeck design` without a deck: the design page on the sample deck, making
+// and changing the extensions in `folder`/extensions, where a deck in that
+// folder finds them. No deck file is read or written.
+export function createDesignServer(folder, { port = 5173, strictPort = false, open = false } = {}) {
+  const abs = resolve(folder, 'design.md')
+  const source = sampleDeck(sampleDataUrl())
+  const base = baseConfig(abs, { source })
+  return createServer({
+    ...base,
+    plugins: [preact(), slidesPlugin(abs, { editor: true, source, ink: false }), editorPlugin(abs, { source })],
+    publicDir: false,
+    server: { ...base.server, host: '127.0.0.1', cors: false, port, strictPort, open: open === true ? '/design.html' : open || false },
+  })
+}

package/src/build/fonts.js

@@ -0,0 +1,84 @@
+// A theme's web fonts, embedded in a single-file build (mdeck send, --single-file,
+// and the page mdeck pdf prints), so a file opened offline and its PDF look
+// like the slides on the presenter's screen instead of falling back to system
+// fonts.
+//
+// The theme's font stylesheets (Google Fonts and the like) are fetched once,
+// limited to the Latin character sets, and every font file becomes a data URI.
+// Fetched files are kept in a cache, so later builds need no network. Without
+// network and cache the build goes on with the fallback fonts and says so.
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// A current browser gets WOFF2, the smallest format.
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36'
+// The character sets slides in Western languages need; Google Fonts names
+// each block of a stylesheet after its set.
+const SUBSETS = new Set(['latin', 'latin-ext'])
+const FONT_TYPES = { woff2: 'font/woff2', woff: 'font/woff', ttf: 'font/ttf', otf: 'font/otf' }
+
+export const fontCacheDir = () => process.env.MDECK_CACHE_DIR
+  ? join(process.env.MDECK_CACHE_DIR, 'fonts')
+  : join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'mdeck', 'fonts')
+
+const key = text => createHash('sha256').update(text).digest('hex').slice(0, 32)
+
+async function cached(url, { fetch: get, cacheDir, binary, timeoutMs }) {
+  const file = join(cacheDir, key(url) + (binary ? '.bin' : '.css'))
+  if (existsSync(file)) return binary ? readFileSync(file) : readFileSync(file, 'utf8')
+  const response = await get(url, { headers: { 'User-Agent': USER_AGENT }, signal: AbortSignal.timeout(timeoutMs) })
+  if (!response.ok) throw new Error(`${url} answered ${response.status}`)
+  const body = binary ? Buffer.from(await response.arrayBuffer()) : await response.text()
+  mkdirSync(cacheDir, { recursive: true })
+  writeFileSync(file, body)
+  return body
+}
+
+// The @font-face blocks of a stylesheet, without the character sets that
+// slides rarely need (Cyrillic, Greek, Vietnamese …). A variable font is
+// listed once per weight with the same file; those become one face with a
+// weight range, so the file is embedded once.
+export function latinFaces(css) {
+  const blocks = [...css.matchAll(/(?:\/\*\s*([\w-]+)\s*\*\/\s*)?(@font-face\s*\{[^}]*\})/g)]
+  const faces = blocks.filter(([, subset]) => !subset || SUBSETS.has(subset)).map(([, , face]) => face)
+  const groups = new Map()
+  for (const face of faces) {
+    const src = face.match(/src:\s*([^;]+);/)?.[1]
+    const style = face.match(/font-style:\s*([^;]+);/)?.[1] ?? 'normal'
+    const weights = (face.match(/font-weight:\s*([^;]+);/)?.[1] ?? '400').trim().split(/\s+/).map(Number)
+    const id = `${src}|${style}`
+    if (!src || weights.some(Number.isNaN)) { groups.set(face, { face }); continue }
+    const group = groups.get(id)
+    if (!group) groups.set(id, { face, min: Math.min(...weights), max: Math.max(...weights) })
+    else { group.min = Math.min(group.min, ...weights); group.max = Math.max(group.max, ...weights) }
+  }
+  return [...groups.values()].map(({ face, min, max }) => min == null ? face
+    : face.replace(/font-weight:\s*[^;]+;/, `font-weight: ${min === max ? min : `${min} ${max}`};`))
+}
+
+/**
+ * CSS with the fonts of these stylesheet URLs embedded, and warnings for
+ * whatever could not be fetched.
+ */
+export async function embedFonts(urls = [], { fetch: get = fetch, cacheDir = fontCacheDir(), timeoutMs = 15000 } = {}) {
+  const faces = [], warnings = []
+  for (const url of urls) {
+    try {
+      const css = await cached(url, { fetch: get, cacheDir, binary: false, timeoutMs })
+      for (const face of latinFaces(css)) {
+        let embedded = face
+        for (const [match, fontUrl] of face.matchAll(/url\((?:'|")?([^'")]+)(?:'|")?\)/g)) {
+          const type = FONT_TYPES[fontUrl.split(/[?#]/)[0].split('.').pop()] ?? 'font/woff2'
+          const data = await cached(new URL(fontUrl, url).href, { fetch: get, cacheDir, binary: true, timeoutMs })
+          embedded = embedded.replace(match, `url(data:${type};base64,${data.toString('base64')})`)
+        }
+        faces.push(embedded)
+      }
+    } catch (error) {
+      warnings.push(`The font ${url} could not be embedded (${error.cause?.code ?? error.message}); the file uses the fallback fonts.`)
+    }
+  }
+  return { css: faces.join('\n'), warnings }
+}