mdeck 2.3.0

package/src/build/homePlugin.js

@@ -0,0 +1,208 @@
+// Launch page API for `mdeck run`: what the deck contains, what `mdeck check`
+// says about it, the state of its server, and buttons that start the
+// editor and the guides or run a build. Like the editor API it answers loopback
+// requests from its own pages only, even when the server is shared on the
+// network for phones.
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { resolve, dirname, basename } from 'node:path'
+import { loadRegistry } from '../extensions/discover.js'
+import { parseSlides } from '../core/parseSlides.js'
+import { checkDeck } from './check.js'
+import { sessionCode } from '../live/code.js'
+import { roomsIn } from '../live/roomTag.js'
+import { isAllowedRequest, send, readJson } from './editorPlugin.js'
+import { findChrome } from './chrome.js'
+import { frameworkRoot } from '../paths.js'
+
+// Each output is one ordinary CLI run beside the deck, so the launch page
+// builds exactly what the command line would.
+export function outputsFor(slidesPath) {
+  const abs = resolve(slidesPath), dir = dirname(abs), name = basename(abs).replace(/\.md$/i, '')
+  return {
+    folder: { title: 'Folder to host', args: ['build', abs, '--reader'], file: resolve(dir, 'dist/index.html') },
+    send: { title: 'One file to send', args: ['send', abs, '-o', `${name}.html`], file: resolve(dir, `${name}.html`), chrome: true },
+    pdf: { title: 'PDF', args: ['pdf', abs, '-o', `${name}.pdf`], file: resolve(dir, `${name}.pdf`), chrome: true },
+  }
+}
+
+export function runCli(args, cwd) {
+  return new Promise(done => {
+    const child = spawn(process.execPath, [resolve(frameworkRoot, 'bin/mdeck.js'), ...args], { cwd, env: { ...process.env, FORCE_COLOR: '0' }, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    child.stdout.on('data', data => { output += data })
+    child.stderr.on('data', data => { output += data })
+    child.on('error', error => done({ code: 1, output: error.message }))
+    child.on('close', code => done({ code, output: output.replace(/\x1b\[[0-9;]*m/g, '').trim() }))
+  })
+}
+
+function reveal(file) {
+  const [command, args] = process.platform === 'darwin' ? ['open', ['-R', file]]
+    : process.platform === 'win32' ? ['explorer', [`/select,${file}`]]
+    : ['xdg-open', [dirname(file)]]
+  spawn(command, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref()
+}
+
+// The server named in the `server` setting: whether it answers, and whether it
+// accepts the key (MDECK_SERVER_KEY, as given to the server).
+export async function liveStatus(live, { key = null, fetch: get = fetch, timeoutMs = 2500 } = {}) {
+  const started = Date.now()
+  try {
+    const response = await get(`${live.server.replace(/\/+$/, '')}/info`, { headers: key ? { Authorization: `Bearer ${key}` } : {}, signal: AbortSignal.timeout(timeoutMs) })
+    if (!response.ok) return { reachable: false, error: `It answered with status ${response.status}` }
+    const body = await response.json()
+    return { reachable: true, ms: Date.now() - started, keyAccepted: key ? !!body.canReset : null }
+  } catch (error) {
+    return { reachable: false, error: error.name === 'TimeoutError' ? `No answer within ${timeoutMs / 1000} s` : error.cause?.code ?? error.message }
+  }
+}
+
+// `urls()` returns the server's addresses; `services` start the editor and the
+// guides; `fetch` reaches the server. All are injected so tests can run
+// without a browser or network.
+export function homeMiddleware(slidesPath, { urls = () => ({ local: [], network: [] }), services = {}, pairing = null, relay = null, server: serverAddress = null, run = runCli, open = reveal, serverKey = process.env.MDECK_SERVER_KEY || null, fetch: get = fetch } = {}) {
+  const abs = resolve(slidesPath)
+  const outputs = outputsFor(abs)
+  const jobs = {}
+  const started = {}, serviceUrls = {}
+
+  async function info(request) {
+    const source = readFileSync(abs, 'utf8')
+    let registry = null, registryError = null
+    try { registry = loadRegistry(abs) } catch (error) { registryError = error.message }
+    const { deck, diagnostics } = registry ? checkDeck(abs, registry, source) : { deck: parseSlides(source), diagnostics: [] }
+    const config = deck.deckConfig ?? {}
+    const { local: serverLocal = [], network = [] } = urls() ?? {}
+    // The address this page was opened with, such as a local proxy's name.
+    const local = request?.headers?.host ? [`http://${request.headers.host}/`, ...serverLocal] : serverLocal
+    return {
+      file: abs,
+      name: basename(abs),
+      modified: statSync(abs).mtime.toISOString(),
+      title: config.meta?.title ?? basename(abs).replace(/\.md$/i, ''),
+      author: config.meta?.author ?? null,
+      slides: deck.slides.length,
+      width: config.width ?? 1920,
+      height: config.height ?? 1080,
+      notes: deck.slides.filter(slide => slide.meta.notes).length,
+      theme: config.theme ?? 'neue',
+      palette: config.palette ?? null,
+      diagnostics: [...(registry?.warnings ?? []).map(message => ({ severity: 'warning', code: 'extension', message })), ...(registryError ? [{ severity: 'error', code: 'extension', message: registryError }] : []), ...diagnostics],
+      live: await live(config, source, { local, network }),
+      presence: presenceUrl(config),
+      // Presenting from an iPad needs an address it can reach (`--host`).
+      pairing: pairing ? { available: !!relay || !!network[0], devices: pairing.devices } : null,
+      relay: relay ? { url: relay.url, state: relay.state, reason: relay.reason } : null,
+      chrome: !!findChrome(),
+      services: Object.fromEntries(Object.keys(services).map(key => [key, serviceUrls[key] ?? null])),
+      outputs: Object.fromEntries(Object.entries(outputs).map(([key, output]) => [key, {
+        title: output.title,
+        file: output.file,
+        exists: existsSync(output.file),
+        needsChrome: !!output.chrome,
+        ...(jobs[key] ?? { status: 'idle' }),
+      }])),
+    }
+  }
+
+  // Where the launch page asks who is connected: the deck's stage room, on
+  // the deck's own server, or here when this server passes the rooms on
+  // (with MDECK_SERVER_KEY) or keeps them itself. Relative to the page.
+  function presenceUrl(config) {
+    const address = serverAddress ?? config.server
+    const room = `rooms/${encodeURIComponent(`${sessionCode(config)}.stage`)}/presence`
+    return typeof address === 'string' && !serverKey ? `${address.replace(/\/+$/, '')}/${room}` : `__mdeck/live/${room}`
+  }
+
+  // Decks with activities, or with a server of their own, get this
+  // section: the server and its health, the join link phones open and,
+  // for a server of their own, the presenter code.
+  async function live(config, source, { local, network }) {
+    const address = serverAddress ?? config.server
+    const settings = { server: address }
+    const own = typeof address === 'string'
+    if (!own && roomsIn(source).length === 0) return null
+    const code = sessionCode(config)
+    const builtIn = base => new URL(`__mdeck/live/${code}`, base).href
+    const joinUrl = own ? `${settings.server.replace(/\/+$/, '')}/${code}` : network[0] ? builtIn(network[0]) : null
+    return {
+      server: own ? settings.server : null,
+      code,
+      ...(own ? await liveStatus(settings, { key: serverKey, fetch: get }) : { reachable: true }),
+      key: own ? serverKey : null,
+      joinUrl,
+      localJoinUrl: joinUrl ?? (local[0] ? builtIn(local[0]) : null),
+    }
+  }
+
+  // Each service starts once; a failed start can be retried.
+  async function start(key) {
+    started[key] ??= services[key]().then(service => { serviceUrls[key] = service.url; return service }, error => { delete started[key]; throw error })
+    return (await started[key]).url
+  }
+
+  // The one-time address an iPad opens to present from: the presenter view,
+  // with a one-time pairing offer; the server's master key stays here.
+  function pairUrl() {
+    const network = relay?.url ?? urls()?.network?.[0]
+    if (!pairing || !network) throw Object.assign(new Error('Start mdeck run with --network or --server so an iPad can reach it'), { status: 409 })
+    const url = new URL(network)
+    url.searchParams.set('view', 'presenter')
+    url.searchParams.set('pair', pairing.offer())
+    return url.href
+  }
+
+  async function act({ action, output } = {}) {
+    if (Object.hasOwn(services, action)) return { url: await start(action) }
+    if (action === 'pair') return { url: pairUrl() }
+    if (action === 'unpair') { pairing?.revoke(); return { ok: true } }
+    if (action === 'build') {
+      if (!Object.hasOwn(outputs, output)) throw Object.assign(new Error(`Unknown output: ${output}`), { status: 400 })
+      if (jobs[output]?.status === 'running') throw Object.assign(new Error('That build is already running'), { status: 409 })
+      jobs[output] = { status: 'running', startedAt: new Date().toISOString() }
+      const { code, output: log } = await run(outputs[output].args, dirname(abs))
+      jobs[output] = { status: code === 0 ? 'done' : 'failed', log, finishedAt: new Date().toISOString() }
+      return jobs[output]
+    }
+    if (action === 'reveal') {
+      const target = outputs[output]?.file ?? (output === 'deck' ? abs : null)
+      if (!target || !existsSync(target)) throw Object.assign(new Error('Nothing to show yet'), { status: 404 })
+      open(target)
+      return { ok: true }
+    }
+    throw Object.assign(new Error(`Unknown action: ${action}`), { status: 400 })
+  }
+
+  return async (request, response, next) => {
+    const pathname = new URL(request.url, 'http://localhost').pathname
+    if (!['/info', '/action'].includes(pathname)) return next()
+    if (!isAllowedRequest(request)) return send(response, 403, { error: 'The launch page only answers on this computer' })
+    try {
+      if (pathname === '/info' && request.method === 'GET') return send(response, 200, await info(request))
+      if (pathname === '/action' && request.method === 'POST') return send(response, 200, await act(await readJson(request)))
+      response.setHeader('Allow', pathname === '/info' ? 'GET' : 'POST')
+      return send(response, 405, { error: 'Method not allowed' })
+    } catch (error) {
+      return send(response, error.status ?? 500, { error: error.message })
+    }
+  }
+}
+
+export function homePlugin(slidesPath, { services, pairing, relay = null, server: serverAddress = null } = {}) {
+  return {
+    name: 'vite-plugin-mdeck-home',
+    configureServer(server) {
+      // The bare address is the launch page; the slides are at ?view=deck.
+      // Only a plain page visit is redirected: every view, preview and editor
+      // frame carries a query.
+      const base = server.config.base
+      server.middlewares.use((request, response, next) => {
+        if (request.method !== 'GET' || ![base, `${base}index.html`].includes(request.url) || !/text\/html/.test(request.headers.accept ?? '')) return next()
+        response.writeHead(302, { Location: `${base}home.html` })
+        response.end()
+      })
+      server.middlewares.use('/__mdeck/home', homeMiddleware(slidesPath, { urls: () => server.resolvedUrls, services, pairing, relay, server: serverAddress }))
+    },
+  }
+}

package/src/build/inkPlugin.js

@@ -0,0 +1,192 @@
+// Saving ink while `mdeck run` runs: the file beside the deck is the source of
+// truth, and devices send changes as operations (see applyOp in core/ink.js),
+// so strokes drawn on two devices at once never overwrite each other.
+//
+//   GET  /__mdeck/ink        { ink, deckHash }
+//   POST /__mdeck/ink/ops    { deckHash, ops } → { deckHash, renamed }
+//
+// A slide that gets ink but has no `id:` of its own gets one, written into
+// its settings, so the ink stays with it when slides are inserted. Ids by
+// position (slide-3) are only trusted when the device saw the current deck
+// (deckHash); otherwise the answer is 409 and the device reloads. The server's
+// own writes do not reload the open windows (ownWrites.js); instead it sends
+// `mdeck:ink`, and the pages fetch the ink again.
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs'
+import { resolve, dirname, basename } from 'node:path'
+import { parseSlides } from '../core/parseSlides.js'
+import { setSlideMeta } from '../core/editDeck.js'
+import { slideTitle } from '../core/outline.js'
+import { slug } from '../live/code.js'
+import { inkFileFor, normalizeInk, emptyInk, applyOp, serializeInk } from '../core/ink.js'
+import { hashSource, isAllowedRequest, send, readJson, BACKUP_DIR } from './editorPlugin.js'
+import { markOwnWrite } from './ownWrites.js'
+
+const ID_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/
+const BACKUPS_KEPT = 10
+
+function writeAtomic(path, text) {
+  const temp = `${path}.${process.pid}.tmp`
+  writeFileSync(temp, text, 'utf8')
+  renameSync(temp, path)
+}
+
+// A readable, unique id from the slide's heading, as ids must start with a letter.
+function newSlideId(deck, slide, index) {
+  const taken = new Set(deck.slides.map(s => s.id))
+  let base = slug(slideTitle(slide, index, null)) || 'slide'
+  if (!/^[a-z]/.test(base)) base = `slide-${base}`
+  let id = base, n = 2
+  while (taken.has(id) || !ID_RE.test(id)) id = `${base}-${n++}`
+  return id
+}
+
+export function createInkFile(deckPath, { debounceMs = 300, onChange = () => {} } = {}) {
+  const abs = resolve(deckPath)
+  const inkPath = inkFileFor(abs)
+  let ink = null, timer = null, backedUp = false
+  // Ids given to slides, for devices that still saw the deck from before:
+  // { from, to, before } applies only to requests made against `before`.
+  const renames = []
+  let knownIds = null
+
+  const readDeck = () => { const source = readFileSync(abs, 'utf8'); return { source, deck: parseSlides(source), hash: hashSource(source) } }
+  const size = deck => ({ width: deck.deckConfig?.width ?? 1920, height: deck.deckConfig?.height ?? 1080 })
+
+  // The file on disk, unless changes are still waiting to be written.
+  function current(deck) {
+    if (timer && ink) return ink
+    try { ink = existsSync(inkPath) ? normalizeInk(JSON.parse(readFileSync(inkPath, 'utf8')), size(deck)) : emptyInk(size(deck)) }
+    catch { ink ??= emptyInk(size(deck)) }
+    return ink
+  }
+
+  function backupOnce() {
+    if (backedUp || !existsSync(inkPath)) { backedUp = true; return }
+    const dir = resolve(dirname(abs), BACKUP_DIR)
+    mkdirSync(dir, { recursive: true })
+    const name = basename(inkPath, '.json')
+    writeFileSync(resolve(dir, `${name}-${new Date().toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z')}.json`), readFileSync(inkPath))
+    const copies = readdirSync(dir).filter(entry => entry.startsWith(`${name}-`) && entry.endsWith('.json')).sort()
+    for (const old of copies.slice(0, -BACKUPS_KEPT)) unlinkSync(resolve(dir, old))
+    backedUp = true
+  }
+
+  function flush() {
+    clearTimeout(timer)
+    timer = null
+    if (!ink) return
+    backupOnce()
+    const text = serializeInk(ink)
+    markOwnWrite(inkPath, text)
+    writeAtomic(inkPath, text)
+  }
+
+  // A slide whose `id:` was changed in the editor or by hand, at the same
+  // place in a deck with the same number of slides, keeps its ink. Ink of a
+  // removed slide stays in the file (mdeck check reports it), so undoing the
+  // removal brings it back.
+  function deckChanged() {
+    let deck
+    try { deck = readDeck().deck } catch { return [] }
+    const ids = deck.slides.map(slide => slide.id)
+    const before = knownIds
+    knownIds = ids
+    if (!before || before.length !== ids.length) return []
+    current(deck)
+    const moved = []
+    ids.forEach((id, i) => {
+      const from = before[i]
+      if (from !== id && !ids.includes(from) && !before.includes(id) && ink.slides[from]) {
+        ink = applyOp(ink, { type: 'rename', from, to: id })
+        moved.push({ from, to: id })
+      }
+    })
+    if (moved.length) flush()
+    return moved
+  }
+  try { knownIds = readDeck().deck.slides.map(slide => slide.id) } catch {}
+
+  return {
+    path: inkPath,
+    deckChanged,
+    read() {
+      const { deck, hash } = readDeck()
+      return { ink: current(deck), deckHash: hash }
+    },
+    apply(ops, deckHash) {
+      let { source, deck, hash } = readDeck()
+      current(deck)
+      const renamed = []
+      const seen = deckHash
+      const alias = new Map(renames.filter(r => r.before === seen).map(r => [r.from, r.to]))
+      for (const raw of Array.isArray(ops) ? ops : []) {
+        const op = { ...raw, slideId: alias.get(raw?.slideId) ?? raw?.slideId }
+        if (op.type === 'add') {
+          const index = deck.slides.findIndex(slide => slide.id === op.slideId)
+          if (index < 0) return { status: 409, error: `No slide "${op.slideId}" in the deck any more`, deckHash: hash }
+          const slide = deck.slides[index]
+          if (slide.meta.id == null) {
+            // An id by position: only trusted for the deck the device saw.
+            if (deckHash !== hash) return { status: 409, error: 'The deck changed; reload', deckHash: hash }
+            const id = newSlideId(deck, slide, index)
+            renames.push({ from: op.slideId, to: id, before: hash })
+            source = setSlideMeta(deck, op.slideId, { id })
+            markOwnWrite(abs, source)
+            writeAtomic(abs, source)
+            deck = parseSlides(source)
+            hash = hashSource(source)
+            deckHash = hash
+            ink = applyOp(ink, { type: 'rename', from: op.slideId, to: id })
+            renamed.push({ from: op.slideId, to: id })
+            alias.set(op.slideId, id)
+            op.slideId = id
+          }
+        }
+        ink = applyOp(ink, op)
+      }
+      knownIds = deck.slides.map(slide => slide.id)
+      clearTimeout(timer)
+      timer = setTimeout(flush, debounceMs)
+      onChange({ renamed })
+      return { status: 200, deckHash: hash, renamed }
+    },
+    flush,
+  }
+}
+
+// `authorize(request)` may allow requests beyond this computer (pairing).
+export function inkMiddleware(file, { authorize = isAllowedRequest } = {}) {
+  return async (request, response, next) => {
+    const { pathname } = new URL(request.url, 'http://localhost')
+    if (pathname !== '/' && pathname !== '/ops') return next()
+    if (!authorize(request)) return send(response, 403, { error: 'Only the presenter can change the ink' })
+    try {
+      if (pathname === '/' && request.method === 'GET') return send(response, 200, file.read())
+      if (pathname === '/ops' && request.method === 'POST') {
+        const { deckHash, ops } = await readJson(request)
+        const result = file.apply(ops, deckHash)
+        return send(response, result.status, result)
+      }
+      response.setHeader('Allow', pathname === '/' ? 'GET' : 'POST')
+      return send(response, 405, { error: 'Method not allowed' })
+    } catch (error) {
+      return send(response, error.status ?? 500, { error: error.message })
+    }
+  }
+}
+
+export function inkPlugin(slidesPath, { authorize } = {}) {
+  return {
+    name: 'vite-plugin-mdeck-ink',
+    configureServer(server) {
+      const file = createInkFile(slidesPath, { onChange: ({ renamed }) => server.ws.send('mdeck:ink', { renamed }) })
+      server.middlewares.use('/__mdeck/ink', inkMiddleware(file, { authorize }))
+      server.watcher.on('change', changed => {
+        if (resolve(changed) !== resolve(slidesPath)) return
+        const renamed = file.deckChanged()
+        if (renamed.length) server.ws.send('mdeck:ink', { renamed })
+      })
+      server.httpServer?.once('close', () => file.flush())
+    },
+  }
+}

package/src/build/ownWrites.js

@@ -0,0 +1,18 @@
+// Files mdeck itself just wrote while the dev server runs, so the watcher can
+// tell its own writes (a new slide id, saved ink) from edits by the author:
+// its own writes must not reload the open windows in the middle of a talk.
+import { createHash } from 'node:crypto'
+import { resolve } from 'node:path'
+
+const written = new Map()
+const hash = content => createHash('sha1').update(content).digest('hex')
+
+export function markOwnWrite(path, content) {
+  written.set(resolve(path), hash(content))
+}
+
+// True when `content` is what mdeck last wrote to `path`. The mark stays, as
+// watchers may report one write twice; the same content needs no reload.
+export function isOwnWrite(path, content) {
+  return written.get(resolve(path)) === hash(content)
+}

package/src/build/pairing.js

@@ -0,0 +1,81 @@
+// Pairing another device (an iPad) with `mdeck run`, so it may do what only
+// this computer may: save ink and steer the rooms. The launch page, which
+// only answers on this computer, offers a one-time address as a QR code; the
+// device trades the one-time token in it for a token of its own, which it
+// sends as `Authorization: Bearer …`. Tokens live in memory: restarting
+// `mdeck run` or "Unpair" on the launch page ends every pairing.
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { send, readJson } from './editorPlugin.js'
+
+const OFFER_MS = 10 * 60 * 1000
+const token = () => randomBytes(24).toString('base64url')
+const same = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y) }
+
+export function createPairing({ now = Date.now } = {}) {
+  const offers = new Map() // one-time token → expiry
+  const devices = new Set()
+  const listeners = new Set()
+  const changed = () => { for (const listener of listeners) listener() }
+  const bearer = request => (request.headers?.authorization ?? '').replace(/^Bearer\s+/i, '')
+
+  return {
+    /** A one-time token for the QR code, valid for ten minutes. */
+    offer() {
+      for (const [offer, expires] of offers) if (expires < now()) offers.delete(offer)
+      const offer = token()
+      offers.set(offer, now() + OFFER_MS)
+      return offer
+    },
+    /** The device's own token for a one-time token, or null. */
+    claim(offer) {
+      if (typeof offer !== 'string') return null
+      for (const [known, expires] of offers) {
+        if (!same(known, offer)) continue
+        offers.delete(known)
+        if (expires < now()) return null
+        const device = token()
+        devices.add(device)
+        changed()
+        return device
+      }
+      return null
+    },
+    /** Whether a request comes from a paired device. */
+    allows(request) {
+      const given = bearer(request)
+      if (!given) return false
+      for (const device of devices) if (same(device, given)) return true
+      return false
+    },
+    revoke() { devices.clear(); offers.clear(); changed() },
+    /** The paired devices' tokens, for the server of `mdeck run --server`. */
+    tokens: () => [...devices],
+    /** Calls back when a device pairs or all are unpaired; returns a function that stops it. */
+    onChange(listener) { listeners.add(listener); return () => listeners.delete(listener) },
+    get devices() { return devices.size },
+  }
+}
+
+// POST /claim { token } → { token }: open to the network, like the page the
+// QR code leads to; everything else about pairing is on the launch page.
+export function pairingMiddleware(pairing) {
+  return async (request, response, next) => {
+    const { pathname } = new URL(request.url, 'http://localhost')
+    if (pathname !== '/claim') return next()
+    if (request.method !== 'POST') { response.setHeader('Allow', 'POST'); return send(response, 405, { error: 'Method not allowed' }) }
+    try {
+      const device = pairing.claim((await readJson(request))?.token)
+      if (!device) return send(response, 403, { error: 'This pairing code was used or is too old; show a new one on the launch page' })
+      return send(response, 200, { token: device })
+    } catch (error) {
+      return send(response, error.status ?? 500, { error: error.message })
+    }
+  }
+}
+
+export function pairingPlugin(pairing) {
+  return {
+    name: 'vite-plugin-mdeck-pairing',
+    configureServer(server) { server.middlewares.use('/__mdeck/pair', pairingMiddleware(pairing)) },
+  }
+}

package/src/build/pdf.js

@@ -0,0 +1,34 @@
+// Renders a built deck to PDF with a local headless Chrome, using the deck's
+// own print rules: one slide per page at the design size, vector text.
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve, dirname, basename } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { launchChrome, findChrome } from './chrome.js'
+
+export { findChrome }
+
+export async function renderPdf({ htmlFile, output, chrome = findChrome(), timeout = 90000 }) {
+  const html = resolve(htmlFile)
+  const browser = await launchChrome({ dir: dirname(html), chrome, timeout })
+  try {
+    const page = await browser.open(`${encodeURIComponent(basename(html))}?view=deck&embedded=1`)
+    await page.waitForDeck()
+    // Reveal every step and let interactive slides render their final state.
+    await page.evaluate("document.querySelector('deck-stage').printing = true")
+    await delay(300)
+    const { data } = await page.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true, displayHeaderFooter: false, marginTop: 0, marginBottom: 0, marginLeft: 0, marginRight: 0 })
+    writeFileSync(output, Buffer.from(data, 'base64'))
+    return output
+  } finally {
+    await browser.close()
+  }
+}
+
+// Points the share view at the PDF: a relative link for folders, an embedded
+// data URI for single files.
+export function attachPdf(htmlFile, pdfFile, { embed = false } = {}) {
+  const html = readFileSync(htmlFile, 'utf8').replace(/<link rel="alternate" type="application\/pdf"[^>]*>/, '')
+  const href = embed ? `data:application/pdf;base64,${readFileSync(pdfFile).toString('base64')}` : encodeURIComponent(basename(pdfFile))
+  const link = `<link rel="alternate" type="application/pdf" href="${href}">`
+  writeFileSync(htmlFile, html.includes('</head>') ? html.replace('</head>', `${link}</head>`) : link + html)
+}

