mdeck 2.3.0

package/src/core/labels.js

@@ -0,0 +1,144 @@
+// Words the audience sees — in the reader, the deck controls, polls and the
+// answer page — in the deck's language. `lang` picks a set (the part before a
+// hyphen, so `de-CH` uses `de`); `labels` in the deck settings replaces single
+// entries. Tools for the presenter (presenter view, launch page, editor) stay
+// in English.
+
+export const LABELS = {
+  en: {
+    'reader.outline': 'Outline',
+    'reader.untitled': 'Slides',
+    'reader.slides': 'Slides',
+    'reader.read': 'Read',
+    'reader.appearance': 'Light or dark',
+    'reader.light': 'Light',
+    'reader.dark': 'Dark',
+    'reader.downloadPdf': 'Download PDF',
+    'reader.savePdf': 'Save as PDF…',
+    'reader.savePdfHint': "Opens the browser's print dialog; choose Save as PDF",
+    'reader.present': 'Present',
+    'reader.previous': 'Previous',
+    'reader.next': 'Next',
+    'reader.copyLink': 'Copy link to this slide',
+    'reader.linkCopied': 'Link copied',
+    'reader.slide': 'Slide {n}',
+    'deck.overview': 'Overview',
+    'slide.chapter': 'Chapter',
+    'deck.controls': 'Deck controls',
+    'deck.previous': 'Previous slide',
+    'deck.next': 'Next slide',
+    'deck.reset': 'Reset',
+    'deck.resetHint': 'Reset to first slide',
+    'poll.scan': 'Scan to vote',
+    'poll.answer': '1 answer',
+    'poll.answers': '{n} answers',
+    'poll.reset': 'Reset',
+    'poll.showAnswer': 'Show the right answer',
+    'poll.hideAnswer': 'Hide the right answer',
+    'poll.live': 'Live',
+    'poll.offline': 'Not connected to the server',
+    'poll.unreachable': 'Phones cannot reach this computer. Start with {command}, or set {setting}.',
+    'poll.tryHere': 'Try the answer page here',
+    'poll.static': 'Answered live during the talk.',
+    'poll.pick': 'Tap one answer.',
+    'poll.thanks': 'Thanks! You chose “{choice}”. Tap another to change.',
+    'respond.waiting': 'The next question will appear here.',
+    'respond.send': 'Send',
+    'respond.sent': 'Sent. Thank you!',
+    'join.scan': 'Scan to join',
+    'join.static': 'During the talk, phones joined here to answer.',
+    'question.empty': 'Answers appear here.',
+    'scale.average': 'Average {n}',
+  },
+  de: {
+    'reader.outline': 'Gliederung',
+    'reader.untitled': 'Folien',
+    'reader.slides': 'Folien',
+    'reader.read': 'Lesen',
+    'reader.appearance': 'Hell oder dunkel',
+    'reader.light': 'Hell',
+    'reader.dark': 'Dunkel',
+    'reader.downloadPdf': 'PDF herunterladen',
+    'reader.savePdf': 'Als PDF sichern…',
+    'reader.savePdfHint': 'Öffnet den Druckdialog des Browsers; dort „Als PDF sichern“ wählen',
+    'reader.present': 'Präsentieren',
+    'reader.previous': 'Zurück',
+    'reader.next': 'Weiter',
+    'reader.copyLink': 'Link zu dieser Folie kopieren',
+    'reader.linkCopied': 'Link kopiert',
+    'reader.slide': 'Folie {n}',
+    'deck.overview': 'Übersicht',
+    'slide.chapter': 'Kapitel',
+    'deck.controls': 'Foliensteuerung',
+    'deck.previous': 'Vorherige Folie',
+    'deck.next': 'Nächste Folie',
+    'deck.reset': 'Neustart',
+    'deck.resetHint': 'Zurück zur ersten Folie',
+    'poll.scan': 'Scannen und abstimmen',
+    'poll.answer': '1 Antwort',
+    'poll.answers': '{n} Antworten',
+    'poll.reset': 'Zurücksetzen',
+    'poll.showAnswer': 'Richtige Antwort zeigen',
+    'poll.hideAnswer': 'Richtige Antwort ausblenden',
+    'poll.live': 'Live',
+    'poll.offline': 'Keine Verbindung zum Server',
+    'poll.unreachable': 'Handys erreichen diesen Computer nicht. Mit {command} starten oder {setting} setzen.',
+    'poll.tryHere': 'Antwortseite hier ausprobieren',
+    'poll.static': 'Im Vortrag live beantwortet.',
+    'poll.pick': 'Eine Antwort antippen.',
+    'poll.thanks': 'Danke! Gewählt: „{choice}“. Zum Ändern eine andere antippen.',
+    'respond.waiting': 'Die nächste Frage erscheint hier.',
+    'respond.send': 'Senden',
+    'respond.sent': 'Gesendet. Danke!',
+    'join.scan': 'Scannen und mitmachen',
+    'join.static': 'Im Vortrag haben sich hier die Handys zum Antworten verbunden.',
+    'question.empty': 'Hier erscheinen die Antworten.',
+    'scale.average': 'Durchschnitt {n}',
+  },
+}
+
+export const LABEL_KEYS = Object.keys(LABELS.en)
+
+// Callout titles by type (`::: tip`), in the deck's language; the deck's
+// `callouts` setting replaces single titles.
+export const CALLOUT_LABELS = {
+  en: { note: 'Note',    tip: 'Tip',  important: 'Important', warning: 'Warning', caution: 'Caution',
+    definition: 'Definition', theorem: 'Theorem', lemma: 'Lemma', corollary: 'Corollary', proof: 'Proof', example: 'Example', remark: 'Remark' },
+  de: { note: 'Hinweis', tip: 'Tipp', important: 'Wichtig',   warning: 'Achtung', caution: 'Vorsicht',
+    definition: 'Definition', theorem: 'Satz',    lemma: 'Lemma', corollary: 'Korollar',  proof: 'Beweis', example: 'Beispiel', remark: 'Bemerkung' },
+}
+
+export const CALLOUT_TYPES = Object.keys(CALLOUT_LABELS.en)
+
+let language = 'en'
+let current = LABELS.en
+
+export function labelSetFor(lang) {
+  const base = String(lang ?? '').toLowerCase().split('-')[0]
+  return Object.hasOwn(LABELS, base) ? base : 'en'
+}
+
+export function setDeckLanguage({ lang, labels } = {}) {
+  language = typeof lang === 'string' && lang.trim() ? lang.trim() : 'en'
+  const overrides = labels && typeof labels === 'object' && !Array.isArray(labels) ? labels : {}
+  current = { ...LABELS[labelSetFor(language)], ...Object.fromEntries(Object.entries(overrides).filter(([, value]) => typeof value === 'string')) }
+}
+
+/** Words for the <deck-stage> control bar. */
+export function stageLabels() {
+  return { controls: t('deck.controls'), previous: t('deck.previous'), next: t('deck.next'), reset: t('deck.reset'), resetHint: t('deck.resetHint') }
+}
+
+/** The deck's `lang`, for the page's language attribute. */
+export function deckLanguage() {
+  return language
+}
+
+// Fills {name} placeholders. With only strings it returns a string; when a
+// value is anything else (such as a Preact element) it returns an array of
+// parts, ready to render.
+export function t(key, vars = {}) {
+  const text = current[key] ?? LABELS.en[key] ?? key
+  const parts = text.split(/\{(\w+)\}/).map((part, i) => i % 2 ? (Object.hasOwn(vars, part) ? vars[part] : `{${part}}`) : part)
+  return parts.every(part => typeof part === 'string' || typeof part === 'number') ? parts.join('') : parts.filter(part => part !== '')
+}

