@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/zone.ts

@@ -0,0 +1,291 @@
+// A ZONE is a rule with a boundary — where riding, throttling or parking changes.
+//
+// ★ ZONES ARE PAINT, NOT MARKS. A region has no centre worth claiming, so a zone is a `fill` plus a
+// `line`, described by `useMapOverlay` like any other overlay. There is no zone primitive and no zone
+// component: the style spec already says everything a fill and a line need to say.
+//
+// ★ AUDIENCE IS THE FIRST AXIS, AND IT IS A SOURCE DECISION.
+// The same geometry does not mean the same thing to an operator and to a rider, and one zone — the
+// exclusion — is an internal control the rider is never told about. So audience never rides
+// `visibility`: a hidden layer still ships its polygons to the client, and a control that is one
+// devtools tab away is not a control. `zoneFeatures()` filters the DATA; `zoneLayers()` only paints
+// what it is given.
+//
+// ★ FILLS AND LINES COME FROM DIFFERENT FEATURE SETS, and this is the part that is easy to get wrong.
+// Restrictions overlap — a low-speed zone can cross a no-parking zone — and two translucent fills
+// blend, so an overlap paints a colour that belongs to no zone kind at all. A LINE has no such
+// problem: every zone draws its own complete boundary, and boundaries crossing is what boundaries do.
+// So: lines take the raw features, fills take a DISJOINT set where the strictest rule already won.
+// See ZONE_RANK and the note on `zoneSources`.
+import { MAP_SLOT, token, type OverlayLayer } from './useMapOverlay';
+import type { MapLegendItem } from './mapLegend';
+
+export type ZoneKind = 'BUSINESS' | 'LOW_SPEED' | 'NO_PARKING' | 'EVENT' | 'EXCLUSION';
+
+/** Who is looking at the map. It decides which zones exist, not how they are painted. */
+export type ZoneAudience = 'operations' | 'rider';
+
+/**
+ * What each zone does to a rental, stated as the two things a rider can be doing.
+ *
+ * `speed` is the only three-valued one, and only because a low-speed zone permits the ride and limits
+ * it at the same time.
+ */
+export interface ZoneRule {
+  /** may a rider ride here */
+  ride: boolean;
+  /** may a rider END A RENTAL here */
+  park: boolean;
+  /** is the vehicle throttled here */
+  throttled: boolean;
+  /** does this zone appear and disappear on a schedule */
+  scheduled: boolean;
+}
+
+export const ZONE_RULE: Record<ZoneKind, ZoneRule> = {
+  BUSINESS: { ride: true, park: true, throttled: false, scheduled: false },
+  LOW_SPEED: { ride: true, park: true, throttled: true, scheduled: false },
+  NO_PARKING: { ride: true, park: false, throttled: false, scheduled: false },
+  // An event zone IS a no-parking zone. What separates it is that it is temporary and tied to an
+  // event, so it appears and disappears on a schedule where a no-parking zone is standing policy.
+  EVENT: { ride: true, park: false, throttled: false, scheduled: true },
+  // ★ THE EXCLUSION ZONE PERMITS. It is a pocket cut out of a no-parking zone where a rental may end
+  // after all. The rider is shown the no-parking zone whole and is never told the pocket is there; if
+  // they happen to park inside it, the system simply does not refuse.
+  EXCLUSION: { ride: true, park: true, throttled: false, scheduled: false },
+};
+
+/**
+ * ★ WHO SEES WHICH ZONE. Four of the five are rules a rider must be able to obey, so a rider is shown
+ * them. The exclusion is not a rule a rider is asked to obey — it is a hole in one — so it is
+ * operations-only, and `zoneFeatures()` drops it from the payload rather than hiding it.
+ */
+export const ZONE_AUDIENCE: Record<ZoneKind, readonly ZoneAudience[]> = {
+  BUSINESS: ['operations', 'rider'],
+  LOW_SPEED: ['operations', 'rider'],
+  NO_PARKING: ['operations', 'rider'],
+  EVENT: ['operations', 'rider'],
+  EXCLUSION: ['operations'],
+};
+
+export const zoneVisibleTo = (kind: ZoneKind, audience: ZoneAudience): boolean =>
+  ZONE_AUDIENCE[kind].includes(audience);
+
+/**
+ * ★ COLOUR IS WHAT THE RULE DOES TO A RENTAL (José, 2026-07-26).
+ *
+ * Green permits, amber limits, red forbids. It is a SEVERITY, so it takes the semantic roles — the
+ * same reason the battery ring does, and the reason the vivid categorical set stays with the vehicle
+ * discs. PARKING is the axis, not riding: a low-speed zone limits the ride and leaves parking alone,
+ * which is what makes it amber rather than red.
+ *
+ * Two of the five are not on that scale, and each says so by not taking a hue from it:
+ *
+ *   BUSINESS is INK. It is the container the others nest in and it claims nothing about behaviour
+ *     inside itself. The line is where the service stops, and ink flips with the mode, so the
+ *     outermost boundary stays maximally separated from the page in both.
+ *   EVENT is PINK — one step from red, because an event zone IS a no-parking zone with a schedule.
+ *     The dash carries the schedule and the hue carries the kinship.
+ */
+export const ZONE_COLOUR: Record<ZoneKind, string> = {
+  BUSINESS: '--forest-map-zone',
+  LOW_SPEED: '--forest-map-zone-low-speed',
+  NO_PARKING: '--forest-map-zone-no-parking',
+  EVENT: '--forest-map-zone-event',
+  EXCLUSION: '--forest-map-zone-exclusion',
+};
+
+/**
+ * ★ THE BUSINESS ZONE HAS NO FILL. It is the normal condition and it covers the whole screen, so an
+ * 8% wash over every pixel is a permanent tint a reader stops seeing — and every restriction inside
+ * it would then be a second layer on top of it. Its boundary is the whole of its message: the
+ * operating area is where the line is, and the rest of the map is outside it.
+ *
+ * The exclusion has no fill either, for the opposite reason: it is an ABSENCE. It marks where the
+ * no-parking fill stops, and painting an absence is how it stops being one.
+ */
+export const ZONE_FILL_OPACITY: Record<ZoneKind, number> = {
+  BUSINESS: 0,
+  LOW_SPEED: 0.1,
+  NO_PARKING: 0.12,
+  EVENT: 0.12,
+  EXCLUSION: 0,
+};
+
+/**
+ * ★ THE DASH SAYS "THIS BOUNDARY IS NOT A STANDING RULE".
+ *
+ * An event zone is temporary and an exclusion is internal, and both of those are the same statement
+ * about the line: do not read this edge as policy. Solid means standing, dashed means conditional.
+ * Dashes are in LINE WIDTHS, so the pattern holds its proportions as the line scales.
+ */
+export const ZONE_DASH: Partial<Record<ZoneKind, readonly number[]>> = {
+  EVENT: [3, 2],
+  EXCLUSION: [2, 2],
+};
+
+/**
+ * ★ STRICTEST WINS, AND IT WINS IN THE DATA.
+ *
+ * Two overlapping translucent fills blend: 12% over 12% paints 23%, which reads as a fourth zone kind
+ * that does not exist. Mapbox has no per-pixel precedence to reach for — a `fill` layer blends every
+ * feature it draws — so the only correct fix is to hand the fill layer a DISJOINT feature set.
+ *
+ * This rank is what resolves it: where regions overlap, the higher rank owns the pixels, and the
+ * exclusion (rank 0, and permissive) subtracts from whatever it sits inside. A feed that cannot
+ * flatten its own geometry can still be drawn correctly — see `zoneSources`, which takes the fills
+ * and the boundaries separately for exactly this reason.
+ */
+export const ZONE_RANK: Record<ZoneKind, number> = {
+  EXCLUSION: 0,
+  BUSINESS: 1,
+  LOW_SPEED: 2,
+  NO_PARKING: 3,
+  EVENT: 4,
+};
+
+export const ZONE_LABEL: Record<ZoneKind, string> = {
+  BUSINESS: 'Business zone',
+  LOW_SPEED: 'Low speed zone',
+  NO_PARKING: 'No parking zone',
+  EVENT: 'Event zone',
+  EXCLUSION: 'Exclusion zone',
+};
+
+/** What the rule does, in one line, for a legend or a popup. */
+export const ZONE_RULE_TEXT: Record<ZoneKind, string> = {
+  BUSINESS: 'Ride and park inside it.',
+  LOW_SPEED: 'Ride, throttled. Parking is unaffected.',
+  NO_PARKING: 'Ride through it. Do not end a rental in it.',
+  EVENT: 'A no parking zone with a schedule.',
+  EXCLUSION: 'A pocket inside a no parking zone where a rental may end. Operations only.',
+};
+
+/** the kinds an audience is allowed to know about, strictest last so paint order follows the rank */
+export const zoneKinds = (audience: ZoneAudience): ZoneKind[] =>
+  (Object.keys(ZONE_RULE) as ZoneKind[])
+    .filter((kind) => zoneVisibleTo(kind, audience))
+    .sort((a, b) => ZONE_RANK[a] - ZONE_RANK[b]);
+
+/**
+ * The legend rows for an audience — the same kinds `zoneKinds` allows, described so a swatch can be
+ * drawn from them.
+ *
+ * ★ IT TAKES THE AUDIENCE FOR THE SAME REASON THE DATA DOES. A rider legend naming the exclusion zone
+ * would hand back exactly what `zoneFeatures` withholds, so both filters run through `zoneVisibleTo`
+ * rather than each restating the rule.
+ *
+ * ★ AND IT READS IN A DIFFERENT ORDER THAN IT PAINTS. `zoneKinds` sorts by ZONE_RANK so the strictest
+ * zone paints over the rest, which puts the exclusion first. A legend read in that order opens on an
+ * ops-only exception. Ranking below the business zone is what makes a kind an exception to it, so
+ * those read last: here is where you operate, here is what narrows it, and here is what gives some
+ * back.
+ */
+export function zoneLegendItems(audience: ZoneAudience): MapLegendItem[] {
+  const count = Object.keys(ZONE_RULE).length;
+  const order = (kind: ZoneKind) =>
+    ZONE_RANK[kind] < ZONE_RANK.BUSINESS ? ZONE_RANK[kind] + count : ZONE_RANK[kind];
+
+  return zoneKinds(audience)
+    .sort((a, b) => order(a) - order(b))
+    .map((kind) => ({
+      key: kind,
+      // ★ The shared noun comes off. Every row in a zone legend is a zone, so carrying it five times
+      // says nothing and costs the width that made four of the five labels wrap in a rail. Derived
+      // rather than a second table of names, so ZONE_LABEL stays the only place a zone is named.
+      label: ZONE_LABEL[kind].replace(/ zone$/i, ''),
+      colour: ZONE_COLOUR[kind],
+      // A zone with no fill is drawn as its boundary alone, and the swatch says so rather than
+      // implying a wash the map never paints.
+      swatch: ZONE_FILL_OPACITY[kind] > 0 ? ('fill' as const) : ('line' as const),
+      dash: ZONE_DASH[kind],
+    }));
+}
+
+/**
+ * Drop every feature the audience must not receive.
+ *
+ * ★ Call this where the payload is BUILT, not where it is painted. On a rider surface the exclusion
+ * geometry should never leave the server; this function is the last line of that defence, not the
+ * whole of it.
+ */
+export function zoneFeatures<T extends { properties?: Record<string, unknown> | null }>(
+  features: readonly T[],
+  audience: ZoneAudience,
+  prop = 'kind',
+): T[] {
+  return features.filter((f) => {
+    const kind = f.properties?.[prop] as ZoneKind | undefined;
+    return !!kind && zoneVisibleTo(kind, audience);
+  });
+}
+
+export interface ZoneLayerOptions {
+  /** the source holding the DISJOINT fill features. Omit to draw boundaries only */
+  fillSource?: string;
+  /** the source holding every zone's complete boundary */
+  lineSource: string;
+  /** which audience the surface is for. Decides which kinds get layers at all */
+  audience: ZoneAudience;
+  /** feature property holding the kind. Default `kind` */
+  prop?: string;
+  /** id prefix, so two zone overlays can coexist. Default `zone` */
+  prefix?: string;
+  /** the width of a boundary, in px. Default 1.5 */
+  lineWidth?: number;
+}
+
+/**
+ * The overlay layers for a zone set: one fill layer, then one line layer per kind.
+ *
+ * ONE fill layer, because a fill answers "which rule applies here" and the answer is single-valued
+ * once the geometry is disjoint — a `match` on the kind paints it. MANY line layers, because a dash
+ * pattern is not data-driven in the way a colour is, and because a boundary per kind is what lets an
+ * operator turn one off.
+ *
+ * Everything lands in `MAP_SLOT.zone` (`bottom`): a zone is context, so it goes under the basemap's own
+ * labels, under the 3D buildings, and under every mark. Emissive strength is added by `useMapOverlay` — `fill` and `line` are both
+ * shaded types, and an unlit overlay paints at about a fifth of its luminance under the night preset.
+ */
+export function zoneLayers(opts: ZoneLayerOptions): OverlayLayer[] {
+  const { fillSource, lineSource, audience, prop = 'kind', prefix = 'zone', lineWidth = 1.5 } = opts;
+  const kinds = zoneKinds(audience);
+  const filled = kinds.filter((k) => ZONE_FILL_OPACITY[k] > 0);
+  const kindProp = ['get', prop];
+
+  const layers: OverlayLayer[] = [];
+
+  if (fillSource && filled.length) {
+    layers.push({
+      id: `${prefix}-fill`,
+      type: 'fill',
+      source: fillSource,
+      slot: MAP_SLOT.zone,
+      // A kind this audience must not see is filtered out of the data as well; the filter is here so
+      // that a feed which sends one anyway paints nothing rather than painting it in a fallback colour.
+      filter: ['in', kindProp, ['literal', filled]],
+      paint: {
+        'fill-color': ['match', kindProp, ...filled.flatMap((k) => [k, token(ZONE_COLOUR[k])]), token(ZONE_COLOUR.BUSINESS)],
+        'fill-opacity': ['match', kindProp, ...filled.flatMap((k) => [k, ZONE_FILL_OPACITY[k]]), 0],
+      },
+    });
+  }
+
+  for (const kind of kinds) {
+    const dash = ZONE_DASH[kind];
+    layers.push({
+      id: `${prefix}-line-${kind.toLowerCase().replace('_', '-')}`,
+      type: 'line',
+      source: lineSource,
+      slot: MAP_SLOT.zone,
+      filter: ['==', kindProp, kind],
+      paint: {
+        'line-color': token(ZONE_COLOUR[kind]),
+        'line-width': lineWidth,
+        ...(dash ? { 'line-dasharray': [...dash] } : {}),
+      },
+    });
+  }
+
+  return layers;
+}

