mdeck 3.2.0 → 3.4.0

package/docs/site/content/drawing.md

@@ -16,7 +16,7 @@ Press **D** in standalone slides or in the presenter view, or use the pen button
 
 **Zoom**: two fingers zoom into the slide and move around it, one finger moves a zoomed slide, and Ctrl + scroll (a trackpad pinch) zooms on a laptop. Only the slide grows; the bars and the toolbar keep their size. The audience window shows the same part of the slide. **1:1** at the top left shows the whole slide again, as does the next slide.
 
-On a touch screen such as an iPad, drawing is on as soon as the presenter view opens, and in the deck as soon as the pencil touches it, with the toolbar folded into its button in the bottom right corner (↘ folds it again). Until then, a tap on the right third of the screen goes forward, on the left third back, and a swipe does the same. Drawing starts with the laser pointer; choose the pen or the highlighter to write. The pen and the highlighter each have colours and three sizes, and each keeps its own; one pen colour is **Accent**, the accent colour of the theme and palette: a drawing in it changes with them. The other pen colours follow light and dark: on dark slides red, blue and green are lighter, and the text colour is white instead of black. The toolbar also has undo and redo (also Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z), **Clear this slide**, and **×** to stop drawing; **D** and **Escape** do the same. While you draw, the pencil and the mouse draw; fingers keep working: a swipe to the left goes forward, to the right back, a tap on a stroke selects it, and buttons and polls on the slide still respond. Turn slides with the arrow keys or the presenter view's arrows, as always. Holding the pen still for half a second at the end of a stroke makes it a straight line.
+On a touch screen such as an iPad, drawing is on as soon as the presenter view opens, and in the deck as soon as the pencil touches it, with the toolbar folded into its button in the bottom right corner (↘ folds it again). Until then, a tap on the right third of the screen goes forward, on the left third back, and a swipe does the same. Drawing starts with the laser pointer; choose the pen or the highlighter to write. The pen and the highlighter each have colours and three sizes, and each keeps its own; one pen colour is **Accent**, the accent colour of the theme and palette: a drawing in it changes with them. The other pen colours follow light and dark: on dark slides red, blue and green are lighter, and the text colour is white instead of black. The toolbar also has undo and redo (also Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z), **Clear this slide**, and **×** to stop drawing; **D** and **Escape** do the same. While you draw, the pencil and the mouse draw; fingers keep working: a swipe to the left goes forward, to the right back, a tap on a stroke selects it, and buttons and polls on the slide still respond. Turn slides with the arrow keys or the presenter view's arrows, as always. Holding the pen still for half a second at the end of a stroke makes it a straight line; near a multiple of 15° (horizontal, vertical, 45° …) it snaps to that angle.
 
 **I** hides and shows what was drawn before, for example when a slide should look clean again. The toolbar has the same switch.
 

package/docs/site/content/more-content.md

@@ -81,6 +81,28 @@ This finding comes from our neighborhood survey.[^survey]
 
 The name inside the brackets connects the sentence to its source. Give each source a different name.
 
