@humanforest/slidev-theme 0.1.0

package/styles/index.ts

@@ -0,0 +1,71 @@
+// Theme style entry — Slidev auto-loads styles/index.ts.
+// Order matters: fonts + token ramps first (they only declare CSS custom properties
+// and @font-face), then base.css maps those tokens onto the deck's semantic roles.
+
+// Brand fonts (@font-face: MohrAlt, GT Haptik, JetBrains Mono), fetched from the CDN.
+//
+// ⚠⚠ THE CDN BUILD, AND THAT IS A LICENCE DECISION RATHER THAN A DELIVERY ONE. The sibling
+// `forest-fonts.css` points at `./files/*.woff2`, which Vite emits into whatever imports it — a
+// built deck then SHIPS the binaries, and every copy of that deck is another place the faces are
+// distributed from. Mohr and GT Haptik are licensed to Forest, not to whoever a deck is sent to.
+// The CDN build names `https://assets.forest.bike/fonts/*` instead, so a deck references the faces
+// and never carries them. This is also the only build the fonts package publishes (`files` +
+// `exports` in its package.json list the CDN css alone), which is why this is a bare specifier now
+// rather than a reach across the workspace.
+//
+// The trade, stated: a deck no longer renders in its own typeface offline, and it depends on that
+// host answering. Verified — the host sends `access-control-allow-origin: *` with `vary: Origin`,
+// which a cross-origin font fetch requires and fails SILENTLY without.
+import '@humanforest/fonts/forest-fonts.cdn.css'
+
+// Engine colour ramps (--forest-*, --neutral-*, …) — single source of truth.
+import '@humanforest/tokens/scales/ramps.css'
+// Typography role bundles (--type-*) + .type-* utility classes.
+import '@humanforest/tokens/type/type.css'
+// The deck type context (--type-deck-*): canonical roles remapped to the top of the ramp.
+import '@humanforest/tokens/type/type.deck.css'
+// The motion ladder (--motion-*) and the system-wide reduced-motion floor. The deck used to restate
+// these by hand, because they lived in @humanforest/ui's forest.css and pulling that drags the whole
+// Nuxt UI preset in. They are engine tokens now, and motion.css is deliberately framework-agnostic —
+// no @theme, no @utility — so UnoCSS eats it exactly as Tailwind does. The Tailwind-only companion
+// (motion.theme.css) is the one file a deck must NOT import: it re-points Tailwind's own
+// --default-transition-* and means nothing here.
+import '@humanforest/tokens/motion/motion.css'
+// Data-viz palette (--dataviz-*) so charts inherit the same colours.
+import '@humanforest/tokens/dataviz/dataviz.css'
+// The deck SURFACE: colour roles, the radius contract, the spacing scale, the derived surface ladder
+// and the dark mapping. Generated by scripts/deck.ts, so the deck's brand decisions are versioned and
+// reviewable alongside every other token — they used to live in this package, which is gitignored.
+// Framework-agnostic by construction: not one Tailwind at-rule, so UnoCSS reads it unchanged.
+import '@humanforest/tokens/deck/deck.css'
+
+// What is left of this package's own CSS, in two halves. tokens.css holds only the SLIDEV bridges —
+// the font-family names the engine's type.css expects, and Slidev's --slidev-* vars re-pointed at
+// Forest roles. base.css styles slide elements using nothing but engine tokens. Keeping them apart is
+// what makes the guardrail checkable: a literal colour or corner in base.css is visible as a rule
+// that skipped the token layer.
+import './tokens.css'
+import './base.css'
+
+// ── THE OBLIQUE IS NOT FETCHED FOR FREE, and that is a measured difference from the other faces ──
+//
+// Every slide's own h1 and body text make the browser request MohrAlt and GT Haptik Regular/Bold as
+// part of ordinary layout, so those are on the wire immediately. The oblique is requested only when
+// the first italic glyph is actually painted — so on a deck where one slide uses <em>, it lands
+// after everything else has settled and that line reflows in front of the audience.
+//
+// MEASURED, by scripts/deckAudit.ts, on the first deck in this repo ever to use italic:
+// `em → dx 0 dy -2 dh 4` — the element moved 2px up and grew 4px after the swap. That is precisely
+// the category deckAudit's own setup() comment describes for JetBrains Mono ("only slides with a
+// <code>/<pre> actually render it, so on every OTHER slide nothing on the page ever asks the browser
+// to fetch it"), and it takes the same fix: ask for the face explicitly instead of waiting for a
+// glyph to ask on your behalf.
+//
+// Fired, never awaited — this must not block first paint. Guarded for `slidev build`'s SSR pass,
+// where there is no document. Mohr-BlackIt is deliberately NOT here: it is a separate family the
+// deck never sets, so requesting it would cost a round trip for a face no slide can render.
+if (typeof document !== 'undefined' && document.fonts) {
+  for (const face of ['italic 400 1em "GT Haptik"', 'italic 700 1em "GT Haptik"']) {
+    document.fonts.load(face).catch(() => {})
+  }
+}

