@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/canvas/FCanvasFlyout.vue

@@ -0,0 +1,216 @@
+<script setup lang="ts">
+// One canvas control that opens into a cluster of them, in place.
+//
+//   <FCanvasFlyout icon="i-lucide-lasso" label="Selection tools" :items="tools" @select="pick" />
+//
+// ★ WHY IT EXISTS. A rail is a narrow column shared with the zoom pair, the compass and the rest, and
+// four controls stacked is 144px of a 480px map before anything else gets its share. This is one
+// control at rest, and the cluster exists only while a reader is choosing from it — the only moment it
+// says anything.
+//
+// ★ IT OPENS ACROSS THE RAIL, NOT ALONG IT. `orientation` is the axis the cluster opens ALONG, and it
+// defaults to horizontal precisely because rails are vertical: a group that grew downward would push
+// every control below it along, every time someone glanced at the tools. Opening across spends space
+// the canvas has and the rail does not.
+//
+// ★ AND IT IS AN OVERLAY, NOT A RESIZE. The wrapper only ever occupies the trigger; the cluster is
+// absolutely positioned from it. A rail hugs its widest child (`fit-content`), so a cluster that grew
+// in flow would widen the whole column and drag its neighbours sideways — measured, before this was
+// positioned out of flow.
+//
+// ★ NOT A POPOVER. It grows contiguously from the trigger and shares one surface with it, so it reads
+// as one object opening rather than a panel arriving beside it: no anchor to position, nothing to
+// teleport, no second pane of glass. <FMapSearch> takes the same view for the same reason.
+import { computed, ref, watch } from 'vue';
+import FCanvasControl from './FCanvasControl.vue';
+
+/** One member of the cluster. `value` is what comes back on select. */
+export interface FlyoutItem {
+  value: string;
+  icon: string;
+  label: string;
+  /** lit — for a cluster of modes, the one currently held */
+  pressed?: boolean;
+}
+
+import FCanvasControlGroup from './FCanvasControlGroup.vue';
+
+const open = defineModel<boolean>('open', { default: false });
+
+const emit = defineEmits<{ select: [value: string] }>();
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * The trigger's icon at rest.
+     *
+     * ★ Deliberately not derived. A flyout of MODES usually wants the active one here, so a reader can
+     * see what is in their hand without opening anything; a flyout of one-shot ACTIONS wants a fixed
+     * icon, because there is no state to report. The component cannot tell which it is in, so it does
+     * not try.
+     */
+    icon: string;
+    label: string;
+    /** Lit at rest — for a mode flyout, whether the mode it names is active. */
+    pressed?: boolean;
+    /** The axis the cluster opens along. Horizontal suits a vertical rail, and vice versa. */
+    orientation?: 'vertical' | 'horizontal';
+    /** Which end the trigger is pinned to, so the cluster opens INWARD rather than off the canvas. */
+    side?: 'start' | 'end';
+    /**
+     * The controls the cluster holds.
+     *
+     * ★ Items rather than a slot, and the motion is why. A cluster's members enter and leave, and
+     * <TransitionGroup> can only drive vnodes it created — hand it slot content and the classes never
+     * land on anything (measured: members appeared with the button's own transition and no enter
+     * class at all). Owning the members buys working motion; the cost is that a member is an icon
+     * control rather than arbitrary markup, which is all a cluster of chrome ever is.
+     */
+    items?: FlyoutItem[];
+    /** Icon for the dismiss the trigger becomes while open. */
+    closeIcon?: string;
+    /** Accessible name for that dismiss. */
+    closeLabel?: string;
+  }>(),
+  {
+    items: () => [],
+    pressed: undefined,
+    orientation: 'horizontal',
+    side: 'end',
+    closeIcon: 'i-lucide-x',
+    closeLabel: 'Close',
+  },
+);
+
+const root = ref<HTMLElement | null>(null);
+const close = () => (open.value = false);
+
+// Picking closes: a cluster of modes has said everything it has to say once one is chosen.
+function choose(value: string) {
+  emit('select', value);
+  close();
+}
+
+/**
+ * Where a member starts from: just inside the trigger, so the cluster reads as unfolding OUT of it
+ * rather than materialising beside it.
+ *
+ * ★ `translate-*`, and the transition names `translate` — not `transform`. In Tailwind v4 the
+ * translate utilities set the `translate` property, so a `transition-[opacity,transform]` would
+ * animate the fade alone and snap the movement.
+ */
+const from = computed(() => {
+  const d = '0.5rem';
+  if (props.orientation === 'horizontal')
+    return { '--forest-flyout-x': props.side === 'end' ? d : `-${d}`, '--forest-flyout-y': '0' };
+  return { '--forest-flyout-x': '0', '--forest-flyout-y': props.side === 'end' ? d : `-${d}` };
+});
+
+/**
+ * ★ A CSS ANIMATION, NOT <TransitionGroup>. Measured: with the members inside a TransitionGroup —
+ * both as slot content and rendered here — the enter classes never landed on them at all; every
+ * member showed the button's own `transition-property` and no opacity or translate of its own. An
+ * animation runs on mount by construction, which is exactly when a member appears, and nothing has
+ * to be wired correctly for it to fire.
+ */
+
+// ★ Focus alone cannot dismiss this. A map canvas is not focusable, so pressing on it may move focus
+// nowhere at all, and the cluster would sit open over the very thing the reader reached for. Watching
+// pointerdown catches the press wherever it lands.
+watch(open, (isOpen, _was, onCleanup) => {
+  if (!isOpen) return;
+  const away = (e: PointerEvent) => {
+    if (!root.value?.contains(e.target as Node)) close();
+  };
+  // Capture, so a handler that stops propagation cannot leave the cluster open behind its own panel.
+  document.addEventListener('pointerdown', away, true);
+  onCleanup(() => document.removeEventListener('pointerdown', away, true));
+});
+
+// The keyboard still moves focus properly, so this covers tabbing away.
+function onFocusOut() {
+  requestAnimationFrame(() => {
+    if (!open.value) return;
+    if (root.value?.contains(document.activeElement)) return;
+    close();
+  });
+}
+</script>
+
+<style>
+/* One keyframe serves all four placements; the flyout sets the axis it enters from. */
+@keyframes forest-flyout-in {
+  from {
+    opacity: 0;
+    translate: var(--forest-flyout-x, 0) var(--forest-flyout-y, 0);
+  }
+}
+.forest-flyout-in {
+  /* No var() fallbacks. They had already DRIFTED: 150ms is Tailwind's stock default, not
+     --motion-fast's 140ms, and the bare `ease-out` keyword is the weak built-in the doctrine bans
+     outright — so the "safety net" quietly contradicted the ladder it was netting. The tokens ship
+     with the layer now (packages/tokens/motion/motion.css), so an absent value means a broken
+     install, which should look broken rather than silently animate off-doctrine. */
+  animation: forest-flyout-in var(--motion-fast) var(--motion-ease-out) both;
+}
+/* The global floor covers transitions; an animation has to be said separately. */
+@media (prefers-reduced-motion: reduce) {
+  .forest-flyout-in {
+    animation: none;
+  }
+}
+</style>
+
+<template>
+  <div
+    ref="root"
+    class="pointer-events-auto relative"
+    :style="from"
+    :class="orientation === 'horizontal' ? 'h-(--forest-canvas-control)' : 'w-(--forest-canvas-control)'"
+    @keydown.escape="close"
+    @focusout="onFocusOut"
+  >
+    <FCanvasControlGroup
+      :orientation="orientation"
+      class="absolute"
+      :class="
+        orientation === 'horizontal'
+          ? ['top-0', side === 'end' ? 'end-0' : 'start-0']
+          : ['start-0', side === 'end' ? 'bottom-0' : 'top-0']
+      "
+    >
+      <!-- Order follows `side` so the TRIGGER stays put and the cluster appears beside it. Pinned at
+           the end, members render first and the trigger last — otherwise opening would walk the
+           trigger off the edge it is anchored to. -->
+        <FCanvasControl
+          v-for="item in open && side === 'end' ? items : []"
+          :key="item.value"
+          :icon="item.icon"
+          :label="item.label"
+          :pressed="item.pressed"
+          class="forest-flyout-in"
+          @click="choose(item.value)"
+        />
+
+      <!-- Closed it is the thing itself; open it is the way out. A dismiss rather than a member,
+           because a member that also closed the cluster would be indistinguishable from one that
+           does not. -->
+      <FCanvasControl
+        :icon="open ? closeIcon : icon"
+        :label="open ? closeLabel : label"
+        :pressed="open ? undefined : pressed"
+        @click="open = !open"
+      />
+
+        <FCanvasControl
+          v-for="item in open && side === 'start' ? items : []"
+          :key="item.value"
+          :icon="item.icon"
+          :label="item.label"
+          :pressed="item.pressed"
+          class="forest-flyout-in"
+          @click="choose(item.value)"
+        />
+    </FCanvasControlGroup>
+  </div>
+</template>