+If you keep your sources in Zotero or another reference manager, export them as a `.bib` file next to the deck and cite them by their keys. The slide shows a short citation and lists the full reference at its bottom; a slide with `<bibliography />` lists them all:
+
+```markdown
+---
+bibliography: refs.bib
+---
+# Results
+
+Gardens cool the street [@smith2020, p. 12].
+
+---
+# Sources
+
+<bibliography />
+```
+
+- `[@smith2020, p. 12]` adds a page, `[see @smith2020; @doe2019]` cites two works at once, and `@smith2020` in a sentence reads "Smith et al. (2020)".
+- `csl: vancouver` numbers the works instead; `harvard1` is built in too, and any style from the [Zotero style repository](https://www.zotero.org/styles) works as a `.csl` file next to the deck. Words such as "p." follow the deck's `lang`.
+- Besides `.bib`, a CSL-JSON file (`.json`) or a Typst Hayagriva file (`.yml`) works, and `bibliography:` takes a list of several.
+- A long list goes over two slides with `<bibliography part="1/2" />` and `<bibliography part="2/2" />`.
+- A key that is not in the file shows as `@key?`, and `mdeck check` names it.
+
 ## Add a QR code
 
 A QR code lets people open a link on their phones. Replace the address below with your own:

package/docs/site/content/sharing.md

@@ -20,6 +20,7 @@ Send `my-talk.html` by email. It opens in a **reader view**: an outline of all s
 
 - Drawings from `my-talk.drawings.json` are part of every build and PDF; `--no-drawings` leaves them out. See [Draw on your slides](drawing.html).
 - Your speaker notes are removed. Add `--notes` to keep them in the file, for example when you also present from the same file. Readers only see notes if you put `reader:` with `notes: true` in the settings at the top of your slide file.
+- Slides with a poll, question, word cloud or scale stay as a record of the talk: the question and its options, marked as answered live. Add `--no-polls` to leave them out of the file and its PDF, together with slides showing the join code (`<qrcode join />`).
 - The PDF is made while sending, using Chrome or Chromium on your computer. If neither is found, the button offers the browser's own "Save as PDF" dialog instead. Set `MDECK_CHROME` to the browser's path if it is installed somewhere unusual. `--no-pdf` skips it.
 - `-o` chooses the name: `mdeck send my-talk.md -o handout.html`.
 - The file keeps your theme and colours; readers can only switch between light and dark. To keep that fixed too, put `reader:` with `themes: false` in the settings at the top of your slide file.

package/docs/site/content/troubleshooting.md

@@ -61,7 +61,7 @@ For new slides, a settings block should begin with `:::meta` and end with `:::`.
 
 ## Text is missing or does not fit
 
-A slide has a fixed amount of space. Split a long explanation over two slides, shorten a paragraph, or try a simpler layout. The current checker does not automatically detect visual overflow; tell your assistant which slides overflow.
+A slide has a fixed amount of space. Split a long explanation over two slides, shorten a paragraph, or try a simpler layout. `mdeck check my-talk.md --render` lists the slides whose content does not fit, with the line each starts on.
 
 If you see an “unknown region” error, check that the layout supports the named area you used. For example, `left` and `right` work with `split`, but not with `title`.
 

package/docs/site/content/views.md

@@ -11,12 +11,14 @@ Every build and every preview contains all views. The address picks one with `?v
 | `?view=deck` | Standalone slides with drawing controls | Slides opened from the reader view or a built file |
 | `?view=presenter` | Current and next slide, notes and timer, and a button that opens the audience window | You, while presenting |
 | `?view=audience` | Slides without notes, with navigation synced to the presenter view | The projector |
-| `?view=reader` | The reader view: an outline, **Slides** and **Read** modes, a **Look** menu and a PDF | People you send the talk to |
+| `?view=reader` | The reader view: an outline, **Slides** and **Read** modes, light or dark, and a PDF | People you send the talk to |
+| `?view=follow` | The slide you are showing and your drawing, live; people can page back and return with **Back to live**, but never see a slide before you show it | People in the room, on their phone or laptop |
 
 Ways to switch between them:
 
 - The **Overview** link in the corner of the deck opens the reader view. Its outline is the overview of all slides.
 - **Present** in the reader view opens standalone slides at the current slide.
+- People in the room open the follow view with `<qrcode follow />` on a slide, with the **Follow the slides** link on the phones' answer page, or with the **Follow** address `mdeck run --network` prints. It works where their devices reach both the slides and your stage room: on the same network with `mdeck run --network`, or anywhere for a deck hosted with a `server` setting.
 - The presenter view's audience-window button opens the audience view in a new window. Navigation in either window updates the other, in the same browser or on a paired iPad: see [Draw on your slides](drawing.html#present-from-an-ipad).
 - The launch page of `mdeck run`, at the preview's plain address, offers Presenter, Audience and Reader. Its presenter and audience buttons belong together.
 - Fullscreen is a control inside a view (**F** or its fullscreen button). For a single screen, use the presenter view's slide-only layout.

package/examples/citations/refs.bib

@@ -0,0 +1,30 @@
+@article{sweller1988,
+  author  = {Sweller, John},
+  title   = {Cognitive Load During Problem Solving: Effects on Learning},
+  journal = {Cognitive Science},
+  year    = {1988},
+  volume  = {12},
+  number  = {2},
+  pages   = {257--285},
+  doi     = {10.1207/s15516709cog1202_4}
+}
+
+@article{roediger2006,
+  author  = {Roediger, Henry L. and Karpicke, Jeffrey D.},
+  title   = {Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention},
+  journal = {Psychological Science},
+  year    = {2006},
+  volume  = {17},
+  number  = {3},
+  pages   = {249--255},
+  doi     = {10.1111/j.1467-9280.2006.01693.x}
+}
+
+@book{mayer2009,
+  author    = {Mayer, Richard E.},
+  title     = {Multimedia Learning},
+  edition   = {2},
+  publisher = {Cambridge University Press},
+  address   = {Cambridge},
+  year      = {2009}
+}

package/examples/citations/refs.yml

@@ -0,0 +1,21 @@
+# The same deck can draw on a Typst (Hayagriva) file as well.
+freeman2014:
+  type: Article
+  title: Active learning increases student performance in science, engineering, and mathematics
+  author:
+    - Freeman, Scott
+    - Eddy, Sarah L.
+    - McDonough, Miles
+    - Smith, Michelle K.
+    - Okoroafor, Nnadozie
+    - Jordt, Hannah
+    - Wenderoth, Mary Pat
+  date: 2014
+  page-range: 8410-8415
+  serial-number:
+    doi: 10.1073/pnas.1319030111
+  parent:
+    type: Periodical
+    title: Proceedings of the National Academy of Sciences
+    volume: 111
+    issue: 23

package/examples/citations/slides.md

@@ -0,0 +1,43 @@
+---
+theme: academic
+meta:
+  title: "What helps people learn"
+  author: "Tilman Schieber"
+  organization: "FHNW"
+bibliography: [refs.bib, refs.yml]
+csl: apa
+---
+
+---
+:::meta
+layout: title
+:::
+# What helps people learn
+## Citations from a reference file
+
+:::notes
+The references come from `refs.bib` (BibTeX, as Zotero exports it) and `refs.yml` (Hayagriva, Typst's format). Try `csl: vancouver` or `lang: de` in the deck settings.
+:::
+
+---
+# Less on the slide
+
+Working memory holds only a few things at once, so a slide that makes people search wastes it [@sweller1988].
+
+Words spoken alongside a picture beat the same words printed on it [@mayer2009, chap. 11].
+
+---
+# Ask, don't tell
+
+As @roediger2006 showed, recalling something fixes it better than reading it again.
+
+Lectures with active learning cut failure rates by about a third [@freeman2014; see also @roediger2006].
+
+:::notes
+Freeman et al. pooled 225 studies [-@freeman2014].
+:::
+
+---
+# References
+
+<bibliography />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeck",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "type": "module",
   "description": "Write slides as a plain text file, present them in the browser, share them as one HTML file or PDF.",
   "license": "MIT",
@@ -57,7 +57,11 @@
     "theme-images": "node tools/theme-images.mjs"
   },
   "dependencies": {
+    "@citation-js/core": "^0.9.0",
+    "@citation-js/plugin-bibtex": "^0.9.0",
+    "@citation-js/plugin-csl": "^0.9.0",
     "@preact/preset-vite": "^2.10.6",
+    "citeproc": "^2.4.63",
     "d3-cloud": "^1.2.9",
     "js-yaml": "^4.3.2",
     "katex": "^0.18.9",

package/skills/write-slides/SKILL.md

@@ -41,6 +41,8 @@ meta:
   author: "Name"
   organization: "FHNW"
   date: "2026-09-16"
+bibliography: refs.bib  # optional: .bib, CSL-JSON or Hayagriva; cite [@key, p. 3] or @key, list with <bibliography />
+csl: apa                # optional: apa, vancouver, harvard1 or a .csl file
 ---
 
 ---
@@ -92,7 +94,7 @@ Right column
 - Named areas use `:::slot name … :::`; the layout's regions and settings come from `mdeck list layouts --json`.
 - `:::notes … :::` holds speaker notes. `:::steps … :::` reveals list items one at a time. `:::note`, `:::tip`, `:::important`, `:::warning` and `:::caution` are callouts (`mdeck check` warns about other names); for lectures, `:::definition`, `:::theorem`, `:::lemma`, `:::proof`, `:::example` and `:::remark`, numbered in the title (`::: theorem Theorem 2.4 (Lagrange)`). `:::columns … +++ … :::` makes columns inside a slide.
 - Code fences get syntax highlighting; `$…$` and `$$…$$` render math.
-- `<poll room="lunch" options="Mensa|Thai|Pizza" />` lets the audience vote on their phones through a QR code on the slide; each poll needs its own `room`. `<scale room="pace" min="1" max="5" low="Too slow" high="Too fast" />`, `<wordcloud room="mood" />` and `<question room="ask" />` ask for a rating, short words or open answers the same way. With several of them, put `<qrcode join />` (the deck's join code) on an early slide to show the QR code once, and add `qr="false"` to the questions. It works when the deck is presented with `mdeck run <deck>.md --network` or with a server set as `server:` in the deck settings.
+- `<poll room="lunch" options="Mensa|Thai|Pizza" />` lets the audience vote on their phones through a QR code on the slide; each poll needs its own `room`. `question` and `options` may use Markdown and `$…$` maths (`options="$2x$|$x^2$"`); `answer` repeats the right option's text. `multiple` allows several picks; `buttons="letters"` shows only A, B, C on the phones, for options that are pictures or long formulas. `<numeric room="lim" question="…" answer="1/2" tolerance="0.01" />` asks for a number. `<scale room="pace" min="1" max="5" low="Too slow" high="Too fast" />`, `<wordcloud room="mood" />` and `<question room="ask" />` ask for a rating, short words or open answers the same way. With several of them, put `<qrcode join />` (the deck's join code) on an early slide to show the QR code once, and add `qr="false"` to the questions. It works when the deck is presented with `mdeck run <deck>.md --network` or with a server set as `server:` in the deck settings.
 
 ## 3. Write the deck
 
@@ -128,10 +130,12 @@ The request is the message that invoked this skill: usually source material to t
 Save the deck as a `.md` file named after the topic (for example `enzyme-kinetics.md`), then run:
 
 ```sh
-mdeck check <deck>.md
+mdeck check <deck>.md --render
 ```
 
-Fix anything it reports. When you worked from source material, list what you left out or moved to notes, and anything you added that is not in the material. Finish by telling the user the two commands they will want next: `mdeck run <deck>.md` for the launch page (preview, presenting, editor, builds and checks), and `mdeck send <deck>.md` for a file to send around (a reader view with a PDF; notes are removed unless `--notes` is added).
+Fix anything it reports. `--render` builds the deck and shows every slide in Chrome with all steps revealed; it names each slide whose content does not fit, whose text is cut off at the edge or hard to read, with the line the slide starts on. Shorten or split those slides, or pick another layout, and check again. If Chrome is missing, run the check without `--render` and tell the user.
+
+To see slides yourself, if you can read pictures, run `mdeck snapshot <deck>.md --slide 3,5-7`: it saves PNG files to `.mdeck-snapshots/` beside the deck and prints their paths (`--dark` shows the dark appearance). Look at slides you were unsure about, such as diagrams, pictures and columns. When you worked from source material, list what you left out or moved to notes, and anything you added that is not in the material. Finish by telling the user the two commands they will want next: `mdeck run <deck>.md` for the launch page (preview, presenting, editor, builds and checks), and `mdeck send <deck>.md` for a file to send around (a reader view with a PDF; notes are removed unless `--notes` is added).
 
 ## 5. A new look: themes and palettes
 

package/src/build/bibliography.js

@@ -0,0 +1,307 @@
+import { readFileSync, statSync, existsSync } from 'fs'
+import { resolve, dirname, extname, basename } from 'path'
+import yaml from 'js-yaml'
+import { parseSlides } from '../core/parseSlides.js'
+import { scanCitations, citedKeys } from '../core/citations.js'
+import { sampleDeck, SAMPLE_REFERENCES, SAMPLE_REFERENCES_FILE } from '../editor/sampleDeck.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 items = await parseReferences(readFileSync(file, 'utf-8'), extname(file))
+  parsed.set(file, { mtimeMs, items })
+  return items
+}
+
+// Reference file text as CSL-JSON items; `ext` names the format.
+export async function parseReferences(text, ext) {
+  ext = ext.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')
+  return items.filter(item => item && item.id != null).map(item => ({ ...item, id: String(item.id) }))
+}
+
+// `sample`: the sample deck's references stand in for a missing file of
+// theirs (the dev and edit servers show the sample deck without a folder).
+export async function loadBibliography(files, { sample = false } = {}) {
+  const items = []
+  const seen = new Set()
+  const diagnostics = []
+  for (const file of files) {
+    let found
+    try {
+      found = sample && basename(file) === SAMPLE_REFERENCES_FILE && !existsSync(file) ? await parseReferences(SAMPLE_REFERENCES, '.bib') : 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, { sample = false } = {}) {
+  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, { sample })
+  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) }
+}
+
+// The sample deck's citations, formatted once: the design page previews it
+// in the editor of any deck, whose own references are another matter.
+let sampleFormatted = null
+export function sampleBibliography() {
+  sampleFormatted ??= parseReferences(SAMPLE_REFERENCES, '.bib')
+    .then(items => formatBibliography({ items, texts: deckTexts(sampleDeck()) }))
+  return sampleFormatted
+}

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 }
+  })
+}