mdeck 2.3.0

package/src/live/client.js

@@ -0,0 +1,290 @@
+// Audience interaction for slide components: `import { useRoom } from 'mdeck/live'`.
+//
+// Relay mode: the server connects the presenter's screen and the phones
+// and never needs the deck. Every activity in a deck shares one join link,
+// <server>/<code>. The presenter's screen announces the activity on the current
+// slide together with what the phone should show (a component's `phone`
+// description), the deck's look and the words in its language; the room
+// server's answer page shows that. On the slides, `useRoom` follows the
+// answers.
+import { useCallback, useEffect, useState } from 'preact/hooks'
+import { sessionCode } from './code.js'
+import { pairToken } from './pairing.js'
+import { devPath } from '../core/devPath.js'
+import { t, deckLanguage } from '../core/labels.js'
+
+// The QR code component the built-in poll uses, for your own activities.
+export { default as QrCode } from '../components/QrCode.jsx'
+
+let settings = { server: null, code: '000000' }
+
+// Called by the runtime with the deck settings.
+// `mdeck run --server <address>` and MDECK_SERVER name the server without the
+// deck; the dev server passes it in as __MDECK_SERVER__ and it wins.
+const givenServer = typeof __MDECK_SERVER__ === 'string' ? __MDECK_SERVER__ : null
+
+export function configureLive(deckConfig = {}) {
+  const server = givenServer ?? deckConfig.server
+  settings = { server: typeof server === 'string' ? server.replace(/\/+$/, '') : null, code: sessionCode(deckConfig) }
+  infoRequest = null
+  takeKeyFromAddress()
+}
+
+/** The deck's session code, the last part of its join link. */
+export const liveCode = () => settings.code
+
+const proxyControls = typeof __MDECK_PROXY_CONTROLS__ !== 'undefined' && __MDECK_PROXY_CONTROLS__
+const controlBase = () => proxyControls ? new URL(devPath('__mdeck/live'), window.location.origin).href : serverBase()
+const controlRoomPath = room => `${controlBase()}/rooms/${encodeURIComponent(`${settings.code}.${room}`)}`
+const controlSessionPath = () => `${controlBase()}/rooms/${encodeURIComponent(settings.code)}`
+
+const page = () => new URL(window.location.href)
+// Without a `server` setting, the server built into `mdeck run`.
+const serverBase = () => settings.server ?? new URL(devPath('__mdeck/live'), window.location.origin).href
+const roomPath = room => `${serverBase()}/rooms/${encodeURIComponent(`${settings.code}.${room}`)}`
+const sessionPath = () => `${serverBase()}/rooms/${encodeURIComponent(settings.code)}`
+
+// Which rooms keep a live connection: those on the current slide, set by the
+// runtime for each deck it shows. Browsers allow only six connections per
+// server, shared by all tabs, so a deck must not hold one per activity.
+// null means every room is live (Read mode, print, pages without slides).
+let activeRooms = null
+const activeListeners = new Set()
+export function setActiveRooms(rooms) {
+  activeRooms = rooms == null ? null : new Set(rooms.map(String))
+  for (const listener of activeListeners) listener()
+}
+function useActive(room) {
+  const [, redraw] = useState(0)
+  useEffect(() => {
+    const listener = () => redraw(n => n + 1)
+    activeListeners.add(listener)
+    return () => activeListeners.delete(listener)
+  }, [])
+  return activeRooms == null || activeRooms.has(String(room))
+}
+
+// The presenter unlocks a standalone server once with ?serverkey=… in the
+// address. The code is kept in this browser, where the presenter view's other
+// windows find it, and taken out of the address bar at once, so it never shows
+// on a projector.
+let givenKey = null
+function takeKeyFromAddress() {
+  const url = page()
+  const given = url.searchParams.get('serverkey')
+  if (!given) return
+  givenKey = given
+  try { localStorage.setItem(`mdeck-server-key:${serverBase()}`, given) } catch {}
+  url.searchParams.delete('serverkey')
+  try { history.replaceState(history.state, '', url) } catch {}
+}
+// The server built into `mdeck run` also lets a paired iPad in, and so
+// does the server that relays `mdeck run --server`: this page then comes
+// from it, so it is the same origin. The token is never sent to another server.
+function ownServer() {
+  if (!settings.server) return true
+  try { return new URL(settings.server).origin === window.location.origin } catch { return false }
+}
+function presenterKey() {
+  // A relayed page always uses its own pairing, even if this origin once
+  // stored a master key for a different presentation.
+  if (/^\/t\/[^/]+\/$/.test(devPath('')) || proxyControls || (import.meta.env?.DEV && ownServer())) return pairToken()
+  let key = givenKey
+  try { key = localStorage.getItem(`mdeck-server-key:${serverBase()}`) ?? givenKey } catch {}
+  return key ?? (ownServer() ? pairToken() : null)
+}
+const withKey = (headers = {}) => { const key = presenterKey(); return key ? { ...headers, Authorization: `Bearer ${key}` } : headers }
+
+// Only an answer is kept; after a failure the next call asks again, so a room
+// server that starts later is found. `reachable` is false when it did not answer.
+let infoRequest = null
+function serverInfo() {
+  infoRequest ??= fetch(`${controlBase()}/info?session=${encodeURIComponent(settings.code)}`, { headers: withKey() })
+    .then(response => { if (!response.ok) throw new Error(String(response.status)); return response.json() })
+    .then(info => ({ ...info, reachable: true }))
+    .catch(() => { infoRequest = null; return { reachable: false } })
+  return infoRequest
+}
+
+// The join link phones can open: the `server` setting, or `mdeck run --network`'s
+// network address. null when only this computer can reach the server;
+// `localJoinUrl` then still opens the answer page here, for trying it out.
+function joinUrl(info) {
+  if (settings.server) return `${settings.server}/${settings.code}`
+  return info.network ? new URL(`__mdeck/live/${settings.code}`, info.network).href : null
+}
+const localJoinUrl = () => `${serverBase()}/${settings.code}`
+// Until the server has answered or failed, `known` is false and activities
+// show no join code, so a quick capture never shows a passing warning.
+const reach = info => ({ known: info.reachable != null, offline: info.reachable === false })
+
+/**
+ * Follow a room's answers on a slide.
+ *   messages  every answer so far: { n, at, from, data: { value } }
+ *   joinUrl   the deck's join link for the QR code, or null if phones cannot
+ *             reach the server; localJoinUrl works on this computer
+ *   canReset / reset()  presenter only
+ *   connected false until the live stream is open
+ *   offline   no room server answered: a PDF, a file sent to readers or a
+ *             build hosted without one. Activities then show their question
+ *             as a record of the talk, without a join code.
+ * Off the current slide the room keeps its last messages but disconnects.
+ */
+export function useRoom(room) {
+  const live = useActive(room)
+  const [messages, setMessages] = useState([])
+  const [connected, setConnected] = useState(false)
+  const [info, setInfo] = useState({})
+
+  useEffect(() => { serverInfo().then(setInfo) }, [])
+
+  useEffect(() => {
+    if (!live || !room || typeof EventSource === 'undefined') return
+    const source = new EventSource(`${roomPath(room)}/events`)
+    source.addEventListener('open', () => setConnected(true))
+    source.addEventListener('error', () => setConnected(false))
+    source.addEventListener('snapshot', event => setMessages(JSON.parse(event.data).messages))
+    source.addEventListener('message', event => { const message = JSON.parse(event.data); setMessages(list => list.some(m => m.n === message.n) ? list : [...list, message]) })
+    source.addEventListener('reset', () => setMessages([]))
+    return () => { source.close(); setConnected(false) }
+  }, [room, live])
+
+  const reset = useCallback(async () => {
+    const response = await fetch(`${controlRoomPath(room)}/reset`, { method: 'POST', headers: withKey({ 'Content-Type': 'application/json' }), body: '{}' })
+    if (!response.ok) throw new Error((await response.json().catch(() => ({}))).error ?? 'Could not reset')
+  }, [room])
+
+  return { messages, reset, connected, canReset: !!info.canReset, joinUrl: joinUrl(info), localJoinUrl: localJoinUrl(), code: settings.code, ...reach(info) }
+}
+
+/** The deck's join link alone, for a slide that only invites people in (<qrcode join />). */
+export function useJoinLink() {
+  const [info, setInfo] = useState({})
+  useEffect(() => { serverInfo().then(setInfo) }, [])
+  return { joinUrl: joinUrl(info), localJoinUrl: localJoinUrl(), code: settings.code, ...reach(info) }
+}
+
+/** The latest answer of each device, e.g. to count votes that can be changed. */
+export function latestByDevice(messages) {
+  const latest = new Map()
+  for (const message of messages) latest.set(message.from ?? `#${message.n}`, message)
+  return [...latest.values()]
+}
+
+// ── The presenter's screen ──────────────────────────────────────────────────
+
+// The deck's look as the answer page needs it: theme variables, font
+// stylesheets and the style of a slide heading, read from the page that shows
+// the slides (the presenter's current-slide frame, or the deck itself).
+const LOOK_TOKENS = ['--bg', '--ink', '--ink-soft', '--muted', '--rule', '--surface', '--accent', '--accent-2', '--on-accent', '--font-body', '--font-display']
+let lookSource = () => document
+export function setLookSource(source) { lookSource = source }
+export function captureLook(doc = lookSource()) {
+  if (!doc?.documentElement) return null
+  const style = getComputedStyle(doc.documentElement)
+  const tokens = Object.fromEntries(LOOK_TOKENS.map(name => [name, style.getPropertyValue(name).trim()]).filter(([, value]) => value))
+  const fonts = [...doc.querySelectorAll('link[data-deck-theme-font]')].map(link => link.href)
+  // A frame that has not loaded its slides yet has no theme: send nothing, so
+  // phones keep the look they have.
+  if (!tokens['--bg'] && !tokens['--font-body']) return null
+  const h1 = doc.querySelector('.slide-body h1')
+  const hs = h1 && doc.defaultView.getComputedStyle(h1)
+  // Letter spacing relative to the font size, so a slide heading's spacing
+  // fits the much smaller heading on a phone.
+  const spacing = hs && (hs.letterSpacing === 'normal' ? 'normal' : `${(parseFloat(hs.letterSpacing) / parseFloat(hs.fontSize)).toFixed(3)}em`)
+  const heading = hs ? { family: hs.fontFamily, weight: hs.fontWeight, spacing, transform: hs.textTransform } : null
+  return { tokens, fonts, heading }
+}
+
+// The words the answer page shows, in the deck's language.
+const phoneWords = () => ({ waiting: t('respond.waiting'), pick: t('poll.pick'), thanks: t('poll.thanks'), send: t('respond.send'), sent: t('respond.sent') })
+
+// The presenter's screen announces the activity on the current slide and
+// repeats it every few seconds, so phones that join late and a server
+// that restarted catch up; the server passes on only changes. Only the
+// presenter may: `steering` says whether this screen reaches the phones.
+const REPEAT_MS = 4000
+// This window, so the server can tell its repeats from new changes.
+const SCREEN = Math.random().toString(36).slice(2, 10)
+let current = { room: null, activity: null, title: '', at: 0, screen: SCREEN }, repeat = null
+let steering = null
+let lastLook = null
+const steeringListeners = new Set()
+function report(next) {
+  if (steering && steering.ok === next.ok && steering.reason === next.reason) return
+  steering = next
+  for (const listener of steeringListeners) listener(next)
+}
+
+// A presenter view outranks other deck windows in the same browser: while it
+// runs, they stay quiet, so two screens on different slides or looks do not
+// make the phones flip between them.
+let role = 'screen'
+export function actAsPresenter() { role = 'presenter' }
+const presenterMark = () => `mdeck-live-presenter:${settings.code}`
+function outranked() {
+  try {
+    if (role === 'presenter') { localStorage.setItem(presenterMark(), String(Date.now())); return false }
+    return Date.now() - Number(localStorage.getItem(presenterMark()) ?? 0) < REPEAT_MS * 2.5
+  } catch { return false }
+}
+
+async function sendCurrent() {
+  if (outranked()) return
+  const info = await serverInfo()
+  if (!info.reachable) return report({ ok: false, reason: 'unreachable' })
+  if (!info.canReset) return report({ ok: false, reason: presenterKey() ? 'wrong-code' : 'no-code' })
+  const look = captureLook()
+  if (look) lastLook = look
+  const state = { ...current, look: lastLook, lang: deckLanguage(), labels: phoneWords() }
+  try {
+    const response = await fetch(`${controlSessionPath()}/state`, { method: 'POST', headers: withKey({ 'Content-Type': 'application/json' }), body: JSON.stringify({ state }) })
+    const body = response.ok ? await response.json().catch(() => ({})) : {}
+    report(!response.ok ? { ok: false, reason: response.status === 403 ? 'wrong-code' : 'unreachable' } : body.ignored ? { ok: false, reason: 'other-screen' } : { ok: true })
+  } catch { report({ ok: false, reason: 'unreachable' }) }
+}
+
+/**
+ * The activity on the current slide: { room, activity, title }, where
+ * `activity` is what the phones show ({ type: 'choice' | 'text' | 'scale', … }),
+ * or nothing between activities.
+ */
+export function announce({ room = null, activity = null, title = '', initial = false } = {}) {
+  // `at` marks this change; the server keeps the latest change of all
+  // screens. A screen that just opened says 0, so opening a tab to look at
+  // the deck does not take the phones away from the presenter.
+  current = { room, activity, title, at: initial ? 0 : Date.now(), screen: SCREEN }
+  sendCurrent()
+  repeat ??= setInterval(sendCurrent, REPEAT_MS)
+}
+
+/**
+ * The deck's stage room, which carries the presenter's position and live ink
+ * to screens on other devices (src/runtime/ink/room.js).
+ */
+// The stage room's own `info`: with a standalone server behind `mdeck run`,
+// the stage room stays on `mdeck run` (src/live/server.js), so it asks there.
+let stageRequest = null
+function stageInfo() {
+  if (!proxyControls) return serverInfo()
+  stageRequest ??= fetch(`${controlBase()}/info?session=${encodeURIComponent(settings.code)}&stage=1`, { headers: withKey() })
+    .then(response => { if (!response.ok) throw new Error(String(response.status)); return response.json() })
+    .then(info => ({ ...info, reachable: true }))
+    .catch(() => { stageRequest = null; return { reachable: false } })
+  return stageRequest
+}
+
+export function stageRoom() {
+  return { url: `${controlSessionPath()}.stage`, headers: withKey, info: stageInfo, screen: SCREEN }
+}
+
+/** For the presenter view: null before the first announcement, else { ok, reason }. */
+export function useSteering() {
+  const [state, setState] = useState(steering)
+  useEffect(() => {
+    steeringListeners.add(setState)
+    setState(steering)
+    return () => steeringListeners.delete(setState)
+  }, [])
+  return state
+}

