mdeck 3.11.0 → 3.12.1

package/src/build/include.js

@@ -0,0 +1,249 @@
+// Decks made of other decks. A slide that is nothing but
+//
+//   :::include ./lectures/02-graphs.md
+//   :::include ./lectures/02-graphs.md slides=3-7
+//
+// stands for the slides of that file (core/parseSlides.js includeOf), which
+// stays a deck of its own: `mdeck run 02-graphs.md` presents it alone, and its
+// settings (theme, title, time …) count only then; included, only its slides
+// are taken. `slides=` keeps some of them, numbered as that file shows them.
+//
+// Everything that reads a deck to show it reads it through expandDeck, which
+// puts the slides in place of the include: the dev server, builds, `mdeck
+// check`, the launch page. What writes into a deck (the editor, saved times,
+// slide ids for drawings) writes into the file a slide is written in; the
+// editor shows an include as a card naming the file.
+//
+// So that a slide keeps its drawings however many slides come before it, the
+// expanded deck gives every slide an id: a slide of the deck itself keeps the
+// one it has in its file (slide-3 stays slide-3), an included slide gets its
+// file's name in front (graphs-slide-3, graphs-dijkstra). `origins` says, for
+// each such id, the file the slide is written in and its id there.
+//
+// What an included deck's slides need from its settings comes along; how
+// it looks and is presented stays the including deck's. `hotspots` and
+// `time` become each included slide's own, unless it has one: a slide
+// without a time gets its share of the included deck's `time`. The
+// references (`bibliography`, `nocite`, and `csl` when the deck has none),
+// the `components` folders (and a components/ folder beside the file) and
+// callout names of its own (`callouts`, where the deck does not name them)
+// are added to the including deck's settings. Theme, palette, size,
+// language, labels, `show`, `meta` and the server stay the including deck's.
+//
+// Paths of pictures and media in an included file are written from its own
+// folder; they are rewritten to work from the deck's. A deck in several
+// languages (talk.de.md) takes an included file's twin in its language
+// (02-graphs.de.md) where there is one.
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve, dirname, relative, basename, sep } from 'node:path'
+import { parseSlides } from '../core/parseSlides.js'
+import { setSlideMeta, setDeckConfig, shareSlides } from '../core/editDeck.js'
+import { diagnostic } from '../core/source.js'
+import { languageOfFile } from '../core/languages.js'
+import { planFor, formatTime } from '../core/timing.js'
+import { CALLOUT_TYPES } from '../core/labels.js'
+import { isPlainObject, DECK_KEYS, SLIDE_KEYS } from '../core/parseSlides.js'
+import { parseSlideNumbers } from '../cli/args.js'
+import { rewriteAssetRefs } from './slidesPlugin.js'
+import { deckTexts } from './bibliography.js'
+import { scanCitations, citedKeys } from '../core/citations.js'
+import { replaceTagsIn } from '../core/tags.js'
+
+const read = file => readFileSync(file, 'utf8')
+
+/** Whether the deck text has an include at all. */
+export const hasIncludes = source => parseSlides(source).slides.some(slide => slide.include)
+
+/**
+ * The deck in `file` (or `source`, its text) with its includes in place:
+ * { source, files, origins, diagnostics }. `files` are the included files
+ * (to watch), `origins` maps each slide id to { file, id } (null when the
+ * deck includes nothing), `diagnostics` are problems with the includes:
+ * { file, line, severity, code, message }. Without includes, `source` is
+ * the deck's text unchanged.
+ */
+export function expandDeck(file, { source = null, lang = null } = {}) {
+  const abs = resolve(file)
+  const text = source ?? read(abs)
+  if (!hasIncludes(text)) return { source: text, files: [], origins: null, diagnostics: [] }
+  const deck = parseSlides(text)
+  const state = { root: dirname(abs), files: new Set(), diagnostics: [], prefixes: new Set(), origins: {}, settings: [] }
+  const language = lang ?? languageOfFile(basename(abs))?.lang ?? (typeof deck.deckConfig.lang === 'string' ? deck.deckConfig.lang : null)
+  let expanded = expandFile(abs, text, { state, language, stack: [abs], prefix: null, top: true })
+  const patch = addedSettings(deck.deckConfig, state)
+  if (patch) expanded = setDeckConfig(parseSlides(expanded), patch)
+  return { source: expanded, files: [...state.files], origins: state.origins, diagnostics: state.diagnostics }
+}
+
+/** The deck's text with its includes in place, or its text as it is when there are none. */
+export const expandedSource = (file, options) => expandDeck(file, options).source
+
+// One file's slides, ids given, its own includes in place, paths written from
+// the deck's folder; the top file keeps its settings in front.
+function expandFile(abs, source, { state, language, stack, prefix, top }) {
+  let deck = parseSlides(source)
+  // Where each include is written, for messages, before ids change the lines.
+  const lines = deck.slides.filter(slide => slide.include).map(slide => {
+    const at = slide.source.start + source.slice(slide.source.start, slide.source.end).indexOf(':::')
+    return diagnostic(source, '', '', at).line
+  })
+  // Each slide gets the id it has in its own file, written out, with the
+  // file's name in front when it is included.
+  for (const slide of [...deck.slides]) {
+    if (slide.include) continue
+    const own = slide.id
+    const id = prefix ? `${prefix}-${own}` : own
+    state.origins[id] = { file: abs, id: own }
+    if (slide.meta.id === id) continue
+    source = setSlideMeta(deck, own, { id })
+    deck = parseSlides(source)
+  }
+  const fromHere = dirname(abs)
+  const moved = fromHere !== state.root
+  const own = text => moved ? rewriteAssetRefs(text, ref => relative(state.root, resolve(fromHere, ref)).split(sep).join('/')) : text
+  let included = 0
+  const chunks = deck.slides.map(slide => {
+    const text = deck.source.slice(slide.source.start, slide.source.end)
+    if (!slide.include) return own(text)
+    return includeText(abs, slide, lines[included++], { state, language, stack, prefix }) ?? own(text)
+  }).filter(chunk => chunk.trim())
+  const body = chunks.map(chunk => chunk.replace(/^\s*\n/, '').replace(/\s*$/, '\n')).join('\n---\n\n')
+  return top ? deck.source.slice(0, deck.slides[0]?.source.start ?? 0) + body : body
+}
+
+// The slides an include stands for, or null (with a diagnostic) when they cannot be had.
+function includeText(abs, slide, line, { state, language, stack, prefix }) {
+  const { file, slides } = slide.include
+  const problem = (code, message) => {
+    state.diagnostics.push({ file: abs, line, severity: 'error', code, message })
+    return null
+  }
+  const target = chooseFile(dirname(abs), file, language)
+  if (!existsSync(target)) return problem('missing-include', `Included file not found: ${file}`)
+  if (stack.includes(target)) return problem('include-loop', `${file} includes this file again (${[...stack, target].map(f => basename(f)).join(' → ')})`)
+  let numbers = null
+  if (slides != null) {
+    try { numbers = parseSlideNumbers(slides) } catch (error) { return problem('invalid-include', error.message.replace('--slide', 'slides=')) }
+  }
+  state.files.add(target)
+  const childPrefix = uniquePrefix(state, prefix, target)
+  const source = read(target)
+  const settings = parseSlides(source).deckConfig ?? {}
+  state.settings.push({ file: target, settings })
+  // `time:` or `hotspots:` alone at the top is the file's, for all its
+  // slides; meant for its first slide, it belongs in a :::meta block.
+  const keys = Object.keys(settings)
+  if (keys.length && keys.every(key => DECK_KEYS.has(key) && SLIDE_KEYS.has(key)) && !state.diagnostics.some(d => d.file === target && d.code === 'include-settings')) {
+    state.diagnostics.push({ file: target, line: 1, severity: 'warning', code: 'include-settings', message: `The block at the top (${keys.join(', ')}) is read as this file's settings, for all its slides; for its first slide alone, write it in a :::meta block` })
+  }
+  let text = ownReferences(inherit(expandFile(target, source, { state, language, stack: [...stack, target], prefix: childPrefix, top: false }), settings), settings)
+  if (numbers) {
+    try { text = shareSlides(text, { slides: numbers }).source } catch (error) { return problem('invalid-include', `${file}: ${error.message}`) }
+  }
+  return text
+}
+
+// The included deck's `hotspots` and `time`, as each of its slides' own
+// where it has none; `time` is shared out as the deck itself would (its
+// slides' own times first, the rest in equal parts).
+function inherit(text, { hotspots, time }) {
+  if (hotspots == null && time == null) return text
+  let deck = parseSlides(text)
+  const plan = time == null ? null : planFor(deck.slides, { time })
+  for (const [i, slide] of [...deck.slides].entries()) {
+    if (slide.include) continue
+    const patch = {}
+    if (hotspots != null && slide.meta.hotspots == null) patch.hotspots = hotspots
+    if (plan?.budget && slide.meta.time == null && plan.perSlide[i] >= 1) patch.time = formatTime(plan.perSlide[i])
+    if (!Object.keys(patch).length) continue
+    text = setSlideMeta(deck, slide.id, patch)
+    deck = parseSlides(text)
+  }
+  return text
+}
+
+// An included deck's <bibliography /> lists the works that deck cites (and
+// its `nocite`), as it does when shown alone, not every work the including
+// deck cites: it gets them as `keys`. With `nocite: '*'` it lists them all.
+function ownReferences(text, { nocite }) {
+  const named = [nocite ?? []].flat().map(key => String(key).replace(/^@/, ''))
+  if (!/<bibliography\b/.test(text) || named.includes('*')) return text
+  const keys = [...new Set([...citedKeys(deckTexts(text).flatMap(part => scanCitations(part))), ...named])].join(' ')
+  return replaceTagsIn(text, tag => {
+    if (tag.closing || tag.name !== 'bibliography' || 'keys' in tag.attrs) return
+    return tag.raw.replace(/(\s*)(\/?>)$/, ` keys="${keys}"$1$2`)
+  })
+}
+
+// What the included decks add to the including deck's settings, or null.
+function addedSettings(config, { root, settings: included }) {
+  const fromRoot = (file, path) => {
+    if (typeof path !== 'string' || !path.trim()) return null
+    const trimmed = path.trim()
+    if (trimmed === '~' || trimmed.startsWith('~/') || trimmed.startsWith('/')) return trimmed
+    return relative(root, resolve(dirname(file), trimmed)).split(sep).join('/') || '.'
+  }
+  const list = value => [value ?? []].flat()
+  const patch = {}
+  const bibliography = list(config.bibliography)
+  const nocite = list(config.nocite)
+  const components = list(config.components)
+  const callouts = isPlainObject(config.callouts) ? { ...config.callouts } : {}
+  const known = new Set([...CALLOUT_TYPES, ...Object.keys(callouts)].map(name => name.toLowerCase()))
+  let csl = config.csl ?? null
+  for (const { file, settings } of included) {
+    for (const path of list(settings.bibliography)) { const own = fromRoot(file, path); if (own && !bibliography.includes(own)) bibliography.push(own) }
+    for (const key of list(settings.nocite)) if (!nocite.includes(key)) nocite.push(key)
+    if (csl == null && typeof settings.csl === 'string') csl = patch.csl = /\.csl$/i.test(settings.csl) ? fromRoot(file, settings.csl) : settings.csl
+    const folders = [...list(settings.components), ...(existsSync(resolve(dirname(file), 'components')) ? ['components'] : [])]
+    for (const path of folders) { const own = fromRoot(file, path); if (own && !components.includes(own) && resolve(root, own) !== resolve(root, 'components')) components.push(own) }
+    if (isPlainObject(settings.callouts)) {
+      for (const [name, title] of Object.entries(settings.callouts)) {
+        if (known.has(name.toLowerCase())) continue
+        callouts[name] = title
+        known.add(name.toLowerCase())
+      }
+    }
+  }
+  if (bibliography.length > list(config.bibliography).length) patch.bibliography = bibliography
+  if (nocite.length > list(config.nocite).length) patch.nocite = nocite
+  if (components.length > list(config.components).length) patch.components = components
+  if (Object.keys(callouts).length > Object.keys(isPlainObject(config.callouts) ? config.callouts : {}).length) patch.callouts = callouts
+  return Object.keys(patch).length ? patch : null
+}
+
+// The file in the deck's language where there is one: ./02-graphs.md in a
+// German deck is ./02-graphs.de.md beside it.
+function chooseFile(dir, ref, language) {
+  const abs = resolve(dir, ref)
+  if (language && /\.md$/i.test(abs) && !languageOfFile(basename(abs))) {
+    const twin = abs.replace(/\.md$/i, `.${language}.md`)
+    if (existsSync(twin)) return twin
+  }
+  return abs
+}
+
+// An id prefix from the file's name, unique in the deck: 02-graphs.md → graphs.
+function uniquePrefix(state, parent, file) {
+  const name = languageOfFile(basename(file))?.name ?? basename(file).replace(/\.md$/i, '')
+  const base = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^[^a-z]+|-+$/g, '') || 'part'
+  const full = parent ? `${parent}-${base}` : base
+  let prefix = full, n = 2
+  while (state.prefixes.has(prefix)) prefix = `${full}-${n++}`
+  state.prefixes.add(prefix)
+  return prefix
+}
+
+/**
+ * An included file's problems without those in its settings, which count
+ * only when it is shown alone (its theme need not be installed for the
+ * deck that includes it).
+ */
+export function withoutSettings(source, diagnostics) {
+  const range = parseSlides(source).configSource
+  if (!range) return diagnostics
+  return diagnostics.filter(d => d.offset == null || d.offset < range.start || d.offset > range.end)
+}
+
+/** Include problems as lines for the terminal, file:line: severity [code] message. */
+export const formatIncludeDiagnostics = diagnostics => diagnostics.map(d => `${d.file}:${d.line}:1: ${d.severity} [${d.code}] ${d.message}`).join('\n')

