@humanforest/frames 0.1.0

package/ATTRIBUTION.md

@@ -0,0 +1,48 @@
+# Attribution — third-party artwork
+
+The device renders in `src/art/` are unmodified vector illustrations from Wikimedia Commons,
+used under the **Creative Commons Attribution-ShareAlike 4.0 International** licence
+(<https://creativecommons.org/licenses/by-sa/4.0/>).
+
+Attribution is a condition of that licence, not a courtesy. If you redistribute this package, or
+ship a build that includes these renders, this notice must travel with it. Works derived from the
+art itself must be licensed under CC BY-SA 4.0 in turn.
+
+No changes have been made to the artwork. The package positions and clips each render; it does not
+alter the drawings.
+
+## DM115Wiki — CC BY-SA 4.0
+
+- `src/art/pixel-8a.svg`
+- `src/art/pixel-9a.svg`
+
+## Mliu92 — CC BY-SA 4.0
+
+- `src/art/pixel-10-pro-xl.svg`
+- `src/art/pixel-10-pro.svg`
+- `src/art/pixel-10.svg`
+- `src/art/pixel-8-pro.svg`
+- `src/art/pixel-8.svg`
+- `src/art/pixel-9-pro-xl.svg`
+- `src/art/pixel-9-pro.svg`
+
+## Rafael Fernandez — CC BY-SA 4.0
+
+- `src/art/iphone-12.svg`
+- `src/art/iphone-13-pro.svg`
+- `src/art/iphone-13.svg`
+- `src/art/iphone-14.svg`
+- `src/art/iphone-15-pro.svg`
+- `src/art/iphone-15.svg`
+- `src/art/iphone-16-plus.svg`
+- `src/art/iphone-16-pro-max.svg`
+- `src/art/iphone-16-pro.svg`
+- `src/art/iphone-16.svg`
+- `src/art/iphone-17-pro-max.svg`
+- `src/art/iphone-17.svg`
+- `src/art/iphone-air.svg`
+- `src/art/iphone-se-3.svg`
+- `src/art/iphone-x.svg`
+
+Source: Wikimedia Commons. Search the filename for the original file page, which carries
+the author's own attribution string and the full licence text.

package/LICENSE

@@ -0,0 +1,67 @@
+Forest Design System — Licence
+Copyright (c) 2026 HumanForest Ltd. All rights reserved.
+
+This software is published openly so that people building Forest products can install it
+without access to its source repository. It is not open-source software.
+
+
+1. GRANT
+
+You may install, use, copy and modify this software, and incorporate it into applications,
+prototypes, documents and presentations, for the purpose of building or operating Forest
+products, services and communications.
+
+This grant is free of charge and requires no separate agreement. It runs to anyone who
+obtains the software from a public registry.
+
+
+2. RESERVED
+
+All rights not granted above are reserved. In particular, you may not:
+
+  (a) redistribute this software, modified or unmodified, as a design system, component
+      library, template or theme of your own;
+
+  (b) use the HumanForest and Forest names, logos, wordmarks, sub-brand marks or any
+      confusingly similar mark. Nothing here grants any trademark right. The brand marks
+      included in these packages are provided to render Forest's own products correctly,
+      not as artwork you may adopt;
+
+  (c) represent your product as being made, endorsed or approved by HumanForest.
+
+
+3. THIRD-PARTY MATERIAL
+
+Parts of these packages are not HumanForest's to license, and the grant in section 1 does
+not extend to them. Each keeps its own terms:
+
+  TYPEFACES — Mohr and GT Haptik are licensed to HumanForest by their foundries and are NOT
+  sublicensed to you. No font binary is included in any published package. The stylesheets
+  reference https://assets.forest.bike/fonts/, which serves them to those entitled to use
+  them. If you are not covered by Forest's licences, substitute your own faces. JetBrains
+  Mono is licensed under the SIL Open Font License 1.1 and may be used under those terms.
+
+  GLYPH OUTLINES — packages/tokens ships `glyphs/glyphs.json`, letterforms of the above
+  typefaces outlined as vector paths so sub-brand lockups can be composed at runtime. It is
+  covered by the same foundry terms as the typefaces themselves, not by section 1.
+
+  DEVICE ARTWORK — packages/frames ships device renders from Wikimedia Commons under the
+  Creative Commons Attribution-ShareAlike 4.0 International licence
+  (https://creativecommons.org/licenses/by-sa/4.0/). They are unmodified. Attribution is a
+  condition of that licence: see ATTRIBUTION.md in that package, and keep it with the art
+  wherever the art travels. Works derived from the artwork must themselves be CC BY-SA 4.0.
+
+  DEPENDENCIES — third-party packages installed alongside these keep their own licences.
+
+
+4. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+
+Questions about use beyond this grant: design@forest.bike

package/README.md

@@ -0,0 +1,52 @@
+# @humanforest/frames
+
+Presentation frames for staging prototypes at true scale.
+
+| Component | What it frames |
+| --- | --- |
+| `FDeviceFrame` | A phone. Photoreal hardware, live HTML screen at the model's true logical points, OS-authentic status bar, measured safe-area insets. |
+| `FBrowserFrame` | A desktop browser window, screen sized to a real display aspect (16:10 or 16:9). |
+| `FFitFrame` | Neither — it lays a slot out at a fixed logical width and scales the result down to fit. Use it to place either frame on a page narrower than the frame itself. |
+
+```vue
+<script setup lang="ts">
+import { FDeviceFrame } from '@humanforest/frames';
+</script>
+
+<template>
+  <FDeviceFrame model="iphone-16-pro" full-bleed touch>
+    <RiderApp />
+  </FDeviceFrame>
+</template>
+```
+
+The device registry (`DEVICES`, `findDevice`) carries screen points, safe-area insets, cutout type and
+art metadata for 25 models. `artUrl(device)` resolves the bundled render.
+
+## Distribution
+
+**Private channel only.** This package is bundled into the giget layer (`packages/nuxt-layer`) and is
+never published to public npm — see the licence below for why.
+
+## Art licence
+
+The hardware renders in `src/art/` are unmodified Wikimedia Commons vectors under **CC BY-SA 4.0**.
+Attribution is a condition of the licence and must be displayed wherever the art is shown; `ART_CREDITS`
+exports the deduped list for exactly that.
+
+- Rafael Fernandez (Goldenbox) — most iPhone renders
+- Mliu92 — Pixel 8/9/10 renders
+- DM115Wiki — Pixel 8a / 9a renders
+- Hajoon0102 — iPhone SE (3rd gen)
+
+Share-alike attaches to the SVGs. Redistributing them outside the private channel would extend that
+obligation to whoever receives them, which is why the public npm packages ship no device art.
+
+## Artwork licence
+
+The device renders in `src/art/` are unmodified Wikimedia Commons vectors under
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/), by Rafael Fernandez, Mliu92 and
+DM115Wiki. Attribution is a condition of that licence rather than a courtesy: see
+[ATTRIBUTION.md](./ATTRIBUTION.md), and keep that notice with the art wherever it is redistributed
+or displayed — a published build, an exported PDF, a hosted deck. The art stays CC BY-SA; the rest
+of this package does not become CC BY-SA by containing it.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@humanforest/frames",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "ATTRIBUTION.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./devices": "./src/devices.ts",
+    "./art": "./src/art.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.5",
+    "@nuxt/ui": "^4"
+  },
+  "devDependencies": {
+    "vue": "^3.5.22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/src/FBrowserFrame.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+// Desktop browser chrome — the web counterpart to DeviceFrame. A neutral macOS-style window
+// (traffic lights + address pill) wrapping a live app screen rendered at the chosen logical width.
+// The screen is a `@container`, so the slotted shell reflows against the frame width (not the
+// viewport) — switching the Viewport control genuinely resizes the layout. Flip `dark` to theme the
+// screen subtree (adds `.dark` over `bg-default text-default`, exactly like DeviceFrame's screen).
+// ★ The SCREEN carries a real display aspect — 16:10 or 16:9, the two shapes a desktop actually comes in
+// — and the height is derived from it rather than typed in. A hand-picked height drifts into ratios no
+// monitor has, which makes a specimen's reflow decisions untestable against anything real.
+const props = withDefaults(
+  defineProps<{
+    width: number;
+    aspect?: '16/10' | '16/9';
+    /** Overrides the aspect. Only for a screen that is deliberately not a whole display. */
+    height?: number;
+    dark?: boolean;
+    url?: string;
+  }>(),
+  { aspect: '16/10', dark: false, url: 'console.forest.bike/fleet' },
+);
+
+const screenH = computed(() => props.height ?? Math.round(props.width * (props.aspect === '16/9' ? 9 / 16 : 10 / 16)));
+</script>
+
+<template>
+  <div
+    class="shrink-0 overflow-hidden rounded-xl border border-default bg-default"
+    :style="{ width: width + 'px', filter: 'drop-shadow(0 25px 45px rgba(0,0,0,.28))' }"
+  >
+    <!-- title bar -->
+    <div class="flex items-center gap-3 border-b border-default bg-elevated/60 px-4 py-2.5">
+      <div class="flex items-center gap-1.5">
+        <span class="size-3 rounded-full bg-[#ff5f57]"></span>
+        <span class="size-3 rounded-full bg-[#febc2e]"></span>
+        <span class="size-3 rounded-full bg-[#28c840]"></span>
+      </div>
+      <div class="mx-auto flex w-full max-w-xs items-center justify-center gap-1.5 rounded-md border border-default bg-default px-3 py-1 text-xs text-muted">
+        <UIcon name="i-lucide-lock" class="size-3 text-dimmed" />
+        {{ url }}
+      </div>
+      <UIcon name="i-lucide-plus" class="size-4 shrink-0 text-dimmed" />
+    </div>
+
+    <!-- live screen — its own theming context + container -->
+    <div
+      :class="['@container relative overflow-hidden bg-default text-default', { dark }]"
+      :style="{ height: screenH + 'px' }"
+    >
+      <slot />
+    </div>
+  </div>
+</template>

package/src/FDeviceFrame.vue

@@ -0,0 +1,242 @@
+<script setup lang="ts">
+// Photoreal device shell: an unmodified Wikimedia SVG render is the hardware; the live HTML screen is
+// overlaid at the SVG's measured screen insets and clipped to the SVG's own screen path. We draw the
+// cutout (island/notch/punch-hole) + an OS-authentic status bar on top.
+//
+// Status bar matches the platform: iOS uses the system font (SF Pro via system-ui) with hand-drawn
+// SF-style glyphs (cellular bars, wifi cone, capsule battery); Android uses Roboto with Material
+// Symbols glyphs. Sizes follow each platform's status bar. Rendered at true 1× logical points.
+import { computed, useId } from 'vue';
+import { findDevice, type DeviceModel } from './devices';
+import { artUrl } from './art';
+
+const clipId = `screenclip-${useId()}`;
+
+const props = withDefaults(
+  defineProps<{
+    model: string | DeviceModel;
+    dark?: boolean;
+    statusBar?: boolean;
+    time?: string;
+    /** Overlay the safe-area insets (top/bottom) for inspection. */
+    showSafe?: boolean;
+    /** Slot content runs edge-to-edge under the status bar (maps, camera). Pad with `safe.top`. */
+    fullBleed?: boolean;
+    /** A real phone is a COARSE pointer. Opt in to stamp `[data-force-coarse]` on the screen so the
+     *  preset's `coarse:` touch bumps fire for the content inside — the truthful render for a
+     *  web-cut surface (standard/marketing) viewed on a device. The mobile cut stays put on its own
+     *  (its `cut-fixed` opts the bump out — it already baked its size), and components with no
+     *  `coarse:` bump are unaffected. Default off so existing frames don't shift. */
+    touch?: boolean;
+  }>(),
+  { dark: false, statusBar: true, time: '9:41', showSafe: false, fullBleed: false, touch: false },
+);
+
+const device = computed<DeviceModel>(() =>
+  typeof props.model === 'string' ? findDevice(props.model) : props.model,
+);
+const art = computed(() => device.value.art!);
+const artSrc = computed(() => artUrl(device.value));
+const os = computed<'ios' | 'android'>(() => (device.value.brand === 'Apple' ? 'ios' : 'android'));
+
+const dims = computed(() => {
+  const a = art.value;
+  const w = device.value.screen.w / (1 - (a.inset.left + a.inset.right) / 100);
+  return { w, h: w * a.aspect };
+});
+
+const screenStyle = computed(() => {
+  const a = art.value;
+  return {
+    top: a.inset.top + '%',
+    left: a.inset.left + '%',
+    right: a.inset.right + '%',
+    bottom: a.inset.bottom + '%',
+    ...(a.clip
+      ? { clipPath: `url(#${clipId})` }
+      : { borderRadius: (device.value.screen.w * (a.radiusPct ?? 0)) / 100 + 'px' }),
+  };
+});
+
+const screenW = computed(() => device.value.screen.w);
+const statusBarH = computed(() => device.value.safe.top);
+const cutout = computed(() => device.value.cutout);
+const island = computed(() => ({ w: Math.round(screenW.value * 0.3), h: 36, top: 10 }));
+const notch = computed(() => ({ w: Math.round(screenW.value * 0.42), h: 30 }));
+const compact = computed(() => cutout.value === 'home' || cutout.value === 'none');
+
+// Safe-area bridge. A mock phone has no notch for the browser to report, so `env(safe-area-inset-*)`
+// resolves to 0 in here and chrome would tuck under the island. The frame publishes the device's
+// measured insets as the vars FCanvasHud reads first; on a real device nothing sets them and the
+// `env()` fallback takes over. Top is only owed when the content runs full-bleed — otherwise the
+// wrapper is already offset below the status bar and charging for it twice would double the gap.
+const safeVars = computed(() => ({
+  '--forest-safe-top': (props.fullBleed ? device.value.safe.top : 0) + 'px',
+  '--forest-safe-bottom': device.value.safe.bottom + 'px',
+}));
+
+// Status-bar metrics, computed per device so the clock/icons sit at the cutout's vertical centre and
+// clear the rounded-corner curve (no per-device hand-tuning, no clipped glyphs).
+const sb = computed(() => {
+  const d = device.value;
+  const ios = os.value === 'ios';
+  // vertical centre of the row = centre of the cutout (island/punch-hole) or middle of a short bar
+  const centerY =
+    cutout.value === 'island' ? island.value.top + island.value.h / 2
+    : cutout.value === 'punch-hole' ? 19
+    : statusBarH.value * 0.5;
+  // screen corner radius (px) → how far the corner curves in at centerY
+  const cornerR = d.art.radiusPct ? (d.screen.w * d.art.radiusPct) / 100 : d.screen.w * (ios ? 0.13 : 0.12);
+  const cornerInset = centerY >= cornerR ? 0 : cornerR - Math.sqrt(cornerR * cornerR - (cornerR - centerY) ** 2);
+  const basePad = ios ? (compact.value ? 16 : 22) : 14;
+  const padX = Math.max(basePad, Math.ceil(cornerInset) + 8);
+  return ios
+    ? { padX, barH: centerY * 2, clockPx: 15, clockFont: '-apple-system, "SF Pro Text", system-ui, sans-serif', clockWeight: 600, iconGap: 5 }
+    : { padX, barH: centerY * 2, clockPx: 14, clockFont: 'Roboto, system-ui, sans-serif', clockWeight: 500, iconGap: 6 };
+});
+
+</script>
+
+<template>
+  <div
+    class="device relative shrink-0"
+    :style="{ width: dims.w + 'px', height: dims.h + 'px', filter: 'drop-shadow(0 25px 45px rgba(0,0,0,.28))' }"
+  >
+    <img :src="artSrc" alt="" class="pointer-events-none absolute inset-0 h-full w-full select-none" draggable="false" />
+
+    <svg v-if="art.clip" class="absolute size-0" aria-hidden="true">
+      <defs>
+        <clipPath :id="clipId" clipPathUnits="objectBoundingBox"><path :d="art.clip" /></clipPath>
+      </defs>
+    </svg>
+
+    <!-- LIVE SCREEN -->
+    <div :class="['screen absolute overflow-hidden bg-default text-default', { dark }]" :style="screenStyle">
+      <!-- cutout -->
+      <div
+        v-if="cutout === 'island'"
+        class="absolute z-30 -translate-x-1/2 rounded-full bg-black"
+        :style="{ left: '50%', top: island.top + 'px', width: island.w + 'px', height: island.h + 'px' }"
+      ></div>
+      <div
+        v-else-if="cutout === 'notch' && !art.clip"
+        class="absolute left-1/2 top-0 z-30 -translate-x-1/2 bg-black"
+        :style="{ width: notch.w + 'px', height: notch.h + 'px', borderRadius: '0 0 18px 18px' }"
+      ></div>
+      <div
+        v-else-if="cutout === 'punch-hole'"
+        class="absolute left-1/2 top-3 z-30 size-3.5 -translate-x-1/2 rounded-full bg-black"
+      ></div>
+
+      <!-- OS-authentic status bar -->
+      <div
+        v-if="statusBar"
+        class="absolute inset-x-0 top-0 z-20 flex items-center justify-between text-highlighted"
+        :style="{ height: sb.barH + 'px', paddingInline: sb.padX + 'px' }"
+      >
+        <span
+          class="tabular-nums"
+          :style="{ fontFamily: sb.clockFont, fontSize: sb.clockPx + 'px', fontWeight: sb.clockWeight, letterSpacing: os === 'ios' ? '.01em' : '0' }"
+        >{{ time }}</span>
+
+        <!-- iOS glyphs: cellular bars · wifi cone · capsule battery -->
+        <div v-if="os === 'ios'" class="flex items-center" :style="{ gap: sb.iconGap + 'px' }">
+          <svg viewBox="0 0 18 12" height="11" fill="currentColor" aria-hidden="true">
+            <rect x="0" y="8" width="3" height="4" rx="1" /><rect x="5" y="5.5" width="3" height="6.5" rx="1" />
+            <rect x="10" y="3" width="3" height="9" rx="1" /><rect x="15" y="0" width="3" height="12" rx="1" />
+          </svg>
+          <svg viewBox="0 0 18 13" height="12" fill="currentColor" aria-hidden="true">
+            <path d="M9 2.4c2.9 0 5.6 1.05 7.7 2.9a.6.6 0 0 1 .03.87L9.5 13.5a.7.7 0 0 1-1 0L1.27 6.17a.6.6 0 0 1 .03-.87C3.4 3.45 6.1 2.4 9 2.4Z" />
+          </svg>
+          <svg viewBox="0 0 28 13" height="12" aria-hidden="true">
+            <rect x=".5" y=".5" width="23" height="12" rx="3.6" fill="none" stroke="currentColor" stroke-opacity=".4" />
+            <rect x="2" y="2" width="18" height="9" rx="2.2" fill="currentColor" />
+            <path d="M25.3 4.3c1.1.25 1.1 4.15 0 4.4Z" fill="currentColor" fill-opacity=".4" />
+          </svg>
+        </div>
+
+        <!-- Android glyphs: Material Symbols (cellular · wifi · battery) -->
+        <div v-else class="flex items-center" :style="{ gap: sb.iconGap + 'px' }">
+          <svg viewBox="0 -960 960 960" height="15" fill="currentColor" aria-hidden="true">
+            <path d="M260-160q-25 0-42.5-17.5T200-220v-120q0-25 17.5-42.5T260-400q25 0 42.5 17.5T320-340v120q0 25-17.5 42.5T260-160Zm240 0q-25 0-42.5-17.5T440-220v-320q0-25 17.5-42.5T500-600q25 0 42.5 17.5T560-540v320q0 25-17.5 42.5T500-160Zm240 0q-25 0-42.5-17.5T680-220v-520q0-25 17.5-42.5T740-800q25 0 42.5 17.5T800-740v520q0 25-17.5 42.5T740-160Z" />
+          </svg>
+          <svg viewBox="0 -960 960 960" height="15" fill="currentColor" aria-hidden="true">
+            <path d="M174-540q67-48 145-74t161-26q83 0 161 26t145 74l58-58q-79-60-172-91t-192-31q-99 0-192 31t-172 91l58 58Zm249 363L61-539q-12-12-18-27t-6-30q0-17 7-32.5T65-656q82-71 195-107.5T480-800q107 0 220 36.5T895-656q14 12 21 27.5t7 32.5q0 15-6 30t-18 27L537-177q-12 12-27 18t-30 6q-15 0-30-6t-27-18Z" />
+          </svg>
+          <svg viewBox="0 -960 960 960" height="15" fill="currentColor" aria-hidden="true">
+            <path d="M320-80q-17 0-28.5-11.5T280-120v-640q0-17 11.5-28.5T320-800h80v-40q0-17 11.5-28.5T440-880h80q17 0 28.5 11.5T560-840v40h80q17 0 28.5 11.5T680-760v640q0 17-11.5 28.5T640-80H320Z" />
+          </svg>
+        </div>
+      </div>
+
+      <!-- screen content — starts below the status bar unless fullBleed (maps, camera), in which
+           case it runs edge-to-edge and the status bar/cutout (z-20/z-30) draw over it -->
+      <div
+        class="absolute inset-x-0 bottom-0 overflow-hidden"
+        :style="{ top: fullBleed ? '0px' : statusBarH + 'px', ...safeVars }"
+        :data-force-coarse="touch ? '' : undefined"
+      >
+        <slot :device="device" :safe="device.safe" />
+      </div>
+
+      <!-- home indicator -->
+      <div
+        v-if="!compact"
+        class="absolute bottom-2 left-1/2 z-20 h-1 -translate-x-1/2 rounded-full bg-highlighted/40"
+        :style="{ width: screenW * 0.36 + 'px' }"
+      ></div>
+
+      <!-- safe-area overlay (toggle) -->
+      <template v-if="showSafe">
+        <div
+          class="pointer-events-none absolute inset-x-0 top-0 z-40 flex items-start justify-center"
+          :style="{ height: device.safe.top + 'px', background: 'rgba(56,189,248,.28)', borderBottom: '1px dashed rgba(2,132,199,.9)' }"
+        >
+          <span class="mt-0.5 rounded bg-sky-600 px-1 text-[9px] font-semibold text-white">{{ device.safe.top }}pt</span>
+        </div>
+        <div
+          v-if="device.safe.bottom > 0"
+          class="pointer-events-none absolute inset-x-0 bottom-0 z-40 flex items-end justify-center"
+          :style="{ height: device.safe.bottom + 'px', background: 'rgba(56,189,248,.28)', borderTop: '1px dashed rgba(2,132,199,.9)' }"
+        >
+          <span class="mb-0.5 rounded bg-sky-600 px-1 text-[9px] font-semibold text-white">{{ device.safe.bottom }}pt</span>
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* A touch glyph over the live screen, so a mouse reading a phone mock reads as a finger, not a
+   pointer: a solid grey contact dot inside a translucent halo, the shape a fingertip makes. Forced
+   onto descendants too — otherwise every button's own `cursor: pointer` wins back.
+   The SVG is baked static (no tokens, no `currentColor`), so the two modes are two encoded copies —
+   dark grey on a light screen, light grey on a dark one. Fine pointers only.
+   32px is the ceiling, not a taste call: Chrome refuses a cursor bitmap larger than 32×32 on
+   Windows and silently falls back to the arrow. */
+@media (hover: hover) and (pointer: fine) {
+  .screen,
+  .screen :deep(*) {
+    cursor:
+      url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Ccircle cx='16' cy='16' r='15' fill='%2352525B' fill-opacity='.28'/%3E%3Ccircle cx='16' cy='16' r='9.5' fill='%2352525B'/%3E%3C/svg%3E")
+        16 16,
+      pointer;
+  }
+
+  /* Two ways a screen ends up dark: the frame's own `dark` prop, or the whole docs app being in
+     dark mode (`html.dark`) — the screen inherits that through `bg-default` without ever carrying
+     the class itself. Both need the light-grey glyph.
+     Plain descendant selectors, NOT `:global(.dark) .screen` — Vue compiles that down to bare
+     `.dark`, which is on `<html>`, and `cursor` inherits to the whole page. Scoping only stamps the
+     last compound, so an unscoped ancestor matches on its own. */
+  .screen.dark,
+  .screen.dark :deep(*),
+  .dark .screen,
+  .dark .screen :deep(*) {
+    cursor:
+      url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Ccircle cx='16' cy='16' r='15' fill='%23D4D4D8' fill-opacity='.28'/%3E%3Ccircle cx='16' cy='16' r='9.5' fill='%23D4D4D8'/%3E%3C/svg%3E")
+        16 16,
+      pointer;
+  }
+}
+</style>

package/src/FFitFrame.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+// Lays its slot out at a fixed LOGICAL width and scales the result down to fit the space available.
+//
+// Why a specimen wants this: a shell only reflows honestly at a real width, and its measures are absolute
+// — `railTop: 17rem` is 20% of 1360px and 65% of a 420px diagram box. Laying out at the real width and
+// shrinking the picture keeps every proportion true; shrinking the width instead changes the design.
+//
+// ★ SCALED WITH `transform`, NEVER WITH `zoom`. Both shrink the frame; only one keeps a Mapbox canvas
+// correct. Mapbox sizes its canvas from the container's LAYOUT box (clientWidth) and writes that back as
+// the canvas's CSS size. `zoom` changes the layout box, so the factor lands twice: MEASURED at zoom 0.72,
+// an 862px container held a 621px canvas — dead strips down two edges, and `map.resize()` cannot fix it
+// because it recomputes the same wrong value. A `transform` leaves the layout box alone, so Mapbox writes
+// the logical size and the transform scales the result once.
+//
+// The cost of a transform is that the element still OCCUPIES its unscaled box, which is what the rest of
+// this component is for.
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** Logical width the slot lays out at, whatever the space available. */
+    width: number;
+    /** Largest scale to draw at, so a wide page does not render the specimen at 1:1. */
+    maxScale?: number;
+  }>(),
+  { maxScale: 1 },
+);
+
+// The wrapper's own padding, added back to the height it reserves. Weighted downwards because a frame's
+// shadow is cast downwards, so that is the side that needs the room.
+const PAD_TOP = 8;
+const PAD_BOTTOM = 24;
+
+const inner = ref<HTMLElement | null>(null);
+const wrapper = ref<HTMLElement | null>(null);
+const naturalH = ref(0);
+const availW = ref(0);
+
+// Watched rather than read in onMounted: the refs are not guaranteed to be populated by the time this
+// component's mounted hook runs, and a missed attach leaves the wrapper unsized with no visible error.
+// No loop between the two: the slot's unscaled height is fixed by its own content, and the wrapper's
+// width is its block width — neither depends on the scale derived from them.
+const innerRO = new ResizeObserver(([e]) => { naturalH.value = e.contentRect.height; });
+const wrapRO = new ResizeObserver(([e]) => { availW.value = e.contentRect.width; });
+watch(inner, (el) => { innerRO.disconnect(); if (el) innerRO.observe(el); }, { immediate: true, flush: 'post' });
+watch(wrapper, (el) => { wrapRO.disconnect(); if (el) wrapRO.observe(el); }, { immediate: true, flush: 'post' });
+onBeforeUnmount(() => { innerRO.disconnect(); wrapRO.disconnect(); });
+
+// ★ SCALE TO FIT, capped. A fixed factor overflows its container the moment the page is narrower than
+// width × scale — the slot's layout width never changes, so nothing else absorbs it.
+const fit = computed(() => (availW.value ? Math.min(props.maxScale, availW.value / props.width) : props.maxScale));
+
+// Height the scaled frame actually takes on the page. 0 until measured, so nothing jumps.
+const reservedH = computed(() =>
+  naturalH.value ? Math.round(naturalH.value * fit.value) + PAD_TOP + PAD_BOTTOM : 0,
+);
+</script>
+
+<template>
+  <!-- The wrapper reserves the SCALED height and the shadow's room in its own padding. It does NOT clip:
+       the height already stops the unscaled leftover box from pushing the page around, and that leftover
+       box paints nothing. Any `overflow` value here costs the shadow — `hidden` cuts it off square, and
+       `hidden`/`clip` on one axis forces the other to `auto`, which adds a scrollbar. -->
+  <div
+    ref="wrapper"
+    class="flex justify-center pt-2 pb-6"
+    :style="reservedH ? { height: `${reservedH}px` } : undefined"
+  >
+    <!-- `self-start` is load-bearing: without it the flex default stretches this to the wrapper's
+         reserved height, which the wrapper derives from THIS element's height — a loop that collapses
+         both to nothing. `shrink-0` only guards the main axis.
+         `pointer-events-none` because this box keeps its UNSCALED height, so part of it hangs past the
+         frame over whatever follows. Transparent, but it would still swallow clicks and text selection
+         there. The slot opts back in. -->
+    <div
+      ref="inner"
+      class="pointer-events-none shrink-0 self-start [&>*]:pointer-events-auto"
+      :style="{ transform: `scale(${fit})`, transformOrigin: 'top center' }"
+    >
+      <slot />
+    </div>
+  </div>
+</template>