@humanforest/slidev-theme 0.1.0

package/setup/mermaid.ts

@@ -0,0 +1,30 @@
+// The FLOOR under setup/mermaid-renderer.ts, and it exists because of a failure that was invisible.
+//
+// The custom renderer is what gives this deck two registers (see that file for why a config alone
+// cannot). While it was being written it failed to load — `mermaid` was not resolvable from this
+// package, so Vite could not transform the module — and @slidev/client's own wiring is:
+//
+//     export default [Object.values(setup0)[0], …].filter(Boolean)
+//     …
+//     for (const setup of mermaidRenderers) { const renderer = await setup(); if (renderer) { … } }
+//     // fallback: existing mermaid
+//
+// A setup module that fails to load is filtered out and Slidev falls back. So the deck rendered
+// PERFECTLY WELL and completely unbranded: lavender nodes, 10px labels, no error in the console, no
+// warning in the terminal, nothing on the page to look at and doubt. It was found by fetching the
+// virtual setup module by hand and noticing the array had length 0.
+//
+// This file makes that failure mode land on Forest colours instead of mermaid's defaults. It cannot
+// give a dark slide the dark palette — a MermaidSetup is wrapped in `createSingletonPromise` and
+// resolved once, which is the whole reason the renderer exists — so a fallback render on a dark
+// slide would still be wrong. But it would be wrong in a way anyone can SEE, which the lavender
+// was not.
+//
+// The gate that catches the underlying cause is themeImports.static.test.ts: every import specifier
+// in this directory has to resolve from this package.
+import type { MermaidSetup } from '@slidev/types';
+import { mermaidConfig } from '../components/mermaidTheme';
+
+const setupMermaid: MermaidSetup = () => mermaidConfig('light');
+
+export default setupMermaid;

package/setup/shiki.ts

@@ -0,0 +1,44 @@
+// Slidev discovers a theme's Shiki config through `setup/shiki.<ts|js|mts|mjs>` (@slidev/cli's
+// node/virtual/setups.ts globs exactly that path across every root) and merges each root's return
+// value, deck last. Returning `themes` rather than `theme` puts Shiki into DUAL mode: every token
+// span carries `--shiki-light` and `--shiki-dark` and a stylesheet picks between them, which is the
+// only shape that can serve a deck whose register changes per SLIDE. See components/codeTheme.ts for
+// the palette and the measured reason the shipped default could not stay.
+//
+// ★ THIS FILE RUNS IN NODE AS WELL AS THE BROWSER. Slidev highlights magic-move steps at BUILD time
+// (`shiki.codeToTokens` inside the magic-move codeblock transformer), so a theme that could only be
+// assembled in front of a live document would produce un-highlighted animated code and nothing
+// would say why. components/deckPalette.ts is written to that constraint — pure token arithmetic,
+// no DOM.
+//
+// ★ LANGUAGES MUST BE NAMED. Shiki has every bundled grammar available as INPUT, but only the names
+// in `languageNames` are actually loaded in the browser (@slidev/client's setup/shiki-options.ts
+// seeds that set with markdown/vue/js/ts/html/css and nothing else). A ```sql fence with `sql`
+// unlisted renders as plain text — no error, no warning, just a code block with no colour in it.
+// So every language any Forest deck highlights is listed here, and codeTheme.static.test.ts checks
+// the specimen book's own fences against this list so a new language cannot ship un-highlighted.
+import { forestCodeThemes } from '../components/codeTheme';
+
+/** Every language a Forest deck may highlight. Alphabetical; `vue` is already seeded but restated
+ *  so the list reads as the complete answer to "what can a slide use". */
+export const DECK_LANGS = [
+  'bash',
+  'css',
+  'go',
+  'html',
+  'javascript',
+  'json',
+  'markdown',
+  'python',
+  'sql',
+  'typescript',
+  'vue',
+  'yaml',
+];
+
+export default function setupShiki() {
+  return {
+    themes: forestCodeThemes(),
+    langs: DECK_LANGS,
+  };
+}

package/setup/shortcuts.ts