package/styles/tokens.css

@@ -0,0 +1,144 @@
+/* ───────────────────────────────────────────────────────────────────────────
+   Forest deck theme — the SLIDEV-SPECIFIC half of the token layer.
+
+   The deck's own identity — colour roles, the radius contract, the spacing scale, the derived
+   surface ladder, the dark mapping, the chart series — is NOT here any more. It lives in the
+   engine, generated by scripts/deck.ts into @humanforest/tokens/deck/deck.css, and styles/index.ts
+   imports it. That move is the point: mobile and marketing declare their voice in tracked, tested
+   files under packages/ui/src/contexts/, while this package is gitignored and out-of-workspace, so
+   every brand decision made here was unversioned and unreviewable.
+
+   What is left is the two things that are genuinely about SLIDEV rather than about Forest:
+
+   1. The font-family bridge. --font-display/sans/mono normally come from @humanforest/ui's
+      forest.css, which the deck cannot pull (it carries the whole Nuxt UI preset). The engine's
+      type.css references these names, so something has to declare them.
+   2. Slidev's own --slidev-* vars, re-pointed at Forest roles. Left alone they leak a teal primary,
+      a stock grey code block and a black letterbox through an otherwise on-brand deck.
+
+   Both are bridges to a specific tool. Neither is a brand decision, which is why neither followed
+   the roles into the engine.
+   ─────────────────────────────────────────────────────────────────────────── */
+
+:root {
+  /* ── Font bridge — resolves type.css's var(--font-display) etc. ─────────────────────────── */
+  --font-display: 'MohrAlt', 'Mohr-BlackIt', system-ui, sans-serif;
+  --font-display-italic: 'Mohr-BlackIt', 'MohrAlt', system-ui, sans-serif;
+  --font-sans: 'GT Haptik', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+
+  /* ── Slidev's own vars, re-pointed ───────────────────────────────────────────────────────
+     Slide-to-slide travel: Slidev ships 0.5s with `ease`, which is off the motion ladder in both
+     halves. `slow` is the bucket for large travel and keeps the deck on the snappy end.
+
+     The deck's own transition is `view-transition`, which does NOT read this — the API runs its
+     animations on pseudo-elements and base.css puts them on the same ladder. This still governs
+     any slide that opts back into a Vue transition with its own `transition:` frontmatter. */
+  --slidev-transition-duration: var(--motion-slow);
+
+  --slidev-theme-primary: var(--deck-accent);
+
+  /* The letterbox behind the 16∶9 canvas. Slidev ships black, which frames a light slide like a
+     cinema screen; a deep neutral recedes instead and lets the paper ground read as paper. */
+  --slidev-slide-container-background: var(--neutral-900);
+
+  /* ★ 24px — three steps of the base radius, between the nested step (16) and the slide card (48).
+     The item step (8px) is for code CHIPS, tags and swatches; on a block the size of half a slide
+     it reads as a square with the corners filed off, and the nested step is still tighter than the
+     block wants.
+
+     ⚠ AND IT IS THIS TOKEN THAT RENDERS, not the `border-radius` base.css sets on `pre`. Slidev's own
+     `.slidev-code` carries `border-radius: var(--slidev-code-radius) !important`, so the rule in
+     base.css loses and the value here is the one that reaches the corner. */
+  --slidev-code-radius: calc(var(--deck-radius) * 3);
+  --slidev-code-font-family: var(--font-mono);
+  /* ★ ONE STEP UP THE LADDER FROM THE OLD 24. A block set at 36px wants more air than a paragraph
+     does, and this token is read TWICE — Slidev pads the block with it and base.css sizes each line
+     to overhang by it, so the lit band still reaches both padding edges at the new value. */
+  --slidev-code-padding: var(--deck-space-4);
+  --slidev-code-font-size: var(--type-deck-body-sm-size);
+  --slidev-code-line-height: var(--type-deck-body-sm-line-height);
+  /* A code-group tab is furniture naming a file, so it takes the OVERLINE rung the running chrome's
+     own pills use. Slidev ships 12px — a desk number on a 1920px canvas, where it lands at roughly
+     the width of a full stop from the back of a room. */
+  --slidev-code-tab-font-size: var(--type-deck-overline-size);
+}
+
+/* ★★ MEASURED, task-8-brief.md CONTROLLER ADDENDUM 2's rendered-contrast sweep — --slidev-code-
+   background/-foreground are the one pair here that reference DARK-AWARE roles (--deck-surface,
+   --deck-fg), so they need the SAME "declared on every mode boundary, not just :root" fix
+   deck.css's own derived roles (--deck-surface itself included) already carry, and — before this
+   fix — did not have.
+
+   Root cause, confirmed live: @slidev/client/styles/code.css ships its OWN inline-code rule,
+   `.slidev-layout :not(pre) > code { background: var(--slidev-code-background); }`, which OUTRANKS
+   base.css's `.slidev-layout code { background: var(--deck-accent-soft); }` outright — one more
+   class-shaped pseudo-selector than base.css's rule, (0,2,1) against (0,1,1) — regardless of
+   either rule's position in the cascade. So Slidev's own rule is what a `<code>` element actually
+   paints with, not base.css's. That makes --slidev-code-background load-bearing for every inline
+   code span in the deck, not a background hook nobody actually reaches — and with it declared only
+   at :root, a `class: deck-dark` slide's `<code>` background/foreground stayed frozen at :root's
+   OWN (light) --deck-surface/--deck-fg forever, because a custom property resolves ITS OWN var()
+   reference once, where IT is declared, not again at each point of use. Measured on
+   apps/deck-template's own "Charts inherit the palette" demo slide: a `<code>` pill rendered pale
+   cream-on-near-white-text — text #3bd996 (dark register's --deck-accent) on a background frozen at
+   #f1ede6 (LIGHT --deck-surface) — 1.56:1, on a DARK slide, invisible to a geometry-only audit and
+   to a unit-level gate that only ever checks token PAIRS in isolation, never what Slidev's own CSS
+   actually resolves them against. */
+:root,
+.dark,
+.deck-dark {
+  /*
+    ★★ THE BLOCK'S GROUND IS CATPPUCCIN'S OWN BASE, NOT --deck-surface.
+
+    It was the derived surface — deck-bg mixed 5% toward the ink — which is right for a surface OF
+    the deck and wrong for this one: the palette on top of it is Catppuccin's, and Catppuccin's
+    colours are designed against Catppuccin's ground. On the dark register the derived surface is
+    forest-950 lifted, so the block was the PAGE's green showing through, under a violet-lavender
+    palette. Jose: "why are you using that shade of green for the bg?"
+
+    The hexes are latte `base` and mocha `base`, and they are restated here only because a Shiki
+    theme registration cannot be read from CSS. codeTheme.static.test.ts pins both against
+    CATPPUCCIN[register].base so the two copies cannot drift.
+
+    Measured: every mocha ink gains on its own base (9.50 -> 11.34, 6.17 -> 7.37, 6.76 -> 8.07,
+    9.24 -> 11.03, 7.76 -> 9.27), and latte needs the same three lifts either way.
+
+    ⚠ INLINE code is deliberately NOT this — see base.css. A `code` chip in a sentence is deck
+    furniture, and a Catppuccin-blue chip mid-paragraph reads as a bug.
+  */
+  --slidev-code-background: var(--deck-surface);
+  /* The block's EDGE and its lit-line MARKER, from the same palette as its ground — see the note
+     above AYU in components/codeTheme.ts. There is no marker token: the lit-line bar is the deck's
+     own --deck-accent, and the band is the ground mixed toward its own ink, so neither is a colour
+     this file has to hold. */
+  /* ★ THE EDGE IS DERIVED FROM THE GROUND, in ONE declaration for both registers: mixing toward
+     --deck-fg means it darkens on light and lightens on dark on its own, exactly as --deck-border
+     does against the page. Nothing to keep in sync when the well moves. */
+  --deck-code-border: color-mix(in oklab, var(--slidev-code-background), var(--deck-fg) 9%);
+  --slidev-code-foreground: var(--deck-fg);
+
+  /* The code-group tab strip, same three-selector treatment and for the identical reason: Slidev
+     declares these at `:root` and `.dark` only (its own styles/vars.css), so on a `class: deck-dark`
+     slide the tabs kept the LIGHT #67676c/#3c3c43 pair over a dark strip. Two of the three are
+     text colours, so this is the tokens.css trap above repeated on a second surface. */
+  --slidev-code-tab-divider: var(--deck-border);
+  --slidev-code-tab-text-color: var(--deck-fg-muted);
+  --slidev-code-tab-active-text-color: var(--deck-fg);
+}
+
+/* The dark half of the pair above. Both registers of `.deck-dark` and the whole-deck `.dark`, for
+   the same reason every other role is bound to both. Mocha's base, unmodified. */
+.dark,
+.deck-dark {
+  --slidev-code-background: var(--neutral-900);
+}
+
+/* A dark slide paints its own ground. The ROLES for `.deck-dark` are declared in the engine's
+   deck.css; this is only the paint, because it is styling rather than a token. `.slidev-layout`
+   already reads --deck-bg, but the class can also land on a wrapper inside a slide (a dark card
+   band, a chart well), so it is said here rather than left to the layout rule. */
+.deck-dark {
+  background: var(--deck-bg);
+  color: var(--deck-fg);
+}

