@codename/deck 0.0.0-stage → 0.1.1

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'
+}

package/src/look.js

@@ -0,0 +1,124 @@
+// A deck's look: a design system's few tokens (paper, ink, primary, a voice for its type), from a
+// named look, then the project's, then the deck's own `themeConfig`, as Slidev names a theme's
+// settings. Light and dark are both worked out from them: each colour kept at its hue, deepened or
+// lightened until it reads at AA on the paper it sits on (4.5:1 for words, 3:1 for a chart's
+// marks), so a brain's or a person's colours can't make a slide unreadable. Pure.
+
+/** @typedef {{ paper: string, ink: string, primary: string, voice: string, radius: number, muted?: string, soft?: string, dark?: Record<string, string>, fonts?: { heading: string[], body: string[] } }} Tokens */
+/** @typedef {{ paper: string, ink: string, muted: string, line: string, primary: string, onPrimary: string, soft: string, series: string[] }} Scheme */
+
+/** Looks a deck can name (`theme:`), each a handful of tokens. */
+export const LOOKS = /** @type {Record<string, Tokens>} */ ({
+  default: { paper: '#fffdf8', ink: '#1d1b16', primary: '#f7c531', voice: 'calm', radius: 10 },
+  ocean: { paper: '#f6fafb', ink: '#0d2530', primary: '#0f766e', voice: 'calm', radius: 6 },
+  ember: { paper: '#fff8f3', ink: '#2a160c', primary: '#d9480f', voice: 'bold', radius: 2 },
+  ink: { paper: '#ffffff', ink: '#111111', primary: '#3b5bdb', voice: 'elegant', radius: 0 },
+})
+
+/** Type for each voice: the device's faces, so a deck needs nothing to download to look right. */
+export const VOICES = /** @type {Record<string, { heading: string, body: string }>} */ ({
+  calm: { heading: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, "Noto Sans", sans-serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, "Noto Sans", sans-serif' },
+  elegant: { heading: 'ui-serif, "Iowan Old Style", Georgia, "Noto Serif", serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif' },
+  bold: { heading: '"Avenir Next Condensed", "Arial Narrow", ui-sans-serif, system-ui, sans-serif', body: 'ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif' },
+  friendly: { heading: 'ui-rounded, "SF Pro Rounded", "Nunito", system-ui, sans-serif', body: 'ui-rounded, "SF Pro Rounded", system-ui, sans-serif' },
+})
+
+/**
+ * The tokens a deck's settings give, over the project's look and a named one.
+ * @param {Record<string, any>} settings @param {Partial<Tokens>} [project]
+ * @returns {Tokens}
+ */
+export function tokensOf(settings, project = {}) {
+  const named = LOOKS[String(settings.theme ?? '')] ?? LOOKS.default
+  const own = typeof settings.themeConfig === 'object' && settings.themeConfig ? settings.themeConfig : {}
+  /** @type {Tokens} */
+  const tokens = { ...named, ...clean(project), ...clean(own) }
+  if (!VOICES[tokens.voice]) tokens.voice = 'calm'
+  return tokens
+}
+
+/** @param {Record<string, any>} given @returns {Partial<Tokens>} */
+function clean(given) {
+  /** @type {Partial<Tokens>} */
+  const kept = {}
+  for (const key of /** @type {const} */ (['paper', 'ink', 'primary', 'muted', 'soft'])) if (typeof given[key] === 'string' && hex(given[key])) kept[key] = given[key]
+  if (given.dark && typeof given.dark === 'object') kept.dark = Object.fromEntries(Object.entries(given.dark).filter(([, v]) => typeof v === 'string' && hex(v)))
+  if (given.fonts && Array.isArray(given.fonts.heading) && Array.isArray(given.fonts.body)) kept.fonts = { heading: given.fonts.heading.map(String), body: given.fonts.body.map(String) }
+  if (typeof given.voice === 'string') kept.voice = given.voice
+  if (typeof given.radius === 'number') kept.radius = given.radius
+  return kept
+}
+
+/**
+ * Light or dark, worked out from the tokens: dark swaps paper and ink and lifts the primary.
+ * @param {Tokens} tokens @param {'light' | 'dark'} scheme @returns {Scheme}
+ */
+export function schemeOf(tokens, scheme) {
+  const light = hex(tokens.paper) ?? [255, 253, 248], dark = hex(tokens.ink) ?? [29, 27, 22]
+  // A kit's own dark colours where it gives them (a design system's dark mode), else worked out.
+  const own = scheme === 'dark' ? tokens.dark ?? {} : {}
+  const paper = round(hex(own.paper ?? '') ?? (scheme === 'dark' ? mix(dark, [0, 0, 0], 0.35) : light))
+  const ink = round(hex(own.ink ?? '') ?? (scheme === 'dark' ? mix(light, [255, 255, 255], 0.2) : dark))
+  const primary = hex(own.primary ?? tokens.primary) ?? [247, 197, 49]
+  // The primary as a fill keeps its own colour; as words or marks it is made to read on the paper.
+  const text = readable(primary, paper, 4.5)
+  const onPrimary = contrast(ink, primary) >= contrast(paper, primary) ? ink : paper
+  const series = [0, 1, 2, 3, 4, 5].map((n) => readable(rotate(primary, n * 57), paper, 3))
+  return {
+    paper: css(paper), ink: css(ink), muted: css(readable(round(hex(own.muted ?? (scheme === 'light' ? tokens.muted ?? '' : '')) ?? mix(ink, paper, 0.38)), paper, 4.5)), line: css(mix(ink, paper, 0.82)),
+    primary: css(text), onPrimary: css(onPrimary), soft: css(hex(own.soft ?? (scheme === 'light' ? tokens.soft ?? '' : '')) ?? mix(primary, paper, 0.78)), series: series.map(css),
+  }
+}
+
+/** @param {string} value @returns {[number, number, number] | null} */
+export function hex(value) {
+  const m = /^#?([\da-f]{3}|[\da-f]{6})$/i.exec(String(value).trim())
+  if (!m) return null
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1]
+  return /** @type {[number, number, number]} */ ([0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)))
+}
+
+/** @param {number[]} rgb */
+export const css = (rgb) => `#${rgb.map((c) => Math.round(Math.max(0, Math.min(255, c))).toString(16).padStart(2, '0')).join('')}`
+
+/** A colour as it will be written: whole numbers, so that it reads at the ratio checked. @param {number[]} c */
+const round = (c) => /** @type {[number, number, number]} */ (c.map((v) => Math.round(Math.max(0, Math.min(255, v)))))
+
+/** @param {number[]} a @param {number[]} b @param {number} t */
+const mix = (a, b, t) => /** @type {[number, number, number]} */ (a.map((c, i) => c + (b[i] - c) * t))
+
+/** @param {number[]} rgb */
+function luminance(rgb) {
+  const [r, g, b] = rgb.map((c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4 })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** WCAG's contrast ratio. @param {number[]} a @param {number[]} b */
+export function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}
+
+/**
+ * The colour, its hue kept, deepened or lightened toward black or white until it reads at the
+ * ratio on the paper. @param {number[]} colour @param {number[]} paper @param {number} ratio
+ */
+export function readable(colour, paper, ratio) {
+  const toward = luminance(paper) > 0.18 ? [0, 0, 0] : [255, 255, 255]
+  let t = 0, out = round(colour)
+  while (contrast(out, paper) < ratio && t < 1) out = round(mix(colour, toward, (t = Math.min(1, t + 0.02))))
+  return out
+}
+
+/** The colour turned round the colour wheel. @param {number[]} rgb @param {number} degrees */
+function rotate(rgb, degrees) {
+  const [r, g, b] = rgb.map((c) => c / 255)
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2
+  const d = max - min
+  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1))
+  let h = d === 0 ? 0 : max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+  h = (h * 60 + degrees + 360) % 360
+  const c = (1 - Math.abs(2 * l - 1)) * Math.max(s, 0.55), x = c * (1 - Math.abs(((h / 60) % 2) - 1)), m = l - c / 2
+  const [p, q, u] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x]
+  return [p + m, q + m, u + m].map((v) => v * 255)
+}

