mdeck 3.11.0 → 3.12.1

package/src/cli/index.js

@@ -13,6 +13,7 @@ import { BACKUP_DIR } from '../build/editorPlugin.js'
 import { createEditorServer, createDesignServer } from '../build/editorServer.js'
 import { homePlugin } from '../build/homePlugin.js'
 import { checkDeck, bibliographyDiagnostics } from '../build/check.js'
+import { expandedSource } from '../build/include.js'
 import { livePlugin, startLiveServer } from '../live/server.js'
 import { inkPlugin } from '../build/inkPlugin.js'
 import { resultsPlugin } from '../build/resultsPlugin.js'
@@ -30,7 +31,8 @@ import { parseSlides } from '../core/parseSlides.js'
 import { stripNotes as stripNotesFrom, shareSlides } from '../core/editDeck.js'
 import { parseArgs, parseSlideNumbers, validateServerOrigin } from './args.js'
 import { assertDrawings } from '../build/drawings.js'
-import { resultsFileFor, normalizeResults, resultsCsv } from '../core/results.js'
+import { resultsFileFor, normalizeResults } from '../core/results.js'
+import { resultsReport, reportAnswersCsv, reportSummaryCsv, reportJson } from '../core/resultsReport.js'
 import { createRelayAccess } from '../build/relayAccess.js'
 import { sessionCode } from '../live/code.js'
 import { migrateDeck } from './migrate.js'
