@exxatdesignux/ui 0.2.16 → 0.2.18

package/template/components/ui/dot-pattern.tsx

@@ -37,8 +37,32 @@ type Cloud = {
   delay: number
 }
 
-function rand(min: number, max: number) {
-  return min + Math.random() * (max - min)
+/**
+ * Tiny deterministic PRNG (mulberry32). We use a seeded RNG instead of
+ * `Math.random()` so the SVG attributes emitted on the server match the
+ * client's first paint — otherwise React reports a hydration mismatch and
+ * has to re-paint every drifting `<motion.circle>` on mount, which is both
+ * a perf cost and a visible jump.
+ */
+function mulberry32(seed: number): () => number {
+  let s = seed >>> 0
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0
+    let t = s
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function hashString(str: string): number {
+  // Cheap FNV-1a-style hash. Stable across SSR + CSR for the same input.
+  let h = 2166136261
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
 }
 
 export function DotPattern({
@@ -59,33 +83,33 @@ export function DotPattern({
   const maskId = `${id}-mask`
   const gradId = `${id}-grad`
 
-  const clouds = React.useMemo<Cloud[]>(
-    () =>
-      Array.from({ length: glowCount }).map((_, i) => {
-        // Drift diagonally: bottom-right → top-left. Start/end partly off-canvas
-        // so the cloud enters and exits softly without a visible edge.
-        const startX = rand(85, 120)
-        const endX = rand(-20, 15)
-        const midX = (startX + endX) / 2 + rand(-6, 6)
+  const clouds = React.useMemo<Cloud[]>(() => {
+    const rng = mulberry32(hashString(`${id}|${glowCount}`))
+    const rand = (min: number, max: number) => min + rng() * (max - min)
+    return Array.from({ length: glowCount }).map((_, i) => {
+      // Drift diagonally: bottom-right → top-left. Start/end partly off-canvas
+      // so the cloud enters and exits softly without a visible edge.
+      const startX = rand(85, 120)
+      const endX = rand(-20, 15)
+      const midX = (startX + endX) / 2 + rand(-6, 6)
 
-        const startY = rand(85, 115)
-        const endY = rand(-15, 10)
-        const midY = (startY + endY) / 2 + rand(-4, 4)
+      const startY = rand(85, 115)
+      const endY = rand(-15, 10)
+      const midY = (startY + endY) / 2 + rand(-4, 4)
 
-        const duration = rand(8, 12)
-        // Offset clouds by half a cycle so one is arriving as the other leaves.
-        const delay = -(i / glowCount) * duration
+      const duration = rand(8, 12)
+      // Offset clouds by half a cycle so one is arriving as the other leaves.
+      const delay = -(i / glowCount) * duration
 
-        return {
-          key: i,
-          xs: [`${startX}%`, `${midX}%`, `${endX}%`],
-          ys: [`${startY}%`, `${midY}%`, `${endY}%`],
-          duration,
-          delay,
-        }
-      }),
-    [glowCount],
-  )
+      return {
+        key: i,
+        xs: [`${startX}%`, `${midX}%`, `${endX}%`],
+        ys: [`${startY}%`, `${midY}%`, `${endY}%`],
+        duration,
+        delay,
+      }
+    })
+  }, [glowCount, id])
 
   return (
     <svg

package/template/components/ui/leo-icon.tsx

@@ -618,14 +618,34 @@ function InteractiveIcon({ sz, reduced }: { sz: SZ; reduced: boolean }) {
   const onDown = React.useCallback(() => setPressed(true), [])
   const onUp = React.useCallback(() => setPressed(false), [])
 
+  // Track click-effect timers so unmounting (Ask Leo sidebar close) doesn't
+  // leave timers running that then call setState on an unmounted component.
+  const clickTimersRef = React.useRef<Set<ReturnType<typeof setTimeout>>>(new Set())
+  React.useEffect(() => {
+    const set = clickTimersRef.current
+    return () => {
+      for (const t of set) clearTimeout(t)
+      set.clear()
+    }
+  }, [])
+
+  const ringIdRef = React.useRef(0)
   const onClick = React.useCallback(() => {
     if (reduced) return
     setCast(true)
-    setTimeout(() => setCast(false), 720)
+    const tCast = setTimeout(() => {
+      clickTimersRef.current.delete(tCast)
+      setCast(false)
+    }, 720)
+    clickTimersRef.current.add(tCast)
 
-    const id = Date.now() + Math.random()
+    const id = ++ringIdRef.current
     setRings(prev => [...prev, id])
-    setTimeout(() => setRings(prev => prev.filter(r => r !== id)), 800)
+    const tRing = setTimeout(() => {
+      clickTimersRef.current.delete(tRing)
+      setRings(prev => prev.filter(r => r !== id))
+    }, 800)
+    clickTimersRef.current.add(tRing)
 
     spawnBurst(6)
   }, [reduced, spawnBurst])

package/template/contexts/product-context.tsx

@@ -10,29 +10,92 @@
 
 import * as React from "react"
 import { useAppStore, type Product } from "@/stores/app-store"
+import {
+  brandForProduct,
+  EXXAT_ASSESSMENT_BRAND,
+  EXXAT_ONE_BRAND,
+  EXXAT_PRISM_BRAND,
+} from "@/lib/product-brand"
+
+const DEFAULT_PRODUCT_ACCENT: Record<Product, string> = {
+  "exxat-one": EXXAT_ONE_BRAND.brandColor,
+  "exxat-prism": EXXAT_PRISM_BRAND.brandColor,
+  "exxat-assessment": EXXAT_ASSESSMENT_BRAND.brandColor,
+  "exxat-custom": "",
+}
+
+function accentOverrideActive(product: Product, override: string | undefined): boolean {
+  if (!override?.trim()) return false
+  const defaultAccent = DEFAULT_PRODUCT_ACCENT[product]?.trim()
+  if (!defaultAccent) return true
+  return override.trim().toLowerCase() !== defaultAccent.toLowerCase()
+}
 
 export type { Product }
 
 export function useProduct() {
-  const product    = useAppStore(s => s.product)
-  const setProduct = useAppStore(s => s.setProduct)
-  return { product, setProduct }
+  const product               = useAppStore(s => s.product)
+  const setProduct            = useAppStore(s => s.setProduct)
+  const customProductBrand    = useAppStore(s => s.customProductBrand)
+  const setCustomProductBrand = useAppStore(s => s.setCustomProductBrand)
+  const productBrandColors    = useAppStore(s => s.productBrandColors)
+  const setProductBrandColor  = useAppStore(s => s.setProductBrandColor)
+  const hiddenProductIds      = useAppStore(s => s.hiddenProductIds)
+  const hideProduct           = useAppStore(s => s.hideProduct)
+  const showProduct           = useAppStore(s => s.showProduct)
+  return {
+    product,
+    setProduct,
+    customProductBrand,
+    setCustomProductBrand,
+    productBrandColors,
+    setProductBrandColor,
+    hiddenProductIds,
+    hideProduct,
+    showProduct,
+  }
 }
 
 export function ProductProvider({ children }: { children: React.ReactNode }) {
   const product = useAppStore(s => s.product)
+  const customProductBrand = useAppStore(s => s.customProductBrand)
+  const productBrandColors = useAppStore(s => s.productBrandColors)
 
   // Rehydrate from localStorage once — keeps SSR render matching server output.
   React.useEffect(() => {
     void useAppStore.persist.rehydrate()
   }, [])
 
-  // Sync theme class to <html> whenever product changes.
+  // Sync theme class to <html> whenever product (or its accent override) changes.
   React.useEffect(() => {
     const html = document.documentElement
-    html.classList.remove("theme-one", "theme-prism")
-    html.classList.add(product === "exxat-one" ? "theme-one" : "theme-prism")
-  }, [product])
+    html.classList.remove("theme-one", "theme-prism", "theme-assessment", "theme-custom")
+    // Effective brand colour for the active product — picks up any
+    // per-product override the user set in Settings → Appearance. Drives
+    // `--custom-product-brand-color` so `theme-custom` chrome retints.
+    const effectiveBrandColor = brandForProduct(product, customProductBrand, productBrandColors).brandColor
+    html.style.setProperty("--custom-product-brand-color", effectiveBrandColor)
+    // If the user has set a brand-colour override for the active product,
+    // flip to `theme-custom` so the chrome retints from
+    // `--custom-product-brand-color`. The hardcoded `theme-one / theme-prism
+    // / theme-assessment` classes (with bespoke hue formulas in
+    // `globals.css`) are still used for the **default** look of each
+    // built-in.
+    const hasAccentOverride = accentOverrideActive(product, productBrandColors[product])
+    let themeClass: "theme-one" | "theme-prism" | "theme-assessment" | "theme-custom"
+    if (hasAccentOverride) {
+      themeClass = "theme-custom"
+    } else if (product === "exxat-one") {
+      themeClass = "theme-one"
+    } else if (product === "exxat-prism") {
+      themeClass = "theme-prism"
+    } else if (product === "exxat-assessment" || (product === "exxat-custom" && !customProductBrand)) {
+      themeClass = "theme-assessment"
+    } else {
+      themeClass = "theme-custom"
+    }
+    html.classList.add(themeClass)
+  }, [customProductBrand, product, productBrandColors])
 
   return <>{children}</>
 }

package/template/contexts/system-banner-context.tsx

@@ -43,6 +43,111 @@ export const DEFAULT_SYSTEM_BANNER_CONFIG: SystemBannerConfig = {
 
 const STORAGE_KEY = "exxat:system-banner-config"
 
+const ALLOWED_VARIANTS: ReadonlySet<SystemBannerVariant> = new Set([
+  "info",
+  "warning",
+  "error",
+  "success",
+  "promo",
+])
+
+const ALLOWED_EMPHASIS: ReadonlySet<SystemBannerEmphasis> = new Set([
+  "prominent",
+  "subtle",
+])
+
+/**
+ * Strip any `actionHref` whose URL scheme could execute script when the
+ * banner CTA is clicked (`javascript:`, `data:`, `vbscript:`, etc.).
+ *
+ * The banner UI renders `actionHref` as a plain `<a href>`, so a malicious
+ * value in `localStorage` — written by an extension, a victim of a
+ * same-origin bug elsewhere, or a future feature that accepts user input —
+ * would become a one-click XSS or open-redirect vector on every tab that
+ * receives the storage event. We accept only:
+ *
+ *   - Absolute http(s) URLs.
+ *   - Absolute mailto: / tel: URIs (banner CTAs sometimes deep-link these).
+ *   - Same-origin relative paths (`/foo`, `./bar`, `../baz`).
+ *   - The single legacy placeholder `"#"` shipped in the default config.
+ *
+ * Anything else collapses to `undefined`, which the banner treats as
+ * "no CTA link".
+ */
+function sanitizeActionHref(href: unknown): string | undefined {
+  if (typeof href !== "string") return undefined
+  const trimmed = href.trim()
+  if (!trimmed) return undefined
+  if (trimmed === "#") return trimmed
+
+  // Same-origin relative paths.
+  if (
+    trimmed.startsWith("/") ||
+    trimmed.startsWith("./") ||
+    trimmed.startsWith("../")
+  ) {
+    return trimmed
+  }
+
+  // Absolute URLs — only allow http(s) / mailto: / tel:.
+  try {
+    // Use a dummy base so `new URL` accepts both absolute and protocol-relative inputs.
+    const url = new URL(trimmed, "https://exxat.invalid")
+    if (
+      url.protocol === "http:" ||
+      url.protocol === "https:" ||
+      url.protocol === "mailto:" ||
+      url.protocol === "tel:"
+    ) {
+      return trimmed
+    }
+  } catch {
+    /* fallthrough to reject */
+  }
+
+  return undefined
+}
+
+/**
+ * Coerce an unknown JSON payload (from `localStorage` or a cross-tab
+ * `storage` event) into a `SystemBannerConfig`. Unknown fields are dropped,
+ * known fields are type-narrowed, and any string field is capped so a
+ * malformed/oversized payload cannot stall the renderer.
+ *
+ * Returns `null` when the payload cannot be coerced — callers fall back to
+ * the shipped default rather than render attacker-controlled content.
+ */
+function coerceConfig(raw: unknown): SystemBannerConfig | null {
+  if (!raw || typeof raw !== "object") return null
+  const r = raw as Record<string, unknown>
+  const str = (v: unknown, max = 280): string | undefined =>
+    typeof v === "string" ? v.slice(0, max) : undefined
+
+  const variant = ALLOWED_VARIANTS.has(r.variant as SystemBannerVariant)
+    ? (r.variant as SystemBannerVariant)
+    : DEFAULT_SYSTEM_BANNER_CONFIG.variant
+  const emphasis = ALLOWED_EMPHASIS.has(r.emphasis as SystemBannerEmphasis)
+    ? (r.emphasis as SystemBannerEmphasis)
+    : DEFAULT_SYSTEM_BANNER_CONFIG.emphasis
+
+  return {
+    enabled:
+      typeof r.enabled === "boolean"
+        ? r.enabled
+        : DEFAULT_SYSTEM_BANNER_CONFIG.enabled,
+    variant,
+    emphasis,
+    title: str(r.title, 120) ?? DEFAULT_SYSTEM_BANNER_CONFIG.title,
+    message: str(r.message, 280) ?? DEFAULT_SYSTEM_BANNER_CONFIG.message,
+    actionLabel: str(r.actionLabel, 60),
+    actionHref: sanitizeActionHref(r.actionHref),
+    dismissible:
+      typeof r.dismissible === "boolean"
+        ? r.dismissible
+        : DEFAULT_SYSTEM_BANNER_CONFIG.dismissible,
+  }
+}
+
 interface SystemBannerContextValue {
   config: SystemBannerConfig
   updateConfig: (patch: Partial<SystemBannerConfig>) => void
@@ -66,9 +171,8 @@ function readStored(): SystemBannerConfig {
   try {
     const raw = window.localStorage.getItem(STORAGE_KEY)
     if (!raw) return DEFAULT_SYSTEM_BANNER_CONFIG
-    const parsed = JSON.parse(raw) as Partial<SystemBannerConfig>
-    // Merge so newly-added fields in the default keep working for old payloads.
-    return { ...DEFAULT_SYSTEM_BANNER_CONFIG, ...parsed }
+    const coerced = coerceConfig(JSON.parse(raw))
+    return coerced ?? DEFAULT_SYSTEM_BANNER_CONFIG
   } catch {
     return DEFAULT_SYSTEM_BANNER_CONFIG
   }
@@ -95,11 +199,15 @@ export function SystemBannerProvider({ children }: { children: React.ReactNode }
   }, [config, hydrated])
 
   // Cross-tab sync — if you change the banner in one tab, others follow.
+  // The payload is treated as untrusted (an extension or future bug could
+  // write into the same key) so we route it through `coerceConfig` to drop
+  // unknown fields and `sanitizeActionHref` to refuse `javascript:` URLs.
   React.useEffect(() => {
     function onStorage(e: StorageEvent) {
       if (e.key !== STORAGE_KEY || !e.newValue) return
       try {
-        setConfig({ ...DEFAULT_SYSTEM_BANNER_CONFIG, ...JSON.parse(e.newValue) })
+        const coerced = coerceConfig(JSON.parse(e.newValue))
+        if (coerced) setConfig(coerced)
       } catch {
         /* ignore malformed payloads */
       }

package/template/docs/data-views-pattern.md

@@ -18,6 +18,8 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 | **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
 | **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
 | **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
+| **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Question bank clients |
+| **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Question bank |
 | **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
 | **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
 

package/template/docs/kpi-flat-band-pattern.md

@@ -0,0 +1,57 @@
+# KPI flat band (`KeyMetrics` `variant="flat"`)
+
+> **Component:** `components/key-metrics.tsx` — **`flatMetricsHairlineClass`**, **`flatBandStyle`**.  
+> **Tokens:** `app/globals.css` — `--key-metrics-flat-*`.  
+> **Cursor:** `.cursor/rules/exxat-kpi-flat-band.mdc` · `.cursor/skills/exxat-kpi-flat-band/SKILL.md`  
+> **Related:** `docs/kpi-strip-max-four-pattern.md`, `docs/kpi-trend-pattern.md`
+
+## Intent
+
+List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as a **metrics strip without a surface**: users see KPI copy and deltas on the **page canvas**, with a **brand-colored glow** under the band only. This is **not** a card, tinted panel, or `gap-px` grid fill.
+
+## MUST
+
+1. **No band surface** — The `<section>` background is **only** `var(--key-metrics-flat-band-radial)`. **Do not** stack `--key-metrics-flat-band-linear`, opaque gradients, or `box-shadow` fills that read as a grey/lavender box.
+2. **Transparent cells** — `metricsCellSurfaceClassName` is **`bg-transparent`** for `variant="flat"`. **Do not** use `bg-background`, `bg-card`, or `gap-px` + `bg-border` / `bg-foreground/*` on the grid (that paints tile surfaces).
+3. **Hairlines = borders only** — Use **`flatMetricsHairlineClass(itemCount, metricsHalfWidthLayout)`** in `key-metrics.tsx`:
+   - **2 tiles:** `border-r` on the first cell only.
+   - **4 tiles, wide strip (default):** `border-r` on cells 1–3 (verticals between all columns); **no** horizontal rule.
+   - **4 tiles, narrow `@container` (&lt; 30rem, 2×2 grid):** odd-column `border-r` + `border-b` on the top row only (via `@[max-width:29.99rem]` overrides).
+4. **Divider color (OKLCH)** — `--key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent)`; apply on children with `[&>*]:border-[color:var(--key-metrics-flat-divider)]`. Dividers follow **active product** hue (`--sidebar-border`), not neutral grey alone.
+5. **Glow (OKLCH)** — Radial stops use `color-mix(in oklch, var(--brand-color) …%, transparent)` so **Exxat One / Prism / Assessment / `theme-custom`** each tint correctly. **Do not** hardcode rose/indigo literals on theme blocks unless documenting a one-off.
+6. **List page usage** — Prefer **`showHeader={false}`**, **`metricsSingleRow`** when four KPIs share one row; pass **`insight`** only when the insight rail is product-required (same row uses `lg:grid-cols-[3fr_2fr]`).
+7. **Cap at four tiles** — See **`docs/kpi-strip-max-four-pattern.md`**.
+
+## MUST NOT
+
+- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. question-bank hub hero).
+- Use **`variant="card"`** on **`ListPageTemplate`** metrics when the design calls for a **flat strip** on the page background.
+- Duplicate KPI numbers in ad-hoc **`Card`** grids on the same hub.
+- Set **`variant="mutedSuffix"`** on product wordmarks to grey out the **suffix** in dark mode — suffix stays **Exxat pink** (`wordmarkColor`); see **`lib/product-brand.ts`**.
+
+## Tokens (`app/globals.css`)
+
+| Token | Role |
+|--------|------|
+| `--key-metrics-flat-band-radial` | Bottom brand glow (only layer on flat `<section>`) |
+| `--key-metrics-flat-band-shadow` | **`none`** for flat band (no faux surface lift) |
+| `--key-metrics-flat-cell-bg` | **`transparent`** |
+| `--key-metrics-flat-divider` | OKLCH hairline between cells |
+
+Dark mode (`.dark`): same rules — transparent cells, radial glow only, no linear fill to `--background`.
+
+## Reference implementations
+
+- `components/question-bank-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
+- `components/dashboard-tabs.tsx` — mix view flat band + insight
+- `components/placements-client.tsx`, `team-client.tsx`, `compliance-client.tsx` — list hub metrics slot
+
+## Insight rail (flat + side-by-side)
+
+When **`insight`** is shown beside KPIs, the insight **`Card`** may keep its own surface; the **KPI grid** stays transparent. **Do not** add `lg:border-l` on the insight column for flat band — the insight card ring is the separator (`key-metrics.tsx`).
+
+## See also
+
+- **`docs/kpi-strip-max-four-pattern.md`**
+- **`docs/kpi-trend-pattern.md`**
+- **`docs/shell-surface-elevation-pattern.md`** — sidebar / secondary panel / page stack

package/template/docs/kpi-strip-max-four-pattern.md

@@ -26,4 +26,5 @@ On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard
 ## See also
 
 - **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
+- **`docs/kpi-flat-band-pattern.md`** — **`variant="flat"`** presentation (orthogonal to tile count).
 - **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/template/docs/shell-surface-elevation-pattern.md

@@ -0,0 +1,52 @@
+# Shell surface elevation (sidebar · secondary panel · page)
+
+> **Tokens:** `app/globals.css` — `--sidebar`, `--secondary-panel-bg`, `--background`, `--brand-tint*`.  
+> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-[var(--secondary-panel-bg)]`.  
+> **Cursor:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc` · `.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md`
+
+## Stack (back → front)
+
+| Level | Surface | Token / class | Notes |
+|-------|---------|---------------|--------|
+| **0** | Primary icon rail + app chrome | `--sidebar` (= `--brand-tint` on light product themes) | Darkest brand wash in the shell |
+| **1** | Nested secondary panel (Library, etc.) | `--secondary-panel-bg` | **Lighter** than level 0; **same product hue** |
+| **2** | Main page / inset content | `--background` | Lightest (white canvas light; dark charcoal dark) |
+
+**MUST** derive secondary panel fill from **`--brand-tint` / `--brand-tint-light`**, not a fixed rose or neutral grey. When the user selects **Exxat One**, both levels use **indigo hue ~286**; **Prism** uses **rose ~342**; **`theme-custom`** follows `--custom-product-brand-color` via `ProductProvider`.
+
+## OKLCH formulas (light)
+
+```css
+--sidebar: var(--brand-tint);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%);
+```
+
+## OKLCH formulas (dark)
+
+```css
+--secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
+```
+
+Per-product **dark** theme blocks (`.theme-one.dark`, `.theme-prism.dark`, …) set **`--brand-tint-light`** where needed so mixes stay on-hue.
+
+## Implementation
+
+- **`NestedSecondaryPanelShell`** — `bg-[var(--secondary-panel-bg)]`, `ring-sidebar-border` (not generic `ring-border` alone).
+- **Do not** set secondary panel to `bg-sidebar` (same as level 0 — loses elevation).
+- **Do not** use `color-mix(… var(--sidebar) …)` without brand tokens if it drifts from active product theme.
+
+## Product theme classes
+
+- **`theme-one`** / **`theme-prism`** / **`theme-assessment`** — built-in OKLCH brand scales in `globals.css`.
+- **`theme-custom`** — when user picks an accent in Settings; driven by `--custom-product-brand-color`.
+- **`ProductProvider`** — applies `theme-one` vs `theme-prism` vs `theme-custom`; accent override only when it **differs** from the product default (see `accentOverrideActive` in `contexts/product-context.tsx`).
+
+## Logo vs chrome
+
+- **Chrome** (sidebar, secondary panel, KPI glow) follows **`--brand-tint` / `--brand-color`** per product.
+- **Logo art** (mark + suffix) stays **Exxat pink** via `wordmarkColor` / `markGradient` in `lib/product-brand.ts` — recolouring a product in Settings changes **theme accent**, not corporate logo pink.
+
+## See also
+
+- **`docs/kpi-flat-band-pattern.md`** — flat KPI strip uses brand glow only, no surface
+- **`apps/web/AGENTS.md` §4.6** — secondary panel wiring

package/template/eslint.config.mjs

@@ -13,6 +13,24 @@ const eslintConfig = defineConfig([
     "build/**",
     "next-env.d.ts",
   ]),
+  {
+    rules: {
+      // Allow intentionally-unused args / vars / destructured props /
+      // generics when prefixed with `_`. This is the standard escape hatch
+      // for "I'm satisfying a callback signature but don't need this slot"
+      // — common in cell renderers (`(value, _row) => …`), destructured
+      // tuples (`const [_, setX] = useState()`), and generic constraints.
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
 ]);
 
 export default eslintConfig;

package/template/hooks/use-sidebar-reflow-zoom.ts

@@ -1,6 +1,7 @@
 "use client"
 
 import * as React from "react"
+import { rafThrottle } from "@/lib/raf-throttle"
 
 /**
  * When true, the sidebar should **not** pin utilities + profile to the bottom — the whole
@@ -14,25 +15,34 @@ export function useSidebarReflowZoom(): boolean {
 
   React.useEffect(() => {
     const vv = window.visualViewport
+    // Cache the MediaQueryList — calling `matchMedia` on every compute() is
+    // measurable on pinch/zoom where visualViewport scroll fires per frame.
+    const mql = window.matchMedia("(max-height: 640px)")
 
     function compute() {
       const scale = vv?.scale ?? 1
-      const short = window.matchMedia("(max-height: 640px)").matches
+      const short = mql.matches
       const veryShort = window.innerHeight <= 420
-      setReflow(scale >= 1.99 || short || veryShort)
+      const next = scale >= 1.99 || short || veryShort
+      // Avoid unnecessary React re-renders when nothing changed.
+      setReflow(prev => (prev === next ? prev : next))
     }
 
     compute()
-    vv?.addEventListener("resize", compute)
-    vv?.addEventListener("scroll", compute)
-    window.addEventListener("resize", compute)
-    const mql = window.matchMedia("(max-height: 640px)")
-    mql.addEventListener("change", compute)
+    // rAF-coalesce: visualViewport.scroll can fire hundreds of times per second
+    // during pinch-zoom — without throttling we trigger setReflow + matchMedia
+    // per event. One sample per frame is enough for a layout breakpoint flag.
+    const scheduled = rafThrottle(compute)
+    vv?.addEventListener("resize", scheduled, { passive: true })
+    vv?.addEventListener("scroll", scheduled, { passive: true })
+    window.addEventListener("resize", scheduled, { passive: true })
+    mql.addEventListener("change", scheduled)
     return () => {
-      vv?.removeEventListener("resize", compute)
-      vv?.removeEventListener("scroll", compute)
-      window.removeEventListener("resize", compute)
-      mql.removeEventListener("change", compute)
+      scheduled.cancel()
+      vv?.removeEventListener("resize", scheduled)
+      vv?.removeEventListener("scroll", scheduled)
+      window.removeEventListener("resize", scheduled)
+      mql.removeEventListener("change", scheduled)
     }
   }, [])
 

package/template/lib/chunk-load-error.ts

@@ -0,0 +1,13 @@
+/** Detect stale Turbopack / webpack chunk failures after dev-server rebuilds. */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false
+  const err = error as { name?: string; message?: string }
+  const name = err.name ?? ""
+  const msg = err.message ?? ""
+  return (
+    name === "ChunkLoadError" ||
+    msg.includes("Failed to load chunk") ||
+    msg.includes("Loading chunk") ||
+    msg.includes("ChunkLoadError")
+  )
+}