mdeck 2.3.0

package/docs/reference/structured-slides.md

@@ -0,0 +1,120 @@
+# Structured slides and validation
+
+Existing decks keep their `---` frontmatter syntax. Code fences protect literal
+`---` and `:::notes` examples. A deck can also start directly with Markdown.
+Legacy slide metadata is recognized by a known field at the start of the block
+(such as `layout:`, `section:` or `image:`). For arbitrary metadata, or to remove
+that ambiguity, use an explicit metadata block at the start of a slide:
+
+```markdown
+---
+:::meta
+layout: split
+id: deployment-options
+:::
+# Deployment options
+
+:::slot left
+## Directory bundle
+- Separate media files
+:::
+
+:::slot right
+## Single HTML file
+- Easy to transfer
+:::
+
+:::notes
+Explain the tradeoff.
+:::
+```
+
+`:::meta` belongs to the slide, while the optional initial deck configuration
+continues to use YAML between `---` lines. Put a blank line before a directive
+when combining it with ordinary Markdown. Directives can nest: for example, a
+callout inside columns inside a slot. `+++` separates columns only at that
+column block's top level. Slots, notes and metadata are top-level slide blocks.
+
+Unassigned Markdown is the `body` region. `split` accepts `left` and `right`
+regions with the shared body above them; without named regions it retains the
+legacy first-block-left behavior. An explicit `:::slot body` is also supported,
+but cannot be combined with unassigned content. Duplicate or unclosed regions
+are errors. Layouts declare the other regions they accept.
+
+Set `id:` for a durable link such as `#deployment-options`. Numeric links such
+as `#3` remain supported. Without an authored ID, the parser assigns positional
+IDs (`slide-1`, etc.); these are not stable across reordering.
+
+Run `mdeck check talk.md` to validate YAML, dimensions, IDs, metadata and local
+asset references. `--strict` also fails on warnings. Builds reject source errors;
+unknown layouts warn and retain the generic fallback for compatibility.
+
+## Source model for integrations
+
+`parseSlides(source)` returns the original `source`, `deckConfig`, `configSource`,
+`slides` and `diagnostics`. Each slide has its resolved `meta`, `authoredMeta`
+(the authored YAML fields before section inheritance), `id`, `content`, `regions`, directive `blocks`, and
+`source`, `metaSource`, `bodySource` ranges. Ranges are half-open UTF-16 offsets
+into the original string, including its whitespace and line endings.
+
+Regions contain Markdown `content`. Explicit regions also carry their original
+`raw` body and contiguous `source` range. The implicit body has `ranges` because
+notes and slots may interrupt it. This is a source-preserving document model,
+not a normalized Markdown serializer. Speaker notes come from `:::notes` body
+blocks and are available as `slide.meta.notes`; they are not authored metadata.
+
+`serializeDeck(deck)` returns the original source unchanged. Use
+`replaceRegion(deck, slideId, regionName, markdown)` for targeted explicit-region
+edits, or `applySourceEdits(source, edits)` for general changes. Edits specify
+`start`, `end`, `text` and optionally `expected` text; overlaps and stale expected
+text are rejected. Reparse the returned source after editing. Callers saving to
+disk must also compare against the current file to detect external changes.
+
+## Editing helpers
+
+`src/core/editDeck.js` builds on the source model to change a deck without
+disturbing anything else in the file. Every function takes the parsed deck,
+never mutates it, and returns the new source (or `{ source, index }` for
+structural changes); reparse the result before the next edit. Untouched bytes
+stay identical, including comments, blank lines and the file's line endings.
+
+| Function | Effect |
+|---|---|
+| `setRegion(deck, slideId, name, markdown)` | Replaces an explicit `:::slot` body, the implicit body (discontiguous ranges collapse into the first one), or appends a new slot |
+| `removeRegion(deck, slideId, name)` | Removes a slot block |
+| `setSlideMeta(deck, slideId, patch)` | Patches top-level keys of the slide's YAML; `undefined` deletes a key; works for `:::meta` and the legacy `---` form, inserting or removing the block as needed |
+| `setSlideNotes(deck, slideId, markdown)` | Edits or removes a `:::notes` block, or appends one when absent |
+| `setDeckConfig(deck, patch)` | Patches the frontmatter, inserting it when absent |
+| `insertSlide(deck, index, markdown)` | Inserts a slide, keeping delimiters and blank lines tidy |
+| `removeSlide(deck, slideId)` / `moveSlide(deck, slideId, toIndex)` | Structural changes that return the index to select next |
+| `replaceSlideSource(deck, slideId, text)` | Replaces one slide's Markdown verbatim |
+
+Metadata patches rewrite only the block of each changed key
+(`patchYamlMapping` in `source.js`), so comments on other keys survive.
+Comments inside an edited nested block such as `props:` are lost.
+
+## Editor API
+
+`mdeck edit` serves a small JSON API from the Vite dev server for the browser
+editor. It binds to the loopback interface, refuses requests whose `Origin`
+differs from its own host, and only ever writes the deck file and folders
+under the deck's `extensions/` directory.
+
+| Route | Purpose |
+|---|---|
+| `GET /__mdeck/deck` | `{ path, name, source, hash, registry, warnings }` |
+| `POST /__mdeck/source` | `{ source, base }` writes when `base` equals the hash of the file on disk; otherwise `409 { source, hash }` |
+| `GET /__mdeck/extension/:kind/:id` | The extension's manifest and text files |
+| `PUT /__mdeck/extension/:kind/:id` | `{ files: { name: text \| null } }` writes into `extensions/<id>/` after validating the manifest against the files that will exist; built-ins are refused |
+| `DELETE /__mdeck/extension/:kind/:id` | Removes a deck-local extension folder |
+
+Two custom websocket events keep the editor in step with the disk:
+`mdeck:deck-changed { hash }` when another program saved the deck, and
+`mdeck:extensions-changed { file }` when an extension file changed.
+
+The preview iframe runs the normal deck runtime with `?view=deck&editor=1`. The editor
+posts `{ deckSource: { source, selection, config, overrides } }` to it;
+`config` merges over the deck settings (for example to preview a palette) and
+`overrides` carries unsaved theme and palette manifests. The runtime answers
+with `{ deckEditorReady }`, `{ deckRendered: { slideCount, diagnostics, error } }`
+and the usual `{ deckStateChanged }` messages.

