@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/logo/FSubLogo.vue

@@ -0,0 +1,214 @@
+<script setup lang="ts">
+// Sub-brand lockup — "<lead> [WORD]", composed from the glyph atlas in @humanforest/tokens. Any word,
+// any lead, no build step and no font dependency: the SVG carries OUTLINES only, never <text>, so it
+// renders the same in a browser with no brand fonts, in a downloaded file, and pasted into Figma.
+//
+// The default lead is the drawn wordmark. Name any other and it's set in GT Haptik Bold at the
+// wordmark's own size — with the drawn f substituted for every f, and GT's flat ascenders (b d h k l)
+// trimmed level with the t, which is where the drawn f stops. Both rules live in setWord().
+//
+// Variants: lockup (lead + keycap) · badge (keycap alone) · icon (square, first letter) · joined
+// (lead + sub-brand butted on as one word).
+import { computed } from 'vue';
+import { WORDMARK_PATHS, WORDMARK_W, WORDMARK_H } from '@humanforest/tokens/logo';
+import { setWord, runInk } from '@humanforest/tokens/glyphs';
+import {
+  SUBLOGO, SUBLOGO_MOHR_SIZE, SUBLOGO_GT_SIZE, SUBLOGO_BASELINE,
+  keycapGeometry, iconGeometry, skewTransform,
+} from '@humanforest/tokens/sublogo';
+
+const props = withDefaults(defineProps<{
+  /** The sub-brand — set in the keycap. Upper-cased; Mohr is only ever used uppercase. */
+  word: string;
+  /** The word ahead of the keycap. 'forest' (default) draws the wordmark; anything else is set. */
+  lead?: string;
+  /** Colour ramp the keycap lives on. */
+  family?: string;
+  /** Keycap fill level. */
+  face?: number;
+  /** Keycap word level — omit for white, set it when the face is too light to hold white. */
+  ink?: number | null;
+  /** Border level — omit to sit on 950 and lighten to 300 in dark. */
+  line?: number | null;
+  /** Border level in dark, when a pinned `line` should shift rather than hold. */
+  lineDark?: number | null;
+  variant?: 'lockup' | 'badge' | 'icon' | 'joined';
+  /** Rendered height in px; width follows. */
+  size?: number;
+}>(), {
+  lead: 'forest', family: 'forest', face: SUBLOGO.faceLevel, ink: null, line: null, lineDark: null,
+  variant: 'lockup', size: 40,
+});
+
+const word = computed(() => props.word.toUpperCase());
+const isWordmarkLead = computed(() => props.lead.toLowerCase() === 'forest');
+const isIcon = computed(() => props.variant === 'icon');
+const isJoined = computed(() => props.variant === 'joined');
+
+// ── The runs ── all synchronous: the outlines are data, so nothing waits on a font to load. That also
+// means an instance mounted in an app shell, before any stylesheet lands, draws correctly first frame.
+const gtRun = (text: string, x = 0) =>
+  setWord(text, { font: 'gt', size: SUBLOGO_GT_SIZE, x, baseline: SUBLOGO_BASELINE, brandF: true });
+
+const lead = computed(() => (isWordmarkLead.value ? null : gtRun(props.lead.toLowerCase())));
+// the keycap gap is measured off the lead's INK; the joined sub-brand off its ADVANCE, so the letter
+// spacing carries through the seam rather than butting ink to ink
+const leadW = computed(() => lead.value?.inkRight ?? WORDMARK_W);
+const leadAdvance = computed(() => lead.value?.advance ?? WORDMARK_W);
+
+// keycap word, set at the origin and moved into place once the box it sits in is known
+const keycap = computed(() => setWord(word.value, { font: 'mohr', size: SUBLOGO_MOHR_SIZE }));
+const key = computed(() => keycapGeometry(leadW.value, runInk(keycap.value)));
+
+const joined = computed(() => gtRun(word.value.toLowerCase(), leadAdvance.value));
+
+const ic = iconGeometry();
+// the icon letter is sized to the square's cap height, so it's set twice: once to measure, once at size
+const icon = computed(() => {
+  const probe = setWord(word.value[0], { font: 'mohr', size: SUBLOGO_MOHR_SIZE });
+  const size = (SUBLOGO_MOHR_SIZE * ic.letterCap) / (probe.inkBottom - probe.inkTop);
+  const run = setWord(word.value[0], { font: 'mohr', size });
+  return {
+    run,
+    x: ic.cx - (run.inkLeft + (run.inkRight - run.inkLeft) / 2),
+    y: ic.cy - (run.inkTop + (run.inkBottom - run.inkTop) / 2),
+  };
+});
+
+// ── Geometry ──
+const viewBox = computed(() => {
+  if (isIcon.value) return `0 0 ${ic.side} ${ic.side}`;
+  if (isJoined.value) return `0 0 ${Math.ceil(joined.value.inkRight + 6)} ${WORDMARK_H}`;
+  if (props.variant === 'badge') return `${key.value.badgeVB[0]} 0 ${key.value.badgeVB[1]} ${WORDMARK_H}`;
+  return `0 0 ${key.value.fullW} ${WORDMARK_H}`;
+});
+const rect = computed(() => {
+  const k = key.value;
+  return isIcon.value
+    ? { x: ic.off, y: ic.off, w: ic.sq, h: ic.sq, t: skewTransform(ic.cx, ic.cy) }
+    : { x: k.boxX, y: k.boxY, w: k.boxW, h: k.boxH, t: skewTransform(k.cx, k.cy) };
+});
+
+// One clip per instance trims the flat ascenders. The id must be unique per mark — two lockups on a
+// page would otherwise share a def, and a downloaded file has to carry its own.
+const clipId = `fsub-cut-${++uid}`;
+// the trim line: the t's ink top, which is where the drawn f stops
+const CUT_Y = setWord('t', { font: 'gt', size: SUBLOGO_GT_SIZE, baseline: SUBLOGO_BASELINE }).cutY;
+
+// ── Colour ── emitted as light/dark PAIRS resolved in CSS below, so a mark follows a forced .light or
+// .dark island as well as the page theme; a value derived in script computes once and strands islands.
+const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+const ramp = (lvl: number) => `var(--color-${props.family}-${lvl})`;
+const faceVar = computed(() => ramp(props.face));
+const inkVar = computed(() => (props.ink != null ? ramp(props.ink) : 'white'));
+const lineLight = computed(() => ramp(props.line ?? SUBLOGO.lineLevel));
+const lineDarkVar = computed(() => ramp(props.lineDark ?? (props.line != null ? props.line : 300)));
+// JOINED sets the sub-brand as TYPE on the page surface, so it contrasts with the PAGE rather than sit
+// on a face of its own. A seed pins `ink` exactly when its face is too light to hold white — and a face
+// that light is unreadable as type on a light page. Those seeds own a pair already, so take whichever
+// opposes the surface; the rest step one level lighter in dark to keep their pop.
+const joinedLight = computed(() => ramp(props.ink != null ? props.ink : props.face));
+const joinedDark = computed(() => {
+  if (props.ink != null) return ramp(props.face);
+  const i = STEPS.indexOf(props.face);
+  return ramp(i > 0 ? STEPS[i - 1] : props.face);
+});
+
+const vars = computed(() => ({
+  '--fsub-line-l': lineLight.value,
+  '--fsub-line-d': lineDarkVar.value,
+  '--fsub-joined-l': joinedLight.value,
+  '--fsub-joined-d': joinedDark.value,
+  height: `${props.size}px`,
+  width: 'auto',
+  overflow: isJoined.value ? 'visible' : undefined,
+}));
+
+const label = computed(() => `${props.lead} ${word.value}`);
+</script>
+
+<script lang="ts">
+// module-scoped so every instance on a page gets its own clip id
+let uid = 0;
+</script>
+
+<template>
+  <svg
+    class="fsub" :viewBox="viewBox" :style="vars"
+    fill="none" xmlns="http://www.w3.org/2000/svg" :aria-label="label"
+  >
+    <defs>
+      <clipPath :id="clipId">
+        <!-- trims the flat ascenders level with the t; everything from that line down survives -->
+        <rect :x="-WORDMARK_W" :y="CUT_Y" :width="WORDMARK_W * 8" :height="WORDMARK_H * 4" />
+      </clipPath>
+    </defs>
+
+    <!-- Each glyph is wrapped so the clip lands in the SVG's own space. `clip-path` resolves against
+         the user space of the element carrying it, and the glyph paths carry their own translate+scale
+         — clipping them directly would measure the trim line in glyph units. -->
+    <!-- JOINED — lead in the theme ink, sub-brand butted on in the face colour -->
+    <template v-if="isJoined">
+      <template v-if="isWordmarkLead">
+        <path v-for="(p, i) in WORDMARK_PATHS" :key="i" :d="p" fill="currentColor" />
+      </template>
+      <g
+        v-for="(g, i) in lead?.glyphs ?? []" :key="`l${i}`"
+        fill="currentColor" :clip-path="g.cut ? `url(#${clipId})` : undefined"
+      ><path :d="g.d" :transform="g.transform" /></g>
+      <g
+        v-for="(g, i) in joined.glyphs" :key="`j${i}`"
+        class="fsub-joined" :clip-path="g.cut ? `url(#${clipId})` : undefined"
+      ><path :d="g.d" :transform="g.transform" /></g>
+    </template>
+
+    <template v-else>
+      <!-- lead word — reverses with the theme via currentColor (lockup only) -->
+      <template v-if="variant === 'lockup'">
+        <template v-if="isWordmarkLead">
+          <path v-for="(p, i) in WORDMARK_PATHS" :key="i" :d="p" fill="currentColor" />
+        </template>
+        <g
+          v-for="(g, i) in lead?.glyphs ?? []" :key="`l${i}`"
+          fill="currentColor" :clip-path="g.cut ? `url(#${clipId})` : undefined"
+        ><path :d="g.d" :transform="g.transform" /></g>
+      </template>
+
+      <!-- keycap: coloured face, theme-aware border, the word set on top -->
+      <rect
+        :transform="rect.t" :x="rect.x" :y="rect.y" :width="rect.w" :height="rect.h"
+        :rx="SUBLOGO.radius" :fill="faceVar" class="fsub-line" :stroke-width="SUBLOGO.border"
+      />
+      <g v-if="isIcon" :transform="`translate(${icon.x} ${icon.y})`" :fill="inkVar">
+        <path v-for="(g, i) in icon.run.glyphs" :key="i" :d="g.d" :transform="g.transform" />
+      </g>
+      <g v-else :transform="`translate(${key.wordAt.x} ${key.wordAt.y})`" :fill="inkVar">
+        <path v-for="(g, i) in keycap.glyphs" :key="i" :d="g.d" :transform="g.transform" />
+      </g>
+    </template>
+  </svg>
+</template>
+
+<!-- NOT scoped, deliberately. The mode switch needs `.dark .fsub` — an ancestor plus the element — and
+     Vue's scoped compiler rewrites `:global(.dark) .fsub` to a bare `.dark`, dropping the descendant.
+     That lands the variable on <html>, where the element's own declaration then out-specifies it and
+     every mark stays stuck in light. The classes are namespaced instead. -->
+<style>
+/* Light/dark resolved in CSS, not JS: a value derived in script computes once and strands any forced
+   .light or .dark island on the page's own mode. `.light` comes last so a light island inside a dark
+   page wins the tie. */
+.fsub {
+  --fsub-line: var(--fsub-line-l);
+  --fsub-joined: var(--fsub-joined-l);
+}
+.dark .fsub {
+  --fsub-line: var(--fsub-line-d);
+  --fsub-joined: var(--fsub-joined-d);
+}
+.light .fsub {
+  --fsub-line: var(--fsub-line-l);
+  --fsub-joined: var(--fsub-joined-l);
+}
+.fsub-line { stroke: var(--fsub-line); }
+.fsub-joined { fill: var(--fsub-joined); }
+</style>

