mdeck 2.3.0 → 3.0.0

package/src/extensions/appearance.js

@@ -6,6 +6,7 @@
 // one is available to inverted slides as --inverse-bg, --inverse-ink, …
 // Theme tokens (type, spacing, fonts) and theme parameters come on top.
 import { tokensToCss, COLOR_ROLES, APPEARANCES, palettesFor } from './tokens.js'
+import { movedHint } from './moved.js'
 
 // Code highlighting and logos on dark slides, unless the palette says otherwise.
 export const DARK_TOKENS = {
@@ -34,7 +35,7 @@ export function resolvePalette({ theme, palettes = {}, palette: requested, appea
   const warnings = []
   const offered = palettesFor(theme, palettes)
   let palette = requested ? palettes[requested] : null
-  if (requested && !palette) warnings.push(`Unknown palette "${requested}". Available: ${offered.map(p => p.id).join(', ')}`)
+  if (requested && !palette) warnings.push(movedHint('palette', requested) ?? `Unknown palette "${requested}". Available: ${offered.map(p => p.id).join(', ')}`)
   else if (palette && !offered.includes(palette)) { warnings.push(`The theme "${theme.id}" does not offer the palette "${requested}". Available: ${offered.map(p => p.id).join(', ')}`); palette = null }
   palette ??= palettes[theme.palette] ?? offered[0] ?? null
   let appearance = requestedAppearance || theme.appearance || 'light'

package/src/extensions/discover.js

@@ -1,26 +1,55 @@
 // One discovery layer for layouts, themes and palettes. The same registry
 // backs `mdeck check`, CLI listings, the dev server and builds.
 import { palettesFor } from './tokens.js'
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { resolve, dirname, relative } from 'node:path'
 import { homedir } from 'node:os'
 import { MANIFEST_FILENAME, ManifestError, KINDS, parseManifestText, validateManifest } from './manifest.js'
-import { builtinExtensionsRoot } from '../paths.js'
+import { builtinExtensionsRoot, bundledPacksRoot } from '../paths.js'
 
 const SKIP = name => name.startsWith('.') || name === 'node_modules'
 
+// mdeck's own folder for this user: ~/.mdeck, or $MDECK_HOME.
+export function mdeckHome() {
+  return process.env.MDECK_HOME || resolve(homedir(), '.mdeck')
+}
+
 // Extensions installed for one user (`mdeck themes install --global`), for
-// every deck: ~/.mdeck/extensions, or $MDECK_HOME/extensions.
+// every deck: ~/.mdeck/extensions.
 export function userExtensionsDir() {
-  return resolve(process.env.MDECK_HOME || resolve(homedir(), '.mdeck'), 'extensions')
+  return resolve(mdeckHome(), 'extensions')
+}
+
+// The bundled packs this user removed (`mdeck themes remove <pack> --global`):
+// they stay in mdeck's folder but are not offered.
+const removedFile = () => resolve(mdeckHome(), 'removed.json')
+export function removedPacks() {
+  try { const packs = JSON.parse(readFileSync(removedFile(), 'utf8')).packs; return Array.isArray(packs) ? packs : [] } catch { return [] }
+}
+export function setRemovedPacks(packs) {
+  mkdirSync(mdeckHome(), { recursive: true })
+  writeFileSync(removedFile(), JSON.stringify({ packs: [...new Set(packs)].sort() }, null, 2) + '\n')
+}
+
+// The packs that come with mdeck: { id: folder }, all or only those offered
+// (not `hidden`, by default those this user removed).
+export function bundledPacks({ root = bundledPacksRoot, all = false, hidden = all ? [] : removedPacks() } = {}) {
+  if (!existsSync(root)) return {}
+  const removed = hidden
+  return Object.fromEntries(sortedEntries(root).map(entry => entry.name).filter(id => !removed.includes(id)).map(id => [id, resolve(root, id)]))
 }
 
-// Built-in, then the user's, then the deck's own: a deck's extension replaces
-// a user one with the same id.
-export function extensionRoots(slidesPath, { builtinRoot = builtinExtensionsRoot, userRoot = userExtensionsDir() } = {}) {
+// Built-in layouts and the bundled packs, then the user's, then the deck's
+// own. For themes and palettes a later place replaces an earlier one with the
+// same id: an installed newer version replaces the bundled one, and a deck's
+// copy replaces both.
+// `userRoot: null` leaves out what this user installed and removed, for
+// results that must not depend on the computer (checks, the repository).
+export function extensionRoots(slidesPath, { builtinRoot = builtinExtensionsRoot, packsRoot = bundledPacksRoot, userRoot = userExtensionsDir() } = {}) {
   const deckDir = dirname(resolve(slidesPath))
   return [
     { dir: builtinRoot, source: 'built-in' },
+    ...Object.entries(bundledPacks({ root: packsRoot, hidden: userRoot ? removedPacks() : [] })).map(([pack, dir]) => ({ dir, source: 'built-in', pack })),
     ...(userRoot ? [{ dir: userRoot, source: 'user' }] : []),
     { dir: resolve(deckDir, 'extensions'), source: 'local' },
   ]
@@ -51,18 +80,26 @@ function readLayout(record) {
 function loadManifest({ dir, file, folderName }) {
   const raw = parseManifestText(readFileSync(file, 'utf8'), file)
   const record = validateManifest(raw, { file, dir, folderName })
-  return record.kind === 'layout' ? readLayout(record) : record
+  // An installed pack leaves a note in each folder saying which pack it is.
+  let pack = null
+  try { pack = JSON.parse(readFileSync(resolve(dir, '.mdeck-pack.json'), 'utf8')).pack ?? null } catch {}
+  const withPack = pack ? { ...record, pack } : record
+  return record.kind === 'layout' ? readLayout(withPack) : withPack
 }
 
 export function discoverExtensions(roots) {
   const registry = { layouts: {}, themes: {}, palettes: {}, records: [], warnings: [] }
   const byKey = new Map()
-  const add = (record, source) => {
+  const RANK = { 'built-in': 0, user: 1, local: 2 }
+  const add = (record, source, pack) => {
     const key = `${record.kind}:${record.id}`
     const existing = byKey.get(key)
-    const entry = { ...record, source }
-    if (existing?.source === 'user' && source === 'local') {
-      registry.warnings.push(`The ${record.kind} "${record.id}" in this deck's extensions replaces the one installed in ${dirname(existing.dir)}`)
+    const entry = { ...record, source, ...(pack ? { pack } : {}) }
+    // Themes and palettes may be replaced from a later place; layouts and two
+    // with one id in the same place may not.
+    const replaces = existing && record.kind !== 'layout' && RANK[source] > RANK[existing.source]
+    if (replaces) {
+      if (existing.source === 'user') registry.warnings.push(`The ${record.kind} "${record.id}" in this deck's extensions replaces the one installed in ${dirname(existing.dir)}`)
       registry.records.splice(registry.records.indexOf(existing), 1)
     } else if (existing) throw new ManifestError(`Duplicate ${record.kind} "${record.id}" is also defined in ${existing.file}. Extension IDs must be unique within their kind.`, { file: record.file })
     byKey.set(key, entry)
@@ -71,8 +108,10 @@ export function discoverExtensions(roots) {
   }
   for (const root of roots) {
     if (!existsSync(root.dir) || !statSync(root.dir).isDirectory()) continue
-    for (const found of walk(root.dir)) add(loadManifest(found), root.source)
+    for (const found of walk(root.dir)) { const record = loadManifest(found); add(record, root.source, root.pack ?? record.pack) }
   }
+  // Themes and palettes in name order, wherever they come from.
+  for (const kind of ['themes', 'palettes']) registry[kind] = Object.fromEntries(Object.entries(registry[kind]).sort(([a], [b]) => a.localeCompare(b, 'en')))
   checkPaletteReferences(registry)
   return registry
 }
@@ -96,9 +135,10 @@ function checkPaletteReferences(registry) {
   }
 }
 
-// The extensions that come with mdeck, alone.
+// The extensions that come with mdeck, alone: layouts and every bundled pack,
+// removed or not.
 export function builtInRegistry() {
-  return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }])
+  return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }, ...Object.entries(bundledPacks({ all: true })).map(([pack, dir]) => ({ dir, source: 'built-in', pack }))])
 }
 
 export function loadRegistry(slidesPath, options) {
@@ -118,7 +158,7 @@ export function serializeRegistry(registry, { relativeTo } = {}) {
   const out = { schema: 2, warnings: registry.warnings }
   for (const kind of KINDS) {
     out[`${kind}s`] = Object.values(registry[`${kind}s`]).map(record => ({
-      ...record.manifest, kind, source: record.source,
+      ...record.manifest, kind, source: record.source, ...(record.pack ? { pack: record.pack } : {}),
       file: relativeTo ? relative(relativeTo, record.file) : record.file,
     }))
   }

package/src/extensions/installed.js

@@ -0,0 +1,63 @@
+// Where packs are installed: for every deck (the user's folder, where the
+// bundled packs are offered too) or beside one deck. Shared by mdeck themes
+// and the design page.
+import { existsSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { bundledPacks, loadRegistry, mdeckHome, removedPacks, setRemovedPacks, userExtensionsDir } from './discover.js'
+import { installedPacks, installWithRequirements, PackError, removePack } from './packs.js'
+
+// Where a command works: for every deck (the user's folder), or beside a
+// deck when one is named or --local is given.
+export function target(where, local) {
+  if (!where && !local) return { user: true, root: userExtensionsDir(), deck: resolve('slides.md'), label: 'for every deck' }
+  const given = resolve(where ?? '.')
+  if (!existsSync(given) && !/\.md$/i.test(given)) throw new PackError(`${where} does not exist; name a slides file or the folder it is in`)
+  const folder = existsSync(given) && statSync(given).isDirectory() ? given : dirname(given)
+  return { user: false, root: resolve(folder, 'extensions'), deck: existsSync(given) && !statSync(given).isDirectory() ? given : resolve(folder, 'slides.md'), label: `in ${resolve(folder, 'extensions')}` }
+}
+
+// The packs that `where` has: installed there, and for the user's folder
+// also the bundled packs that are offered.
+export function packsAt(where) {
+  const installed = installedPacks(where.root)
+  if (!where.user) return installed
+  const offered = Object.fromEntries(Object.keys(bundledPacks()).map(id => [id, { bundled: true, requires: [] }]))
+  return { ...offered, ...installed }
+}
+
+// The packs at `where` that require `id`.
+export function requiredBy(id, where, catalogue) {
+  return Object.entries(packsAt(where)).filter(([other, pack]) => {
+    if (other === id) return false
+    const requires = pack.bundled ? catalogue.packs.find(p => p.id === other)?.requires ?? [] : pack.requires
+    return requires.includes(id)
+  }).map(([other]) => other)
+}
+
+// Installs a pack with what it requires. For every deck, a bundled pack is
+// offered again instead of copied.
+export async function installHere(catalogue, id, where, { mdeckVersion, force = false }) {
+  const removed = removedPacks()
+  const has = pack => Object.hasOwn(packsAt(where), pack)
+  const bundledHere = where.user ? entry => { setRemovedPacks(removedPacks().filter(other => other !== entry.id)); return true } : null
+  const done = await installWithRequirements(catalogue, id, { root: where.root, mdeckVersion, force, has, bundledHere })
+  return done.map(step => ({ ...step, wasRemoved: step.bundled && removed.includes(step.id) }))
+}
+
+// Removes a pack. For every deck, a bundled pack is hidden (and a newer
+// version installed over it removed too); install brings it back.
+export function removeHere(catalogue, id, where, { force = false } = {}) {
+  const needed = requiredBy(id, where, catalogue)
+  if (needed.length && !force) throw new PackError(`${needed.join(', ')} ${needed.length > 1 ? 'require' : 'requires'} ${id}; remove ${needed.length > 1 ? 'them' : 'it'} first, or add --force`)
+  const installed = installedPacks(where.root)[id]
+  const isBundled = Object.hasOwn(bundledPacks({ all: true }), id)
+  if (!installed && !(where.user && isBundled)) throw new PackError(`The pack ${id} is not installed ${where.label}`)
+  // Every deck needs a theme: the last one stays, even with --force.
+  if (where.user) {
+    const themes = Object.values(loadRegistry(resolve(mdeckHome(), 'no-deck', 'slides.md')).themes)
+    if (themes.length && themes.every(theme => theme.pack === id)) throw new PackError(`${id} has the last theme installed for every deck (${themes.map(theme => theme.id).join(', ')}); install another theme first, for example mdeck themes install neue`)
+  }
+  const pack = installed ? removePack(id, { root: where.root, force }) : null
+  if (where.user && isBundled) setRemovedPacks([...removedPacks(), id])
+  return { folders: pack?.folders ?? [], hidden: where.user && isBundled }
+}

package/src/extensions/moved.js

@@ -0,0 +1,13 @@
+// Themes and palettes that came with mdeck before 3.0 and now live in the
+// theme repository, by the pack that has them. A deck that names one is told
+// how to install it instead of being told the name is unknown.
+export const MOVED = {
+  themes: { duet: 'duet', editorial: 'editorial', fhnw: 'fhnw', terminal: 'terminal', sketch: 'sketch' },
+  palettes: { cobalt: 'duet', terra: 'editorial', brand: 'fhnw', phosphor: 'terminal', pastel: 'sketch', ember: 'earth', forest: 'earth', graphite: 'graphite' },
+}
+
+// "The theme "duet" is no longer built in: mdeck themes install duet", or null.
+export function movedHint(kind, id) {
+  const pack = MOVED[`${kind}s`]?.[id]
+  return pack ? `The ${kind} "${id}" is no longer built into mdeck; install it beside the deck with: mdeck themes install ${pack}` : null
+}

package/src/extensions/packs.js

@@ -1,8 +1,11 @@
-// Packs: themes and palettes shared through the theme repository
-// (https://gh.tschieber.de/mdeck-themes/). A pack is a folder with pack.toml
-// and one folder per theme or palette; it travels as one JSON file of text
-// files, so installing it is checking it and writing those files. Only
-// extension.toml and styles.css are allowed: a pack never carries code.
+// Packs: every theme and palette comes in one. A pack is a folder with
+// pack.toml and one folder per theme or palette; it travels as one JSON file
+// of text files, so installing it is checking it and writing those files.
+// Only extension.toml and styles.css are allowed: a pack never carries code.
+// A pack may require others (`requires = ["lagoon"]`) for palettes its
+// themes name. Packs come from two places: the starter set bundled with
+// mdeck (assets/packs), and the theme repository
+// (https://gh.tschieber.de/mdeck-themes/).
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { resolve, relative } from 'node:path'
@@ -47,6 +50,7 @@ function checkMeta(meta, where) {
   if (typeof meta.id !== 'string' || !ID_RE.test(meta.id)) fail(`${where}: id must use lowercase letters, digits and hyphens, starting with a letter`)
   if (typeof meta.version !== 'string' || !VERSION_RE.test(meta.version)) fail(`${where}: version must look like 1.0.0`)
   if (meta.mdeck != null && (typeof meta.mdeck !== 'string' || !RANGE_RE.test(meta.mdeck))) fail(`${where}: mdeck must look like ">=2.3.0"`)
+  if (meta.requires != null && (!Array.isArray(meta.requires) || meta.requires.some(id => typeof id !== 'string' || !ID_RE.test(id) || id === meta.id))) fail(`${where}: requires must be a list of other packs' ids`)
 }
 
 // pack.toml and the files of each theme or palette in a pack folder.
@@ -75,7 +79,7 @@ export function readPackDir(dir) {
 // The published form of a pack folder: one JSON text and its checksum.
 export function bundlePack(dir) {
   const { meta, files } = readPackDir(dir)
-  const bundle = { schema: 1, id: meta.id, version: meta.version, ...(meta.mdeck ? { mdeck: meta.mdeck } : {}), files }
+  const bundle = { schema: 1, id: meta.id, version: meta.version, ...(meta.mdeck ? { mdeck: meta.mdeck } : {}), ...(meta.requires?.length ? { requires: meta.requires } : {}), files }
   const text = JSON.stringify(bundle, null, 1) + '\n'
   return { meta, bundle, text, sha256: sha256(text) }
 }
@@ -87,10 +91,11 @@ function checkCss(text, where) {
   }
 }
 
-// Checks a pack before it is published or installed. `known` is the registry
-// it will join (built-in extensions at least), for palettes a theme names.
-// Returns the ids it holds, as { themes, palettes }.
-export function checkPack(bundle, { known = { themes: {}, palettes: {} } } = {}) {
+// Checks a pack before it is published or installed. `provided` holds the
+// themes and palettes of the packs it requires ({ themes, palettes } by id),
+// for those its themes name; `owners` maps ids to the packs that have them,
+// so no pack takes another's id. Returns the ids and manifests it holds.
+export function checkPack(bundle, { provided = { themes: {}, palettes: {} }, owners = {} } = {}) {
   if (!bundle || typeof bundle !== 'object' || typeof bundle.files !== 'object' || !bundle.files) fail('Not a pack')
   checkMeta(bundle, `Pack ${bundle.id ?? '?'}`)
   const byId = {}
@@ -119,18 +124,19 @@ export function checkPack(bundle, { known = { themes: {}, palettes: {} } } = {})
       for (const url of record.manifest.fonts) if (!FONT_HOSTS.some(host => url.startsWith(host))) fail(`${bundle.id}: ${id} loads fonts from ${url}; allowed are ${FONT_HOSTS.join(', ')}`)
       checkCss(files['styles.css'] ?? '', `${bundle.id}: ${id}/styles.css`)
     }
-    if (known.themes[id] || known.palettes[id]) fail(`${bundle.id}: ${id} is the id of a built-in ${known.themes[id] ? 'theme' : 'palette'}`)
+    if (owners[id] && owners[id] !== bundle.id) fail(`${bundle.id}: ${id} is already the id of a theme or palette in the pack ${owners[id]}`)
     records.push(record)
   }
-  const themes = records.filter(r => r.kind === 'theme').map(r => r.id)
-  const palettes = records.filter(r => r.kind === 'palette').map(r => r.id)
-  const hasPalette = id => palettes.includes(id) || Boolean(known.palettes[id])
-  const hasTheme = id => themes.includes(id) || Boolean(known.themes[id])
+  const mine = kind => Object.fromEntries(records.filter(r => r.kind === kind).map(r => [r.id, r.manifest]))
+  const themes = mine('theme'), palettes = mine('palette')
+  const requires = bundle.requires?.length ? ` or in ${bundle.requires.join(', ')}` : ''
   for (const record of records) {
-    if (record.kind === 'theme') for (const id of [record.manifest.palette, ...(record.manifest.palettes ?? [])]) if (!hasPalette(id)) fail(`${bundle.id}: the theme ${record.id} names the palette "${id}", which is neither in the pack nor built in`)
-    if (record.kind === 'palette' && record.manifest.theme && !hasTheme(record.manifest.theme)) fail(`${bundle.id}: the palette ${record.id} belongs to the theme "${record.manifest.theme}", which is neither in the pack nor built in`)
+    if (record.kind === 'theme') for (const id of [record.manifest.palette, ...(record.manifest.palettes ?? [])]) {
+      if (!palettes[id] && !provided.palettes[id]) fail(`${bundle.id}: the theme ${record.id} names the palette "${id}", which is not in the pack${requires}; add the pack that has it to requires`)
+    }
+    if (record.kind === 'palette' && record.manifest.theme && !themes[record.manifest.theme] && !provided.themes[record.manifest.theme]) fail(`${bundle.id}: the palette ${record.id} belongs to the theme "${record.manifest.theme}", which is not in the pack${requires}`)
   }
-  return { themes, palettes }
+  return { themes: Object.keys(themes), palettes: Object.keys(palettes), manifests: { themes, palettes } }
 }
 
 function readMarker(dir) {
@@ -152,7 +158,7 @@ export function installedPacks(root) {
   for (const entry of readdirSync(root).sort()) {
     const marker = readMarker(resolve(root, entry))
     if (!marker?.pack) continue
-    const pack = packs[marker.pack] ??= { version: marker.version, url: marker.url, folders: [] }
+    const pack = packs[marker.pack] ??= { version: marker.version, url: marker.url, requires: marker.requires ?? [], folders: [] }
     pack.folders.push(entry)
   }
   return packs
@@ -166,8 +172,8 @@ const refuseChanged = (root, folder, marker) => {
 // Writes a checked pack into an extensions folder (a deck's, or the user's).
 // A folder of another pack or of the deck itself is never touched; a folder
 // of this pack is replaced unless it was changed by hand.
-export function installPack(bundle, { root, known, url = null, digest = null, force = false } = {}) {
-  const { themes, palettes } = checkPack(bundle, { known })
+export function installPack(bundle, { root, provided, owners, url = null, digest = null, force = false } = {}) {
+  const { themes, palettes } = checkPack(bundle, { provided, owners })
   const ids = [...themes, ...palettes]
   const before = installedPacks(root)[bundle.id]
   for (const id of ids) {
@@ -193,7 +199,7 @@ export function installPack(bundle, { root, known, url = null, digest = null, fo
       hashes[name] = sha256(content)
     }
     for (const name of readdirSync(dir)) if (name !== MARKER && !Object.hasOwn(hashes, name)) rmSync(resolve(dir, name), { recursive: true, force: true })
-    writeFileSync(resolve(dir, MARKER), JSON.stringify({ pack: bundle.id, version: bundle.version, url, sha256: digest, files: hashes }, null, 2) + '\n')
+    writeFileSync(resolve(dir, MARKER), JSON.stringify({ pack: bundle.id, version: bundle.version, ...(bundle.requires?.length ? { requires: bundle.requires } : {}), url, sha256: digest, files: hashes }, null, 2) + '\n')
   }
   return { themes, palettes, replaced: before?.version ?? null }
 }
@@ -230,38 +236,121 @@ export async function fetchPack(index, entry) {
   return { bundle, url, digest: entry.sha256 }
 }
 
-// Installs a pack listed in the index: refused when this mdeck is too old.
-export async function installFromIndex(index, entry, { root, known, mdeckVersion, force = false }) {
-  if (!satisfies(entry.mdeck, mdeckVersion)) fail(`${entry.id} ${entry.version} needs mdeck ${entry.mdeck}; this is ${mdeckVersion}. Update mdeck first: npm install -g mdeck`)
-  const { bundle, url, digest } = await fetchPack(index, entry)
-  return installPack(bundle, { root, known, url, digest, force })
+// ─── The catalogue: bundled packs and the repository ──────────────────────
+
+// A bundled pack as the catalogue lists it.
+function bundledEntry(id, dir) {
+  const { meta, bundle, sha256: digest } = bundlePack(dir)
+  const { themes, palettes } = checkPack(bundle)
+  return { id, title: meta.title, description: meta.description ?? '', version: meta.version, author: meta.author, license: meta.license,
+    ...(meta.mdeck ? { mdeck: meta.mdeck } : {}), requires: meta.requires ?? [], themes, palettes, sha256: digest, bundled: true, dir }
+}
+
+// Every pack mdeck can install: the bundled ones, and the repository's when
+// it answers. Of two versions of one pack the newer is offered; the bundled
+// one on a tie, since it needs no download. `offline` says why the
+// repository is missing.
+export async function loadCatalogue({ bundled = {}, url = indexUrl(), online = true } = {}) {
+  const packs = new Map(Object.entries(bundled).map(([id, dir]) => [id, bundledEntry(id, dir)]))
+  let offline = null, index = { url, packs: [] }
+  if (online) { try { index = await fetchIndex(url) } catch (error) { offline = error.message } }
+  for (const entry of index.packs) {
+    const have = packs.get(entry.id)
+    if (!have || compareVersions(entry.version, have.version) > 0) packs.set(entry.id, { ...entry, requires: entry.requires ?? [], bundled: false, bundledVersion: have?.version })
+    else if (have.bundled) have.repository = entry
+  }
+  return { url, offline, packs: [...packs.values()].sort((a, b) => a.id.localeCompare(b.id, 'en')) }
 }
 
-export function findPack(index, id) {
-  return index.packs.find(pack => pack.id === id) ?? fail(`There is no pack "${id}" in ${index.url}; mdeck themes search lists them`)
+export function findPack(catalogue, id) {
+  return catalogue.packs.find(pack => pack.id === id) ?? fail(`There is no pack "${id}"${catalogue.offline ? ` among those that come with mdeck, and the theme repository could not be reached (${catalogue.offline})` : `; mdeck themes search lists them`}`)
 }
 
+// The ids every pack in the catalogue has, so packs do not take each other's.
+export const ownersIn = catalogue => Object.fromEntries(catalogue.packs.flatMap(pack => [...pack.themes, ...pack.palettes].map(id => [id, pack.id])))
+
+// A pack's files: read from mdeck's folder, or downloaded and checked
+// against the repository's checksum.
+export async function obtainPack(catalogue, entry) {
+  if (entry.bundled) { const { bundle, sha256: digest } = bundlePack(entry.dir); return { bundle, url: null, digest } }
+  return fetchPack({ url: catalogue.url }, entry)
+}
+
+// A pack and the packs it requires, in the order to install them; the pack
+// itself last.
+export function withRequirements(catalogue, id, seen = []) {
+  if (seen.includes(id)) fail(`The packs ${[...seen, id].join(' → ')} require each other in a circle`)
+  const entry = findPack(catalogue, id)
+  const order = []
+  for (const required of entry.requires ?? []) for (const pack of withRequirements(catalogue, required, [...seen, id])) if (!order.includes(pack)) order.push(pack)
+  return [...order, entry]
+}
+
+// Installs a pack and what it requires into an extensions folder. A required
+// pack that `has(id)` says is there already is left as it is. `bundledHere`
+// handles a bundled pack without writing it (for the user's folder, where the
+// bundled one is offered anyway); it returns true when it did.
+export async function installWithRequirements(catalogue, id, { root, mdeckVersion, force = false, has = () => false, bundledHere = null }) {
+  const owners = ownersIn(catalogue)
+  const provided = { themes: {}, palettes: {} }
+  const done = []
+  for (const entry of withRequirements(catalogue, id)) {
+    if (!satisfies(entry.mdeck, mdeckVersion)) fail(`${entry.id} ${entry.version} needs mdeck ${entry.mdeck}; this is ${mdeckVersion}. Update mdeck first: npm install -g mdeck`)
+    const { bundle, url, digest } = await obtainPack(catalogue, entry)
+    const { manifests } = checkPack(bundle, { provided, owners })
+    const target = entry.id === id
+    if (!target && has(entry.id)) done.push({ id: entry.id, version: entry.version, kept: true })
+    else if (entry.bundled && bundledHere?.(entry)) done.push({ id: entry.id, version: entry.version, bundled: true, themes: Object.keys(manifests.themes), palettes: Object.keys(manifests.palettes) })
+    else done.push({ id: entry.id, version: entry.version, ...installPack(bundle, { root, provided, owners, url, digest, force }) })
+    Object.assign(provided.themes, manifests.themes)
+    Object.assign(provided.palettes, manifests.palettes)
+  }
+  return done
+}
+
+// ─── The repository itself ────────────────────────────────────────────────
+
 // The theme repository as served: index.json and packs/<id>-<version>.json,
-// from a folder of pack folders. Each pack is checked on its own against the
-// built-in extensions, since it is installed alone, and no two packs may
-// share an id. Previews are added by the caller.
-export function buildRepository(packsDir, outDir, { known }) {
-  const entries = []
-  const owner = {}
-  const dirs = readdirSync(packsDir).filter(name => !name.startsWith('.') && statSync(resolve(packsDir, name)).isDirectory()).sort()
-  mkdirSync(resolve(outDir, 'packs'), { recursive: true })
-  for (const name of dirs) {
-    const { meta, bundle, text, sha256: digest } = bundlePack(resolve(packsDir, name))
-    const { themes, palettes } = checkPack(bundle, { known })
-    for (const id of [...themes, ...palettes]) {
-      if (owner[id]) fail(`${id} is in both ${owner[id]} and ${meta.id}`)
-      owner[id] = meta.id
+// from a folder of pack folders and mdeck's bundled packs (marked bundled).
+// Each pack is checked with only the packs it requires, as it is installed;
+// no two packs may share an id. Previews are added by the caller.
+export function buildRepository(packsDir, outDir, { bundled = {} } = {}) {
+  const dirs = { ...Object.fromEntries(readdirSync(packsDir).filter(name => !name.startsWith('.') && statSync(resolve(packsDir, name)).isDirectory()).map(name => [name, resolve(packsDir, name)])) }
+  for (const [id, dir] of Object.entries(bundled)) {
+    if (dirs[id]) fail(`${id} comes with mdeck; change it there instead of in ${packsDir}`)
+    dirs[id] = dir
+  }
+  const read = Object.fromEntries(Object.entries(dirs).map(([id, dir]) => [id, bundlePack(dir)]))
+  const owners = {}
+  for (const [id, { bundle }] of Object.entries(read)) {
+    for (const ext of Object.keys(bundle.files).map(path => path.split('/')[0])) {
+      if (owners[ext] && owners[ext] !== id) fail(`${ext} is in both ${owners[ext]} and ${id}`)
+      owners[ext] = id
     }
+  }
+  const checked = {}
+  const check = (id, seen = []) => {
+    if (checked[id]) return checked[id]
+    if (!read[id]) fail(`${seen.at(-1)} requires ${id}, which is not in the repository`)
+    if (seen.includes(id)) fail(`The packs ${[...seen, id].join(' → ')} require each other in a circle`)
+    const provided = { themes: {}, palettes: {} }
+    for (const required of read[id].bundle.requires ?? []) {
+      const result = check(required, [...seen, id])
+      Object.assign(provided.themes, result.provides.themes); Object.assign(provided.palettes, result.provides.palettes)
+    }
+    const result = checkPack(read[id].bundle, { provided, owners })
+    return checked[id] = { ...result, provides: { themes: { ...provided.themes, ...result.manifests.themes }, palettes: { ...provided.palettes, ...result.manifests.palettes } } }
+  }
+  mkdirSync(resolve(outDir, 'packs'), { recursive: true })
+  const entries = Object.keys(read).sort((a, b) => a.localeCompare(b, 'en')).map(id => {
+    const { meta, text, sha256: digest } = read[id]
+    const { themes, palettes } = check(id)
     const file = `packs/${meta.id}-${meta.version}.json`
     writeFileSync(resolve(outDir, file), text)
-    entries.push({ id: meta.id, title: meta.title, description: meta.description ?? '', version: meta.version, author: meta.author, license: meta.license,
-      ...(meta.homepage ? { homepage: meta.homepage } : {}), ...(meta.mdeck ? { mdeck: meta.mdeck } : {}), themes, palettes, url: file, sha256: digest })
-  }
+    return { id: meta.id, title: meta.title, description: meta.description ?? '', version: meta.version, author: meta.author, license: meta.license,
+      ...(meta.homepage ? { homepage: meta.homepage } : {}), ...(meta.mdeck ? { mdeck: meta.mdeck } : {}), ...(meta.requires?.length ? { requires: meta.requires } : {}),
+      ...(bundled[id] ? { bundled: true } : {}), themes, palettes, url: file, sha256: digest }
+  })
   const index = { schema: 1, packs: entries }
   writeFileSync(resolve(outDir, 'index.json'), JSON.stringify(index, null, 2) + '\n')
   return index

package/src/home/Home.jsx

@@ -66,24 +66,29 @@ async function openService(action, page = '') {
   const tab = window.open('about:blank', '_blank')
   try {
     const { url } = await api('/action', { action })
-    const target = new URL(page, url).href
-    if (tab) tab.location = target
-    else window.open(target, '_blank')
+    const target = new URL(page, url)
+    // The editors link back here.
+    if (action === 'editor') target.searchParams.set('home', location.href.split('#')[0])
+    if (tab) tab.location = target.href
+    else window.open(target.href, '_blank')
   } catch (error) {
     tab?.close()
     throw error
   }
 }
 
-function ServiceTile({ icon, title, text, action, url, onError, onStarted }) {
+// `page` opens another page of the same service, such as the editor's
+// design page.
+function ServiceTile({ icon, title, text, action, page = '', url, onError, onStarted }) {
   const [starting, setStarting] = useState(false)
   const launch = async () => {
     setStarting(true)
-    try { await openService(action); onStarted() } catch (error) { onError(error.message) } finally { setStarting(false) }
+    try { await openService(action, page); onStarted() } catch (error) { onError(error.message) } finally { setStarting(false) }
   }
+  const shown = url && new URL(page, url).href
   return <button class="home-tile" onClick={launch} disabled={starting}>
     <span class="home-tile-icon"><HomeIcon name={icon} size={22} /></span>
-    <span class="home-tile-body"><strong>{title}</strong><span>{starting ? 'Starting…' : url ? url.replace(/^https?:\/\//, '') : text}</span></span>
+    <span class="home-tile-body"><strong>{title}</strong><span>{starting ? 'Starting…' : shown ? shown.replace(/^https?:\/\//, '') : text}</span></span>
     <HomeIcon name="external" size={16} />
   </button>
 }
@@ -335,6 +340,7 @@ export function Home() {
         <h2>Write and learn</h2>
         <div class="home-tiles">
           <ServiceTile icon="editor" title="Visual editor" text="Forms and a live preview; saves into the file and keeps a backup." action="editor" url={info.services.editor} onError={setError} onStarted={load} />
+          <ServiceTile icon="look" title="Theme editor" text="Try and fine-tune themes and palettes on a sample deck; install more." action="editor" page="design.html" url={info.services.editor} onError={setError} onStarted={load} />
           <ServiceTile icon="guides" title="Guides" text="How to write slides, layouts, presenting, sharing and more." action="docs" url={info.services.docs} onError={setError} onStarted={load} />
         </div>
       </section>

package/src/layouts/layoutApi.jsx

@@ -62,8 +62,16 @@ export function extractContent(markdown, { headingLevels = [], paragraph = false
 
 // An SVG picture that uses the theme's colour variables is drawn inline, so it
 // follows the theme, palette and light or dark. The build lists them by the
-// path the deck uses.
-export const themedSvg = src => themedSvgs[src] ?? themedSvgs[String(src ?? '').split(/[?#]/)[0]]
+// path the deck uses; an SVG data URL carries its drawing itself.
+export const themedSvg = src => themedSvgs[src] ?? themedSvgs[String(src ?? '').split(/[?#]/)[0]] ?? themedDataSvg(src)
+
+function themedDataSvg(src) {
+  const match = /^data:image\/svg\+xml(;base64)?,(.*)$/s.exec(String(src ?? ''))
+  if (!match) return null
+  let markup
+  try { markup = match[1] ? atob(match[2]) : decodeURIComponent(match[2]) } catch { return null }
+  return /var\(--/.test(markup) && /^\s*<svg\b/.test(markup) ? markup : null
+}
 
 const attribute = (tag, name) => tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, 'i'))?.slice(1).find(v => v != null)
 

package/src/paths.js

@@ -7,3 +7,5 @@ export const runtimeRoot = resolve(frameworkRoot, 'src/runtime')
 export const assetsRoot = resolve(frameworkRoot, 'assets')
 export const docsRoot = resolve(frameworkRoot, 'docs/site')
 export const builtinExtensionsRoot = resolve(assetsRoot, 'extensions')
+// The packs of themes and palettes that come with mdeck (the starter set).
+export const bundledPacksRoot = resolve(assetsRoot, 'packs')

package/src/runtime/themeLoader.js

@@ -1,6 +1,7 @@
 import baseCSS from '../../assets/base.css?inline'
 import { themes, palettes } from 'virtual:mdeck-extensions'
 import { buildAppearance } from '../extensions/appearance.js'
+import { movedHint } from '../extensions/moved.js'
 
 const SELF_CONTAINED = typeof __MDECK_SELF_CONTAINED__ !== 'undefined'
   && __MDECK_SELF_CONTAINED__
@@ -48,8 +49,10 @@ function syncThemeFonts(urls) {
 }
 
 export async function loadTheme({ theme = 'neue', palette, appearance, params = {}, meta = {} } = {}) {
-  const entry = themeEntry(theme)
-  if (!entry) throw new Error(`Unknown theme: "${theme}". Available: ${THEME_NAMES.join(', ')}`)
+  // A deck without a theme gets neue, or the first installed theme when neue
+  // was removed.
+  const entry = themeEntry(theme) ?? (theme === 'neue' && THEME_NAMES.length ? themeEntry(THEME_NAMES[0]) : null)
+  if (!entry) throw new Error(movedHint('theme', theme) ?? `Unknown theme: "${theme}". Available: ${THEME_NAMES.join(', ') || 'none; install one with mdeck themes install'}`)
 
   const styles = await entry.load()
   const look = buildAppearance({

package/assets/extensions/palettes/brand/extension.toml

@@ -1,29 +0,0 @@
-schema = 1
-kind = "palette"
-id = "brand"
-title = "FHNW"
-description = "The FHNW corporate colours: black, white and FHNW yellow."
-# Only for the fhnw theme: its corporate colours.
-theme = "fhnw"
-
-[light]
-"--bg" = "#ffffff"
-"--surface" = "#f1f1ee"
-"--ink" = "#000000"
-"--ink-soft" = "#262626"
-"--muted" = "#6e6e6e"
-"--rule" = "#deded9"
-"--accent" = "#fde70e"
-"--accent-2" = "#000000"
-"--on-accent" = "#000000"
-
-[dark]
-"--bg" = "#000000"
-"--surface" = "#1c1c1c"
-"--ink" = "#ffffff"
-"--ink-soft" = "#dcdcdc"
-"--muted" = "#9a9a9a"
-"--rule" = "#333333"
-"--accent" = "#fde70e"
-"--accent-2" = "#ffffff"
-"--on-accent" = "#000000"