@@ -0,0 +1,28 @@
+// task-14-brief.md, requirement 6 — the keyboard toggle for the layout-debug overlay ("would it
+// be possible if you add red lines for border in a way to debug it?"). Slidev discovers a theme's
+// own shortcuts through `setup/shortcuts.<ts|mts|js|mjs>` at the theme root (@slidev/cli's
+// node/virtual/setups.ts globs exactly that path across every root, theme included) and composes
+// each file's default export over Slidev's own built-in shortcut list — see
+// @slidev/client/setup/shortcuts.ts's own `for (const setup of setups)` loop.
+//
+// `key: 'l'` is a plain STRING, not a magicKeys ref — @slidev/client's own shortcut() function
+// (logic/shortcuts.ts) converts a string key through `magicKeys[key]` internally, so a setup file
+// never needs to import magicKeys itself to bind a single key. 'l' is free: Slidev's own defaults
+// use space/arrows/pageup/pagedown/d(ark)/g(oto)/o(verview)/`` ` ``/f(ullscreen) and nothing else,
+// checked against @slidev/client's setup/shortcuts.ts and logic/shortcuts.ts directly rather than
+// assumed — 'l' for "layout" was free in both.
+//
+// NOTHING here decides whether the overlay is safe to render — this file only flips the ref.
+// Slidev's own shortcut engine already refuses to fire ANY shortcut while `isPrintMode` is true
+// (logic/shortcuts.ts: `enabled = and(not(isInputting), not(isOnFocus), not(isPrintMode),
+// shortcutsEnabled)`), so this key cannot even be pressed during `slidev export`'s Playwright run
+// — but global-top.vue does not rely on that either; see its own two-guard comment for why the
+// render-time check is independent of whether this shortcut could theoretically fire.
+import { toggleLayoutDebug } from '../debug/layoutDebug.js';
+
+export default function setupLayoutDebugShortcut(_nav, shortcuts) {
+  return [
+    ...shortcuts,
+    { name: 'toggle_layout_debug', key: 'l', fn: toggleLayoutDebug },
+  ];
+}

package/slide-bottom.vue