package/src/core/outline.js

@@ -0,0 +1,33 @@
+// Slide titles and the deck outline, shared by the editor and the share view.
+import { fenceState } from './source.js'
+
+function firstProseLine(content = '') {
+  let fence = null
+  for (const raw of content.split(/\r?\n/)) {
+    const before = fence
+    fence = fenceState(raw, fence)
+    if (before || fence) continue
+    const line = raw.trim()
+    if (line && !/^(:::|\||<|!\[|---)/.test(line)) return line
+  }
+  return null
+}
+
+// `slideName(n)` names a slide without a heading or text for readers
+// ("Slide 4"); without it, the layout's title is used, as the editor wants.
+export function slideTitle(slide, index, manifest, { slideName = null } = {}) {
+  if (slide.meta.title) return slide.meta.title
+  const heading = slide.content?.match(/^\s*#{1,3}\s+(.+?)\s*#*\s*$/m)?.[1]
+  if (heading) return heading.replace(/[*_`]/g, '')
+  const first = firstProseLine(slide.content)
+  if (first) return first.replace(/[*_`#>]/g, '').slice(0, 60)
+  if (slideName) return slideName(index + 1)
+  return manifest?.title ?? slide.meta.layout ?? `Slide ${index + 1}`
+}
+
+export function deckOutline(deck, layouts = {}, options = {}) {
+  return deck.slides.map((slide, index) => {
+    const layout = slide.meta.layout ?? 'generic'
+    return { index, id: slide.id, title: slideTitle(slide, index, layouts[layout], options), layout, chapter: layout === 'chapter', part: slide.meta.part ?? null, section: slide.meta.section ?? null, notes: slide.meta.notes ?? '' }
+  })
+}

package/src/core/parseSlides.js

@@ -0,0 +1,152 @@
+import yaml from 'js-yaml'
+import { sourceLines, fenceState, scanDirectives, diagnostic } from './source.js'
+export { sourceLines, fenceState } from './source.js'
+
+export const DECK_KEYS = new Set('theme palette appearance params meta width height show lang labels callouts reader components server session'.split(' '))
+export const SLIDE_KEYS = new Set('layout id title section number part description label image alt overlay eyebrow attribution props'.split(' '))
+
+// Names from before 2.0. They are still recognised, so that an old deck gets a
+// message naming the new setting (see validateDeck) instead of being read as
+// a slide, but nothing uses them.
+export const RENAMED_DECK_KEYS = {
+  design: 'theme',
+  institution: 'show.organization',
+  authorDate: 'show.author',
+  pageNumbers: 'show.numbers',
+  sections: 'show.sections',
+  share: 'reader',
+  live: 'server and session',
+}
+const ANY_DECK_KEYS = new Set([...DECK_KEYS, ...Object.keys(RENAMED_DECK_KEYS)])
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function segmentsOf(source) {
+  const segments = []
+  let start = 0
+  let fence = null
+  let depth = 0
+  for (const line of sourceLines(source)) {
+    const before = fence
+    fence = fenceState(line.text, fence)
+    if (before || fence) continue
+    if (/^:::\s*[\w-]+/.test(line.text)) depth++
+    else if (/^:::\s*$/.test(line.text)) depth = Math.max(0, depth - 1)
+    if (!depth && /^---[ \t]*$/.test(line.text)) {
+      segments.push({ start, end: line.start, delimiterEnd: line.end })
+      start = line.end
+    }
+  }
+  segments.push({ start, end: source.length, delimiterEnd: source.length })
+  return segments.filter(s => source.slice(s.start, s.end).trim())
+}
+
+export function looksLikeMeta(text, keys, { frontmatter = false } = {}) {
+  const first = sourceLines(text).find(line => line.text.trim() && !/^\s*#/.test(line.text))
+  const key = first?.text.match(/^([\w-]+):/)
+  return !!key && keys.has(key[1]) && (frontmatter || !/^\s*#{1,6}\s/.test(text))
+}
+
+function extractBody(source, body, diagnostics) {
+  const raw = body ? source.slice(body.start, body.end) : ''
+  const offset = body?.start ?? 0
+  const scan = scanDirectives(raw)
+  diagnostics.push(...scan.diagnostics.map(d => diagnostic(source, d.code, d.message, offset + d.offset)))
+  const regions = Object.create(null)
+  const notes = []
+  const blocks = []
+  const bodyParts = []
+  let cursor = 0
+  for (const node of scan.nodes) {
+    if (node.end == null || !['slot', 'notes', 'meta'].includes(node.name)) continue
+    if (node.start > cursor) bodyParts.push({ start: offset + cursor, end: offset + node.start })
+    const range = { start: offset + node.bodyStart, end: offset + node.bodyEnd }
+    const block = { type: node.name, name: node.argument, source: { start: offset + node.start, end: offset + node.end }, bodySource: range }
+    blocks.push(block)
+    const value = source.slice(range.start, range.end)
+    if (node.name === 'notes') notes.push(value.trim())
+    if (node.name === 'meta') diagnostics.push(diagnostic(source, 'misplaced-meta', ':::meta must be the first block of a slide', offset + node.start))
+    if (node.name === 'slot') {
+      const name = node.argument
+      if (!/^[a-z][a-z0-9-]*$/.test(name)) diagnostics.push(diagnostic(source, 'invalid-region', 'Region names must use lowercase letters, digits and hyphens', offset + node.start))
+      else if (regions[name]) diagnostics.push(diagnostic(source, 'duplicate-region', `Duplicate region "${name}"`, offset + node.start))
+      else regions[name] = { name, content: value.trim(), raw: value, source: range, explicit: true }
+      const checkChildren = children => {
+        for (const child of children) {
+          if (['slot', 'notes', 'meta'].includes(child.name)) diagnostics.push(diagnostic(source, 'nested-region', 'Slots, notes and metadata must be top-level slide blocks', offset + child.start))
+          checkChildren(child.children)
+        }
+      }
+      checkChildren(node.children)
+    }
+    cursor = node.end
+  }
+  if (cursor < raw.length) bodyParts.push({ start: offset + cursor, end: offset + raw.length })
+  const content = bodyParts.map(range => source.slice(range.start, range.end)).join('').trim()
+  // Unassigned content is always available as the default body region.
+  if (!regions.body) regions.body = { name: 'body', content, explicit: false, ranges: bodyParts }
+  else if (content) diagnostics.push(diagnostic(source, 'ambiguous-body', 'An explicit body slot cannot be combined with unassigned slide content', offset))
+  return { content, notes: notes.join('\n\n'), regions, blocks }
+}
+
+export function parseSlides(source) {
+  const segments = segmentsOf(source)
+  const diagnostics = []
+  const text = segment => source.slice(segment.start, segment.end).trim()
+  const readMeta = segment => {
+    try {
+      const value = yaml.load(source.slice(segment.start, segment.end))
+      if (!isPlainObject(value)) throw new Error('Metadata must be a YAML mapping')
+      return value
+    } catch (error) {
+      const offset = segment.start + (error.mark?.position ?? 0)
+      diagnostics.push(diagnostic(source, 'invalid-yaml', error.reason ?? error.message, offset))
+      return {}
+    }
+  }
+  let deckConfig = {}
+  let configSource = null
+  let i = 0
+  if (segments[0] && /^\s*---[ \t]*\r?\n/.test(source) && looksLikeMeta(text(segments[0]), ANY_DECK_KEYS, { frontmatter: true }) && !looksLikeMeta(text(segments[0]), SLIDE_KEYS)) {
+    deckConfig = readMeta(segments[0])
+    configSource = { start: segments[0].start, end: segments[0].end }
+    i++
+  }
+  const slides = []
+  while (i < segments.length) {
+    const segment = segments[i++]
+    let meta = {}
+    let body = segment
+    let metaSource = null
+    const explicit = scanDirectives(source.slice(segment.start, segment.end)).nodes[0]
+    if (explicit?.name === 'meta' && explicit.end != null && !source.slice(segment.start, segment.start + explicit.start).trim()) {
+      metaSource = { start: segment.start + explicit.bodyStart, end: segment.start + explicit.bodyEnd }
+      meta = readMeta(metaSource)
+      body = { start: segment.start + explicit.end, end: segment.end }
+    } else if (looksLikeMeta(text(segment), SLIDE_KEYS)) {
+      meta = readMeta(segment)
+      metaSource = { start: segment.start, end: segment.end }
+      body = segments[i]
+      if (body && !looksLikeMeta(text(body), SLIDE_KEYS) && !/^:::meta\b/.test(text(body))) i++
+      else body = null
+    }
+    const { content, notes, regions, blocks } = extractBody(source, body, diagnostics)
+    const authoredMeta = { ...meta }
+    // Speaker notes come only from body blocks. Keep the YAML snapshot for
+    // source editing and validation, separate from the resolved block notes.
+    delete meta.notes
+    if (notes) meta.notes = notes
+    slides.push({ id: meta.id ?? `slide-${slides.length + 1}`, meta, authoredMeta, content, regions, blocks,
+      source: { start: segment.start, end: body?.end ?? segment.end },
+      metaSource, bodySource: body ? { start: body.start, end: body.end } : null })
+  }
+  let currentSection = null
+  for (const slide of slides) {
+    if (slide.meta.layout === 'chapter' && slide.meta.part) currentSection = slide.meta.part
+    else if (Object.hasOwn(slide.meta, 'section')) currentSection = slide.meta.section
+    else if (currentSection) slide.meta.section = currentSection
+  }
+  return { source, configSource, deckConfig, slides, diagnostics }
+}

package/src/core/source.js

@@ -0,0 +1,137 @@
+import yaml from 'js-yaml'
+// All ranges are half-open UTF-16 offsets into the original source string.
+export function sourceLines(source) {
+  const lines = []
+  let offset = 0
+  for (const raw of source.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+    lines.push({ text: raw.replace(/\r?\n$/, ''), start: offset, end: offset + raw.length })
+    offset += raw.length
+  }
+  return lines
+}
+
+export function fenceState(text, fence) {
+  const match = text.match(/^ {0,3}(`{3,}|~{3,})(.*)$/)
+  if (!match) return fence
+  if (!fence) return { char: match[1][0], length: match[1].length }
+  if (match[1][0] === fence.char && match[1].length >= fence.length && !match[2].trim()) return null
+  return fence
+}
+
+export function diagnostic(source, code, message, offset = 0, severity = 'error') {
+  const before = source.slice(0, offset)
+  return { severity, code, message, offset, line: before.split('\n').length, column: offset - before.lastIndexOf('\n') }
+}
+
+// Balanced directive scanner, shared by the document parser and Markdown lexer.
+export function scanDirectives(source) {
+  const nodes = []
+  const stack = []
+  const diagnostics = []
+  let fence = null
+  for (const line of sourceLines(source)) {
+    const before = fence
+    fence = fenceState(line.text, fence)
+    if (before || fence) continue
+    const open = line.text.match(/^:::\s*([\w-]+)(.*)$/)
+    if (open) {
+      const node = { name: open[1], argument: open[2].trim(), start: line.start, bodyStart: line.end, children: [] }
+      if (stack.length) stack.at(-1).children.push(node)
+      else nodes.push(node)
+      stack.push(node)
+    } else if (/^:::[ \t]*$/.test(line.text)) {
+      const node = stack.pop()
+      if (!node) diagnostics.push(diagnostic(source, 'unexpected-close', 'Directive closing fence has no opening fence', line.start))
+      else Object.assign(node, { bodyEnd: line.start, end: line.end })
+    }
+  }
+  for (const node of stack) diagnostics.push(diagnostic(source, 'unclosed-directive', `Unclosed :::${node.name} block`, node.start))
+  return { nodes, diagnostics }
+}
+
+export function applySourceEdits(source, edits) {
+  const sorted = [...edits].sort((a, b) => a.start - b.start)
+  let end = 0
+  for (const edit of sorted) {
+    if (!Number.isInteger(edit.start) || !Number.isInteger(edit.end) || edit.start < end || edit.end < edit.start || edit.end > source.length) throw new Error('Invalid or overlapping source edits')
+    if (edit.expected != null && source.slice(edit.start, edit.end) !== edit.expected) throw new Error('Source changed since this edit was prepared')
+    end = edit.end
+  }
+  for (const edit of sorted.reverse()) source = source.slice(0, edit.start) + edit.text + source.slice(edit.end)
+  return source
+}
+
+export function serializeDeck(deck) { return deck.source }
+
+export function replaceRegion(deck, slideId, name, markdown) {
+  const slide = deck.slides.find(slide => slide.id === slideId)
+  const region = slide?.regions[name]
+  if (!region || !region.explicit) throw new Error(`No explicit region "${name}" on slide "${slideId}"`)
+  const newline = deck.source.includes('\r\n') ? '\r\n' : '\n'
+  const text = markdown.replace(/\r?\n/g, newline).replace(/[\r\n]*$/, '') + newline
+  return applySourceEdits(deck.source, [{ ...region.source, text, expected: region.raw }])
+}
+
+// ─── Byte-preserving editing primitives ────────────────────────────────────
+
+export function detectNewline(source) { return source.includes('\r\n') ? '\r\n' : '\n' }
+
+// Normalizes line endings and guarantees exactly one trailing newline; '' stays ''.
+export function normalizeBlock(text, newline = '\n') {
+  if (!text || !text.trim()) return ''
+  return text.replace(/\r?\n/g, newline).replace(/[\r\n]*$/, '') + newline
+}
+
+const KEY_LINE_RE = /^([\w-]+):(\s|$)/
+const TRAIL_LINE_RE = /^\s*(#.*)?$/
+
+export function firstYamlKey(text) {
+  for (const line of sourceLines(text)) {
+    if (TRAIL_LINE_RE.test(line.text)) continue
+    return line.text.match(KEY_LINE_RE)?.[1] ?? null
+  }
+  return null
+}
+
+// Patches top-level keys of a YAML mapping given as full lines. Only the
+// blocks of the patched keys are rewritten; every other line stays
+// byte-identical, including comments. `undefined` deletes a key. Returns ''
+// when no keys remain. `leadKeys` moves a recognized key to the top so
+// legacy slide metadata and deck frontmatter keep being detected.
+export function patchYamlMapping(text, patch, { newline = detectNewline(text), leadKeys = null } = {}) {
+  const existing = text.trim() ? yaml.load(text) : null
+  if (existing != null && (typeof existing !== 'object' || Array.isArray(existing))) throw new Error('Metadata must be a YAML mapping')
+  const blocks = [{ key: null, lines: [] }]
+  for (const line of sourceLines(text)) {
+    const key = line.text.match(KEY_LINE_RE)?.[1]
+    if (key) blocks.push({ key, lines: [] })
+    blocks.at(-1).lines.push(line.text)
+  }
+  const split = lines => {
+    let end = lines.length
+    while (end > 0 && TRAIL_LINE_RE.test(lines[end - 1])) end--
+    return [lines.slice(0, end), lines.slice(end)]
+  }
+  const dump = (key, value) => yaml.dump({ [key]: value }, { flowLevel: 2, lineWidth: -1, noRefs: true, quotingType: '"' }).replace(/\n$/, '').split('\n')
+  for (const [key, value] of Object.entries(patch)) {
+    if (!KEY_LINE_RE.test(`${key}:`)) throw new Error(`Invalid metadata key "${key}"`)
+    const index = blocks.findIndex(block => block.key === key)
+    if (index < 0) {
+      if (value !== undefined) blocks.push({ key, lines: dump(key, value) })
+      continue
+    }
+    const [, trailing] = split(blocks[index].lines)
+    if (value === undefined) blocks[index] = { key: null, lines: trailing }
+    else blocks[index].lines = [...dump(key, value), ...trailing]
+  }
+  const keyed = blocks.filter(block => block.key)
+  if (!keyed.length) return ''
+  if (leadKeys && !leadKeys.has(keyed[0].key)) {
+    const lead = keyed.find(block => leadKeys.has(block.key))
+    if (lead) {
+      blocks.splice(blocks.indexOf(lead), 1)
+      blocks.splice(1, 0, lead)
+    }
+  }
+  return blocks.flatMap(block => block.lines).join(newline) + newline
+}

package/src/core/urls.js

@@ -0,0 +1,34 @@
+const VIEWS = new Set(['deck', 'reader', 'presenter', 'audience'])
+const OLD_VIEWS = { d: 'deck', s: 'reader', p: 'presenter', a: 'audience', share: 'reader' }
+
+// Old URLs must be corrected explicitly: guessing a view can expose notes or
+// put the wrong window on the projector. Never include credentials in errors.
+export function validatePageUrl(url) {
+  const replacements = []
+  const corrected = new URL(url)
+  if (url.searchParams.has('v')) {
+    corrected.searchParams.set('view', OLD_VIEWS[url.searchParams.get('v')] ?? url.searchParams.get('v'))
+    corrected.searchParams.delete('v')
+    replacements.push('v → view')
+  }
+  if (corrected.searchParams.get('view') === 'share') { corrected.searchParams.set('view', 'reader'); replacements.push('view=share → view=reader') }
+  for (const [old, name] of [['design', 'theme'], ['livekey', 'serverkey']]) {
+    if (url.searchParams.has(old)) {
+      corrected.searchParams.set(name, url.searchParams.get(old)); corrected.searchParams.delete(old)
+      replacements.push(`${old} → ${name}`)
+    }
+  }
+  for (const secret of ['serverkey', 'livekey', 'pair']) corrected.searchParams.delete(secret)
+  if (replacements.length) return { message: `This URL uses settings from before API 2.0: ${replacements.join(', ')}. Open the updated address below. If you supplied a server key, add it again as ?serverkey=… on your own computer.`, corrected: corrected.href }
+  const view = url.searchParams.get('view')
+  if (view !== null && !VIEWS.has(view)) return { message: `Unknown view "${view}". Choose deck, reader, presenter or audience.` }
+  return null
+}
+
+export function readerLink(address, slideId) {
+  const url = new URL(address)
+  for (const name of ['v', 'serverkey', 'livekey', 'pair', 'session', 'embedded', 'draw']) url.searchParams.delete(name)
+  url.searchParams.set('view', 'reader')
+  url.hash = encodeURIComponent(slideId)
+  return url.href
+}

package/src/core/validateDeck.js

@@ -0,0 +1,139 @@
+import { diagnostic, scanDirectives } from './source.js'
+import { isPlainObject, RENAMED_DECK_KEYS } from './parseSlides.js'
+import { palettesFor } from '../extensions/tokens.js'
+import { LABEL_KEYS, CALLOUT_TYPES } from './labels.js'
+import { resolveLayoutProps, propertyErrors } from '../layouts/layoutProps.js'
+
+// `layouts`, `themes` and `palettes` are manifest maps from the extension
+// registry (see src/extensions/discover.js). Checks for a kind are skipped when
+// its map is not supplied.
+export function validateDeck(deck, { layouts = null, themes = null, palettes = null } = {}) {
+  const diagnostics = [...deck.diagnostics]
+  const add = (code, message, offset, severity) => diagnostics.push(diagnostic(deck.source, code, message, offset, severity))
+  const config = deck.deckConfig
+  for (const key of ['width', 'height']) {
+    if (config[key] != null && (typeof config[key] !== 'number' || !Number.isFinite(config[key]) || config[key] <= 0)) add('invalid-config', `${key} must be a positive number`, deck.configSource?.start)
+  }
+  for (const [old, now] of Object.entries(RENAMED_DECK_KEYS)) {
+    if (config[old] != null) add('renamed-setting', `${old} is now ${now}${old === 'live' ? ': the address is server, and id and code are session.id and session.code' : ''}`, deck.configSource?.start)
+  }
+  // Colours come only from the palette now.
+  for (const key of ['accent', 'accent2']) {
+    if (config[key] != null) add('removed-setting', `${key} is no longer a setting: colours come from the palette; choose one with palette (see mdeck list palettes)`, deck.configSource?.start)
+  }
+  if (config.appearance != null && !['light', 'dark'].includes(config.appearance)) add('invalid-config', 'appearance must be light or dark', deck.configSource?.start)
+  for (const key of ['meta', 'params', 'callouts', 'labels', 'show', 'reader', 'session']) {
+    if (config[key] != null && !isPlainObject(config[key])) add('invalid-config', `${key} must be a mapping`, deck.configSource?.start)
+  }
+  if (isPlainObject(config.reader)) {
+    for (const key of Object.keys(config.reader)) if (!['themes', 'notes'].includes(key)) add('invalid-config', `reader.${key} is not a setting; available: themes, notes`, deck.configSource?.start, 'warning')
+    for (const key of ['themes', 'notes']) if (config.reader[key] != null && typeof config.reader[key] !== 'boolean') add('invalid-config', `reader.${key} must be true or false`, deck.configSource?.start)
+  }
+  if (config.components != null && (!Array.isArray(config.components) || config.components.some(path => typeof path !== 'string' || !path.trim()))) add('invalid-config', 'components must be a list of folder paths', deck.configSource?.start)
+  if (config.lang != null && (typeof config.lang !== 'string' || !/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(config.lang))) add('invalid-config', 'lang must be a language code such as en, de or de-CH', deck.configSource?.start)
+  if (isPlainObject(config.labels)) {
+    for (const [key, value] of Object.entries(config.labels)) {
+      if (!LABEL_KEYS.includes(key)) add('invalid-config', `labels.${key} is not a label; see the authoring reference for the list`, deck.configSource?.start, 'warning')
+      else if (typeof value !== 'string') add('invalid-config', `labels.${key} must be text`, deck.configSource?.start)
+    }
+  }
+  if (config.server != null && (typeof config.server !== 'string' || !/^https?:\/\//.test(config.server))) add('invalid-config', 'server must be an http:// or https:// address', deck.configSource?.start)
+  if (isPlainObject(config.session)) {
+    for (const key of Object.keys(config.session)) if (!['id', 'code'].includes(key)) add('invalid-config', `session.${key} is not a setting; available: id, code`, deck.configSource?.start, 'warning')
+    if (config.session.code != null && !/^\d{4,8}$/.test(String(config.session.code))) add('invalid-config', 'session.code must be 4 to 8 digits', deck.configSource?.start)
+  }
+  const enums = { organization: ['title', 'all', 'none'], author: ['title', 'all', 'none'], numbers: ['slides', 'all', 'none'], sections: ['all', 'none'] }
+  if (isPlainObject(config.show)) {
+    for (const key of Object.keys(config.show)) if (!Object.hasOwn(enums, key)) add('invalid-config', `show.${key} is not a setting; available: ${Object.keys(enums).join(', ')}`, deck.configSource?.start, 'warning')
+    for (const [key, values] of Object.entries(enums)) {
+      if (config.show[key] != null && !values.includes(config.show[key])) add('invalid-config', `show.${key} must be one of: ${values.join(', ')}`, deck.configSource?.start)
+    }
+  }
+  if (themes && config.theme != null && !Object.hasOwn(themes, config.theme)) add('unknown-theme', `Unknown theme "${config.theme}"; available: ${Object.keys(themes).join(', ')}`, deck.configSource?.start)
+  if (palettes && themes && config.palette != null) {
+    const theme = themes[config.theme ?? 'neue']
+    const offered = theme ? palettesFor(theme, palettes).map(palette => palette.id) : Object.keys(palettes)
+    if (!Object.hasOwn(palettes, config.palette)) add('unknown-palette', `Unknown palette "${config.palette}"; available: ${offered.join(', ')}`, deck.configSource?.start)
+    else if (theme && !offered.includes(config.palette)) add('unknown-palette', `The theme "${theme.id}" does not offer the palette "${config.palette}"; available: ${offered.join(', ')}`, deck.configSource?.start)
+  }
+  if (themes && config.params != null && isPlainObject(config.params) && Object.hasOwn(themes, config.theme ?? 'neue')) {
+    const theme = themes[config.theme ?? 'neue']
+    for (const name of Object.keys(config.params)) if (!Object.hasOwn(theme.params ?? {}, name)) add('unknown-param', `Theme "${theme.id}" has no parameter "${name}"; available: ${Object.keys(theme.params ?? {}).join(', ') || 'none'}`, deck.configSource?.start, 'warning')
+  }
+  // Callout types the deck names under `callouts:` are its own, on purpose.
+  const calloutTypes = [...CALLOUT_TYPES, ...(isPlainObject(config.callouts) ? Object.keys(config.callouts).map(key => key.toLowerCase()) : [])]
+  const ids = new Set()
+  for (const slide of deck.slides) {
+    const offset = slide.metaSource?.start ?? slide.source.start
+    if (typeof slide.id !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(slide.id)) add('invalid-id', 'Slide IDs must start with a letter and contain letters, digits, hyphens or underscores', offset)
+    if (ids.has(slide.id)) add('duplicate-id', `Duplicate slide ID "${slide.id}"`, offset)
+    ids.add(slide.id)
+    for (const key of ['note', 'notes']) {
+      if (Object.hasOwn(slide.authoredMeta, key)) add('invalid-metadata', `${key} is not a slide setting; write speaker notes in a :::notes block`, offset)
+    }
+    for (const key of ['layout', 'title', 'image', 'alt', 'section', 'part', 'eyebrow', 'attribution']) {
+      if (slide.meta[key] != null && typeof slide.meta[key] !== 'string') add('invalid-metadata', `${key} must be a string`, offset)
+    }
+    if (slide.meta.props != null && !isPlainObject(slide.meta.props)) add('invalid-props', 'props must be a mapping', offset)
+    if (slide.meta.overlay != null && typeof slide.meta.overlay !== 'boolean') add('invalid-metadata', 'overlay must be true or false', offset)
+    for (const node of directivesIn(deck.source.slice(slide.source.start, slide.source.end))) {
+      if (DIRECTIVES.includes(node.name) || calloutTypes.includes(node.name.toLowerCase())) continue
+      const near = closest(node.name.toLowerCase(), [...DIRECTIVES, ...calloutTypes])
+      add('unknown-callout', `Unknown block "${node.name}"${near ? `; did you mean "${near}"?` : ''} It shows as a plain callout. Known: ${CALLOUT_TYPES.join(', ')}; name your own under callouts: in the settings`, slide.source.start + node.start, 'warning')
+    }
+    if (!layouts) continue
+    const layout = slide.meta.layout ?? 'generic'
+    if (!Object.hasOwn(layouts, layout)) {
+      add('unknown-layout', `Unknown layout "${layout}"; using the generic renderer`, offset, 'warning')
+      continue
+    }
+    const manifest = layouts[layout]
+    for (const [name, region] of Object.entries(slide.regions)) {
+      if (region.explicit && !Object.hasOwn(manifest.regions, name)) add('unknown-region', `Layout "${layout}" has no region "${name}"`, region.source.start)
+    }
+    for (const [name, schema] of Object.entries(manifest.regions)) {
+      if (schema.required && !slide.regions[name]?.content.trim()) add('missing-region', `Layout "${layout}" requires region "${name}"`, offset)
+    }
+    if (slide.meta.props != null && !isPlainObject(slide.meta.props)) continue
+    const props = resolveLayoutProps(manifest, slide.meta)
+    for (const [name, schema] of Object.entries(manifest.properties ?? {})) {
+      if (props[name] === undefined) {
+        if (schema.required) add('missing-property', `Layout "${layout}" requires props.${name}`, offset)
+      } else for (const message of propertyErrors(props[name], schema, `props.${name}`)) add('invalid-property', message, offset)
+    }
+    for (const name of Object.keys(slide.meta.props ?? {})) {
+      if (!Object.hasOwn(manifest.properties ?? {}, name)) add('unknown-property', `Layout "${layout}" has no property "${name}"`, offset)
+    }
+  }
+  return diagnostics
+}
+
+// The `:::` blocks mdeck reads itself; any other name is a callout type.
+const DIRECTIVES = ['meta', 'notes', 'slot', 'steps', 'columns']
+
+function directivesIn(source) {
+  const all = []
+  const visit = nodes => { for (const node of nodes) { all.push(node); visit(node.children) } }
+  visit(scanDirectives(source).nodes)
+  return all
+}
+
+// The known name a misspelling is most likely meant to be: at most two
+// letters added, left out or changed.
+function closest(name, names) {
+  const distance = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+      const next = [i]
+      for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+      row = next
+    }
+    return row[b.length]
+  }
+  const [best] = names.map(candidate => [candidate, distance(name, candidate)]).sort((x, y) => x[1] - y[1])
+  return best && best[1] <= 2 ? best[0] : null
+}
+
+export function formatDiagnostics(diagnostics, filename = 'slides.md') {
+  return diagnostics.map(d => `${filename}:${d.line}:${d.column ?? 1}: ${d.severity} [${d.code}] ${d.message}`).join('\n')
+}