mdeck 3.10.1 → 3.12.0

package/src/runtime/shared.js

@@ -0,0 +1,77 @@
+// State that deck components share across slides and across the windows of
+// one talk: the presenter's slide frame, the audience window, other deck
+// windows in this browser, and a paired iPad. Components reach it through
+// `mdeck/component` (component.js). Values travel on the ink bus (ink/bus.js)
+// as `shared` messages; nothing is saved, and a window that opens later asks
+// the others for what they hold (`shared-ask`). A deck whose components use
+// none of it sends nothing.
+//
+// The latest change wins as it arrives. A value replayed for a window that
+// opened later only fills a name that window does not know yet, so no clocks
+// are compared between devices.
+
+const values = new Map()
+const listeners = new Map()
+let send = null
+let asked = false
+let view = 'deck'
+
+// Windows that only show the talk read shared state but do not change it.
+const READ_ONLY = new Set(['preview', 'reader', 'follow'])
+
+/** The kind of window this is: presenter, audience, deck, follow, preview or reader. */
+export function setView(next) { view = next }
+export function currentView() { return view }
+
+function notify(name) {
+  for (const listener of listeners.get(name) ?? []) listener(values.get(name))
+}
+
+// Asks the others once, when this window has both a bus and a component
+// that uses shared state.
+function ask() {
+  if (asked || !send || !listeners.size) return
+  asked = true
+  send({ type: 'shared-ask' })
+}
+
+/** The bus this window sends on. */
+export function connectShared(sender) {
+  send = sender
+  ask()
+}
+
+/** A `shared` or `shared-ask` message from another window. */
+export function receiveShared(message) {
+  if (message.type === 'shared-ask') {
+    for (const [name, value] of values) send?.({ type: 'shared', name, value, replay: true })
+    return
+  }
+  if (typeof message.name !== 'string') return
+  if (message.replay && values.has(message.name)) return
+  values.set(message.name, message.value)
+  notify(message.name)
+}
+
+export function getShared(name) { return values.get(name) }
+
+/** Sets a value here and in every other window; ignored where the talk is only shown. */
+export function setShared(name, value) {
+  if (READ_ONLY.has(view)) return false
+  // Only what survives JSON reaches the other windows; keep this one the same.
+  const plain = value === undefined ? null : JSON.parse(JSON.stringify(value))
+  values.set(name, plain)
+  notify(name)
+  send?.({ type: 'shared', name, value: plain })
+  return true
+}
+
+export function subscribeShared(name, listener) {
+  if (!listeners.has(name)) listeners.set(name, new Set())
+  listeners.get(name).add(listener)
+  ask()
+  return () => listeners.get(name)?.delete(listener)
+}
+
+/** For tests: forget everything. */
+export function resetShared() { values.clear(); listeners.clear(); send = null; asked = false; view = 'deck' }

package/src/runtime/slideControls.js

