@codename/deck 0.0.0-stage → 0.1.0

package/src/deck.js

@@ -0,0 +1,356 @@
+// A deck on a page: its slides drawn into the element given, paged with the bar, the keys a
+// presenter's clicker sends, a click or a swipe; each step shown in turn; moved between with the
+// transition its settings name, through the View Transitions API; presented full screen, with
+// the presenter's view (this slide, the next, the notes, the time) and all slides at once; light
+// or dark; changed as Markdown beside the slides, or in place on a slide, live. Host-agnostic:
+// the host gives the drawers of ```echarts and ```mermaid, how a picture's address resolves, its
+// words, and what to do when the deck changes or is saved.
+import { parseDeck } from './parse.js'
+import { renderSlide, h } from './render.js'
+import { tokensOf, schemeOf, VOICES } from './look.js'
+import { mergeKits } from './kit.js'
+import { stringsFor } from './strings.js'
+
+/** @typedef {import('./parse.js').Deck} Deck */
+/**
+ * @typedef {{
+ *   source: string, lang?: string, dir?: string, kit?: Record<string, any>, scheme?: 'light' | 'dark' | 'auto',
+ *   blocks?: Record<string, import('./render.js').Drawer>, resolve?: (src: string) => string | null,
+ *   strings?: Record<string, string>, headings?: 'real' | 'aria', editable?: boolean,
+ *   onChange?: (source: string) => void, onSave?: (source: string) => void, onExport?: (deck: DeckView) => void,
+ * }} Options
+ */
+
+const RTL = /^(ar|he|fa|ur|ps|sd|ug|yi|dv|ckb)\b/i
+const ICONS = {
+  back: 'M15 5l-7 7 7 7', next: 'M9 5l7 7-7 7', present: 'M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5',
+  presenter: 'M3 5h12v9H3zM18 8h3M18 12h3M6 19h6', grid: 'M4 4h6v6H4zM14 4h6v6h-6zM4 14h6v6H4zM14 14h6v6h-6z',
+  edit: 'M4 20h4L19 9l-4-4L4 16zM13.5 6.5l4 4', scheme: 'M12 3a9 9 0 1 0 9 9 7 7 0 0 1-9-9z', export: 'M12 4v11M7 10l5 5 5-5M5 20h14',
+}
+
+/** @param {string} name */
+function icon(name) {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('aria-hidden', 'true')
+  if (name === 'back' || name === 'next') svg.setAttribute('class', 'deck-flip')
+  const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+  path.setAttribute('d', ICONS[/** @type {keyof typeof ICONS} */ (name)])
+  svg.append(path)
+  return svg
+}
+
+/** @typedef {ReturnType<typeof createDeck>} DeckView */
+
+/** @param {HTMLElement} root @param {Options} options */
+export function createDeck(root, options) {
+  let source = options.source.replace(/\r\n?/g, '\n')
+  let deck = parseDeck(source)
+  let at = 0, stepAt = 0
+  /** @type {{ element: HTMLElement, steps: number }[]} */
+  let drawn = []
+  const lang = String(options.lang ?? deck.settings.lang ?? document.documentElement.lang ?? 'en') || 'en'
+  const dir = String(options.dir ?? deck.settings.dir ?? (RTL.test(lang) ? 'rtl' : 'ltr'))
+  const words = { ...stringsFor(lang), ...options.strings }
+  const number = new Intl.NumberFormat(lang).format
+  const dark = matchMedia('(prefers-color-scheme: dark)')
+  let scheme = /** @type {'light' | 'dark'} */ ('light')
+  const started = Date.now()
+
+  root.classList.add('deck')
+  root.lang = lang
+  root.dir = dir
+  const stage = h('div', { class: 'deck-stage', tabindex: 0, role: 'region', 'aria-roledescription': 'carousel', 'aria-label': words.deck })
+  const where = h('span', { class: 'deck-where', 'aria-live': 'polite' })
+  const button = (/** @type {string} */ name, /** @type {string} */ label, /** @type {() => void} */ act) => {
+    const b = h('button', { type: 'button', 'aria-label': label, 'data-act': name }, [icon(name)])
+    b.addEventListener('click', act)
+    return b
+  }
+  const back = button('back', words.previous, () => move(-1))
+  const next = button('next', words.next, () => move(1))
+  const editButton = button('edit', words.edit, () => toggle('is-editing'))
+  const presenterButton = button('presenter', words.presenter, () => toggle('is-presenting'))
+  const overviewButton = button('grid', words.overview, () => toggle('is-overview'))
+  const bar = h('div', { class: 'deck-bar' }, [back, where, next, h('span', { class: 'deck-gap' }),
+    overviewButton, presenterButton, options.editable === false ? null : editButton,
+    button('scheme', words.scheme, () => { scheme = scheme === 'dark' ? 'light' : 'dark'; paintLook() }),
+    options.onExport ? button('export', words.export, () => options.onExport?.(view)) : null,
+    document.fullscreenEnabled ? button('present', words.present, () => present()) : null])
+  const sourceBox = /** @type {HTMLTextAreaElement} */ (h('textarea', { class: 'deck-source', spellcheck: 'false', 'aria-label': words.source, dir: 'auto' }))
+  const nextBox = h('div', { class: 'deck-next' })
+  const notes = h('div', { class: 'deck-notes', dir: 'auto', 'aria-label': words.notes })
+  const clock = h('span', { class: 'deck-clock' })
+  const presenter = h('div', { class: 'deck-presenter' }, [nextBox, notes])
+  root.replaceChildren(sourceBox, stage, presenter, bar)
+  bar.insertBefore(clock, bar.querySelector('.deck-gap'))
+
+  // The kit: deck's own, under the host's (an organisation's, a project's), under the file's own.
+  let kitProblems = /** @type {string[]} */ ([])
+  const kitOf = () => {
+    const merged = mergeKits(options.kit, deck.settings.kit)
+    kitProblems = merged.problems
+    return merged.kit
+  }
+
+  function paintLook() {
+    context.kit = kitOf()
+    const tokens = tokensOf(deck.settings, context.kit.tokens)
+    const colours = schemeOf(tokens, scheme)
+    const stack = (/** @type {string[]} */ faces) => faces.map((f) => (/^[\w-]+$/.test(f) ? f : `"${f.replace(/["\\]/g, '')}"`)).join(', ')
+    const voice = tokens.fonts ? { heading: stack(tokens.fonts.heading), body: stack(tokens.fonts.body) } : VOICES[tokens.voice]
+    for (const [name, value] of Object.entries({
+      paper: colours.paper, ink: colours.ink, muted: colours.muted, line: colours.line, primary: colours.primary,
+      fill: tokens.primary, 'on-fill': colours.onPrimary, soft: colours.soft, heading: voice.heading, body: voice.body, radius: `${tokens.radius}px`,
+      ...Object.fromEntries(colours.series.map((colour, n) => [`series-${n + 1}`, colour])),
+    })) root.style.setProperty(`--deck-${name}`, value)
+    root.dataset.scheme = scheme
+    root.dispatchEvent(new CustomEvent('deck-scheme', { detail: { scheme, colours, tokens } }))
+  }
+  const chooseScheme = () => {
+    const asked = options.scheme ?? deck.settings.colorSchema ?? 'auto'
+    scheme = asked === 'dark' || (asked === 'auto' && dark.matches) ? 'dark' : 'light'
+  }
+
+  /** @type {import('./render.js').Context} */
+  const context = {
+    blocks: options.blocks ?? {}, resolve: options.resolve ?? ((src) => src), headings: options.headings ?? 'real', number: (n) => number(n), total: 0, kit: mergeKits().kit,
+  }
+
+  function draw() {
+    context.total = deck.slides.length
+    drawn = deck.slides.map((slide) => renderSlide(slide, context))
+    for (const [i, { element }] of drawn.entries()) {
+      element.setAttribute('aria-label', words.where.replace('{n}', number(i + 1)).replace('{count}', number(drawn.length)))
+      element.addEventListener('click', () => { if (root.classList.contains('is-overview')) { toggle('is-overview'); go(i, 0) } })
+    }
+    stage.replaceChildren(...drawn.map(({ element }) => element))
+    at = Math.min(at, drawn.length - 1)
+    show()
+    requestAnimationFrame(() => fitAll())
+  }
+
+  /** Each slot's type shrunk, down to six tenths, until it holds what it says; a slide still over is marked. */
+  function fitAll() {
+    for (const { element } of drawn) fit(element)
+  }
+  /** @param {HTMLElement} slide */
+  function fit(slide) {
+    let over = false
+    for (const slot of /** @type {NodeListOf<HTMLElement>} */ (slide.querySelectorAll('.deck-slot'))) {
+      let scale = 1
+      slot.style.setProperty('--deck-fit', '1')
+      while (slot.scrollHeight > slot.clientHeight + 1 && scale > 0.6) slot.style.setProperty('--deck-fit', String((scale = Math.round((scale - 0.05) * 100) / 100)))
+      if (slot.scrollHeight > slot.clientHeight + 1) over = true
+    }
+    if (over) slide.dataset.overflow = 'true'
+    else delete slide.dataset.overflow
+  }
+
+  function show() {
+    for (const [i, { element, steps }] of drawn.entries()) {
+      element.classList.toggle('is-shown', i === at)
+      element.inert = i !== at && !root.classList.contains('is-overview')
+      for (const one of element.querySelectorAll('.deck-step')) one.classList.toggle('is-on', i < at || (i === at && Number(one.getAttribute('data-step')) <= stepAt) || steps === 0)
+    }
+    where.textContent = `${number(at + 1)} / ${number(drawn.length)}`
+    back.toggleAttribute('disabled', at === 0 && stepAt === 0)
+    next.toggleAttribute('disabled', at >= drawn.length - 1 && stepAt >= (drawn[at]?.steps ?? 0))
+    notes.textContent = deck.slides[at]?.notes || words.noNotes
+    const following = deck.slides[at + 1]
+    nextBox.replaceChildren(h('span', {}, [following ? words.upNext : words.last]), ...(following ? [renderSlide(following, context).element] : []))
+    root.dispatchEvent(new CustomEvent('deck-move', { detail: { at, step: stepAt } }))
+  }
+
+  /** A click on, or the next key: the next step, else the next slide. @param {number} by */
+  function move(by) {
+    const steps = drawn[at]?.steps ?? 0
+    if (by > 0 && stepAt < steps) { stepAt++; show(); return }
+    if (by < 0 && stepAt > 0) { stepAt--; show(); return }
+    const to = at + by
+    if (to < 0 || to >= drawn.length) return
+    go(to, by > 0 ? 0 : drawn[to].steps)
+  }
+
+  /** @param {number} to @param {number} [toStep] */
+  function go(to, toStep = 0) {
+    if (to === at) { stepAt = toStep; show(); return }
+    const forward = to > at
+    const settings = deck.slides[forward ? to : at]?.settings ?? {}
+    const named = String(settings.transition ?? deck.settings.transition ?? 'none')
+    // Slidev's `a | b`: one going forward, the other going back.
+    const [ahead, behind] = named.split('|').map((part) => part.trim())
+    let kind = forward ? ahead : behind ?? ahead
+    if (dir === 'rtl') kind = kind.replace(/-(left|right)$/, (_, side) => (side === 'left' ? '-right' : '-left'))
+    if (kind === 'view-transition') kind = 'morph'
+    const update = () => { at = to; stepAt = toStep; if (kind === 'morph') name(drawn[to].element); show() }
+    const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches
+    if (!document.startViewTransition || kind === 'none' || reduced || root.classList.contains('is-overview')) return update()
+    if (kind === 'morph') name(drawn[at].element, drawn[to].element)
+    document.documentElement.dataset.deckTransition = kind
+    const transition = document.startViewTransition(update)
+    // A transition skipped by the next one, as a clicker pressed twice does, is no error.
+    transition.ready.catch(() => {})
+    transition.finished.finally(() => {
+      delete document.documentElement.dataset.deckTransition
+      for (const { element } of drawn) for (const one of element.querySelectorAll('[data-morph]')) { /** @type {HTMLElement} */ (one).style.removeProperty('view-transition-name'); one.removeAttribute('data-morph') }
+    })
+  }
+
+  /**
+   * Morph, as Keynote's Magic Move and PowerPoint's Morph do it, with nothing to write: what two
+   * slides share (a heading's words, a list item's, a picture, a chart) gets one name on each,
+   * so the browser moves it from where it was to where it goes. Called with the slide shown and
+   * the next, then with the next alone once it shows. @param {HTMLElement} slide @param {HTMLElement} [toward]
+   */
+  function name(slide, toward) {
+    const key = (/** @type {Element} */ el) => `${el.tagName}:${el.tagName === 'IMG' ? el.getAttribute('src') : (el.textContent ?? '').trim().slice(0, 80)}`
+    const parts = (/** @type {HTMLElement} */ s) => /** @type {HTMLElement[]} */ ([...s.querySelectorAll('h1, h2, h3, h4, .deck-h, li, p, img, .deck-block, blockquote, .deck-image')])
+    if (toward) {
+      const there = new Map(parts(toward).map((el) => [key(el), el]))
+      let n = 0
+      for (const el of parts(slide)) {
+        const match = there.get(key(el))
+        if (!match || match.dataset.morph || el.closest('[data-morph]')) continue
+        const id = `deck-m${n++}`
+        el.dataset.morph = match.dataset.morph = id
+        el.style.setProperty('view-transition-name', id)
+      }
+      return
+    }
+    for (const el of /** @type {NodeListOf<HTMLElement>} */ (slide.querySelectorAll('[data-morph]'))) {
+      const id = /** @type {string} */ (el.dataset.morph)
+      for (const old of /** @type {NodeListOf<HTMLElement>} */ (stage.querySelectorAll(`[data-morph="${id}"]`))) if (old !== el) old.style.removeProperty('view-transition-name')
+      el.style.setProperty('view-transition-name', id)
+    }
+  }
+
+  /** @param {string} mode */
+  function toggle(mode) {
+    for (const other of ['is-editing', 'is-presenting', 'is-overview']) if (other !== mode) root.classList.remove(other)
+    root.classList.toggle(mode)
+    editButton.setAttribute('aria-pressed', String(root.classList.contains('is-editing')))
+    presenterButton.setAttribute('aria-pressed', String(root.classList.contains('is-presenting')))
+    overviewButton.setAttribute('aria-pressed', String(root.classList.contains('is-overview')))
+    if (root.classList.contains('is-editing')) { sourceBox.value = source; sourceBox.focus() }
+    show()
+    requestAnimationFrame(() => fitAll())
+  }
+
+  function present() {
+    stage.requestFullscreen?.().then(() => stage.focus(), () => {})
+  }
+
+  /** The source changed, by the Markdown or on a slide: read again, drawn again, where the user is. @param {string} text */
+  function setSource(text) {
+    source = text.replace(/\r\n?/g, '\n')
+    deck = parseDeck(source)
+    paintLook()
+    draw()
+    options.onChange?.(source)
+  }
+
+  // Changed as Markdown: drawn again as the user types, the slide under the caret shown.
+  let pending = 0
+  sourceBox.addEventListener('input', (event) => {
+    if (/** @type {InputEvent} */ (event).isComposing) return
+    clearTimeout(pending)
+    pending = setTimeout(() => setSource(sourceBox.value), 120)
+  })
+  const followCaret = () => {
+    const caret = sourceBox.selectionStart
+    const found = deck.slides.findIndex((slide) => caret >= slide.start && caret <= slide.end + 1)
+    if (found >= 0 && found !== at) { at = found; stepAt = drawn[found]?.steps ?? 0; show() }
+  }
+  sourceBox.addEventListener('keyup', followCaret)
+  sourceBox.addEventListener('click', followCaret)
+
+  // Changed in place: a double click on words makes them editable; Enter or leaving keeps them.
+  stage.addEventListener('dblclick', (event) => {
+    if (options.editable === false || document.fullscreenElement) return
+    const target = /** @type {HTMLElement | null} */ (/** @type {Element} */ (event.target).closest('[data-edit]'))
+    if (!target) return
+    const [from, to] = /** @type {string} */ (target.dataset.edit).split('-').map(Number)
+    target.contentEditable = 'true'
+    target.focus()
+    const done = (/** @type {boolean} */ keep) => {
+      target.removeEventListener('keydown', key)
+      target.removeEventListener('blur', blur)
+      target.contentEditable = 'false'
+      const words = markdownOf(target)
+      if (keep && words !== source.slice(from, to)) setSource(source.slice(0, from) + words + source.slice(to))
+      else draw()
+    }
+    const key = (/** @type {KeyboardEvent} */ e) => {
+      if (e.isComposing) return
+      if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); done(true) }
+      if (e.key === 'Escape') { e.preventDefault(); done(false) }
+    }
+    const blur = () => done(true)
+    target.addEventListener('keydown', key)
+    target.addEventListener('blur', blur)
+  })
+
+  // The keys a clicker sends, and the deck's own.
+  root.addEventListener('keydown', (event) => {
+    const target = /** @type {HTMLElement} */ (event.target)
+    if (target.isContentEditable || target === sourceBox || (target.tagName === 'BUTTON' && (event.key === ' ' || event.key === 'Enter'))) {
+      if ((event.metaKey || event.ctrlKey) && event.key === 's') { event.preventDefault(); options.onSave?.(source) }
+      return
+    }
+    const forward = dir === 'rtl' ? 'ArrowLeft' : 'ArrowRight', backward = dir === 'rtl' ? 'ArrowRight' : 'ArrowLeft'
+    if (event.altKey || event.ctrlKey || event.metaKey) {
+      if ((event.metaKey || event.ctrlKey) && event.key === 's') { event.preventDefault(); options.onSave?.(source) }
+      return
+    }
+    const acts = /** @type {Record<string, () => void>} */ ({
+      [forward]: () => move(1), [backward]: () => move(-1), ArrowDown: () => move(1), ArrowUp: () => move(-1), PageDown: () => move(1), PageUp: () => move(-1), ' ': () => move(1),
+      Home: () => go(0), End: () => go(drawn.length - 1, drawn.at(-1)?.steps ?? 0), f: present, p: () => toggle('is-presenting'), o: () => toggle('is-overview'), e: () => toggle('is-editing'),
+    })
+    const act = acts[event.key]
+    if (!act) return
+    event.preventDefault()
+    act()
+  })
+  stage.addEventListener('click', (event) => {
+    if (document.fullscreenElement && !(/** @type {Element} */ (event.target).closest('a, button, input'))) move(1)
+  })
+  let touch = 0
+  stage.addEventListener('touchstart', (event) => { touch = event.touches[0].clientX }, { passive: true })
+  stage.addEventListener('touchend', (event) => {
+    const dx = event.changedTouches[0].clientX - touch
+    if (Math.abs(dx) > 50) move((dx < 0) === (dir !== 'rtl') ? 1 : -1)
+  })
+  dark.addEventListener('change', () => { chooseScheme(); paintLook() })
+  const tick = setInterval(() => {
+    const s = Math.floor((Date.now() - started) / 1000)
+    clock.textContent = root.classList.contains('is-presenting') ? `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}` : ''
+  }, 1000)
+
+  chooseScheme()
+  paintLook()
+  draw()
+  document.fonts?.ready.then(() => fitAll())
+
+  const view = {
+    root, stage, get source() { return source }, get deck() { return deck }, get at() { return at }, get scheme() { return scheme }, get kit() { return context.kit }, get kitProblems() { return kitProblems }, lang, dir,
+    slides: () => drawn.map(({ element }) => element), setSource, go, toggle, present, fitAll,
+    setScheme: (/** @type {'light' | 'dark'} */ value) => { scheme = value; paintLook() },
+    destroy: () => clearInterval(tick),
+  }
+  return view
+}
+
+/** The Markdown of words changed in place: bold, italics, code and links kept as Markdown writes them. @param {Node} node @returns {string} */
+export function markdownOf(node) {
+  let out = ''
+  for (const child of node.childNodes) {
+    if (child.nodeType === Node.TEXT_NODE) out += (child.textContent ?? '').replace(/([*_`[\]\\])/g, '\\$1')
+    else if (child instanceof HTMLElement) {
+      const inner = markdownOf(child)
+      out += ({ STRONG: `**${inner}**`, B: `**${inner}**`, EM: `*${inner}*`, I: `*${inner}*`, CODE: `\`${child.textContent}\``, DEL: `~~${inner}~~`, BR: '  \n',
+        A: `[${inner}](${child.getAttribute('href') ?? ''})` })[child.tagName] ?? inner
+    }
+  }
+  return out.replace(/ /g, ' ').replace(/\n+$/, '')
+}

