@humanforest/slidev-theme 0.1.0

package/notch.js

@@ -0,0 +1,458 @@
+// The notch, and the chrome mirror it implies — the shared decisions, split out of the three
+// components that have to agree on them so they are one rule rather than three copies.
+//
+// WHAT THE NOTCH IS. A split slide's figure side is a PANEL — a photo frame or a tint — and its
+// outer top corner is cut INWARD so the running Forest mark can sit in the cut-out. The panel's
+// edge then reads convex → concave → convex around the mark, which is what makes the mark look
+// seated INTO the panel rather than parked on top of it. split.vue owns the cut (a mask, see its
+// own `.has-notch` comment); slide-top.vue owns the mark. Neither may decide on its own whether
+// there is a notch, because a cut with nothing in it is a hole and a mark with nothing cut for it
+// is the collision this replaced.
+//
+// WHY A PLAIN MODULE. packages/slidev-theme's suite runs under plain Node with no DOM
+// (vitest.config.ts: `environment: 'node'`) and never mounts a component, so a computed buried in
+// slide-top.vue's <script setup> is unreachable from a test. Same move, same reason, as section.js
+// and backgrounds.js: the decision is a pure function taking plain data.
+//
+// ★ THE MIRROR, AND THE ONE JUDGEMENT CALL IN IT. Jose: "this should work on either order... 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 rule in one sentence: CHROME SITS ON THE TEXT SIDE,
+// THE MARK SITS ON THE PANEL SIDE. Everything else falls out of split's existing `flip` prop.
+//
+// `flip` is frontmatter, so slide-top.vue and slide-bottom.vue can read it exactly the way they
+// already read `chrome` and `confidential` — no new plumbing, no prop drilling, no coupling to the
+// layout component.
+//
+// The call: the chrome mirrors on `layout === 'split'` AND `flip === true`, never on `flip`
+// alone. `flip` is a plain frontmatter key, so any slide can carry one — a `default` slide with a
+// stray `flip: true` (copy-pasted frontmatter, an AI's guess) has no panel and no second column,
+// and swinging its page number across the canvas would be a silent, unexplainable move. Gating on
+// the layout that actually splits means the mirror only fires where there is something to mirror
+// AROUND. bleed is the same case for the same reason: it fills the canvas, has no panel side, and
+// must keep the default arrangement and grow no notch.
+
+/** The one layout whose `flip` means "which half is the text" — the only one the chrome mirrors for. */
+export const SPLIT_LAYOUT = 'split';
+
+/** The one layout whose figure spans the WHOLE canvas width, so both ends of the chrome sit over it. */
+export const STACK_LAYOUT = 'stack';
+
+/** `frame` values that make split's figure side a real PANEL (rather than a second content column). */
+/*
+ * The frame kinds that are a REAL FIGURE — one that fills its cell top to bottom, so the running
+ * mark would be drawn over it and the corner has to be cut.
+ *
+ * ★ `figure` joined `photo` and `panel` when it was added: it is the kind for a COMPONENT figure (a
+ * live map, a chart) and it fills the cell exactly as the other two do. Measured before adding it —
+ * a full-height component on the figure side runs its top corner straight under the Forest mark,
+ * which is the collision this list exists to describe. `none` stays out because that side is a
+ * second column of TEXT, which the chrome sits above rather than on.
+ */
+export const PANEL_FRAMES = ['photo', 'panel', 'figure', 'code'];
+
+/*
+  ★★ THE CHROME NO LONGER MIRRORS, AND THE NOTCH IS WHAT PAID FOR IT.
+
+  `isMirrored(layout, side)` and `chromeSides(mirrored)` lived here. A `flip: true` split puts the
+  figure on the LEFT, so the notch was cut from the figure's top-left and the mark travelled there
+  to sit in it, with the pills pushed to the far end. The mark and the cut were one mechanism: the
+  bite exists so the mark has somewhere to sit.
+
+  Jose, looking at a rendered mirrored slide: "i dont think we want to mirror the chrome". So the
+  mark is fixed top-right and the row never reverses.
+
+  ★★ AND THE NOTCH SURVIVES IT, WHICH THE FIRST ATTEMPT AT THIS GOT WRONG. That attempt reasoned
+  that the cut exists to seat the MARK, so a figure the mark can no longer reach must not be bitten,
+  and gated hasNotch on `flip`. That is false, and ./useNotchCuts.js says so in its own first line:
+  it measures whatever running chrome is sitting on the panel — the mark, each section pill item,
+  the page marker, the confidentiality pill — assigns each to the corner it lands in, and cuts all
+  of them. Jose: "ffs there could still be a section pill... dont kill the notch".
+
+  On a `flip: true` split the figure is on the LEFT, which is exactly where the pills now are. So
+  the cut is still needed there; what changed is only which occupant it seats. Nothing in hasNotch
+  had to know about sides at all.
+
+  Not left as a function returning false. A predicate that always answers the same way reads as a
+  live decision to the next person and is a branch nobody can ever exercise; the arrangement is
+  fixed in slide-top.vue's and slide-bottom.vue's own CSS instead. scripts/deckAudit.ts still
+  measures the chrome's corners per slide, so a mirror reappearing is caught by the rendering rather
+  than trusted to this comment.
+*/
+
+/**
+ * Is the running chrome actually drawn on this slide? The same predicate slide-top.vue has always
+ * used for its own `v-if`, lifted here because split.vue now needs the SAME answer: a notch is only
+ * ever correct when there is a mark to put in it, and `chrome: false` (or slide 1, which carries no
+ * page number worth reading) means there is not.
+ *
+ * ★★ A DIVIDER CARRIES NO CHROME UNLESS IT ASKS FOR SOME. It is the one slide that takes over the
+ * whole field, so the running furniture is the thing it is taking the field FROM — and the pill it
+ * would draw names the section this very slide is announcing, which is the heading already filling
+ * the middle of it. Every divider in both decks passed `chrome: false` by hand; that is a default,
+ * written nine times.
+ *
+ * ⚠ AND IT WAS NOT ONLY REDUNDANT, IT COLLIDED. The section pill paints the deck's own green, and
+ * the section rank now paints that same green full-bleed — measured on the rank specimen, the pill
+ * vanished into the ground it sat on while still passing every contrast check, because white text
+ * on green scores 6.27 whether or not the chip behind it is visible.
+ *
+ * `??`, so an explicit `chrome: true` still brings it back — the default moves, the lever does not.
+ *
+ * ★ SPLIT IN TWO because the two chrome rows do not ask the same question: the bottom row has never
+ * carried the `currentPage > 1` clause, since slide 1 has no page number worth reading at the TOP
+ * and that says nothing about the row underneath. `chromeWanted` is the half they share, and it is
+ * the only place in this theme where a layout name decides VISIBILITY rather than position.
+ *
+ * @param {Record<string, any> | undefined} frontmatter the slide's own frontmatter.
+ * @param {number} currentPage Slidev's own one-based page number.
+ */
+/*
+  ★★ A COVER JOINS THE DIVIDER, AND FOR A SHARPER REASON. A divider suppresses the chrome because
+  the chrome would repeat what the slide is already shouting. A cover suppresses it because the
+  chrome is a RUNNING mark — a page number, a section pill, the identity — and an opener is the
+  slide none of those has started running on yet. It also carried the Forest mark twice: once as the
+  running identity top-right, once as the lockup cover.vue signs with.
+
+  ⚠ THE CONFIDENTIALITY MARKING IS NOT PART OF THIS. slide-bottom.vue draws it on its own condition
+  rather than through `chromeShows`, precisely so a title slide can still carry its marking — which
+  is the one piece of chrome a real deck wants on a cover, and the reason this is a default here
+  rather than `chrome: false` written on every cover by hand.
+*/
+/* ★ `end` JOINED THE LIST RATHER THAN CARRYING `chrome: false` ON EVERY SLIDE. Jose: "end layouts
+   should not have chrome never". A closer is the last frame of a deck — a page number and a running
+   section pill on it are furniture for a deck that is still going. Written as a default here, an
+   author who genuinely wants the chrome back can still say `chrome: true`; written as frontmatter on
+   every closing slide, it is a line nobody remembers. */
+const CHROMELESS_LAYOUTS = ['divider', 'cover', 'end'];
+
+export const chromeWanted = (frontmatter) => frontmatter?.chrome ?? !CHROMELESS_LAYOUTS.includes(frontmatter?.layout);
+
+export const chromeShows = (frontmatter, currentPage) => chromeWanted(frontmatter) && currentPage > 1;
+
+/**
+ * ★ THE OPT-OUT (task-18-brief.md). `notch: false` on a slide's own frontmatter.
+ *
+ * The notch is theme-wide by construction — every `frame: photo`/`frame: panel` figure in every
+ * deck grows one — which is what made it visible without editing a single slide, and is also why it
+ * needs an escape hatch: it changed the look of ~50 committed slides and there was no way to say
+ * "not this one". A photograph whose subject sits in that corner, a panel that must keep its full
+ * height, a slide being compared against an older export: all real, none of them a bug in the cut.
+ *
+ * ⚠ WHAT OPTING OUT ACTUALLY RESTORES, stated plainly rather than discovered later. Every part of
+ * the notch keys off the same predicate — the mask, the panel's rise to the chrome inset, and the
+ * band of content reserved from a text panel — so `notch: false` drops all three together and the
+ * figure returns EXACTLY to its pre-notch geometry: full corner, --deck-inset-text top margin, no
+ * reserved band. That is the clean removal the brief asks for (no gap left where the cut was), and
+ * it is also, unavoidably, the 18px mark-over-corner overlap the notch was built to fix — the mark
+ * is inset 36px and the un-notched figure starts at 90px. The escape hatch's whole job is to give
+ * that old look back on a chosen slide; a slide that wants neither can also carry `chrome: false`.
+ *
+ * Separate from `chrome: false` on purpose: that hides the mark AND the pills AND the
+ * confidentiality watermark. A slide that wants its running chrome but not the cut has no way to
+ * say so through `chrome:`.
+ *
+ * @param {Record<string, any> | undefined} frontmatter the slide's own frontmatter.
+ * @returns {boolean} false only when the slide explicitly wrote `notch: false`.
+ */
+export const notchShows = (frontmatter) => frontmatter?.notch !== false;
+
+/**
+ * Does this figure cut a notch?
+ *
+ * All three are required, and each one alone is a defect: without a panel there is no material to
+ * cut (a `frame: content` figure side is the author's own second CONTENT column, which owns its own
+ * corner), without the chrome the cut has no occupant, and with `notch: false` the author has said
+ * not to.
+ *
+ * Called by split.vue for its figure side and by stack.vue for its band — both are the same
+ * question, which is why `frame` is the parameter rather than a layout name.
+ *
+ * @param {string | undefined} frame the layout's `frame` prop.
+ * @param {boolean} chromeShowing `chromeShows()`'s answer for this slide.
+ * @param {boolean} [notchShowing] `notchShows()`'s answer. Defaults to true so a caller that has no
+ *   frontmatter to consult still gets the theme-wide behaviour rather than silently no cut.
+ */
+export const hasNotch = (frame, chromeShowing, notchShowing = true) =>
+  chromeShowing && notchShowing && PANEL_FRAMES.includes(frame);
+
+/**
+ * ★ CO-BRANDING — "maybe two logo marks for forest+companion" (Jose), task-18-brief.md.
+ *
+ * task-15 proved the cut SIZES to any occupant (measured 72px → 160px of occupant, corner radius
+ * unmoved) but nothing ever drew a second mark. This is the missing half: one pure function, so the
+ * component that DRAWS the lockup and the layout that CUTS room for it compute the same width from
+ * the same frontmatter and cannot part company. That is the same reason `hasNotch` lives here
+ * rather than inside either component.
+ *
+ * ★★ THE PARTNER IS A SQUARE, THE SAME SIZE AND SHAPE AS THE MARK. Jose: "the other logo should be
+ * anything (an avatar or whatever), but the second one should be a rounded square like the mark".
+ * The companion's artwork can be any ratio — an avatar, a wordmark, a photograph — and it is COVERED
+ * into a mark-sized square clipped to the mark's own corner, rather than being drawn at its own
+ * proportions beside it.
+ *
+ * No author input reaches the size, and that is what makes the cut right on the first frame: an
+ * image's intrinsic ratio is unknown until it loads, so the occupant is `markPx + pairGapPx +
+ * markPx` — 160px — known before anything loads, identical on every slide, and inside even the
+ * narrowest ratio's ceiling of 220.5px at 3:1. The clamp below cannot fire for a co-brand; it stays
+ * because `notchBudgetPx()` still guards the general `--deck-notch-occupant-w` override.
+ *
+ * The lockup's own composition follows packages/ui/src/logo/FSubLogo.vue's rule — one shared
+ * height, the lead first, a measured gap between — rather than inventing a second co-brand
+ * grammar. It does NOT import it: FSubLogo composes from the glyph atlas through Nuxt UI/Tailwind,
+ * neither of which exists on a slide.
+ *
+ * @param {Record<string, any> | undefined} frontmatter the slide's own frontmatter.
+ * @param {{ markPx: number, pairGapPx: number }} chrome deck.json's `chrome` block — the mark's own
+ *   size and the lockup gap, read rather than restated.
+ * @returns {{ src: string, companionPx: number, occupantPx: number } | null} null when the slide
+ *   declares no companion, in which case NEITHER reader may declare --deck-notch-occupant-w: leaving
+ *   it undeclared is what keeps the documented `class:`-based override reaching both of them.
+ */
+export const coBrand = (frontmatter, chrome, budgetPx = Infinity) => {
+  const src = frontmatter?.companion;
+  if (typeof src !== 'string' || !src.trim()) return null;
+  // Always the mark's own size — see the note above. No author input reaches this, which is what
+  // makes the occupant deterministic and the first frame correct without measuring anything.
+  const declaredPx = chrome.markPx;
+  // The lockup's fixed part: the Forest mark plus the pair gap. Whatever the budget is, this much of
+  // it is already spent before a companion's mark is drawn at all.
+  const lead = chrome.markPx + chrome.pairGapPx;
+  const room = Number.isFinite(budgetPx) ? Math.max(0, budgetPx - lead) : Infinity;
+  const companionPx = Math.min(declaredPx, room);
+  return {
+    src: src.trim(),
+    companionPx,
+    occupantPx: lead + companionPx,
+    /** What the slide asked for, kept so a clamp is inspectable rather than invisible. */
+    declaredCompanionPx: declaredPx,
+    /** True when the panel could not hold the declared width — see notchBudgetPx(). */
+    clamped: companionPx < declaredPx,
+  };
+};
+
+/**
+ * ★★ THE BUDGET, AND THE THING THAT SPENDS AGAINST IT.
+ *
+ * `deck.json → notch.fit.maxOccupantPx` is 208.5px and `scripts/deck.ts` defines `NOTCH_PAIR_PX` as
+ * 160, the widest occupant. Both are ceilings this function applies rather than assertions about
+ * defaults: anything a slide can widen the cut with is measured against the panel it is cut into.
+ *
+ * Rendered against the real theme CSS on a 3:1 panel (489px wide):
+ *
+ *     occupant  72 (default)  → cut 108  correct seat
+ *     occupant 288 (shipped)  → cut 324  66% of the panel width: an L-shaped step, not a bite;
+ *                                        the convex → concave → convex read is gone
+ *     occupant 600            → cut 636  the mask subtracts the ENTIRE top 108px of the panel and
+ *                                        the mark floats above it with nothing cut for it
+ *
+ * So the ceiling is now per-RATIO, read from the generated table rather than restated, and
+ * `coBrand()` clamps against it. A clamped companion still DRAWS — its `<img>` is `object-fit:
+ * contain`, so it renders smaller inside a narrower box rather than distorted or dropped — because
+ * a co-brand silently disappearing is worse than one that is visibly too small for its slide.
+ *
+ * Every caller must pass the SAME budget or the cut and its occupant part company again, which is
+ * why `coBrandFitted()` below exists and is what the three components actually call.
+ *
+ * @param {Record<string, any> | undefined} frontmatter the slide's own frontmatter.
+ * @param {number} currentPage Slidev's own one-based page number.
+ * @param {{ defaultRatio: string, byRatio: Record<string, { figurePx: number, maxOccupantPx: number }> }} fit
+ *   deck.json's `notch.fit` block.
+ * @returns {number} the widest occupant this slide's panel can seat — `Infinity` when there is no
+ *   cut at all, because then nothing is being spent and clamping would only shrink a lockup for no
+ *   geometric reason.
+ */
+export const notchBudgetPx = (frontmatter, currentPage, fit) => {
+  const frame = frontmatter?.frame;
+  const chromeShowing = chromeShows(frontmatter, currentPage);
+  // Every reason there is no cut is a reason not to clamp: no panel, opted out, no chrome, slide 1.
+  // Shrinking a lockup that is merely being DRAWN would be an arbitrary haircut.
+  const cutting = hasNotch(frame, chromeShowing, notchShows(frontmatter));
+  if (!cutting) return Infinity;
+  const byRatio = fit?.byRatio ?? {};
+  const entry =
+    frontmatter?.layout === STACK_LAYOUT
+      ? byRatio.stack
+      : byRatio[frontmatter?.ratio] ?? byRatio[fit?.defaultRatio];
+  // An unknown ratio resolves to the layout's own default (split.vue clamps `ratio` through
+  // RATIO_CLASS for exactly the same reason); a table with no entry at all means the generator and
+  // this module have parted company, and an unbounded occupant is the safer failure than a
+  // zero-width one — it is visible.
+  return Number.isFinite(entry?.maxOccupantPx) ? entry.maxOccupantPx : Infinity;
+};
+
+/**
+ * The co-brand lockup, already fitted to the panel it will be cut into — the ONE call slide-top.vue,
+ * split.vue and stack.vue all make, so the mark that is DRAWN and the cut made FOR it are the same
+ * arithmetic on the same inputs rather than three call sites that must remember to pass the same
+ * third argument.
+ *
+ * @param {Record<string, any> | undefined} frontmatter the slide's own frontmatter.
+ * @param {number} currentPage Slidev's own one-based page number.
+ * @param {{ chrome: { markPx: number, pairGapPx: number }, notch: { fit: any } }} deck deck.json.
+ */
+export const coBrandFitted = (frontmatter, currentPage, deck) =>
+  coBrand(frontmatter, deck.chrome, notchBudgetPx(frontmatter, currentPage, deck.notch.fit));
+
+/*
+  ★★ RETIRED — task-26's `clearsChrome()` is gone, and this note is what it left behind.
+
+  It made a full-width PHOTO band stand clear of the running chrome rather than notch into it. The
+  reasoning was sound at the time: the chrome then MIRRORED, routing the pills to the text side and
+  the mark to the panel side, which is complete for `split` but not for `stack`, whose band spans
+  the whole canvas so BOTH ends land on it. (The mirror is gone now — see the note above hasNotch —
+  but that is not what retired this rule.) The mark got its notch; the page marker and the section pill got
+  nothing and sat directly on a photograph whose corner can be any colour.
+
+  ★ WHAT RETIRED IT: useNotchCuts.js measures EVERY running-chrome element on the panel — the mark,
+  each pill, the page marker, the confidentiality pill — assigns each to the corner it sits in, and
+  cuts all of them. The premise "the pills get nothing" stopped being true when that landed, and
+  nothing re-checked the rule built on it.
+
+  MEASURED, on apps/deck's `frame: photo` band with the clearance removed: the band's clip
+  path opens at `M 234.508 0`, i.e. the top-LEFT is cut for the section pill exactly as the top-right
+  is cut for the mark, and the deck audit's occlusion pass reports 0 text elements painted under an
+  opaque media surface across all 126 slides. Both ends are seated, which is what the rule wanted
+  and could not get.
+*/
+
+/*
+  ★★ WHICH END OF THE RUNNING CHROME SITS ON A DARK PANEL.
+
+  `panelDark` re-points a panel's ground to the dark register (split.vue, stack.vue). The running
+  chrome is a SIBLING of `.slidev-layout`, so it cannot inherit that — and when the panel BLEEDS
+  there is no ring of ground left for the chrome to sit on, so it lands directly on it.
+
+  Measured on the specimen's alert slide before this existed: the page marker painted
+  the chrome pill (--deck-accent, forest-700 on light) on a forest-900 panel, 1.09:1. That is the exact
+  collision deckNotch.static.test.ts's ground table already predicts for a pinned pill on a dark
+  ground; the table's own dark column is only survivable because the pill turns over with the
+  register, and here the register turned over under half the slide while the pill did not.
+
+  So each end is answered separately, from the same frontmatter both layouts read:
+
+    split   the panel is the FIGURE side, which is the opposite of `flip`. The chrome does not
+            mirror — mark and page marker are always at the right end, section and confidentiality
+            pills always at the left — so one end lands on the panel and the other on the content
+            column, whichever way `flip` points.
+    stack   the band spans the full width, so BOTH ends of the row it occupies land on it and neither
+            end of the other does: the strip facing it is cream by definition. `flip` moves which row
+            that is — unflipped the band is row 1, flipped it is row 2.
+
+  Panels at `edge: inset` are deliberately absent. They keep the media inset, and the chrome then
+  sits on the slide's own ground with the notch cutting a seat for it — which is what the notch is
+  for.
+*/
+/*
+  ── THE ONE GROUND THE FRONTMATTER DOES NOT STATE ──────────────────────────────────────────────
+
+  ★★ A COVER CAN CHOOSE ITS OWN, AND THE CHROME CANNOT SEE IT. `cover.vue` resolves
+  `background: auto` — the default — from its VARIANT: the mosaic opens on the vivid pair's dark
+  half because that is the register the brand draws a field of photographs on. That resolution
+  happens inside the component and lands as classes on `.slidev-layout`, which the chrome is a
+  SIBLING of, not a descendant.
+
+  So a slide whose frontmatter states neither `dark` nor a background still renders dark, and both
+  chrome rows read the frontmatter to decide their register. MEASURED on the specimen's mosaic
+  cover with a `confidential:` added: the marking painted --deck-fg-subtle (neutral-500) on
+  forest-700 at 1.36:1 — the row had no idea it was on a dark ground.
+
+  The table lives HERE, and cover.vue imports it, because this is the module the "chrome names no
+  layout" gate exempts (see darkChromeParts below, which names split and stack for the same
+  reason). One table, two readers, no drift.
+
+  ⚠ "UNSTATED" IS SPELLED DIFFERENTLY ON EACH SIDE and that is not sloppiness: cover.vue reads
+  PROPS, where an absent boolean arrives as `null` from its declared default, and this reads
+  FRONTMATTER, where it is simply missing. Same question, two vocabularies.
+*/
+/* Two, not six — see the `background` prop in cover.vue for why an opener does not take the named
+   pairs. Kept in step with that validator; the clamp below and the layout's own must agree.
+
+   ★ BEAT_, NOT COVER_, since `end` took the same contract. The two bookends of a deck answer the
+   same question — which ground does this open (or close) on when nobody said — and answering it
+   twice is how they would come to differ. Named for the pair of layouts rather than for one. */
+export const BEAT_GROUNDS = ['auto', 'paper'];
+/*
+  ★★ ONE GROUND FOR EVERY VARIANT, NOT A TABLE KEYED BY ONE. It began as `{ mosaic: {...} }` — the
+  brand cover choosing its own green while the other six fell back to paper — and that made the
+  default ground a property of the SHAPE, so two openers in the same deck opened on different
+  colours depending on which composition an author reached for. A cover is where a deck states its
+  identity; the identity does not change with the arrangement of the picture.
+*/
+export const BEAT_GROUND = { background: 'vivid', dark: true };
+/*
+  The cover variants whose ground props describe a PANEL rather than the slide — cover.vue reads the
+  same list. Their page keeps its paper however the panel is painted, so the chrome on one of them
+  is on the light register no matter what `dark` says.
+*/
+export const COVER_PANEL_SHAPED = ['inset'];
+/*
+  ★★ THE VARIANT WHOSE GROUND IS A PHOTOGRAPH, so `background` and `dark` have nothing to paint: a
+  poster covers the canvas edge to edge and lays a black scrim over it. Every one of them is light
+  ink on a dark picture whatever the frontmatter says, and drawing the same composition once per
+  named ground gave four slides that were pixel-identical apart from a caption — which is how this
+  was caught. The register is FIXED here rather than chosen, and both readers have to agree on it
+  or the confidentiality marking comes back dark on a dark photograph.
+*/
+export const COVER_PHOTO_GROUND = ['poster'];
+/* The same fact about the closer: `photo` fills the canvas with a photograph under a scrim, so its
+   register is fixed light-on-dark whatever the frontmatter says. One list per layout rather than one
+   shared list, because these name VARIANTS and the two layouts' enums are their own. */
+export const END_PHOTO_GROUND = ['photo'];
+/*
+  ★★ THE CLOSER TAKES THE NAMED PAIRS AND THE OPENER DOES NOT, and that asymmetry is deliberate
+  rather than drift. cover.vue's own note argues an opener down to two grounds: a deck states its
+  identity there, and the identity does not change with the arrangement. A closer is the last frame
+  and is regularly the one slide a deck is allowed to be loud on — Jose asked for a peach ground with
+  brown words the day the layout gained its variants — so it reads the same four-name table
+  `default`, `split`'s panel, `stack`'s band and a Card already share.
+
+  `auto` stays first because it is the default, and it means the same thing here as there: the brand
+  pair, resolved from BEAT_GROUND.
+*/
+export const END_GROUNDS = ['auto', 'paper', 'warm', 'accent', 'vivid', 'neutral'];
+/* The layouts that resolve an unstated ground from BEAT_GROUND. Everything else renders on the
+   deck's paper unless it says otherwise, which is what `dark` and a `deck-dark` class are for. */
+const BEAT_LAYOUTS = ['cover', 'end'];
+
+/**
+ * Does this slide RENDER on the dark register? `dark: true` and a hand-written `deck-dark` class are
+ * the two ways a slide says so itself; the third is a cover letting its variant choose.
+ */
+export function darkRegister(frontmatter) {
+  const fm = frontmatter ?? {};
+  if (fm.layout === 'cover' && COVER_PANEL_SHAPED.includes(fm.variant)) return false;
+  if (fm.layout === 'cover' && COVER_PHOTO_GROUND.includes(fm.variant)) return true;
+  if (fm.layout === 'end' && END_PHOTO_GROUND.includes(fm.variant)) return true;
+  if (fm.dark === true) return true;
+  if (String(fm.class ?? '').split(/\s+/).includes('deck-dark')) return true;
+  if (!BEAT_LAYOUTS.includes(fm.layout) || fm.dark !== undefined) return false;
+  // Clamped the same way the layout clamps it, so a misspelt ground resolves here exactly as it
+  // does there — `auto` — rather than the two disagreeing about which slide is dark.
+  //
+  // ⚠ AND EACH LAYOUT'S OWN LIST DOES THE CLAMPING. `end` takes the four named pairs as well; read
+  // against the opener's two, a closer on `warm` fell through to `auto` here and the marking on it
+  // was drawn for a dark register on a peach ground.
+  const grounds = fm.layout === 'end' ? END_GROUNDS : BEAT_GROUNDS;
+  const stated = grounds.includes(fm.background) ? fm.background : 'auto';
+  return stated === 'auto' && BEAT_GROUND.dark === true;
+}
+
+const NO_DARK_CHROME = { top: 'none', bottom: 'none' };
+export function darkChromeParts(frontmatter) {
+  const fm = frontmatter ?? {};
+  if (fm.panelDark !== true || fm.edge !== 'bleed') return NO_DARK_CHROME;
+  if (fm.layout === 'split') {
+    if ((fm.frame ?? 'figure') !== 'panel') return NO_DARK_CHROME;
+    const figureSide = fm.flip === true ? 'left' : 'right';
+    return { top: figureSide, bottom: figureSide };
+  }
+  if (fm.layout === 'stack') {
+    if ((fm.frame ?? 'panel') !== 'panel') return NO_DARK_CHROME;
+    /* A band is full width, so BOTH ends of whichever row it occupies land on it and neither end of
+       the other does — the region facing it is cream by definition. `flip` moves which row that is. */
+    return fm.flip === true ? { top: 'none', bottom: 'both' } : { top: 'both', bottom: 'none' };
+  }
+  return NO_DARK_CHROME;
+}
+/** True when the given end of a chrome row sits on a dark panel. `part` is 'left' or 'right'. */
+export const darkChromeAt = (parts, part) => parts === 'both' || parts === part;