package/src/live/code.js

@@ -0,0 +1,19 @@
+// A deck's session code: six digits that name its rooms on the server
+// and end its join link (`<server>/482113`). It is derived from the deck, so
+// the presenter's screen, the QR code on the slides and the launch page agree
+// without asking the server. `session.code` sets it; otherwise `session.id` or the
+// title picks it.
+
+export const slug = text => String(text ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+
+export const CODE_RE = /^\d{4,8}$/
+
+export function sessionCode(deckConfig = {}) {
+  const session = deckConfig.session ?? {}
+  if (session.code != null && CODE_RE.test(String(session.code))) return String(session.code)
+  const name = slug(session.id ?? deckConfig.meta?.title) || 'deck'
+  // FNV-1a, then six digits that never start with 0.
+  let hash = 0x811c9dc5
+  for (const char of name) hash = Math.imul(hash ^ char.codePointAt(0), 0x01000193) >>> 0
+  return String(100000 + (hash % 900000))
+}

package/src/live/follow.js

@@ -0,0 +1,17 @@
+// Only the current slide's activities keep a live connection; while printing,
+// all of them do. Returns a function that stops following.
+import { setActiveRooms } from './client.js'
+import { roomsOnSlide } from './roomTag.js'
+
+export function followActiveRooms(stage, slides) {
+  if (!stage || !slides.some(slide => roomsOnSlide(slide).length)) return () => {}
+  const update = () => setActiveRooms(stage.printing ? null : roomsOnSlide(slides[stage.index]))
+  update()
+  stage.addEventListener('slidechange', update)
+  stage.addEventListener('printchange', update)
+  return () => {
+    stage.removeEventListener('slidechange', update)
+    stage.removeEventListener('printchange', update)
+    setActiveRooms(null)
+  }
+}

package/src/live/pairing.js

@@ -0,0 +1,34 @@
+// The browser side of pairing with `mdeck run` (src/build/pairing.js): a
+// device that opened the launch page's QR code trades the one-time token in
+// the address for a token of its own, kept in this browser for this server.
+import { devPath } from '../core/devPath.js'
+
+export const pairStorageKey = (origin, base) => `mdeck-pair:${origin}${base}`
+const storageKey = () => pairStorageKey(location.origin, devPath(''))
+
+export function pairToken() {
+  try { return localStorage.getItem(storageKey()) } catch { return null }
+}
+
+/** Authorization for a paired device, or nothing. */
+export const pairHeaders = (headers = {}) => { const token = pairToken(); return token ? { ...headers, Authorization: `Bearer ${token}` } : headers }
+
+/** Claims `?pair=…` if the address has one; resolves to whether it worked. */
+export async function claimPairing() {
+  const url = new URL(location.href)
+  const offer = url.searchParams.get('pair')
+  if (!offer) return false
+  // Out of the address at once, so it is not bookmarked or shown.
+  url.searchParams.delete('pair')
+  try { history.replaceState(history.state, '', url) } catch {}
+  try {
+    const response = await fetch(devPath('__mdeck/pair/claim'), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: offer }) })
+    const body = await response.json().catch(() => ({}))
+    if (!response.ok) { console.warn('mdeck: pairing failed:', body.error ?? response.status); return false }
+    localStorage.setItem(storageKey(), body.token)
+    return true
+  } catch (error) {
+    console.warn('mdeck: pairing failed:', error.message)
+    return false
+  }
+}