package/packages/ui/src/shell/FAppNavbar.vue

@@ -0,0 +1,68 @@
+<script setup lang="ts">
+// The app shell's header — the rail control, the crumb, and the app's own actions.
+//
+//   <FAppNavbar :crumbs="[{ label: 'Fleet' }, { label: 'Vehicles' }]">
+//     <template #right> …buttons… </template>
+//   </FAppNavbar>
+//
+// The counterpart to <FAppSidebar>: the app supplies the CRUMB and the actions, everything else is
+// the same in every Forest app. It exists so a shell header needs no `:ui` at the usage site — three
+// things were being restated by hand in every app that composed <UDashboardNavbar> directly:
+//
+//   · The CHROME GUTTER. <FAppShell> puts the header in the chrome gutter, whose edges already track
+//     the card's (mx-(--forest-panel-inset)), so stock's own px-4 sm:px-6 lands on top of a margin
+//     that is already there. Stock's padding is right where stock puts a navbar — inside a panel,
+//     lining up with its body — and wrong in the gutter, so this is the shell's to state, not the theme's.
+//   · The CRUMB CONVENTION. Forest's crumb is `group · page` on a middot, not a chevron trail: a nav
+//     group is not a route. The middot is slot CONTENT, so no theme fragment can carry it — only a
+//     component can, which is why breadcrumb.ts is empty and this is not.
+//   · The SEPARATOR SPACING. A middot is narrower than a chevron and reads cramped on the list's own
+//     gap-1.5; mx-1 is what the middot needs, so it travels with the middot rather than apart from it.
+import { computed } from 'vue';
+import type { FCrumb } from './nav';
+
+const props = withDefaults(defineProps<{
+  /**
+   * The crumb, in reading order — `group · page`. Unlinked by default: a crumb names where you are,
+   * and a nav group has no route of its own. Pass `to` where a step genuinely is a destination.
+   */
+  crumbs?: FCrumb[];
+  /** The desktop rail's collapse control, first in the header. */
+  collapse?: boolean;
+}>(), { crumbs: () => [], collapse: true });
+
+const hasCrumbs = computed(() => props.crumbs.length > 0);
+</script>
+
+<template>
+  <!-- `px-0 sm:px-2` is the chrome gutter — see the note above. Everything else is stock. -->
+  <UDashboardNavbar :ui="{ root: 'px-0 sm:px-2' }">
+    <template #leading>
+      <UDashboardSidebarCollapse v-if="collapse" />
+
+      <UBreadcrumb
+        v-if="hasCrumbs"
+        :items="crumbs"
+        color="neutral"
+        class="ms-1.5"
+        :ui="{ separator: 'mx-1' }"
+      >
+        <template #separator>·</template>
+      </UBreadcrumb>
+
+      <slot name="leading" />
+    </template>
+
+    <template v-if="$slots.title" #title><slot name="title" /></template>
+    <template v-if="$slots.trailing" #trailing><slot name="trailing" /></template>
+    <template v-if="$slots.default" #default><slot /></template>
+
+    <template #right>
+      <!-- gap-3 is the action cluster's own rhythm, not the navbar's — square icon triggers sitting
+           together read as one group at 12px and as separate controls beyond it. -->
+      <div v-if="$slots.right" class="flex items-center gap-3">
+        <slot name="right" />
+      </div>
+    </template>
+  </UDashboardNavbar>
+</template>