package/docs/reference/themes.md

@@ -0,0 +1,133 @@
+# Themes
+
+A theme defines how slides look: typography, spacing and layout structure. Its
+colours come from a [palette](palettes.md): each theme names a default, and the
+deck may choose another. A theme is one kind of [extension](extensions.md).
+
+## Using a theme
+
+Set `theme:` in the deck frontmatter:
+
+```yaml
+---
+theme: neue
+---
+```
+
+| Theme | Look | Default palette |
+|---|---|---|
+| `neue` | Swiss style: large flush-left type, rules, red on white | `swiss` |
+| `aurora` | Northern lights: curtains of light, night-sky chapters, frosted glass | `neon` |
+| `duet` | Two voices: heavy slab headings, split slides as two colour fields, diagonal chapters | `cobalt` |
+| `editorial` | Magazine spread: masthead rule, drop caps, pull quotes, Roman chapter numerals | `terra` |
+| `fhnw` | The FHNW corporate design | `brand` (the only one) |
+| `terminal` | A terminal session: prompts, a blinking cursor, a tmux status bar | `phosphor`, dark |
+| `academic` | A lecture: compact type, the heading fixed at the top and the content centred below, theorem and definition blocks, booktabs tables, a footnote rule | `nordic` |
+| `sketch` | A sketchbook: handwriting on dotted paper, marker scribbles, sticky-note callouts, taped photos | `pastel` |
+
+`mdeck list my-talk.md` lists them with their descriptions.
+
+## Theme structure
+
+```text
+assets/extensions/themes/my-theme/     built-in
+extensions/my-theme/                    beside a deck
+  extension.toml     identity, default palette, fonts, tokens, parameters
+  styles.css         slide frame and layout rules
+```
+
+No registration step is needed: any theme folder in either place is found
+automatically, and the `mdeck new` wizard offers it.
+
+### `extension.toml`
+
+```toml
+schema = 1
+kind = "theme"
+id = "my-theme"
+title = "My Theme"
+palette = "lagoon"
+fonts = ["https://fonts.googleapis.com/css2?family=..."]
+
+[tokens]
+"--fs-display" = "128px"
+"--fs-h" = "64px"
+"--fs-body" = "34px"
+"--pad-x" = "140px"
+"--pad-y" = "110px"
+"--font-display" = "\"My Display Font\", sans-serif"
+"--font-body" = "\"My Body Font\", sans-serif"
+
+[params.fontDisplay]
+token = "--font-display"
+title = "Display font"
+```
+
+`palette` names the default palette. `tokens` hold the typography and spacing
+values the stylesheet uses; mdeck writes them into a `:root` block ahead of the
+stylesheet. A theme may not set the nine palette colours.
+
+`params` connect author-facing names to tokens. Users set them in the deck:
+
+```yaml
+params:
+  fontDisplay: "Georgia, serif"
+```
+
+A parameter's default is its token's value. Unknown parameter names are
+reported by `mdeck check`.
+
+Optional settings: `description`, `appearance = "dark"` for a theme that starts
+dark, and `palettes = [...]` to offer only those palettes (the FHNW theme offers
+only `brand`). `[files] styles` may name one stylesheet or a list.
+
+### `styles.css`
+
+Layout CSS for all slide types. It refers to the palette colours (`--bg`,
+`--ink`, `--accent` …) and the theme's tokens for every colour and spacing value
+and contains no `:root` defaults of its own. It must style:
+
+- `.slide` — base slide
+- `.slide-header`, `.slide-footer`, `.slide-body` — structural rails
+- `.slide--title`, `.slide--chapter`, `.slide--focus`, `.slide--image-text`, `.slide--split`, `.slide--full-bleed-image` — the built-in layouts
+
+## Custom layouts
+
+Define reusable slide structures with [deck-local layouts](layouts.md).
+They provide named regions, typed properties, and shared slide chrome without
+editing the framework. Theme CSS continues to style those structures.
+
+For compatibility, an unrecognised `layout:` value warns and falls through to the
+generic renderer. It renders the full Markdown body with standard slide chrome
+and emits a `.slide--<layout-name>` class. Prefer a declared layout for new layouts.
+
+To style a custom layout, target `.slide--<layout-name>` in a CSS file loaded alongside your deck, or use inline styles in your markdown HTML.
+
+Because `.slide-body` sets baseline typography (`font-family`, `font-size`, `color`, `line-height`) as inheritable defaults, any raw HTML you write inside a custom slide automatically inherits the theme's body text style. You only need inline styles for structural concerns like grid layout:
+
+```markdown
+---
+layout: four-columns
+---
+# My heading
+
+<div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 48px;">
+  <div><strong>One</strong> — description text</div>
+  <div><strong>Two</strong> — description text</div>
+  <div><strong>Three</strong> — description text</div>
+  <div><strong>Four</strong> — description text</div>
+</div>
+```
+
+Standard markdown elements (`h1`–`h6`, `p`, `ul`, `ol`, `strong`, `em`, `code`) are styled by the theme and work without any inline styles.
+
+## Colour contract
+
+A theme uses only the nine palette colours, and mixes of them
+(`color-mix(in oklab, var(--accent) 14%, var(--bg))`). This is what makes every
+palette fit every theme. For an inverted slide it reads the palette's other
+variant, `--inverse-bg`, `--inverse-ink`, `--inverse-accent` and so on, which is
+tuned to be read on its own background.
+
+Themes may define additional tokens for type, spacing and shapes; those are
+theme-specific and are not affected by palettes.

