mdeck 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 3.9.0 — 2026-10-11
+
+- Theme parameters say what kind of value they take: `type = "size"` (pixels, with `min`, `max` and `step`), `"number"`, `"switch"` (1 or 0), `"choice"` (one of `choices`) or `"font"`. The deck settings show a slider, a box to tick or a list instead of a text box; a deck value that does not fit is left out, so the theme's own value stays, and `mdeck check` says why; a value outside the range is used, with a warning. `mdeck list themes` shows each theme's settings and what they take, and the design page lets a theme's author set the kind. `mdeck themes build` writes each theme's settings into the gallery's `looks.json`. A parameter without a type takes any text, as before. The built-in themes give every parameter a type and a description with its default and range. A theme that uses `type` needs this version of mdeck.
+
 ## 3.8.0 — 2026-10-11
 
 - Hotspots: with `hotspots: auto` in the deck's settings, the presenter view puts a numbered key on each picture, code block, table, formula, video, callout, column and poll of the slide, and **1**–**9** zoom smoothly until that part fills the screen, keeping the slide around a part of another shape in view. The audience window, a paired iPad and phones zoom along; only the presenter view shows the keys, which can also be tapped. The same number, **0**, **Escape**, a tap on the slide or the next point or slide show the whole slide again. `hotspots: marked` keys only parts marked `data-hotspot`; a slide can set its own (`hotspots: false`), and **H** or the presenter view's new button turns hotspots on or off during the talk. Without hotspots, the default, **1**–**9** still go to slides 1–9. The editor has a **Hotspots** choice in the deck's settings and in each slide's details, and the tour deck a slide to try it on.

package/assets/extensions/themes/academic/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "academic"
 title = "Academic"
 description = "A lecture: Source Sans and Source Serif, compact slides with the heading in a fixed place, theorem and definition blocks, booktabs tables and a footnote rule."
-version = "1.0.0"
+version = "1.1.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -46,14 +46,17 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.fontSerif]
 token = "--font-serif"
 title = "Serif for theorems and quotes"
+type = "font"
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/glass/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "glass"
 title = "Glass"
 description = "Liquid glass: soft pools of light behind every slide, content without frames, titles on a frosted pane with a bright rim; capsule labels, glass beads for list markers and a glass lens for chapter numbers; Geist throughout, dark by default."
-version = "0.1.1"
+version = "0.2.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -49,14 +49,20 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.glassBlur]
 token = "--glass-blur"
 title = "How much the glass blurs"
+type = "size"
+min = 0
+max = 48
+description = "28px by default, from 0px (clear glass) to about 48px."
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/minimal/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "minimal"
 title = "Minimal"
 description = "Nothing but the content: system fonts, calm type, plenty of space, no decoration. Works offline."
-version = "1.0.0"
+version = "1.1.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -42,10 +42,12 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/neue/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "neue"
 title = "Neue"
 description = "Swiss typography: large flush-left type, rules instead of boxes, signal red on white."
-version = "1.0.0"
+version = "1.1.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -43,10 +43,12 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/plain/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "plain"
 title = "Plain"
 description = "Black on white and lots of room: Inter, the heading in a column of its own beside the content, lists of short titles with a line under each, the accent only in small places; in greyscale, dark is the same, inverted."
-version = "0.1.0"
+version = "0.2.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -48,14 +48,20 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.side]
 token = "--side"
 title = "Width of the heading column"
+type = "size"
+min = 400
+max = 640
+description = "560px of the 1920px slide by default, from about 400px to 640px; the content takes the rest."
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/assets/extensions/themes/work/extension.toml

@@ -3,7 +3,7 @@ kind = "theme"
 id = "work"
 title = "Work"
 description = "An everyday company template: IBM Plex Sans, an accent band along the top, the logo top left, headings in a fixed place, section dividers with a large number in the accent, a quiet footer with the page number."
-version = "0.1.0"
+version = "0.2.0"
 author = "Tilman Schieber"
 license = "MIT"
 # The palette this theme uses unless the deck sets one; colours come only from palettes.
@@ -47,14 +47,20 @@ styles = "styles.css"
 [params.fontDisplay]
 token = "--font-display"
 title = "Display font"
+type = "font"
 
 [params.fontBody]
 token = "--font-body"
 title = "Body font"
+type = "font"
 
 [params.band]
 token = "--band"