@@ -59,6 +61,14 @@ function hasFlag(name, short = null) { return !!(parsed.options[name] ?? parsed.
 const positionals = () => parsed.positionals
 const outputOption = () => parsed.options['--output'] ?? null
 const serverOption = () => parsed.options['--server']
+// Whether a poll server answers at `address`, within a few seconds.
+async function serverAnswers(address) {
+  try {
+    validateServerOrigin(address)
+    const response = await fetch(new URL('info', address.replace(/\/*$/, '/')), { signal: AbortSignal.timeout(3000) })
+    return response.ok
+  } catch { return false }
+}
 const portOption = () => parsed.options['--port'] ?? null
 // --slide 3,5-7 for build, send and pdf: only these slides, numbered as written.
 function slideOption(input) {
@@ -196,7 +206,8 @@ async function copyLocalAssets(slidesPath, outDir, { stripNotes = false, stripAc
   const absSlides = resolve(slidesPath)
   const deckDir = dirname(absSlides)
   const absOutDir = resolve(outDir)
-  const raw = readFileSync(absSlides, 'utf-8')
+  // The deck as shown: pictures of included slides are copied too.
+  const raw = expandedSource(absSlides)
   let markdown = stripNotes ? stripNotesFrom(raw) : raw
   if (stripActivities || slides) markdown = shareSlides(markdown, { activities: stripActivities, slides }).source
 
@@ -323,7 +334,10 @@ const HELP = `
       --network              reach the slides from phones and tablets on the same network
       --server [address]     present from an iPad on any network, through your server
                              (the address, or the deck's server setting, or MDECK_SERVER;
-                              the key in MDECK_SERVER_KEY)
+                              the key in MDECK_SERVER_KEY). With both MDECK_SERVER and
+                              MDECK_SERVER_KEY set, the server is used without --server
+                              when it answers
+      --no-server            present from this computer only, even with MDECK_SERVER set
       --no-open   --port <number>
     ${c.green}mdeck rehearse${c.reset} [slides.md]                Like run, but opens the presenter view rehearsing: it times
                                               each slide and saves the times into the deck (time: 1m30s)
@@ -361,7 +375,9 @@ const HELP = `
       --slide <numbers>      only these slides: 3, 3,5 or 2-4
       --sheet                one picture of them all in a grid, each under its number and heading
       --dark | --light       in this appearance instead of the deck's own   -o <folder>
-    ${c.green}mdeck results${c.reset} [slides.md] [-o answers.csv]  The answers kept in the talk, as CSV (room, phone, time, answer)
+    ${c.green}mdeck results${c.reset} [slides.md] [-o answers.csv]  The answers kept in the talk, as CSV: slide, question, phone, time, answer
+      --summary              one row per option, number or word, with how many chose it
+      --json                 everything as JSON: each question, its summary and its answers (also -o answers.json)
     ${c.green}mdeck list${c.reset} [layouts|themes|palettes] [slides.md] [--json]
                                               List built-in and deck-local layouts, themes and palettes
     ${c.green}mdeck starter${c.reset} <layout> [slides.md]        Print starter Markdown for a layout
@@ -375,6 +391,7 @@ const HELP = `
                                               through it (MDECK_SERVER_KEY); put a web server in front
 
   Commands that take ${c.bold}slides.md${c.reset} use the one in the current folder when you leave it out.
+  ${c.green}mdeck --version${c.reset} shows which mdeck this is.
 
   ${c.dim}Install the${c.reset} ${c.bold}mdeck${c.reset} ${c.dim}command globally:${c.reset}
     npm link
@@ -386,6 +403,11 @@ const HELP = `
 // ── Argument parsing ──────────────────────────────────────────────────────────
 const [command, ...argv] = process.argv.slice(2)
 
+if (command === '--version' || command === '-v' || command === 'version') {
+  console.log(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version)
+  process.exit(0)
+}
+
 if (!command || command === '--help' || command === '-h') {
   console.log(HELP)
   process.exit(0)
@@ -491,11 +513,18 @@ if (command === 'new') {
   const input = requireInput('results')
   const file = resultsFileFor(resolve(input))
   if (!existsSync(file)) { err(`No answers kept for ${basename(input)} yet: ${basename(file)} appears beside it once people answer during mdeck run.`); process.exit(1) }
-  let csv
-  try { csv = resultsCsv(normalizeResults(JSON.parse(readFileSync(file, 'utf8')))) } catch (error) { err(`${basename(file)}: ${error.message}`); process.exit(1) }
+  let results
+  try { results = normalizeResults(JSON.parse(readFileSync(file, 'utf8'))) } catch (error) { err(`${basename(file)}: ${error.message}`); process.exit(1) }
+  // Read against the deck as shown, included slides too, for the slide and the question.
+  let deck
+  try { deck = parseSlides(expandedSource(resolve(input))) } catch { deck = parseSlides(readFileSync(resolve(input), 'utf8')) }
+  const report = resultsReport(results, deck)
   const out = outputOption()
-  if (out) { writeFileSync(out, csv); ok(`Saved ${relative(process.cwd(), resolve(out))}`) }
-  else process.stdout.write(csv)
+  const json = hasFlag('--json') || /\.json$/i.test(out ?? '')
+  const text = json ? reportJson(report, { title: deck.deckConfig?.meta?.title ?? basename(input).replace(/\.md$/i, '') })
+    : hasFlag('--summary') ? reportSummaryCsv(report) : reportAnswersCsv(report)
+  if (out) { writeFileSync(out, text); ok(`Saved ${relative(process.cwd(), resolve(out))}`) }
+  else process.stdout.write(text)
 } else if (command === 'check') {
   const input = requireInput('check')
   const registry = registryFor(input)
@@ -565,8 +594,18 @@ if (command === 'new') {
   // (src/build/tunnelClient.js). The dev server then serves under /t/<id>/, the
   // address the iPad uses on the server, and its own addresses follow it. The
   // address is the flag's value, else the deck's server setting, else MDECK_SERVER.
+  // With MDECK_SERVER and MDECK_SERVER_KEY set, the server is used without
+  // --server when it answers; otherwise this computer presents alone.
+  // --no-server keeps it out.
   let relay = null
-  const serverFlag = serverOption()
+  let serverFlag = serverOption()
+  if (serverFlag === undefined && !hasFlag('--no-server') && process.env.MDECK_SERVER && process.env.MDECK_SERVER_KEY) {
+    const address = process.env.MDECK_SERVER
+    if (await serverAnswers(address)) {
+      serverFlag = address
+      tip(`Using your server from MDECK_SERVER (${address}); --no-server presents without it.`)
+    } else tip(`Your server (MDECK_SERVER, ${address}) does not answer: presenting from this computer only.`)
+  }
   if (serverFlag !== undefined) {
     const inDeck = parseSlides(readFileSync(abs, 'utf8')).deckConfig?.server
     const address = serverFlag ?? (typeof inDeck === 'string' ? inDeck : null) ?? process.env.MDECK_SERVER ?? null
@@ -644,7 +683,7 @@ if (command === 'new') {
   // Phones in the room follow the talk (the reader view would show slides ahead).
   if (exposed) for (const url of server.resolvedUrls.network) tip(`Follow:      ${new URL('?view=follow', url).href}`)
   console.log()
-  if (relay) tip(`iPad:        choose "Show pairing code" on the launch page; it opens ${relay.url}`)
+  if (relay) tip(`iPad:        in the presenter view, click the connection icons and choose "iPad" or "Phone clicker"; it opens ${relay.url}`)
   ok(`Watching ${c.cyan}${abs}${c.reset}`)
   tip('Edit and save to reload.\n')
 

package/src/components/Bibliography.jsx

@@ -4,6 +4,9 @@ import { currentBibliography, onBibliography } from '../runtime/citations.js'
 // <bibliography /> on a slide: the deck's reference list, the works it cites
 // plus `nocite`, in the citation style's order. A long list goes over several
 // slides with <bibliography part="1/2" /> and <bibliography part="2/2" />.
+// `keys="a b"` lists only these works; in a deck that includes another, that
+// deck's own list gets the keys it cites (build/include.js), so it shows what
+// it shows alone.
 
 function slice(order, part) {
   const match = String(part ?? '').match(/^\s*(\d+)\s*\/\s*(\d+)\s*$/)
@@ -14,10 +17,12 @@ function slice(order, part) {
   return order.slice((index - 1) * size, index * size)
 }
 
-export default function Bibliography({ part }) {
+export default function Bibliography({ part, keys }) {
   const [bib, setBib] = useState(currentBibliography)
   useEffect(() => onBibliography(setBib), [])
   if (!bib) return <p class="bibliography-hint">Name a reference file in the deck settings, e.g. <code>bibliography: refs.bib</code>.</p>
-  const html = slice(bib.order, part).map(id => bib.entries[id]).join('')
+  const only = keys == null ? null : new Set(String(keys).split(/[\s,]+/).map(key => key.replace(/^@/, '')).filter(Boolean))
+  const order = only ? bib.order.filter(id => only.has(id)) : bib.order
+  const html = slice(order, part).map(id => bib.entries[id]).join('')
   return <div class="bibliography csl-bib-body" dangerouslySetInnerHTML={{ __html: html }} />
 }

package/src/components/Poll.jsx

@@ -7,8 +7,8 @@ import { pollChoices } from '../core/pollList.js'
 import './poll.css'
 
 // <poll room="lunch" question="Where do we eat?" options="Mensa|Thai|Pizza" />
-// On the slide: live bars, the number of answers and the deck's join code
-// (`qr="false"` leaves it out, when the code was on an earlier slide).
+// On the slide: live bars and the number of answers; the deck's join code
+// beside them only with `qr` (the presenter shows it over the slide, J).
 // On the phones, the server's answer page shows one button per option,
 // as described by Poll.phone. Each device has one vote and can change it; the
 // latest one counts.

package/src/components/QrCodeTag.jsx

@@ -7,8 +7,8 @@ import './poll.css'
 
 // <qrcode url="https://example.com" size="240" /> on a slide.
 // <qrcode join />: the deck's join link for audience questions, with the
-// short link below it, so a slide early in the talk can invite everyone once
-// and the questions after it can leave out their own code (`qr="false"`).
+// short link below it, for a slide that invites everyone (the presenter view
+// can also put it over any slide, J).
 // <qrcode follow />: the link for following the slides on a phone or laptop.
 
 function JoinQr({ size }) {

package/src/components/WordCloud.jsx

@@ -1,15 +1,15 @@
 import { h } from 'preact'
 import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import cloud from 'd3-cloud'
-import { useRoom } from '../live/client.js'
+import { useRoom, latestByDevice } from '../live/client.js'
 import { JoinCode, ActivityFooter, ActivityQuestion, ActivityControls, useControls, wantsQr } from './activity.jsx'
 import { phoneQuestion } from './inlineText.js'
 import { t } from '../core/labels.js'
 import './poll.css'
 
 // <wordcloud room="mood" question="One word for today?" />
-// Phones send a word or two, as often as they like. The slide packs every
-// answer into a cloud around its middle: the more often it was sent, the
+// Each phone sends a word or two; a new one replaces its earlier word. The
+// slide packs the answers into a cloud around its middle: the more often it was sent, the
 // larger; some stand upright. Answers that differ only in case or spacing
 // count together. `height` is the cloud's height in slide pixels (520),
 // `limit` the most words shown (60).
@@ -66,7 +66,7 @@ function layout(words, { width, height, font }) {
 export default function WordCloud({ room = 'words', question = '', limit = '60', height = '520', qr }) {
   const live = useRoom(room)
   const controls = useControls(room, live)
-  const all = countWords(controls.counted(live.messages))
+  const all = countWords(latestByDevice(controls.counted(live.messages)))
   const words = all.slice(0, Math.max(1, Number(limit) || 60))
   const total = all.reduce((sum, word) => sum + word.n, 0)
   const cloudHeight = Math.max(200, Number(height) || 520)
@@ -99,7 +99,7 @@ export default function WordCloud({ room = 'words', question = '', limit = '60',
           </svg>
           : !live.offline && <p class="question-empty">{t('question.empty')}</p>}
       </div>
-      <ActivityFooter count={total} {...live} reset={controls.reset} closed={controls.closed}>
+      <ActivityFooter count={total} {...live} perPhone reset={controls.reset} closed={controls.closed}>
         <ActivityControls controls={controls} messages={live.messages} offline={live.offline} />
       </ActivityFooter>
     </div>
@@ -107,4 +107,5 @@ export default function WordCloud({ room = 'words', question = '', limit = '60',
   </div>
 }
 
-WordCloud.phone = ({ question, placeholder }, { slideTitle = '' } = {}) => ({ type: 'text', ...phoneQuestion(question, slideTitle), placeholder: placeholder ?? '', maxLength: 40 })
+// `once`: the phone's latest word counts (a server before 3.12 ignores it and lets phones send more).
+WordCloud.phone = ({ question, placeholder }, { slideTitle = '' } = {}) => ({ type: 'text', ...phoneQuestion(question, slideTitle), placeholder: placeholder ?? '', maxLength: 40, once: true })

package/src/components/activity.jsx

@@ -12,9 +12,10 @@ import 'katex/dist/katex.min.css'
 // the number of answers, the live dot, Reset and the presenter's controls.
 
 export const shortLink = url => url.replace(/^https?:\/\//, '')
-// `qr="false"` (or "no", "off") leaves the code out: it was on an earlier
-// slide (<qrcode join />), and people's phones follow along.
-export const wantsQr = qr => !/^(false|no|off|0)$/i.test(String(qr ?? 'true'))
+// An activity shows no join code of its own: the presenter puts it over the
+// slide when it is wanted (J), and phones that joined follow along. `qr` (or
+// `qr="true"`) still puts the code beside the question.
+export const wantsQr = qr => qr != null && !/^(false|no|off|0)$/i.test(String(qr))
 // A switch such as `multiple`: on when given, unless it says false.
 export const isSet = value => value != null && !/^(false|no|off|0)$/i.test(String(value))
 
@@ -86,11 +87,13 @@ export function useControls(room, live, { results = true, solution = null } = {}
  * A record of the talk (`offline`) can still show the answer and results.
  */
 export function ActivityControls({ controls, messages, offline = false, results = false, solve = false }) {
-  const button = (name, on, label, onClick, icon) => <button type="button" class={`poll-control poll-${name}${on ? ' is-on' : ''}`} title={label} aria-label={label} aria-pressed={on} onClick={onClick}>{icon}</button>
+  // data-presenter-control: the phone clicker offers them too (runtime/slideControls.js).
+  const button = (name, on, label, onClick, icon, iconName) => <button type="button" class={`poll-control poll-${name}${on ? ' is-on' : ''}`} title={label} aria-label={label} aria-pressed={on} data-presenter-control="" data-presenter-icon={iconName} onClick={onClick}>{icon}</button>
+  const lock = controls.closed ? 'lock' : 'lock-open', eye = controls.results ? 'eye' : 'eye-off'
   return <>
-    {!offline && button('close', controls.closed, t(controls.closed ? 'poll.open' : 'poll.close'), () => controls.close(messages), <Icon name={controls.closed ? 'lock' : 'lock-open'} size={22} />)}
-    {results && button('results', !controls.results, t(controls.results ? 'poll.hideResults' : 'poll.showResults'), () => controls.change({ results: !controls.results }), <Icon name={controls.results ? 'eye' : 'eye-off'} size={24} />)}
-    {solve && button('solve', controls.revealed, t(controls.revealed ? 'poll.hideAnswer' : 'poll.showAnswer'), () => controls.change({ revealed: !controls.revealed }), <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12l5 5 9-10" /></svg>)}
+    {!offline && button('close', controls.closed, t(controls.closed ? 'poll.open' : 'poll.close'), () => controls.close(messages), <Icon name={lock} size={22} />, lock)}
+    {results && button('results', !controls.results, t(controls.results ? 'poll.hideResults' : 'poll.showResults'), () => controls.change({ results: !controls.results }), <Icon name={eye} size={24} />, eye)}
+    {solve && button('solve', controls.revealed, t(controls.revealed ? 'poll.hideAnswer' : 'poll.showAnswer'), () => controls.change({ revealed: !controls.revealed }), <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12l5 5 9-10" /></svg>, 'check')}
   </>
 }
 
@@ -110,7 +113,7 @@ export function ActivityFooter({ count, connected, canReset, reset, offline, pre
     {of != null ? t('poll.answeredOf', { n: count, of }) : count === 1 ? t('poll.answer') : t('poll.answers', { n: count })}
     {closed && <span class="poll-closed">{t('poll.closed')}</span>}
     <span class="poll-spacer" />
-    {canReset && <button class="poll-reset" disabled={count === 0 && !closed} onClick={() => reset().catch(() => {})}>{t('poll.reset')}</button>}
+    {canReset && <button class="poll-reset" disabled={count === 0 && !closed} data-presenter-control="" data-presenter-icon="reset" aria-label={t('poll.reset')} onClick={() => reset().catch(() => {})}>{t('poll.reset')}</button>}
     {children}
   </p>
 }

package/src/components/poll.css

@@ -31,6 +31,8 @@ deck-stage[data-follower] .poll-reset { display: none; }
 .poll-control:hover, .poll-control:focus-visible { opacity: 1; }
 .poll-close.is-on, .poll-results.is-on { opacity: 1; background: var(--muted, #666); border-color: var(--muted, #666); color: #fff; }
 deck-stage[data-follower] .poll-control { display: none; }
+/* The presenter view has them in its toolbar (runtime/PresenterChrome.jsx). */
+deck-stage[data-presenter] :is(.poll-control, .poll-reset) { display: none; }
 /* Closed: no more answers count. */
 .poll-closed { padding: 2px 12px; border-radius: 999px; background: color-mix(in srgb, var(--ink, #111) 10%, transparent); color: var(--ink, #111); font-weight: 600; }
 /* results="hidden" or the eye off: the presenter's screens show the results faint and hatched, the audience none. */

package/src/core/icons.js

@@ -50,11 +50,14 @@ export const ICONS = {
   highlighter: '<path d="m9 11-6 6v3h9l3-3"/><path d="m22 12-4.6 4.6a2 2 0 0 1-2.8 0l-5.2-5.2a2 2 0 0 1 0-2.8L14 4"/>', // highlighter
   marker: '<path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z"/><path d="M20 2v4"/><path d="M22 4h-4"/><circle cx="4" cy="20" r="2"/>', // sparkles
   select: '<path d="M5 3a2 2 0 0 0-2 2"/><path d="M19 3a2 2 0 0 1 2 2"/><path d="M21 19a2 2 0 0 1-2 2"/><path d="M5 21a2 2 0 0 1-2-2"/><path d="M9 3h1"/><path d="M9 21h1"/><path d="M14 3h1"/><path d="M14 21h1"/><path d="M3 9v1"/><path d="M21 9v1"/><path d="M3 14v1"/><path d="M21 14v1"/>', // square-dashed
-  laser: '<line x1="2" x2="5" y1="12" y2="12"/><line x1="19" x2="22" y1="12" y2="12"/><line x1="12" x2="12" y1="2" y2="5"/><line x1="12" x2="12" y1="19" y2="22"/><circle cx="12" cy="12" r="7"/><circle cx="12" cy="12" r="3"/>', // locate-fixed
+  laser: '<rect width="5" height="13" x="3.5" y="9.5" rx="2.5" transform="rotate(45 6 16)"/><path d="m11.5 12.5 3-3" stroke-dasharray="0.1 2.6"/><circle cx="17.5" cy="6.5" r="3"/><path d="M17.5 1v0.5"/><path d="M23 6.5h-.5"/><path d="m21.4 2.6-.35.35"/>', // drawn for mdeck on Lucide's grid: a laser pointer (Lucide has none; its "locate" read as a map pin)
   fold: '<path d="m7 7 10 10"/><path d="M17 7v10H7"/>', // arrow-down-right
   eraser: '<path d="M21 21H8a2 2 0 0 1-1.42-.587l-3.994-3.999a2 2 0 0 1 0-2.828l10-10a2 2 0 0 1 2.829 0l5.999 6a2 2 0 0 1 0 2.828L12.834 21"/><path d="m5.082 11.09 8.828 8.828"/>', // eraser
+  join: '<rect width="5" height="5" x="3" y="3" rx="1"/><rect width="5" height="5" x="16" y="3" rx="1"/><rect width="5" height="5" x="3" y="16" rx="1"/><path d="M21 16h-3a2 2 0 0 0-2 2v3"/><path d="M21 21v.01"/><path d="M12 7v3a2 2 0 0 1-2 2H7"/><path d="M3 12h.01"/><path d="M12 3h.01"/><path d="M12 16v.01"/><path d="M16 12h1"/><path d="M21 12v.01"/><path d="M12 21v-1"/>', // qr-code
+  settings: '<line x1="21" x2="14" y1="4" y2="4"/><line x1="10" x2="3" y1="4" y2="4"/><line x1="21" x2="12" y1="12" y2="12"/><line x1="8" x2="3" y1="12" y2="12"/><line x1="21" x2="16" y1="20" y2="20"/><line x1="12" x2="3" y1="20" y2="20"/><line x1="14" x2="14" y1="2" y2="6"/><line x1="8" x2="8" y1="10" y2="14"/><line x1="16" x2="16" y1="18" y2="22"/>', // sliders-horizontal
   people: '<path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><path d="M16 3.128a4 4 0 0 1 0 7.744"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><circle cx="9" cy="7" r="4"/>', // users
   tablet: '<rect width="16" height="20" x="4" y="2" rx="2" ry="2"/><line x1="12" x2="12.01" y1="18" y2="18"/>', // tablet
+  phone: '<rect width="14" height="20" x="5" y="2" rx="2" ry="2"/><path d="M12 18h.01"/>', // smartphone
   speaker: '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M15 3v18"/>', // panel-right
   fullscreen: '<path d="M8 3H5a2 2 0 0 0-2 2v3"/><path d="M21 8V5a2 2 0 0 0-2-2h-3"/><path d="M3 16v3a2 2 0 0 0 2 2h3"/><path d="M16 21h3a2 2 0 0 0 2-2v-3"/>', // maximize
   sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>', // sun
@@ -63,6 +66,8 @@ export const ICONS = {
   play: '<path d="M5 5a2 2 0 0 1 3.008-1.728l11.997 6.998a2 2 0 0 1 .003 3.458l-12 7A2 2 0 0 1 5 19z"/>', // play
   hotspots: '<path d="M3 7V5a2 2 0 0 1 2-2h2"/><path d="M17 3h2a2 2 0 0 1 2 2v2"/><path d="M21 17v2a2 2 0 0 1-2 2h-2"/><path d="M7 21H5a2 2 0 0 1-2-2v-2"/><circle cx="12" cy="12" r="3"/><path d="m16 16-1.9-1.9"/>', // scan-search
   rehearse: '<line x1="10" x2="14" y1="2" y2="2"/><line x1="12" x2="15" y1="14" y2="11"/><circle cx="12" cy="14" r="8"/>', // timer
+  blank: '<path d="M17 17H4a2 2 0 0 1-2-2V5c0-1.5 1-2 1-2"/><path d="M22 15V5a2 2 0 0 0-2-2H9"/><path d="M8 21h8"/><path d="M12 17v4"/><path d="m2 2 20 20"/>', // monitor-off
+  overview: '<rect width="18" height="14" x="3" y="3" rx="2"/><path d="M4 21h1"/><path d="M9 21h1"/><path d="M14 21h1"/><path d="M19 21h1"/>', // gallery-horizontal-end
   pause: '<rect x="14" y="3" width="5" height="18" rx="1"/><rect x="5" y="3" width="5" height="18" rx="1"/>', // pause
   loading: '<path d="M21 12a9 9 0 1 1-6.219-8.56"/>', // loader-circle
 }

package/src/core/labels.js

@@ -51,6 +51,7 @@ export const LABELS = {
     'respond.waiting': 'The next question will appear here.',
     'respond.send': 'Send',
     'respond.sent': 'Sent. Thank you!',
+    'respond.react': 'React',
     'join.scan': 'Scan to join',
     'follow.scan': 'Scan to follow the slides',
     'follow.open': 'Follow the slides',
@@ -124,6 +125,7 @@ export const LABELS = {
     'respond.waiting': 'Die nächste Frage erscheint hier.',
     'respond.send': 'Senden',
     'respond.sent': 'Gesendet. Danke!',
+    'respond.react': 'Reagieren',
     'join.scan': 'Scannen und mitmachen',
     'follow.scan': 'Scannen und Folien mitverfolgen',
     'follow.open': 'Folien mitverfolgen',
@@ -197,6 +199,7 @@ export const LABELS = {
     'respond.waiting': 'سيظهر السؤال التالي هنا.',
     'respond.send': 'إرسال',
     'respond.sent': 'أُرسلت. شكرًا لك!',
+    'respond.react': 'تفاعل',
     'join.scan': 'امسح الرمز للانضمام',
     'follow.scan': 'امسح الرمز لمتابعة الشرائح',
     'follow.open': 'متابعة الشرائح',

package/src/core/parseSlides.js

@@ -1,8 +1,8 @@
 import yaml from 'js-yaml'
-import { sourceLines, fenceState, scanDirectives, diagnostic } from './source.js'
+import { sourceLines, fenceState, scanDirectives, diagnostic, isIncludeLine } 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 bibliography csl nocite hotspots time'.split(' '))
+export const DECK_KEYS = new Set('theme palette appearance params meta width height show lang labels callouts reader components server session bibliography csl nocite hotspots time reactions'.split(' '))
 export const SLIDE_KEYS = new Set('layout id title section number part description label image alt overlay eyebrow attribution props hotspots time'.split(' '))
 
 // Names from before 2.0. They are still recognised, so that an old deck gets a
@@ -32,7 +32,7 @@ function segmentsOf(source) {
     const before = fence
     fence = fenceState(line.text, fence)
     if (before || fence) continue
-    if (/^:::\s*[\w-]+/.test(line.text)) depth++
+    if (/^:::\s*[\w-]+/.test(line.text) && !isIncludeLine(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 })
@@ -103,6 +103,15 @@ function extractBody(source, body, diagnostics) {
   return { content, notes: notes.join('\n\n'), regions, blocks }
 }
 
+// What a slide that is nothing but `:::include <file> [slides=3-7]` includes:
+// { file, slides } (slides as written, or null), or null for any other slide.
+export function includeOf(content) {
+  const match = /^:::\s*include\s+(?:"([^"]+)"|(\S+))((?:\s+[\w-]+=\S+)*)\s*$/.exec(String(content ?? '').trim())
+  if (!match) return null
+  const options = Object.fromEntries([...match[3].matchAll(/([\w-]+)=(\S+)/g)].map(([, key, value]) => [key, value]))
+  return { file: match[1] ?? match[2], slides: options.slides ?? null, options }
+}
+
 export function parseSlides(source) {
   const segments = segmentsOf(source)
   const diagnostics = []
@@ -150,9 +159,10 @@ export function parseSlides(source) {
     // source editing and validation, separate from the resolved block notes.
     delete meta.notes
     if (notes) meta.notes = notes
+    const include = Object.keys(authoredMeta).length ? null : includeOf(content)
     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 })
+      metaSource, bodySource: body ? { start: body.start, end: body.end } : null, ...(include ? { include } : {}) })
   }
   let currentSection = null
   for (const slide of slides) {

package/src/core/reactions.js

@@ -0,0 +1,27 @@
+// Reactions: people tap an emoji on the answer page, and it floats up on the
+// presenter's screen for a moment, never on the projector. A deck turns them
+// on with `reactions: true` (the set below) or its own list of up to eight,
+// such as `reactions: [👍, 🤔, 🐢]`. They go to the session's `reactions`
+// room, which the server passes on without keeping (src/live/rooms.js).
+
+export const REACTIONS_ROOM = 'reactions'
+// 🐢: "slower, please".
+export const DEFAULT_REACTIONS = ['👍', '👏', '❤️', '😮', '🤔', '🐢']
+const MAX = 8
+const MAX_LENGTH = 16
+
+/** Whether `value` is a usable `reactions` setting; a problem as text, or null. */
+export function reactionsProblem(value) {
+  if (value == null || typeof value === 'boolean') return null
+  if (!Array.isArray(value) || !value.length || value.length > MAX) return `reactions must be true, false, or a list of 1 to ${MAX} emoji or short words`
+  const bad = value.find(item => typeof item !== 'string' && typeof item !== 'number' || !String(item).trim() || String(item).trim().length > MAX_LENGTH)
+  return bad !== undefined ? `reactions: each one is an emoji or a word of up to ${MAX_LENGTH} characters, not ${JSON.stringify(bad)}` : null
+}
+
+/** The reactions a deck offers, or null when it offers none. */
+export function reactionsOf(config) {
+  const value = config?.reactions
+  if (value === true) return DEFAULT_REACTIONS
+  if (reactionsProblem(value) || !Array.isArray(value)) return null
+  return [...new Set(value.map(item => String(item).trim()))]
+}

package/src/core/resultsReport.js

@@ -0,0 +1,153 @@
+// The answers kept in a talk (<deck>.results.json, results.js) read against
+// the deck they were given in: which slide asked, what, and how it came out.
+// `mdeck results` and the launch page export them from here, as the answers
+// one by one (CSV), one row per option, word or number (summary CSV), or
+// all of it (JSON).
+//
+// The summary counts as the slide does: for a poll, a scale, a number and a
+// word cloud, each phone's latest answer; for open questions, every answer. Phones stay numbered per question; no device ids are kept.
+import { tagsIn } from './tags.js'
+import { expandPollLists, pollChoices } from './pollList.js'
+import { choicesOf } from '../components/inlineText.js'
+import { parseNumber, groupNumbers } from '../components/numbers.js'
+
+const KINDS = { poll: 'poll', scale: 'scale', numeric: 'number', wordcloud: 'words', question: 'question' }
+
+const plain = text => String(text ?? '').replace(/\$([^$]+)\$/g, '$1').replace(/[*_`]/g, '').replace(/\s+/g, ' ').trim()
+
+function headingOf(slide) {
+  const heading = String(slide?.content ?? '').replace(/^(```|~~~)[\s\S]*?^\1/gm, '').match(/^\s*#{1,3}\s+(.+?)\s*#*\s*$/m)?.[1]
+  return heading ? plain(heading) : plain(slide?.meta?.title ?? '')
+}
+
+const scaleBounds = ({ min, max }) => {
+  const low = Number.isFinite(Number(min)) && min !== '' && min != null ? Math.round(Number(min)) : 1
+  const high = Number.isFinite(Number(max)) && max !== '' && max != null ? Math.round(Number(max)) : 5
+  return high > low && high - low <= 10 ? [low, high] : [1, 5]
+}
+
+/**
+ * The activities of a parsed deck, in order: [{ room, slide, kind, tag,
+ * question, options?, multiple?, min?, max? }]. `slide` counts from 1; a
+ * room asked on several slides is listed where it is first asked.
+ */
+export function activitiesIn(deck) {
+  const found = new Map()
+  ;(deck?.slides ?? []).forEach((slide, i) => {
+    const texts = [slide.content ?? '', ...Object.values(slide.regions ?? {}).map(region => region.content ?? '')]
+    for (const text of texts) {
+      for (const tag of tagsIn(expandPollLists(text))) {
+        const room = tag.attrs.room
+        if (tag.closing || !room || found.has(room)) continue
+        const kind = KINDS[tag.name] ?? tag.name
+        const entry = { room, slide: i + 1, kind, tag: tag.name, question: plain(tag.attrs.question) || headingOf(slide) }
+        if (tag.name === 'poll') {
+          const listed = tag.attrs['data-choices'] != null && pollChoices(tag.attrs['data-choices'])
+          entry.options = listed ? listed.map(choice => choice.text) : choicesOf(tag.attrs.options)
+          if (tag.attrs.multiple != null && tag.attrs.multiple !== 'false') entry.multiple = true
+        }
+        if (tag.name === 'scale') [entry.min, entry.max] = scaleBounds(tag.attrs)
+        found.set(room, entry)
+      }
+    }
+  })
+  return [...found.values()]
+}
+
+// Each phone's last answer, in the order the phones first answered.
+function latestPerPhone(answers) {
+  const latest = new Map()
+  for (const answer of answers) latest.set(answer.phone, answer)
+  return [...latest.values()]
+}
+
+const round = value => Math.round(value * 100) / 100
+function stats(values) {
+  if (!values.length) return {}
+  const sorted = [...values].sort((a, b) => a - b)
+  const middle = sorted.length >> 1
+  const median = sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
+  return { average: round(values.reduce((sum, value) => sum + value, 0) / values.length), median: round(median), lowest: sorted[0], highest: sorted.at(-1) }
+}
+
+/** How one activity came out: { phones, answers, counts: [{ answer, count }], average?, median?, lowest?, highest? }. */
+export function summarize(activity, answers = []) {
+  const phones = new Set(answers.map(answer => answer.phone)).size
+  const base = { phones, answers: answers.length }
+  const tag = activity?.tag
+  if (tag === 'poll') {
+    const options = activity.options ?? []
+    const votes = latestPerPhone(answers)
+      .map(answer => activity.multiple ? (Array.isArray(answer.value) ? answer.value : [answer.value]) : (Array.isArray(answer.value) ? [] : [answer.value]))
+      .map(picks => picks.filter(pick => options.includes(pick)))
+      .filter(picks => picks.length)
+    return { ...base, voted: votes.length, counts: options.map(option => ({ answer: option, count: votes.filter(picks => picks.includes(option)).length })) }
+  }
+  if (tag === 'scale') {
+    const steps = Array.from({ length: activity.max - activity.min + 1 }, (_, i) => activity.min + i)
+    const values = latestPerPhone(answers).map(answer => Number(answer.value)).filter(value => steps.includes(value))
+    return { ...base, voted: values.length, counts: steps.map(step => ({ answer: String(step), count: values.filter(value => value === step).length })), ...stats(values) }
+  }
+  if (tag === 'numeric') {
+    const texts = latestPerPhone(answers).map(answer => answer.value).filter(value => parseNumber(value) != null)
+    return { ...base, voted: texts.length, counts: groupNumbers(texts).map(group => ({ answer: group.text, count: group.n })), ...stats(texts.map(parseNumber)) }
+  }
+  // Words (each phone's latest) and open answers (every one), the same words together.
+  const counts = new Map()
+  for (const answer of tag === 'wordcloud' ? latestPerPhone(answers) : answers) {
+    const text = String(answer.value ?? '').trim().replace(/\s+/g, ' ')
+    if (!text) continue
+    const key = text.toLocaleLowerCase()
+    const entry = counts.get(key) ?? { answer: text, count: 0 }
+    entry.count++
+    counts.set(key, entry)
+  }
+  return { ...base, counts: [...counts.values()].sort((a, b) => b.count - a.count || a.answer.localeCompare(b.answer)) }
+}
+
+/**
+ * The kept answers against the deck: [{ room, slide, kind, question,
+ * closed, savedAt, summary, answers }], in the order of the slides; rooms
+ * the deck no longer asks come last, with what is known of them.
+ */
+export function resultsReport(results, deck) {
+  const rooms = results?.rooms ?? {}
+  const activities = activitiesIn(deck)
+  const asked = activities.filter(activity => rooms[activity.room])
+  const gone = Object.keys(rooms).filter(room => !activities.some(activity => activity.room === room)).map(room => ({ room, slide: null, kind: null, tag: null, question: '' }))
+  return [...asked, ...gone].map(activity => {
+    const entry = rooms[activity.room]
+    const { tag, options, multiple, min, max, ...shown } = activity
+    return { ...shown, closed: entry.closed, savedAt: entry.savedAt, summary: summarize(activity, entry.answers), answers: entry.answers }
+  })
+}
+
+const csvCell = value => {
+  const text = value == null ? '' : Array.isArray(value) ? value.join('|') : String(value)
+  return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
+}
+const csv = rows => rows.map(row => row.map(csvCell).join(',')).join('\n') + '\n'
+
+/** Every answer with its question: slide, room, kind, question, phone, time, answer (several picks joined by |). */
+export function reportAnswersCsv(report) {
+  const rows = [['slide', 'room', 'kind', 'question', 'phone', 'at', 'answer']]
+  for (const entry of report) for (const answer of entry.answers) rows.push([entry.slide, entry.room, entry.kind, entry.question, answer.phone, answer.at, answer.value])
+  return csv(rows)
+}
+
+/** One row per option, step, number or word: slide, room, kind, question, answer, count, and its share of the phones that answered. */
+export function reportSummaryCsv(report) {
+  const rows = [['slide', 'room', 'kind', 'question', 'answer', 'count', 'share']]
+  for (const entry of report) {
+    const { counts = [], voted } = entry.summary
+    const total = voted ?? counts.reduce((sum, row) => sum + row.count, 0)
+    for (const row of counts) rows.push([entry.slide, entry.room, entry.kind, entry.question, row.answer, row.count, total ? `${Math.round((row.count / total) * 100)}%` : ''])
+    for (const key of ['average', 'median']) if (entry.summary[key] != null) rows.push([entry.slide, entry.room, entry.kind, entry.question, key, entry.summary[key], ''])
+  }
+  return csv(rows)
+}
+
+/** All of it, for other programs: the deck's title, when, and each question with its summary and answers. */
+export function reportJson(report, { title = '', exportedAt = new Date().toISOString() } = {}) {
+  return JSON.stringify({ version: 1, title, exportedAt, questions: report }, null, 2) + '\n'
+}

package/src/core/source.js

@@ -24,6 +24,11 @@ export function diagnostic(source, code, message, offset = 0, severity = 'error'
 }
 
 // Balanced directive scanner, shared by the document parser and Markdown lexer.
+// `:::include ./part.md`, alone on a slide, stands for the slides of another
+// deck file (build/include.js puts them in its place). Without a path, `:::include`
+// opens a block as any other name does (a callout of the deck's own).
+export const isIncludeLine = text => /^:::\s*include\s+\S/.test(text)
+
 export function scanDirectives(source) {
   const nodes = []
   const stack = []
@@ -38,7 +43,9 @@ export function scanDirectives(source) {
       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)
+      // :::include is one line: it has no body and no closing fence.
+      if (isIncludeLine(line.text)) Object.assign(node, { bodyEnd: line.end, end: line.end })
+      else 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))