package/src/live/presence.js

@@ -0,0 +1,33 @@
+// Who is connected to a deck: each presenter, audience and deck window says
+// what it is when it connects to the stage room, and the answer page counts
+// as a phone. The server tells windows that ask (?presence=1) who is there;
+// see src/live/rooms.js and src/components/ConnectedViews.jsx.
+
+/** This device, roughly: an iPad says it is a Mac, but has a touch screen. */
+export function deviceKind(nav = typeof navigator === 'undefined' ? {} : navigator) {
+  const agent = nav.userAgent ?? ''
+  if (/iPad/.test(agent) || (/Macintosh/.test(agent) && nav.maxTouchPoints > 1)) return 'ipad'
+  if (/iPhone|iPod|Android.*Mobile/.test(agent)) return 'phone'
+  if (/Android|Tablet/.test(agent)) return 'tablet'
+  return 'computer'
+}
+
+/** The query that counts this window as `view`, and asks for presence too. */
+export function presenceQuery({ view = null, listen = false } = {}) {
+  const query = new URLSearchParams()
+  if (view) { query.set('view', view); query.set('device', deviceKind()) }
+  if (listen) query.set('presence', '1')
+  return query.toString()
+}
+
+const DEVICE_NAME = { computer: 'a computer', ipad: 'an iPad', tablet: 'a tablet', phone: 'a phone' }
+const list = words => words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`
+
+/** The devices of some connected views, as words: "an iPad and 2 computers". */
+export function devicesText(views) {
+  const counts = {}
+  for (const entry of views) counts[entry.device] = (counts[entry.device] ?? 0) + 1
+  return list(Object.entries(counts).map(([device, n]) => n === 1 ? DEVICE_NAME[device] : `${n} ${device === 'ipad' ? 'iPads' : `${device}s`}`))
+}
+
+export const phonesText = n => `${n} phone${n === 1 ? '' : 's'}`

package/src/live/roomTag.js

@@ -0,0 +1,38 @@
+// Finds the component tag a phone should see: the one whose `room` attribute
+// matches, with its content if it has any.
+const escape = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// Code is not an activity: fenced blocks and `inline code` are blanked out
+// (keeping every other character where it was) before searching.
+const blank = text => text.replace(/[^\n]/g, ' ')
+export function maskCode(source = '') {
+  return source.replace(/^(```+|~~~+)[^\n]*\n[\s\S]*?^\1[ \t]*$/gm, blank).replace(/`[^`\n]+`/g, blank)
+}
+
+// Every activity in a source, in order: [{ tag, room }].
+export function roomsIn(source = '') {
+  return [...maskCode(source).matchAll(/<([a-z][a-z0-9-]*)\b[^>]*?\broom\s*=\s*(["'])([^"']+)\2/gi)].map(match => ({ tag: match[1].toLowerCase(), room: match[3] }))
+}
+
+// The rooms on one slide, from its body and its named regions (the body is
+// also a region, so each room is listed once).
+export function roomsOnSlide(slide) {
+  if (!slide) return []
+  const rooms = [slide.content ?? '', ...Object.values(slide.regions ?? {}).map(region => region.content ?? '')].flatMap(roomsIn).map(found => found.room)
+  return [...new Set(rooms)]
+}
+
+// The heading of the slide that holds `room` (what the audience saw), else
+// its `title:` setting, or ''.
+export function slideTitleFor(deck, room) {
+  const slide = deck.slides.find(slide => findRoomTag(slide.content ?? '', room) || Object.values(slide.regions ?? {}).some(region => findRoomTag(region.content ?? '', room)))
+  return slide?.content?.match(/^\s*#{1,3}\s+(.+?)\s*#*\s*$/m)?.[1]?.replace(/[*_`]/g, '') ?? slide?.meta.title ?? ''
+}
+
+export function findRoomTag(source, room) {
+  const open = new RegExp(`<([a-z][a-z0-9-]*)\\b[^>]*?\\broom\\s*=\\s*(["'])${escape(room)}\\2[^>]*>`, 'i').exec(maskCode(source))
+  if (!open) return null
+  if (open[0].endsWith('/>')) return open[0]
+  const close = source.indexOf(`</${open[1]}>`, open.index + open[0].length)
+  return close < 0 ? open[0] : source.slice(open.index, close + open[1].length + 3)
+}