mdeck 3.2.0 → 3.4.0

package/src/build/renderCheck.js

@@ -0,0 +1,98 @@
+// A deck as it shows, in a real browser: `mdeck check --render` finds slides
+// whose content does not fit, text cut off at the slide's edge or hard to
+// read on what is behind it, and errors the page reports; `mdeck snapshot`
+// saves pictures of slides, so a person or an assistant can look at them.
+// Both build the deck as it is (with the extensions installed here), show
+// every slide with all its steps revealed, as in a PDF, and need Chrome
+// (MDECK_CHROME). The measuring is the theme check's (themeCheck.js).
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, resolve } from 'node:path'
+import { launchChrome } from './chrome.js'
+import { frameworkRoot } from '../paths.js'
+import { parseSlides } from '../core/parseSlides.js'
+import { MEASURE, RECORDER, settle } from './themeCheck.js'
+
+// Each slide's number, line and heading, for messages.
+export function slideLabels(source) {
+  return parseSlides(source).slides.map((slide, index) => {
+    // The slide's first written line, past its settings and blank lines.
+    const body = slide.bodySource ?? slide.source ?? { start: 0, end: 0 }
+    let start = body.start
+    while (/\s/.test(source[start] ?? '') && start < body.end) start++
+    const line = source.slice(0, start).split('\n').length
+    const heading = /^#{1,2}\s+(.+)$/m.exec(slide.content ?? '')?.[1]?.replace(/[*_`]/g, '').trim() ?? null
+    return { number: index + 1, id: slide.id, line, heading }
+  })
+}
+
+// Builds the deck into a temporary folder and opens it in Chrome for
+// `use({ page, count })`, at `appearance` ('' for the deck's own), with every
+// step revealed.
+async function withDeckPage(slidesPath, { appearance = '', width = 1600, height = 900 } = {}, use) {
+  const abs = resolve(slidesPath)
+  const temp = mkdtempSync(resolve(tmpdir(), 'mdeck-render-'))
+  try {
+    try {
+      execFileSync(process.execPath, [resolve(frameworkRoot, 'bin/mdeck.js'), 'build', abs, '-o', resolve(temp, 'out/index.html')], { cwd: dirname(abs), stdio: 'pipe' })
+    } catch (error) {
+      throw new Error(`The deck could not be built: ${String(error.stderr ?? error.message).replace(/\x1b\[[0-9;]*m/g, '').trim().split('\n').slice(-3).join(' ')}`)
+    }
+    const browser = await launchChrome({ dir: resolve(temp, 'out') })
+    try {
+      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${appearance ? `&appearance=${appearance}` : ''}#1` })
+      await page.waitFor("location.href.includes('index.html')")
+      await page.waitForDeck()
+      await page.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false })
+      await page.evaluate("document.querySelector('deck-stage').printing = true")
+      const count = await page.evaluate("document.querySelector('deck-stage').length")
+      return await use({ page, count, show: async index => { await page.evaluate(`window.__index = ${index}; document.querySelector('deck-stage').goTo(${index})`); await settle(page) } })
+    } finally { await browser.close() }
+  } finally { rmSync(temp, { recursive: true, force: true }) }
+}
+
+// The problems of each slide, in the deck's own look, as diagnostics
+// ({ severity, code, message, line }) at the line the slide starts.
+export function renderCheck(slidesPath) {
+  const labels = slideLabels(readFileSync(slidesPath, 'utf8'))
+  return withDeckPage(slidesPath, {}, async ({ page, count, show }) => {
+    const diagnostics = []
+    for (let index = 0; index < count; index++) {
+      await show(index)
+      const label = labels[index] ?? { number: index + 1, line: 1, heading: null }
+      const where = `slide ${label.number}${label.heading ? ` (“${label.heading}”)` : ''}`
+      // Content that does not fit cuts off line after line; the first says which.
+      const problems = await page.evaluate(MEASURE)
+      const cut = problems.filter(problem => problem.endsWith(' is cut off at the edge'))
+      const shown = problems.filter(problem => !cut.includes(problem))
+      if (cut.length) shown.push(cut.length === 1 ? cut[0] : `${cut[0].replace(/ is cut off at the edge$/, '')} and ${cut.length - 1} more ${cut.length === 2 ? 'line is' : 'lines are'} cut off at the edge`)
+      for (const problem of shown) diagnostics.push({ severity: 'warning', code: 'render', message: `${where}: ${problem}`, line: label.line })
+    }
+    // The deck's own warning about content that does not fit is said above, per slide.
+    for (const line of (await page.evaluate('window.__report')).filter(line => !/has more content than fits/.test(line))) diagnostics.push({ severity: line.startsWith('error') ? 'error' : 'warning', code: 'render', message: `the page reported ${line}`, line: 1 })
+    return diagnostics
+  })
+}
+
+// Pictures of slides (numbers from 1; all when none are given) as PNG files
+// in `outDir`, named <deck>-<number>.png. Returns the files written.
+export async function snapshot(slidesPath, { slides = [], outDir, width = 1280, height = 720, appearance = '' } = {}) {
+  const name = basename(slidesPath).replace(/\.md$/i, '')
+  mkdirSync(outDir, { recursive: true })
+  return withDeckPage(slidesPath, { appearance, width, height }, async ({ page, count, show }) => {
+    const wanted = slides.length ? slides : Array.from({ length: count }, (_, i) => i + 1)
+    const files = []
+    for (const number of wanted) {
+      if (number < 1 || number > count) throw new Error(`There is no slide ${number}; the deck has ${count}`)
+      await show(number - 1)
+      const file = resolve(outDir, `${name}-${String(number).padStart(2, '0')}.png`)
+      writeFileSync(file, await page.screenshot({ width, height }))
+      files.push(file)
+    }
+    return files
+  })
+}

