@humanforest/nuxt-layer 0.2.0 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@humanforest/nuxt-layer",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Forest design system as a Nuxt layer — extend it to inherit the theme, colour roles, icons and brand fonts in one line.",
   "main": "./nuxt.config.ts",
   "files": [

package/packages/charts/src/FSparkline.vue

@@ -100,10 +100,22 @@ const yCompare = (d: Point) => d.c;
 
 const hasCompare = computed(() => !!props.compare?.some((v) => v !== null && v !== undefined));
 
-// Bars are measured from zero, not from the data's own floor. The line mark frames min-to-max
-// because it reads as a shape; a bar reads as a LENGTH, and a bar that starts anywhere but zero has
-// a length no longer proportional to its value. The domain therefore always contains zero, which
-// also puts negative readings below the baseline instead of quietly flipping them.
+// The line marks share one scale, framed by the floor and ceiling of everything drawn on it — a
+// line reads as a shape, and a shape wants its own range. Set by hand because an Unovis area is
+// measured from a baseline: left to itself, `area` pulls the floor to zero and flattens the line it
+// is filling under. `null` when there is nothing to draw, so the container keeps its own fallback.
+const domain = computed<[number, number] | null>(() => {
+  const vals = [...props.data, ...(props.compare ?? [])].filter((v): v is number => typeof v === 'number');
+  return vals.length ? [Math.min(...vals), Math.max(...vals)] : null;
+});
+// An area is a band from its baseline to baseline + y, not a fill up to y, so reaching the line
+// from the floor of the frame means passing the height above that floor.
+const yFromFloor = (d: Point) => (d.v === null || !domain.value ? null : d.v - domain.value[0]);
+
+// Bars are the exception: they are measured from zero, not from the data's own floor. A bar reads
+// as a LENGTH, and a bar that starts anywhere but zero has a length no longer proportional to its
+// value. The bar domain therefore always contains zero, which also puts negative readings below the
+// baseline instead of quietly flipping them.
 const barDomain = computed(() => {
   const vals = props.data.filter((v): v is number => v !== null);
   const lo = Math.min(0, ...vals);
@@ -134,15 +146,11 @@ const last = computed(() => {
   for (let i = props.data.length - 1; i >= 0; i--) if (props.data[i] !== null) return props.data[i] as number;
   return null;
 });
-const bounds = computed(() => {
-  const vals = props.data.filter((v): v is number => v !== null);
-  return { min: Math.min(...vals), max: Math.max(...vals) };
-});
 // Fraction of the height the final point sits at, for the endpoint dot.
 const endpointTop = computed(() => {
-  const { min, max } = bounds.value;
-  if (last.value === null || max === min) return 50;
-  return (1 - (last.value - min) / (max - min)) * 100;
+  const [lo, hi] = domain.value ?? [0, 0];
+  if (last.value === null || hi === lo) return 50;
+  return (1 - (last.value - lo) / (hi - lo)) * 100;
 });
 </script>
 
@@ -179,6 +187,7 @@ const endpointTop = computed(() => {
       :data="points"
       :height="height"
       :margin="{ top: 2, right: endpoint ? 4 : 0, bottom: 0, left: 0 }"
+      :y-domain="domain ?? undefined"
       :duration="motionDuration('slow')"
     >
       <!-- Comparison first, so the current series draws over it. Dashed and thinner: the dash says
@@ -194,7 +203,7 @@ const endpointTop = computed(() => {
         :opacity="0.45"
         :curve-type="curve ? CurveType.MonotoneX : CurveType.Linear"
       />
-      <VisArea v-if="area" :x="x" :y="y" :color="color" :opacity="0.12" :curve-type="curve ? CurveType.MonotoneX : CurveType.Linear" />
+      <VisArea v-if="area" :x="x" :y="yFromFloor" :baseline="domain?.[0] ?? 0" :color="color" :opacity="0.12" :curve-type="curve ? CurveType.MonotoneX : CurveType.Linear" />
       <VisLine :x="x" :y="y" :color="color" :line-width="1.5" :curve-type="curve ? CurveType.MonotoneX : CurveType.Linear" />
     </VisXYContainer>
     <span

package/packages/tokens/src/colourEngine.ts

@@ -1,14 +1,20 @@
 // colourEngine.ts — framework-free colour math: the canonical Forest colour-generation method.
 // All functions exported; consumed by the Forest colour documentation page.
 
+// Colour vectors are fixed-length triples. Typed as a tuple rather than number[] so indexed
+// reads are known-present: number[] makes every component `number | undefined` under
+// noUncheckedIndexedAccess, which is how the apps that extend this layer typecheck it.
+export type Vec3 = [number, number, number];
+
 // ---- OKLCH ↔ sRGB (compact port of scales.ts) ----
 export const srgbToLin = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
 export const linToSrgb = (c: number) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
-export function hexToLin(hex: string): number[] {
+export function hexToLin(hex: string): Vec3 {
   const c = hex.replace('#', '');
-  return [0, 2, 4].map((i) => srgbToLin(parseInt(c.slice(i, i + 2), 16) / 255));
+  const ch = (i: number) => srgbToLin(parseInt(c.slice(i, i + 2), 16) / 255);
+  return [ch(0), ch(2), ch(4)];
 }
-export function linToOklab([r, g, b]: number[]): number[] {
+export function linToOklab([r, g, b]: Vec3): Vec3 {
   const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
   const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
   const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
@@ -18,7 +24,7 @@ export function linToOklab([r, g, b]: number[]): number[] {
     0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
   ];
 }
-export function oklabToLin([L, a, b]: number[]): number[] {
+export function oklabToLin([L, a, b]: Vec3): Vec3 {
   const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
   const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
   const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
@@ -134,12 +140,12 @@ export const hueOf = (hex: string) => hexToOklch(hex).H;
 
 // ---- Display-P3 gamut (wider than sRGB; both D65, so a plain linear matrix maps sRGB→P3) ----
 // Lets ramps reach chroma sRGB can't show, emitted as a color(display-p3 …) primary with a hex fallback.
-const sRGBlinToP3lin = ([r, g, b]: number[]): number[] => [
+const sRGBlinToP3lin = ([r, g, b]: Vec3): Vec3 => [
   0.8224621 * r + 0.177538 * g,
   0.0331941 * r + 0.9668058 * g,
   0.0170827 * r + 0.0723974 * g + 0.9105199 * b,
 ];
-export const inGamutP3 = (linsrgb: number[]) => sRGBlinToP3lin(linsrgb).every((v) => v >= -0.001 && v <= 1.001);
+export const inGamutP3 = (linsrgb: Vec3) => sRGBlinToP3lin(linsrgb).every((v) => v >= -0.001 && v <= 1.001);
 export function maxChromaP3(L: number, H: number) {
   const rad = (H * Math.PI) / 180, co = Math.cos(rad), si = Math.sin(rad);
   let lo = 0, hi = 0.4;
@@ -156,13 +162,14 @@ export function oklchToP3(L: number, C: number, H: number): string {
     c = lo;
   }
   const enc = (v: number) => Math.max(0, Math.min(1, linToSrgb(v)));
-  const [r, g, b] = sRGBlinToP3lin(oklabToLin([L, c * co, c * si])).map(enc);
+  const [pr, pg, pb] = sRGBlinToP3lin(oklabToLin([L, c * co, c * si]));
+  const r = enc(pr), g = enc(pg), b = enc(pb);
   return `color(display-p3 ${r.toFixed(4)} ${g.toFixed(4)} ${b.toFixed(4)})`;
 }
 
 // ---- Okhsl chroma model (Ottosson): smooth 3-anchor (C0 / Cmid / Cmax) rational interpolation ----
 export function okhslCuspPoint(H: number) { let bL = 0.35, bc = 0; for (let L = 0.35; L <= 0.99; L += 0.006) { const c = maxChromaAt(L, H); if (c > bc) { bc = c; bL = L; } } return { L: bL, C: bc }; }
-export function getSTmid(a: number, b: number) {
+export function getSTmid(a: number, b: number): [number, number] {
   const S = 0.11516993 + 1 / (7.4477897 + 4.1590124 * b + a * (-2.19557347 + 1.75198401 * b + a * (-2.13704948 - 10.02301043 * b + a * (-4.24894561 + 5.38770819 * b + 4.69891013 * a))));
   const T = 0.11239642 + 1 / (1.6132032 - 0.68124379 * b + a * (0.40370612 + 0.90148123 * b + a * (-0.27087943 + 0.6122399 * b + a * (0.00299215 - 0.45399568 * b - 0.14661872 * a))));
   return [S, T];
@@ -197,7 +204,7 @@ export const dEok = (h1: string, h2: string) => { const A = labOf(h1), B = labOf
 // STRESS ~47 vs CIEDE2000 ~29 on COMBVD). Author scales with dEok; GATE shipped data-viz palettes
 // on dE00 / dE00cvd. See COLOUR-DATAVIZ-RESEARCH.md.
 // CIELAB (D65) from linear-sRGB / hex.
-export function linToLab([r, g, b]: number[]): number[] {
+export function linToLab([r, g, b]: Vec3): Vec3 {
   const X = 0.4124564 * r + 0.3575761 * g + 0.1804375 * b;
   const Y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
   const Z = 0.0193339 * r + 0.119192 * g + 0.9503041 * b;
@@ -207,7 +214,7 @@ export function linToLab([r, g, b]: number[]): number[] {
 }
 export const labCie = (hex: string) => linToLab(hexToLin(hex));
 // CIEDE2000. Verified against the canonical Sharma et al. reference vectors (incl. the 1.0000 hue-wrap traps).
-export function ciede2000([L1, a1, b1]: number[], [L2, a2, b2]: number[]): number {
+export function ciede2000([L1, a1, b1]: Vec3, [L2, a2, b2]: Vec3): number {
   const rad = Math.PI / 180, deg = 180 / Math.PI;
   const C1 = Math.hypot(a1, b1), C2 = Math.hypot(a2, b2), Cb = (C1 + C2) / 2;
   const G = 0.5 * (1 - Math.sqrt(Cb ** 7 / (Cb ** 7 + 25 ** 7)));
@@ -230,12 +237,16 @@ export const dE00 = (h1: string, h2: string) => Math.round(ciede2000(labCie(h1),
 // CVD simulation — Machado, Oliveira & Fernandes (2009), severity 1.0, applied in linear sRGB.
 export const CVD_TYPES = ['protan', 'deutan', 'tritan'] as const;
 export type CvdType = (typeof CVD_TYPES)[number];
-const CVD_M: Record<CvdType, number[][]> = {
+const CVD_M: Record<CvdType, [Vec3, Vec3, Vec3]> = {
   protan: [[0.152286, 1.052583, -0.204868], [0.114503, 0.786281, 0.099216], [-0.003882, -0.048116, 1.051998]],
   deutan: [[0.367322, 0.860646, -0.227968], [0.280085, 0.672501, 0.047413], [-0.01182, 0.04294, 0.968881]],
   tritan: [[1.255528, -0.076749, -0.178779], [-0.078411, 0.930809, 0.147602], [0.004733, 0.691367, 0.3039]],
 };
-export const simulateCvdLin = (lin: number[], t: CvdType) => CVD_M[t].map((row) => row[0] * lin[0] + row[1] * lin[1] + row[2] * lin[2]);
+export const simulateCvdLin = (lin: Vec3, t: CvdType): Vec3 => {
+  const [m0, m1, m2] = CVD_M[t];
+  const dot = (row: Vec3) => row[0] * lin[0] + row[1] * lin[1] + row[2] * lin[2];
+  return [dot(m0), dot(m1), dot(m2)];
+};
 export const simulateCvd = (hex: string, t: CvdType) => { const l = simulateCvdLin(hexToLin(hex), t); const to = (v: number) => Math.round(Math.max(0, Math.min(1, linToSrgb(v))) * 255).toString(16).padStart(2, '0'); return '#' + to(l[0]) + to(l[1]) + to(l[2]); };
 // Worst-case ΔE00 across normal + all three dichromacies — the number to gate categorical series on.
 export const dE00cvd = (h1: string, h2: string) => {
@@ -248,7 +259,7 @@ export const dE00cvd = (h1: string, h2: string) => {
 export interface DataVizGate { minSep: number; minBrand: number; minContrast: number; bgs: string[]; brand: string[]; }
 export function validateDataViz(hexes: string[], g: DataVizGate) {
   const pairs: { a: string; b: string; dE: number }[] = [];
-  for (let i = 0; i < hexes.length; i++) for (let j = i + 1; j < hexes.length; j++) pairs.push({ a: hexes[i], b: hexes[j], dE: dE00cvd(hexes[i], hexes[j]) });
+  hexes.forEach((a, i) => hexes.slice(i + 1).forEach((b) => pairs.push({ a, b, dE: dE00cvd(a, b) })));
   const minMutual = Math.min(...pairs.map((p) => p.dE));
   const brand = hexes.map((h) => ({ h, dE: Math.min(...g.brand.map((b) => dE00(h, b))) }));
   const minBrand = Math.min(...brand.map((b) => b.dE));
@@ -387,7 +398,7 @@ export const TWL_WARM: Record<number, number> = { 0: 0.99, 50: 0.97, 100: 0.935,
 export const ladderFor = (fam: string) => (fam === 'warm' ? TWL_WARM : BRIGHT.has(fam) ? TWL_BRIGHT : TWL);
 export const TWFRAC: Record<number, number> = { 0: 0.16, 50: 0.34, 100: 0.62, 200: 0.72, 300: 0.84, 400: 0.9, 500: 0.9, 600: 0.88, 700: 0.84, 800: 0.72, 900: 0.58, 950: 0.44 };
 export const MUTE = 0.8;
-export const nearestOn = (hex: string, ladder: Record<number, number>) => { const L = hexToOklch(hex).L; let b = BRAND_SHADES[0], bd = Infinity; for (const s of BRAND_SHADES) { const d = Math.abs(ladder[s] - L); if (d < bd) { bd = d; b = s; } } return b; };
+export const nearestOn = (hex: string, ladder: Record<number, number>) => { const L = hexToOklch(hex).L; let b = BRAND_SHADES[0]!, bd = Infinity; for (const s of BRAND_SHADES) { const d = Math.abs(ladder[s]! - L); if (d < bd) { bd = d; b = s; } } return b; };
 export const CMUL: Record<string, Record<number, number>> = {
   acid: { 0: 0.4, 50: 0.45, 100: 0.5, 200: 0.65, 300: 0.82 },
   primary: { 400: 1.15, 600: 1.3, 700: 1.4, 800: 1.4, 900: 1.3 },
@@ -411,9 +422,9 @@ export const TUNE: Record<string, Record<number, { L?: number; C?: number; H?: n
 // ---- buildTW: a simple generate-then-stamp ramp (retained as a comparison/utility) ----
 export function buildTW(H: number, pins: Record<number, string> = {}, ladder: Record<number, number> = TWL, cmul?: Record<number, number>, dHue = 0, sat = 0.9) {
   const o: Record<number, string> = {};
-  const L5 = ladder[500], Lbot = ladder[950];
+  const L5 = ladder[500]!, Lbot = ladder[950]!;
   for (const s of BRAND_SHADES) {
-    const L = ladder[s];
+    const L = ladder[s]!;
     const hh = dHue && L < L5 ? H + dHue * ((L5 - L) / (L5 - Lbot || 1)) : H;
     o[s] = oklchToHex(L, okhslChroma(L, hh, sat) * (cmul?.[s] ?? 1), hh);
   }
@@ -422,25 +433,28 @@ export function buildTW(H: number, pins: Record<number, string> = {}, ladder: Re
 }
 
 // ---- PCHIP machinery (monotone-cubic C(L) / H(L) splines through anchors) ----
+// The indexing below is genuinely dynamic — the loop bounds guarantee each read is in range but
+// TypeScript cannot see that, so the reads carry `!`. Guards would be dead branches, and casting
+// to number would hide a real out-of-range read. Note pchipSlopes still assumes n >= 2, as before.
 export function pchipSlopes(xs: number[], ys: number[]) {
   const n = xs.length, h: number[] = [], d: number[] = [], m: number[] = new Array(n);
-  for (let i = 0; i < n - 1; i++) { h[i] = xs[i + 1] - xs[i]; d[i] = (ys[i + 1] - ys[i]) / h[i]; }
-  m[0] = d[0]; m[n - 1] = d[n - 2];
+  for (let i = 0; i < n - 1; i++) { h[i] = xs[i + 1]! - xs[i]!; d[i] = (ys[i + 1]! - ys[i]!) / h[i]!; }
+  m[0] = d[0]!; m[n - 1] = d[n - 2]!;
   for (let i = 1; i < n - 1; i++) {
-    if (d[i - 1] * d[i] <= 0) m[i] = 0;
-    else { const w1 = 2 * h[i] + h[i - 1], w2 = h[i] + 2 * h[i - 1]; m[i] = (w1 + w2) / (w1 / d[i - 1] + w2 / d[i]); }
+    if (d[i - 1]! * d[i]! <= 0) m[i] = 0;
+    else { const w1 = 2 * h[i]! + h[i - 1]!, w2 = h[i]! + 2 * h[i - 1]!; m[i] = (w1 + w2) / (w1 / d[i - 1]! + w2 / d[i]!); }
   }
   return m;
 }
 export function makeSpline(pts: { x: number; y: number }[]) {
   const s = [...pts].sort((a, b) => a.x - b.x);
   const xs = s.map((p) => p.x), ys = s.map((p) => p.y), m = pchipSlopes(xs, ys), n = xs.length;
-  return (x: number) => {
-    if (x <= xs[0]) return ys[0];
-    if (x >= xs[n - 1]) return ys[n - 1];
-    let i = 0; while (x > xs[i + 1]) i++;
-    const hh = xs[i + 1] - xs[i], t = (x - xs[i]) / hh, t2 = t * t, t3 = t2 * t;
-    return (2 * t3 - 3 * t2 + 1) * ys[i] + (t3 - 2 * t2 + t) * hh * m[i] + (-2 * t3 + 3 * t2) * ys[i + 1] + (t3 - t2) * hh * m[i + 1];
+  return (x: number): number => {
+    if (x <= xs[0]!) return ys[0]!;
+    if (x >= xs[n - 1]!) return ys[n - 1]!;
+    let i = 0; while (x > xs[i + 1]!) i++;
+    const hh = xs[i + 1]! - xs[i]!, t = (x - xs[i]!) / hh, t2 = t * t, t3 = t2 * t;
+    return (2 * t3 - 3 * t2 + 1) * ys[i]! + (t3 - 2 * t2 + t) * hh * m[i]! + (-2 * t3 + 3 * t2) * ys[i + 1]! + (t3 - t2) * hh * m[i + 1]!;
   };
 }
 export const normH = (h: number) => ((h % 360) + 360) % 360;
@@ -489,7 +503,7 @@ export const FRAC_DARK = 0.4; // extreme-dark anchor (L0.20, below the floor). T
 // the shared dark cusp-fraction, so every family's darks stay rich. This anchor only extrapolates below 950.
 export const CHROMA_HEADROOM = 1.0; // multiplier on the comfort ceiling (1 = exact pin envelope)
 function buildBrandChromaProfile() {
-  const allPins = Object.values(PINS).flat() as [string, string, number?][];
+  const allPins = Object.values(PINS).flat();
   // 1. cusp-fraction curve: pin chroma as a fraction of its own cusp (drop near-white pins — cusp too small).
   // Also drop deliberately-muted dark accents (Bark Brown: f≈0.45 at L0.30): authored low on purpose, it
   // would clash with Forest's rich dark pins (Darkest Forest rides ~0.94) and suppress the system's dark richness.
@@ -528,13 +542,13 @@ export type PchipOverrides = { sat?: number; chromaMul?: number; headroom?: numb
 // (the Lime mock), so it shouldn't shape the semantics. ----
 const HOUSE_ANCHORS = ['primary', 'warm'];
 const STEERED = new Set(['maple', 'river', 'amber']);
-const P3_TO_SRGBLIN = [[1.2249401, -0.2249404, 0], [-0.0420569, 1.0420571, 0], [-0.0196376, -0.0786361, 1.0982735]];
+const P3_TO_SRGBLIN: [Vec3, Vec3, Vec3] = [[1.2249401, -0.2249404, 0], [-0.0420569, 1.0420571, 0], [-0.0196376, -0.0786361, 1.0982735]];
 // decode a built swatch string (hex or color(display-p3 …)) back to OKLCH.
 export function decodeOklch(s: string) {
   if (s[0] === '#') return hexToOklch(s);
   const m = s.match(/display-p3\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)/);
   if (!m) return { L: 0, C: 0, H: 0 };
-  const lin = [srgbToLin(+m[1]), srgbToLin(+m[2]), srgbToLin(+m[3])];
+  const lin: Vec3 = [srgbToLin(+m[1]!), srgbToLin(+m[2]!), srgbToLin(+m[3]!)];
   const r = P3_TO_SRGBLIN[0][0] * lin[0] + P3_TO_SRGBLIN[0][1] * lin[1] + P3_TO_SRGBLIN[0][2] * lin[2];
   const g = P3_TO_SRGBLIN[1][0] * lin[0] + P3_TO_SRGBLIN[1][1] * lin[1] + P3_TO_SRGBLIN[1][2] * lin[2];
   const b = P3_TO_SRGBLIN[2][0] * lin[0] + P3_TO_SRGBLIN[2][1] * lin[1] + P3_TO_SRGBLIN[2][2] * lin[2];
@@ -544,10 +558,11 @@ export function decodeOklch(s: string) {
 const _houseCache: Record<string, Record<number, number>> = {};
 // average chroma per level across the pinned brand anchors (Primary + Warm) — built canonically (NOT steered → no recursion), cached per gamut.
 export function houseChroma(gamut: 'srgb' | 'p3' = 'srgb'): Record<number, number> {
-  if (_houseCache[gamut]) return _houseCache[gamut];
+  const cached = _houseCache[gamut];
+  if (cached) return cached;
   const ramps = HOUSE_ANCHORS.map((f) => buildPCHIP(f, gamut));
   const h: Record<number, number> = {};
-  for (const s of BRAND_SHADES) { const cs = ramps.map((r) => decodeOklch(r[s]).C); h[s] = cs.reduce((a, b) => a + b, 0) / cs.length; }
+  for (const s of BRAND_SHADES) { const cs = ramps.map((r) => decodeOklch(r[s]!).C); h[s] = cs.reduce((a, b) => a + b, 0) / cs.length; }
   _houseCache[gamut] = h;
   return h;
 }
@@ -555,7 +570,7 @@ export function houseChroma(gamut: 'srgb' | 'p3' = 'srgb'): Record<number, numbe
 export function buildPCHIP(fam: string, gamut: 'srgb' | 'p3' = 'srgb', ov?: PchipOverrides) {
   const maxC = gamut === 'p3' ? maxChromaP3 : maxChromaAt;
   const toStr = gamut === 'p3' ? oklchToP3 : oklchToHex;
-  const base = hexToOklch(ov?.hue ?? HUE[fam]);
+  const base = hexToOklch(ov?.hue ?? HUE[fam]!); // an unknown family already threw here
   const H0 = normH(base.H);
   const ladder = ov?.ladder ?? ladderFor(fam);
   const sat = ov?.sat ?? SAT[fam] ?? 0.9;
@@ -572,12 +587,12 @@ export function buildPCHIP(fam: string, gamut: 'srgb' | 'p3' = 'srgb', ov?: Pchi
   if (!anchors.some((a) => a.L < 0.34)) { const Ld = 0.24, hd = H0 + tors.d; anchors.push({ L: Ld, C: Math.min(okhslChroma(Ld, hd, sat), maxC(Ld, hd)), H: hd, hex: '' }); }
   anchors.sort((a, b) => a.L - b.L);
   // unwrap hue to dodge 0/360 wrap in the spline
-  for (let i = 1; i < anchors.length; i++) { while (anchors[i].H - anchors[i - 1].H > 180) anchors[i].H -= 360; while (anchors[i].H - anchors[i - 1].H < -180) anchors[i].H += 360; }
+  for (let i = 1; i < anchors.length; i++) { const a = anchors[i]!, prev = anchors[i - 1]!; while (a.H - prev.H > 180) a.H -= 360; while (a.H - prev.H < -180) a.H += 360; }
   const hS = makeSpline(anchors.map((a) => ({ x: a.L, y: a.H })));
   // pin owns its level's L: override the ladder slot lightness with the pin's true L
   const Lad: Record<number, number> = { ...ladder };
-  const pinHex: Record<number, string> = {};
-  for (const [, hex, lvl] of list) { const o = hexToOklch(hex); const level = lvl ?? nearestOn(hex, ladder); Lad[level] = o.L; pinHex[level] = hex.toLowerCase(); }
+  const pinned: { level: number; hex: string }[] = [];
+  for (const [, hex, lvl] of list) { const po = hexToOklch(hex); const level = lvl ?? nearestOn(hex, ladder); Lad[level] = po.L; pinned.push({ level, hex: hex.toLowerCase() }); }
   const o: Record<number, string> = {};
   const tune = ov?.tune ?? TUNE[fam] ?? {};
   const cMul = ov?.chromaMul ?? 1; // global chroma dial — scales the derived curve (then gamut-clamped)
@@ -587,16 +602,16 @@ export function buildPCHIP(fam: string, gamut: 'srgb' | 'p3' = 'srgb', ov?: Pchi
   const house = steered ? houseChroma(gamut) : null;
   for (const s of BRAND_SHADES) {
     const tu = tune[s];
-    const L = s === 0 ? 0.985 : (tu?.L ?? Lad[s]);
+    const L = s === 0 ? 0.985 : (tu?.L ?? Lad[s]!);
     const hh = tu?.H != null ? tu.H : hS(L);
     // chroma: steered families take the house curve; brand families ride the cusp-fraction + comfort ceiling. Clamp to gamut.
-    const target = house ? house[s] : brandChroma(L, hh, gamut, headroom);
+    const target = house ? house[s]! : brandChroma(L, hh, gamut, headroom);
     let C = Math.min(target * cMul, maxC(L, hh));
     if (tu?.C != null) C = Math.min(tu.C, maxC(L, hh));
     o[s] = toStr(L, C, hh);
   }
   // guarantee exact pin (sRGB brand hex; in p3 mode emit its display-p3 form — same in-gamut colour)
-  for (const [lvl, hex] of Object.entries(pinHex)) { const po = hexToOklch(hex); o[+lvl] = gamut === 'p3' ? oklchToP3(po.L, po.C, po.H) : hex; }
+  for (const { level, hex } of pinned) { const po = hexToOklch(hex); o[level] = gamut === 'p3' ? oklchToP3(po.L, po.C, po.H) : hex; }
   return o;
 }
 

package/packages/ui/src/card/FInsetCard.vue

@@ -0,0 +1,237 @@
+<script setup lang="ts">
+// A card whose body is an INSET BOX: the box carries the content, and the card's own ground shows
+// as ONE strip — a header above it or a footer below, never both. For dashboard tiles.
+//
+//   <FInsetCard>              …a chart…   <template #footer>…</template>   </FInsetCard>
+//   <FInsetCard :gap="4">     …a chart…   <template #header>…</template>   </FInsetCard>
+//   <FInsetCard bare>         <template #default="{ boxUi }"> <FKpi :ui="boxUi" … />
+//
+// ★ WHY A WRAPPER, NOT A CARD VARIANT. Card variants are a FILL axis (soft/outline/subtle/solid +
+// the tints). "Inset box" is a composition, and making it a variant would put its blast radius on
+// every card in the system. Same reasoning as FlushCard, which is the other end of this axis: it
+// zeroes the body padding so a table runs to the card's edge; this one shrinks it to a visible gap.
+//
+// ★ THE GAP IS ONE VALUE DOING THREE JOBS. Setting --forest-card-pad drives (a) the body padding,
+// so the box is inset by it, (b) the concentric radius, because forest.css derives a nested card's
+// corner as `outer − pad`, and (c) FKpi's bleed margin, which pulls by the same var. Set it once
+// here and all three stay in step; set the padding with a class instead and they silently diverge.
+//
+// ★ THE BODY DROPS ITS PADDING ON THE SIDE THE STRIP IS ON. The box is inset on three sides; on the
+// fourth it meets the strip directly, and the strip owns all the space there. Two consequences, both
+// load-bearing: the box's edge lands flush against the strip (as it does in the reference), and the
+// strip's `pt` and `pb` can then be EQUAL and actually read equal. Leave the body padding on and it
+// stacks — the label sits `gap + pt` from the box but only `pb` from the card edge, which is the
+// lopsided look this pattern kept producing.
+//
+// ★ THE STRIP RESTATES ITS PADDING UNDER THE FRAGMENT'S OWN VARIANT. Forest's `flatGap` carries
+// `footer: '[&:not(:first-child)]:pt-0'` / `header: '[&:not(:last-child)]:pb-0'` to collapse a
+// doubled gap on a normal card. Here the body already zeroed that side, so the collapse would eat
+// the strip's only top padding. A bare `py-*` cannot answer it — the `:not()` selector out-specifies
+// a plain class — so the value is restated under the same variant.
+//
+// ★ WHOLE CLASS STRINGS, NEVER CONCATENATED. Tailwind scans source text, so `p-${gap}` and
+// `pt-[${n}px]` generate nothing at all — they fail silently, at runtime, with no error. Every
+// combination is spelled out below. This is why `gap` is an enum and not a number.
+import { computed, useSlots, watchEffect } from 'vue';
+
+type Gap = 4 | 8 | 12;
+
+// ★ ONE SOURCE OF TRUTH FOR THE GAP. The var is not a stylistic choice — two rules OUTSIDE this
+// component read it and no Tailwind class can reach either: forest.css derives the nested card's
+// concentric radius as `calc(--forest-card-radius - --forest-card-pad)`, and kpi.theme.ts pulls the
+// bleed by `-mx-[var(--forest-card-pad)]`. Measured: with the var set, box radii are 20/16/12 for
+// gaps 4/8/12; without it they all stay at 8.
+// So the padding CLASS reads the same var rather than restating the number — otherwise the value
+// lives in two places and a future edit can move one and not the other. That also makes the body
+// classes gap-independent: only `pad` varies.
+const PAD: Record<Gap, string> = { 4: '0.25rem', 8: '0.5rem', 12: '0.75rem' };
+
+// ★ THE BOX NEEDS THE VAR ON ITSELF, NOT JUST INHERITED. The bold contexts set
+// `[--forest-card-pad:1.25rem]` on EVERY card root (mobile-theme.ts / marketing-theme.ts), and the
+// box is a card — so the context's value lands on the box's own element and beats the frame's,
+// which only reaches it by inheritance. The concentric rule then runs on the box with the CONTEXT's
+// padding while the body was inset by OURS: 8px of inset with a corner struck for 20px.
+// Restating the gap on the box makes both halves read the same number. Literal strings per gap
+// because Tailwind scans source text and cannot generate `[--forest-card-pad:${x}]`.
+const PAD_CLASS: Record<Gap, string> = {
+  4: '[--forest-card-pad:0.25rem]',
+  8: '[--forest-card-pad:0.5rem]',
+  12: '[--forest-card-pad:0.75rem]',
+};
+
+// The body drops its padding on whichever side the strip is on — see the note above. Both
+// breakpoints every time: the card fragment re-pins `sm:p-*`, so a bare `pb-0` still pads at ≥640px.
+const BODY = {
+  none: 'p-[var(--forest-card-pad)] sm:p-[var(--forest-card-pad)]',
+  header: 'p-[var(--forest-card-pad)] pt-0 sm:p-[var(--forest-card-pad)] sm:pt-0',
+  footer: 'p-[var(--forest-card-pad)] pb-0 sm:p-[var(--forest-card-pad)] sm:pb-0',
+} as const;
+
+// Gap-independent, because the body no longer contributes on the strip's side: pt === pb.
+// The 8px here deliberately equals the DEFAULT gap: the space around the box and the space around
+// the strip's own label are then one number, so the frame reads as a single rhythm rather than two
+// unrelated ones. Change the default gap and this should move with it.
+// ★ THE STRIP OWNS ITS HEIGHT, THE CONTENT DOES NOT. Without a floor the band is as tall as whatever
+// sits in it, so a footer holding a UButton (min-h-8, its touch target — see themes/button.ts, where
+// `min-h` is the sole height driver) came out 48px against a header of text at ~40px, and a card
+// with one of each looked lopsided. min-h-10 is that button plus the strip's own 8+8, so the tallest
+// realistic content still fits and a plain text row is centred in the same band.
+//
+// `grid items-center` rather than `flex items-center`: a lone grid child spans the column, so a row
+// using `ms-auto` to push its meta right still works. Under flex it would shrink to content and the
+// meta would collapse leftward.
+const STRIP = {
+  header: 'grid min-h-10 items-center px-4 pt-2 sm:px-4 [&:not(:last-child)]:pb-2',
+  footer: 'grid min-h-10 items-center px-4 pb-2 sm:px-4 [&:not(:first-child)]:pt-2',
+} as const;
+
+const props = withDefaults(
+  defineProps<{
+    /** The inset, in px. An enum because the classes must exist in source — see the note above. */
+    gap?: Gap;
+    /** The card's hairline. Uses the relative ring, so it holds at any surface level. */
+    outlined?: boolean;
+    /**
+     * The child already draws its own surface (an FKpi does), so this card must not draw a second
+     * one. Named for the exception rather than the rule so the common case stays free and the
+     * exception is a bare attribute — `<FInsetCard bare>` — since Vue's shorthand can only ever
+     * express `true`, which would make the opposite spelling cost `:box="false"` at every KPI.
+     */
+    bare?: boolean;
+
+    /**
+     * The strip's content, for the shape nearly every card wants: an icon, a title, something
+     * right-aligned above; a single action below. Given as props so a call site does not hand-roll
+     * the same flex row each time — and so the voice (overline/toned title, caption meta, muted
+     * action) is decided once here rather than re-chosen per page.
+     *
+     * The `#header` / `#footer` slots still win when a card needs a shape these cannot express.
+     */
+    icon?: string;
+    title?: string;
+    meta?: string;
+    /** Footer action label. `to` makes it a link; without one it is a button. */
+    action?: string;
+    to?: string;
+
+  }>(),
+  { gap: 8, outlined: true, bare: false },
+);
+
+const slots = useSlots();
+
+// A strip is present when its slot OR its props are supplied — the body's padding and the
+// one-strip rule both key off this, so neither can be fooled by the prop form.
+const hasHeader = computed(() => !!(slots.header || props.title));
+const hasFooter = computed(() => !!(slots.footer || props.action));
+
+// One strip is the whole idea: the box plus the ground it sits on. With both, the box becomes the
+// filling in a sandwich, neither side can drop its padding, and the frame stops reading as a frame.
+if (import.meta.env.DEV) {
+  watchEffect(() => {
+    if (hasHeader.value && hasFooter.value)
+      console.warn('[FInsetCard] `header` and `footer` together — this pattern takes one strip, not both.');
+  });
+}
+
+
+
+// Set as a var rather than a class so the radius and FKpi's bleed follow it.
+const style = computed(() => ({ '--forest-card-pad': PAD[props.gap] }));
+
+const ui = computed(() => ({
+  body: hasFooter.value ? BODY.footer : hasHeader.value ? BODY.header : BODY.none,
+  header: STRIP.header,
+  footer: STRIP.footer,
+}));
+
+// ★ THE FRAME IS ALWAYS `soft`, and the variant is not exposed. Probed 2026-09-10 with the prop
+// restored and the divider suppressed, measuring frame vs box in both modes:
+//
+//   soft     frame l1        box page   → box visible
+//   subtle   frame l1        box page   → box visible
+//   outline  frame PAGE      box page   → BOX INVISIBLE, both modes
+//   solid    frame inverted  box page   → visible, but a light box in a black card
+//
+// `outline` fills the frame with the page colour, and the box is pinned to the page colour too, so
+// the inset box vanishes into its own frame — the one thing this component exists to draw. That is
+// the real reason, and it is a property of the fill being pinned, not of the divider: `divide-y-0`
+// suppressed the hairline in one class, so the divider was never the objection it looked like.
+//
+// `soft` + a ring, rather than `subtle`: subtle also restores divide-y, and the gap is what
+// separates the strip here — a hairline in it would say the same thing twice.
+// ★ `h-fit` IS LOAD-BEARING, not a layout preference. A grid or flex row stretches its children by
+// default, and a stretched card grows past its content — the extra height lands BELOW the box, so
+// the even inset turns into a lopsided gap at the bottom and the frame stops reading as a frame.
+// The card must hug its content vertically.
+// ⚠ NOT `self-start`, which was the first cut: `align-self` acts on the CROSS axis, so in a flex
+// COLUMN it stops the card filling the width instead of capping its height — the card shrank to its
+// content in every column layout. `h-fit` caps the height and leaves width alone, which is the axis
+// actually at issue.
+const rootClass = computed(() =>
+  ['h-fit', props.outlined ? 'ring ring-[var(--forest-card-ring)]' : ''].filter(Boolean).join(' '),
+);
+
+// ★ THE BOX IS ALWAYS RAISED — there is no ramp option, on purpose. Letting the nesting ladder fill
+// the box steps it one level AWAY from the page, which in light means DARKER than the card it sits
+// in. That reads as a recess, not as a panel, and it is not a look this pattern should be able to
+// produce. --forest-card-inset (forest.css) is the raised surface: always lighter than the card, in
+// both modes. It replaced a bare `bg-default`, which is the PAGE colour and so went darker than the
+// card in dark — the box read as a hole punched in the frame.
+//
+// The box takes no padding of its own: UCard already pads its BODY slot, and adding p-* to the root
+// stacks on top of it for double the intended space.
+const boxUi = computed(() => ({ root: `bg-[var(--forest-card-inset)] ${PAD_CLASS[props.gap]}` }));
+
+// ★ FOR `bare`, WHERE THE CHILD IS ITS OWN SURFACE (an FKpi). Exposed as a slot prop so the
+// call site passes it straight to the child's `ui` without needing to know any of this:
+//   · the child pads its ROOT (FKpi's root IS the padded grid), unlike UCard which pads its body
+//   · pb is left OFF so FKpi's `visual-fit="bleed"` keeps its own `pb-0` and the graphic reaches the
+//     bottom edge — a blanket `p-4` here silently re-adds it
+//   · the bleed margin is restated to match the reading padding actually in force. FKpi pulls by
+//     `-mx-[var(--forest-card-pad)]`, which is the GAP — not the 16px this box pads by — so without
+//     this the graphic stops short on both sides.
+// A workaround for FKpi's coupling to --forest-card-pad; the real fix belongs in kpi.theme.ts, at
+// which point the `visual` line here can go.
+const selfBoxUi = computed(() => ({
+  root: `bg-[var(--forest-card-inset)] px-4 pt-4 ${PAD_CLASS[props.gap]}`,
+  visual: '-mx-4',
+}));
+</script>
+
+<template>
+  <UCard variant="soft" :class="rootClass" :style="style" :ui="ui">
+    <template v-if="hasHeader" #header>
+      <!-- The slot's FALLBACK is the prop form: pass `#header` and it replaces this wholesale. -->
+      <slot name="header">
+        <div class="flex items-center gap-2">
+          <UIcon v-if="icon" :name="icon" class="size-4 shrink-0 text-muted" />
+          <span class="type-overline truncate text-toned">{{ title }}</span>
+          <span v-if="meta" class="ms-auto shrink-0 type-caption text-muted">{{ meta }}</span>
+        </div>
+      </slot>
+    </template>
+
+    <UCard v-if="!bare" :ui="boxUi">
+      <slot />
+    </UCard>
+    <slot v-else :box-ui="selfBoxUi" />
+
+    <template v-if="hasFooter" #footer>
+      <!-- `xs` on purpose: the strip's floor is 40px, and a `md` button's 32px touch target plus the
+           strip's own 8+8 would push it to 48 and leave the header shorter than the footer. -->
+      <slot name="footer">
+        <UButton
+          :to="to"
+          size="xs"
+          variant="link"
+          color="neutral"
+          trailing-icon="i-lucide-arrow-right"
+          class="w-full justify-between px-0 text-muted"
+        >
+          {{ action }}
+        </UButton>
+      </slot>
+    </template>
+  </UCard>
+</template>

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

@@ -0,0 +1,3 @@
+// Forest card compositions. UCard itself is Nuxt UI's, themed in ../themes/card.ts — this entry
+// carries only the compositions built ON it that a call site would otherwise hand-roll.
+export { default as FInsetCard } from './FInsetCard.vue';

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

@@ -3,8 +3,9 @@
 // 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
+// doesn't pay for all of them up front), the load fade, and teardown. Cooperative gestures are
+// available (`cooperative`) but OFF unless a surface asks: a map in a document should not swallow
+// the scroll, and a map that IS the surface should not need two fingers to move. 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
@@ -75,7 +76,16 @@ const props = withDefaults(
      *  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 gestures. ONE flag, TWO behaviours — Mapbox does not separate them: scroll-zoom
+     * then needs ⌘/ctrl held, AND a touch pan needs TWO FINGERS (pitch, three). It is the second
+     * half that decides the default.
+     *
+     * OFF by default, which is Mapbox's own default too. A map is usually the subject of the
+     * surface it is on — an ops canvas, a rider finding a vehicle — and there one finger should
+     * move it. Turn it ON for a map embedded in a document, where a map that swallows the scroll
+     * traps the reader on the way past.
+     */
     cooperative?: boolean;
     /** create the WebGL context only when the frame nears the viewport */
     lazy?: boolean;
@@ -102,7 +112,7 @@ const props = withDefaults(
     lightPreset: 'auto',
     height: 'h-105',
     attribution: true,
-    cooperative: true,
+    cooperative: false,
     lazy: true,
     frame: false,
   },

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

@@ -54,7 +54,12 @@ const props = withDefaults(
   // navigation and the weight split between two edges. It is what a console with a left rail does
   // everywhere (Linear, Figma, Retool). Pass `side="start"` where the panel IS the navigation for its
   // view, which in practice means a settings sub-nav.
-  { behaviour: 'push', side: 'end', size: 'md' },
+  // ★ `close: undefined` is load-bearing, not noise. A type-declared `close?: boolean` compiles to
+  // `{ type: Boolean }`, and Vue casts an ABSENT boolean prop to `false` unless the options carry a
+  // `default` key — so without this `props.close ?? overlay` never sees `undefined`, and an overlay
+  // panel drew no close at all unless a consumer asked for one. Declaring the default keeps the three
+  // states the prop is written for: unset (follow the behaviour), true, false.
+  { behaviour: 'push', side: 'end', size: 'md', close: undefined },
 );
 
 const open = defineModel<boolean>('open', { default: true });
@@ -214,6 +219,20 @@ const sidebarUi = computed(() => ({
   // panel title and a card title share a baseline instead of nearly sharing one.
   header: 'min-h-0 p-4 pb-0',
   inner: overlay.value ? 'forest-canvas-chrome divide-y-0' : '',
+  // ★ THE PANEL OWNS DISMISS — the button it renders into `#actions`, wired to its own `open`. Stock adds a
+  // SECOND one under 1024px and it is inert: `canClose` is `close && collapsible !== 'none' ||
+  // isMobile`, and that `|| isMobile` survives this component's `collapsible="none"`, while the click
+  // writes USidebar's own `open` model — which this never binds and which changes nothing in the
+  // `collapsible="none"` branch (no `data-state`, no mobile menu). So it is a dead control, and on a
+  // phone it sat next to a live one.
+  //
+  // ★ Hidden through the theme rather than through `<template #close />`, which LOOKS like the tighter
+  // fix and does not work: Vue falls back to a slot's default content when the passed slot renders no
+  // valid vnode, so an empty template hands back exactly the button it was meant to suppress (measured
+  // — stock's close was still in the DOM). And not `:open` either: USidebar's
+  // `watch(isMobile, …, { immediate: true })` sets that model to `false` on crossing 1024px, so a bound
+  // panel would shut itself on a phone.
+  close: 'hidden',
 }));
 </script>
 

package/styles.cdn.gen.css

@@ -1297,6 +1297,20 @@
   --forest-card-l2: color-mix(in oklab, var(--ui-bg), var(--ui-text-highlighted) 8%);
   --forest-card-l3: color-mix(in oklab, var(--ui-bg), var(--ui-text-highlighted) 13%);
 }
+/* ── Inset surface — a RAISED panel sitting on a card, the inverse of the ramp above ──────────────
+   The ramp steps AWAY from the page (light darker, dark lighter), which reads as a recess. A panel
+   inset into a card's own ground is the opposite gesture: it should read as lifted, so it steps
+   TOWARD white in both modes — i.e. always lighter than the card it sits in.
+   Light lands back on the page plane (a white panel on a grey card, the dashboard look); dark cannot
+   do that, because the page is the darkest thing there, so it borrows the ramp's own next level.
+   Measured against a card at L1 (.967 light / .229 dark): this is .994 / .268 — lighter in both.
+   ⚠ Declared on EVERY mode-boundary selector for the same reason the levels above are: the value
+   derives from --ui-bg, a custom property resolves ONCE where it is declared, and on :root alone a
+   nested force-light or force-dark island would inherit the outer mode's already-resolved colour.
+   ⚠ NOT --ui-bg-elevated or --ui-bg-muted, which sound right and are not: both are DARKER than the
+   Forest card surface in dark (.156 against the card's .229), so a panel on them reads as a hole. */
+:root, .light { --forest-card-inset: var(--ui-bg); }
+.dark { --forest-card-inset: var(--forest-card-l2); }
 /* Map — WHICH PALETTE OWNS WHICH REGION (José, 2026-07-26). Two rules, and they do not overlap:
      the DISC and the BADGE take the VIVID set (plus neutrals). They are categorical: they say WHICH
        kind of thing this is, and vivid separates further than the CVD-gated set does at marker size.