package/src/build/relayAccess.js

@@ -0,0 +1,85 @@
+import { readFileSync, realpathSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { shareable, resourceKey } from './tunnelClient.js'
+import { collectLocalAssetRefs } from './slidesPlugin.js'
+import { parseSlides } from '../core/parseSlides.js'
+import { sessionCode } from '../live/code.js'
+
+const canonical = file => { try { return realpathSync(file) } catch { return null } }
+
+// Use the entry's import graph, rather than Vite's filesystem allow list.
+// Unrelated files and modules that a local editor loaded stay private.
+export function createRelayAccess(server, slidesPath) {
+  const base = server.config.base
+  const root = server.config.root
+  const graph = server.environments.client.moduleGraph
+  const at = path => `${base}${path.replace(/^\//, '')}`
+  const bootstrap = ['main.jsx', '@vite/client', '@vite/env', '@id/__x00__virtual:prefresh']
+  const knownFiles = new Map()
+  let knownSource = null
+  return async (address, method) => {
+    let source
+    try { source = readFileSync(slidesPath, 'utf8') } catch { return false }
+    if (source !== knownSource) { knownFiles.clear(); knownSource = source }
+    const resources = new Set(bootstrap.map(path => resourceKey(at(path))))
+    const files = new Map()
+    const addFile = (file, address) => {
+      const real = canonical(file)
+      if (!real) return
+      if (!knownFiles.has(file)) knownFiles.set(file, real)
+      if (knownFiles.get(file) !== real) return
+      resources.add(resourceKey(address))
+      files.set(resourceKey(address), { file, real })
+    }
+    const seen = new Set()
+    const visit = mod => {
+      if (!mod || seen.has(mod)) return
+      seen.add(mod)
+      const url = mod.url.startsWith(base) ? mod.url : at(mod.url)
+      if (mod.file && !mod.id?.startsWith('\0')) addFile(mod.file, url)
+      else resources.add(resourceKey(url))
+      if (mod.id?.startsWith('\0')) resources.add(resourceKey(at(`@id/__x00__${mod.id.slice(1)}`)))
+      for (const child of mod.importedModules) visit(child)
+      // Vite rewrites CSS url() references without adding them as JS imports.
+      if (mod.file?.endsWith('.css')) {
+        let css
+        try { css = readFileSync(mod.file, 'utf8') } catch { return }
+        for (const match of css.matchAll(/url\(\s*["']?([^\s"')]+)["']?\s*\)/g)) {
+          const ref = match[1]
+          if (/^(?:[a-z]+:|\/\/|#)/i.test(ref)) continue
+          const file = ref.startsWith('/') ? resolve(root, `.${ref}`) : resolve(dirname(mod.file), ref.split(/[?#]/)[0])
+          addFile(file, at(`@fs/${file.replace(/^\//, '')}`))
+        }
+      }
+    }
+    visit(graph.getModuleById(resolve(root, 'main.jsx')))
+    // The HTML-injected Vite client is a second trusted entry point.
+    visit(await graph.getModuleByUrl(at('@vite/client')))
+    const viteEnv = fileURLToPath(new URL('../client/env.mjs', import.meta.resolve('vite')))
+    addFile(viteEnv, at(`@fs/${viteEnv.replace(/^\//, '')}`))
+    addFile(resolve(root, 'main.jsx'), at('main.jsx'))
+    addFile(resolve(root, 'index.html'), at('index.html'))
+    addFile(fileURLToPath(new URL('../client/client.mjs', import.meta.resolve('vite'))), at('@vite/client'))
+    for (const ref of collectLocalAssetRefs(source)) {
+      // Root-relative assets belong to the deck's public directory.
+      const file = resolve(dirname(slidesPath), ref.replace(/^\//, ''))
+      const path = ref.replace(/^\.\//, '').replace(/^\//, '')
+      addFile(file, at(path))
+      addFile(file, at(`@fs/${file.replace(/^\//, '')}`))
+    }
+    const allowed = shareable(address, method, { base, resources, session: sessionCode(parseSlides(source).deckConfig) })
+    if (!allowed) return false
+    // Recheck symlinks before forwarding, even if Vite cached an older graph.
+    const entry = files.get(resourceKey(address))
+    if (entry && canonical(entry.file) !== entry.real) return false
+    // Vite serves public files ahead of framework modules. A file beside the
+    // deck must not shadow an approved runtime URL and become shareable.
+    const path = decodeURIComponent(new URL(address, 'http://localhost').pathname).slice(base.length)
+    if (path && !path.startsWith('__mdeck/')) {
+      const publicFile = canonical(resolve(dirname(slidesPath), path))
+      if (publicFile && publicFile !== entry?.real) return false
+    }
+    return true
+  }
+}