mdeck 2.3.0 → 3.1.0

package/src/editor/components/DesignApp.jsx

@@ -1,10 +1,10 @@
 import { h } from 'preact'
 import { useEffect, useRef, useState } from 'preact/hooks'
 import { useDeckDocument } from '../useDeckDocument.js'
-import { loadExtension, saveExtension, deleteExtension, installThemePack } from '../api.js'
+import { loadExtension, saveExtension, deleteExtension, installPackage, removePackage } from '../api.js'
 import { starterFiles, parseManifest, toModel, toRuntimeManifest, MANIFEST } from '../extensions.js'
 import { sampleDeck, sampleDataUrl } from '../sampleDeck.js'
-import { parseTarget } from '../designLink.js'
+import { parseTarget, launchPageUrl } from '../designLink.js'
 import { palettesFor } from '../../extensions/tokens.js'
 import { parseSlides } from '../../core/parseSlides.js'
 import { setDeckConfig } from '../../core/editDeck.js'
@@ -36,6 +36,7 @@ export function DesignApp() {
   const [slide, setSlide] = useState(0)
   const [inspectorWidth, setInspectorWidth] = useState(readInspectorWidth)
   const resize = width => { setInspectorWidth(width); storeInspectorWidth(width) }
+  const [home] = useState(launchPageUrl)
   const timer = useRef(null)
   const currentRef = useRef(current)
   currentRef.current = current
@@ -117,13 +118,18 @@ export function DesignApp() {
     } catch (caught) { setError(caught.message) }
   }
 