@@ -0,0 +1,60 @@
+// What the presenter can do on the slide shown, for the phone clicker
+// (main.jsx): the buttons components mark with `data-presenter-control` (a
+// poll's lock, eye, tick and Reset), the slide's videos (play or pause), and
+// its hotspots (zoom to a part, back to the whole slide). The clicker's slide
+// frame reports them; a tap on the clicker presses the original here, so the
+// change reaches the other screens the way a click on the slide does.
+
+const activeSlide = stage => stage.querySelector(':scope > [data-deck-active]')
+
+function controlElements(stage) {
+  const slide = activeSlide(stage)
+  if (!slide) return []
+  return [...slide.querySelectorAll('[data-presenter-control], video')].filter(element => !element.closest('[data-deck-static]'))
+}
+
+const labelOf = element => element.getAttribute('data-presenter-control') || element.getAttribute('aria-label') || element.getAttribute('title') || element.textContent.trim()
+
+/** { items: [{ label, icon, pressed, disabled }], hotspots: n, hotspot } for the slide shown. `icon` names one of mdeck's icons (`data-presenter-icon`). */
+export function slideControls(stage) {
+  const items = controlElements(stage).map(element => element.localName === 'video'
+    ? { label: element.paused ? 'Play the video' : 'Pause the video', icon: element.paused ? 'play' : 'pause', pressed: !element.paused, disabled: false }
+    : { label: labelOf(element), icon: element.getAttribute('data-presenter-icon') || null, pressed: element.getAttribute('aria-pressed') === 'true', disabled: !!element.disabled })
+  const hotspots = stage.hotspotMode === 'off' ? 0 : Math.min(9, stage.hotspots.length)
+  return { items, hotspots, hotspot: hotspots ? stage.hotspot ?? null : null }
+}
+
+/** Presses control `index` of slideControls(stage). */
+export function pressSlideControl(stage, index) {
+  const element = controlElements(stage)[index]
+  if (!element || element.disabled) return false
+  if (element.localName === 'video') {
+    // Pressed from the toolbar or a phone, not in this frame: the browser may
+    // refuse sound here. The audience window plays it; this copy goes silent.
+    if (element.paused) element.play().catch(error => {
+      if (error?.name !== 'NotAllowedError') return
+      element.muted = true
+      return element.play()
+    }).catch(() => {})
+    else element.pause()
+  } else element.click()
+  return true
+}
+
+/** Calls `report(slideControls(stage))` whenever they may have changed, a few times a second at most. */
+export function watchSlideControls(stage, report) {
+  // A timer, not an animation frame: a presenter view in a background tab
+  // gets no frames, but its clicker still wants to know.
+  let timer = 0
+  const send = () => {
+    if (timer) return
+    timer = setTimeout(() => { timer = 0; report(slideControls(stage)) }, 60)
+  }
+  for (const type of ['slidechange', 'statechange', 'zoomchange', 'hotspotschange']) stage.addEventListener(type, send)
+  // Videos say when they play or pause; their events do not bubble.
+  for (const type of ['play', 'pause']) stage.addEventListener(type, send, true)
+  const observer = new MutationObserver(send)
+  observer.observe(stage, { subtree: true, childList: true, attributes: true, attributeFilter: ['aria-pressed', 'disabled', 'data-deck-active', 'data-presenter-control', 'data-presenter-icon'] })
+  send()
+  return () => observer.disconnect()
+}

package/src/runtime/steps.js

@@ -0,0 +1,36 @@
+// The steps of a slide: what appears one press at a time.
+//
+// Steps follow the slide's document order. Inside an SVG drawing that order
+// is also what is drawn on top, so a drawing may number its parts instead:
+// `data-step="2"` shows after `data-step="1"`, and parts with the same number
+// appear together. A drawing's numbered steps take the place of its first
+// one; parts with a bare `data-step` keep their own place.
+
+// [[element, …], …]: each step's elements, in the order they are shown.
+export function slideSteps(slide) {
+  if (!slide) return []
+  const order = []
+  const drawings = new Map()
+  for (const element of slide.querySelectorAll('[data-step]')) {
+    const drawing = element.closest('svg')
+    const number = numbered(element.getAttribute('data-step'))
+    if (!drawing || number == null) { order.push([element]); continue }
+    let parts = drawings.get(drawing)
+    if (!parts) {
+      parts = new Map()
+      drawings.set(drawing, parts)
+      order.push(parts)
+    }
+    if (!parts.has(number)) parts.set(number, [])
+    parts.get(number).push(element)
+  }
+  return order.flatMap(entry => entry instanceof Map
+    ? [...entry.keys()].sort((a, b) => a - b).map(number => entry.get(number))
+    : [entry])
+}
+
+function numbered(value) {
+  if (value == null || !value.trim()) return null
+  const number = Number(value)
+  return Number.isFinite(number) ? number : null
+}

package/src/runtime/useTalkTimer.js