-title = "Height of the band along the top (0px for none)"
+title = "Height of the band along the top"
+type = "size"
+min = 0
+max = 32
+description = "14px by default, up to about 32px; 0px leaves the top without a band."
 
 # What this theme is for and how to write for it: shown in listings, and read
 # by assistants that write slides as the theme author's advice.

package/docs/reference/authoring.md

@@ -60,7 +60,7 @@ Each `---` line starts a new slide. Frontmatter is only needed when you want a s
 | `session.id` | from the title | Name the session code is derived from |
 | `session.code` | from `session.id` | The session code itself, 4 to 8 digits; phones join at `<server>/<code>` |
 | `components` | — | Extra folders of Preact components shared between decks, relative to the deck or starting with `~/` |
-| `params` | — | Theme-specific color/font overrides (see below) |
+| `params` | — | The theme's own settings, such as its fonts (see below) |
 | `reader.themes` | `true` | Whether the reader view offers a switch between light and dark (see below) |
 | `reader.notes` | `false` | Whether the reader view shows speaker notes under each slide in Read mode |
 | `bibliography` | — | Reference file, or a list of them, relative to the deck: `.bib`, `.json` (CSL-JSON) or `.yml` (Hayagriva) (see [Citations](#citations-and-references)) |
@@ -71,15 +71,20 @@ Each `---` line starts a new slide. Frontmatter is only needed when you want a s
 
 ### Theme params
 
-Some themes expose their fonts as settings. Set them under `params:`:
+Themes offer settings of their own: their fonts, and often the size or
+strength of what makes them look the way they do. Set them under `params:`:
 
 ```yaml
 params:
   fontDisplay: "Georgia, serif"
+  glassBlur: 12px
 ```
 
-Available params depend on the theme; `mdeck list themes` shows them. Colours
-are not params: they come from the palette.
+Available params depend on the theme; `mdeck list themes` shows them with the
+kind of value each takes: a size in pixels, a number, a switch (`1` or `0`), a
+choice or a font. `0` or `0px` turns a feature off. A value that does not fit
+is left out, and `mdeck check` says why. Colours are not params: they come from
+the palette.
 
 ---
 

package/docs/reference/extensions.md

@@ -201,7 +201,11 @@ Keep headings to a few words; three or four points make a good slide.
   `:root` block from them, so the stylesheet only contains rules.
 - `params` name the settings authors may change under `params:` in the deck.
   Each points at a token; its default is the token's value, so nothing is
-  written twice.
+  written twice. `type` (`size`, `number`, `switch`, `choice` or `font`) says
+  what kind of value it takes; `min`, `max` and `step` go with a size (in
+  pixels) or a number, `choices` with a choice. The token's value must be of
+  that type. The editor shows a slider, a box to tick or a list for it, and
+  `mdeck check` reports a deck value that does not fit.
 - `fonts` are stylesheet URLs. Normal builds load them; single files (`mdeck send`,
   `--single-file`) and PDFs embed their Latin character sets, so they look the
   same offline. The fallbacks named in the token values apply when a font

package/docs/reference/themes.md

@@ -77,8 +77,12 @@ params:
   fontDisplay: "Georgia, serif"
 ```
 
-A parameter's default is its token's value. Unknown parameter names are
-reported by `mdeck check`.
+A parameter's default is its token's value. `type` says what kind of value it
+takes: `size` (pixels, with `min`, `max` and `step`), `number` (with the same
+three), `switch` (1 or 0), `choice` (one of `choices`) or `font`. A deck value
+that does not fit is left out, and `mdeck check` reports it, like unknown
+parameter names; one outside `min` and `max` is used, with a warning. Without
+a `type`, a parameter takes any text.
 
 Optional settings: `description`, `appearance = "dark"` for a theme that starts
 dark, and `palettes = [...]` to offer only those palettes (a corporate design

package/docs/site/content/theme-authoring.md

@@ -140,6 +140,34 @@ params:
 
 Its default is simply the token's value. Colours are not parameters: they come from the palette.
 
+Say what kind of value a parameter takes with `type`, so mdeck can check what authors write and the editor can offer the right control:
+
+```toml
+[params.bar]
+token = "--bar"
+title = "Thickness of the bar under headings"
+type = "size"
+min = 0
+max = 20
+description = "12px by default, from about 6px to 20px; 0px leaves headings without bars."
+```
+
+| `type` | Takes | The editor shows | Settings |
+|---|---|---|---|
+| `size` | pixels: `12px`, or just `12` | a slider | `min`, `max`, `step` in pixels |
+| `number` | a number; a strength from 0 to 1 | a slider | `min`, `max`, `step` |
+| `switch` | `1` or `0` (also `true`/`false`, `on`/`off`) | a box to tick | |
+| `choice` | one of its `choices` | a list | `choices = ["left", "right"]` |
+| `font` | a CSS font list | a text box | |
+
+The token's value must be a value of that type: a `size` is written `"12px"`, a `switch` `"1"`. A value in the deck that does not fit is left out, and the theme's own value stays; `mdeck check` says why. A value outside `min` and `max` is used, with a warning: the range is what the theme was made for. A parameter without a `type` takes any text, as before.
+
+A few habits make parameters easy to use:
+
+- Turn a feature off with its parameter at zero (`0px`, `0`) rather than a second parameter.
+- Use a switch or a strength by multiplying with it, as in `calc(330px * var(--shapes))`.
+- Let the `description` give the default and a sensible range: the editor shows it under the control, and assistants read it.
+
 ## Say what it is for
 
 A `[guide]` tells people, and assistants that write slides, what your theme is good for and how slides for it are written:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdeck",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "type": "module",
   "description": "Write slides as a plain text file, present them in the browser, share them as one HTML file or PDF.",
   "license": "MIT",

package/src/cli/index.js

@@ -22,6 +22,7 @@ import { renderPdf, attachPdf, findChrome } from '../build/pdf.js'
 import { installSkill, readSkill, TARGETS } from './skill.js'
 import { runPackages } from './themes.js'
 import { ManifestError, KINDS } from '../extensions/manifest.js'
+import { paramKind } from '../extensions/params.js'
 
 import { frameworkRoot } from '../paths.js'
 import { parseSlides } from '../core/parseSlides.js'
@@ -523,6 +524,9 @@ if (command === 'new') {
       console.log(`    ${c.cyan}${record.id}${c.reset} — ${record.title} ${c.dim}(${record.source})${record.description ? ' ' + record.description : ''}${c.reset}`)
       // What a theme suits, from its guide; --json has the whole guide.
       if (record.manifest?.guide?.suits) console.log(`      ${c.dim}Suits: ${record.manifest.guide.suits.join(' · ')}${c.reset}`)
+      // The settings a deck may change under params:, with the kind of value each takes.
+      const params = Object.entries(record.manifest?.params ?? {})
+      if (params.length) console.log(`      ${c.dim}Settings: ${params.map(([name, param]) => name + paramKind(param)).join(' · ')}${c.reset}`)
     }
   }
 

package/src/cli/themes.js

@@ -34,6 +34,8 @@ function looksOf(registry, catalogue) {
       // The oldest mdeck it works with, for the gallery's install note.
       ...(registry.themes[theme.id]?.package?.mdeck ? { mdeck: registry.themes[theme.id].package.mdeck } : {}),
       palette: theme.palette, appearance: theme.appearance ?? 'light', palettes: palettesFor(theme, palettes).map(p => p.id), ...(theme.guide ? { guide: theme.guide } : {}),
+      // Its settings, for the gallery's controls: token, default, kind and range.
+      ...(Object.keys(theme.params ?? {}).length ? { params: theme.params } : {}),
       ...(icons.get(theme.id) ? { icon: icons.get(theme.id) } : {}) })),
     palettes: Object.values(palettes).map(palette => ({ id: palette.id, title: palette.title, description: palette.description ?? '', builtIn: builtIn.has(palette.id + ':p'),
       ...(palette.theme ? { theme: palette.theme } : {}), light: colours(palette.light), dark: colours(palette.dark) })),

package/src/core/validateDeck.js

@@ -4,6 +4,7 @@ import { palettesFor } from '../extensions/tokens.js'
 import { LABEL_KEYS, CALLOUT_TYPES } from './labels.js'
 import { resolveLayoutProps, propertyErrors } from '../layouts/layoutProps.js'
 import { movedHint } from '../extensions/moved.js'
+import { paramValue } from '../extensions/params.js'
 
 // Hotspots (runtime/hotspots.js): the deck's setting and a slide's own.
 const HOTSPOT_SETTINGS = ['auto', 'marked', 'off', true, false]
@@ -70,7 +71,13 @@ export function validateDeck(deck, { layouts = null, themes = null, palettes = n
   }
   if (themes && config.params != null && isPlainObject(config.params) && Object.hasOwn(themes, config.theme ?? 'neue')) {
     const theme = themes[config.theme ?? 'neue']
-    for (const name of Object.keys(config.params)) if (!Object.hasOwn(theme.params ?? {}, name)) add('unknown-param', `Theme "${theme.id}" has no parameter "${name}"; available: ${Object.keys(theme.params ?? {}).join(', ') || 'none'}`, deck.configSource?.start, 'warning')
+    for (const [name, value] of Object.entries(config.params)) {
+      const param = theme.params?.[name]
+      if (!param) { add('unknown-param', `Theme "${theme.id}" has no parameter "${name}"; available: ${Object.keys(theme.params ?? {}).join(', ') || 'none'}`, deck.configSource?.start, 'warning'); continue }
+      const result = paramValue(param, value)
+      if (result.problem) add('invalid-param', `params.${name} ${result.problem}; the theme's ${param.default} is used instead`, deck.configSource?.start, 'warning')
+      else if (result.note) add('invalid-param', `params.${name} ${result.note}; ${result.value} may not look right`, deck.configSource?.start, 'warning')
+    }
   }
   // Callout types the deck names under `callouts:` are its own, on purpose.
   const calloutTypes = [...CALLOUT_TYPES, ...(isPlainObject(config.callouts) ? Object.keys(config.callouts).map(key => key.toLowerCase()) : [])]