package/packages/ui/src/canvas/FCanvasHud.vue

@@ -0,0 +1,402 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { CANVAS_CARD_MAX, CANVAS_RAIL_BOTTOM_MAX, type CanvasSurface } from './canvasSurface';
+// The canvas HUD — chrome OVER a full-bleed canvas (a map, a camera) instead of around content.
+//
+// ★ NOT A SHELL, and the distinction is the point. A shell DISPLACES: a sidebar takes its space and the
+// content is simply smaller. A HUD OCCLUDES: the canvas keeps the whole surface and the chrome floats over
+// it, which is why this component's budget is measured in occlusion and reachability — figures that mean
+// nothing for a sidebar. It also composes WITH a shell rather than replacing one: on a console this sits
+// inside the app shell's released panel, and on a phone it stands alone.
+// See /layout/canvas.
+//
+// ★ THE CHROME IS A FRAME OF AREAS, NOT A SET OF CORNERS.
+// Corner slots size themselves to whatever you put in them, which makes the layout a consequence of
+// the content instead of a decision. Areas are the other way round: the HUD declares where chrome
+// may live and how much room it has, and content fills them. That is what makes two screens built by
+// two people line up, and it is what a Flutter implementation can match.
+//
+// Eight areas, as a STACK of rows — hub, top band, bottom band, dock:
+//
+//   ┌───────────────────────────────────────┐
+//   │                 hub                   │  a full-width row, contents centred. It centres on the
+//   ├──────┬─────────────┬────────┬─────────┤  CANVAS because it SPANS it.
+//   │ rail │  card-top   │        │  rail   │  TOP BAND — its own grid. Rails hug their control and
+//   │ -top │             │        │  -top   │  cap; the card takes its own track; the middle is slack.
+//   │ start│             │        │  end    │  Aligned to the band's TOP edge.
+//   ├──────┴─────────────┴────────┴─────────┤
+//   │            canvas visible             │  NO element here at all — nothing to swallow a drag.
+//   ├──────┬─────────────┬────────┬─────────┤
+//   │ rail │ card-bottom │        │  rail   │  BOTTOM BAND — its own grid, aligned to the BOTTOM edge,
+//   │ -bot │             │        │  -bot   │  so it grows upward from the dock.
+//   │ start│             │        │  end    │
+//   ├───────────────────────────────────────┤
+//   │                dock                   │  PHONE: its own full-width row, rails on its top edge.
+//   └───────────────────────────────────────┘  CONSOLE: joins the band's row, spanning it.
+//
+// ★ ONE GRID PER BAND, NOT ONE FOR THE HUD. A single grid means one set of columns for the whole
+// layer, and that couples the bands to each other: an empty top rail cannot free its column because
+// the BOTTOM rail is holding it open, and a card in each band is pinned to the same track whatever its
+// band wants. Both were real — a card stayed indented by a rail that was not there. Bands sized
+// independently have none of it, and nothing outside a band can move what is inside it.
+//
+// ★ THE HUB AND THE DOCK SPAN, WHICH IS WHY THEY ARE CENTRED. An area centred in a middle TRACK is
+// centred on whatever the side tracks left over — and those are content-sized, so two cards of
+// different lengths put it off centre. Measured: 11px with both sides filled, before anything is
+// empty. Spanning the row makes it centre on the canvas by construction rather than by arithmetic.
+//
+// ★ RAILS HUG. The track is `fit-content(--forest-canvas-rail-max)`, so a 36px control leaves 36px and
+// the hub keeps the rest. A fixed track left the control floating in dead space with the card beside it
+// indented by space nothing occupied. The cap still earns its keep: an oversized child clamps there
+// instead of starving the hub.
+//
+// ★ ONE CARD PER BAND. The slot names the BAND (`card-top`, `card-bottom`) and a prop names the side,
+// so a band holding two cards is unrepresentable rather than merely discouraged. Two side by side need
+// ~424px before the hub gets anything, which a 390pt phone does not have — measured at 79px each,
+// against 164px for one.
+//
+// ★ AN UNUSED AREA RENDERS NOTHING — `v-if`, never an empty div. An empty div still carries the area's
+// padding and holds its track open, so the neighbour never gets the width back.
+//
+//   canvas    the default slot. Full-bleed, reaches the physical edge, runs under the status bar.
+//   hub       a full-width row: filter or mode chips, a search pill, a status line.
+//   rails     four control stacks, hugging their content up to the rail cap.
+//   cards     one per band, on the side its prop names — at every width, because the card hugs its
+//             content rather than stretching. Capped at the card measure on a console; on a phone its
+//             AREA spans between the rails, and a card that wants all of that says `w-full` itself.
+//   dock      the primary action, or a stacked pair. Its row is `auto`, so it grows with its
+//             content and the bottom rails rise to meet it.
+//   drawer    NOT here: that is UDrawer, portalled, and it owns its own scrim and drag. It does not
+//             need the dock hidden — a bottom drawer occupies the bottom of the screen, so it covers
+//             the dock on its own. The convention worth following is that the primary action rides the
+//             DRAWER's foot once one is open; the HUD does not enforce it, because a drawer opened as
+//             a peek over a still-relevant dock is a legitimate arrangement too.
+//   takeover  NOT here, and not a slot. A takeover REPLACES the canvas, so it is `v-if` on this component
+//             or a route of its own — never an element inside it. A slot could only ever COVER the canvas,
+//             leaving the map mounted with its GL context live and its tiles loading behind an opaque box.
+//             A CAMERA earns a takeover; nothing else does. It replaces the canvas with a full-screen
+//             capture frame of its own.
+//
+// The grid does the arranging: top rails align to the top of their row, bottom rails to the BOTTOM of
+// theirs, so they sit directly above the dock and move with it. That dependency is the reason this is
+// one component rather than six absolutely-positioned boxes.
+//
+// Two rules it enforces structurally rather than by memo:
+//
+// 1. POINTER-EVENTS. The layer is `pointer-events-none`, the area wrappers STAY none, and only the
+//    children placed inside them opt back in (`[&>*]:pointer-events-auto`). That distinction is
+//    load-bearing: an area is a zone that spans real estate, so a wrapper that opted in itself would
+//    swallow every drag across its whole column — the defining bug of hand-rolled canvas chrome, and
+//    invisible until someone tries to pan the map behind a transparent box. The canvas column holds
+//    no element at all.
+//
+// 2. SAFE AREA IS CHROME'S, NEVER THE CANVAS'S. The canvas bleeds under the notch by definition;
+//    only chrome is inset. The inset reads `var(--forest-safe-*, env(safe-area-inset-*))` so a device
+//    mock can override with measured numbers while a real device falls through to `env()`.
+const props = defineProps<{
+  /** Element the canvas renders as — `section` where the HUD is a page's main region. */
+  as?: string;
+  /**
+   * Which arrangement to draw. `auto` — the default — reflows on the width of its OWN container,
+   * so one instance is correct on a phone browser and on a console without the caller doing anything.
+   *
+   * `phone` and `web` PIN it, overriding the query in both directions. That is for a specimen that has to
+   * draw a given surface regardless of how wide it happens to be rendered (a diagram, a device mock) — not
+   * for production, where the point is that it adapts.
+   *
+   * The reflow itself is CSS: see `.forest-hud` / `.forest-hud-band` in forest.css.
+   */
+  surface?: CanvasSurface;
+  /**
+   * Ceiling on a rail's width, overriding the surface's own. A rail HUGS its control — the track is
+   * `fit-content(this)` — so a 36px button leaves 36px and the hub keeps the rest. The cap still
+   * matters: an oversized child clamps here instead of starving the hub.
+   */
+  railMax?: string;
+  /** Ceiling on a card area's width, overriding the surface's own. */
+  card?: string;
+  /**
+   * Which side of its band each card takes. Both default to `start`.
+   *
+   * ★ It means the same thing at every width. On a phone the card AREA spans between the rails, but the
+   * card inside hugs its content, so there is a side to take — a narrow card sits at the start or the
+   * end of that span. Only a card that asks for `w-full` has no side left to choose.
+   */
+  cardTop?: 'start' | 'end';
+  cardBottom?: 'start' | 'end';
+  /**
+   * Ceiling on how tall a bottom rail may grow, as a share of the HUD.
+   *
+   * Expressed in `cqh` because that is the only unit that means what it says here: `%` on a grid item
+   * resolves against its grid area, not the screen, and `dvh` would measure the browser viewport — wrong
+   * inside a device mock. The chrome layer is declared a size container so `cqh` resolves against the
+   * HUD's own safe region.
+   */
+  railBottomMax?: string;
+  /**
+   * Ceiling on how tall a card may grow, as a share of the HUD. Half the canvas per band.
+   *
+   * A card is the one area whose content has no natural stopping point — a rail holds two buttons, a card
+   * holds however many bays are in view — so it is the one that has to be told. Uncapped it pushes the
+   * dock out of the layer entirely: measured on a phone, a tall card moved the primary action 1582px past
+   * the bottom edge, where `overflow-hidden` clipped it away.
+   */
+  cardMax?: string;
+}>();
+
+const el = computed(() => props.as ?? 'div');
+const surface = computed(() => props.surface ?? 'auto');
+const railMax = computed(() => props.railMax);
+const card = computed(() => props.card);
+// Defaulted here rather than with withDefaults so the class name can never interpolate `undefined`.
+const cardTop = computed(() => props.cardTop ?? 'start');
+const cardBottom = computed(() => props.cardBottom ?? 'start');
+const railBottomMax = computed(() => props.railBottomMax ?? CANVAS_RAIL_BOTTOM_MAX);
+const cardMax = computed(() => props.cardMax ?? CANVAS_CARD_MAX);
+
+// ★ THE DOCK CENTRES ON THE CANVAS, not on whatever the rails leave over — and in the wide arrangement the
+// band's side columns are declared symmetrically for exactly that reason, whether or not a rail is there to
+// fill them. Asymmetric columns would push the primary action off centre by half a rail whenever one corner
+// held a panel and the other did not. Reserving both costs nothing: they are transparent and pointer-none.
+// This used to be JS, and had to stop being JS — a `computed` reading `$slots` caches its first answer,
+// because `$slots` is not reactive, so a reserved column outlived the rail that justified it. Grid columns
+// have no such failure mode.
+//
+// The hub does NOT balance, deliberately: it sits BETWEEN two cards as a peer in a band, so centring it in
+// the space they leave is right. The dock is a single anchored action on the surface.
+
+// ★ The safe inset ONLY. The gutter is padding INSIDE each area, not a gap between them — see the
+// note on the grid below.
+// Every area shares this: pointer-transparent wrapper, children opt in, and the gutter as INTERNAL
+// padding.
+//
+// ★ Height is NOT here. Two `height` utilities at equal specificity are resolved by Tailwind's
+// stylesheet order, not by the order they are listed on the element — so a shared `h-full` cannot be
+// overridden per area. Each area states its own height.
+// ★ HALF the gutter here, and the layer pads by the other half on top of the safe inset. Content is
+// still one gutter from the screen edge, but two things in NEIGHBOURING areas are one gutter apart
+// rather than two — a full gutter on each side of a shared edge read as dead space.
+const AREA_BASE = 'pointer-events-none flex flex-col gap-2 p-[calc(var(--forest-chrome-gutter)/2)]';
+// ★ `shrink-0` ON A RAIL'S CHILDREN, and it is a correctness rule rather than a spacing one.
+//
+// A bottom rail carries the same 50cqh ceiling a card does, but it has no scroll wrapper — that is the
+// CARD constant below, which pins its children `shrink-0` and scrolls the overflow. Without the same
+// pin here, a rail child taller than half the canvas is simply flex-shrunk to fit, and because every
+// <FCanvasCard> is `overflow-hidden`, whatever no longer fits DISAPPEARS: measured on a five-row
+// legend, the last row was gone with no scrollbar, no clipping edge and nothing in the DOM to say so —
+// the element reported all five children while painting four.
+//
+// Pinned, the same child overflows its rail instead. That spills over the canvas, which is not pretty,
+// but it is visible the moment it happens and it is fixable by whoever sees it. Silent loss is neither.
+const AREA = `${AREA_BASE} [&>*]:shrink-0 [&>*]:pointer-events-auto`;
+// ★ The hub and the dock use AREA_BASE, WITHOUT the grant. Their child is the reading wrapper, which is
+// `w-full` up to 46rem — granting it pointers made a transparent 736px box that takes clicks either side
+// of a 72px chip row. The grant cannot be undone on the wrapper either: `pointer-events-none` there and
+// `[&>*]:pointer-events-auto` here are equal specificity, so Tailwind's stylesheet order decides it and
+// the element loses. The wrapper passes the grant to ITS children instead.
+
+// The safe inset per side. The gutter is padding INSIDE each area, not part of this.
+//
+// ★ The bottom also clears --forest-canvas-basemap-strip, which is a LICENCE constraint rather than
+// spacing: Mapbox requires its wordmark (bottom-left) and its attribution (bottom-right) to stay
+// visible, so the whole bottom edge of a map canvas belongs to the basemap. Reserving it here means
+// compliance does not depend on whoever fills the areas remembering it. Defaults to 0, so a camera or
+// board canvas pays nothing for a rule that does not apply to it.
+// ★ THE HUB AND THE DOCK ARE CENTRED AND CONTENT-SIZED, with the reading measure as their ceiling.
+//
+// These are the only two areas that span the canvas, so they are the only two that can stretch a control
+// cluster across the whole surface. On a phone that is right — a dock IS a full-width CTA across the thumb
+// zone. On a 1360px console it is wrong: a button bar 1358px wide reads as a toolbar for the window rather
+// than as actions for the canvas.
+//
+// The fix is NOT a width. It is `items-center` on the area plus this wrapper, which together make the
+// child's own declaration decide:
+//
+//   <UButton block>   → w-full, so it fills, up to the reading measure. The phone dock.
+//   <UButton>         → content width, centred. The desktop dock.
+//
+// That is already the Nuxt UI idiom for "fill your container", so the HUD adds no second mechanism and
+// the same markup is correct on both surfaces. `max-w` is the ceiling for the `block` case only — it stops
+// a filling child at the same measure the well's reading rung uses, and never binds on a phone, where the
+// screen is narrower than the measure.
+//
+// The AREA still tiles the frame either way: this constrains its contents, so the grid and the overlay are
+// untouched.
+// `flex flex-col items-center` and not just `mx-auto`: the wrapper centres ITSELF in the area, which
+// leaves a content-width child sitting against the wrapper's start edge rather than in the middle of the
+// canvas. A `block` child is w-full and fills regardless, so this costs the filling case nothing. `gap-2`
+// is for the stacked pair the dock is allowed to grow into.
+// ★ POINTER-TRANSPARENT, and its children opt back in. The area grants `[&>*]:pointer-events-auto`,
+// which lands on THIS wrapper — and it is `w-full` up to the reading measure, so it was a transparent
+// 736px box taking clicks either side of a 72px chip row. Measured on a console: the hub and the dock
+// each claimed 736×36 of canvas that looks empty and does not pan.
+const READING =
+  'mx-auto flex w-full max-w-(--forest-well-reading) flex-col items-center gap-2 [&>*]:pointer-events-auto';
+
+// A card scrolls at its ceiling rather than spilling past it, so the area caps the BOX and this scrolls
+// the CONTENT. It has to be a wrapper: the area is pointer-transparent and a pointer-none box cannot be
+// scrolled directly, whereas a wheel or a drag landing on the card itself chains up to this one.
+// ★ Pointer-transparent regardless of its width, and the grant lands on its children — which is where the
+// card actually is. A wrapper that took clicks itself would own every pixel of its box, including whatever
+// sits beside a card narrower than it.
+// ★ IT HUGS ITS CONTENT — no `w-full`. The AREA still spans columns 2/5 below 60rem, because a third-width
+// track plus two rails wants ~424px and a phone has not got it; what does not follow is that the CARD must
+// stretch to fill that span. Stretching it made two things wrong at once: `cardTop`/`cardBottom` became
+// inert on a phone, since aligning a full-width box does nothing, and every author who wanted a card the
+// size of its content wrote around it — `w-64` appears on three of the five shipped call sites. Hugging
+// makes the side prop mean the same thing at every width, and anything that genuinely wants the whole
+// measure (a phone sheet) says `w-full` on its own card, where it reads as a decision.
+// ★ `[&>*]:shrink-0` is what makes it scroll rather than crush. A card carries `overflow`, which gives it
+// an automatic minimum size of 0 — so as a flex item it shrank to the ceiling and clipped its own content,
+// leaving the scroller with nothing to scroll. Measured: a 2000px card became 367px with the excess simply
+// gone. Holding children at their natural height puts the overflow where the scrollbar is.
+const CARD = 'flex min-h-0 flex-col gap-2 overflow-y-auto [&>*]:shrink-0 [&>*]:pointer-events-auto';
+
+// ★ The side insets also clear whatever an open <FSidePanel> declared on the container they share
+// (--forest-canvas-inset-start/end, 0 when none is open). A panel OCCLUDES the canvas, so a rail on
+// that edge would otherwise sit underneath it — visible chrome that cannot be clicked, and no z-index
+// resolves it because the panel is deliberately on top. Adding it to the safe inset rather than
+// replacing it means a panel and a device notch compose instead of one erasing the other.
+//
+// ★ PHYSICAL sides, matching the safe-area insets they are added to (`env(safe-area-inset-*)` is
+// physical — a notch does not move under RTL). FSidePanel maps its logical `side` to the physical
+// property when it writes it; an RTL surface would need that mapping to become direction-aware, which
+// nothing here ships today.
+const inset = (side: 'top' | 'right' | 'bottom' | 'left') => {
+  const safe = `var(--forest-safe-${side}, env(safe-area-inset-${side}, 0px))`;
+  // ★ Plus HALF the gutter. Each area carries the other half, so content sits one gutter from the
+  // edge while neighbours across a shared edge stay one gutter apart rather than two. The safe inset
+  // is a MINIMUM, not a target, so adding to it is legitimate.
+  const half = 'calc(var(--forest-chrome-gutter) / 2)';
+  if (side === 'bottom')
+    return `calc(${safe} + var(--forest-canvas-basemap-strip, 0px) + ${half})`;
+  if (side === 'top') return `calc(${safe} + ${half})`;
+  return `calc(${safe} + var(--forest-canvas-inset-${side}, 0px) + ${half})`;
+};
+</script>
+
+<template>
+  <!-- ★ The named query container the reflow keys on, and it is the ROOT rather than the viewport: on a
+       console this HUD is the interior of an inset panel, narrower than the window and narrower again
+       when the sidebar expands. `inline-size` because only the width is queried; the chrome layer inside
+       declares `size` separately, for the rails' `cqh` ceiling. -->
+  <!-- ★ `data-forest-canvas` is a HANDLE, not a styling hook: it is how a control finds the whole
+       canvas — chrome and all — from the thing it is chrome for. <FMapFullscreen> walks up from the
+       map's own container to it, because fullscreening the map element alone leaves every control
+       behind. Nothing in this file styles off it, and nothing should. -->
+  <component
+    :is="el"
+    data-forest-canvas
+    class="relative isolate h-full w-full overflow-hidden"
+    style="container: forest-canvas / inline-size"
+  >
+    <!-- CANVAS — z-0, edge to edge, untouched by safe area -->
+    <div class="absolute inset-0 z-0">
+      <slot />
+    </div>
+
+    <!-- CHROME — one layer, pointer-transparent; areas opt in.
+         A STACK, not a grid: hub row, top band, bottom band, and each band brings its own columns. -->
+    <div
+      class="forest-hud pointer-events-none absolute inset-0 z-10 flex flex-col"
+      :data-surface="surface"
+      :style="{
+        containerType: 'size',
+        ...(railMax ? { '--forest-canvas-rail-max': railMax } : {}),
+        ...(card ? { '--forest-canvas-card': card } : {}),
+        '--forest-canvas-card-max': cardMax,
+        paddingTop: inset('top'),
+        paddingRight: inset('right'),
+        paddingBottom: inset('bottom'),
+        paddingLeft: inset('left'),
+        transitionProperty: 'padding',
+        transitionDuration: `var(${'--forest-canvas-inset-duration'}, var(--motion-slow))`,
+        transitionTimingFunction: 'var(--motion-ease-out)',
+      }"
+    >
+      <!-- HUB — a full-width row of the stack, so it centres on the CANVAS by construction rather than
+           on whatever the rails leave over. It was a middle track between two rails, which put it off
+           centre the moment the two sides held different content — and starved it to nothing on a
+           phone, where two card-width rails leave ~16px between them. -->
+      <div v-if="$slots.hub" data-area="hub" :class="[AREA_BASE, 'items-center']">
+        <div :class="READING">
+          <slot name="hub" />
+        </div>
+      </div>
+
+      <!-- TOP BAND -->
+      <div v-if="$slots['rail-top-start'] || $slots['card-top'] || $slots['rail-top-end']" class="forest-hud-band">
+        <div
+          v-if="$slots['rail-top-start']"
+          data-area="rail-top-start"
+          :class="[AREA, 'items-start justify-start']"
+          style="grid-column: 1 / 2; grid-row: 1"
+        >
+          <slot name="rail-top-start" />
+        </div>
+        <div
+          v-if="$slots['card-top']"
+          data-area="card-top"
+          :class="[AREA_BASE, 'forest-hud-card min-h-0', `forest-hud-card--${cardTop}`, cardTop === 'end' ? 'items-end' : 'items-start', 'justify-start']"
+          :style="{ gridRow: '1', maxHeight: '100%' }"
+        >
+          <div :class="CARD">
+            <slot name="card-top" />
+          </div>
+        </div>
+        <div
+          v-if="$slots['rail-top-end']"
+          data-area="rail-top-end"
+          :class="[AREA, 'items-end justify-start']"
+          style="grid-column: 5 / 6; grid-row: 1"
+        >
+          <slot name="rail-top-end" />
+        </div>
+      </div>
+
+      <!-- ★ NO SPACER ELEMENT between the bands. The canvas region holds nothing at all, so there is no
+           box to swallow a drag across it. `mt-auto` on the bottom band does the pushing. -->
+      <div class="forest-hud-band forest-hud-band--dock mt-auto">
+        <div
+          v-if="$slots['rail-bottom-start']"
+          data-area="rail-bottom-start"
+          :class="[AREA, 'items-start justify-end']"
+          :style="{ gridColumn: '1 / 2', gridRow: '1', maxHeight: railBottomMax }"
+        >
+          <slot name="rail-bottom-start" />
+        </div>
+        <div
+          v-if="$slots['card-bottom']"
+          data-area="card-bottom"
+          :class="[AREA_BASE, 'forest-hud-card min-h-0', `forest-hud-card--${cardBottom}`, cardBottom === 'end' ? 'items-end' : 'items-start', 'justify-end']"
+          :style="{ gridRow: '1', maxHeight: '100%' }"
+        >
+          <div :class="CARD">
+            <slot name="card-bottom" />
+          </div>
+        </div>
+        <div
+          v-if="$slots['rail-bottom-end']"
+          data-area="rail-bottom-end"
+          :class="[AREA, 'items-end justify-end']"
+          :style="{ gridColumn: '5 / 6', gridRow: '1', maxHeight: railBottomMax }"
+        >
+          <slot name="rail-bottom-end" />
+        </div>
+
+        <!-- The dock spans its row, so it centres on the canvas. Phone: its own row under the band.
+             Console: the band's single row, between the rails. Which one is CSS, so `auto` reflows. -->
+        <div
+          v-if="$slots.dock"
+          data-area="dock"
+          :class="[AREA_BASE, 'forest-hud-dock min-w-0 items-center justify-end']"
+        >
+          <div :class="READING">
+            <slot name="dock" />
+          </div>
+        </div>
+      </div>
+    </div>
+
+  </component>
+</template>