package/uno.config.ts

@@ -0,0 +1,231 @@
+/*
+  Slidev loads a uno.config.ts from every root it knows about — the deck's and the theme's —
+  and merges them, so this is where the theme adds what the brand owns to the utility layer.
+
+  One job right now: register the FOREST ICON SET. The design system owns its own icons (bikes,
+  traffic lights, parking, the mark) alongside the third-party sets, and without this a slide
+  that needs a bike has to reach for someone else's. The files are read straight from
+  packages/ui/icons/forest — the same source the product's addCollection() call uses, so a deck
+  icon and a product icon are the same artwork, not a redraw.
+
+  They are monotone (currentColor on fill and stroke), which puts presetIcons in mask mode, so
+  the icon takes its colour from the text around it:
+
+      <div class="i-forest-bike text-6xl" />
+*/
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig, presetIcons } from 'unocss'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const iconDir = resolve(here, '../ui/icons/forest')
+
+/* Read eagerly rather than through a loader: the set is 17 files, so the cost is nothing, and a
+   plain object means no dependency on @iconify/utils' filesystem loader — which is only present
+   here transitively, via UnoCSS. */
+const forest = Object.fromEntries(
+  readdirSync(iconDir)
+    .filter((f) => f.endsWith('.svg'))
+    .map((f) => [f.replace(/\.svg$/, ''), readFileSync(resolve(iconDir, f), 'utf-8')]),
+)
+
+/*
+  ⚠ The rename is load-bearing, not cosmetic.
+
+  Slidev's own config already installs presetIcons (for its `slidev` collection), and UnoCSS
+  de-duplicates presets BY NAME — `resolveConfig` runs
+  `uniqueBy(presets, (a, b) => a.name === b.name)`. A second preset called
+  "@unocss/preset-icons" is therefore dropped in silence, taking `collections: { forest }` with
+  it: no error, no warning, just no `i-forest-*` rules ever generated. Naming this one
+  differently is what keeps both alive.
+
+  `autoInstall: false` so an unknown `i-<something>-*` on a slide never tries to fetch an
+  Iconify package from the network mid-presentation; unknown names simply fall through to
+  Slidev's preset.
+*/
+const forestIcons = presetIcons({
+  collections: { forest },
+  autoInstall: false,
+  /*
+    `width`/`height` are NOT optional here. presetIcons forwards `extraProperties` into Iconify's
+    SVG customiser (`customizations.additionalProps`), and the forest SVGs carry their own
+    `width="24" height="24"`, so the generated rule came out with a mask and no box — every icon
+    rendered 0×0 with the CSS present and correct. Sizing them in `em` makes an icon scale with
+    the text tier it sits in, which is what `text-6xl` on the element is meant to do.
+
+    display/vertical-align: icons sit beside 36–48px body copy and are read at distance, so they
+    align to the middle of the text box rather than UnoCSS's default baseline nudge.
+  */
+  extraProperties: {
+    width: '1em',
+    height: '1em',
+    display: 'inline-block',
+    'vertical-align': 'middle',
+  },
+})
+forestIcons.name = 'forest-icons'
+
+/*
+  Second job: register LUCIDE, alongside forest rather than in place of it — Jose's own direction
+  ("icons should come from lucide or from our own icon library") plus the concrete gap it closes:
+  a `checklist` preset was reworded away from a check icon on the false premise the design system
+  has no tick. It does — in Lucide, not Forest. `<IconTile>` (components/IconTile.vue) draws its
+  own icons via a CSS mask built from a handful of pre-extracted local .svg files, never through
+  this preset's `i-lucide-*` classes — that file's own doc comment explains why (the exact same
+  "a class assembled from a runtime prop is invisible to UnoCSS's static scanner" trap this file's
+  own comment above already documents for forest). So this registration exists for its OWN sake,
+  independent of IconTile: any deck author (or a future component) can drop a raw
+  `i-lucide-<name>` class straight onto an element, no wrapper required, and it works precisely
+  because THAT class is a literal string UnoCSS's scanner can actually see.
+
+  `@iconify-json/lucide/icons.json` is 543 KB — collections here are ALWAYS resolved in Node, at
+  config-eval / build time, never shipped to a deck's own bundle (see this file's own comment on
+  `forest` above: presetIcons only ever emits CSS for classes actually found in scanned source).
+  Loaded as a function, not the eager `readFileSync` forest gets, specifically so nothing forces
+  it to resolve at all unless some `i-lucide-*` class is actually found — the standard UnoCSS
+  recipe for a collection too big to read eagerly. `packages/slidev-theme/test/uno.static.test.ts`
+  proves this registration actually produces a rule (and that an UNREFERENCED name — the
+  `zodiac-virgo` canary — never does), rather than trusting the de-dup trap stayed closed.
+*/
+const lucideIcons = presetIcons({
+  collections: {
+    lucide: () => import('@iconify-json/lucide/icons.json').then((m) => m.default),
+  },
+  autoInstall: false,
+  extraProperties: {
+    width: '1em',
+    height: '1em',
+    display: 'inline-block',
+    'vertical-align': 'middle',
+  },
+})
+lucideIcons.name = 'lucide-icons'
+
+
+/*
+  THE DECK'S OWN SPACING, AS UTILITIES.
+
+  Slidev ships presetWind3, and the deck runs it — the theme patched @slidev/client onto presetWind4
+  for a while and the patch is gone, because measuring both showed the deck renders identically
+  either way and a patched dependency cannot travel to anyone who installs this theme from npm.
+  So a deck gets Tailwind v3's vocabulary on the default 4px
+  scale. Most of this system's ladder LANDS on that scale by arithmetic — `p-10` is 40px, which is
+  --deck-space-5 — and that coincidence is exactly the problem: it is not the token. Retune
+  --deck-grid and every `p-10` in every deck silently means something else while every
+  `var(--deck-space-5)` follows. One of the ladder's own numbers does not even land: 90px is 22.5
+  steps, and presetWind3 does not generate `p-22.5` at all.
+
+  So the scale is registered by NAME, pointing at the generated custom properties rather than at
+  numbers. `p-deck-inset-text` compiles to `padding: var(--deck-inset-text)` — one source of truth, and a
+  utility that cannot drift from the token it is named after.
+
+  Values, not literals, for the same reason scripts/deck.ts emits them: the engine owns the numbers.
+*/
+const deckSpacing = Object.fromEntries([
+  /*
+    ★★ EVERY NAME CARRIES THE `deck-` PREFIX, and the rungs are the reason it started.
+
+    The preset's numeric scale reads the digit in `p-4` as Tailwind's own step — 1rem, 16px. This
+    system reads the digit in --deck-space-4 as a RUNG INDEX, so it is 32px. Same digit, half the
+    value. While the utility was `p-space-4` the two sat beside each other looking like a long and a
+    short spelling of one idea, and reaching for the wrong one halved the spacing with nothing to
+    notice.
+
+    The insets never had that problem — checked, not assumed: `inset-text` and `top-inset-text`
+    generate nothing on their own, and the preset's positional `inset-4` is untouched by registering
+    an `inset-text` SPACING key. They are prefixed anyway, because a vocabulary where some names say
+    whose they are and others do not is a vocabulary you have to remember rather than read. The cost
+    is length — `p-deck-inset-text` — and the gain is that every Forest utility is recognisable as
+    one on sight, and no future wind4 key can collide with any of them.
+
+    The prefix is on the UTILITY name only. The tokens keep their own names, and every value here
+    still points at one, so nothing is restated.
+  */
+  ...[1, 2, 3, 4, 5, 6, 7].map((n) => [`deck-${n}`, `var(--deck-space-${n})`]),
+  ['deck-grid', 'var(--deck-grid)'],
+  ['deck-inset-chrome', 'var(--deck-inset-chrome)'],
+  ['deck-inset-media', 'var(--deck-inset-media)'],
+  ['deck-inset-text', 'var(--deck-inset-text)'],
+  ['deck-inset-display', 'var(--deck-inset-display)'],
+]);
+
+export default defineConfig({
+  presets: [forestIcons, lucideIcons],
+  /*
+    THE CODE-GROUP TAB ICONS — the file-type marks on a ```::code-group``` tab strip.
+
+    @slidev/client's internals/TitleIcon.vue matches a tab title against a table of
+    `i-vscode-icons:file-type-*` names, so `[Panel.vue]` gets the mark an editor would show it with.
+    These are the one place a full-colour third-party icon is right rather than off-brand: a file
+    mark is shared developer furniture, read the way a file extension is. They are not part of the
+    deck's own icon vocabulary — forest and lucide are what a slide reaches for.
+
+    ★ SAFELISTED, BECAUSE NOTHING SCANS THE FILE THAT ASKS FOR THEM. TitleIcon.vue lives inside
+    node_modules/@slidev/client, outside UnoCSS's scan, and picks its class at RUNTIME — so without
+    these lines the tab resolves a class against CSS that was never generated and renders an empty
+    box beside the label. That is the whole fix: the COLLECTION needs no registration of its own,
+    because presetIcons resolves `@iconify-json/vscode-icons` out of node_modules once it is a
+    dependency (verified from both the theme's directory and a deck's, with and without an explicit
+    `collections:` entry — it resolves either way, so the entry was deleted rather than kept as
+    decoration).
+
+    Listed by hand rather than imported from Slidev's table: a safelist is a promise about the built
+    stylesheet and should read as one. These are the extensions a Forest deck writes a tab for; a
+    new one is one line, and uno.static.test.ts proves each still resolves, so a name that moves
+    upstream fails here rather than on a slide.
+  */
+  safelist: [
+    'i-vscode-icons:file-type-vue',
+    'i-vscode-icons:file-type-typescript',
+    'i-vscode-icons:file-type-js',
+    'i-vscode-icons:file-type-json',
+    'i-vscode-icons:file-type-markdown',
+    'i-vscode-icons:file-type-python',
+    'i-vscode-icons:file-type-html',
+    'i-vscode-icons:file-type-css',
+    'i-vscode-icons:file-type-light-yaml',
+    'i-vscode-icons:file-type-node',
+    'i-vscode-icons:file-type-bun',
+    /* ★★ THESE THREE ARE REQUESTED BY A TITLE MARKER, NOT BY SLIDEV'S OWN LOOKUP. Slidev's
+       TitleIcon.vue matches an extension against a closed `builtinIcons` map and renders
+       `<div v-if="matchIcon(title)">`; go, sql and shell are not on that map, so it emits no element
+       at all and a safelist entry alone would never be asked for. The generator appends a `~…~` icon
+       marker to those tabs (see TAB_ICONS in scripts/deckSpecimen.ts), which is the hook matchIcon
+       consults first — that is what makes these three reachable. */
+    'i-vscode-icons:file-type-go',
+    'i-vscode-icons:file-type-sql',
+    'i-vscode-icons:file-type-shell',
+  ],
+  /*
+    `spacing` feeds p/m/gap/space/inset utilities alike, so one table covers `p-deck-inset-text`,
+    `gap-deck-5`, `mt-deck-3` and the rest without a rule per property.
+  */
+  theme: {
+    spacing: deckSpacing,
+    /*
+      ★★ WIND4 EMITS `--font-sans` AND `--font-mono` ITSELF, and that is a collision with this
+      design system rather than a coincidence — Tailwind v4 exposes its theme AS custom properties,
+      and those two names are already ours (styles/tokens.css declares them on :root, pointing at
+      GT Haptik and JetBrains Mono). wind4's preflight declares them again at the same specificity
+      and wins on order, so every type role that resolves through `var(--font-sans)` fell back to
+      `ui-sans-serif, system-ui, …`.
+
+      MEASURED after the preset swap: GT Haptik was LOADED — `document.fonts` said so — and no text
+      on the deck was set in it, because `--type-deck-body-family` had quietly become the browser's
+      own stack.
+
+      Slidev's own wiring does not save it: setups/unocss.ts assigns `config.theme.fontFamily.sans`,
+      which is wind3's shape. wind4 reads `theme.font`, so that assignment silently does nothing.
+
+      Declaring them here means the value wind4 emits IS the deck's, so there is one declaration
+      rather than two fighting. Literals rather than `var(--font-sans)`, which would be circular —
+      wind4 would emit `--font-sans: var(--font-sans)`. Pinned to tokens.css by
+      packages/slidev-theme/test/uno.static.test.ts.
+    */
+    font: {
+      sans: "'GT Haptik', system-ui, sans-serif",
+      mono: "'JetBrains Mono', ui-monospace, monospace",
+    },
+  },
+})