package/docs/site/assets/favicon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <title>mdeck</title>
+  <rect width="512" height="512" rx="96" fill="#0d9488"/>
+  <rect x="72" y="136" width="368" height="240" rx="18" fill="#f4f1e8"/>
+  <g fill="#0d9488">
+    <rect x="132" y="176" width="26" height="160" rx="13"/>
+    <rect x="184" y="176" width="26" height="160" rx="13"/>
+    <rect x="102" y="222" width="140" height="26" rx="13"/>
+    <rect x="102" y="266" width="140" height="26" rx="13"/>
+  </g>
+  <g fill="#1b1a17" opacity="0.85">
+    <rect x="268" y="226" width="130" height="20" rx="10"/>
+    <rect x="268" y="276" width="88" height="20" rx="10"/>
+  </g>
+</svg>

package/docs/site/assets/github-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="20" height="20"><path fill="#24292f" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>

package/docs/site/assets/site.css

@@ -0,0 +1,162 @@
+:root {
+  --paper: #fff;
+  --mist: #eef2f7;
+  --ink: #203148;
+  --secondary: #54647a;
+  --blue: #244ec7;
+  --blue-soft: #e8eefc;
+  --rule: #dbe3ee;
+  --code: #f5f7fa;
+  --font: 'Avenir Next', Avenir, 'Segoe UI', sans-serif;
+  --mono: 'SFMono-Regular', Consolas, 'Liberation Mono', monospace;
+  color: var(--ink);
+  background: var(--paper);
+  font: 17px/1.7 var(--font);
+  scroll-padding-top: 110px;
+}
+* { box-sizing: border-box; }
+body { margin: 0; }
+a { color: var(--blue); text-decoration-thickness: 1px; text-underline-offset: .2em; }
+a:hover { text-decoration-thickness: 2px; }
+button, input, select { font: inherit; }
+button, select { cursor: pointer; }
+button { color: var(--ink); }
+button:disabled { cursor: default; }
+:focus-visible { outline: 3px solid var(--blue); outline-offset: 4px; border-radius: 2px; }
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+.skip-link { position: fixed; top: -100px; left: 16px; z-index: 100; padding: 12px 20px; background: white; border: 2px solid var(--blue); }
+.skip-link:focus { top: 12px; }
+.site-header { height: 82px; padding: 0 38px; display: flex; align-items: center; justify-content: space-between; gap: 30px; background: var(--paper); border-bottom: 1px solid var(--rule); position: sticky; top: 0; z-index: 10; }
+.brand { display: inline-flex; align-items: center; gap: 13px; color: var(--ink); text-decoration: none; font-size: 27px; font-weight: 750; letter-spacing: -.05em; }
+.brand img { width: 30px; height: 30px; border-radius: 7px; }
+.brand-guide { font-size: 15px; font-weight: 450; color: var(--secondary); letter-spacing: 0; margin-left: 12px; padding-left: 20px; border-left: 1px solid var(--rule); }
+.header-tools { display: flex; align-items: center; gap: 14px; }
+.repo-link { display: inline-flex; align-items: center; gap: 7px; padding: 8px 12px; border: 1px solid var(--rule); border-radius: 6px; color: var(--ink); text-decoration: none; font-size: 14px; font-weight: 500; white-space: nowrap; }
+.repo-link:hover { background: var(--mist); }
+.repo-link img { width: 20px; height: 20px; }
+@media (max-width: 640px) { .repo-link { font-size: 0; gap: 0; padding: 8px; } }
+.search-box { width: min(340px, 45vw); position: relative; }
+.search-box input { appearance: none; width: 100%; padding: 9px 38px 9px 15px; color: var(--ink); background: var(--mist); border: 1px solid transparent; border-radius: 6px; font-size: 14px; }
+.search-box input::placeholder { color: var(--secondary); }
+.search-box kbd { position: absolute; right: 14px; top: 9px; font: 14px/24px var(--mono); color: var(--secondary); pointer-events: none; }
+#search-results { position: absolute; right: 0; top: calc(100% + 10px); width: min(530px, 90vw); max-height: 65vh; overflow: auto; padding: 8px; background: white; border: 1px solid var(--rule); border-radius: 8px; box-shadow: 0 12px 35px #20314820; }
+#search-results[hidden] { display: none; }
+#search-results a { display: block; padding: 12px; text-decoration: none; border-radius: 4px; }
+#search-results a:hover, #search-results a:focus-visible { background: var(--blue-soft); }
+#search-results strong { display: block; font-size: 15px; }
+#search-results span, #search-results p { font-size: 13px; line-height: 1.5; color: var(--secondary); }
+#search-results p { margin: 12px; }
+.site-layout { display: grid; grid-template-columns: 256px minmax(0, 820px) 200px; max-width: 1430px; padding: 0 38px; margin: auto; column-gap: 46px; }
+.nav-shell { position: sticky; top: 82px; height: calc(100dvh - 82px); overflow: auto; padding: 32px 10px 28px 0; scrollbar-width: thin; }
+.nav-shell > summary { display: none; }
+.nav-group { margin: 0 0 23px; }
+.nav-group > p, .advanced-nav > summary { margin: 0 0 8px; color: var(--ink); font-size: 13px; font-weight: 700; }
+.nav-group a, .advanced-nav a { display: block; padding: 6px 12px; margin: 2px 0; border-radius: 4px; font-size: 13px; line-height: 1.55; text-decoration: none; color: var(--secondary); }
+.nav-group a:hover, .advanced-nav a:hover { background: var(--mist); color: var(--ink); }
+.nav-shell a[aria-current] { background: var(--blue-soft); color: var(--blue); font-weight: 650; }
+.advanced-nav { padding-top: 10px; border-top: 1px solid var(--rule); }
+.advanced-nav > summary { padding: 6px 0; cursor: pointer; }
+.nav-help { display: block; margin-top: 27px; padding-top: 18px; border-top: 1px solid var(--rule); color: var(--secondary); text-decoration: none; font-size: 11px; }
+.nav-help code { display: block; margin-top: 3px; color: var(--ink); font-size: 12px; }
+main { min-width: 0; padding: 49px 0 20px; }
+article { max-width: 76ch; }
+article img { display: block; max-width: 100%; height: auto; border: 1px solid var(--rule); border-radius: 6px; }
+article a:has(> img) { display: block; margin: 16px 0 8px; }
+.breadcrumb { color: var(--secondary); font-size: 13px; margin: 0 0 12px; }
+h1, h2, h3 { line-height: 1.2; letter-spacing: -.035em; font-weight: 700; color: var(--ink); }
+h1 { font-size: clamp(32px, 3vw, 46px); margin: 0 0 24px; max-width: 23ch; }
+.welcome h1 { font-size: clamp(40px, 4.5vw, 63px); line-height: 1.08; max-width: 14ch; letter-spacing: -.055em; }
+.welcome article > p:first-of-type { font-size: 20px; line-height: 1.55; color: var(--secondary); max-width: 53ch; }
+.welcome article > p:nth-of-type(3) > a { display: inline-block; background: var(--blue); color: white; text-decoration: none; padding: 10px 19px; border-radius: 5px; font-size: 15px; font-weight: 600; }
+h2 { font-size: 28px; margin: 52px 0 17px; }
+h3 { font-size: 21px; margin: 32px 0 12px; }
+p { margin: 0 0 20px; }
+li { padding-left: 3px; margin-bottom: 9px; }
+ul, ol { padding-left: 25px; margin: 20px 0; }
+strong { font-weight: 650; }
+.heading-link { margin-left: 10px; font-size: .7em; font-weight: 400; opacity: 0; text-decoration: none; }
+h2:hover .heading-link, h3:hover .heading-link, .heading-link:focus-visible { opacity: 1; }
+code, kbd { font-family: var(--mono); }
+:not(pre) > code { font-size: .84em; background: var(--mist); padding: 2px 5px; border-radius: 3px; overflow-wrap: anywhere; }
+.code-example { margin: 25px 0; border: 1px solid var(--rule); border-radius: 7px; overflow: hidden; background: var(--code); }
+.code-example figcaption { display: flex; justify-content: space-between; align-items: center; padding: 8px 16px; border-bottom: 1px solid var(--rule); font-size: 12px; color: var(--secondary); }
+.code-example button { background: none; border: 0; font-size: 12px; padding: 4px 9px; border-radius: 3px; }
+.code-example button:hover { background: var(--blue-soft); }
+pre { margin: 0; padding: 20px; overflow-x: auto; font: 13px/1.8 var(--mono); tab-size: 2; }
+pre code { white-space: pre; }
+.token.comment, .token.prolog { color: #637084; }
+.token.punctuation { color: #536279; }
+.token.keyword, .token.tag, .token.important { color: #244ec7; }
+.token.string, .token.attr-value { color: #17625c; }
+.token.function, .token.attr-name, .token.key { color: #753fa1; }
+.token.number, .token.boolean { color: #a33a51; }
+.token.title, .token.bold { font-weight: 700; }
+.table-scroll { overflow-x: auto; margin: 26px 0; border: 1px solid var(--rule); border-radius: 5px; }
+table { border-collapse: collapse; width: 100%; font-size: 14px; text-align: left; }
+th { background: var(--mist); font-weight: 650; }
+th, td { padding: 12px 16px; border-bottom: 1px solid var(--rule); vertical-align: top; }
+tr:last-child td { border-bottom: 0; }
+td { min-width: 140px; }
+blockquote, .advanced-notice { border-left: 3px solid var(--blue); padding: 12px 19px; margin: 24px 0; background: var(--blue-soft); font-size: 15px; }
+blockquote p:last-child { margin: 0; }
+.slide-example { margin: 32px 0; border-radius: 8px; overflow: hidden; background: var(--blue-soft); border: 1px solid #c6d3f2; }
+.slide-example > figcaption { display: flex; justify-content: space-between; gap: 20px; padding: 13px 18px; font-size: 12px; color: #344d80; }
+.slide-example iframe { display: block; width: calc(100% - 36px); aspect-ratio: 16 / 9; margin: 0 18px; border: 0; background: white; box-shadow: 0 3px 9px #20314815; }
+.preview-controls { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 13px 18px; font-size: 12px; }
+.preview-controls > div { display: flex; align-items: center; gap: 7px; }
+.preview-controls button, .preview-controls select { padding: 5px 9px; border: 1px solid #bdcce9; background: white; border-radius: 4px; font-size: 12px; }
+.preview-controls button:hover { border-color: var(--blue); color: var(--blue); }
+.preview-controls output { margin-left: 5px; color: #344d80; }
+.preview-controls label { display: flex; align-items: center; gap: 7px; color: #344d80; }
+.page-outline { position: sticky; top: 120px; align-self: start; font-size: 12px; max-height: calc(100dvh - 150px); overflow: auto; padding-left: 18px; border-left: 1px solid var(--rule); margin-top: 53px; }
+.page-outline > p { font-weight: 650; margin: 0 0 12px; }
+.page-outline a { display: block; margin-bottom: 10px; color: var(--secondary); text-decoration: none; line-height: 1.5; }
+.page-outline a:hover { color: var(--blue); }
+.page-navigation { display: flex; justify-content: space-between; gap: 24px; margin: 64px 0 30px; padding-top: 25px; border-top: 1px solid var(--rule); font-size: 15px; }
+.page-navigation a { flex: 1; text-decoration: none; }
+.page-navigation a:last-child { text-align: right; }
+.page-navigation small { display: block; font-size: 11px; color: var(--secondary); margin-bottom: 6px; }
+.article-footer { font-size: 11px; color: var(--secondary); display: flex; justify-content: space-between; gap: 20px; padding-bottom: 24px; }
+@media (min-width: 961px) { .nav-shell:not([open]) > nav { display: block; } }
+@media (max-width: 1250px) { .site-layout { grid-template-columns: 224px minmax(0, 1fr); max-width: 1110px; gap: 38px; } .page-outline { display: none; } }
+@media (max-width: 960px) {
+  .site-header { padding: 0 22px; height: 70px; }
+  .site-layout { display: block; padding: 0 24px; max-width: 780px; }
+  .nav-shell { position: static; height: auto; overflow: visible; padding: 0; border-bottom: 1px solid var(--rule); }
+  .nav-shell > summary { display: list-item; font-size: 14px; padding: 15px 0; cursor: pointer; }
+  .nav-shell nav { padding: 10px 0 20px; }
+  main { padding-top: 30px; }
+  h1 { max-width: none; }
+}
+@media (max-width: 520px) {
+  :root { font-size: 16px; }
+  .site-header { padding: 0 16px; gap: 16px; }
+  .brand { gap: 8px; font-size: 24px; }
+  .brand img, .brand svg { width: 28px; }
+  .brand-guide { display: none; }
+  .search-box { width: 49vw; }
+  .search-box input { font-size: 12px; }
+  .site-layout { padding: 0 18px; }
+  h2 { font-size: 25px; }
+  pre { padding: 15px; font-size: 12px; }
+  .preview-controls { flex-wrap: wrap; }
+  .slide-example > figcaption { flex-wrap: wrap; gap: 3px; }
+  .article-footer span { display: none; }
+}
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { scroll-behavior: auto !important; } }
+@media print { .site-header, .nav-shell, .page-outline, .page-navigation, .code-example button, .preview-controls { display: none; } .site-layout { display: block; padding: 0; } main { padding: 0; } pre { white-space: pre-wrap; } pre code { white-space: pre-wrap; } a { color: inherit; } }
+
+.nav-project { margin-top: 24px; padding-top: 20px; border-top: 1px solid var(--rule); }
+.article-footer { display: flex; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+.footer-links { display: flex; gap: 14px; }
+.footer-links a { color: var(--secondary); text-decoration: none; }
+.footer-links a:hover { color: var(--blue); }
+
+/* Tabs for the theme contact sheets */
+.theme-sheets { margin: 20px 0 32px; }
+.theme-tabs { display: flex; flex-wrap: wrap; gap: 4px; border-bottom: 1px solid var(--rule); margin-bottom: 16px; }
+.theme-tabs [role="tab"] { font: inherit; font-size: 15px; color: var(--secondary); background: none; border: 0; border-bottom: 3px solid transparent; padding: 8px 14px; margin-bottom: -1px; cursor: pointer; }
+.theme-tabs [role="tab"]:hover { color: var(--ink); }
+.theme-tabs [role="tab"][aria-selected="true"] { color: var(--blue); border-bottom-color: var(--blue); font-weight: 600; }
+.theme-tabs [role="tab"]:focus-visible { outline: 2px solid var(--blue); outline-offset: 2px; border-radius: 4px; }
+.theme-sheet a { margin: 0; }

package/docs/site/assets/site.js

@@ -0,0 +1,123 @@
+const search = document.querySelector('#search')
+const results = document.querySelector('#search-results')
+const status = document.querySelector('#search-status')
+let searchIndex
+let searchVersion = 0
+
+async function runSearch() {
+  const version = ++searchVersion
+  const query = search.value.trim().toLowerCase()
+  results.replaceChildren()
+  results.hidden = !query
+  search.setAttribute('aria-expanded', String(!!query))
+  if (!query) { status.textContent = ''; return }
+  try {
+    searchIndex ??= fetch('search.json').then(response => { if (!response.ok) throw new Error(); return response.json() })
+    const index = await searchIndex
+    if (version !== searchVersion) return
+    const words = query.split(/\s+/)
+    const matches = index.map(page => {
+      const title = page.title.toLowerCase(), description = page.description.toLowerCase(), text = page.text.toLowerCase()
+      return { ...page, score: words.every(word => `${title} ${description} ${text}`.includes(word)) ? words.reduce((score, word) => score + (title.includes(word) ? 10 : description.includes(word) ? 4 : 1), 0) : 0 }
+    }).filter(page => page.score > 0).sort((a, b) => b.score - a.score).slice(0, 8)
+    status.textContent = `${matches.length} guides found.`
+    if (!matches.length) {
+      const message = document.createElement('p')
+      message.textContent = 'No guides found. Try “picture”, “notes”, or “share”.'
+      results.append(message)
+    }
+    for (const page of matches) {
+      const link = document.createElement('a'), title = document.createElement('strong'), description = document.createElement('span')
+      link.href = page.href
+      title.textContent = page.title
+      description.textContent = page.description
+      link.append(title, description)
+      results.append(link)
+    }
+  } catch {
+    searchIndex = undefined
+    const message = document.createElement('p')
+    message.textContent = 'Search could not load. Use the guide menu, or open these pages with mdeck docs.'
+    results.append(message)
+  }
+}
+search.addEventListener('input', runSearch)
+search.addEventListener('focus', () => { if (search.value.trim()) runSearch() })
+search.addEventListener('keydown', event => {
+  if (event.key === 'ArrowDown') { event.preventDefault(); results.querySelector('a')?.focus() }
+  if (event.key === 'Enter' && results.querySelector('a')) results.querySelector('a').click()
+})
+document.addEventListener('keydown', event => {
+  if (event.key === '/' && !event.target.closest('input, textarea, select, [contenteditable]') && !event.metaKey && !event.ctrlKey) { event.preventDefault(); search.focus() }
+  if (event.key === 'Escape') { results.hidden = true; search.setAttribute('aria-expanded', 'false'); if (results.contains(document.activeElement)) search.focus() }
+})
+document.addEventListener('click', event => { if (!event.target.closest('.search-box')) { results.hidden = true; search.setAttribute('aria-expanded', 'false') } })
+
+const navigation = document.querySelector('.nav-shell')
+const mobile = matchMedia('(max-width: 960px)')
+function adaptNavigation() { navigation.open = !mobile.matches }
+adaptNavigation()
+mobile.addEventListener('change', adaptNavigation)
+
+for (const button of document.querySelectorAll('[data-copy]')) {
+  button.addEventListener('click', async () => {
+    const code = button.closest('figure').querySelector('code')
+    try {
+      await navigator.clipboard.writeText(code.textContent)
+      button.textContent = 'Copied'
+    } catch {
+      const range = document.createRange()
+      range.selectNodeContents(code)
+      const selection = window.getSelection()
+      selection.removeAllRanges()
+      selection.addRange(range)
+      button.textContent = 'Selected — copy now'
+    }
+    setTimeout(() => { button.textContent = 'Copy' }, 2500)
+  })
+}
+
+for (const example of document.querySelectorAll('[data-preview]')) {
+  const frame = example.querySelector('iframe')
+  const output = example.querySelector('output')
+  let index = 0
+  for (const button of example.querySelectorAll('[data-control]')) {
+    button.addEventListener('click', () => frame.contentWindow.postMessage({ deckControl: { command: button.dataset.control } }, location.origin))
+  }
+  example.querySelector('select').addEventListener('change', event => {
+    const url = new URL(frame.src)
+    url.searchParams.set('theme', event.target.value)
+    url.hash = String(index + 1)
+    frame.src = url.toString()
+  })
+  window.addEventListener('message', event => {
+    if (event.source !== frame.contentWindow || event.origin !== location.origin || !event.data?.deckStateChanged) return
+    index = event.data.deckStateChanged.index
+    output.textContent = `Slide ${index + 1}`
+  })
+}
+
+// Tabs: one panel at a time; without the script every panel shows.
+for (const group of document.querySelectorAll('[data-tabs]')) {
+  const tabs = [...group.querySelectorAll('[role="tab"]')]
+  const select = tab => {
+    for (const other of tabs) {
+      const selected = other === tab
+      other.setAttribute('aria-selected', String(selected))
+      other.tabIndex = selected ? 0 : -1
+      document.getElementById(other.getAttribute('aria-controls')).hidden = !selected
+    }
+  }
+  tabs.forEach(tab => tab.addEventListener('click', () => select(tab)))
+  group.querySelector('[role="tablist"]').addEventListener('keydown', event => {
+    const step = { ArrowRight: 1, ArrowLeft: -1 }[event.key]
+    const index = tabs.indexOf(document.activeElement)
+    if (index < 0) return
+    const next = step ? tabs[(index + step + tabs.length) % tabs.length] : event.key === 'Home' ? tabs[0] : event.key === 'End' ? tabs.at(-1) : null
+    if (!next) return
+    event.preventDefault()
+    select(next)
+    next.focus()
+  })
+  select(tabs.find(tab => tab.getAttribute('aria-selected') === 'true') ?? tabs[0])
+}