package/packages/ui/src/canvas/canvasSurface.ts

@@ -0,0 +1,39 @@
+/**
+ * The canvas HUD's surface vocabulary.
+ *
+ * ★ THE MEASURES ARE NOT HERE, and deliberately so. `railTop` and `railBottom` live once, as the
+ * `--forest-canvas-rail-*` custom properties in styles/forest.css, where a container query reflows them
+ * between the two surfaces. Anything that needs to state a number reads that property back:
+ *
+ *   · the HUD applies them as `var(--forest-canvas-rail-top)`, never as a JS value;
+ *   · a diagram sizes its rail chips from the same property, so it cannot draw a cap the HUD is not
+ *     applying;
+ *   · documentation reads them off a hidden probe (apps/docs useCanvasMeasures), so prose prints what the
+ *     HUD resolved.
+ *
+ * A TS mirror of those values used to live here for documentation to quote. It was one copy too many: this
+ * page had already shipped a caption claiming 18rem while the component passed 17. Numbers belong wherever
+ * they are used, and everything else asks.
+ */
+export type CanvasSurface = 'auto' | 'phone' | 'web';
+
+/**
+ * Ceiling on how tall a bottom rail may grow, as a share of the HUD. Same on both surfaces, applied as an
+ * inline `max-height`, so unlike the rail widths it has no CSS counterpart to drift from.
+ *
+ * `cqh` because it is the only unit that means what it says here: `%` on a grid item resolves against its
+ * grid area, and `dvh` would measure the browser viewport — wrong inside a device mock. The HUD's chrome
+ * layer is declared a size container so this resolves against the HUD's own safe region.
+ */
+export const CANVAS_RAIL_BOTTOM_MAX = '50cqh';
+
+/**
+ * Ceiling on how tall a card may grow, as a share of the HUD — half the canvas per band, so a card in each
+ * band still leaves the map its middle. Same unit and the same reasoning as the rail ceiling above.
+ *
+ * ★ Applied to the band's ROW — `minmax(0, cap)` — and not as a `max-height` on the card. A max-height on a
+ * grid item clamps only what it paints: the auto row still sizes to the item's content, so a 2000px card
+ * drew at its 383px ceiling inside a 2116px band and pushed the dock out of the layer regardless. On the
+ * track it binds, and the card takes `max-height: 100%` of the row it is given.
+ */
+export const CANVAS_CARD_MAX = '50cqh';