-  // A pack from the theme repository, installed beside the deck; its first
-  // theme or palette of the kind shown is opened.
-  const installOnline = async (pack, kind) => {
-    const result = await installThemePack(pack.id)
+  // A theme or palette installed for every deck, then opened.
+  const installOnline = async (kind, id) => {
+    const result = await installPackage(kind, id)
     dispatch({ type: 'setRegistry', registry: result.registry })
-    const id = pack[`${kind}s`][0]
-    if (id) await select(kind, id)
+    await select(kind, id)
+  }
+
+  // Removes a theme or palette for every deck; the deck's look is not changed.
+  const removeOnline = async (kind, id) => {
+    const result = await removePackage(kind, id)
+    dispatch({ type: 'setRegistry', registry: result.registry })
+    setCurrent(null)
   }
 
   const remove = async () => {
@@ -232,6 +238,7 @@ export function DesignApp() {
       {state.designOnly
         ? <span class="muted" title={`${state.path}/extensions`}>Saved in {state.name}/extensions</span>
         : <a class="btn is-small" href="/editor.html">Back to the slides</a>}
+      {home && <a class="btn is-small" href={home}>Launch page</a>}
     </header>
     {state.status === 'conflict' && <ConflictBanner onReload={() => resolve('reload')} onOverwrite={() => resolve('overwrite')} />}
     <div class="editor-main" style={{ gridTemplateColumns: `290px minmax(0, 1fr) ${inspectorWidth}px` }}>
@@ -244,7 +251,7 @@ export function DesignApp() {
           ? <div class="form"><p class="empty">Choose one of {state.designOnly ? "this folder's" : "this deck's"} themes and palettes on the left to change it, or start from a built-in one. What you change is saved as you type, in the <code>extensions</code> folder {state.designOnly ? 'of this folder, where decks in it find them' : "beside the deck. The deck's look is chosen in the editor's Deck settings"}.{error ? ` ${error}` : ''}</p></div>
           : current.source === 'local'
             ? <>{usage}<ExtensionEditor extension={current} palettes={manifests.palettes} status={status} error={error} note={note} onFiles={onFiles} onDelete={remove} onCopy={() => copyDialog(current.kind, current.id)} /></>
-            : <BuiltInCard extension={current} manifest={manifests[`${current.kind}s`][current.id]} onCopy={() => copyDialog(current.kind, current.id)} />}
+            : <BuiltInCard extension={current} manifest={manifests[`${current.kind}s`][current.id]} onCopy={() => copyDialog(current.kind, current.id)} onRemove={removeOnline} />}
       </aside>
     </div>
     {dialog && <NewExtensionDialog kind={dialog.kind} initial={dialog.initial ?? null} registry={state.registry} existing={existing} onCreate={create} onClose={() => setDialog(null)} />}

package/src/editor/components/ExtensionEditor.jsx

@@ -45,19 +45,29 @@ export function ExtensionEditor({ extension, palettes = {}, status, error, note,
   </>
 }
 
-// A built-in or installed extension: what it is, and the one way to change
-// it, a copy in the deck's extensions folder.
-export function BuiltInCard({ extension, manifest, onCopy }) {
+// A built-in or installed theme or palette: what it is, the one way to
+// change it (a copy in the deck's extensions folder), and removing it.
+export function BuiltInCard({ extension, manifest, onCopy, onRemove }) {
   const { kind, id, files } = extension
   const user = extension.source === 'user'
+  const [removing, setRemoving] = useState(null)
   return <div class="form">
-    <p class="section-title">{user ? `Installed ${kind}, for every deck` : `Built-in ${kind}`}</p>
+    <p class="section-title">{user ? `Installed for every deck` : `Comes with mdeck`}{manifest?.version ? ` · ${manifest.version}` : ''}</p>
     <h2 class="builtin-title">{manifest?.title ?? id} <span class="muted">{id}</span></h2>
     {manifest?.description && <p class="builtin-description">{manifest.description}</p>}
     {kind === 'palette' && manifest && ['light', 'dark'].map(mode => <Field key={mode} label={mode === 'light' ? 'Light' : 'Dark'}><Swatches tokens={manifest[mode] ?? {}} /></Field>)}
     {kind === 'theme' && manifest?.palette && <p class="builtin-description">Its default palette is <code>{manifest.palette}</code>{manifest.palettes?.length ? `; it offers only ${manifest.palettes.join(', ')}` : ''}.</p>}
-    <p class="note">{user ? `Installed ${kind}s are changed only by updating them (mdeck themes update --global).` : `Built-in ${kind}s cannot be changed.`} Copy this one into the deck's <code>extensions</code> folder and change the copy. The preview shows every change as you make it.</p>
-    <div class="row" style={{ display: 'flex', gap: '8px' }}><button class="btn is-primary" onClick={onCopy}>Copy to customise</button></div>
+    <p class="note">{user ? `Installed ${kind}s change only when they are updated (mdeck ${kind}s update).` : `This ${kind} cannot be changed where it is.`} Copy this one into the deck's <code>extensions</code> folder and change the copy. The preview shows every change as you make it.</p>
+    <div class="row" style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+      <button class="btn is-primary" onClick={onCopy}>Copy to customise</button>
+      {onRemove && (removing === 'confirm'
+        ? <><span class="muted" style={{ alignSelf: 'center' }}>Remove the {kind} {id} for every deck?</span>
+          <button class="btn" onClick={async () => { setRemoving('busy'); try { await onRemove(kind, id); setRemoving(null) } catch (error) { setRemoving({ error: error.message }) } }}>Remove</button>
+          <button class="btn" onClick={() => setRemoving(null)}>Keep</button></>
+        : <button class="btn" disabled={removing === 'busy'} onClick={() => setRemoving('confirm')}>Remove {kind}</button>)}
+    </div>
+    {removing?.error && <p class="online-error">{removing.error}</p>}
+    {!user && <p class="hint-text">Removing a {kind} that comes with mdeck hides it; install it again from “More to install”.</p>}
     <details class="builtin-source">
       <summary>{MANIFEST}</summary>
       <pre>{files?.[MANIFEST] ?? ''}</pre>

package/src/editor/components/ExtensionsPanel.jsx

@@ -3,13 +3,13 @@ import { useEffect, useState } from 'preact/hooks'
 import { ID_RE } from '../extensions.js'
 import { Icon } from '../../components/Icon.jsx'
 import { LookThumbnail } from './LookThumbnail.jsx'
-import { loadThemeIndex } from '../api.js'
+import { loadCatalogue } from '../api.js'
 
 const KINDS = [['theme', 'Themes'], ['palette', 'Palettes']]
 
 // The deck's own themes or palettes, to change; those installed for every
-// deck; packs from the theme repository; and the built-in ones to start
-// from. A new theme always starts as a copy; a palette can also start from
+// deck; the built-in ones; and those to install from the theme repository.
+// A new theme always starts as a copy; a palette can also start from
 // readable plain colours. The pictures show the sample deck as `view` says:
 // palettes in the preview's theme where it offers them, themes with its
 // palette where they offer it, both in its light or dark.
@@ -37,56 +37,50 @@ export function ExtensionsPanel({ registry, view = {}, owner = "This deck's", se
     </div>
     {own.length
       ? <ol class="outline-list">{own.map(row)}</ol>
-      : <p class="panel-hint">None yet. Start from a built-in one below{kind === 'palette' ? ', or with + from plain colours' : ''}.</p>}
+      : <p class="panel-hint">None yet. Copy one below to start{kind === 'palette' ? ', or with + from plain colours' : ''}.</p>}
     {installed.length > 0 && <>
       <div class="panel-section-head"><p class="section-title">Installed for every deck</p></div>
       <ol class="outline-list">{installed.map(row)}</ol>
     </>}
-    <OnlinePacks key="online" kind={kind} owner={owner} onInstall={onInstall} />
-    <div class="panel-section-head"><p class="section-title">Built in, to start from</p></div>
+    <div class="panel-section-head"><p class="section-title">Come with mdeck</p></div>
     <ol class="outline-list">{builtIn.map(row)}</ol>
+    <OnlinePackages key="online" kind={kind} onInstall={onInstall} />
   </aside>
 }
 
-// Packs from the theme repository with this kind of extension, loaded on
-// request since it needs the network. Installing puts a pack beside the deck.
-function OnlinePacks({ kind, owner, onInstall }) {
+// Themes or palettes not available yet: from the theme repository, and
+// built-in ones that were removed. Loaded on request, since it needs the
+// network. Installing makes one available to every deck; a theme brings its
+// default palette along.
+function OnlinePackages({ kind, onInstall }) {
   const [state, setState] = useState({ status: 'idle' })
   const [busy, setBusy] = useState(null)
   const load = () => {
-    setState({ status: 'loading' })
-    loadThemeIndex().then(index => setState({ status: 'ready', index }), error => setState({ status: 'error', error: error.message }))
+    setState(prev => ({ ...prev, status: prev.catalogue ? 'ready' : 'loading' }))
+    loadCatalogue().then(catalogue => setState({ status: 'ready', catalogue }), error => setState({ status: 'error', error: error.message }))
   }
-  const install = async pack => {
-    setBusy(pack.id)
-    try {
-      await onInstall(pack, kind)
-      setState(prev => ({ ...prev, index: { ...prev.index, installed: { ...prev.index.installed, [pack.id]: { version: pack.version } } } }))
-    } catch (error) { setState(prev => ({ ...prev, error: error.message })) }
+  const install = async entry => {
+    setBusy(entry.id)
+    try { await onInstall(entry.kind, entry.id); load() } catch (error) { setState(prev => ({ ...prev, error: error.message })) }
     setBusy(null)
   }
-  const head = <div class="panel-section-head"><p class="section-title">From the theme repository</p></div>
+  const head = <div class="panel-section-head"><p class="section-title">More to install</p></div>
   if (state.status !== 'ready') return <>{head}<div class="panel-hint">
-    {state.status === 'loading' ? 'Loading…' : <button class="btn is-small" onClick={load}>Show what others made</button>}
+    {state.status === 'loading' ? 'Loading…' : <button class="btn is-small" onClick={load}>Show what you can install</button>}
     {state.error && <p class="online-error">{state.error}</p>}
   </div></>
-  const { index } = state
-  const packs = index.packs.filter(pack => pack[`${kind}s`].length)
+  const { catalogue } = state
+  const entries = catalogue.entries.filter(entry => entry.kind === kind && !entry.available)
   return <>{head}
     {state.error && <p class="panel-hint online-error">{state.error}</p>}
-    {!packs.length && <p class="panel-hint">No {kind}s there yet.</p>}
-    <ol class="outline-list">{packs.map(pack => {
-      const id = pack[`${kind}s`][0]
-      const have = index.installed?.[pack.id]
-      return <li key={pack.id} class="outline-item has-thumb online-pack">
-        {pack.previews?.[id] && <div class="thumb"><img src={new URL(pack.previews[id], index.url).href} alt="" loading="lazy" /></div>}
-        <span><span class="title" style={{ display: 'block' }}>{pack.title} <span class="muted">{pack.version}</span></span>
-          <span class="online-meta">{[...pack.themes, ...pack.palettes].join(', ')} · {pack.author}</span></span>
-        {have
-          ? <span class="muted">{`Installed${have.version !== pack.version ? ` (${have.version})` : ''} in ${owner === "This folder's" ? 'this folder' : 'this deck'}`}</span>
-          : <button class="btn is-small" disabled={busy === pack.id} onClick={() => install(pack)}>{busy === pack.id ? 'Installing…' : 'Install'}</button>}
-      </li>
-    })}</ol>
+    {catalogue.offline && <p class="panel-hint">The theme repository could not be reached; showing what comes with mdeck.</p>}
+    {!entries.length && <p class="panel-hint">Every {kind} there is, is installed.</p>}
+    <ol class="outline-list">{entries.map(entry => <li key={entry.id} class="outline-item has-thumb online-pack">
+      {entry.preview && <div class="thumb"><img src={entry.preview} alt="" loading="lazy" /></div>}
+      <span><span class="title" style={{ display: 'block' }}>{entry.title} <span class="muted">{entry.version}</span></span>
+        <span class="online-meta">{entry.removed ? 'comes with mdeck, removed' : entry.author}{kind === 'theme' ? ` · with ${entry.palette}` : entry.theme ? ` · for ${entry.theme}` : ''}</span></span>
+      <button class="btn is-small" disabled={busy === entry.id} onClick={() => install(entry)}>{busy === entry.id ? 'Installing…' : 'Install'}</button>
+    </li>)}</ol>
   </>
 }
 

package/src/editor/designLink.js

@@ -4,11 +4,15 @@ export const DESIGN_URL = '/design.html'
 export const DESIGN_TAB = 'mdeck-design'
 
 // `copy` starts a copy of a built-in extension to change; `open` opens one of
-// the deck's own. Both are `kind:id`.
+// the deck's own. Both are `kind:id`. The launch page's address, if this
+// editor came from it, is passed on.
 export function designUrl({ copy = null, open = null } = {}) {
   const query = new URLSearchParams()
   if (copy) query.set('copy', copy)
   if (open) query.set('open', open)
+  // A new tab does not share this one's memory: the way back goes along.
+  const home = typeof location === 'undefined' ? null : launchPageUrl()
+  if (home) query.set('home', home)
   return query.size ? `${DESIGN_URL}?${query}` : DESIGN_URL
 }
 
@@ -17,3 +21,16 @@ export function parseTarget(value) {
   const match = /^(theme|palette|layout):([a-z][a-z0-9-]*)$/.exec(value ?? '')
   return match ? { kind: match[1], id: match[2] } : null
 }
+
+// The launch page of `mdeck run` that opened this editor, if one did: it
+// passes its address as ?home=…, kept for this tab so that switching
+// between the editor and the design page keeps the way back.
+const HOME_KEY = 'mdeck-launch-page'
+export function launchPageUrl() {
+  let home = new URLSearchParams(location.search).get('home')
+  try {
+    if (home) sessionStorage.setItem(HOME_KEY, home)
+    else home = sessionStorage.getItem(HOME_KEY)
+  } catch {}
+  try { return home && /^https?:$/.test(new URL(home).protocol) ? home : null } catch { return null }
+}

package/src/editor/sampleDeck.js

@@ -2,7 +2,9 @@
 // ordinary amounts. The design page previews themes and palettes on it, and
 // `npm run test:themes` checks every theme against it.
 
-export const SAMPLE_PICTURE = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><rect width="400" height="300" fill="#6b7f99"/><circle cx="140" cy="150" r="80" fill="#e0c068"/><rect x="220" y="80" width="120" height="140" fill="#2d3e50"/></svg>'
+// A drawing in the palette's colours (with plain colours elsewhere): a chart
+// over hills under a sun, for every layout that shows a picture.
+export const SAMPLE_PICTURE = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 500"><rect width="800" height="500" fill="var(--surface, #eef1f4)"/><g stroke="var(--rule, #d5dbe1)" stroke-width="2"><path d="M0 100H800M0 200H800M0 300H800M0 400H800M100 0V500M200 0V500M300 0V500M400 0V500M500 0V500M600 0V500M700 0V500"/></g><circle cx="580" cy="165" r="128" fill="none" stroke="var(--accent, #3d5a73)" stroke-width="4" opacity="0.35"/><circle cx="580" cy="165" r="88" fill="var(--accent, #3d5a73)"/><path d="M0 360C140 292 262 300 384 338S628 424 800 330V500H0Z" fill="var(--accent-2, #c2410c)"/><path d="M0 418C168 366 330 392 470 422S690 474 800 434V500H0Z" fill="var(--accent, #3d5a73)" opacity="0.6"/><polyline points="80,262 170,214 260,236 350,170 440,196" fill="none" stroke="var(--ink, #1b2733)" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/><g fill="var(--bg, #ffffff)" stroke="var(--ink, #1b2733)" stroke-width="5"><circle cx="80" cy="262" r="10"/><circle cx="170" cy="214" r="10"/><circle cx="260" cy="236" r="10"/><circle cx="350" cy="170" r="10"/><circle cx="440" cy="196" r="10"/></g></svg>'
 
 // `picture` is where the slides find the picture: a file beside the deck, or
 // a data URL where there is no such file.

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,7 +1,7 @@
 // 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'
@@ -9,18 +9,42 @@ import { builtinExtensionsRoot } 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 built-in themes and palettes this user removed (`mdeck themes remove
+// aurora`): they stay in mdeck's folder but are not offered. Kept as
+// "theme:aurora" and "palette:neon".
+const removedFile = () => resolve(mdeckHome(), 'removed.json')
+export function removedBuiltIns() {
+  let saved = {}
+  try { saved = JSON.parse(readFileSync(removedFile(), 'utf8')) } catch {}
+  return (Array.isArray(saved.hidden) ? saved.hidden : []).filter(key => /^(theme|palette):[a-z][a-z0-9-]*$/.test(key))
+}
+export function setRemovedBuiltIns(keys) {
+  mkdirSync(mdeckHome(), { recursive: true })
+  writeFileSync(removedFile(), JSON.stringify({ hidden: [...new Set(keys)].sort() }, null, 2) + '\n')
 }
 
-// Built-in, then the user's, then the deck's own: a deck's extension replaces
-// a user one with the same id.
+// mdeck's own layouts, themes and palettes, 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 built-in one, and a
+// deck's copy replaces both. Built-in themes and palettes this user removed
+// are left out. `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, userRoot = userExtensionsDir() } = {}) {
   const deckDir = dirname(resolve(slidesPath))
   return [
-    { dir: builtinRoot, source: 'built-in' },
+    { dir: builtinRoot, source: 'built-in', hidden: userRoot ? removedBuiltIns() : [] },
     ...(userRoot ? [{ dir: userRoot, source: 'user' }] : []),
     { dir: resolve(deckDir, 'extensions'), source: 'local' },
   ]
@@ -57,12 +81,16 @@ function loadManifest({ dir, file, folderName }) {
 export function discoverExtensions(roots) {
   const registry = { layouts: {}, themes: {}, palettes: {}, records: [], warnings: [] }
   const byKey = new Map()
+  const RANK = { 'built-in': 0, user: 1, local: 2 }
   const add = (record, source) => {
     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)}`)
+    // 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 +99,13 @@ 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)
+      if (!root.hidden?.includes(`${record.kind}:${record.id}`)) add(record, root.source)
+    }
   }
+  // 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,7 +129,7 @@ function checkPaletteReferences(registry) {
   }
 }
 
-// The extensions that come with mdeck, alone.
+// The extensions that come with mdeck, alone, removed or not.
 export function builtInRegistry() {
   return discoverExtensions([{ dir: builtinExtensionsRoot, source: 'built-in' }])
 }
@@ -118,7 +151,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.package?.version ? { version: record.package.version } : {}),
       file: relativeTo ? relative(relativeTo, record.file) : record.file,
     }))
   }

package/src/extensions/installed.js

@@ -0,0 +1,88 @@
+// Where themes and palettes are installed: for every deck (the user's
+// folder, where the built-in ones are offered too) or beside one deck.
+// Shared by mdeck themes / mdeck palettes and the design page.
+import { existsSync, rmSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { loadRegistry, mdeckHome, removedBuiltIns, setRemovedBuiltIns, userExtensionsDir } from './discover.js'
+import { installedPackages, installPackage, keyOf, obtainPackage, PackageError, removePackage, satisfies, withDependencies } from './packages.js'
+
+const fail = message => { throw new PackageError(message) }
+
+// 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(mdeckHome(), 'no-deck', 'slides.md'), label: 'for every deck' }
+  const given = resolve(where ?? '.')
+  if (!existsSync(given) && !/\.md$/i.test(given)) fail(`${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 themes and palettes `where` sees, as a registry: for every deck what
+// this user has, beside a deck also what that deck has.
+const registryAt = where => loadRegistry(where.deck)
+
+// Installs a theme or palette with what it needs. What `where` has already
+// stays as it is. A built-in one is not copied: for every deck it is offered
+// again if it was removed. A theme and its own palette may need each other,
+// so the registry is checked before anything is written and once all is
+// there; if anything fails, what this call installed is taken out again.
+export async function installHere(catalogue, kind, id, where, { mdeckVersion, force = false }) {
+  const before = registryAt(where)
+  const plan = withDependencies(catalogue, kind, id)
+  const done = [], written = []
+  try {
+    for (const entry of plan) {
+      const key = keyOf(entry.kind, entry.id)
+      const requested = entry.kind === kind && entry.id === id
+      if (entry.builtIn) {
+        const hidden = removedBuiltIns()
+        const wasRemoved = hidden.includes(key)
+        if (wasRemoved) setRemovedBuiltIns(hidden.filter(other => other !== key))
+        done.push({ kind: entry.kind, id: entry.id, version: entry.version, builtIn: true, wasRemoved, requested })
+        continue
+      }
+      const have = installedPackages(where.root)[key]
+      // Beside a deck, what is installed only for every deck is copied too,
+      // so the slide folder carries it.
+      const there = before[`${entry.kind}s`][entry.id]
+      if (!requested && (have || (there && (where.user || there.source !== 'user')))) { done.push({ kind: entry.kind, id: entry.id, version: have?.version ?? null, kept: true, requested }); continue }
+      if (!satisfies(entry.mdeck, mdeckVersion)) fail(`The ${entry.kind} ${entry.id} ${entry.version} needs mdeck ${entry.mdeck}; this is ${mdeckVersion}. Update mdeck first: npm install -g mdeck`)
+      const { bundle, url, digest } = await obtainPackage(catalogue, entry)
+      const result = installPackage(bundle, { root: where.root, url, digest, force })
+      if (!result.replaced) written.push(result.dir)
+      done.push({ kind: entry.kind, id: entry.id, version: entry.version, replaced: result.replaced, requested })
+    }
+    registryAt(where)
+  } catch (error) {
+    for (const dir of written) rmSync(dir, { recursive: true, force: true })
+    throw error
+  }
+  return done
+}
+
+// Removes a theme or palette. A built-in one is hidden instead, for every
+// deck; installing it brings it back. A palette a theme here uses by default
+// stays; a theme takes the palettes that belong only to it along; the last
+// theme stays.
+export function removeHere(kind, id, where, { force = false } = {}) {
+  const registry = registryAt(where)
+  const record = registry[`${kind}s`][id]
+  const installed = installedPackages(where.root)
+  const key = keyOf(kind, id)
+  if (!installed[key] && !(where.user && record?.source === 'built-in')) fail(`The ${kind} ${id} is not installed ${where.label}`)
+  if (kind === 'palette') {
+    const users = Object.values(registry.themes).filter(theme => theme.manifest.palette === id).map(theme => theme.id)
+    if (users.length) fail(`${users.join(', ')} ${users.length > 1 ? 'use' : 'uses'} the palette ${id} by default; remove ${users.length > 1 ? 'those themes' : 'that theme'} first`)
+  }
+  if (kind === 'theme' && Object.keys(registry.themes).length === 1) fail(`${id} is the last theme ${where.label}; install another theme first (mdeck themes search lists them)`)
+  const removed = []
+  const take = (k, i) => {
+    const r = registry[`${k}s`][i]
+    if (installedPackages(where.root)[keyOf(k, i)]) { removePackage(k, i, { root: where.root, force }); removed.push({ kind: k, id: i }) }
+    else if (where.user && r?.source === 'built-in') { setRemovedBuiltIns([...removedBuiltIns(), keyOf(k, i)]); removed.push({ kind: k, id: i, hidden: true }) }
+  }
+  take(kind, id)
+  if (kind === 'theme') for (const palette of Object.values(registry.palettes)) if (palette.manifest.theme === id) take('palette', palette.id)
+  return removed
+}

package/src/extensions/manifest.js

@@ -15,11 +15,16 @@ export const MANIFEST_FILENAME = 'extension.toml'
 const FRAMES = ['standard', 'title', 'chapter', 'none']
 const PROPERTY_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object']
 const SHARED_KEYS = ['schema', 'kind', 'id', 'title', 'description']
+// A theme or palette is also a package that can be installed: its version,
+// who made it, its licence, a web page and the oldest mdeck it works with.
+const PACKAGE_KEYS = ['version', 'author', 'license', 'homepage', 'mdeck']
 const KEYS = {
   layout: [...SHARED_KEYS, 'frame', 'files', 'regions', 'properties'],
-  theme: [...SHARED_KEYS, 'palette', 'palettes', 'appearance', 'fonts', 'files', 'tokens', 'params'],
-  palette: [...SHARED_KEYS, 'theme', 'light', 'dark'],
+  theme: [...SHARED_KEYS, ...PACKAGE_KEYS, 'palette', 'palettes', 'appearance', 'fonts', 'files', 'tokens', 'params'],
+  palette: [...SHARED_KEYS, ...PACKAGE_KEYS, 'theme', 'light', 'dark'],
 }
+export const VERSION_RE = /^\d+\.\d+\.\d+$/
+export const RANGE_RE = /^>=\s*(\d+\.\d+\.\d+)$/
 const SCHEMA_KEYS = ['type', 'title', 'description', 'enum', 'required', 'default', 'minimum', 'maximum', 'minItems', 'maxItems', 'items']
 const RESERVED_NAMES = ['constructor', 'prototype', '__proto__']
 
@@ -72,7 +77,19 @@ export function validateManifest(raw, { file, dir, folderName, fileExists = exis
   const manifest = kind === 'layout' ? validateLayout(raw, shared, fail)
     : kind === 'theme' ? validateTheme(raw, shared, fail)
     : validatePalette(raw, shared, fail)
-  return { kind, id: raw.id, title: shared.title, description: shared.description, dir, file, manifest, files }
+  const pkg = kind === 'layout' ? null : validatePackage(raw, fail)
+  return { kind, id: raw.id, title: shared.title, description: shared.description, dir, file, manifest, files, ...(pkg ? { package: pkg } : {}) }
+}
+
+// The package settings, all optional for a theme or palette of one's own;
+// the theme repository requires version, author and license.
+function validatePackage(raw, fail) {
+  const pkg = {}
+  if (raw.version != null) { if (typeof raw.version !== 'string' || !VERSION_RE.test(raw.version)) fail('version must look like 1.0.0', 'version'); pkg.version = raw.version }
+  for (const key of ['author', 'license']) if (raw[key] != null) { if (typeof raw[key] !== 'string' || !raw[key].trim()) fail(`${key} must be text`, key); pkg[key] = raw[key].trim() }
+  if (raw.homepage != null) { if (typeof raw.homepage !== 'string' || !/^https:\/\//.test(raw.homepage)) fail('homepage must be an https:// address', 'homepage'); pkg.homepage = raw.homepage }
+  if (raw.mdeck != null) { if (typeof raw.mdeck !== 'string' || !RANGE_RE.test(raw.mdeck)) fail('mdeck must look like ">=3.1.0"', 'mdeck'); pkg.mdeck = raw.mdeck }
+  return pkg
 }
 
 const FILE_KEYS = { layout: ['layout', 'styles', 'starter'], theme: ['styles'], palette: [] }

package/src/extensions/moved.js

@@ -0,0 +1,20 @@
+// Themes and palettes that came with mdeck before 3.0 and now live in the
+// theme repository. A deck that names one is told how to install it instead
+// of being told the name is unknown.
+export const MOVED = {
+  themes: ['duet', 'editorial', 'fhnw', 'terminal', 'sketch'],
+  palettes: ['cobalt', 'terra', 'brand', 'phosphor', 'pastel', 'forest'],
+}
+
+// Palettes that were removed because another one looks almost the same, by
+// the one to use instead.
+export const REPLACED = { palettes: { graphite: 'nordic', ember: 'paper' } }
+
+// "The theme "duet" is no longer built into mdeck; install it with: mdeck
+// themes install duet", what to use instead of a removed one, or null.
+// Installing goes to every deck by default.
+export function movedHint(kind, id) {
+  const instead = REPLACED[`${kind}s`]?.[id]
+  if (instead) return `The ${kind} "${id}" was removed from mdeck; use ${kind}: ${instead}, which looks almost the same`
+  return MOVED[`${kind}s`]?.includes(id) ? `The ${kind} "${id}" is no longer built into mdeck; install it with: mdeck ${kind}s install ${id}` : null
+}