@@ -0,0 +1,305 @@
+<script setup>
+/*
+  Running chrome, mounted PER SLIDE — the bottom half.
+
+  It replaces global-bottom.vue, which decided visibility from a hard-coded Set of layout names —
+  a list that had to be edited by hand every time a layout was added, and which was already wrong:
+  a `layout: default` slide carrying `class: deck-dark` still got light-ground footer text.
+
+  slide-bottom.vue is mounted inside the slide with the route's frontmatter injected, so a slide
+  says `chrome: false` for itself and every layout stays ignorant of the chrome.
+
+  The page number is BACK in this row, and deliberately at the opposite end from the confidentiality
+  pill — Jose: "the page number i think it can go at the bottom, other extreme of the confidential
+  chip". The earlier note here argued the number and the section "only make sense read together";
+  that was wrong about what each is for. The section answers WHERE AM I and belongs at the top with
+  the mark, where a reader looks up. The page number is a reference handle ("slide 34") that gets
+  used out loud, and the foot of the slide is where an audience already looks for one. The two feet
+  are the two ends of one band. Beside it sits the confidentiality pill: a
+  watermark from `confidential: '<text>'` in a slide's own frontmatter, absent by default. Unlike
+  the page number and section, it is NOT gated on `currentPage > 1` — a page count is meaningless on
+  a cover slide, but a confidentiality marking is exactly the kind of thing a real deck still wants
+  on its title slide, so this only reads `chrome`, not the page number.
+
+  ★ The key is `confidential`, not `info` — `info` is reserved on slide 1 (Slidev's own meta
+  description; see RESERVED_ON_SLIDE_ONE in test/props.ts) and a layout prop or a frontmatter read
+  named after it would silently see Slidev's own value instead of whatever an author intended.
+
+  ★ FIX ROUND 1, MINOR — task-5-brief.md's Step 3 says "text from headmatter `confidential:`",
+  which reads as if a bare `confidential: '…'` in the deck's headmatter (slide 1's own frontmatter
+  block) marks the WHOLE DECK. It does not: this component reads `injectionFrontmatter`, which is
+  the CURRENT slide's own frontmatter only, and a bare headmatter key is only ever slide 1's own
+  frontmatter — it does not propagate. Measured live, both ways: `confidential: '…'` written
+  directly in the deck's headmatter shows up ONLY on slide 1 (and only if `chrome` allows it
+  there); wrapping the SAME key inside headmatter's own `defaults:` block —
+
+      ---
+      theme: '@humanforest/slidev-theme'
+      defaults:
+        confidential: 'Private & Confidential'
+      ---
+
+  — renders it on every slide that doesn't override or clear it, confirmed live on a slide with no
+  `confidential:` of its own. `defaults:` is Slidev's own headmatter-to-every-slide mechanism (it
+  is why this key is safe to use at all: RESERVED_ON_SLIDE_ONE already lists `defaults` itself as
+  reserved, precisely because Slidev owns this exact merge). This file's own behaviour needed no
+  code change for this — it already just reads whatever frontmatter object it was handed, correctly,
+  regardless of which of the two forms above put the value there — but the BRIEF's phrasing and this
+  comment both under-specified WHICH form produces deck-wide behaviour, and neither is Slidev
+  looking it up for you: get the form wrong and the pill silently never shows past slide 1.
+
+  ★ AUTHORING NOTE, measured live: `bleed.vue`'s own `::overlay::` slot is documented to anchor
+  content bottom-left inside the same safe margin this pill uses (see the demo deck's own bleed
+  slide). Forcing `chrome: true` AND `confidential: '…'` on a bleed slide whose overlay ALSO
+  anchors bottom-left collides — the overlay content and this pill occupy the same corner, and
+  nothing here reflows around the other because neither knows the other exists. This is why every
+  bleed slide in the demo deck keeps `chrome: false`: full-bleed media is meant to run the overlay
+  right up to the edge, and the running chrome is exactly the kind of thing that edge shouldn't
+  have to make room for. An author who wants both needs to keep the overlay clear of the bottom-
+  left safe margin (`--deck-inset-chrome`, task-14-brief.md — was `--deck-space-3`/`--deck-grid *
+  2.5`, two different numbers for the same corner; now the one token this pill's own `left`/
+  `bottom` below actually use) themselves.
+
+  Reads `injectionFrontmatter`. SlideWrapper.vue:29 provides the RAW frontmatter object, not a
+  ref — `provideLocal(injectionFrontmatter, props.route.meta.slide.frontmatter)`. Do not reach
+  for `.value`.
+
+  The import below spells out the `.ts` extension. Without it (`from '@slidev/client/constants'`,
+  the extensionless subpath the package's own exports map advertises) Vite mis-resolves the
+  specifier in this monorepo's live dev server: it rewrites it to a bare filesystem path missing
+  the `/@fs/` prefix, the extension and the cache-busting query every other import in this file
+  gets, and the module fails to load entirely (verified live — blank slide, console "Failed to
+  fetch dynamically imported module"). @slidev/cli's own generated imports always spell out the
+  extension for exactly this family of subpath (see templateImportContextUtils in
+  node/vite/common.ts: `"@slidev/client/context.ts"`) — this file follows that precedent.
+*/
+import { computed, inject } from 'vue';
+import { useNav } from '@slidev/client';
+import { injectionCurrentPage, injectionFrontmatter } from '@slidev/client/constants.ts';
+import { chromeShows, darkChromeAt, darkChromeParts, darkRegister } from './notch.js';
+import { chromePillStyle } from './components/backgrounds.js';
+// Explicit: this file sits at the package ROOT beside slide-bottom, not under components/,
+// so Slidev's auto-registration does not reach it. It is chrome, and chrome lives here.
+import ConfidentialMark from './confidential-mark.vue';
+import { confidentialHidden } from './debug/reviewToggles.js';
+
+const frontmatter = inject(injectionFrontmatter, {});
+
+/*
+  ★★ THE CHROME OPTS ITSELF INTO THE DARK REGISTER, because nothing else can put it there.
+
+  `deck-dark` lands on `.slidev-layout` — that is where both `class: deck-dark` and the layouts'
+  `dark` prop write it — and SlideWrapper renders this chrome as a SIBLING of the layout, not a
+  descendant. So every --deck-* role inside the chrome kept resolving on the LIGHT register while
+  the slide beside it was dark. Measured on a `dark: true` slide before this: the page pill painted
+  forest-700 with white ink, identical to its light-register self.
+
+  Reading the same frontmatter this component already injects and stamping the class on its own root
+  is the only place the two can be reconciled without moving `deck-dark` onto the page element,
+  which no layout can reach.
+*/
+// Delegated to notch.js: a cover can resolve a dark ground from its VARIANT without saying so in
+// frontmatter, and this row is a sibling of the layout so it cannot read the classes that resolution
+// lands as. See darkRegister() — the same module, and the same reason, as darkChromeParts below.
+const isDarkRegister = computed(() => darkRegister(frontmatter));
+// The same per-end register the top row takes. This row's own end is 'none' on stack — the strip
+// below a band is cream by definition — and the figure side on split. See darkChromeParts().
+const darkParts = computed(() => darkChromeParts(frontmatter).bottom);
+// From injectionCurrentPage, NOT useNav().currentPage — the /print and /overview routes carry no
+// `:no` param, so useNav() reports 1 for every slide at once and an exported PDF would number every
+// page "1". SlideWrapper.vue provides this per slide on every route. slide-top.vue's own comment
+// records the measured failure this guards against.
+const currentPage = inject(injectionCurrentPage, computed(() => 1));
+
+/*
+  Beats opt out by declaring `chrome: false` in their own frontmatter — and a DIVIDER opts out by
+  being one, because it takes over the whole field and the pill it would draw names the section it
+  is itself announcing. `??` rather than `!== false`, so an explicit `chrome: true` still brings the
+  row back: the default moves, the lever does not.
+
+  DELEGATED to notch.js rather than written here, and that is the gate talking rather than taste:
+  frontmatter.static.test.ts holds every chrome file to naming NO layout, because chrome whose
+  visibility switches on the layout showing is a defect this theme has already had. The rule is
+  real, so the knowledge lives in the one module the gate exempts for exactly this — the same place
+  `split` is named for the mirror — and this file reads a predicate rather than a layout name.
+
+  ★★ AND IT GATES THE PAGE NUMBER, NOT THE ROW. There used to be a `show` here — `chromeWanted` —
+  ANDed over the whole band, so `chrome: false` took the confidentiality marking down with the page
+  number. A page number is furniture: it is the deck telling you where you are, and a slide that
+  wants no furniture means it. A confidentiality marking is a statement about the CONTENT, and a
+  deck that drops its chrome for a full-bleed photograph has not stopped being confidential.
+
+  So the opt-out reaches the number (through `chromeShows`, which is `chromeWanted && page > 1`) and
+  the marking answers to `confidential:` alone. Both of the marking's exemptions now point the same
+  way — notch.js records the other one, the slide-1 gate, for the same reason.
+*/
+/*
+  The reviewer's preview-only override (custom-nav-controls.vue). It can only ever SUBTRACT: a slide
+  with no `confidential:` cannot be made to show one from the toolbar.
+
+  `isPrintMode` is re-checked HERE rather than trusted from the control that sets it. The nav bar
+  already refuses to render under print, so this is the second of two independent guards — and it is
+  the one that matters, because `slidev export` drives a real browser through this same client and a
+  toggle left on would otherwise ship a PDF missing its own confidentiality marking. A guard whose
+  failure mode is "the legal marking silently disappears" is worth stating twice.
+*/
+const { isPrintMode } = useNav();
+const confidentialShows = computed(
+  () => !!frontmatter?.confidential && (isPrintMode.value || !confidentialHidden.value),
+);
+// The number carries the EXTRA gate the confidentiality pill does not: a page count is meaningless
+// on a cover, while a confidentiality marking is exactly what a title slide still wants.
+const showPage = computed(() => chromeShows(frontmatter, currentPage.value));
+
+/*
+  ★ THE MIRROR IS RETIRED — this pill sits at the same end on every slide.
+
+  Jose, on task-15-brief.md's notch: "if text is left or right, the notch position should adapt (and
+  move the page to the other side, along with the confidenciality chip)". The chip is this. The
+  decision is ./notch.js's, shared with slide-top.vue and split.vue rather than re-derived here, so
+  the page marker and this pill can never end up in opposite corners.
+
+  A bottom pill left in place while the top one mirrored would be worse than not mirroring at all:
+  on a `flip: true` split the panel's own bottom-left corner would sit over it.
+*/
+// (The pills' end of this row used to be computed from the mirror. It is a literal in the template
+// now — see the note on the row-reverse rule below.)
+// The page number alone — no "/ total". A running total tells a reader how much is left, which is
+// a thing a presenter usually does NOT want advertised, and it made the pill wide enough to read as
+// a label rather than a marker. The number is what anyone actually refers to ("slide 34").
+const pageLabel = computed(() => String(currentPage.value));
+
+
+</script>
+
+<template>
+  <div v-if="confidentialShows || showPage" :class="['deck-chrome-bottom', isDarkRegister ? 'deck-dark' : '']" data-pills-side="left">
+    <!-- Either child showing brings the band; neither one is gated on the other. See the note on
+    `showPage` above for why the marking does not answer to `chrome: false`. -->
+    <!-- The spacer is not decoration: with `justify-content: space-between` and only ONE child, a
+         lone page number would fall to the start of the row instead of holding its own end. -->
+    <ConfidentialMark
+      v-if="confidentialShows"
+      class="deck-chrome-confidential"
+      :class="darkChromeAt(darkParts, 'left') ? 'deck-dark' : ''"
+      :label="frontmatter.confidential"
+    />
+    <span v-else class="deck-chrome-spacer" aria-hidden="true" />
+    <span
+      v-if="showPage"
+      class="deck-page-dot"
+      :class="darkChromeAt(darkParts, 'right') ? 'deck-dark' : ''"
+      :style="chromePillStyle()"
+    >{{ pageLabel }}</span>
+  </div>
+</template>
+
+<style scoped>
+.deck-chrome-bottom {
+  position: absolute;
+  /* Chrome is inset --deck-inset-chrome on every edge it touches — the same token slide-top.vue's
+     row uses on all four of ITS edges, so the two bands sit the identical distance from the canvas. */
+  bottom: var(--deck-inset-chrome);
+  /* BOTH edges now, which the single-child version could not do. Its own comment warned that pinning
+     left AND right would "stretch a short confidentiality string into a wide empty pill" — true when
+     the PILL was the positioned box, and no longer true now that the positioned box is this row and
+     the pill is a shrink-wrapped child of it. */
+  left: var(--deck-inset-chrome);
+  right: var(--deck-inset-chrome);
+  display: flex;
+  /* flex-END, mirroring slide-top.vue's flex-start, and for the same reason. The band is the PAGE
+     MARKER's height (49) and the confidentiality chip is 31, so centring floated the chip's bottom
+     at 45 from the canvas where the band's own bottom is 36 — the chip read as not quite sitting
+     down. Reported by eye. Bottom-aligning gives the two ends of this band one shared baseline at
+     --deck-inset-chrome, exactly as the top row shares one at the same token. */
+  align-items: flex-end;
+  gap: var(--deck-space-2);
+  /* The two ends of one band: the confidentiality pill at one, the page number at the other. */
+  justify-content: space-between;
+  z-index: 20;
+  pointer-events: none;
+}
+/* The mirror. The pill travels to the TEXT side with the rest of the chrome (./notch.js owns that
+   decision), and the page number takes whichever end is left — so the pair always spans the foot
+   rather than crowding one corner.
+
+   ★ THE row-reverse RULE WENT WITH THE MIRROR. It swapped which end was which on a `flip: true`
+   split; nothing flips now, so a selector for the other order would be one nothing can match. The
+   attribute stays as a literal because the two ends still need naming in the CSS below. */
+/* The pill may shrink (BadgeStrip's own 20em cap and ellipsis do the truncating); the number never
+   does — a marker that squeezed would stop being one shape across the deck. */
+.deck-chrome-confidential { min-width: 0; }
+.deck-chrome-spacer { flex: none; }
+/*
+  The page marker: a circle, not a pill — and now actually one at every digit count.
+
+  It carries BadgeStrip's background pair (via backgroundStyle, so fill and ink can never be mismatched —
+  13 of 24 fill x ink combinations fail body contrast) and its overline type role, so the two still
+  read as one family. What it does NOT share is the geometry: a pill is sized by its content's
+  width, which makes "8" and "216" different shapes, and a marker has to be the same shape on every
+  slide or it stops reading as a marker.
+
+  A STADIUM, NOT A CIRCLE — and it grows with the number.
+
+  It was a circle, squared off by declaring both axes from the deck's widest number, so the marker
+  was one constant shape whatever page it sat on. Jose: "the page should not be a circle but a full
+  rounded rectangle... and it should adapt the notch, even if it have 2, 3, 4 digits". A stadium
+  gets that for free: the height is the overline line box, the width is whatever the digits need
+  plus symmetric padding, and `min-width` equal to the height keeps a single digit from collapsing
+  into a lozenge narrower than it is tall. One digit still reads as a circle; four reads as a pill.
+
+  WHAT SURVIVES FROM THE CIRCLE, because both were measured and neither was about the shape:
+
+  1. NO TRACKING. The overline role tracks 0.08em, applied after the last character too, so a
+     tracked number sits ~2.4px left of its own optical centre. Tracking is a LABEL treatment; a
+     marker is a number in a box. The section pill keeps the role's tracking, which is what makes
+     the two read as label-and-marker rather than as two labels.
+  2. TABULAR FIGURES. Proportional digits change the box's width between slides — "11" is far
+     narrower than "18" — so the marker would twitch on every page turn.
+
+  The width is now CONTENT-driven rather than declared from `total`, which is what lets the notch
+  track it: slide-bottom measures the rendered box and publishes it, so the cut follows the real
+  number rather than the widest one the deck might reach.
+*/
+.deck-page-dot {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  height: var(--deck-page-dot-line);
+  /* Never narrower than it is tall — a lone "1" stays a circle rather than a slot. */
+  min-width: var(--deck-page-dot-line);
+  --deck-page-dot-line: calc(var(--type-deck-overline-size) * var(--type-deck-overline-line-height) + var(--deck-space-1) * 2);
+  padding-inline: var(--deck-space-2);
+  border-radius: var(--deck-radius-full);
+  font-family: var(--type-deck-overline-family);
+  font-size: var(--type-deck-overline-size);
+  line-height: var(--type-deck-overline-line-height);
+  font-weight: var(--type-deck-overline-weight);
+  letter-spacing: normal;
+  font-variant-numeric: tabular-nums;
+}
+
+/*
+  ★★ THE REGISTER LANDS HERE TO RE-POINT THE PILLS, NEVER TO PAINT. styles/tokens.css gives
+  `.deck-dark` a ground of its own — right for a wrapper INSIDE a slide (a dark card band, a chart
+  well), wrong for this row, which floats over the slide and has never had a ground. Measured on the
+  specimen's alert slide the moment the per-end register landed: a forest-950 block behind the mark,
+  sitting on the forest-900 panel it was supposed to match.
+
+  ★★ AND THE ROW ITSELF, NOT ONLY ITS CHILDREN. This rule listed the pills, the mark and the
+  confidential flag and stopped there — so the container kept the ground, and the container is the
+  one that spans the full 1848px. Invisible on a bare slide, because there is nothing behind it to
+  cover. Measured on a dark split slide carrying a full-height map: `deck-chrome-top.deck-dark` at
+  y 36 h 72 and `deck-chrome-bottom.deck-dark` at y 995 h 49, both painting forest-950 across the
+  whole width, over a figure spanning 36 to 1044 — two dark bands across the top and bottom of the
+  map, which read as a map that fails to fill its frame rather than as chrome with a ground.
+*/
+.deck-chrome-bottom.deck-dark,
+.deck-chrome-pills.deck-dark,
+.deck-chrome-mark.deck-dark,
+.deck-chrome-confidential.deck-dark {
+  background: transparent;
+}
+</style>