package/useNotchCuts.js

@@ -0,0 +1,200 @@
+// Measure whatever running chrome is sitting on a panel, and return the clip-path that seats it.
+//
+// WHY MEASURED, WHEN THE FIRST NOTCH WAS DECLARED. The original cut was sized from a token because
+// its one occupant — the Forest mark — is 72px and always has been. Everything added since has a
+// size that CSS cannot know:
+//
+//   · the section pill's width is a section NAME;
+//   · the page marker is a stadium that grows with the digit count;
+//   · the confidentiality pill's width is an author's own string.
+//
+// A token cannot state any of those, and hard-coding a generous cut for the worst case would draw a
+// hole far larger than the thing it holds. So the panel asks the DOM what is actually on it.
+//
+// THE COST, stated plainly: a measured cut cannot be correct on the FIRST frame, and the earlier
+// declared-not-measured note in notch.js was right that this matters. It is mitigated rather than
+// solved — styles/base.css still carries the single-notch clip-path for the mark, so the first
+// painted frame is the old, correct-for-the-common-case shape, and this refines it on mount. A
+// slide changing shape one frame in is a smaller defect than a cut that never fits its occupant.
+//
+// WHAT IT DOES NOT DO: reflow. Clipping removes paint, not space — a panel's own content still has
+// to keep out of its corners, which is what the layouts' own padding is for.
+import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import { notchPath, occupantFor } from './notchPath.js';
+
+/**
+ * Every chrome element that can land on a panel. Queried by class from the slide root rather than
+ * passed in, because chrome is a SIBLING of the layout (SlideWrapper mounts both), so there is no
+ * component boundary to hand them across and no shared ancestor to provide through.
+ *
+ * The page marker and the confidentiality pill are addressed by their own wrappers rather than by
+ * `.badge-strip-item`, so a future strip of tags somewhere else on the slide cannot be mistaken for
+ * running chrome and start cutting holes in panels.
+ */
+const CHROME_SELECTORS = [
+  '.deck-chrome-mark',
+  '.deck-chrome-pills .badge-strip-item',
+  '.deck-page-dot',
+  /*
+    ⚠ `.deck-confidential-pill`, NOT `.badge-strip-item`, AND IT WAS THE WRONG ONE FOR A WHILE. The
+    marking used to be `BadgeStrip variant="outline"`; ConfidentialMark.vue records the split that
+    ended that, and this selector was not moved with it. It kept matching nothing — measured on the
+    specimen's own marking slide, 0 hits for the old selector and 1 for this one — so the notch was
+    blind to the one piece of chrome a cover, a split panel or a stack band can still be carrying.
+
+    ★ classRefs.static.test.ts could not catch it. That gate asks whether every hardcoded class is
+    one the theme EMITS, and `.badge-strip-item` is emitted — by BadgeStrip, elsewhere. A compound
+    selector whose two halves are both real and never co-occur is invisible to it.
+  */
+  '.deck-chrome-confidential .deck-confidential-pill',
+];
+
+/**
+ * An occupant's OWN corner radius, so the cut around it can be concentric.
+ *
+ * Read from the element rather than passed in: the mark is a squircle whose corner is 21.87% of its
+ * size, a pill is a stadium, and a future occupant will be something else again. `--deck-radius-full`
+ * resolves to 9999px, which is not a radius so much as "as round as this box gets" — for a stadium
+ * that is half its height, and using the literal would ask for a cut radius of ~10,000px.
+ */
+const ownRadius = (el) => {
+  const r = parseFloat(getComputedStyle(el).borderTopLeftRadius) || 0;
+  const half = Math.min(el.offsetWidth, el.offsetHeight) / 2;
+  return Math.min(r, half);
+};
+
+/**
+ * The ring and the card radius are READ FROM THE PANEL'S OWN COMPUTED STYLE rather than passed in.
+ * They are already tokens (--deck-notch-gap, --deck-radius-card) that the panel resolves anyway, and
+ * a caller restating them in JS is how two sources of one number start to disagree.
+ *
+ * @param {import('vue').Ref<HTMLElement|null>} panelRef the element to cut
+ * @param {object} opts
+ * @param {() => boolean} opts.enabled whether this slide wants a cut at all (chrome, notch, media)
+ * @param {string[]} [opts.occupants] EXTRA selectors to seat, beyond the running chrome. A cover
+ *   carries no chrome at all — that is the point of it — and still has something in a corner: its
+ *   own lockup. Passing the selector in keeps ONE implementation of the cut rather than a second
+ *   one in the layout, which is what a first attempt at this did, reproducing both of the bugs
+ *   documented inside `measure()` (screen-vs-CSS pixels, and parseFloat of a `calc()` custom
+ *   property) within twenty lines of the notes that record them.
+ * @returns {{ clip: import('vue').Ref<string>, remeasure: () => void }} a `path(...)` value, or ''
+ *   before the first measurement — which is when styles/base.css's own single-notch rule applies.
+ */
+export const useNotchCuts = (panelRef, opts) => {
+  const clip = ref('');
+  let ro = null;
+  let raf = 0;
+
+  const measure = () => {
+    const panel = panelRef.value;
+    if (!panel) return;
+    if (!opts.enabled()) { clip.value = ''; return; }
+
+    const slide = panel.closest('.slidev-page') ?? panel.ownerDocument;
+    const rect = panel.getBoundingClientRect();
+    if (!(rect.width > 0) || !(rect.height > 0)) return;
+
+    /*
+      ★★ EVERYTHING IS CONVERTED TO CSS PIXELS FIRST, and this is not a nicety.
+
+      A slide is a transform-scaled box, so getBoundingClientRect() returns SCREEN pixels while
+      offsetWidth, the tokens and the path all speak CSS pixels. Mixing them is silent: the first
+      version added a 24px CSS ring to a screen-pixel measurement and drew a cut 76.8 wide around an
+      occupant whose edge was at 70.4 — a 6.4px gap where the deck declares 24. It looked plausible,
+      because everything was still roughly notch-shaped. Reported by eye as a lost margin.
+    */
+    const scale = panel.offsetWidth / rect.width;
+    const toCss = (r) => ({
+      left: (r.left - rect.left) * scale,
+      top: (r.top - rect.top) * scale,
+      right: (r.right - rect.left) * scale,
+      bottom: (r.bottom - rect.top) * scale,
+      width: r.width * scale,
+      height: r.height * scale,
+    });
+    // The panel in its own CSS-pixel space, which is the frame the path is written in.
+    const panelBox = { left: 0, top: 0, right: panel.offsetWidth, bottom: panel.offsetHeight,
+                       width: panel.offsetWidth, height: panel.offsetHeight };
+
+    /*
+      ★ RESOLVE, don't parse. getComputedStyle().getPropertyValue() returns a custom property's RAW
+      DECLARED TEXT, not its computed value — `--deck-notch-gap` reads back as the literal string
+      "calc(40px * 0.6)", and parseFloat() of that is NaN. The first version of this fell straight
+      through to its own hard-coded fallback and looked correct only because the fallback happened to
+      equal the token. Measured: ring came back null, and the cut was drawn from a number this file
+      invented rather than the one the deck declares.
+
+      A throwaway element is the only way to make the browser evaluate the expression: give it the
+      var as a width and read the width back.
+    */
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:absolute;visibility:hidden;pointer-events:none';
+    panel.appendChild(probe);
+    /*
+      ⚠ `>= 0`, NOT `> 0`. Zero is a REAL value for both of these and the strict test threw it away:
+      a flush picture set sets `--deck-radius-card: 0px` so its inner corners meet square, the probe
+      resolved 0, the guard read that as "unset" and the cut was drawn with the hard-coded 48 —
+      putting a rounded bite back in the middle of a set whose whole point is that it has no seam.
+      An UNSET var is what the fallback is for, and an unset var gives `auto`, hence NaN.
+    */
+    const px = (name, fallback) => {
+      probe.style.width = `var(${name})`;
+      const v = parseFloat(getComputedStyle(probe).width);
+      return Number.isFinite(v) && v >= 0 ? v : fallback;
+    };
+    const ring = px('--deck-notch-gap', 24);
+    const notches = {};
+    for (const sel of [...CHROME_SELECTORS, ...(opts.occupants ?? [])]) {
+      for (const el of slide.querySelectorAll(sel)) {
+        const cut = occupantFor(toCss(el.getBoundingClientRect()), panelBox, ring);
+        if (!cut) continue;
+        const r = ownRadius(el) + ring;
+        // Two occupants in one corner (the mark and a companion are one box, but a pill row need not
+        // be) take the UNION: the deeper cut wins on each axis, and the larger radius with it, so
+        // neither is left sitting on the panel.
+        const prev = notches[cut.corner];
+        notches[cut.corner] = prev
+          ? { w: Math.max(prev.w, cut.w), h: Math.max(prev.h, cut.h), r: Math.max(prev.r, r) }
+          : { w: cut.w, h: cut.h, r };
+      }
+    }
+
+    const cardRadius = px('--deck-radius-card', 48);
+    probe.remove();
+
+    const path = notchPath({
+      w: panel.offsetWidth,
+      h: panel.offsetHeight,
+      radius: cardRadius,
+      notches,
+    });
+    clip.value = `path('${path}')`;
+  };
+
+  // Coalesce to one measurement per frame. Chrome, panel and fonts all settle independently, and a
+  // ResizeObserver firing per element would rebuild the path several times for one change.
+  const schedule = () => {
+    if (raf) return;
+    raf = requestAnimationFrame(() => { raf = 0; measure(); });
+  };
+
+  onMounted(() => {
+    schedule();
+    // Fonts land after first paint and change every pill's width — without this the cut is sized to
+    // the fallback face's metrics and stays there.
+    if (typeof document !== 'undefined' && document.fonts?.ready) document.fonts.ready.then(schedule);
+    if (typeof ResizeObserver === 'undefined') return;
+    ro = new ResizeObserver(schedule);
+    const panel = panelRef.value;
+    if (panel) {
+      ro.observe(panel);
+      const slide = panel.closest('.slidev-page');
+      if (slide) for (const sel of CHROME_SELECTORS) for (const el of slide.querySelectorAll(sel)) ro.observe(el);
+    }
+  });
+
+  onBeforeUnmount(() => { ro?.disconnect(); if (raf) cancelAnimationFrame(raf); });
+  watch(() => opts.enabled(), schedule);
+
+  return { clip, remeasure: schedule };
+};