package/src/build/resultsPlugin.js

@@ -0,0 +1,77 @@
+// Keeping the answers while `mdeck run` runs: the presenter's screens send
+// each activity's answers as they come in (src/live/client.js), and they go
+// into <deck>.results.json beside the deck (src/core/results.js).
+//
+//   POST /__mdeck/results   { room, closed, answers } → { ok }
+//
+// Answers of none take the room out of the file, as Reset does. Writes wait
+// a moment, so a burst of votes is one write, and do not reload the open
+// windows (ownWrites.js).
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { resultsFileFor, normalizeResults, withRoom, serializeResults } from '../core/results.js'
+import { isAllowedRequest, send, readJson } from './editorPlugin.js'
+import { markOwnWrite } from './ownWrites.js'
+
+export function createResultsFile(deckPath, { debounceMs = 500 } = {}) {
+  const path = resultsFileFor(resolve(deckPath))
+  let results = null, timer = null
+
+  const current = () => {
+    if (results) return results
+    try { results = existsSync(path) ? normalizeResults(JSON.parse(readFileSync(path, 'utf8'))) : normalizeResults({}) }
+    catch { results = normalizeResults({}) }
+    return results
+  }
+
+  function flush() {
+    clearTimeout(timer)
+    timer = null
+    if (!results) return
+    // A deck that never kept answers gets no empty file.
+    if (!Object.keys(results.rooms).length && !existsSync(path)) return
+    const text = serializeResults(results)
+    markOwnWrite(path, text)
+    const temp = `${path}.${process.pid}.tmp`
+    writeFileSync(temp, text, 'utf8')
+    renameSync(temp, path)
+  }
+
+  return {
+    path,
+    read: current,
+    save(room, entry) {
+      results = withRoom(current(), room, entry)
+      clearTimeout(timer)
+      timer = setTimeout(flush, debounceMs)
+    },
+    flush,
+  }
+}
+
+export function resultsMiddleware(file, { authorize = isAllowedRequest } = {}) {
+  return async (request, response, next) => {
+    const { pathname } = new URL(request.url, 'http://localhost')
+    if (pathname !== '/') return next()
+    if (request.method !== 'POST') { response.setHeader('Allow', 'POST'); return send(response, 405, { error: 'Method not allowed' }) }
+    if (!authorize(request)) return send(response, 403, { error: 'Only the presenter keeps the results' })
+    try {
+      const { room, closed, answers } = await readJson(request)
+      file.save(String(room ?? ''), { closed, answers })
+      return send(response, 200, { ok: true })
+    } catch (error) {
+      return send(response, error.status ?? 500, { error: error.message })
+    }
+  }
+}
+
+export function resultsPlugin(slidesPath, { authorize } = {}) {
+  return {
+    name: 'vite-plugin-mdeck-results',
+    configureServer(server) {
+      const file = createResultsFile(slidesPath)
+      server.middlewares.use('/__mdeck/results', resultsMiddleware(file, { authorize }))
+      server.httpServer?.once('close', () => file.flush())
+    },
+  }
+}

package/src/build/slidesPlugin.js

@@ -5,13 +5,15 @@ 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 { stripNotes as stripNotesFrom, stripActivities as stripActivitiesFrom } from '../core/editDeck.js'
 import { componentFolders, componentFiles } from './components.js'
 import { inkFileFor, normalizeInk, emptyInk } from '../core/ink.js'
