mdeck 3.1.0 → 3.3.0

package/src/build/bibliography.js

@@ -0,0 +1,289 @@
+import { readFileSync, statSync } from 'fs'
+import { resolve, dirname, extname } from 'path'
+import yaml from 'js-yaml'
+import { parseSlides } from '../core/parseSlides.js'
+import { scanCitations, citedKeys } from '../core/citations.js'
+
+// The deck's references, formatted here in Node with citeproc so that none of
+// it travels in the deck: the page receives finished HTML for every citation
+// as written, the full entry of every cited work, and the reference list.
+//
+// Reference files: BibTeX/BibLaTeX (.bib), CSL-JSON (.json), and YAML (.yml,
+// .yaml) holding either Hayagriva (Typst's format, a map of entries) or
+// CSL-YAML (a list of entries with ids).
+
+export const bibliographyFiles = (deckPath, deckConfig = {}) =>
+  [deckConfig.bibliography ?? []].flat().filter(file => typeof file === 'string' && file).map(file => resolve(dirname(resolve(deckPath)), file))
+
+export const styleFile = (deckPath, deckConfig = {}) =>
+  typeof deckConfig.csl === 'string' && /\.csl$/i.test(deckConfig.csl) ? resolve(dirname(resolve(deckPath)), deckConfig.csl) : null
+
+// ─── Reading reference files ──────────────────────────────────────────────
+
+const parsed = new Map()
+
+async function readItems(file) {
+  const { mtimeMs } = statSync(file)
+  const cached = parsed.get(file)
+  if (cached?.mtimeMs === mtimeMs) return cached.items
+  const text = readFileSync(file, 'utf-8')
+  const ext = extname(file).toLowerCase()
+  let items
+  if (ext === '.json') items = JSON.parse(text)
+  else if (ext === '.yml' || ext === '.yaml') {
+    // The core schema keeps dates as written (2003-06-21), not as Date objects.
+    const doc = yaml.load(text, { schema: yaml.CORE_SCHEMA })
+    items = Array.isArray(doc) ? doc : hayagrivaToCsl(doc ?? {})
+  } else if (ext === '.bib' || ext === '.bibtex') {
+    const { Cite } = await import('@citation-js/core')
+    await import('@citation-js/plugin-bibtex')
+    items = new Cite(text, { forceType: '@biblatex/text' }).data
+  } else throw new Error(`unknown reference format "${ext}" (use .bib, .json or .yml)`)
+  if (!Array.isArray(items)) throw new Error('expected a list of references')
+  items = items.filter(item => item && item.id != null).map(item => ({ ...item, id: String(item.id) }))
+  parsed.set(file, { mtimeMs, items })
+  return items
+}
+
+export async function loadBibliography(files) {
+  const items = []
+  const seen = new Set()
+  const diagnostics = []
+  for (const file of files) {
+    let found
+    try { found = await readItems(file) } catch (error) {
+      diagnostics.push({ severity: 'warning', code: 'bibliography-file', message: error.code === 'ENOENT' ? `Bibliography ${file} not found` : `Bibliography ${file}: ${error.message}` })
+      continue
+    }
+    for (const item of found) {
+      if (seen.has(item.id)) { diagnostics.push({ severity: 'warning', code: 'bibliography-duplicate', message: `Reference "${item.id}" appears twice; using the first (${file})` }); continue }
+      seen.add(item.id)
+      items.push(item)
+    }
+  }
+  return { items, diagnostics }
+}
+
+// ─── Hayagriva → CSL-JSON ─────────────────────────────────────────────────
+
+const text = value => value == null ? undefined : typeof value === 'object' && !Array.isArray(value) ? text(value.value) : String(value)
+
+function person(value) {
+  if (value && typeof value === 'object') {
+    return { family: value.name, given: value['given-name'], 'non-dropping-particle': value.prefix, suffix: value.suffix }
+  }
+  const parts = String(value).split(',').map(part => part.trim())
+  if (parts.length === 1) return { literal: parts[0] }
+  const [family, given, suffix] = parts
+  const particle = family.match(/^((?:[a-z]+\s+)+)(.+)$/)
+  return particle ? { 'non-dropping-particle': particle[1].trim(), family: particle[2], given, suffix } : { family, given, suffix }
+}
+const people = value => value == null ? undefined : [value].flat().map(person)
+
+function date(value) {
+  if (value == null) return undefined
+  const parts = String(value).match(/^(-?\d{1,4})(?:-(\d{1,2}))?(?:-(\d{1,2}))?/)
+  return parts ? { 'date-parts': [parts.slice(1).filter(Boolean).map(Number)] } : { literal: String(value) }
+}
+
+const kind = value => String(value ?? 'misc').toLowerCase()
+
+function cslType(type, parentType) {
+  if (type === 'article') return { periodical: 'article-journal', newspaper: 'article-newspaper', proceedings: 'paper-conference', conference: 'paper-conference', blog: 'post-weblog', web: 'webpage', book: 'chapter', anthology: 'chapter' }[parentType] ?? 'article-journal'
+  return {
+    book: 'book', anthology: 'book', proceedings: 'book', chapter: 'chapter', anthos: 'chapter', thesis: 'thesis', report: 'report',
+    web: 'webpage', blog: 'post-weblog', thread: 'post', video: 'motion_picture', audio: 'song', repository: 'software',
+    patent: 'patent', case: 'legal_case', legislation: 'legislation', manuscript: 'manuscript', newspaper: 'article-newspaper',
+    periodical: 'periodical', reference: 'entry-encyclopedia', entry: 'entry', artwork: 'graphic', performance: 'performance',
+    exhibition: 'event', conference: 'event', original: 'document', misc: 'document',
+  }[type] ?? 'document'
+}
+
+function publisher(value) {
+  if (value == null) return {}
+  if (typeof value === 'object') return { publisher: text(value.name), 'publisher-place': text(value.location) }
+  return { publisher: String(value) }
+}
+
+const clean = object => Object.fromEntries(Object.entries(object).filter(([, value]) => value != null && value !== '' && !(Array.isArray(value) && !value.length)))
+
+export function hayagrivaToCsl(doc) {
+  return Object.entries(doc).map(([id, entry]) => {
+    entry ??= {}
+    const parent = [entry.parent ?? []].flat()[0] ?? {}
+    const serial = { ...(typeof parent['serial-number'] === 'object' ? parent['serial-number'] : {}), ...(typeof entry['serial-number'] === 'object' ? entry['serial-number'] : {}) }
+    const url = entry.url ?? parent.url
+    return clean({
+      id,
+      type: cslType(kind(entry.type), parent.type ? kind(parent.type) : undefined),
+      title: text(entry.title),
+      'title-short': typeof entry.title === 'object' ? text(entry.title.short) : undefined,
+      author: people(entry.author),
+      editor: people(entry.editor ?? parent.editor),
+      translator: people(entry.translator),
+      issued: date(entry.date ?? parent.date),
+      'container-title': text(parent.title),
+      'collection-title': text([parent.parent ?? []].flat()[0]?.title),
+      volume: text(entry.volume ?? parent.volume),
+      issue: text(entry.issue ?? parent.issue),
+      page: text(entry['page-range'] ?? parent['page-range']),
+      edition: text(entry.edition ?? parent.edition),
+      ...publisher(entry.publisher ?? parent.publisher),
+      'publisher-place': text(entry.location ?? parent.location) ?? publisher(entry.publisher ?? parent.publisher)['publisher-place'],
+      genre: text(entry.genre),
+      'event-title': kind(parent.type) === 'conference' ? text(parent.title) : undefined,
+      DOI: text(serial.doi),
+      ISBN: text(serial.isbn),
+      ISSN: text(serial.issn),
+      PMID: text(serial.pmid),
+      number: typeof entry['serial-number'] === 'string' ? entry['serial-number'] : undefined,
+      URL: text(url),
+      accessed: typeof url === 'object' ? date(url.date) : undefined,
+      language: text(entry.language),
+      note: text(entry.note),
+      abstract: text(entry.abstract),
+      ...(entry.organization && !entry.publisher ? { publisher: text(entry.organization) } : {}),
+    })
+  })
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────
+
+// The texts a deck shows, in the order the audience sees them: each slide's
+// regions, then its notes. The runtime renders citations in the same texts.
+export function deckTexts(source) {
+  const { slides } = parseSlides(source)
+  const position = region => region.source?.start ?? region.ranges?.[0]?.start ?? 0
+  return slides.flatMap(slide => [
+    ...Object.values(slide.regions ?? { body: { content: slide.content } }).sort((a, b) => position(a) - position(b)).map(region => region.content ?? ''),
+    slide.meta?.notes ?? '',
+  ])
+}
+
+function pickLocale(lang, available) {
+  if (!lang) return 'en-US'
+  const wanted = String(lang).replace('_', '-')
+  const exact = available.find(id => id.toLowerCase() === wanted.toLowerCase())
+  if (exact) return exact
+  const language = wanted.split('-')[0].toLowerCase()
+  return available.find(id => id.toLowerCase().startsWith(language + '-')) ?? null
+}
+
+// A name for a narrative citation when the style has no author-only form
+// (numeric styles): Smith, Smith and Doe, Smith et al.
+function namesOf(item) {
+  const names = (item.author ?? item.editor ?? []).map(name => name.family ?? name.literal).filter(Boolean)
+  if (!names.length) return item['title-short'] ?? item.title ?? item.id
+  if (names.length === 1) return names[0]
+  if (names.length === 2) return `${names[0]} & ${names[1]}`
+  return `${names[0]} et al.`
+}
+
+const toCiteItem = item => clean({ id: item.id, locator: item.locator, label: item.locator ? item.label : undefined, prefix: item.prefix, suffix: item.suffix, 'suppress-author': item.suppressAuthor || undefined })
+
+// `{ ids, clusters, singles, entries, order, diagnostics }`: `clusters` maps
+// each citation as written to its HTML; `singles` and `entries` map keys to a
+// one-work citation and to the full reference; `order` is the reference list.
+export async function formatBibliography({ items, texts, csl, lang, nocite = [], deckDir = '.' }) {
+  const diagnostics = []
+  const byId = new Map(items.map(item => [item.id, item]))
+  const result = { ids: [...byId.keys()], clusters: {}, singles: {}, entries: {}, order: [], diagnostics }
+
+  const clusters = texts.flatMap(text => scanCitations(text, { isKey: id => byId.has(id) }))
+  const unknown = new Set(clusters.flatMap(cluster => cluster.items.map(item => item.id)).filter(id => !byId.has(id)))
+  for (const id of unknown) diagnostics.push({ severity: 'warning', code: 'citation-unknown', message: `Citation @${id} is not in the bibliography` })
+
+  const wanted = [nocite].flat().map(id => String(id).replace(/^@/, ''))
+  const uncited = wanted.includes('*') ? [...byId.keys()] : wanted.filter(id => {
+    if (byId.has(id)) return true
+    diagnostics.push({ severity: 'warning', code: 'citation-unknown', message: `nocite: ${id} is not in the bibliography` })
+    return false
+  })
+  if (!clusters.length && !uncited.length) return result
+
+  const { plugins } = await import('@citation-js/core')
+  await import('@citation-js/plugin-csl')
+  const { default: CSL } = await import('citeproc')
+  const config = plugins.config.get('@csl')
+
+  let style = config.styles.get('apa')
+  const styleName = csl ?? 'apa'
+  if (/\.csl$/i.test(styleName)) {
+    try { style = readFileSync(resolve(deckDir, styleName), 'utf-8') } catch (error) {
+      diagnostics.push({ severity: 'warning', code: 'citation-style', message: `Citation style ${styleName}: ${error.code === 'ENOENT' ? 'file not found' : error.message}; using apa` })
+    }
+  } else if (config.styles.has(styleName)) style = config.styles.get(styleName)
+  else diagnostics.push({ severity: 'warning', code: 'citation-style', message: `Unknown citation style "${styleName}" (built in: ${config.styles.list().join(', ')}, or a .csl file); using apa` })
+
+  let locale = pickLocale(lang, config.locales.list())
+  if (!locale) {
+    diagnostics.push({ severity: 'warning', code: 'citation-locale', message: `No citation locale for "${lang}" (available: ${config.locales.list().join(', ')}); using en-US` })
+    locale = 'en-US'
+  }
+
+  let engine
+  try {
+    engine = new CSL.Engine({
+      retrieveItem: id => byId.get(id),
+      retrieveLocale: id => config.locales.get(id) ?? config.locales.get('en-US'),
+    }, style, locale, true)
+  } catch (error) {
+    diagnostics.push({ severity: 'warning', code: 'citation-style', message: `Citation style ${styleName}: ${error.message}` })
+    return result
+  }
+  engine.setOutputFormat('html')
+  engine.opt.development_extensions.wrap_url_and_doi = true
+
+  // In order, so numbering and disambiguation (2020a, 2020b) come out right.
+  const html = new Map()
+  const done = []
+  clusters.forEach((cluster, index) => {
+    // A mixed citation formats its known works; the runtime marks the others.
+    const known = cluster.items.filter(item => byId.has(item.id))
+    if (!known.length) return
+    const citationItems = known.map(item => toCiteItem(cluster.narrative ? { ...item, suppressAuthor: true } : item))
+    const citation = { citationID: `c${index}`, citationItems, properties: { noteIndex: 0 } }
+    const [, updates] = engine.processCitationCluster(citation, done, [])
+    done.push([citation.citationID, 0])
+    for (const [, text, id] of updates) html.set(id, text)
+  })
+  clusters.forEach((cluster, index) => {
+    const text = html.get(`c${index}`)
+    if (text == null || Object.hasOwn(result.clusters, cluster.raw)) return
+    if (!cluster.narrative) { result.clusters[cluster.raw] = text; return }
+    const { id } = cluster.items[0]
+    let author = engine.makeCitationCluster([{ id, 'author-only': true }])
+    if (!author || /NO_PRINTED_FORM/.test(author)) author = namesOf(byId.get(id))
+    result.clusters[cluster.raw] = `${author} ${text}`
+  })
+
+  const cited = citedKeys(clusters).filter(id => byId.has(id))
+  for (const id of cited) result.singles[id] = engine.makeCitationCluster([{ id }])
+  if (uncited.length) engine.updateUncitedItems(uncited)
+  const bibliography = engine.makeBibliography()
+  if (!bibliography) {
+    diagnostics.push({ severity: 'warning', code: 'citation-style', message: `Citation style ${styleName} has no reference list` })
+    return result
+  }
+  const [meta, entries] = bibliography
+  meta.entry_ids.forEach(([id], i) => {
+    result.entries[id] = entries[i].trim()
+    result.order.push(id)
+  })
+  return result
+}
+
+// Everything the deck's `bibliography`, `csl`, `nocite` and `lang` ask for,
+// or null when the deck has no bibliography.
+export async function resolveBibliography(deckPath, source) {
+  let deckConfig
+  try { deckConfig = parseSlides(source).deckConfig ?? {} } catch { return null }
+  const files = bibliographyFiles(deckPath, deckConfig)
+  if (!files.length) return null
+  const loaded = await loadBibliography(files)
+  const formatted = await formatBibliography({
+    items: loaded.items, texts: deckTexts(source), csl: deckConfig.csl, lang: deckConfig.lang,
+    nocite: deckConfig.nocite ?? [], deckDir: dirname(resolve(deckPath)),
+  })
+  return { ...formatted, diagnostics: [...loaded.diagnostics, ...formatted.diagnostics], files, style: styleFile(deckPath, deckConfig) }
+}

package/src/build/check.js

@@ -10,6 +10,7 @@ import { paletteProblems } from '../extensions/contrast.js'
 import { collectLocalAssetRefs } from './slidesPlugin.js'
 import { componentFolders, isFolder } from './components.js'
 import { inkFileFor, validateInk, normalizeInk, orphanIds } from '../core/ink.js'
+import { resolveBibliography } from './bibliography.js'
 
 export function checkDeck(slidesPath, registry, source = readFileSync(slidesPath, 'utf8')) {
   const deck = parseSlides(source)
@@ -40,3 +41,14 @@ export function checkDeck(slidesPath, registry, source = readFileSync(slidesPath
   }
   return { deck, diagnostics }
 }
+
+// What the deck's references cannot use: missing or unreadable files, an
+// unknown style or language, citations of keys the files do not have.
+export async function bibliographyDiagnostics(slidesPath, source = readFileSync(slidesPath, 'utf8')) {
+  const bibliography = await resolveBibliography(slidesPath, source)
+  return (bibliography?.diagnostics ?? []).map(d => {
+    const at = d.code === 'citation-unknown' ? source.indexOf('@' + d.message.match(/@(\S+)/)?.[1]) : -1
+    const line = at < 0 ? 1 : source.slice(0, at).split('\n').length
+    return { ...d, line, column: 1 }
+  })
+}

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/slidesPlugin.js

@@ -5,13 +5,14 @@ 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 { isOwnWrite } from './ownWrites.js'
 import { fileURLToPath } from 'node:url'
 import { assertDrawings } from './drawings.js'
 import { marked } from 'marked'
+import { resolveBibliography } from './bibliography.js'
 
 const VIRTUAL_ID = 'virtual:slides'
 const RESOLVED_ID = '\0virtual:slides'
@@ -24,6 +25,8 @@ 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 MIME_BY_EXT = {
   '.png': 'image/png',
@@ -213,11 +216,14 @@ 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, 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 extensionDirs = extensionRoots(abs).map(root => root.dir)
   let componentDirs = componentFolders(abs, readDeck()).map(folder => folder.dir)
@@ -233,8 +239,15 @@ 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 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)
@@ -266,6 +279,7 @@ 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
     },
     load(id) {
       if (id === RESOLVED_ID) {
@@ -295,6 +309,14 @@ 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))}`
       }
       if (id === RESOLVED_SVGS_ID) {
@@ -303,6 +325,18 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
         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)
+        return resolveBibliography(abs, sourceFor(readDeck())).then(bibliography => {
+          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'))
+          const data = bibliography && { ids: bibliography.ids, clusters: bibliography.clusters, singles: bibliography.singles, entries: bibliography.entries, order: bibliography.order }
+          return `export default ${JSON.stringify(data)}`
+        })
+      }
       if (id === RESOLVED_EXTENSIONS_ID) {
         const registry = loadRegistry(abs)
         for (const record of registry.records) this.addWatchFile(record.file)
@@ -350,12 +384,18 @@ export function slidesPlugin(slidesPath, { inlineImages = false, inlineMedia = f
       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 +403,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

@@ -14,13 +14,13 @@ import { sampleDeck, SAMPLE_PICTURE } 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)
@@ -120,7 +122,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.
@@ -147,15 +149,25 @@ export function checkLooks(looks, { extensions = {} } = {}) {
   })
 }
 
+// The size of a theme's icon in lists, in CSS pixels; drawn at twice that
+// for sharp screens.
+export const ICON = { width: 96, height: 54, scale: 2 }
+
 // Pictures of looks on the sample deck, as WebP: { file, theme, palette,
-// slide } each, slide counting from 1.
+// slide, icon } each, slide counting from 1. `icon`, if given, is a second
+// file with the same slide at icon size: small enough for a list, and still
+// showing the theme's type, colours and shapes.
 export function renderPreviews(shots, { extensions = {}, width = 960, height = 540 } = {}) {
   return withSampleDeck({ extensions }, async ({ open }) => {
-    for (const { file, theme, palette = '', slide = 1 } of shots) {
+    for (const { file, theme, palette = '', slide = 1, icon = null } of shots) {
       const page = await open({ theme, palette })
       if (slide > 1) { await page.evaluate(`document.querySelector('deck-stage').goTo(${slide - 1})`); await settle(page) }
       mkdirSync(resolve(file, '..'), { recursive: true })
       writeFileSync(file, await page.screenshot({ width, height, format: 'webp' }))
+      if (icon) {
+        mkdirSync(resolve(icon, '..'), { recursive: true })
+        writeFileSync(icon, await page.screenshot({ ...ICON, format: 'webp' }))
+      }
       await page.close()
     }
   })

package/src/cli/args.js

@@ -9,11 +9,12 @@ 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 },
@@ -28,6 +29,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 +84,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 }
 }