package/src/parse.js

@@ -0,0 +1,180 @@
+// A deck's Markdown read as Slidev reads it (@slidev/parser's rules): slides between `---` lines;
+// a `---` line followed by a line that isn't empty opens that slide's settings, YAML up to the next
+// `---` line (or a ```yaml block at the slide's top); the first slide's settings are the deck's
+// too (its headmatter); the last HTML comment at a slide's end is the speaker's notes; `::name::`
+// on its own line starts a layout's slot. Fenced code and comments never split a slide. Every slide
+// and slot keeps where it starts in the source, so an edit made on a slide goes back to its words.
+// Read too, as brains write them even when asked for Slidev: Pandoc's and Quarto's fenced divs,
+// `::: notes` as the notes, and `:::: columns` holding `::: column`s as slots (what is above them
+// the heading, each column a slot, what is under them the foot), never rewritten.
+// Pure: no DOM, no Markdown parser.
+import { parseYaml } from './yaml.js'
+
+/** @typedef {{ name: string, text: string, start: number }} Slot */
+/** @typedef {{ index: number, start: number, end: number, settings: Record<string, any>, slots: Slot[], notes: string, title: string }} Slide */
+/** @typedef {{ settings: Record<string, any>, slides: Slide[] }} Deck */
+
+const SLOT = /^::([\w-]+)::\s*$/
+
+/** @param {string} source @returns {Deck} */
+export function parseDeck(source) {
+  const text = source.replace(/\r\n?/g, '\n')
+  const lines = text.split('\n')
+  const offsets = [0]
+  for (const line of lines) offsets.push(/** @type {number} */ (offsets.at(-1)) + line.length + 1)
+  /** @type {{ start: number, end: number, matter: [number, number] | null }[]} */
+  const ranges = []
+  let start = 0, matter = /** @type {[number, number] | null} */ (null), comment = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trimEnd()
+    if (comment) { comment = commentGoesOn(line, true); continue }
+    if (line.startsWith('---') && !/^---\s*-/.test(line)) {
+      if (i > start || matter) ranges.push({ start, end: i, matter })
+      matter = null
+      start = i + 1
+      // Settings only when settings follow (a `key:` line), not words: Slidev would take a heading
+      // there for settings and lose the slide, as decks brains write often start `---`, `# Title`.
+      if (line[3] !== '-' && lines[i + 1]?.trim() && /^\s*([\w-]+\s*:|#\s)/.test(lines[i + 1]) && !/^#{1,6}\s/.test(lines[i + 1])) {
+        let j = i + 1
+        while (j < lines.length && lines[j].trimEnd() !== '---') j++
+        matter = [i + 1, j]
+        i = j
+        start = j + 1
+      }
+    } else if (/^\s*(`{3,}|~{3,})/.test(line)) {
+      const fence = /** @type {RegExpExecArray} */ (/^\s*(`{3,}|~{3,})/.exec(line))[1]
+      let j = i + 1
+      while (j < lines.length && !lines[j].trimStart().startsWith(fence)) j++
+      if (j < lines.length) i = j
+    } else comment = commentGoesOn(line, false)
+  }
+  if (start < lines.length || matter) ranges.push({ start, end: lines.length, matter })
+  // No `---` at all, as a document or a Pandoc deck is written: a slide at each heading of the first
+  // two levels, as Pandoc's slide level does, the headmatter staying with the first.
+  const last = /** @type {{ start: number, end: number, matter: [number, number] | null }} */ (ranges.at(-1))
+  if (ranges.length === 1 && last) {
+    let fence = ''
+    const heads = []
+    for (let i = last.start; i < last.end; i++) {
+      const mark = /^\s*(`{3,}|~{3,})/.exec(lines[i])?.[1]
+      if (fence) { if (mark && lines[i].trimStart().startsWith(fence)) fence = '' }
+      else if (mark) fence = mark
+      else if (/^#{1,2}\s+\S/.test(lines[i])) heads.push(i)
+    }
+    if (heads.length >= 2) {
+      ranges.pop()
+      const cuts = heads[0] > last.start && !lines.slice(last.start, heads[0]).some((line) => line.trim()) ? heads : [last.start, ...heads.slice(heads[0] === last.start ? 1 : 0)]
+      cuts.forEach((at, k) => ranges.push({ start: k === 0 ? last.start : at, end: cuts[k + 1] ?? last.end, matter: k === 0 ? last.matter : null }))
+    }
+  }
+  const slides = ranges.map(({ start, end, matter }, index) => slide(lines, offsets, start, end, matter, index))
+    .filter((one, i) => i === 0 || one.slots.some((slot) => slot.text.trim()) || Object.keys(one.settings).length)
+  slides.forEach((one, i) => { one.index = i })
+  return { settings: slides[0]?.settings ?? {}, slides }
+}
+
+/**
+ * Pandoc's columns, as the lines where each slot starts: the first column `left`, the next `right`
+ * (or `middle`, then `right`, for three), the line after the columns `bottom`. The fences' own lines
+ * are left as they are and drawn as nothing. @param {string[]} lines @returns {Map<number, string>}
+ */
+function columnsOf(lines) {
+  /** @type {Map<number, string>} */
+  const starts = new Map()
+  const open = lines.findIndex((line) => /^:{3,}[ \t]*\{?[ \t]*\.?columns\b/.test(line))
+  if (open < 0) return starts
+  const fence = /** @type {RegExpExecArray} */ (/^:+/.exec(lines[open]))[0]
+  const close = lines.findIndex((line, i) => i > open && line.trim() === fence)
+  const cols = lines.map((line, i) => [line, i]).filter(([line, i]) => Number(i) > open && (close < 0 || Number(i) < close) && /^:{3,}[ \t]*\{?[ \t]*\.?col(umn)?\b/.test(String(line))).map(([, i]) => Number(i))
+  if (cols.length < 2) return starts
+  const names = cols.length === 2 ? ['left', 'right'] : ['left', 'middle', 'right', ...cols.slice(3).map((_, k) => `col-${k + 4}`)]
+  cols.forEach((at, k) => starts.set(at, names[k]))
+  if (close > 0 && lines.slice(close + 1).some((line) => line.trim())) starts.set(close, 'bottom')
+  return starts
+}
+
+/** Whether a comment is still open at this line's end. @param {string} line @param {boolean} open */
+function commentGoesOn(line, open) {
+  let at = 0
+  for (;;) {
+    if (open) {
+      const end = line.indexOf('-->', at)
+      if (end < 0) return true
+      open = false
+      at = end + 3
+    } else {
+      const begin = line.indexOf('<!--', at)
+      if (begin < 0) return false
+      const end = line.indexOf('-->', begin + 4)
+      if (end < 0) return true
+      at = end + 3
+    }
+  }
+}
+
+/**
+ * @param {string[]} lines @param {number[]} offsets @param {number} from @param {number} to
+ * @param {[number, number] | null} matter @param {number} index @returns {Slide}
+ */
+function slide(lines, offsets, from, to, matter, index) {
+  let settings = matter ? parseYaml(lines.slice(matter[0], matter[1]).join('\n')) : {}
+  let top = from
+  // Slidev's other way to write settings: a ```yaml block at the slide's top.
+  while (top < to && !lines[top].trim()) top++
+  if (!matter && /^```ya?ml\s*$/.test(lines[top] ?? '')) {
+    let j = top + 1
+    while (j < to && !lines[j].startsWith('```')) j++
+    settings = parseYaml(lines.slice(top + 1, j).join('\n'))
+    from = j + 1
+  }
+  let body = lines.slice(from, to).join('\n')
+  let notes = ''
+  // remark's `???` and reveal.js's `Note:`: what follows, to the slide's end, is the notes.
+  const after = /^(\?\?\?|Notes?:)[ \t]*(.*)$/m.exec(body)
+  if (after && after.index !== undefined && !/^```/m.test(body.slice(after.index))) {
+    notes = [after[2], body.slice(after.index + after[0].length)].join('\n').trim()
+    body = body.slice(0, after.index)
+  }
+  // reveal.js's <aside class="notes">, wherever on the slide, as Pandoc's below.
+  body = body.replace(/<aside\b[^>]*class=["']?notes["']?[^>]*>([\s\S]*?)<\/aside>/gi, (all, text) => {
+    notes += (notes ? '\n' : '') + text.replace(/<[^>]*>/g, ' ').replace(/[ \t]+/g, ' ').trim()
+    return all.replace(/[^\n]/g, ' ')
+  })
+  // Pandoc's notes, wherever on the slide: kept as the notes, blanked in place so offsets stay.
+  body = body.replace(/^(:{3,})[ \t]*\{?[ \t]*\.?notes[ \t]*\}?[ \t]*\n([\s\S]*?)\n\1[ \t]*$/gm, (all, _, text) => {
+    notes += (notes ? '\n' : '') + text.trim()
+    return all.replace(/[^\n]/g, ' ')
+  })
+  const comments = [...body.matchAll(/<!--([\s\S]*?)-->/g)]
+  const last = comments.at(-1)
+  if (last && last.index !== undefined && !body.slice(last.index + last[0].length).trim()) {
+    notes = [last[1].trim(), notes].filter(Boolean).join('\n')
+    body = body.slice(0, last.index)
+  }
+  // Each slot's text is the source's own, from where it starts, so offsets in it are the source's.
+  /** @type {Slot[]} */
+  const slots = []
+  let name = 'default', first = from, fence = ''
+  /** @type {string[]} */
+  let taken = []
+  const push = () => slots.push({ name, text: taken.join('\n'), start: offsets[first] })
+  const columns = columnsOf(body.split('\n'))
+  for (const [i, line] of body.split('\n').entries()) {
+    const mark = /^\s*(`{3,}|~{3,})/.exec(line)?.[1]
+    const marker = SLOT.exec(line) ?? (columns.has(i) ? [line, /** @type {string} */ (columns.get(i))] : null)
+    if (fence) { if (mark && line.trimStart().startsWith(fence)) fence = '' }
+    else if (mark) fence = mark
+    else if (marker) {
+      push()
+      name = marker[1]
+      taken = []
+      first = from + i + 1
+      continue
+    }
+    taken.push(line)
+  }
+  push()
+  const kept = slots.filter((slot, i) => i > 0 || slot.text.trim() || slots.length === 1)
+  const heading = /^#{1,6}\s+(.+)$/m.exec(body.replace(/^```[\s\S]*?^```/gm, ''))
+  return { index, start: offsets[matter ? matter[0] - 1 : from], end: offsets[to] - 1, settings, slots: kept, notes, title: String(settings.title ?? heading?.[1] ?? '').trim() }
+}

package/src/pictures.js

@@ -0,0 +1,47 @@
+// Pictures held inside a deck, for a file that leaves its host: each picture the deck names by an
+// address of the host's own (a project's file, a relative path) becomes a data: address holding the
+// picture itself, in the Markdown's images (`![words](place)`) and in a slide's settings (`image`,
+// `background`, `backgroundImage`). Pictures on the web stay links unless asked for, and nothing else
+// in the text moves. Pure but for the host's `read`, which gives a picture's bytes and type.
+
+const SETTINGS = /^(\s*(?:image|background|backgroundImage)\s*:\s*)(['"]?)([^'"\n#]+?)\2(\s*(?:#.*)?)$/gm
+const IMAGE = /(!\[[^\]\n]*\]\()(<[^>\n]+>|[^\s)\n]+)((?:\s+(?:"[^"\n]*"|'[^'\n]*'))?\))/g
+
+/** @param {string} place */
+const held = (place) => /^data:/i.test(place)
+/** @param {string} place */
+const web = (place) => /^(https?:)?\/\//i.test(place)
+
+/** @param {Uint8Array} bytes */
+function base64(bytes) {
+  let text = ''
+  for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  return btoa(text)
+}
+
+/**
+ * The deck with its pictures inside it.
+ * @param {string} source
+ * @param {(place: string) => Promise<{ type: string, bytes: Uint8Array } | null>} read
+ * @param {{ web?: boolean, largest?: number }} [options] `web`: pictures on the web too; `largest`: bytes past which a picture stays a link
+ * @returns {Promise<{ source: string, inlined: string[], missing: string[], kept: string[] }>}
+ */
+export async function inlinePictures(source, read, { web: fromWeb = false, largest = 8 * 1024 * 1024 } = {}) {
+  /** @type {Map<string, string | null>} */
+  const found = new Map()
+  const places = [...source.matchAll(IMAGE)].map((m) => m[2].replace(/^<|>$/g, '')).concat([...source.matchAll(SETTINGS)].map((m) => m[3].trim()))
+  const inlined = [], missing = [], kept = []
+  for (const place of new Set(places)) {
+    if (held(place) || (web(place) && !fromWeb) || /^(#|mailto:|javascript:)/i.test(place)) continue
+    const picture = await read(place).catch(() => null)
+    if (!picture || !/^image\/(png|jpeg|gif|webp|avif|svg\+xml)$/.test(picture.type)) { missing.push(place); found.set(place, null); continue }
+    if (picture.bytes.length > largest) { kept.push(place); found.set(place, null); continue }
+    found.set(place, `data:${picture.type};base64,${base64(picture.bytes)}`)
+    inlined.push(place)
+  }
+  const swap = (/** @type {string} */ place) => found.get(place) ?? null
+  const out = source
+    .replace(IMAGE, (all, open, place, close) => { const data = swap(place.replace(/^<|>$/g, '')); return data ? `${open}${data}${close}` : all })
+    .replace(SETTINGS, (all, key, quote, place, rest) => { const data = swap(place.trim()); return data ? `${key}${quote}${data}${quote}${rest}` : all })
+  return { source: out, inlined, missing, kept }
+}