@humanforest/slidev-theme 0.1.0

package/components/DataTable.vue

@@ -0,0 +1,244 @@
+<script setup>
+/*
+  A table sized for a room.
+
+  The 65-page Forest template catalogue puts a data table on two of its pages, and this theme had
+  no analog — which meant a slide wanting one had to hand-roll `<table>` markup, the exact thing a
+  brand guardrail exists to prevent. So: a small number of rows and columns, a row tall enough to
+  track across 1920px, figures in the tabular treatment, and a header that reads from the back.
+
+  ── FIGURES ────────────────────────────────────────────────────────────────────────────────────
+  Mohr ships no tabular figure set — measured in packages/tokens/type/type.css, its "1" is 13.01px
+  against "0" at 23.66px, and font-variant-numeric moves neither — so a column of Mohr numerals
+  cannot line up, whatever CSS is applied. That is why `.type-tabular` (the engine's own treatment,
+  used here rather than restated) swaps the family to --font-sans as well as switching the figure
+  set on. This component composes that class onto its numeric cells and never declares a
+  font-family on a cell of its own, so the class is what actually wins.
+
+  Kpi.vue makes the OPPOSITE call for the same reason, and both are right: its figure is a single
+  shout with nothing to align against, so it keeps the display face; a table's whole job is
+  alignment down a column, so it takes the sans. The formatting itself is shared — cellParts()
+  runs formatMetric(), the same function Kpi.vue formats with — so a figure in a table and the same
+  figure in a KPI are notated identically.
+
+  ── THE TWO CEILINGS ───────────────────────────────────────────────────────────────────────────
+  Rows truncate and say so; columns refuse to draw at all. components/tableRules.ts's own header
+  carries the full reasoning and the measurement behind ROW_CEILING — the short version is that
+  dropping a row is a shorter list, and dropping a column is a different claim.
+
+  Not a sortable, scrollable, paginated table. A slide has no cursor, and a presenter cannot hover.
+*/
+import { computed } from 'vue';
+import { cellParts, tableMessage, tableState, truncationNotice } from './tableRules';
+
+const props = defineProps({
+  /** The rows, in the order they should read — one plain object per row, keyed by column key. */
+  rows: { type: Array, required: true },
+  /** Columns in draw order: `[{ key, label, align, numeric, format, precision, unit }]`. Omit it and the columns are read off the rows' own keys. */
+  columns: { type: Array, default: undefined },
+  /** How many rows to draw before the rest are withheld and counted on the slide. Clamped to 1…7; the default 5 is what fits under a heading, and 7 needs a slide with no heading at all. */
+  maxRows: { type: Number, default: 5 },
+  /** Default notation for every numeric column: 'full' spells out every digit, 'compact' abbreviates (1.2m, 999k). A column's own `format` overrides it. */
+  format: { type: String, default: 'full', validator: (f) => ['full', 'compact'].includes(f) },
+  /** Locale the figures are formatted in, e.g. 'en-GB'. */
+  locale: { type: String, default: 'en-GB' },
+  /** A source line under the table, e.g. "TfL journey data, Q2 2026". Rendered, never a tooltip. */
+  note: { type: String, default: '' },
+  /** The sentence drawn in place of the table when there is nothing to draw. */
+  empty: { type: String, default: 'No data' },
+});
+
+const state = computed(() => tableState(props.rows, props.columns, props.maxRows, props.format));
+const message = computed(() => (state.value.kind === 'ready' ? null : tableMessage(state.value, props.empty)));
+const notice = computed(() =>
+  state.value.kind === 'ready' ? truncationNotice(state.value.total, state.value.rows.length) : null,
+);
+
+/* The whole table, resolved once: a row of `{ column, text, unit }` per data row. Built here rather
+   than called from the template so cellParts() runs once per cell instead of once per interpolation
+   — and so the shape the template walks is the same shape the tests assert on. */
+const grid = computed(() =>
+  state.value.kind === 'ready'
+    ? state.value.rows.map((row) =>
+        state.value.columns.map((column) => ({ column, ...cellParts(row?.[column.key], column, props.locale) })),
+      )
+    : [],
+);
+</script>
+
+<template>
+  <table v-if="state.kind === 'ready'" class="deck-data-table">
+    <!-- A real <caption>, not a sibling <div>: it belongs to the table, so a screen reader reaches
+         it with the table and it cannot drift away from the figure it qualifies. `caption-side`
+         puts it under the rows, which is where a source line and a truncation notice read. -->
+    <caption v-if="notice || note" class="deck-data-table-caption">
+      <span v-if="notice" class="deck-data-table-truncation">{{ notice }}</span>
+      <span v-if="notice && note" class="deck-data-table-sep" aria-hidden="true"> · </span>
+      <span v-if="note" class="deck-data-table-note">{{ note }}</span>
+    </caption>
+
+    <thead>
+      <tr>
+        <th
+          v-for="column in state.columns"
+          :key="column.key"
+          scope="col"
+          class="deck-data-table-head"
+          :class="`is-${column.align}`"
+        >{{ column.label }}</th>
+      </tr>
+    </thead>
+
+    <tbody>
+      <tr v-for="(cells, index) in grid" :key="index">
+        <!-- The first cell is the row's NAME, so it is a <th scope="row"> — the rest are data.
+             Semantics, not decoration: it is what lets a figure be announced with the row it
+             belongs to instead of on its own. No whitespace between a value and its unit — the
+             0.1em optical gap is set in CSS, because "12 %" is wrong in en-GB and a markup space
+             cannot be taken back. A multi-letter unit ("km") reads better named in the header. -->
+        <template v-for="(cell, position) in cells" :key="cell.column.key">
+          <th
+            v-if="position === 0"
+            scope="row"
+            class="deck-data-table-row-head"
+            :class="[`is-${cell.column.align}`, cell.column.numeric ? 'type-tabular' : null]"
+          >{{ cell.text }}<span v-if="cell.unit" class="deck-data-table-unit">{{ cell.unit }}</span></th>
+          <td
+            v-else
+            class="deck-data-table-cell"
+            :class="[`is-${cell.column.align}`, cell.column.numeric ? 'type-tabular' : null]"
+          >{{ cell.text }}<span v-if="cell.unit" class="deck-data-table-unit">{{ cell.unit }}</span></td>
+        </template>
+      </tr>
+    </tbody>
+  </table>
+
+  <!-- Same well ChartFrame.vue draws for a chart with nothing to plot: the honest empty state
+       occupies space rather than collapsing, so a slide does not silently look finished. -->
+  <div v-else class="deck-data-table-empty">{{ message }}</div>
+</template>
+
+<style scoped>
+/* Every rule here has to out-rank base.css's own `.slidev-layout table/th/td` block, which is sized
+   for a markdown table in a paragraph — 8px of padding, muted cell ink. A scoped compound selector
+   (`.deck-data-table th` → `.deck-data-table th[data-v-…]`, 0-2-1) clears `.slidev-layout th`
+   (0-1-1) on specificity alone, so nothing here needs !important and nothing depends on order. */
+.deck-data-table {
+  width: 100%;
+  /* `separate` with zero spacing, not `collapse`: collapse resolves adjacent borders against each
+     other and the header's accent rule loses half its weight to the first row's own border. */
+  border-collapse: separate;
+  border-spacing: 0;
+  /* Declared once, on the table — never on a cell. A numeric cell carries `.type-tabular`, whose
+     own font-family beats an INHERITED value but would lose to a scoped per-cell declaration. */
+  font-family: var(--type-deck-body-sm-family);
+  font-size: var(--type-deck-body-sm-size);
+  line-height: var(--type-deck-body-sm-line-height);
+  color: var(--deck-fg);
+}
+
+.deck-data-table th,
+.deck-data-table td {
+  /* The row height. 24px above and below 36px type at 1.5 measures 104px including the rule — a
+     band the eye can track across 1920px, and the figure ROW_CEILING is derived from. */
+  padding-block: var(--deck-space-3);
+  padding-inline: var(--deck-space-4);
+  vertical-align: baseline;
+}
+/* Flush at both edges, so the table's first character sits on the same vertical as the slide's
+   heading. The gutter is BETWEEN columns; it is not a margin on the block. */
+.deck-data-table tr > :first-child { padding-inline-start: 0; }
+.deck-data-table tr > :last-child { padding-inline-end: 0; }
+
+.deck-data-table .is-start { text-align: start; }
+.deck-data-table .is-center { text-align: center; }
+.deck-data-table .is-end { text-align: end; }
+
+.deck-data-table-head {
+  font-size: var(--type-deck-overline-size);
+  font-weight: var(--type-deck-overline-weight);
+  letter-spacing: var(--type-deck-overline-tracking);
+  line-height: var(--type-deck-overline-line-height);
+  text-transform: uppercase;
+  color: var(--deck-fg-muted);
+  /* 3px, not base.css's 2: this is the one rule in the table that has to read as a division rather
+     than a separator, and a 2px line at presenting scale is a hairline. */
+  border-bottom: 3px solid var(--deck-accent);
+  white-space: nowrap;
+}
+
+.deck-data-table tbody tr td,
+.deck-data-table tbody tr th {
+  border-bottom: 2px solid var(--deck-border);
+}
+
+.deck-data-table-row-head {
+  font-weight: var(--type-deck-label-weight);
+  color: var(--deck-fg);
+}
+
+.deck-data-table-cell {
+  /* Full ink, not base.css's --deck-fg-muted: a muted figure is a readable choice in a document and
+     the wrong one across a room, where the cell IS the message. */
+  color: var(--deck-fg);
+}
+/* Figures carry weight — the column an audience is actually reading. */
+.deck-data-table-cell.type-tabular {
+  font-weight: var(--type-deck-label-weight);
+}
+/* Full size, NOT the 0.5em shrink Kpi.vue gives its own unit, and the difference is the tier: Kpi's
+   figure is 96px, so a half-size unit is still 48px and reads as a considered pair. At a 36px cell
+   the same move produced a 25px glyph that read as a typo — rendered and looked at. The unit is
+   distinguished by ink here instead, which costs the figure no height and no alignment. */
+.deck-data-table-unit {
+  margin-inline-start: 0.1em;
+  color: var(--deck-fg-muted);
+  font-weight: var(--type-deck-body-sm-weight);
+}
+
+.deck-data-table-caption {
+  caption-side: bottom;
+  text-align: start;
+  /* space-2, not space-3. The caption's own height budget below is measured against the safe-area
+     floor, and the same arithmetic applies above it: at space-3 the truncation notice sat 92px from
+     the bottom edge, which cleared the old 90px text inset and misses the current 96px one by 4px.
+     scripts/deckAudit.ts caught it on slides 50, 51 and 52. 16px still separates the caption from
+     the last row by a full rung and buys 8px of clearance. */
+  padding-top: var(--deck-space-2);
+  font-size: var(--type-deck-caption-size);
+  line-height: var(--type-deck-caption-line-height);
+}
+/* ONE wrapping line, not a stacked pair, and that is a measured decision rather than a preference:
+   a caption line costs 50px, and 307 (heading) + 68 (header row) + 5 x 104 (rows) + two caption
+   lines is 1019 against a 990 safe-area floor — scripts/deckAudit.ts caught exactly that, 30px past
+   the bottom inset, on the first pass of this component. Inline spans on one line cost 74px total
+   and still wrap honestly on a narrow column, where the overflow would be visible rather than
+   silent. Nothing here sets `display`: a <caption> is a table-caption box, and forcing it to flex
+   takes it out of the table's own caption flow. */
+/* The truncation notice takes the accent and the row-label weight, one step louder than the source
+   line beside it: "there is more data than this" is a statement about the figure itself, not a
+   footnote about where it came from. */
+.deck-data-table-truncation {
+  font-weight: var(--type-deck-label-weight);
+  color: var(--deck-accent);
+}
+.deck-data-table-sep,
+.deck-data-table-note {
+  color: var(--deck-fg-subtle);
+}
+
+/* Lifted from ChartFrame.vue's own empty state, deliberately identical: a table with nothing to
+   draw and a chart with nothing to plot are the same failure and should look like it. */
+.deck-data-table-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: var(--deck-space-5);
+  background: var(--deck-surface);
+  border-radius: var(--deck-radius-nested);
+  color: var(--deck-fg-muted);
+  font-size: var(--type-deck-body-size);
+  line-height: var(--type-deck-body-line-height);
+}
+</style>