+import { resultsFileFor, normalizeResults } from '../core/results.js'
 import { isOwnWrite } from './ownWrites.js'
 import { fileURLToPath } from 'node:url'
 import { assertDrawings } from './drawings.js'
 import { marked } from 'marked'
+import { resolveBibliography, sampleBibliography } from './bibliography.js'
 
 const VIRTUAL_ID = 'virtual:slides'
 const RESOLVED_ID = '\0virtual:slides'
@@ -24,6 +26,10 @@ 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 BIB_ID = 'virtual:bibliography'
+const RESOLVED_BIB_ID = '\0virtual:bibliography'
+const RESULTS_ID = 'virtual:deck-results'
+const RESOLVED_RESULTS_ID = '\0virtual:deck-results'
 
 const MIME_BY_EXT = {
   '.png': 'image/png',
@@ -136,6 +142,8 @@ export function collectLocalAssetRefs(markdown) {
         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])
+          // Markdown pictures in a tag's attributes, such as a poll's options.
+          for (const match of token.text.matchAll(/!\[[^\]]*\]\(([^)\s]+)/g)) add(match[1])
         }
       })
     }
@@ -213,12 +221,16 @@ export function deckLookOnly(registry, deckConfig = {}) {
 // 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 } = {}) {
+export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = false, editor = false, stripNotes = false, stripActivities = false, ink = true, results = 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 sourceFor = raw => {
+    const shared = stripNotes ? stripNotesFrom(raw) : raw
+    return stripActivities ? stripActivitiesFrom(shared).source : shared
+  }
   const inkPath = inkFileFor(abs)
+  const resultsPath = resultsFileFor(abs)
   const extensionDirs = extensionRoots(abs).map(root => root.dir)
   let componentDirs = componentFolders(abs, readDeck()).map(folder => folder.dir)
   const watchDirs = () => [...extensionDirs, ...componentDirs]
@@ -233,8 +245,18 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
     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 ALL_IDS = [RESOLVED_ID, RESOLVED_COMPONENTS_ID, RESOLVED_EXTENSIONS_ID, RESOLVED_INK_ID, RESOLVED_SVGS_ID, RESOLVED_BIB_ID]
+  const SOURCE_IDS = [RESOLVED_ID, RESOLVED_INK_ID, RESOLVED_SVGS_ID, RESOLVED_BIB_ID]
+  // The reference files (and .csl style) the deck names, from the last load.
+  let bibFiles = []
+  // The dev and edit servers also show the sample deck (?sample=1, the
+  // design page), with its references from memory; builds never do.
+  let serving = false
+  // The editor keeps its page: the formatted references arrive as a hot update.
+  const bibUpdate = server => {
+    const mod = server.moduleGraph.getModuleById(RESOLVED_BIB_ID)
+    return editor && mod ? [mod] : []
+  }
   const invalidate = (server, ids) => {
     for (const id of ids) {
       const mod = server.moduleGraph.getModuleById(id)
@@ -249,6 +271,7 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
 
   return {
     name: 'vite-plugin-slides',
+    configResolved(config) { serving = config.command === 'serve' },
     configureServer(server) {
       server.watcher.add([abs, inkPath, ...watchDirs()])
       const refresh = file => {
@@ -266,6 +289,8 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
       if (id === EXTENSIONS_ID) return RESOLVED_EXTENSIONS_ID
       if (id === INK_ID) return RESOLVED_INK_ID
       if (id === SVGS_ID) return RESOLVED_SVGS_ID
+      if (id === BIB_ID) return RESOLVED_BIB_ID
+      if (id === RESULTS_ID) return RESOLVED_RESULTS_ID
     },
     load(id) {
       if (id === RESOLVED_ID) {
@@ -295,14 +320,44 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
         if (ink && existsSync(inkPath)) {
           try { data = normalizeInk(JSON.parse(readFileSync(inkPath, 'utf-8')), size) } catch (error) { this.warn(`${inkPath}: ${error.message}; showing no ink`) }
         }
+        // Without the activity slides, drawings follow their slides to their new ids.
+        if (stripActivities) {
+          try {
+            const { ids, removed } = stripActivitiesFrom(readDeck())
+            const gone = new Set(removed)
+            data = { ...data, slides: Object.fromEntries(Object.entries(data.slides).filter(([id]) => !gone.has(id)).map(([id, strokes]) => [ids[id] ?? id, strokes])) }
+          } catch {}
+        }
         return `export default ${JSON.stringify(data)}\nexport const inkFileName = ${JSON.stringify(basename(inkPath))}`
       }
+      // The answers kept in the talk (<deck>.results.json): builds show them
+      // where no room server is (src/live/client.js). `mdeck run` shows the
+      // live answers, and writes the file, so it does not read it here.
+      if (id === RESOLVED_RESULTS_ID) {
+        let data = normalizeResults({})
+        if (results && !serving && existsSync(resultsPath)) {
+          try { data = normalizeResults(JSON.parse(readFileSync(resultsPath, 'utf-8'))) } catch (error) { this.warn(`${resultsPath}: ${error.message}; showing no results`) }
+        }
+        return `export default ${JSON.stringify(data)}`
+      }
       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])))}`
       }
+      // The deck's citations and references, formatted with citeproc here so
+      // that none of it travels in the deck (bibliography.js).
+      if (id === RESOLVED_BIB_ID) {
+        watchDeck(this)
+        const data = bibliography => bibliography && { ids: bibliography.ids, clusters: bibliography.clusters, singles: bibliography.singles, entries: bibliography.entries, order: bibliography.order }
+        return Promise.all([resolveBibliography(abs, sourceFor(readDeck()), { sample: serving }), serving ? sampleBibliography() : null]).then(([bibliography, sample]) => {
+          bibFiles = bibliography ? [...bibliography.files, bibliography.style].filter(Boolean) : []
+          for (const file of bibFiles) if (existsSync(file)) this.addWatchFile(file)
+          if (bibliography?.diagnostics.length) this.warn(bibliography.diagnostics.map(d => d.message).join('\n'))
+          return `export default ${JSON.stringify(data(bibliography))}\nexport const sample = ${JSON.stringify(data(sample))}`
+        })
+      }
       if (id === RESOLVED_EXTENSIONS_ID) {
         const registry = loadRegistry(abs)
         for (const record of registry.records) this.addWatchFile(record.file)
@@ -347,15 +402,23 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
       }
       // 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.
+      // The results file is written during the talk and read only by builds.
+      if (changed === resultsPath) return []
       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 []
+        return changed === abs ? bibUpdate(server) : []
       }
       if (changed === inkPath) {
         reload(server, [RESOLVED_INK_ID], changed)
         return []
       }
+      if (bibFiles.includes(changed)) {
+        invalidate(server, [RESOLVED_BIB_ID])
+        if (editor) return bibUpdate(server)
+        server.ws.send({ type: 'full-reload' })
+        return []
+      }
       if (changed === abs) {
         if (followComponentFolders(server)) {
           reload(server, ALL_IDS, changed)
@@ -363,7 +426,7 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
         }
         // The deck sets the ink's design size and which SVGs are inlined.
         invalidate(server, SOURCE_IDS)
-        if (editor) return []
+        if (editor) return bibUpdate(server)
         server.ws.send({ type: 'full-reload' })
       }
     },

package/src/build/themeCheck.js

@@ -10,17 +10,17 @@ 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'
+import { sampleDeck, SAMPLE_PICTURE, SAMPLE_REFERENCES, SAMPLE_REFERENCES_FILE } from '../editor/sampleDeck.js'
 import { loadRegistry } from '../extensions/discover.js'
 
 // Runs in the page before the deck: keeps what the page reports.
-const RECORDER = `window.__report = [];
+export 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 = `(() => {
+export const MEASURE = `(() => {
   const slide = document.querySelector('deck-stage').querySelectorAll(':scope > section')[window.__index]
   const problems = []
   const frame = slide.getBoundingClientRect()
@@ -71,7 +71,9 @@ const MEASURE = `(() => {
     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')
+    // Text in a box that scrolls (a component's long list) is meant to be out of view.
+    const scrolls = node => { for (; node && node !== slide; node = node.parentElement) if (/auto|scroll/.test(getComputedStyle(node).overflowY + getComputedStyle(node).overflowX)) return true; return false }
+    if (!scrolls(element) && (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)
@@ -89,6 +91,7 @@ export function buildSampleDeck({ extensions = {}, outDir }) {
   try {
     writeFileSync(resolve(temp, 'slides.md'), sampleDeck())
     writeFileSync(resolve(temp, 'picture.svg'), SAMPLE_PICTURE)
+    writeFileSync(resolve(temp, SAMPLE_REFERENCES_FILE), SAMPLE_REFERENCES)
     // Keyed by id, or by "kind:id" to keep a theme and a palette of one name apart.
     for (const [key, dir] of Object.entries(extensions)) cpSync(dir, resolve(temp, 'extensions', ...key.split(':').map((part, i, all) => all.length > 1 && i === 0 ? `${part}s` : part)), { recursive: true })
     mkdirSync(resolve(temp, 'home'))
@@ -120,7 +123,7 @@ export async function withSampleDeck({ extensions = {} } = {}, use) {
   } finally { rmSync(temp, { recursive: true, force: true }) }
 }
 
-const settle = page => page.evaluate('new Promise(done => requestAnimationFrame(() => requestAnimationFrame(() => setTimeout(done, 60))))')
+export 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.

package/src/cli/args.js

@@ -1,7 +1,7 @@
 // Parse the entire command before it can start a server or change any files.
 const value = 'value', flag = 'flag', optional = 'optional'
 const common = { '--port': value, '--no-open': flag }
-const output = { '--output': value, '-o': '--output', '--no-drawings': flag }
+const output = { '--output': value, '-o': '--output', '--no-drawings': flag, '--no-results': flag }
 const commands = {
   new: { max: 0 },
   run: { ...common, '--network': flag, '--server': optional, max: 1 },
@@ -9,17 +9,19 @@ const commands = {
   design: { ...common, max: 1 },
   themes: { '--local': flag, '--force': flag, '--check': flag, '--output': value, '-o': '--output', max: 4 },
   palettes: { '--local': flag, '--force': flag, max: 4 },
-  build: { ...output, '--single-file': flag, '--launchers': flag, '--reader': flag, '--notes': flag, max: 1 },
-  send: { ...output, '--notes': flag, '--no-pdf': flag, max: 1 },
-  pdf: { ...output, max: 1 },
+  build: { ...output, '--single-file': flag, '--launchers': flag, '--reader': flag, '--notes': flag, '--no-polls': flag, max: 1 },
+  send: { ...output, '--notes': flag, '--no-polls': flag, '--no-pdf': flag, max: 1 },
+  pdf: { ...output, '--no-polls': flag, max: 1 },
   preview: { ...common, max: 1 },
-  check: { '--strict': flag, max: 1 },
+  check: { '--strict': flag, '--render': flag, max: 1 },
+  snapshot: { '--output': value, '-o': '--output', '--slide': value, '--dark': flag, '--light': flag, max: 1 },
   list: { '--json': flag, max: 2 },
   starter: { max: 2 },
   docs: { ...common, '--build': flag, max: 1 },
   server: { '--port': value, '--host': optional, max: 0 },
   skill: { '--print': flag, '--install': 'list', '--project': flag, max: 0 },
   migrate: { '--dry-run': flag, max: 1 },
+  results: { '--output': value, '-o': '--output', max: 1 },
 }
 
 export function validateServerOrigin(address) {
@@ -28,6 +30,19 @@ export function validateServerOrigin(address) {
   if (!url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('--server needs an http:// or https:// server origin, for example https://slides.example.org')
 }
 
+// Slide numbers from "3", "3,5" or "2-4": in order, each once.
+export function parseSlideNumbers(text) {
+  const numbers = []
+  for (const part of String(text).split(',').map(part => part.trim()).filter(Boolean)) {
+    const range = /^(\d+)(?:-(\d+))?$/.exec(part)
+    if (!range) throw new Error(`--slide takes slide numbers such as 3, 3,5 or 2-4, not "${part}"`)
+    const [from, to] = [Number(range[1]), Number(range[2] ?? range[1])]
+    if (!from || to < from) throw new Error(`--slide takes slide numbers from 1, with the smaller one first: not "${part}"`)
+    for (let n = from; n <= to; n++) if (!numbers.includes(n)) numbers.push(n)
+  }
+  return numbers
+}
+
 export function parseArgs(command, argv) {
   const schema = commands[command]
   if (!schema) throw new Error(`Unknown command: "${command}"`)
@@ -70,8 +85,10 @@ export function parseArgs(command, argv) {
     validateServerOrigin(options['--server'])
   }
   if (command === 'build' && options['--notes'] && !options['--reader']) throw new Error('--notes requires --reader for mdeck build')
+  if (command === 'build' && options['--no-polls'] && !options['--reader']) throw new Error('--no-polls requires --reader for mdeck build')
   if (command === 'build' && options['--launchers'] && options['--single-file']) throw new Error('--launchers is only available for folders, not with --single-file.')
   if (command === 'list' && positionals.length === 2 && !['layouts', 'themes', 'palettes'].includes(positionals[0])) throw new Error('Use mdeck list [layouts|themes|palettes] [slides.md]')
+  if (command === 'snapshot' && options['--dark'] && options['--light']) throw new Error('Choose --dark or --light')
   if (command === 'skill' && options['--print'] && options['--install']) throw new Error('Choose --print or --install')
   return { options, positionals }
 }

package/src/cli/index.js

@@ -1,5 +1,5 @@
 import { createServer, build, preview } from 'vite'
-import { existsSync, copyFileSync, mkdtempSync, readFileSync, statSync } from 'fs'
+import { existsSync, copyFileSync, mkdtempSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { chmod, rm, mkdir, writeFile } from 'fs/promises'
 import { resolve, dirname, basename, relative, isAbsolute } from 'path'
 import { tmpdir } from 'os'
@@ -12,9 +12,10 @@ import { loadRegistry, manifestsOf, serializeRegistry } from '../extensions/disc
 import { BACKUP_DIR } from '../build/editorPlugin.js'
 import { createEditorServer, createDesignServer } from '../build/editorServer.js'
 import { homePlugin } from '../build/homePlugin.js'
-import { checkDeck } from '../build/check.js'
+import { checkDeck, bibliographyDiagnostics } from '../build/check.js'
 import { livePlugin, startLiveServer } from '../live/server.js'
 import { inkPlugin } from '../build/inkPlugin.js'
+import { resultsPlugin } from '../build/resultsPlugin.js'
 import { createPairing, pairingPlugin } from '../build/pairing.js'
 import { isAllowedRequest } from '../build/editorPlugin.js'
 import { renderPdf, attachPdf, findChrome } from '../build/pdf.js'
@@ -24,9 +25,10 @@ import { ManifestError, KINDS } from '../extensions/manifest.js'
 
 import { frameworkRoot } from '../paths.js'
 import { parseSlides } from '../core/parseSlides.js'
-import { stripNotes as stripNotesFrom } from '../core/editDeck.js'
-import { parseArgs, validateServerOrigin } from './args.js'
+import { stripNotes as stripNotesFrom, stripActivities as stripActivitiesFrom } from '../core/editDeck.js'
+import { parseArgs, parseSlideNumbers, validateServerOrigin } from './args.js'
 import { assertDrawings } from '../build/drawings.js'
+import { resultsFileFor, normalizeResults, resultsCsv } from '../core/results.js'
 import { createRelayAccess } from '../build/relayAccess.js'
 import { sessionCode } from '../live/code.js'
 import { migrateDeck } from './migrate.js'
@@ -178,12 +180,13 @@ async function runNewWizard() {
   }
 }
 
-async function copyLocalAssets(slidesPath, outDir, { stripNotes = false } = {}) {
+async function copyLocalAssets(slidesPath, outDir, { stripNotes = false, stripActivities = false } = {}) {
   const absSlides = resolve(slidesPath)
   const deckDir = dirname(absSlides)
   const absOutDir = resolve(outDir)
   const raw = readFileSync(absSlides, 'utf-8')
-  const markdown = stripNotes ? stripNotesFrom(raw) : raw
+  let markdown = stripNotes ? stripNotesFrom(raw) : raw
+  if (stripActivities) markdown = stripActivitiesFrom(markdown).source
 
   for (const ref of collectLocalAssetRefs(markdown)) {
     const source = resolve(deckDir, ref)
@@ -320,20 +323,28 @@ const HELP = `
 
   ${c.dim}Make something to hand out${c.reset}
     ${c.green}mdeck build${c.reset} [slides.md] [-o dir/index.html]   A folder to host
-      --reader               reader view, notes removed unless --notes
+      --reader               reader view, notes removed unless --notes, polls kept as a record unless --no-polls
       --single-file          everything inlined into one file instead
       --launchers            add macOS/Linux and Windows launchers (folders only)
     ${c.green}mdeck send${c.reset} [slides.md] [-o talk.html]     One file to send: the reader view, speaker notes removed,
                                               with a PDF inside
       --notes                keep the speaker notes in the file
+      --no-polls             for send, build --reader and pdf: leave out the slides with polls and join codes
       --no-pdf               do not render the PDF inside
     ${c.green}mdeck pdf${c.reset} [slides.md] [-o talk.pdf]       A PDF, one page per slide
       --no-drawings          for build, send and pdf: leave out <slides>.drawings.json
+      --no-results           for build, send and pdf: leave out <slides>.results.json (the answers kept in the talk)
     ${c.green}mdeck preview${c.reset} [folder]                    Preview a built folder (default: dist)
 
   ${c.dim}Check and look things up${c.reset}
     ${c.green}mdeck migrate${c.reset} [slides.md] [--dry-run]   Update settings, local layouts and drawings to API 2.0
     ${c.green}mdeck check${c.reset} [slides.md] [--strict]        Validate source and local assets
+      --render               also show every slide in Chrome, all steps revealed: content that
+                             does not fit, text cut off or hard to read, errors on the page
+    ${c.green}mdeck snapshot${c.reset} [slides.md]                Pictures of slides as PNG files (default: .mdeck-snapshots/)
+      --slide <numbers>      only these slides: 3, 3,5 or 2-4
+      --dark | --light       in this appearance instead of the deck's own   -o <folder>
+    ${c.green}mdeck results${c.reset} [slides.md] [-o answers.csv]  The answers kept in the talk, as CSV (room, phone, time, answer)
     ${c.green}mdeck list${c.reset} [layouts|themes|palettes] [slides.md] [--json]
                                               List built-in and deck-local layouts, themes and palettes
     ${c.green}mdeck starter${c.reset} <layout> [slides.md]        Print starter Markdown for a layout
@@ -459,15 +470,42 @@ if (command === 'new') {
     else if (hasFlag('--dry-run')) tip('No files changed. Run without --dry-run to apply these changes.')
   } catch (error) { err(error.message); process.exitCode = 1 }
 
+} else if (command === 'results') {
+  const input = requireInput('results')
+  const file = resultsFileFor(resolve(input))
+  if (!existsSync(file)) { err(`No answers kept for ${basename(input)} yet: ${basename(file)} appears beside it once people answer during mdeck run.`); process.exit(1) }
+  let csv
+  try { csv = resultsCsv(normalizeResults(JSON.parse(readFileSync(file, 'utf8')))) } catch (error) { err(`${basename(file)}: ${error.message}`); process.exit(1) }
+  const out = outputOption()
+  if (out) { writeFileSync(out, csv); ok(`Saved ${relative(process.cwd(), resolve(out))}`) }
+  else process.stdout.write(csv)
 } else if (command === 'check') {
   const input = requireInput('check')
   const registry = registryFor(input)
   const { diagnostics } = checkDeck(input, registry)
+  diagnostics.push(...await bibliographyDiagnostics(input))
+  if (hasFlag('--render') && !diagnostics.some(d => d.severity === 'error')) {
+    tip('Building the deck and looking at every slide in Chrome…')
+    try {
+      const { renderCheck } = await import('../build/renderCheck.js')
+      diagnostics.push(...await renderCheck(input))
+    } catch (error) { diagnostics.push({ severity: 'error', code: 'render', message: error.message, line: 1 }) }
+  }
   if (diagnostics.length) console.log(formatDiagnostics(diagnostics, input))
   const warned = diagnostics.length || registry.warnings.length
   if (diagnostics.some(d => d.severity === 'error') || (warned && hasFlag('--strict'))) process.exitCode = 1
   else ok(`Checked ${input}${warned ? ' (with warnings)' : ''}`)
 
+} else if (command === 'snapshot') {
+  const input = requireInput('snapshot')
+  try {
+    const slides = parseSlideNumbers(parsed.options['--slide'] ?? '')
+    const outDir = resolve(outputOption() ?? resolve(dirname(resolve(input)), '.mdeck-snapshots'))
+    const appearance = hasFlag('--dark') ? 'dark' : hasFlag('--light') ? 'light' : ''
+    const { snapshot } = await import('../build/renderCheck.js')
+    for (const file of await snapshot(input, { slides, outDir, appearance })) console.log(relative(process.cwd(), file))
+  } catch (error) { err(error.message); process.exitCode = 1 }
+
 } else if (command === 'list') {
   const KIND_WORDS = { layouts: 'layout', themes: 'theme', palettes: 'palette' }
   const [first, ...others] = positionals()
@@ -537,7 +575,7 @@ if (command === 'new') {
     ...base,
     // A paired iPad may save ink and steer the rooms, like this computer.
     ...(relay ? { base: relay.base } : {}),
-    plugins: [...(relay ? [stripRelayBase(relay.base)] : []), ...base.plugins, homePlugin(abs, { services, pairing, relay, server: relay?.server ?? null }), pairingPlugin(pairing), livePlugin({ pairing, upstream, key: process.env.MDECK_SERVER_KEY, session: () => sessionCode(parseSlides(readFileSync(abs, 'utf8')).deckConfig) }), inkPlugin(abs, { authorize: request => isAllowedRequest(request) || pairing.allows(request) })],
+    plugins: [...(relay ? [stripRelayBase(relay.base)] : []), ...base.plugins, homePlugin(abs, { services, pairing, relay, server: relay?.server ?? null }), pairingPlugin(pairing), livePlugin({ pairing, upstream, key: process.env.MDECK_SERVER_KEY, session: () => sessionCode(parseSlides(readFileSync(abs, 'utf8')).deckConfig) }), inkPlugin(abs, { authorize: request => isAllowedRequest(request) || pairing.allows(request) }), resultsPlugin(abs, { authorize: request => isAllowedRequest(request) || pairing.allows(request) })],
     publicDir: dirname(abs),
     server: {
       ...base.server,
@@ -578,7 +616,8 @@ if (command === 'new') {
   ok(`Launch page: ${c.cyan}${new URL('home.html', local).href}${c.reset}`)
   tip(`Presenter:   ${new URL('?view=presenter', local).href}`)
   tip(`Audience:    ${new URL('?view=audience', local).href}`)
-  if (exposed) for (const url of server.resolvedUrls.network) tip(`On a phone:  ${new URL('?view=reader', url).href}`)
+  // Phones in the room follow the talk (the reader view would show slides ahead).
+  if (exposed) for (const url of server.resolvedUrls.network) tip(`Follow:      ${new URL('?view=follow', url).href}`)
   console.log()
   if (relay) tip(`iPad:        choose "Show pairing code" on the launch page; it opens ${relay.url}`)
   ok(`Watching ${c.cyan}${abs}${c.reset}`)
@@ -645,6 +684,8 @@ if (command === 'new') {
   const launchers = !sending && hasFlag('--launchers')
   const reader = sending || hasFlag('--reader')
   const stripNotes = reader && !hasFlag('--notes')
+  // Polls show as a record of the talk; --no-polls leaves their slides and join codes out.
+  const stripActivities = reader && hasFlag('--no-polls')
   const wantPdf = sending && !hasFlag('--no-pdf')
 
   if (!hasFlag('--no-drawings')) { try { assertDrawings(input) } catch (error) { err(error.message); process.exit(1) } }
@@ -659,7 +700,7 @@ if (command === 'new') {
   try {
     await build({
       ...baseConfig(input, { selfContained, defaultView: reader ? 'reader' : 'deck' }),
-      plugins: [preact(), slidesPlugin(resolve(input), { inlineImages: selfContained, inlineMedia: selfContained, embedFonts: selfContained, stripNotes, ink: !hasFlag('--no-drawings'), deckLook: reader }), viteSingleFile()],
+      plugins: [preact(), slidesPlugin(resolve(input), { inlineImages: selfContained, inlineMedia: selfContained, embedFonts: selfContained, stripNotes, stripActivities, ink: !hasFlag('--no-drawings'), results: !hasFlag('--no-results'), deckLook: reader }), viteSingleFile()],
       build: {
         outDir,
         emptyOutDir: !tempDir,
@@ -677,7 +718,7 @@ if (command === 'new') {
   await mkdir(finalOutDir, { recursive: true })
 
   if (!selfContained) {
-    await copyLocalAssets(input, finalOutDir, { stripNotes })
+    await copyLocalAssets(input, finalOutDir, { stripNotes, stripActivities })
     if (launchers) await writePresenterLaunchers(finalOutDir, htmlFilename)
   }
 
@@ -701,6 +742,7 @@ if (command === 'new') {
     } finally { await rm(pdfDir, { recursive: true, force: true }) }
   }
   if (stripNotes) tip('Speaker notes were removed from this file (use --notes to keep them).')
+  if (stripActivities && stripActivitiesFrom(readFileSync(resolve(input), 'utf-8')).removed.length) tip('Slides with polls were left out (--no-polls).')
   ok(`${sending ? 'Made' : 'Built'}: ${c.cyan}${htmlFile}${c.reset}${reader ? ' — opens in the reader view' : ''}${selfContained ? ' (single file)' : ' + local assets'}\n`)
 
 // ── skill ─────────────────────────────────────────────────────────────────────
@@ -730,7 +772,7 @@ if (command === 'new') {
   try {
     await build({
       ...baseConfig(input, { selfContained: true }),
-      plugins: [preact(), slidesPlugin(resolve(input), { inlineImages: true, inlineMedia: true, embedFonts: true, ink: !hasFlag('--no-drawings'), deckLook: true }), viteSingleFile()],
+      plugins: [preact(), slidesPlugin(resolve(input), { inlineImages: true, inlineMedia: true, embedFonts: true, stripActivities: hasFlag('--no-polls'), ink: !hasFlag('--no-drawings'), results: !hasFlag('--no-results'), deckLook: true }), viteSingleFile()],
       build: { outDir: tempDir, emptyOutDir: true, target: 'esnext', assetsInlineLimit: 100 * 1024 * 1024 },
       logLevel: 'warn',
     })