@@ -0,0 +1,67 @@
+// The presenter view's clock: the time of the whole talk and of each slide.
+// It reads the wall clock rather than counting ticks, so it does not drift,
+// and keeps its state in sessionStorage, so a reload carries on where it was.
+// Time counts only while the clock runs; it goes to the slide shown.
+//
+// A rehearsal is the same clock, started from nothing: the time each slide
+// got is what the rehearsal summary offers to save (core/timing.js).
+import { useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks'
+
+const fresh = () => ({ running: false, rehearsing: false, mark: 0, total: 0, spent: {}, slide: null })
+
+function load(key) {
+  try {
+    const saved = JSON.parse(sessionStorage.getItem(key))
+    if (saved && typeof saved.total === 'number' && saved.spent && typeof saved.spent === 'object') return { ...fresh(), ...saved }
+  } catch {}
+  return fresh()
+}
+
+// The time since the last mark goes to the whole talk and the slide shown.
+function settle(state, now) {
+  if (!state.running || state.slide == null) return { ...state, mark: now }
+  const gone = Math.max(0, now - state.mark)
+  return { ...state, mark: now, total: state.total + gone, spent: { ...state.spent, [state.slide]: (state.spent[state.slide] ?? 0) + gone } }
+}
+
+export function useTalkTimer(key, slideId, { rehearse = false } = {}) {
+  const [state, setState] = useState(() => {
+    const saved = load(key)
+    // ?rehearse=1 starts a rehearsal, unless this page is in one already.
+    if (rehearse && !saved.rehearsing) return { ...fresh(), rehearsing: true, running: true, mark: Date.now(), slide: slideId }
+    return saved
+  })
+  const [, setTick] = useState(0)
+  const stateRef = useRef(state)
+  stateRef.current = state
+  const update = change => setState(current => change(settle(current, Date.now())))
+
+  useEffect(() => { try { sessionStorage.setItem(key, JSON.stringify(state)) } catch {} }, [state])
+  // At once, not after the next paint: in a background tab that comes late,
+  // and the time in between went to the slide before.
+  useLayoutEffect(() => { if (slideId != null && slideId !== state.slide) update(s => ({ ...s, slide: slideId })) }, [slideId])
+  useEffect(() => {
+    if (!state.running) return
+    const timer = setInterval(() => setTick(n => n + 1), 500)
+    return () => clearInterval(timer)
+  }, [state.running])
+
+  const live = state.running ? Math.max(0, Date.now() - state.mark) : 0
+  const seconds = ms => Math.floor(ms / 1000)
+  return {
+    running: state.running,
+    rehearsing: state.rehearsing,
+    totalElapsed: seconds(state.total + live),
+    slideElapsed: seconds((state.spent[state.slide] ?? 0) + live),
+    // Each slide's time so far, in seconds.
+    spent: () => {
+      const now = settle(stateRef.current, Date.now())
+      return Object.fromEntries(Object.entries(now.spent).map(([id, ms]) => [id, ms / 1000]))
+    },
+    toggle: () => update(s => ({ ...s, running: !s.running })),
+    pause: () => update(s => ({ ...s, running: false })),
+    reset: () => setState(s => ({ ...fresh(), slide: s.slide })),
+    startRehearsal: () => setState(s => ({ ...fresh(), rehearsing: true, running: true, mark: Date.now(), slide: s.slide })),
+    endRehearsal: () => setState(s => ({ ...fresh(), slide: s.slide })),
+  }
+}

package/examples/citations/refs.bib

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

package/examples/citations/refs.yml

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

package/examples/citations/slides.md

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

package/examples/poll/slides.md

@@ -1,127 +0,0 @@
----
-theme: neue
-meta:
-  title: "Ask the room"
-  author: "Tilman Schieber"
-  organization: "FHNW"
-  date: "2026-09-30"
----
-
----
-:::meta
-layout: title
-:::
-# Ask the room.
-## Live questions in a plain slide file.
-
-:::notes
-Start this deck with `mdeck run slides.md --network` so phones in the same network can answer.
-
-The deck shows every kind of question mdeck has: a poll, a scale, a word cloud and open answers. The QR code appears once, on the next slide.
-:::
-
----
-# Take out your phone.
-
-<qrcode join />
-
-:::notes
-Leave this up until most people have scanned. The code is the same for the whole talk: phones that joined now follow along, and each question appears on them when its slide comes up.
-
-Come back to this slide for latecomers, or leave the join code on the last question too.
-:::
-
----
-:::meta
-title: "Poll: how do you make slides?"
-:::
-# How do you make slides today?
-
-<poll room="tools" options="PowerPoint|Keynote|Google Slides|LaTeX Beamer|Markdown" qr="false" />
-
-:::notes
-A poll: one button per answer. Give people half a minute and read out the leader once the bars settle.
-
-Anyone can change their answer: only the latest vote from each phone counts.
-
-Before the talk, hover over the results and click Reset to clear test votes.
-:::
-
----
-:::meta
-title: "Scale: Markdown"
-:::
-# How well do you know Markdown?
-
-<scale room="markdown" min="1" max="5" low="Never used it" high="Every day" qr="false" />
-
-:::notes
-A scale: phones show the numbers from 1 to 5, the slide counts each one and shows the average.
-
-A high average means the rest of the talk can go faster.
-:::
-
----
-:::meta
-title: "Word cloud: slides"
-:::
-# One word for your last presentation?
-
-<wordcloud room="mood" placeholder="One word" qr="false" />
-
-:::notes
-A word cloud: people may send as many words as they like. The more often a word comes in, the larger it gets, packed around the middle; capitals do not matter.
-
-Pick out the largest word and one surprising small one.
-:::
-
----
-:::meta
-title: "Open question"
-:::
-# What would you like to ask?
-
-<question room="ask" placeholder="Your question" qr="false" />
-
-:::notes
-Open answers: the newest eight appear as cards, and people can send several.
-
-Answer one or two now, and promise to go through the rest afterwards; the room keeps them until you reset it.
-:::
-
----
-# Each question is one line.
-
-```markdown
-<qrcode join />
-<poll room="tools" options="PowerPoint|Keynote|Markdown" />
-<scale room="markdown" min="1" max="5" low="Never" high="Daily" />
-<wordcloud room="mood" />
-<question room="ask" placeholder="Your question" />
-```
-
-- **room** — a short name, different for every question in the deck.
-- **qr="false"** — leave out the code when `<qrcode join />` showed it earlier.
-- **question** — optional; without it, phones show the slide heading.
-
-:::notes
-Point at the lines that made the previous slides. That is all the author writes.
-
-The QR code takes the slide's colours, so it fits every theme; phone cameras read light-on-dark codes too.
-:::
-
----
-# Try it on your own computer.
-
-```sh
-mdeck run slides.md --network
-```
-
-- **Same network** — phones must be able to reach your computer.
-- **Lecture hall** — run `mdeck server` on a web server; the slides stay on your laptop.
-
-:::notes
-For a lecture hall, run `mdeck server` on a web server once and point the deck's `server` setting at it. The phones only talk to that server; the slides never leave this laptop. The "Ask your audience" guide has the details.
-
-Many university networks keep devices apart. If phones cannot open the page, use a phone hotspot or a server on the internet.
-:::

package/examples/showcase/slides.drawings.json

@@ -1,11 +0,0 @@
-{
-  "version": 1,
-  "width": 1920,
-  "height": 1080,
-  "slides": {
-    "draw-on-any-slide": [
-      {"id":"tour:underline","tool":"pen","color":"#e11d48","size":7,"points":[[120,462,0.45],[135,464,0.48],[150,466,0.52],[165,467,0.55],[180,468,0.58],[195,469,0.61],[210,469,0.64],[225,468,0.66],[240,467,0.68],[255,465,0.7],[270,464,0.72],[285,462,0.73],[300,460,0.74],[315,459,0.75],[330,458,0.75],[345,458,0.75],[360,459,0.74],[375,460,0.73],[390,461,0.72],[405,463,0.71],[420,465,0.69],[435,467,0.67],[450,469,0.64],[465,470,0.62],[480,471,0.59],[495,472,0.56],[510,472,0.53],[525,471,0.49],[540,470,0.46],[555,468,0.43],[570,467,0.39],[585,465,0.36],[600,464,0.33],[615,462,0.3],[630,462,0.27],[645,461,0.25],[660,462,0.22],[675,462,0.2],[690,464,0.19],[705,466,0.17],[720,468,0.16]]},
-      {"id":"tour:circle","tool":"pen","color":"#e11d48","size":6,"points":[[226,491,0.5],[230,491,0.54],[235,491,0.57],[239,492,0.6],[243,494,0.64],[247,497,0.66],[250,500,0.69],[252,504,0.71],[254,508,0.73],[255,512,0.74],[256,516,0.75],[255,520,0.75],[254,524,0.75],[252,528,0.74],[250,532,0.73],[247,534,0.71],[244,537,0.69],[240,539,0.66],[237,541,0.63],[233,542,0.6],[229,543,0.57],[225,543,0.54],[221,543,0.5],[217,543,0.46],[213,541,0.43],[209,540,0.4],[206,538,0.36],[203,535,0.34],[200,531,0.31],[198,528,0.29],[196,523,0.27],[196,519,0.26],[196,515,0.25],[197,510,0.25],[199,506,0.25],[201,503,0.26],[204,500,0.27],[207,497,0.29],[211,495,0.31],[215,494,0.34],[219,493,0.37],[223,493,0.4],[227,493,0.43],[231,493,0.47],[235,495,0.5],[239,496,0.54]]}
-    ]
-  }
-}