package/components/DeckMap.vue

@@ -0,0 +1,409 @@
+<script setup>
+/*
+  A LIVE Mapbox GL map on a slide, on Forest's own house style.
+
+  ── WHY LIVE, AND NOT A PICTURE ────────────────────────────────────────────────────────────────
+  The Static Images API was tried first and DROPPED: on the Forest style it answers HTTP 200 with a
+  valid PNG that draws nothing — the style imports Standard, and Standard's imports do not compose
+  through the static renderer. A screenshot pasted into a deck goes stale the day the style is
+  republished, and cannot carry the marks a slide wants to put on it. So this is the real GL map.
+
+  ── THE THREE THINGS THAT MAKE A GL MAP SAFE IN A DECK ─────────────────────────────────────────
+
+  ★★ `preserveDrawingBuffer: true`, OR THE EXPORT IS BLANK. `slidev export` drives a real browser
+  and screenshots it. WebGL is allowed to discard the drawing buffer after each composite, and by
+  the time the PDF renderer reads the canvas back there is nothing in it — measured: a map that is
+  correct on screen prints as an empty rectangle, with no error anywhere. The flag costs a little
+  memory and is the whole reason a map can be in a deck at all.
+
+  ★ NOT INTERACTIVE BY DEFAULT. A presenter scrolling past a slide should not leave the map at some
+  other city for the rest of the talk, and a stray trackpad nudge during a talk is unrecoverable in
+  front of a room. `interactive` opts back in for a live demo.
+
+  ★ AN HONEST EMPTY STATE. A map with no token is a blank rectangle that looks like a bug in the
+  deck. Without `VITE_MAPBOX_TOKEN` — which is the case in CI, deliberately, since no token is
+  committed — this draws a panel saying exactly that instead. It keeps the audit deterministic: the
+  gate measures the same geometry on every run rather than depending on a network and a secret.
+
+  ── THE TOKEN ─────────────────────────────────────────────────────────────────────────────────
+  Read from `import.meta.env.VITE_MAPBOX_TOKEN`, the same name the rest of this repo uses, or passed
+  per-slide as `access-token`. A Mapbox `pk.…` token is a PUBLIC token and is designed to ship in a
+  client bundle — but note it BAKES INTO `dist/` at build time, so a deck built with one and then
+  handed to somebody carries it. Scope and restrict the token by URL in the Mapbox account; do not
+  reach for a secret `sk.…` token here, which must never be in a bundle.
+
+  The style is imported rather than restated: packages/ui/src/map/style.ts is a pure module with no
+  imports of its own, so the deck can share the VALUE without pulling in the product's component
+  layer — the same reach across the package boundary Kpi.vue and IconTile.vue already make.
+*/
+import { onBeforeUnmount, onMounted, ref, shallowRef } from 'vue';
+import mapboxgl from 'mapbox-gl';
+import 'mapbox-gl/dist/mapbox-gl.css';
+import { FOREST_MAP_STYLE } from '@humanforest/ui/map/style';
+
+const props = defineProps({
+  /** Centre longitude. Defaults to central London, which is the only city this deck is ever about. */
+  lng: { type: Number, default: -0.1005 },
+  /** Centre latitude. */
+  lat: { type: Number, default: 51.5155 },
+  /** Zoom. 10 holds most of Greater London; 13 is a borough; 15 is a street. */
+  zoom: { type: Number, default: 11 },
+  /** Tilt in degrees. Above 45 the horizon enters the frame and a slide loses its edge. */
+  pitch: { type: Number, default: 0 },
+  /** Rotation in degrees. */
+  bearing: { type: Number, default: 0 },
+  /** Mapbox style URL. Defaults to Forest's own house style. */
+  mapStyle: { type: String, default: FOREST_MAP_STYLE },
+  /**
+   * How the basemap is lit: `day` or `night`. This is what makes a map read as dark — the style is
+   * the same Forest basemap either way, so a dark slide keeps the brand map rather than swapping
+   * to a second one that would have to be kept in sync.
+   *
+   * ★ TWO VALUES, WHERE THE BASEMAP OFFERS FOUR. Mapbox also lights `dawn` and `dusk`, and
+   * packages/ui's FMap passes all four through because a product surface can want a time of day.
+   * A deck has one axis and it is the REGISTER: a slide is light or it is `deck-dark`, and there is
+   * no dusk register for a dusk map to belong to. Narrowed here rather than passed through, because
+   * a specimen book has to draw every value it claims and two of those four would be drawn to
+   * satisfy a gate rather than to show anything.
+   *
+   * ★ NO `auto` EITHER, where FMap has one. That follows the APP's colour mode; a deck has none —
+   * the register belongs to the slide — so a slide that wants a dark map says which one.
+   *
+   * ★★ APPLIED AT CREATION, NOT AFTER `style.load`. Setting it later paints the map in day and
+   * corrects it a beat afterwards, which is a visible flash of the wrong register on every load —
+   * and on an exported slide it is whichever frame the capture happened to catch.
+   */
+  lightPreset: {
+    type: String,
+    default: 'day',
+    validator: (v) => ['day', 'night'].includes(v),
+  },
+  /** Public `pk.…` token. Falls back to `VITE_MAPBOX_TOKEN` from the build environment. */
+  accessToken: { type: String, default: '' },
+  /** Plot height in px. */
+  /** Height in px. **0 fills the parent** — see `.deck-map.is-fill` below for when to reach for it. */
+  height: { type: Number, default: 560 },
+  /** Let the presenter pan and zoom. Off by default — see the note above. */
+  interactive: { type: Boolean, default: false },
+  /**
+   * Points to draw, `[{ lng, lat }]`. Rendered as one GeoJSON circle layer in the deck accent
+   * rather than as N `mapboxgl.Marker` DOM nodes: markers are absolutely-positioned HTML that the
+   * geometry pass would have to measure and the export would have to composite separately, and a
+   * layer is one paint inside the canvas the rest of the slide already accounts for.
+   */
+  marks: { type: Array, default: () => [] },
+  /** Sentence drawn in place of the map when it cannot be shown. */
+  empty: { type: String, default: 'No Mapbox token in this build — set VITE_MAPBOX_TOKEN to draw the map.' },
+});
+
+const token = props.accessToken || import.meta.env?.VITE_MAPBOX_TOKEN || mapboxgl.accessToken || '';
+const holder = ref(null);
+const map = shallowRef(null);
+/* A style that never arrives leaves a blank rectangle: a revoked token, a bad style id, a room with
+   no network. Held as a message so the frame can say WHICH rather than showing nothing. */
+const ready = ref(false);
+const failure = ref(token ? null : props.empty);
+
+const MARK_SOURCE = 'deck-map-marks';
+
+function addMarks(m) {
+  if (!props.marks.length) return;
+  m.addSource(MARK_SOURCE, {
+    type: 'geojson',
+    data: {
+      type: 'FeatureCollection',
+      features: props.marks.map((p) => ({
+        type: 'Feature',
+        geometry: { type: 'Point', coordinates: [p.lng, p.lat] },
+        properties: {},
+      })),
+    },
+  });
+  m.addLayer({
+    id: `${MARK_SOURCE}-circle`,
+    type: 'circle',
+    source: MARK_SOURCE,
+    /*
+      STACKING ORDER, and only that — the black marks below were a lighting problem, not this one.
+      The Forest style imports Mapbox Standard, which is SLOTTED: a layer added with no slot sits
+      low in the stack and the basemap's own labels can print over it. `top` is the value
+      packages/ui names MAP_SLOT.mark — "every mark: vehicles, places, counted bays, clusters,
+      selection rings" — spelled as a literal here rather than imported, for the same reason the
+      rest of this deck shares VALUES with the product and not runtime.
+    */
+    slot: 'top',
+    paint: {
+      // Read off the deck's own custom properties at mount. A GL paint property is a value in a
+      // WebGL program, not a CSS declaration, so it cannot be a var() reference and does not follow
+      // a register flip on its own — which is why a deck map is a light-register device.
+      'circle-radius': 10,
+      'circle-color': readVar('--deck-accent', '#046c4c'),
+      'circle-stroke-width': 4,
+      'circle-stroke-color': readVar('--deck-bg', '#fff9f2'),
+      /*
+        ★★ EMISSIVE, OR THE NIGHT PRESET LIGHTS THE MARK INTO THE GROUND. Mapbox Standard is a LIT
+        style: it carries a 3D lighting model, and a layer at the default emissive strength of 0 is
+        shaded by the scene like anything else in it. Under `lightPreset: night` the ambient light
+        is nearly black, so a mark declared #3bd996 rendered rgb(0,14,24) — measured at all four
+        projected centres, while `getPaintProperty` cheerfully reported the bright green it had been
+        given. The colour was never wrong and the slot was never wrong; the mark was being LIT.
+
+        1 means "emit this colour, ignore the scene", which is what a mark is: it belongs to the
+        deck's palette rather than to the basemap's world, and it has to read the same on both
+        presets. Costs nothing on `day`, where the ambient light is already near white.
+      */
+      'circle-emissive-strength': 1,
+    },
+  });
+}
+
+/*
+  ★★ A DECK COLOUR REACHES MAPBOX ONLY AFTER BEING CONVERTED OUT OF P3. This design system serves
+  its palette in Display P3 — `getComputedStyle` hands back `color(display-p3 .1815 .4169 .3069)` —
+  and Mapbox's style spec parser accepts hex, rgb(), hsl() and the named colours, nothing else. It
+  does not merely ignore what it cannot parse: `addLayer` THROWS, the style never finishes loading,
+  and the whole map is blank. Measured, and it is the exact error this component's own panel
+  reported: `layers.deck-map-marks-circle.paint.circle-color: color expected,
+  "color(display-p3 .1815 .4169 .3069)" found`.
+
+  The canvas 2D context is the conversion, and it needs no library. That narrowing is a real loss —
+  a P3 green outside the sRGB gamut comes back clamped — but it is the right loss here, because a
+  WebGL basemap is being asked for an sRGB value either way.
+
+  ★★ READING `fillStyle` BACK IS NO LONGER THE CONVERSION, AND THAT CHANGED UNDER US. This used to
+  assign the colour and return `ctx.fillStyle`, on the documented behaviour that the property
+  normalises what it stores to `#rrggbb`. Current Chrome PRESERVES the `color()` form: measured,
+  assigning `color(display-p3 0.1815 0.4169 0.3069)` reads back byte-identical, not as a hex. So
+  this handed Mapbox the very string the block above says it cannot parse, `addLayer` threw, and
+  the marks silently stopped drawing — `getSource` still returned the source, because a source
+  carries no colour, and `getLayer` returned undefined. Nothing was logged: the throw happens
+  inside the `load` handler, and the component's own error path only reports what Mapbox emits.
+
+  RASTERISING is the conversion that survives: fill one pixel and read it back, which forces the
+  paint through sRGB whatever the serialization does. Alpha is carried through as `rgba()` because
+  the style spec takes that and a hex would drop it.
+*/
+function toSrgb(value, fallback) {
+  try {
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return fallback;
+    // A context's initial fillStyle is '#000000'; if the assignment is rejected as unparseable the
+    // property keeps its previous value, so an unchanged black is how a failure shows up here.
+    ctx.fillStyle = '#000000';
+    ctx.fillStyle = value;
+    if (ctx.fillStyle === '#000000' && value.trim() !== '#000000') return fallback;
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    const hex = (n) => n.toString(16).padStart(2, '0');
+    return a === 255 ? `#${hex(r)}${hex(g)}${hex(b)}` : `rgba(${r}, ${g}, ${b}, ${Number((a / 255).toFixed(3))})`;
+  } catch {
+    return fallback;
+  }
+}
+
+function readVar(name, fallback) {
+  if (typeof window === 'undefined' || !holder.value) return fallback;
+  const v = getComputedStyle(holder.value).getPropertyValue(name).trim();
+  return v ? toSrgb(v, fallback) : fallback;
+}
+
+let sizeWatcher = null;
+
+onMounted(() => {
+  if (!token || !holder.value) return;
+  mapboxgl.accessToken = token;
+  let m;
+  try {
+    m = new mapboxgl.Map({
+      container: holder.value,
+      style: props.mapStyle,
+      center: [props.lng, props.lat],
+      zoom: props.zoom,
+      pitch: props.pitch,
+      bearing: props.bearing,
+      interactive: props.interactive,
+      config: { basemap: { lightPreset: props.lightPreset } },
+      // ★★ See the header. Without this the exported PDF is an empty rectangle.
+      preserveDrawingBuffer: true,
+      // A deck is never a place for the Mapbox logo to be clicked, but attribution is a licence
+      // term rather than a design choice — it stays, compact.
+      attributionControl: true,
+    });
+  } catch (e) {
+    failure.value = `Map could not start — ${String(e?.message ?? e)}`;
+    return;
+  }
+  map.value = m;
+  /*
+    ★★ ONLY A PRE-LOAD ERROR IS FATAL, and getting this wrong DESTROYS A WORKING MAP. Mapbox emits
+    `error` for plenty of things that are not the map failing: a blocked telemetry beacon
+    (events.mapbox.com answering with status 0 behind a content blocker — measured, that is exactly
+    what happens in the audit's own browser), a single tile that 404s, a sprite that arrives late.
+    Treating every one of them as fatal set `failure`, which swapped the holder out for the panel —
+    and because the holder is the map's CONTAINER, a live map with its style loaded and its tiles
+    painted was torn out of the document because a beacon was refused.
+
+    After `load` the map is a map. An error past that point is logged for whoever opens the console
+    and changes nothing on the slide.
+  */
+  m.on('error', (e) => {
+    const message = String(e?.error?.message ?? 'style or token rejected');
+    if (ready.value || failure.value) {
+      console.warn(`DeckMap: non-fatal Mapbox error after load — ${message}`);
+      return;
+    }
+    failure.value = `Map failed to load — ${message}`;
+  });
+  m.on('load', () => {
+    ready.value = true;
+    addMarks(m);
+    // Slidev mounts neighbouring slides off-screen, where a container can measure zero. One resize
+    // once the style is up is what stops a map arriving at 0x0 and staying there.
+    m.resize();
+  });
+
+  /*
+    ★★ AND A RESIZE OBSERVER, BECAUSE ONE RESIZE ON `load` IS NOT ENOUGH — measured, not guessed.
+    Slidev mounts neighbouring slides, so this map is usually built while its slide is off-screen and
+    the container measures zero. Mapbox does not wait: it falls back to its default 400x300 canvas.
+    The `load` handler above then fires while the container is STILL zero, so the one corrective
+    resize corrects nothing and the canvas keeps 400x300 for the life of the slide.
+
+    Reproduced by arriving the way a presenter does, transitioning in from the slide before rather
+    than loading the URL directly: container 1740x520, canvas 400x300. A direct load looks perfect,
+    which is exactly why this survived — the map is only wrong on the path nobody tests.
+
+    On screen that is a strip of tiles filling the left quarter of a full-width grey box, which
+    reads as a half-loaded map rather than as a sizing bug.
+
+    So watch the box instead of guessing when it settles. The guard is on a NON-ZERO measurement:
+    the observer fires for the 0x0 state too, and resizing to zero is what put us here. No loop is
+    possible — resize() changes the CANVAS, never the holder this observes.
+  */
+  if (typeof ResizeObserver !== 'undefined') {
+    sizeWatcher = new ResizeObserver(() => {
+      const el = holder.value;
+      if (!el || !map.value) return;
+      if (el.clientWidth > 0 && el.clientHeight > 0) map.value.resize();
+    });
+    sizeWatcher.observe(holder.value);
+  }
+});
+
+onBeforeUnmount(() => {
+  sizeWatcher?.disconnect();
+  sizeWatcher = null;
+  map.value?.remove();
+  map.value = null;
+});
+</script>
+
+<template>
+  <div class="deck-map" :class="{ 'is-fill': !height }" :style="height ? { height: `${height}px` } : undefined">
+    <div v-if="failure" class="deck-map-empty">{{ failure }}</div>
+    <div v-else ref="holder" class="deck-map-canvas" />
+  </div>
+</template>
+
+<style scoped>
+/*
+  ★★ THE NOTCH HAS TO BE HANDED DOWN TO THE CANVAS, because an ancestor does not clip one.
+
+  split.vue cuts its figure's corner with a `clip-path` so the running Forest mark sits in the
+  cut-out. That works for every other figure and does nothing here: a composited WebGL canvas is not
+  clipped by an ancestor's clip-path, so the mark was drawn straight over a live map while the
+  element around it was correctly cut. The same reason the map's own corner RADIUS has to land on
+  `.mapboxgl-map` rather than on anything above it.
+
+  `inherit` rather than a copy, so there is one path and this file never computes a shape. It walks
+  the chain a step at a time — the clip is on the figure, the grandparent — and it is safe when
+  there is no notch, because inheriting nothing computes to `none`. It is only correct because the
+  three boxes are the same size: measured 347x302 at figure, .deck-map and .mapboxgl-map alike,
+  which is what `is-fill` guarantees. A map given a fixed height inside a notched figure would be
+  clipped against a path drawn for a taller box.
+*/
+.deck-map {
+  clip-path: inherit;
+}
+.deck-map :deep(.mapboxgl-map) {
+  clip-path: inherit;
+}
+
+/*
+  `height: 0` means FILL — take whatever the parent gives, rather than a number the slide had to
+  guess. The same convention Carousel's `width: 0` already uses for its column.
+
+  ★ It exists for `split` at `media: figure`, where the cell height is the layout's to decide and a
+  slide that wrote its own pixel figure would be encoding the anchor arithmetic by hand. With a
+  number, the map is that tall and the cell's leftover space sits empty below it.
+*/
+.deck-map.is-fill {
+  height: 100%;
+}
+.deck-map {
+  width: 100%;
+  border-radius: var(--deck-radius-nested);
+  /* ★ THE RADIUS HAS TO CLIP A COMPOSITED CANVAS. A WebGL canvas is composited on its own layer, so
+     a rounded corner on an ANCESTOR does not clip it — the map paints square corners over the
+     rounding and the slide looks broken at four points. `overflow: hidden` here plus the same
+     radius on mapbox's own container below is what actually cuts it. */
+  overflow: hidden;
+  background: var(--deck-surface);
+}
+.deck-map-canvas {
+  width: 100%;
+  height: 100%;
+  border-radius: var(--deck-radius-nested);
+  overflow: hidden;
+}
+.deck-map-canvas :deep(.mapboxgl-map) {
+  border-radius: var(--deck-radius-nested);
+}
+
+.deck-map-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  height: 100%;
+  padding: var(--deck-space-5);
+  color: var(--deck-fg-muted);
+  font-size: var(--type-deck-body-size);
+  line-height: var(--type-deck-body-line-height);
+}
+
+/* Mapbox's own chrome is sized for a browser window. The attribution is a licence term and stays,
+   but at 10px on a projector it is noise rather than a credit — the deck's smallest real tier is
+   what it takes instead.
+
+   ★★ IT NEEDS ITS OWN GROUND, AND THAT IS A DETERMINISM FIX, NOT A STYLING ONE. Text sitting
+   straight on the basemap is measured by scripts/deckAudit.ts against whatever is PAINTED beneath
+   it, and a live map paints asynchronously over the network — so the same slide scored 12 contrast
+   failures on one run and none on the next, purely on how far the tiles had got. A near-opaque
+   ground under the credit makes the pairing a constant: the audit measures ink against a known
+   surface instead of against a race. */
+.deck-map :deep(.mapboxgl-ctrl-attrib) {
+  background: var(--deck-bg);
+  border-radius: var(--deck-radius-control);
+  padding: 0 var(--deck-space-2);
+}
+/* ★ A FIXED px SIZE, AND DELIBERATELY NOT A DECK TYPE ROLE. This took
+   `var(--type-deck-caption-size)` first, on the reasoning that every other piece of text in the
+   deck takes a role — and the roles are sized for a ROOM, so the credit rendered at caption tier
+   and ran straight out of the map box, wider than the picture it was crediting.
+
+   The attribution is the one string on a slide that is a LICENCE TERM rather than content: Mapbox
+   requires it to be legible and present, and requires nothing more than that. It cannot be removed,
+   and it should not be room-scale either — 16px on the 1920 canvas is readable up close, which is
+   the standard the term is written to, and invisible from the back, which is where the map is the
+   subject and the credit is not. */
+.deck-map :deep(.mapboxgl-ctrl-attrib),
+.deck-map :deep(.mapboxgl-ctrl-attrib a) {
+  font-size: 16px;
+  line-height: 1.4;
+  color: var(--deck-fg-muted);
+}
+</style>