package/src/build/inkPlugin.js

@@ -20,6 +20,7 @@ import { slug } from '../live/code.js'
 import { inkFileFor, normalizeInk, emptyInk, applyOp, serializeInk } from '../core/ink.js'
 import { hashSource, isAllowedRequest, send, readJson, BACKUP_DIR } from './editorPlugin.js'
 import { markOwnWrite } from './ownWrites.js'
+import { expandDeck } from './include.js'
 
 const ID_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/
 const BACKUPS_KEPT = 10
@@ -119,13 +120,22 @@ export function createInkFile(deckPath, { debounceMs = 300, onChange = () => {}
       const renamed = []
       const seen = deckHash
       const alias = new Map(renames.filter(r => r.before === seen).map(r => [r.from, r.to]))
+      // The slides of files the deck includes (include.js) are not in its
+      // text; their ids carry their file's name and stay where they are.
+      let fromIncludes = null
+      const included = id => {
+        if (!fromIncludes) {
+          try { fromIncludes = new Set(Object.entries(expandDeck(abs, { source }).origins ?? {}).filter(([, origin]) => origin.file !== abs).map(([shown]) => shown)) } catch { fromIncludes = new Set() }
+        }
+        return fromIncludes.has(id)
+      }
       for (const raw of Array.isArray(ops) ? ops : []) {
         const op = { ...raw, slideId: alias.get(raw?.slideId) ?? raw?.slideId }
         if (op.type === 'add') {
           const index = deck.slides.findIndex(slide => slide.id === op.slideId)
-          if (index < 0) return { status: 409, error: `No slide "${op.slideId}" in the deck any more`, deckHash: hash }
+          if (index < 0 && !included(op.slideId)) return { status: 409, error: `No slide "${op.slideId}" in the deck any more`, deckHash: hash }
           const slide = deck.slides[index]
-          if (slide.meta.id == null) {
+          if (slide && slide.meta.id == null) {
             // An id by position: only trusted for the deck the device saw.
             if (deckHash !== hash) return { status: 409, error: 'The deck changed; reload', deckHash: hash }
             const id = newSlideId(deck, slide, index)

package/src/build/relayAccess.js

@@ -5,6 +5,7 @@ import { shareable, resourceKey } from './tunnelClient.js'
 import { collectLocalAssetRefs } from './slidesPlugin.js'
 import { parseSlides } from '../core/parseSlides.js'
 import { sessionCode } from '../live/code.js'
+import { expandedSource } from './include.js'
 
 const canonical = file => { try { return realpathSync(file) } catch { return null } }
 
@@ -20,7 +21,8 @@ export function createRelayAccess(server, slidesPath) {
   let knownSource = null
   return async (address, method) => {
     let source
-    try { source = readFileSync(slidesPath, 'utf8') } catch { return false }
+    // The deck as shown, so the pictures of included slides can be reached too.
+    try { source = expandedSource(slidesPath) } catch { return false }
     if (source !== knownSource) { knownFiles.clear(); knownSource = source }
     const resources = new Set(bootstrap.map(path => resourceKey(at(path))))
     const files = new Map()

package/src/build/renderCheck.js

@@ -13,8 +13,28 @@ import { launchChrome } from './chrome.js'
 import { frameworkRoot } from '../paths.js'
 import { parseSlides } from '../core/parseSlides.js'
 import { MEASURE, RECORDER, settle } from './themeCheck.js'
+import { expandDeck } from './include.js'
 
 // Each slide's number, line and heading, for messages.
+// The labels of the deck as shown, its includes in place (include.js); a
+// slide from an included file names that file and its line there.
+export function deckLabels(slidesPath) {
+  const abs = resolve(slidesPath)
+  const { source, origins } = expandDeck(abs)
+  const labels = slideLabels(source)
+  if (!origins) return labels
+  const byFile = new Map()
+  const lineIn = (file, id) => {
+    if (!byFile.has(file)) byFile.set(file, slideLabels(readFileSync(file, 'utf8')))
+    return byFile.get(file).find(label => label.id === id)?.line ?? 1
+  }
+  return labels.map(label => {
+    const origin = origins[label.id]
+    if (!origin) return label
+    return { ...label, line: lineIn(origin.file, origin.id), ...(origin.file !== abs ? { file: origin.file } : {}) }
+  })
+}
+
 export function slideLabels(source) {
   return parseSlides(source).slides.map((slide, index) => {
     // The slide's first written line, past its settings and blank lines.
@@ -58,7 +78,7 @@ async function withDeckPage(slidesPath, { appearance = '', width = 1600, height
 // 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'))
+  const labels = deckLabels(slidesPath)
   return withDeckPage(slidesPath, {}, async ({ page, count, show }) => {
     const diagnostics = []
     for (let index = 0; index < count; index++) {
@@ -70,7 +90,7 @@ export function renderCheck(slidesPath) {
       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 })
+      for (const problem of shown) diagnostics.push({ severity: 'warning', code: 'render', message: `${where}: ${problem}`, line: label.line, ...(label.file ? { file: label.file } : {}) })
     }
     // 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 })
@@ -85,7 +105,7 @@ export function renderCheck(slidesPath) {
 // written.
 export async function snapshot(slidesPath, { slides = [], outDir, width = 1280, height = 720, appearance = '', sheet = false } = {}) {
   const name = basename(slidesPath).replace(/\.md$/i, '')
-  const labels = sheet ? slideLabels(readFileSync(slidesPath, 'utf8')) : []
+  const labels = sheet ? deckLabels(slidesPath) : []
   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)

package/src/build/slidesPlugin.js

@@ -16,6 +16,7 @@ import { marked } from 'marked'
 import { scanTags, replaceTagsIn, withAttribute } from '../core/tags.js'
 import { resolveBibliography, sampleBibliography } from './bibliography.js'
 import { languageOfFile, languageFiles } from '../core/languages.js'
+import { expandDeck, withoutSettings } from './include.js'
 
 const VIRTUAL_ID = 'virtual:slides'
 const RESOLVED_ID = '\0virtual:slides'
@@ -174,6 +175,27 @@ function outsideCodeFences(markdown, fn) {
   return out + fn(text)
 }
 
+// The local files a part of a deck names, each changed by `map(ref)` (the new
+// ref, or null to keep it): Markdown pictures (also those in a tag's
+// attributes, such as a poll's options), the `src` of pictures and media, and
+// `image:` and `logo:` settings. For an included file (include.js), whose
+// paths are written from its own folder. Paths from the root (/…) stay.
+export function rewriteAssetRefs(markdown, map) {
+  const swap = ref => (isLocalAssetRef(ref) && !ref.startsWith('/') ? map(ref) ?? ref : ref)
+  return outsideCodeFences(markdown, text => {
+    let out = text.replace(/(!\[[^\]]*\]\()([^)\s]+)/g, (m, head, ref) => head + swap(ref))
+    out = replaceTagsIn(out, tag => {
+      if (tag.closing || !(PICTURE_TAGS.has(tag.name) || MEDIA_TAGS.has(tag.name)) || !tag.attrs.src) return
+      const next = swap(tag.attrs.src)
+      return next === tag.attrs.src ? undefined : withAttribute(tag, 'src', next)
+    })
+    return out.replace(/^(\s*)(image|logo):\s*(["']?)([^"'\n]+)\3\s*$/gm, (m, indent, key, quote, value) => {
+      const next = swap(value.trim())
+      return next === value.trim() ? m : `${indent}${key}: ${quote || '"'}${next}${quote || '"'}`
+    })
+  })
+}
+
 export function maybeInlineAssets(markdown, abs, { inlineImages, inlineMedia }) {
   if (!inlineImages && !inlineMedia) return markdown
   const baseDir = dirname(abs)
@@ -232,7 +254,17 @@ export function deckLanguages(abs) {
 // the deck's other languages along, for `mdeck run`; a built file has one.
 export function slidesPlugin(slidesPath, { languages = false, inlineImages = false, inlineMedia = false, editor = false, stripNotes = false, stripActivities = false, slides = null, ink = true, results = true, embedFonts: embedThemeFonts = false, deckLook = false, source: given = null } = {}) {
   const abs = resolve(slidesPath)
-  const readDeck = () => given ?? readFileSync(abs, 'utf-8')
+  // The deck as shown: other files it includes in place (include.js).
+  const readRaw = () => given ?? readFileSync(abs, 'utf-8')
+  const expand = (file, source) => given === null ? expandDeck(file, { source }) : { source, files: [], diagnostics: [] }
+  const readDeck = () => expand(abs, readRaw()).source
+  // The files the deck and its other languages include, from the last load;
+  // the dev server may serve their folders, for their pictures.
+  let included = [], devServer = null
+  const allowIncluded = () => {
+    const allow = devServer?.config.server.fs.allow
+    if (allow) for (const dir of included.map(file => dirname(file))) if (!allow.includes(dir)) allow.push(dir)
+  }
   const watchDeck = context => { if (given === null) context.addWatchFile(abs) }
   const sourceFor = raw => {
     const shared = stripNotes ? stripNotesFrom(raw) : raw
@@ -286,6 +318,7 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
     name: 'vite-plugin-slides',
     configResolved(config) { serving = config.command === 'serve' },
     configureServer(server) {
+      devServer = server
       server.watcher.add([abs, inkPath, ...watchDirs()])
       const refresh = file => {
         if (isWatched(file)) reload(server, ALL_IDS, resolve(file))
@@ -308,28 +341,35 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
     load(id) {
       if (id === RESOLVED_ID) {
         watchDeck(this)
-        const raw = readDeck()
+        const raw = readRaw()
         const registry = loadRegistry(abs)
         for (const warning of registry.warnings) this.warn(warning)
-        const diagnostics = validateDeck(parseSlides(raw), {
-          layouts: manifestsOf(registry, 'layout'), themes: manifestsOf(registry, 'theme'), palettes: manifestsOf(registry, 'palette'),
-        })
+        const manifests = { layouts: manifestsOf(registry, 'layout'), themes: manifestsOf(registry, 'theme'), palettes: manifestsOf(registry, 'palette') }
+        // Each file is checked as it is written, so that messages name its lines.
+        const expansion = expand(abs, raw)
+        const diagnostics = [...validateDeck(parseSlides(raw), manifests), ...expansion.diagnostics]
+        for (const file of expansion.files) {
+          const text = readFileSync(file, 'utf-8')
+          diagnostics.push(...withoutSettings(text, validateDeck(parseSlides(text), manifests)).map(d => ({ ...d, file })))
+        }
         const errors = diagnostics.filter(d => d.severity === 'error')
         if (errors.length && !editor) throw new Error(formatDiagnostics(errors, abs))
         if (diagnostics.length) this.warn(formatDiagnostics(diagnostics, abs))
-        const source = maybeInlineAssets(sourceFor(raw), abs, { inlineImages, inlineMedia })
+        const source = maybeInlineAssets(sourceFor(expansion.source), abs, { inlineImages, inlineMedia })
         // The other languages are read as they are: `mdeck check` checks each file.
         const others = otherLanguages()
         languageWatch = others.map(({ file }) => file)
         for (const file of languageWatch) this.addWatchFile(file)
+        const otherSources = others.map(({ lang, file }) => ({ lang, file, ...expand(file, readFileSync(file, 'utf-8')) }))
+        included = [...new Set([...expansion.files, ...otherSources.flatMap(other => other.files)])]
+        for (const file of included) this.addWatchFile(file)
+        allowIncluded()
         for (const { file } of others) {
-          const found = validateDeck(parseSlides(readFileSync(file, 'utf-8')), {
-            layouts: manifestsOf(registry, 'layout'), themes: manifestsOf(registry, 'theme'), palettes: manifestsOf(registry, 'palette'),
-          })
+          const found = validateDeck(parseSlides(readFileSync(file, 'utf-8')), manifests)
           if (found.length) this.warn(formatDiagnostics(found, file))
         }
         const translations = others.length && fileLanguage
-          ? { [fileLanguage]: source, ...Object.fromEntries(others.map(({ lang, file }) => [lang, maybeInlineAssets(sourceFor(readFileSync(file, 'utf-8')), file, { inlineImages, inlineMedia })])) }
+          ? { [fileLanguage]: source, ...Object.fromEntries(otherSources.map(({ lang, file, source: text }) => [lang, maybeInlineAssets(sourceFor(text), file, { inlineImages, inlineMedia })])) }
           : {}
         return `export default ${JSON.stringify(source)}\nexport const language = ${JSON.stringify(fileLanguage)}\nexport const languages = ${JSON.stringify(translations)}`
       }
@@ -341,7 +381,7 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
         // import. The dev server's watcher notices the file once it appears.
         if (existsSync(inkPath)) this.addWatchFile(inkPath)
         let size = {}
-        try { const config = parseSlides(readDeck()).deckConfig ?? {}; size = { width: config.width ?? 1920, height: config.height ?? 1080 } } catch {}
+        try { const config = parseSlides(readRaw()).deckConfig ?? {}; size = { width: config.width ?? 1920, height: config.height ?? 1080 } } catch {}
         let data = emptyInk(size)
         if (ink && existsSync(inkPath)) {
           try { data = normalizeInk(JSON.parse(readFileSync(inkPath, 'utf-8')), size) } catch (error) { this.warn(`${inkPath}: ${error.message}; showing no ink`) }
@@ -389,7 +429,7 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
         for (const record of registry.records) this.addWatchFile(record.file)
         if (!deckLook) return generateExtensionsModule(registry)
         let config = {}
-        try { config = parseSlides(readDeck()).deckConfig ?? {} } catch {}
+        try { config = parseSlides(readRaw()).deckConfig ?? {} } catch {}
         return generateExtensionsModule(deckLookOnly(registry, config))
       }
       if (id === RESOLVED_COMPONENTS_ID) {
@@ -409,7 +449,7 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
     async transformIndexHtml(html, context) {
       if (!/(^|[\/])index\.html$/.test(context.filename ?? context.path ?? '')) return html
       let config = {}
-      try { config = parseSlides(readDeck()).deckConfig ?? {} } catch {}
+      try { config = parseSlides(readRaw()).deckConfig ?? {} } catch {}
       const lang = config.lang ?? fileLanguage
       if (typeof lang === 'string' && /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) html = html.replace(/<html lang="[^"]*"/, `<html lang="${lang}"`)
       if (embedThemeFonts) {
@@ -430,10 +470,12 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
       // windows mid-talk: the pages refresh their ink on `mdeck:ink` instead.
       // The results file is written during the talk and read only by builds.
       if (changed === resultsPath) return []
-      const own = [inkPath, abs].includes(changed) && (() => { try { return isOwnWrite(changed, readFileSync(changed, 'utf-8')) } catch { return false } })()
+      // An included file counts as the deck (saved times are written into it too).
+      const deckFile = changed === abs || included.includes(changed)
+      const own = (changed === inkPath || deckFile) && (() => { try { return isOwnWrite(changed, readFileSync(changed, 'utf-8')) } catch { return false } })()
       if (own) {
-        invalidate(server, changed === abs ? SOURCE_IDS : [RESOLVED_INK_ID])
-        return changed === abs ? bibUpdate(server) : []
+        invalidate(server, deckFile ? SOURCE_IDS : [RESOLVED_INK_ID])
+        return deckFile ? bibUpdate(server) : []
       }
       if (changed === inkPath) {
         reload(server, [RESOLVED_INK_ID], changed)
@@ -450,6 +492,12 @@ export function slidesPlugin(slidesPath, { languages = false, inlineImages = fal
         server.ws.send({ type: 'full-reload' })
         return []
       }
+      if (included.includes(changed)) {
+        invalidate(server, SOURCE_IDS)
+        if (editor) return bibUpdate(server)
+        server.ws.send({ type: 'full-reload' })
+        return []
+      }
       if (changed === abs) {
         if (followComponentFolders(server)) {
           reload(server, ALL_IDS, changed)

package/src/build/timingPlugin.js

@@ -9,7 +9,8 @@
 // only written when the deck still has the slides the page saw (`ids`);
 // otherwise the answer is 409. The deck is copied to .mdeck-backups/ before
 // the first write, and the write does not reload the open windows
-// (ownWrites.js).
+// (ownWrites.js). A slide from another file the deck includes (include.js)
+// gets its time in that file, as that file's own slide.
 import { readFileSync, writeFileSync, renameSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { parseSlides } from '../core/parseSlides.js'
@@ -17,37 +18,52 @@ import { setSlideMeta } from '../core/editDeck.js'
 import { parseTime, formatTime } from '../core/timing.js'
 import { isAllowedRequest, send, readJson, backupDeck } from './editorPlugin.js'
 import { markOwnWrite } from './ownWrites.js'
+import { expandDeck } from './include.js'
 
 export function createTimingFile(deckPath) {
   const abs = resolve(deckPath)
-  let backedUp = false
-  const read = () => { const source = readFileSync(abs, 'utf8'); return { source, deck: parseSlides(source) } }
+  const backedUp = new Set()
+  // The deck as shown, and for each slide the file it is written in.
+  const shown = () => {
+    const { source, origins } = expandDeck(abs)
+    return { deck: parseSlides(source), origins }
+  }
 
   return {
     path: abs,
-    ids: () => read().deck.slides.map(slide => slide.id),
+    ids: () => shown().deck.slides.map(slide => slide.id),
     save(ids, times) {
-      let { source, deck } = read()
-      const current = deck.slides.map(slide => slide.id)
+      const { deck: whole, origins } = shown()
+      const current = whole.slides.map(slide => slide.id)
       if (!Array.isArray(ids) || ids.join('\n') !== current.join('\n')) return { status: 409, error: 'The deck changed since the rehearsal began; rehearse again', ids: current }
-      const before = source
-      let changed = 0
+      // The new times, by the file the slide is written in and its id there.
+      const files = new Map()
       for (const [id, value] of Object.entries(times ?? {})) {
         if (!current.includes(id)) return { status: 400, error: `No slide "${id}" in the deck` }
         const seconds = value == null ? null : parseTime(value)
         if (value != null && seconds == null) return { status: 400, error: `"${value}" is not a time` }
         const time = seconds == null ? undefined : formatTime(seconds)
-        if (deck.slides.find(slide => slide.id === id).meta.time === time) continue
-        source = setSlideMeta(deck, id, { time })
-        deck = parseSlides(source)
-        changed++
+        if (whole.slides.find(slide => slide.id === id).meta.time === time) continue
+        const { file, id: own } = origins?.[id] ?? { file: abs, id }
+        if (!files.has(file)) files.set(file, [])
+        files.get(file).push([own, time])
+      }
+      let changed = 0
+      for (const [file, entries] of files) {
+        const before = readFileSync(file, 'utf8')
+        let source = before, deck = parseSlides(source)
+        for (const [id, time] of entries) {
+          source = setSlideMeta(deck, id, { time })
+          deck = parseSlides(source)
+          changed++
+        }
+        if (source === before) continue
+        if (!backedUp.has(file)) { backupDeck(file, before); backedUp.add(file) }
+        markOwnWrite(file, source)
+        const temp = `${file}.${process.pid}.tmp`
+        writeFileSync(temp, source, 'utf8')
+        renameSync(temp, file)
       }
-      if (source === before) return { status: 200, ok: true, changed: 0 }
-      if (!backedUp) { backupDeck(abs, before); backedUp = true }
-      markOwnWrite(abs, source)
-      const temp = `${abs}.${process.pid}.tmp`
-      writeFileSync(temp, source, 'utf8')
-      renameSync(temp, abs)
       return { status: 200, ok: true, changed }
     },
   }

package/src/cli/args.js

@@ -4,8 +4,8 @@ const common = { '--port': value, '--no-open': flag }
 const output = { '--output': value, '-o': '--output', '--no-drawings': flag, '--no-results': flag }
 const commands = {
   new: { max: 0 },
-  run: { ...common, '--network': flag, '--server': optional, max: 1 },
-  rehearse: { ...common, '--network': flag, '--server': optional, max: 1 },
+  run: { ...common, '--network': flag, '--server': optional, '--no-server': flag, max: 1 },
+  rehearse: { ...common, '--network': flag, '--server': optional, '--no-server': flag, max: 1 },
   edit: { ...common, max: 1 },
   design: { ...common, max: 1 },
   themes: { '--local': flag, '--force': flag, '--check': flag, '--output': value, '-o': '--output', max: 4 },
@@ -22,7 +22,7 @@ const commands = {
   server: { '--port': value, '--host': optional, max: 0 },
   skill: { '--print': flag, '--install': 'list', '--project': flag, max: 0 },
   migrate: { '--dry-run': flag, max: 1 },
-  results: { '--output': value, '-o': '--output', max: 1 },
+  results: { '--output': value, '-o': '--output', '--summary': flag, '--json': flag, max: 1 },
 }
 
 export function validateServerOrigin(address) {