package/packages/ui/src/shell/FAppShell.vue

@@ -0,0 +1,163 @@
+<script setup lang="ts">
+// The Forest app shell — sidebar, chrome, and the inset card the page lives in.
+//
+// Forest's panel is a CARD floating on the group's muted shell (themes/dashboard-panel.ts), not
+// stock's flat column, and that changes where chrome belongs. The header sits in the gutter ABOVE the
+// card, so the card holds nothing but the page. The card inset, the margin collapse and the teleport
+// plumbing live here so an app composing a shell does not restate them.
+//
+//   <FAppShell storage-key="ops">
+//     <template #sidebar> <UDashboardSidebar …/> </template>
+//     <template #header>  <UDashboardNavbar …/>  </template>
+//     …the page…
+//   </FAppShell>
+//
+// A PAGE fills the toolbar with <FPageToolbar>, which teleports into the element provided here — see
+// ./shell.ts for why it is an element rather than an id.
+import { computed, onBeforeUnmount, onMounted, provide, ref } from 'vue';
+import { createToolbarClaims, TOOLBAR_SEAT_KEY } from './shell';
+
+withDefaults(defineProps<{
+  /** Where the sidebar's width and collapsed state persist. */
+  storageKey?: string;
+  /**
+   * `local` rather than stock's cookie by default: a Vite SPA has no server, and Nuxt UI's useCookie
+   * stub is a no-op there — the rail would silently reset to its default on every load.
+   */
+  storage?: 'local' | 'cookie';
+  /** Unit the sidebar's sizes are expressed in. `rem` reads as widths rather than percentages. */
+  unit?: 'rem' | '%' | 'px';
+}>(), { storageKey: 'forest-shell', storage: 'local', unit: 'rem' });
+
+const toolbar = ref<HTMLElement | null>(null);
+
+// The first claimant owns the seam, so a section stacking a nav row over a filter row keeps the nav
+// row's — and if the nav row goes, the filter row is promoted rather than leaving a live toolbar
+// with a null seam. The ordering lives in ./shell.ts, shared with the docs preview that stages a
+// toolbar in a frame of its own. `claimants` is left behind here: the seat carries the three keys a
+// toolbar uses and nothing else.
+const { actions, claimActions, releaseActions } = createToolbarClaims();
+
+provide(TOOLBAR_SEAT_KEY, { toolbar, actions, claimActions, releaseActions });
+
+// The scrollport lane. <FPageToolbar> bleeds its root to the card's edge but wants its WELL to line
+// up with the page underneath — and the page scrolls in its own container, which the toolbar sits
+// above and outside of. A classic (non-overlay) scrollbar shrinks that container's content box, so
+// its centred well drifts from the toolbar's by however wide the scrollbar is. The shell can measure
+// that drift because it owns the seat; the toolbar cannot, because Teleport puts it outside the
+// scrolling element entirely.
+//
+// Contract: the shell does not parse the page's markup. Among the body wrapper's children EXCLUDING
+// the toolbar seat, the scrollport is whichever one is actually a vertical scroll container —
+// `overflow-y: auto` or `scroll`, CSS's own definition, not a class name or a tag guess. A page that
+// ships no such child (or one that never overflows) leaves the lane at 0px; nothing throws.
+//
+// The scrollport belongs to the PAGE, so a route can replace it with a different element — or with
+// none. The seat's siblings are watched for exactly that, and the lane re-resolves against whatever
+// the incoming page ships. The lane is only ever spent as padding INSIDE the toolbar, never on the
+// scrollport, so measuring it cannot move what is being measured.
+const scrollportLane = ref(0);
+let scrollport: HTMLElement | null = null;
+let scrollportSize: ResizeObserver | null = null;
+let seatSiblings: MutationObserver | null = null;
+
+function findScrollport(): HTMLElement | null {
+  const seat = toolbar.value;
+  const parent = seat?.parentElement;
+  if (!parent) return null;
+  for (const child of parent.children) {
+    if (child === seat || !(child instanceof HTMLElement)) continue;
+    const { overflowY } = getComputedStyle(child);
+    if (overflowY === 'auto' || overflowY === 'scroll') return child;
+  }
+  return null;
+}
+
+// `offsetWidth - clientWidth` counts the horizontal BORDERS as well as the scrollbar, so a
+// scrollport carrying an edge would reserve their width too and push the toolbar's well off the
+// page's. Take the borders back out and what remains is the scrollbar alone.
+function measureLane(el: HTMLElement): number {
+  const { borderLeftWidth, borderRightWidth } = getComputedStyle(el);
+  const borders = parseFloat(borderLeftWidth) + parseFloat(borderRightWidth);
+  return Math.max(0, el.offsetWidth - el.clientWidth - borders);
+}
+
+function bindScrollport() {
+  const next = findScrollport();
+  if (next === scrollport) return;
+  if (scrollport) scrollportSize?.unobserve(scrollport);
+  scrollport = next;
+  if (!next) {
+    scrollportLane.value = 0;
+    return;
+  }
+  scrollportSize?.observe(next, { box: 'content-box' });
+}
+
+onMounted(() => {
+  // `content-box`: a scrollbar appearing changes the content box without necessarily changing the
+  // border box, so the default (border-box) observation can miss exactly the resize that matters.
+  scrollportSize = new ResizeObserver(() => {
+    if (scrollport) scrollportLane.value = measureLane(scrollport);
+  });
+  seatSiblings = new MutationObserver(bindScrollport);
+  const parent = toolbar.value?.parentElement;
+  if (parent) seatSiblings.observe(parent, { childList: true });
+  bindScrollport();
+});
+
+onBeforeUnmount(() => {
+  scrollportSize?.disconnect();
+  seatSiblings?.disconnect();
+});
+
+// Declared on the SEAT, not the panel. A custom property inherits, and the panel is an ancestor of the
+// whole page — so publishing it there hands the lane to every nested thing that happens to use the
+// same token, including a toolbar staged inside a page's own card, which has no scrollbar of its own
+// to reserve for. The seat holds exactly one thing, the teleported toolbar, which is the one element
+// the lane is about.
+const seatStyle = computed(() => ({ '--forest-scrollport-lane': `${scrollportLane.value}px` }));
+</script>
+
+<template>
+  <UDashboardGroup :storage="storage" :storage-key="storageKey" :unit="unit">
+    <slot name="sidebar" />
+
+    <div class="flex min-w-0 flex-1 flex-col">
+      <!-- The chrome gutter. Aligned to the card's inset (mx-4 lg:ms-0) so its edges track the
+           card's. -->
+      <div class="fshell-gutter mx-(--forest-panel-inset) lg:ms-0"><slot name="header" /></div>
+
+      <!-- The page. `p-0` clears stock's body padding: the card is the frame, and what a page puts
+           inside it owns its own rhythm and its own scroll container.
+
+           `gap-0 sm:gap-0` is what keeps a toolbar FLUSH. Stock's body carries gap-4 sm:gap-6, which
+           would open a 24px trench between the toolbar's rule and the page under it — and gap-0
+           alone does not close it, because tailwind-merge drops gap-4 and keeps sm:gap-6. Same shape
+           as the p-0 sm:p-0 beside it, for the same reason. -->
+      <UDashboardPanel class="fshell-panel" :ui="{ body: 'overflow-hidden p-0 sm:p-0 gap-0 sm:gap-0' }">
+        <template #body>
+          <!-- A page's toolbar lands here: inside the card, above the page's own scrollport, so it
+               holds while the page scrolls under it. `empty:hidden` so a route without one costs
+               nothing — Teleport inserts real children, so :empty tracks it. -->
+          <div ref="toolbar" :style="seatStyle" class="fshell-toolbar empty:hidden shrink-0" />
+          <slot />
+        </template>
+      </UDashboardPanel>
+    </div>
+  </UDashboardGroup>
+</template>
+
+<!-- Unscoped: the first rule reads a SIBLING's emptiness, and scoping would stamp the attribute on
+     the panel without giving the selector a way to reach past it. -->
+<style>
+/* The card carries its own m-4. The gutter above would stack its gap on top of that and push the
+   card twice as far from the chrome as it should, so the card yields its top margin whenever the
+   gutter has a header in it. */
+.fshell-gutter:not(:empty) + .fshell-panel { margin-top: 0; }
+
+/* Chrome in the gutter sits on no surface, so it has nothing to divide and takes no edge.
+   UDashboardNavbar is the case that needs saying: its stock recipe carries `border-b border-default`,
+   which reads as a rule floating in the gutter above the card. */
+.fshell-gutter > * { border-block: 0; }
+</style>