package/src/file.js

@@ -0,0 +1,74 @@
+// A deck file, `.deck.html`: a web page any browser opens, whose Markdown sits whole in one
+// element, <script type="text/markdown" id="deck">, which no browser runs. Read and written here
+// as text, never parsed as HTML, so a host can read a deck without running anything in it.
+// The one escape: `<script` and `</script`, in any case, gain a backslash after their `<` (and
+// one more for each already there), which reading takes away again: the HTML parser ends the
+// element at `</script`, and a `<script` after `<!--` would keep it from ending. Pure.
+
+import { VERSION } from './version.js'
+
+export const OPEN = '<script type="text/markdown" id="deck">'
+const CLOSE = '</script>'
+
+/** @param {string} markdown */
+export const escape = (markdown) => markdown.replace(/<(\\*)(\/?script)/gi, '<\\$1$2')
+/** @param {string} text */
+export const unescape = (text) => text.replace(/<\\(\\*)(\/?script)/gi, '<$1$2')
+
+/** @param {string} text */
+const attribute = (text) => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+/** @param {string} text */
+const content = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/**
+ * Code held whole in the file: `</script`, `<script` and `<!--`, which only a string or a regular
+ * expression of a bundle holds, written with `\x3C` for their `<`, which reads the same there.
+ * @param {string} code
+ */
+export function inlineCode(code) {
+  if (/\\<(!--|\/?script)/i.test(code)) throw new Error('This code cannot be held in a page as it is.')
+  return code.replace(/<(!--|\/?script)/gi, '\\x3C$1')
+}
+
+/**
+ * A deck's Markdown, from a file's text, or null when it holds none.
+ * @param {string} html @returns {string | null}
+ */
+export function readDeckFile(html) {
+  const at = html.indexOf(OPEN)
+  if (at < 0) return null
+  const from = at + OPEN.length
+  const end = html.slice(from).search(/<\/script/i)
+  if (end < 0) return null
+  return unescape(html.slice(from, from + end).replace(/^\n/, '').replace(/\n$/, ''))
+}
+
+/** Where a linked file finds its renderer: this version of the package, on jsDelivr's npm mirror. @param {string} [version] */
+export const rendererUrl = (version = VERSION) => `https://cdn.jsdelivr.net/npm/@codename/deck@${version}/dist/deck.js`
+
+/**
+ * A deck file around its Markdown: its title, language and direction in the page's head for
+ * whatever reads it before the renderer does, then the Markdown, in the body (the head is never shown), readable as it is when no
+ * renderer comes, then the renderer: linked by default, to this version's address, or held whole;
+ * `base` tells it where to load the libraries a slide needs (a CDN's npm mirror, or a node_modules).
+ * @param {string} markdown
+ * @param {{ title?: string, lang?: string, dir?: string, renderer?: { src: string } | { code: string }, base?: string, generator?: string }} [options]
+ */
+export function writeDeckFile(markdown, { title = '', lang = 'en', dir = 'auto', renderer = { src: rendererUrl() }, base, generator = `deck ${VERSION}` } = {}) {
+  const data = base ? ` data-base="${attribute(base)}"` : ''
+  const script = 'src' in renderer ? `<script src="${attribute(renderer.src)}"${data}></script>` : `<script${data}>${inlineCode(renderer.code)}</script>`
+  return /* html */ `<!doctype html>
+<html lang="${attribute(lang)}" dir="${attribute(dir)}">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="${attribute(generator)}">
+<title>${content(title)}</title>
+<style>#deck{display:block;white-space:pre-wrap;overflow-wrap:anywhere;font:1rem/1.6 ui-monospace,Menlo,Consolas,monospace;max-width:72ch;margin:2rem auto;padding:0 1rem}</style>
+<body>
+${OPEN}
+${escape(markdown)}
+${CLOSE}
+${script}
+</html>
+`
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// deck for a host: draw a deck into an element, read and write its file, save it as PowerPoint.
+export { createDeck, markdownOf } from './deck.js'
+export { parseDeck } from './parse.js'
+export { renderSlide } from './render.js'
+export { STANDARD, mergeKits, layoutOf, inferLayout, labelOf, tokensFrom } from './kit.js'
+export { tokensOf, schemeOf, LOOKS, readable, contrast } from './look.js'
+export { readDeckFile, writeDeckFile, rendererUrl, escape, unescape } from './file.js'
+export { toPptx } from './pptx.js'
+export { defaultBlocks, libraryAt } from './blocks.js'
+export { inlinePictures } from './pictures.js'
+export { deckIn } from './repair.js'
+export { VERSION } from './version.js'

package/src/kit.js

@@ -0,0 +1,185 @@
+// A kit: a design system and the layouts that go with it, as data and never as CSS or code, so a
+// person, an organisation or a brain can make one and no kit can do more than lay out a slide.
+// deck's own kit holds the usual layouts; a host's (an organisation's, a project's) and the deck
+// file's own `kit:` go over it, in that order. A layout is a grid: its slots by name, the areas
+// they take, its tracks, how its words sit, what paper it is on, and the PowerPoint layout it is
+// nearest to. Everything is checked against a small grammar; what fails is dropped, with a reason.
+// Pure.
+
+/** @typedef {{ required?: boolean, max_words?: number, max_chars?: number, items?: [number, number], item_max_words?: number, heading_max_words?: number, kind?: string }} Budget */
+/** @typedef {{ label?: Record<string, string> | string, intent?: string, use_when?: string, avoid_when?: string, slots: string[], budgets: Record<string, Budget>, areas: string[][], columns: string[], rows: string[], align: 'start' | 'center' | 'end', justify: 'start' | 'center' | 'end', paper: 'paper' | 'fill' | 'ink' | 'soft', title: 'normal' | 'large' | 'huge', pptx: string, numbered: boolean }} Layout */
+/** @typedef {{ name?: string, tokens: Record<string, any>, layouts: Record<string, Layout> }} Kit */
+
+const NAME = /^[a-z][a-z0-9-]{0,31}$/
+const TRACK = /^(auto|min-content|max-content|\d{1,2}(\.\d)?fr|\d{1,3}%)$/
+const PPTX = ['Title Slide', 'Title and Content', 'Section Header', 'Two Content', 'Comparison', 'Title Only', 'Blank', 'Content with Caption', 'Picture with Caption']
+const ENUMS = /** @type {const} */ ({ align: ['start', 'center', 'end'], justify: ['start', 'center', 'end'], paper: ['paper', 'fill', 'ink', 'soft'], title: ['normal', 'large', 'huge'] })
+
+/** The names brains give the usual layouts, for the ones deck has. */
+export const ALIASES = /** @type {Record<string, string>} */ ({
+  title: 'cover', 'title-slide': 'cover', 'two-columns': 'two-cols', 'two-column': 'two-cols', columns: 'two-cols', comparison: 'two-cols-header',
+  'three-columns': 'three-cols', 'section-header': 'section', divider: 'section', big: 'fact', number: 'fact', 'image-text': 'image-right', closing: 'end', thanks: 'end',
+})
+
+/** deck's own kit: the usual layouts, the ones Slidev names and the ones PowerPoint has, as data. */
+export const STANDARD = /** @type {Kit} */ ({
+  name: 'standard',
+  tokens: {},
+  layouts: Object.fromEntries(Object.entries(/** @type {Record<string, any>} */ ({
+    default: { label: { en: 'Title and content', fr: 'Titre et contenu' }, pptx: 'Title and Content' },
+    cover: { label: { en: 'Cover', fr: 'Couverture' }, justify: 'center', paper: 'fill', title: 'huge', pptx: 'Title Slide', numbered: false },
+    intro: { label: { en: 'Introduction', fr: 'Introduction' }, justify: 'center', paper: 'fill', title: 'large', pptx: 'Title Slide', numbered: false },
+    section: { label: { en: 'Section', fr: 'Section' }, justify: 'center', paper: 'ink', title: 'huge', pptx: 'Section Header', numbered: false },
+    center: { label: { en: 'Centred', fr: 'Centré' }, justify: 'center', align: 'center', pptx: 'Title Only' },
+    statement: { label: { en: 'Statement', fr: 'Affirmation' }, justify: 'center', align: 'center', title: 'large', pptx: 'Title Only' },
+    fact: { label: { en: 'Big number', fr: 'Grand chiffre' }, justify: 'center', align: 'center', title: 'huge', pptx: 'Title Only' },
+    quote: { label: { en: 'Quote', fr: 'Citation' }, justify: 'center', pptx: 'Title Only' },
+    end: { label: { en: 'Closing', fr: 'Clôture' }, justify: 'center', align: 'center', paper: 'fill', title: 'large', pptx: 'Title Slide', numbered: false },
+    full: { label: { en: 'Full', fr: 'Plein cadre' }, pptx: 'Blank', numbered: false },
+    none: { label: { en: 'Blank', fr: 'Vide' }, pptx: 'Blank', numbered: false },
+    'two-cols': { label: { en: 'Two columns', fr: 'Deux colonnes' }, slots: ['default', 'right'], areas: 'default right', columns: '1fr 1fr', pptx: 'Two Content' },
+    'two-cols-header': { label: { en: 'Comparison', fr: 'Comparaison' }, slots: ['default', 'left', 'right', 'bottom'], areas: 'default default | left right | bottom bottom', columns: '1fr 1fr', rows: 'auto 1fr auto', pptx: 'Comparison' },
+    'three-cols': { label: { en: 'Three columns', fr: 'Trois colonnes' }, slots: ['default', 'left', 'middle', 'right'], areas: 'default default default | left middle right', columns: '1fr 1fr 1fr', rows: 'auto 1fr', pptx: 'Comparison' },
+    'image-left': { label: { en: 'Picture left', fr: 'Image à gauche' }, pptx: 'Picture with Caption', justify: 'center' },
+    'image-right': { label: { en: 'Picture right', fr: 'Image à droite' }, pptx: 'Picture with Caption', justify: 'center' },
+    image: { label: { en: 'Picture', fr: 'Image' }, pptx: 'Blank', numbered: false },
+  })).map(([name, given]) => [name, /** @type {Layout} */ (layoutOf(given).layout)])),
+})
+
+/**
+ * A layout as given, checked: its slots, areas and tracks in the grammar, its words' place, paper
+ * and size among their names. @param {any} given @returns {{ layout: Layout | null, problems: string[] }}
+ */
+export function layoutOf(given) {
+  const problems = []
+  if (!given || typeof given !== 'object') return { layout: null, problems: ['not a layout'] }
+  // Slots as names, or as a catalog writes them: each a budget, `title` being the heading the
+  // default slot opens with rather than a slot of its own.
+  /** @type {Record<string, Budget>} */
+  const budgets = {}
+  const named = Array.isArray(given.slots) || typeof given.slots === 'string' ? [given.slots].flat().map(String)
+    : given.slots && typeof given.slots === 'object' ? Object.entries(given.slots).map(([name, budget]) => {
+      if (budget && typeof budget === 'object') budgets[name] = clean(budget)
+      return name === 'title' ? 'default' : name
+    }) : ['default']
+  const slots = [...new Set(named)]
+  if (!slots.every((slot) => NAME.test(slot))) return { layout: null, problems: ['a slot name is not a-z, 0-9 and -'] }
+  if (!slots.includes('default')) slots.unshift('default')
+  // Areas as Slidev's and CSS's grid write them, rows split by | or new lines.
+  /** @type {string[]} */
+  const lines = Array.isArray(given.areas) ? given.areas.map((/** @type {any} */ row) => [row].flat().join(' ')) : String(given.areas ?? slots.join(' ')).split(/\||\n/)
+  const rows = lines.map((row) => row.trim().replace(/^"|"$/g, '').split(/\s+/)).filter((row) => row.length && row[0])
+  const width = rows[0]?.length ?? 0
+  if (!rows.length || rows.some((row) => row.length !== width) || rows.flat().some((cell) => cell !== '.' && !slots.includes(cell))) return { layout: null, problems: ['areas are not a rectangle of its slots'] }
+  for (const slot of slots) {
+    const cells = rows.flatMap((row, y) => row.map((cell, x) => /** @type {[string, number, number]} */ ([cell, x, y]))).filter(([cell]) => cell === slot)
+    if (!cells.length) { if (slot !== 'default') problems.push(`slot ${slot} has no area`); continue }
+    const xs = cells.map((c) => c[1]), ys = cells.map((c) => c[2])
+    if (cells.length !== (Math.max(...xs) - Math.min(...xs) + 1) * (Math.max(...ys) - Math.min(...ys) + 1)) return { layout: null, problems: [`slot ${slot} is not a rectangle`] }
+  }
+  const tracks = (/** @type {any} */ value, /** @type {number} */ count) => {
+    const list = value === undefined ? Array(count).fill('1fr') : (Array.isArray(value) ? value : String(value).split(/\s+/)).map(String)
+    return list.length === count && list.every((t) => TRACK.test(t)) ? list : null
+  }
+  const columns = tracks(given.columns, width), rowTracks = tracks(given.rows, rows.length)
+  if (!columns || !rowTracks) return { layout: null, problems: ['columns or rows are not tracks deck knows (auto, 1fr, 40%…), one per column or row'] }
+  const pick = (/** @type {keyof typeof ENUMS} */ key, /** @type {string} */ fallback) => {
+    const value = String(given[key] ?? fallback)
+    if (!(/** @type {readonly string[]} */ (ENUMS[key])).includes(value)) { problems.push(`${key} ${value} is not one of ${ENUMS[key].join(', ')}`); return fallback }
+    return value
+  }
+  const label = typeof given.label === 'string' || (given.label && typeof given.label === 'object') ? given.label : undefined
+  const words = (/** @type {any} */ v) => (typeof v === 'string' ? v.slice(0, 300) : undefined)
+  return {
+    layout: /** @type {Layout} */ ({
+      label, intent: words(given.intent), use_when: words(given.use_when), avoid_when: words(given.avoid_when), slots, budgets, areas: rows, columns, rows: rowTracks,
+      align: pick('align', 'start'), justify: pick('justify', 'start'), paper: pick('paper', 'paper'), title: pick('title', 'normal'),
+      pptx: PPTX.includes(given.pptx) ? given.pptx : slots.length > 1 ? 'Comparison' : 'Title and Content', numbered: given.numbered !== false,
+    }),
+    problems,
+  }
+}
+
+/** A slot's budget, its numbers only. @param {Record<string, any>} given @returns {Budget} */
+function clean(given) {
+  /** @type {Record<string, any>} */
+  const kept = {}
+  for (const key of ['max_words', 'max_chars', 'item_max_words', 'heading_max_words']) if (Number.isInteger(given[key]) && given[key] > 0) kept[key] = given[key]
+  if (Array.isArray(given.items) && given.items.length === 2 && given.items.every(Number.isInteger)) kept.items = given.items
+  if (typeof given.required === 'boolean') kept.required = given.required
+  if (typeof given.kind === 'string' && /^[a-z-]{1,20}$/.test(given.kind)) kept.kind = given.kind
+  return kept
+}
+
+/**
+ * Design tokens as the W3C's Design Tokens format (DTCG 2025.10) writes them, read into a kit's:
+ * `color.light` and `color.dark` groups (bg, surface, fg, muted, accent) or flat colours, `font.sans`
+ * and the like; each `$value` a hex string or a colour object with its `hex`. Tokens already flat
+ * pass through. @param {any} given @returns {Record<string, any>}
+ */
+export function tokensFrom(given) {
+  if (!given || typeof given !== 'object') return {}
+  if (!JSON.stringify(given).includes('"$value"')) return given
+  const value = (/** @type {any} */ t) => (t && typeof t === 'object' && '$value' in t ? t.$value : t)
+  const colour = (/** @type {any} */ t) => { const v = value(t); return typeof v === 'string' ? v : typeof v?.hex === 'string' ? v.hex : undefined }
+  const face = (/** @type {any} */ t) => { const v = value(t); return Array.isArray(v) ? v.map(String) : typeof v === 'string' ? [v] : undefined }
+  const NAMES = /** @type {const} */ ({ bg: 'paper', background: 'paper', paper: 'paper', fg: 'ink', text: 'ink', ink: 'ink', accent: 'primary', primary: 'primary', muted: 'muted', surface: 'soft', soft: 'soft' })
+  const group = (/** @type {any} */ g) => Object.fromEntries(Object.entries(g ?? {}).filter(([k]) => k in NAMES).map(([k, t]) => [NAMES[/** @type {keyof typeof NAMES} */ (k)], colour(t)]).filter(([, v]) => v))
+  const colours = given.color ?? given.colour ?? {}
+  /** @type {Record<string, any>} */
+  const tokens = { ...group(colours), ...group(colours.light) }
+  const dark = group(colours.dark)
+  if (Object.keys(dark).length) tokens.dark = dark
+  const fonts = given.font ?? given.fontFamily ?? {}
+  const heading = face(fonts.heading ?? fonts.display ?? fonts.sans), body = face(fonts.body ?? fonts.text ?? fonts.sans)
+  if (heading || body) tokens.fonts = { heading: heading ?? body, body: body ?? heading }
+  return tokens
+}
+
+/**
+ * Kits merged, the later over the earlier: their tokens, and their layouts by name, each checked.
+ * @param {...any} kits @returns {{ kit: Kit, problems: string[] }}
+ */
+export function mergeKits(...kits) {
+  /** @type {Kit} */
+  const kit = { name: 'standard', tokens: {}, layouts: { ...STANDARD.layouts } }
+  const problems = []
+  for (const given of kits) {
+    if (!given || typeof given !== 'object') continue
+    if (typeof given.name === 'string') kit.name = given.name
+    if (given.tokens && typeof given.tokens === 'object') kit.tokens = { ...kit.tokens, ...tokensFrom(given.tokens) }
+    for (const [name, definition] of Object.entries(given.layouts ?? given.types ?? {})) {
+      if (!NAME.test(name)) { problems.push(`layout ${name}: not a-z, 0-9 and -`); continue }
+      const { layout, problems: found } = layoutOf(definition)
+      problems.push(...found.map((p) => `layout ${name}: ${p}`))
+      if (layout) kit.layouts[name] = layout
+    }
+  }
+  return { kit, problems }
+}
+
+/** A layout's name in a language, else its own name. @param {Layout} layout @param {string} name @param {string} lang */
+export function labelOf(layout, name, lang) {
+  if (typeof layout.label === 'string') return layout.label
+  return layout.label?.[lang] ?? layout.label?.[lang.split('-')[0]] ?? layout.label?.en ?? name
+}
+
+/**
+ * The layout a slide that names none is given, from what it holds, as Pandoc's PowerPoint writer
+ * chooses: the first slide is the cover; a heading alone, a section; slots beyond the first, the
+ * layout of two (or three) columns that has them; a number alone as its heading, a fact; a quote
+ * alone, a quote; else the default. @param {{ index: number, slots: { name: string, text: string }[] }} slide
+ */
+export function inferLayout(slide) {
+  const names = slide.slots.map((slot) => slot.name)
+  if (names.includes('middle')) return 'three-cols'
+  if (names.includes('left')) return 'two-cols-header'
+  if (names.includes('right')) return 'two-cols'
+  if (slide.index === 0) return 'cover'
+  const text = slide.slots.map((slot) => slot.text).join('\n').trim()
+  const lines = text.split('\n').filter((line) => line.trim())
+  if (lines.length === 1 && /^#{1,2}\s+\S/.test(lines[0])) return 'section'
+  if (/^#\s+[^\s]*\d[\d\s.,%€$£¥]*\S*\s*$/u.test(lines[0] ?? '') && lines.length <= 3 && !/^\s*[-*\d]+[.)]?\s/m.test(lines.slice(1).join('\n'))) return 'fact'
+  if (lines.length && lines.every((line, i) => line.startsWith('>') || (i === lines.length - 1 && !line.startsWith('#')))) return lines[0].startsWith('>') ? 'quote' : 'default'
+  return 'default'
+}