package/notchPath.js

@@ -0,0 +1,188 @@
+// The panel outline, as one geometric path — a rounded rectangle with a notch bitten out of any of
+// its four corners.
+//
+// WHY THIS IS A FUNCTION AND NOT CSS. The first notch was a `clip-path: shape()` written by hand,
+// once per corner, with the occupant's size baked in as a token. That worked while exactly one
+// thing (the Forest mark, 72px, known ahead of time) ever sat on a panel. It does not survive what
+// the chrome actually became:
+//
+//   · the section pill sits on a stack band's other top corner, and its width is a section NAME;
+//   · the page marker sits on a split panel's bottom corner, and its width grows with the digit
+//     count — "9", "19", "199" are three different boxes;
+//   · a co-branded slide widens the mark's own occupant to a pair.
+//
+// Written as CSS that would be four corners x two mirror states x per-corner sizes, and every one
+// of those variants would be a separate hand-derived path that could drift from the others. Written
+// as one function it is a single derivation, unit-testable in node against an independent model,
+// and the callers only have to say which corners are occupied and by what.
+//
+// THE PROFILE, corner-local, is unchanged from the hand-written version it replaces — a convex
+// return of radius r meeting the edge at (w + r, 0), a straight run down x = w, a concave quarter
+// circle centred on (w - r, h - r), and the mirrored return meeting the side edge at (0, h + r).
+// See styles/base.css for why the cut is a clip and not a mask (a mask is alpha, and `subtract`
+// leaves a hairline of panel painted into the ground wherever a boundary lands on a fractional
+// device pixel).
+
+/** The four corners, named as they are addressed everywhere else in the theme: physical, not logical. */
+export const CORNERS = ['tl', 'tr', 'br', 'bl'];
+
+/**
+ * Resolve a notch's TWO radii, which the first version wrongly treated as one.
+ *
+ * A notch has a concave inner corner and two convex returns, and they answer to different masters:
+ *
+ *   · the CONCAVE corner must be CONCENTRIC with the occupant it wraps — the occupant's own corner
+ *     plus the ring — or the gap around the occupant is not constant, which is visible as soon as
+ *     the occupant is round;
+ *   · the CONVEX returns are only the transition back to the panel's edge. Nothing is seated in
+ *     them, so their radius is free.
+ *
+ * Sharing one radius forces a false choice. Measured on a 49px-tall page marker with a 24px ring:
+ * concentric wants 48.5, but the cut is only 73 tall, so `min(r, h/2)` clamped it to 36.5 and the
+ * cut stopped being concentric — its concave corner curved about (58.2, 971.5) where the pill's
+ * curved about (46.2, 983.5). Reported by eye as "not perfect", and it was.
+ *
+ * Clamped independently instead: the concave radius only has to fit inside the cut, and the return
+ * radius only has to leave the concave corner room to exist. The mark is unaffected (96px cut, 39.75
+ * concentric — the return still resolves to 39.75, exactly what it drew before).
+ *
+ * @returns {{ r: number, rr: number }} concave radius, convex return radius
+ */
+export const notchRadii = (r, w, h) => {
+  const concave = Math.max(0, Math.min(r, w, h));
+  // What is left on each axis once the concave corner has taken its share.
+  const ret = Math.max(0, Math.min(concave, h - concave, w - concave));
+  return { r: concave, rr: ret };
+};
+
+/**
+ * @typedef {{ w: number, h: number, r: number }} Notch
+ *   w/h — the CUT, i.e. the occupant plus its ring, not the occupant itself. r — the cut's own
+ *   corner radius, ideally concentric with the occupant's (the occupant's corner plus the ring).
+ */
+
+/**
+ * Build the panel outline.
+ *
+ * @param {object} spec
+ * @param {number} spec.w        panel width in px
+ * @param {number} spec.h        panel height in px
+ * @param {number} spec.radius   the card corner radius, used on every corner that has no notch
+ * @param {Partial<Record<'tl'|'tr'|'br'|'bl', Notch>>} [spec.notches]
+ * @returns {string} an SVG path, ready for `clip-path: path('...')`
+ */
+export const notchPath = ({ w, h, radius, notches = {} }) => {
+  const R = Math.max(0, Math.min(radius, w / 2, h / 2));
+  const n = (corner) => {
+    const it = notches[corner];
+    if (!it || !(it.w > 0) || !(it.h > 0)) return null;
+    // A cut cannot be larger than the panel it is bitten out of.
+    const cw = Math.min(it.w, w);
+    const ch = Math.min(it.h, h);
+    return { w: cw, h: ch, ...notchRadii(it.r, cw, ch) };
+  };
+
+  const seg = [];
+  const A = (rx, x, y, sweep) => seg.push(`A ${rx} ${rx} 0 0 ${sweep} ${x} ${y}`);
+  const L = (x, y) => seg.push(`L ${x} ${y}`);
+
+  // Walked CLOCKWISE from the top-left corner. Each corner either turns through the card radius or
+  // bites inward through its notch; the notch profiles below are the same shape rotated, which is
+  // why they read as four near-copies rather than four derivations.
+  const tl = n('tl'), tr = n('tr'), br = n('br'), bl = n('bl');
+
+  // ── start: just past the top-left corner, on the top edge ──────────────────────────────────
+  seg.push(`M ${tl ? tl.w + tl.rr : R} 0`);
+
+  // ── top edge → top-right corner ────────────────────────────────────────────────────────────
+  if (tr) {
+    L(w - tr.w - tr.rr, 0);
+    A(tr.rr, w - tr.w, tr.rr, 1);                   // convex return, into the cut
+    L(w - tr.w, tr.h - tr.r);
+    A(tr.r, w - tr.w + tr.r, tr.h, 0);              // concave inner corner — concentric with the occupant
+    L(w - tr.rr, tr.h);
+    A(tr.rr, w, tr.h + tr.rr, 1);                   // convex return, back to the side edge
+  } else {
+    L(w - R, 0);
+    A(R, w, R, 1);
+  }
+
+  // ── right edge → bottom-right corner ───────────────────────────────────────────────────────
+  if (br) {
+    L(w, h - br.h - br.rr);
+    A(br.rr, w - br.rr, h - br.h, 1);
+    L(w - br.w + br.r, h - br.h);
+    A(br.r, w - br.w, h - br.h + br.r, 0);
+    L(w - br.w, h - br.rr);
+    A(br.rr, w - br.w - br.rr, h, 1);
+  } else {
+    L(w, h - R);
+    A(R, w - R, h, 1);
+  }
+
+  // ── bottom edge → bottom-left corner ───────────────────────────────────────────────────────
+  if (bl) {
+    L(bl.w + bl.rr, h);
+    A(bl.rr, bl.w, h - bl.rr, 1);
+    L(bl.w, h - bl.h + bl.r);
+    A(bl.r, bl.w - bl.r, h - bl.h, 0);
+    L(bl.rr, h - bl.h);
+    A(bl.rr, 0, h - bl.h - bl.rr, 1);
+  } else {
+    L(R, h);
+    A(R, 0, h - R, 1);
+  }
+
+  // ── left edge → back to the start ──────────────────────────────────────────────────────────
+  if (tl) {
+    L(0, tl.h + tl.rr);
+    A(tl.rr, tl.rr, tl.h, 1);
+    L(tl.w - tl.r, tl.h);
+    A(tl.r, tl.w, tl.h - tl.r, 0);
+    L(tl.w, tl.rr);
+    A(tl.rr, tl.w + tl.rr, 0, 1);
+  } else {
+    L(0, R);
+    A(R, R, 0, 1);
+  }
+
+  seg.push('Z');
+  return seg.join(' ');
+};
+
+/**
+ * Is a chrome box actually sitting on this panel, and if so how far into which corner?
+ *
+ * Returns the cut a corner needs to seat that box — the occupant's own extent from the corner, plus
+ * one ring — or null when the box does not overlap the panel at all, which is the common case: on a
+ * split, half the running chrome sits on the text side and must not cut anything.
+ *
+ * The overlap test is deliberately generous by `slack`: a box that stops a pixel short of the panel
+ * still needs the cut, because the ring is what the reader sees, not the overlap.
+ *
+ * @param {DOMRect|null} box    the chrome element's rect
+ * @param {DOMRect} panel       the panel's rect
+ * @param {number} ring         the breathing gap between occupant and panel
+ * @param {number} slack        how close counts as touching
+ * @returns {{ corner: 'tl'|'tr'|'br'|'bl', w: number, h: number } | null}
+ */
+export const occupantFor = (box, panel, ring, slack = 2) => {
+  if (!box || !(box.width > 0) || !(box.height > 0)) return null;
+  const overlaps =
+    box.right > panel.left - slack && box.left < panel.right + slack &&
+    box.bottom > panel.top - slack && box.top < panel.bottom + slack;
+  if (!overlaps) return null;
+
+  // Which corner is it in? Whichever edges it is nearer to — a chrome box always sits in a corner,
+  // never mid-edge, so the nearer edge on each axis names the corner without ambiguity.
+  const nearLeft = Math.abs(box.left - panel.left) <= Math.abs(panel.right - box.right);
+  const nearTop = Math.abs(box.top - panel.top) <= Math.abs(panel.bottom - box.bottom);
+  const corner = `${nearTop ? 't' : 'b'}${nearLeft ? 'l' : 'r'}`;
+
+  // The cut is measured from the panel's own corner to the far side of the box, plus the ring. Using
+  // the box's FAR edge rather than its width is what makes a box that overhangs the panel's edge
+  // still produce a cut deep enough to clear it.
+  const w = (nearLeft ? box.right - panel.left : panel.right - box.left) + ring;
+  const h = (nearTop ? box.bottom - panel.top : panel.bottom - box.top) + ring;
+  return { corner, w: Math.max(0, w), h: Math.max(0, h) };
+};