package/packages/ui/src/logo/index.ts

@@ -0,0 +1,8 @@
+// The brand mark as a component. The primitives it draws from live in @humanforest/tokens
+// (src/logo.ts), beside the generator that bakes the same paths into the shipped SVGs, so the
+// component and packages/tokens/logos/*.svg cannot disagree about the shape of the mark.
+export { default as FLogo } from './FLogo.vue';
+// The sub-brand lockup composes any lead + word from the glyph atlas in @humanforest/tokens. It emits
+// OUTLINES, never <text>, so it needs no font loaded and no build step — and the SVG exporter composes
+// from the same atlas, which is why a downloaded mark is the same shapes rather than a second render.
+export { default as FSubLogo } from './FSubLogo.vue';

package/packages/ui/src/map/FMap.vue

@@ -0,0 +1,355 @@
+<script setup lang="ts">
+// FMap — Forest's map primitive. Wraps Mapbox GL JS with the Forest style (which imports Standard) and
+// owns the boilerplate
+// every surface would otherwise repeat: the access-token guard (with a setup fallback), a lazy WebGL
+// init (the context is created only when the frame nears the viewport, so a page with several maps
+// doesn't pay for all of them up front), the load fade, cooperative gestures (so a page scrolls past
+// the map), and teardown. Emits `ready(map)` once the style has loaded — add sources, layers, config
+// and interactions in that handler.
+//
+// Token: pass `access-token`, or set `mapboxgl.accessToken` once at app start. Public `pk.…` tokens
+// ship in client code by design — restrict them per surface.
+//
+// ★ The map CONTAINER never carries a dynamic `:class` — mapbox-gl writes its own classes onto that
+// element and a Vue class patch wipes them (positioning breaks). Height + fade live on the WRAPPER;
+// the container keeps only static classes.
+//
+// ★ The canvas is kept in sync with its container by a ResizeObserver, not by Mapbox's own
+// window-resize tracking — see watchSize() for why that isn't enough.
+import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, watch } from 'vue';
+import mapboxgl from 'mapbox-gl';
+import { FOREST_MAP } from './mapContext';
+import { readEasing, readMs } from './ease';
+import { resolveInset, withGap } from './padding';
+import { useTokenMode } from './useTokenMode';
+import { FOREST_MAP_STYLE } from './style';
+import 'mapbox-gl/dist/mapbox-gl.css';
+// After mapbox-gl.css: re-points the #fff/#333/3px literals mapbox bakes into popups, controls,
+// attribution and scale at Forest tokens. Order matters — equal specificity, last import wins.
+import './map.css';
+
+const props = withDefaults(
+  defineProps<{
+    accessToken?: string;
+    /** override the house style. Rarely right — see FOREST_MAP_STYLE */
+    style?: string;
+    center?: [number, number];
+    zoom?: number;
+    pitch?: number;
+    bearing?: number;
+    /** frame a box instead of a point. Takes precedence over `center`/`zoom` at creation */
+    bounds?: mapboxgl.LngLatBoundsLike;
+    /** room to leave around `bounds`, in px — on top of `padding`, not instead of it */
+    fitPadding?: number;
+    /** hard pan limit — the London clamp. Pair with `minZoom` or a user can zoom out past it */
+    maxBounds?: mapboxgl.LngLatBoundsLike;
+    minZoom?: number;
+    maxZoom?: number;
+    /**
+     * Viewport inset the camera keeps clear, in px. This is how a bottom sheet or a side panel stops
+     * covering what the map just flew to: every camera move centres inside the remaining box.
+     */
+    padding?: { top?: number; bottom?: number; left?: number; right?: number };
+    /** false makes the map a picture: no pan, no zoom, no rotate, and nothing focusable */
+    interactive?: boolean;
+    /**
+     * Keep the WebGL drawing buffer readable after a frame, so `getCanvas()` can be sampled.
+     *
+     * ★ OFF by default and it should stay off: the browser cannot discard the buffer, which costs memory and
+     * a copy per frame on every map that asks for it. This exists for MEASUREMENT — a probe that has to read
+     * what the renderer actually painted rather than what the style asked for. Without it a canvas read comes
+     * back blank, which reads as "nothing painted" and is the wrong conclusion.
+     */
+    preserveDrawingBuffer?: boolean;
+    /** basemap config, e.g. { lightPreset: 'night', theme: 'monochrome' } */
+    config?: Record<string, unknown>;
+    /**
+     * Which of the basemap's four lighting presets to use. `auto` follows the app's colour mode —
+     * night in dark, day in light — which is what a map inside a themed surface almost always wants.
+     * Pass a preset to pin one, or set `lightPreset` in `config` for the same effect.
+     */
+    lightPreset?: 'auto' | 'day' | 'dawn' | 'dusk' | 'night';
+    /** tailwind height utility for the frame. `h-full` fills a sized parent */
+    height?: string;
+    /** Mapbox's attribution control. Its terms require the attribution to be visible somewhere on
+     *  the surface — only turn this off when the surface carries it elsewhere (e.g. an app's legal
+     *  screen, or chrome drawn above a bottom sheet). */
+    attribution?: boolean;
+    /** ⌘/ctrl-scroll to zoom — on by default so a page scrolls past the map */
+    cooperative?: boolean;
+    /** create the WebGL context only when the frame nears the viewport */
+    lazy?: boolean;
+    /** draw a rounded border card around the map. Off by default: the map fills what it is given,
+     *  and a surface that wants a card supplies its own (a shell canvas, a FlushCard, a code preview).
+     *  Turn it on for a map that stands alone on a page with nothing else drawing its edge. */
+    frame?: boolean;
+  }>(),
+  {
+    accessToken: undefined,
+    style: FOREST_MAP_STYLE,
+    center: () => [-0.1527, 51.5286],
+    zoom: 13.5,
+    pitch: 0,
+    bearing: 0,
+    bounds: undefined,
+    fitPadding: 48,
+    maxBounds: undefined,
+    minZoom: undefined,
+    maxZoom: undefined,
+    padding: undefined,
+    interactive: true,
+    config: undefined,
+    lightPreset: 'auto',
+    height: 'h-105',
+    attribution: true,
+    cooperative: true,
+    lazy: true,
+    frame: false,
+  },
+);
+
+const emit = defineEmits<{ ready: [map: mapboxgl.Map] }>();
+
+const token = props.accessToken || mapboxgl.accessToken;
+const wrap = ref<HTMLElement | null>(null);
+const canvas = ref<HTMLDivElement | null>(null);
+const map = shallowRef<mapboxgl.Map | null>(null);
+const loaded = ref(false);
+// A style that never arrives leaves a blank rectangle otherwise: a bad style id, a revoked token, a
+// network the surface cannot reach. Held as a message so the frame can say which.
+const styleError = ref<string | null>(null);
+
+// Nested primitives (<FMarker>, and <FMapPopup> through it) attach themselves off this. It stays
+// null until the lazy init runs, so they watch it rather than reading it once on mount.
+provide(FOREST_MAP, map);
+
+// Mapbox reads its container's size once at construction and re-reads only on WINDOW resize
+// (`trackResize`). A container that changes size while the window doesn't — a sidebar collapsing, a
+// resize handle dragging, a container query reflowing, a panel animating — leaves the canvas at its
+// old dimensions, which shows up as a strip of dead space down one edge. Observing the container
+// instead covers all of those AND window resize, so it is the only handler needed.
+//
+// ★ THE RESIZE IS TAKEN OUT OF THE OBSERVER CALLBACK, and that is what stops the flicker. Mapbox's
+// resize() writes canvas.width/height, which re-allocates the WebGL drawing buffer and CLEARS it; the
+// re-render is scheduled for the next frame. ResizeObserver runs AFTER layout and BEFORE paint, so a
+// resize taken inline paints an empty canvas for that frame. One frame passes unseen — but a container
+// that TRAVELS fires the observer on every frame of the travel (the app rail collapsing is 240ms of
+// them), and the map blanks for the whole transition.
+//
+// A timeout runs as a task, after the frame it was queued in has painted, so mapbox re-renders into the
+// new buffer before anything is shown. The cost is that the canvas geometry trails the container by a
+// frame: a hairline of the frame's background at the moving edge, against a map that stays lit.
+//
+// Coalesced, because a live transition queues one of these per frame and only the last size matters.
+let ro: ResizeObserver | null = null;
+let pending: ReturnType<typeof setTimeout> | null = null;
+function watchSize(m: mapboxgl.Map, el: HTMLElement) {
+  if (typeof ResizeObserver === 'undefined') return;
+  ro = new ResizeObserver(() => {
+    if (pending) return;
+    pending = setTimeout(() => {
+      pending = null;
+      if (map.value) m.resize();
+    }, 0);
+  });
+  ro.observe(el);
+}
+
+function init() {
+  if (map.value || !token || !canvas.value) return;
+  mapboxgl.accessToken = token;
+  // ★ THE TWO PADDINGS ARE SUMMED HERE, because fitBounds REPLACES the transform's padding rather than
+  // adding to it — the same measurement useMapCamera.fit is built on (GL JS 3.24.1: `_extendPadding`
+  // falls back to `transform.padding` only when the option is absent). Passing `fitPadding` alone framed
+  // a `:padding="{ left: 400 }"` map against the whole element, and since the fit resolves at creation
+  // and setPadding runs after it, the first paint was then visibly shoved sideways by the padding it
+  // should have been framed inside.
+  const inset = resolveInset(props.padding);
+  const m = new mapboxgl.Map({
+    container: canvas.value,
+    style: props.style,
+    center: props.center,
+    zoom: props.zoom,
+    pitch: props.pitch,
+    bearing: props.bearing,
+    // `bounds` wins over center/zoom when both are given — mapbox resolves it at creation, so the
+    // first paint is already framed rather than flying there.
+    ...(props.bounds
+      ? { bounds: props.bounds, fitBoundsOptions: { padding: withGap(props.padding, props.fitPadding) } }
+      : {}),
+    ...(props.maxBounds ? { maxBounds: props.maxBounds } : {}),
+    ...(props.minZoom != null ? { minZoom: props.minZoom } : {}),
+    ...(props.maxZoom != null ? { maxZoom: props.maxZoom } : {}),
+    interactive: props.interactive,
+    ...(props.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
+    cooperativeGestures: props.cooperative,
+    attributionControl: props.attribution,
+    // Creation-time too: applyConfig only runs once the style has loaded, and a map that paints in day
+    // and corrects itself a beat later is a flash of the wrong mode on every load.
+    config: { basemap: { lightPreset: resolvedPreset.value, ...(props.config ?? {}) } },
+  });
+  // Takes the uniform gap back off the transform, so later moves inset by the prop alone rather than by
+  // the prop plus a fit's worth of room — and so getPadding() reports what was asked for. Costs nothing
+  // on screen: `fitPadding` is equal on all four sides, and the centre mapbox renders at depends on the
+  // DIFFERENCE between opposite sides, which the sum leaves untouched.
+  if (props.padding) m.setPadding(inset);
+  m.on('style.load', () => {
+    styleError.value = null;
+    loaded.value = true;
+    emit('ready', m);
+  });
+  // Only a STYLE failure is fatal to the frame. Tile and source errors are routine — one 404 during a
+  // pan is not a broken map — so they stay in the console rather than replacing what is on screen.
+  m.on('error', (e) => {
+    if (loaded.value) return;
+    const message = (e as { error?: Error }).error?.message ?? 'The map style failed to load.';
+    if (/style|token|401|403|404/i.test(message)) styleError.value = message;
+  });
+  map.value = m;
+  watchSize(m, canvas.value);
+}
+
+onMounted(() => {
+  if (!token || !wrap.value) return;
+  if (!props.lazy) {
+    init();
+    return;
+  }
+  const io = new IntersectionObserver(
+    (entries) => {
+      if (entries.some((e) => e.isIntersecting)) {
+        init();
+        io.disconnect();
+      }
+    },
+    { rootMargin: '250px' },
+  );
+  io.observe(wrap.value);
+  onBeforeUnmount(() => io.disconnect());
+});
+
+// Camera padding is the one prop that changes AFTER creation in normal use — a bottom sheet opening
+// or a side panel expanding. Applied on the live instance so the next camera move already respects it.
+//
+// ★ EASED, not set. `setPadding` re-centres the camera in one frame, so a panel that takes 240ms to slide
+// open leaves the map underneath it JUMPING at the moment the panel starts moving — one gesture rendered
+// as two events. `easeTo` runs the same re-centring over the panel's own travel, and the map reads as the
+// thing the panel is moving aside rather than as a separate surface reacting to it.
+//
+// Where the timing comes from, in order: the panel publishes its own travel on the container it shares
+// with the canvas (--forest-canvas-inset-duration), so the two agree in BOTH directions — a fast exit
+// stays fast. Falling back to --motion-slow keeps a bare `:padding` change eased rather than instant, and
+// to 0 (a plain set) if neither token resolves, which is what a non-Forest host would get.
+//
+// The curve is read from --motion-ease-out and sampled by ease.ts, so the camera and the CSS transition
+// are on ONE curve rather than two that look similar.
+watch(
+  () => props.padding,
+  (p) => {
+    const m = map.value;
+    if (!p || !m) return;
+    const ms = readMs(wrap.value, '--forest-canvas-inset-duration') || readMs(wrap.value, '--motion-slow');
+    // Reduced motion is a CSS floor, which a JS camera move sails straight past — so it is honoured here
+    // explicitly. Same outcome as the floor gives a transition: the end state, with no travel.
+    const reduce =
+      typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (!ms || reduce) {
+      m.setPadding(p);
+      return;
+    }
+    m.easeTo({ padding: p, duration: ms, easing: readEasing(wrap.value, '--motion-ease-out') });
+  },
+  { deep: true },
+);
+
+// ★ THE BASEMAP FOLLOWS THE COLOUR MODE ON ITS OWN. Mapbox's `lightPreset` is what makes a map read as
+// dark, and every surface used to wire it by hand — eight consumers in this repo did it four different
+// ways, and the ones that forgot shipped a daylight map on a dark page. It belongs here: a map inside a
+// themed surface almost always wants to match it, and the one that does not says so with a prop.
+//
+// ★ Keyed off useTokenMode, NOT an isDark ref. The ref flips before the class lands on <html>, so
+// anything reading the resolved mode from a watcher is one toggle behind — the bug that composable
+// exists to document. This reads the DOM after the change, like resolveMapColor does.
+const mode = useTokenMode();
+const resolvedPreset = computed(() => {
+  void mode.value;
+  // An explicit prop wins; `config.lightPreset` still wins over both, since a caller spelling it out in
+  // the config object means it deliberately.
+  if (props.lightPreset !== 'auto') return props.lightPreset;
+  if (typeof document === 'undefined') return 'day';
+  // ★ THE CLASS, and never the OS preference. Forest's dark mode is class-based — every token on the
+  // page resolves from `.dark` on <html> — so a map asking `prefers-color-scheme` would disagree with
+  // the surface around it. MEASURED: on a machine whose OS prefers dark, switching the docs to light
+  // left the basemap at night, because the media query outvoted the class the rest of the page obeys.
+  // Whatever decides `.dark` has already accounted for the OS.
+  const el = document.documentElement;
+  const dark = el.classList.contains('dark') || el.dataset.theme === 'dark';
+  return dark ? 'night' : 'day';
+});
+
+// ★ `config` also has to survive creation. Mapbox only reads the `config` option once, so a basemap
+// setting bound to reactive state — `lightPreset` following the colour mode being the obvious one —
+// applied on the first paint and then never again: the map stayed in day while the rest of the page
+// went dark. Re-applied per key on the live instance instead.
+//
+// Guarded on `loaded`: setConfigProperty needs the style, and calling it earlier throws. A map created
+// lazily may not have a style yet when the mode flips, so the ready path re-applies too.
+function applyConfig(cfg?: Record<string, unknown>) {
+  const m = map.value;
+  if (!m || !loaded.value) return;
+  // The preset first, so an explicit `config.lightPreset` lands after it and wins.
+  m.setConfigProperty('basemap', 'lightPreset', resolvedPreset.value);
+  if (!cfg) return;
+  for (const [key, value] of Object.entries(cfg)) m.setConfigProperty('basemap', key, value);
+}
+
+watch(() => props.config, (cfg) => applyConfig(cfg), { deep: true });
+watch(loaded, (ok) => ok && applyConfig(props.config));
+watch(resolvedPreset, () => applyConfig(props.config));
+
+onBeforeUnmount(() => {
+  ro?.disconnect();
+  if (pending) clearTimeout(pending);
+  map.value?.remove();
+});
+
+defineExpose({ map });
+</script>
+
+<template>
+  <!-- Height sits on the outer element and everything below fills it, so `height="h-full"` can
+       inherit a sized parent (a phone screen, a panel) instead of only fixed utilities. -->
+  <div ref="wrap" :class="height">
+    <div class="relative h-full" :class="frame ? 'overflow-hidden rounded-xl border border-default' : ''">
+      <!-- Fade on the wrapper, NOT the map container (see script note). -->
+      <div v-if="token" class="h-full transition-opacity" :class="{ 'opacity-0': !loaded }">
+        <div ref="canvas" class="h-full w-full" />
+        <!-- Children render nothing here: <FMarker> teleports its content into the element mapbox
+             positions. The slot exposes the map for anything that would rather drive it directly. -->
+        <slot :map="map" />
+      </div>
+      <div v-else class="flex h-full w-full items-center justify-center bg-elevated/30">
+        <div class="max-w-sm space-y-3 px-6 text-center">
+          <UIcon name="i-lucide-map-pin-off" class="mx-auto size-8 text-dimmed" />
+          <p class="type-body font-medium text-highlighted">No Mapbox access token</p>
+          <p class="type-body text-muted">
+            Pass <code>:access-token</code> or set <code>mapboxgl.accessToken</code> once at app
+            start. Use a public <code>pk.…</code> token restricted to this surface.
+          </p>
+        </div>
+      </div>
+      <!-- Style failure: over the canvas rather than instead of it, because the map element must stay
+           mounted for a later retry (and for whatever a surface already attached to it). -->
+      <div
+        v-if="styleError"
+        class="absolute inset-0 flex items-center justify-center bg-elevated/80 backdrop-blur"
+      >
+        <div class="max-w-sm space-y-3 px-6 text-center">
+          <UIcon name="i-lucide-triangle-alert" class="mx-auto size-8 text-warning" />
+          <p class="type-body font-medium text-highlighted">The map couldn't load</p>
+          <p class="type-body text-muted">{{ styleError }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>