package/src/editor/components/DeckSettings.jsx

@@ -10,6 +10,7 @@ import { PalettePicker } from './PalettePicker.jsx'
 import { LookThumbnail } from './LookThumbnail.jsx'
 import { designUrl, DESIGN_TAB } from '../designLink.js'
 import { normalMode } from '../../runtime/hotspots.js'
+import { paramValue } from '../../extensions/params.js'
 
 // What the `show` setting controls: the label for each choice and its values.
 const SHOW = { organization: ['Organization', ['title', 'all', 'none']], author: ['Author and date', ['title', 'all', 'none']], numbers: ['Slide numbers', ['slides', 'all', 'none']], sections: ['Section labels', ['all', 'none']] }
@@ -75,11 +76,9 @@ export function DeckSettings({ state, edit }) {
       <p class="section-title">Theme settings</p>
       {Object.entries(theme.params).map(([key, def]) => {
         const value = config.params?.[key]
-        const color = isColor(def.default)
         return <Field key={key} label={def.title ?? key} hint={def.description}>
           <div class="row">
-            {color ? <input type="color" value={isColor(value) ? value : def.default} onInput={e => param(key, e.currentTarget.value)} style={{ flex: '0 0 auto' }} /> : null}
-            <input type="text" value={value ?? ''} placeholder={def.default} onInput={e => param(key, e.currentTarget.value)} />
+            <ParamInput def={def} value={value} onChange={next => param(key, next)} />
             {value != null && <button class="btn is-small is-icon" title="Back to the default" aria-label="Back to the default" onClick={() => param(key, '')}><Icon name="close" size={14} /></button>}
           </div>
         </Field>
@@ -110,3 +109,34 @@ function DesignLink({ kind, item }) {
     {own ? `Edit ${kind}` : `Customise ${kind}`} <span class="muted">{item.title}</span>
   </a>
 }
+
+// The control for one theme parameter, by its type: a slider for a size or a
+// number with a range, a box to tick for a switch, a list for a choice, else
+// text (with a colour picker when the default is a colour). An empty value
+// means the theme's own.
+function ParamInput({ def, value, onChange }) {
+  const current = value != null && !paramValue(def, value).problem ? paramValue(def, value).value : def.default
+  if (def.type === 'switch') return <>
+    <input type="checkbox" checked={current === '1'} aria-label={def.title} onChange={e => onChange(e.currentTarget.checked ? 1 : 0)} style={{ flex: '0 0 auto', width: 'auto' }} />
+    <span class="muted" style={{ flex: '1 1 auto' }}>{current === '1' ? 'On' : 'Off'}</span>
+  </>
+  if (def.type === 'choice') return <select value={value ?? ''} onChange={e => onChange(e.currentTarget.value)}>
+    <option value="">{def.default} (the theme's)</option>
+    {def.choices.filter(choice => choice !== def.default).map(choice => <option key={choice} value={choice}>{choice}</option>)}
+  </select>
+  if ((def.type === 'size' || def.type === 'number') && def.min != null && def.max != null) {
+    const unit = def.type === 'size' ? 'px' : ''
+    const number = parseFloat(current)
+    const step = def.step ?? (def.type === 'size' ? 1 : (def.max - def.min) / 100)
+    return <>
+      <input type="range" min={def.min} max={def.max} step={step} value={number} aria-label={def.title}
+        onInput={e => onChange(unit ? `${e.currentTarget.value}${unit}` : Number(e.currentTarget.value))} />
+      <span class="muted" style={{ flex: '0 0 auto', minWidth: '4em', textAlign: 'end' }}>{number}{unit}</span>
+    </>
+  }
+  const color = isColor(def.default)
+  return <>
+    {color ? <input type="color" value={isColor(value) ? value : def.default} onInput={e => onChange(e.currentTarget.value)} style={{ flex: '0 0 auto' }} /> : null}
+    <input type="text" value={value ?? ''} placeholder={def.default} onInput={e => onChange(e.currentTarget.value)} />
+  </>
+}

package/src/editor/components/ExtensionForms.jsx

@@ -7,6 +7,8 @@ import { PalettePicker, Swatches } from './PalettePicker.jsx'
 const isColor = value => /^#[0-9a-f]{3,8}$/i.test(String(value ?? '').trim())
 const update = (list, index, patch) => list.map((item, i) => i === index ? { ...item, ...patch } : item)
 const without = (list, index) => list.filter((_, i) => i !== index)
+// The kinds of value a theme parameter takes (see src/extensions/params.js).
+const PARAM_KINDS = [['', 'text'], ['size', 'size'], ['number', 'number'], ['switch', 'switch'], ['choice', 'choice'], ['font', 'font']]
 
 function Identity({ model, onChange }) {
   return <>
@@ -122,8 +124,18 @@ export function ThemeForm({ model, files, palettes = {}, onChange, onFile }) {
         <input type="text" value={param.name} placeholder="fontBody" onInput={e => onChange({ params: update(model.params, index, { name: e.currentTarget.value }) })} />
         <select value={param.token ?? ''} onChange={e => onChange({ params: update(model.params, index, { token: e.currentTarget.value }) })}><option value="">token…</option>{tokenNames.map(name => <option key={name} value={name}>{name}</option>)}</select>
         <input type="text" value={param.title ?? ''} placeholder="Title" onInput={e => onChange({ params: update(model.params, index, { title: e.currentTarget.value }) })} />
+        <select value={param.type ?? ''} aria-label="Kind of value" title="Kind of value" onChange={e => onChange({ params: update(model.params, index, { type: e.currentTarget.value || undefined }) })}>
+          {PARAM_KINDS.map(([type, label]) => <option key={type} value={type}>{label}</option>)}
+        </select>
         <button class="btn is-small is-icon" title="Remove setting" aria-label="Remove setting" onClick={() => onChange({ params: without(model.params, index) })}><Icon name="close" size={14} /></button>
       </div>
+      {(param.type === 'size' || param.type === 'number') && <div class="row">
+        {['min', 'max', 'step'].map(key => <input key={key} type="number" value={param[key] ?? ''} placeholder={key} aria-label={key}
+          onInput={e => onChange({ params: update(model.params, index, { [key]: e.currentTarget.value === '' ? undefined : Number(e.currentTarget.value) }) })} />)}
+      </div>}
+      {param.type === 'choice' && <input type="text" value={(param.choices ?? []).join(', ')} placeholder="choices, separated by commas"
+        onInput={e => onChange({ params: update(model.params, index, { choices: e.currentTarget.value.split(',').map(choice => choice.trim()).filter(Boolean) }) })} />}
+      <input type="text" value={param.description ?? ''} placeholder="Description: the default and a sensible range" onInput={e => onChange({ params: update(model.params, index, { description: e.currentTarget.value }) })} />
     </div>)}
     <div><button class="btn is-small" onClick={() => onChange({ params: [...model.params, { name: '', token: tokenNames[0] ?? '', title: '' }] })}>+ setting</button></div>
     <details class="advanced">

package/src/editor/extensions.js

@@ -13,6 +13,9 @@ const STARTER_COLORS = {
 
 const entries = table => Object.entries(table ?? {}).map(([name, value]) => ({ name, ...(value && typeof value === 'object' && !Array.isArray(value) ? value : { value }) }))
 const table = (list, pick) => Object.fromEntries(list.filter(item => item.name).map(item => [item.name, pick(item)]))
+// A parameter's settings as the manifest writes them; the typed ones only with a type.
+const paramSettings = param => clean({ token: param.token, title: param.title, description: param.description,
+  ...(param.type ? { type: param.type, min: param.min, max: param.max, step: param.step, choices: param.choices } : {}) })
 const clean = object => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined && value !== '' && value !== null && !(Array.isArray(value) && !value.length)))
 
 export function parseManifest(text) {
@@ -39,7 +42,7 @@ export function toToml(model) {
   else if (model.kind === 'theme') raw = {
     ...base, palette: model.palette, ...clean({ palettes: model.palettes }), ...(model.appearance === 'dark' ? { appearance: 'dark' } : {}), fonts: model.fonts ?? [], ...model.extra,
     files: { styles: 'styles.css', ...(model.files ?? {}) }, tokens,
-    params: table(model.params ?? [], param => clean({ token: param.token, title: param.title, description: param.description })),
+    params: table(model.params ?? [], paramSettings),
   }
   else if (model.kind === 'layout') raw = {
     ...base, ...(model.frame && model.frame !== 'standard' ? { frame: model.frame } : {}), ...model.extra, ...(Object.keys(model.files ?? {}).length ? { files: model.files } : {}),
@@ -67,7 +70,7 @@ export function toRuntimeManifest(model) {
   if (model.kind === 'palette') return { ...shared, ...(model.theme ? { theme: model.theme } : {}), light: table(model.light ?? [], token => token.value ?? ''), dark: table(model.dark ?? [], token => token.value ?? '') }
   if (model.kind === 'theme') return {
     ...shared, palette: model.palette, ...(model.palettes?.length ? { palettes: model.palettes } : {}), appearance: model.appearance ?? 'light', fonts: model.fonts ?? [], tokens,
-    params: table(model.params ?? [], param => ({ token: param.token, default: tokens[param.token] ?? '', ...(param.title ? { title: param.title } : {}) })),
+    params: table(model.params ?? [], param => ({ ...paramSettings(param), default: tokens[param.token] ?? '' })),
     ...(model.extra?.guide ? { guide: runtimeGuide(model.extra.guide) } : {}),
   }
   return shared
@@ -89,6 +92,6 @@ export function starterFiles(kind, id, title, from = null, fromFiles = {}) {
     return { [MANIFEST]: toToml({ kind, id, title, description: '', theme: '', light, dark, extra: {} }) }
   }
   if (kind !== 'theme' || !from) throw new Error('A new theme starts as a copy of another one')
-  const params = from.params && Object.fromEntries(Object.entries(from.params).map(([name, param]) => [name, { token: param.token, title: param.title, description: param.description }]))
+  const params = from.params && Object.fromEntries(Object.entries(from.params).map(([name, param]) => [name, paramSettings(param)]))
   return { [MANIFEST]: toToml({ ...toModel({ ...from, kind, params }), id, title, files: {} }), 'styles.css': fromFiles['styles.css'] ?? '' }
 }

package/src/extensions/appearance.js

@@ -7,6 +7,7 @@
 // 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'
+import { paramValue } from './params.js'
 
 // Code highlighting and logos on dark slides, unless the palette says otherwise.
 export const DARK_TOKENS = {
@@ -62,8 +63,11 @@ export function buildAppearance({ theme, palettes = {}, palette, appearance, par
   const overrides = {}
   for (const [name, value] of Object.entries(params ?? {})) {
     const param = theme.params?.[name]
-    if (param) overrides[param.token] = value
-    else warnings.push(`Theme "${theme.id}" has no parameter "${name}"`)
+    if (!param) { warnings.push(`Theme "${theme.id}" has no parameter "${name}"`); continue }
+    // A value that does not fit the parameter's type is left out: the theme's own value stays.
+    const result = paramValue(param, value)
+    if (result.problem) warnings.push(`params.${name} ${result.problem}; the theme's ${param.default} is used`)
+    else overrides[param.token] = result.value
   }
   for (const [key, value] of Object.entries(meta ?? {})) overrides[`--meta-${key}`] = JSON.stringify(String(value))
   const overridesCss = tokensToCss(overrides)

package/src/extensions/manifest.js

@@ -6,6 +6,7 @@ import { resolve, relative, isAbsolute, sep } from 'node:path'
 import { parse as parseToml, TomlError } from 'smol-toml'
 import { TOKEN_NAME_RE, COLOR_ROLES, COLOR_FALLBACKS, APPEARANCES } from './tokens.js'
 import { propertyErrors } from '../layouts/layoutProps.js'
+import { paramSettingProblems, paramSettings } from './params.js'
 
 export const SCHEMA_VERSION = 1
 export const KINDS = ['layout', 'theme', 'palette']
@@ -198,10 +199,9 @@ function validateTheme(raw, shared, fail) {
     const path = `params.${name}`
     if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name) || RESERVED_NAMES.includes(name)) fail('parameter names use letters and digits and start with a letter', path)
     if (!isPlainObject(param)) fail('must be a table with a token', path)
-    for (const key of Object.keys(param)) if (!['token', 'title', 'description'].includes(key)) fail('Unknown parameter setting. Allowed: token, title, description', `${path}.${key}`)
     if (typeof param.token !== 'string' || !Object.hasOwn(tokens, param.token)) fail(`token must name an entry of [tokens] (got ${JSON.stringify(param.token)})`, `${path}.token`)
-    for (const key of ['title', 'description']) if (param[key] != null && typeof param[key] !== 'string') fail('must be text', `${path}.${key}`)
-    params[name] = { token: param.token, default: tokens[param.token], ...(param.title ? { title: param.title } : {}), ...(param.description ? { description: param.description } : {}) }
+    for (const [key, message] of paramSettingProblems(param, tokens[param.token])) fail(message, `${path}.${key}`)
+    params[name] = { token: param.token, default: tokens[param.token], ...(param.title ? { title: param.title } : {}), ...(param.description ? { description: param.description } : {}), ...paramSettings(param) }
   }
   const guide = validateGuide(raw.guide, fail)
   return {

package/src/extensions/params.js

@@ -0,0 +1,113 @@
+// What a theme parameter may be set to. A parameter without a type takes any
+// text, as before; a typed one says what kind of value it takes, and mdeck
+// turns what the author wrote into CSS or says why it cannot:
+//
+//   size     pixels ("12px", or a number: 12), with min and max in pixels
+//   number   a number, with min and max (a strength is one from 0 to 1)
+//   switch   1 or 0 (also true and false, on and off, yes and no)
+//   choice   one of `choices`
+//   font     a CSS font list
+//
+// The manifest check, `mdeck check`, the slides and the editor all use these
+// functions, so they agree on what a value means.
+
+export const PARAM_TYPES = ['size', 'number', 'switch', 'choice', 'font']
+export const PARAM_KEYS = ['token', 'title', 'description', 'type', 'min', 'max', 'step', 'choices']
+const RANGED = ['size', 'number']
+const NUMBER_RE = /^-?(\d+\.?\d*|\.\d+)$/
+const SWITCH = new Map([['1', '1'], ['0', '0'], ['true', '1'], ['false', '0'], ['on', '1'], ['off', '0'], ['yes', '1'], ['no', '0']])
+
+// "12px", 12 or "12" as a number of pixels; null when it is not a size.
+function pixels(value) {
+  const text = String(value).trim().toLowerCase()
+  const number = text.endsWith('px') ? text.slice(0, -2).trim() : text
+  return NUMBER_RE.test(number) ? Number(number) : null
+}
+
+const unit = param => param.type === 'size' ? 'px' : ''
+
+/** The range a parameter was made for, as text ("6px to 20px", "at least 0"), or ''. */
+export function paramRange(param) {
+  const { min, max } = param
+  const u = unit(param)
+  if (min != null && max != null) return `${min}${u} to ${max}${u}`
+  if (min != null) return `at least ${min}${u}`
+  if (max != null) return `at most ${max}${u}`
+  return ''
+}
+
+/** The kind of value a parameter takes, for listings: " (size, 0px to 48px)", " (1 or 0)", or '' without a type. */
+export function paramKind(param) {
+  if (!param.type) return ''
+  if (param.type === 'switch') return ' (1 or 0)'
+  if (param.type === 'choice') return ` (${param.choices.join(', ')})`
+  const range = paramRange(param)
+  return ` (${param.type}${range ? ', ' + range : ''})`
+}
+
+/**
+ * The CSS for a value an author set, or why it cannot be used.
+ * Returns { value } with a note when it lies outside the range (it is still
+ * used: the range is what the theme was made for, not a limit), or { problem }.
+ */
+export function paramValue(param, raw) {
+  const type = param.type
+  if (raw == null || (typeof raw === 'object')) return { problem: 'needs a single value' }
+  if (!type) return { value: String(raw) }
+  const text = String(raw).trim()
+  if (!text) return { problem: 'is empty' }
+  if (type === 'font') return { value: text }
+  if (type === 'switch') {
+    const value = SWITCH.get(text.toLowerCase())
+    return value ? { value } : { problem: 'is a switch: 1 or 0' }
+  }
+  if (type === 'choice') {
+    return param.choices.includes(text) ? { value: text } : { problem: `must be one of: ${param.choices.join(', ')}` }
+  }
+  const number = type === 'size' ? pixels(text) : (NUMBER_RE.test(text) ? Number(text) : null)
+  if (number == null) return { problem: type === 'size' ? 'is a size in pixels, such as 12px' : 'is a number, such as 0.5' }
+  const value = type === 'size' ? `${number}px` : String(number)
+  const outside = (param.min != null && number < param.min) || (param.max != null && number > param.max)
+  return outside ? { value, note: `is made for ${paramRange(param)}` } : { value }
+}
+
+/**
+ * What is wrong with a parameter's settings in a manifest, as [key, message]
+ * pairs; `fallback` is its default (the token's value), which must fit it too.
+ */
+export function paramSettingProblems(param, fallback) {
+  const problems = []
+  for (const key of Object.keys(param)) if (!PARAM_KEYS.includes(key)) problems.push([key, `Unknown parameter setting. Allowed: ${PARAM_KEYS.join(', ')}`])
+  for (const key of ['title', 'description']) if (param[key] != null && typeof param[key] !== 'string') problems.push([key, 'must be text'])
+  const type = param.type
+  if (type == null) {
+    for (const key of ['min', 'max', 'step', 'choices']) if (param[key] != null) problems.push([key, 'needs a type (size or number for min, max and step; choice for choices)'])
+    return problems
+  }
+  if (!PARAM_TYPES.includes(type)) return [...problems, ['type', `must be one of: ${PARAM_TYPES.join(', ')}`]]
+  for (const key of ['min', 'max', 'step']) {
+    if (param[key] == null) continue
+    if (!RANGED.includes(type)) problems.push([key, `is for a size or a number, not a ${type}`])
+    else if (typeof param[key] !== 'number' || !Number.isFinite(param[key])) problems.push([key, `must be a number${type === 'size' ? ' of pixels, such as 12' : ''}`])
+  }
+  if (typeof param.step === 'number' && param.step <= 0) problems.push(['step', 'must be more than 0'])
+  if (typeof param.min === 'number' && typeof param.max === 'number' && param.min > param.max) problems.push(['max', 'must not be less than min'])
+  if (type === 'choice') {
+    const choices = param.choices
+    if (!Array.isArray(choices) || !choices.length || choices.some(choice => typeof choice !== 'string' || !choice.trim())) problems.push(['choices', 'a choice needs a list of its values, such as choices = ["left", "right"]'])
+    else if (new Set(choices).size !== choices.length) problems.push(['choices', 'lists a value twice'])
+  } else if (param.choices != null) problems.push(['choices', `is for a choice, not a ${type}`])
+  if (problems.length || fallback == null) return problems
+  // The default is the token's value: it has to be a value of this type too.
+  const result = paramValue(param, fallback)
+  if (result.problem) problems.push(['type', `the token's value ${JSON.stringify(fallback)} ${result.problem}`])
+  else if (result.note) problems.push(['type', `the token's value ${JSON.stringify(fallback)} lies outside ${paramRange(param)}`])
+  else if (type !== 'font' && result.value !== fallback) problems.push(['type', `write the token's value as ${JSON.stringify(result.value)}`])
+  return problems
+}
+
+/** A parameter's typed settings, as a normalized manifest keeps them. */
+export function paramSettings(param) {
+  if (!param.type) return {}
+  return Object.fromEntries(['type', 'min', 'max', 'step', 'choices'].filter(key => param[key] != null).map(key => [key, key === 'choices' ? [...param[key]] : param[key]]))
+}