basalt-ui 1.19.1 → 1.21.0

package/src/guard/types.ts

@@ -1,12 +1,12 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 20 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 25 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 20 theme-guard violation kinds. */
+/** The 25 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -28,6 +28,11 @@ export type GuardKind =
   | 'raw-form-control'
   | 'sub-16-input-font'
   | 'raw-font-family'
+  | 'theme-allow-unscoped'
+  | 'surface-shadow-override'
+  | 'css-raw-surface'
+  | 'inline-font-size'
+  | 'hidden-inline-style'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.
@@ -151,10 +156,30 @@ export type GuardConfig = {
    */
   readonly sub16InputFont: boolean
   /**
-   * Allow-comment policy: a line containing this substring is skipped entirely.
-   * Default 'theme-allow'. Pure-comment lines (// * /\*) are always skipped.
+   * Allow-comment policy. The token that opens an exception annotation inside a COMMENT, on the
+   * finding's own line or the line directly above it (matching the oxlint plugin's placement, and
+   * surviving an `oxfmt` reflow that moves the comment off the offending line). Default
+   * `'theme-allow'`.
+   *
+   * The accountable form is `theme-allow <rule-id>[, <rule-id>] — <reason>`: the rule ids scope the
+   * exception to those kinds only, and the reason says why. A `theme-allow` missing either half
+   * still suppresses (so an upgrade never breaks a build over it) but reports
+   * {@link GuardKind} `theme-allow-unscoped` on its own line.
    */
   readonly allowComment: string
+  /**
+   * Which kinds apply to this consumer. `'mantine'` (default) is the full framework guard.
+   *
+   * `'tokens-only'` is for a consumer that installs the TOKEN LAYER and nothing else — no
+   * `@mantine/core`, often no React (`basalt-ui tokens:css` + `basalt-ui/tokens`). Every kind whose
+   * remedy is a Mantine component or prop is disabled there, because "use `TextInput` from
+   * `@mantine/core`" is not advice, it is a dependency the consumer deliberately does not have.
+   * The color/typography kinds stay on — those are the tokens, which is the whole surface they DO
+   * consume. See `TOKENS_ONLY_DISABLED_KINDS` in `./index` for the exact set.
+   *
+   * Optional so a caller built before this field existed keeps compiling; absent means `'mantine'`.
+   */
+  readonly profile?: 'mantine' | 'tokens-only'
   /**
    * Per-rule, per-path exemptions — complements whole-file `exempt` (BasaltConfig, which skips
    * ALL rules for a file) and code-level `appliesTo` (hardcoded per-kind path scoping, e.g.

package/src/register.ts

@@ -156,3 +156,35 @@ export namespace StandardSchemaV1 {
     T['~standard']['types']
   >['output']
 }
+
+// ── Ambient app globals ───────────────────────────────────────────────────────────────────────────
+
+declare global {
+  /**
+   * The app's version string, injected as a build-time constant by basalt's own Vite preset —
+   * `basaltViteConfig` defines it from `BUILD_VERSION`, falling back to the app package.json
+   * `version` (see `../vite`, the `define` block).
+   *
+   * Declared HERE rather than beside the define because a consumer's `src/**` never loads
+   * `basalt-ui/vite`'s types (that subpath is imported from `vite.config.ts`, which most apps keep
+   * in a separate tsconfig project). This file is re-exported from the root barrel, so an app that
+   * imports from `'basalt-ui'` at all has it in scope with no `/// <reference>` and no
+   * `src/vite-env.d.ts` entry — which is the point: basalt shipped the define and no declaration,
+   * so every consumer hand-wrote this block, one of them needing an `oxlint-disable` in a file that
+   * existed only because basalt asked for it.
+   *
+   * A consumer importing ONLY a subpath (`basalt-ui/tokens`, `basalt-ui/charts`) does not load this
+   * file and does not get the global. That gap is the same set as the applicability gap: reaching
+   * for the root barrel is what `BasaltProvider` requires, and an app that never does is not on
+   * basalt's Vite preset either, so there is no `__APP_VERSION__` to declare.
+   *
+   * Precondition: only defined when your Vite config actually goes through `basaltViteConfig` (or
+   * you define it yourself). An app that hand-rolls its Vite config and reads this gets a
+   * ReferenceError at runtime — TypeScript is trusting the preset, not proving it.
+   */
+  // The dangle IS the API: this declares the build-time constant basalt's own Vite preset defines,
+  // so the name is not ours to change. The SHIPPED preset allows it (configs/oxlint.json); this
+  // repo's own root .oxlintrc.json does not, hence the local suppression.
+  // oxlint-disable-next-line no-underscore-dangle
+  const __APP_VERSION__: string
+}

package/src/router-tanstack/multi-search-param-store.ts

@@ -8,6 +8,7 @@
  * 2. `useStore` — React hook: `const [values, persist] = store.useStore()`.
  *    Call `persist(next)` alongside `navigate` so the selection survives navigation.
  * 3. `readStored` — plain function for non-React contexts (tests, guards).
+ * 4. `linkSearch` — the click-time `search:` thunk for a nav link, ready-made.
  *
  * Headless — no Mantine, no JSX. Same tier as `createSearchParamStore`.
  *
@@ -77,6 +78,16 @@ export type MultiSearchParamStore<T extends string, P extends string = string> =
   useStore: () => readonly [readonly T[], (next: readonly T[]) => void]
   /** Plain read — for use outside React (tests, guards, fallback reads). */
   readStored: () => readonly T[] | null
+  /**
+   * The click-time `search:` thunk for a nav link — `() => ({ [param]: readStored() ?? fallback })`.
+   * Pass it BY REFERENCE (`search: store.linkSearch`), never call it; see `createSearchParamStore`
+   * for why a module-scope literal silently defeats the store.
+   *
+   * No dev warning rides on this one, unlike the single-value store: an empty array in the URL is
+   * indistinguishable from an absent param here (`validateSearch` falls back to storage for both),
+   * so a link declaring `{ tags: [] }` restores correctly and there is no broken state to detect.
+   */
+  linkSearch: () => { [K in P]: readonly T[] }
 }
 
 // ── Implementation ─────────────────────────────────────────────────────────
@@ -104,6 +115,10 @@ export function createMultiSearchParamStore<const T extends string, const P exte
     return normalize(raw)
   }
 
+  const linkSearch = (): { [K in P]: readonly T[] } => {
+    return { [opts.param]: readStored() ?? fallback } as { [K in P]: readonly T[] }
+  }
+
   const validateSearch = (search: Record<string, unknown>): { [K in P]: readonly T[] } => {
     const fromUrl = normalize(search[opts.param])
     if (fromUrl.length > 0) {
@@ -118,5 +133,5 @@ export function createMultiSearchParamStore<const T extends string, const P exte
     initial: fallback,
   })
 
-  return { validateSearch, useStore, readStored }
+  return { validateSearch, useStore, readStored, linkSearch }
 }

package/src/router-tanstack/search-param-store.test.ts

@@ -0,0 +1,135 @@
+/**
+ * `createSearchParamStore`'s persistence seam — the half that was invisible.
+ *
+ * The reference consumer adopted the store in three features, hand-rolled the persistence in all
+ * three, and the reader had ZERO call sites: "remember my window" had never once worked, and
+ * nothing in the type, the runtime or the tests said so. The 5-step recipe in the JSDoc was
+ * present the whole time. So the fix is API-shaped (`linkSearch`) plus a dev warning that fires in
+ * exactly the broken state — and these tests are what keep both honest.
+ */
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
+import { createSearchParamStore } from './search-param-store'
+
+const VALUES = ['1d', '7d', '30d'] as const
+
+function makeStore(key: string) {
+  return createSearchParamStore({ key, param: 'range', values: VALUES, fallback: '30d' })
+}
+
+/** Writes the `createPersistedState` envelope directly — the shape `readStored` parses. */
+function persist(key: string, value: string, version = 1): void {
+  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: version, value }))
+}
+
+let warn: ReturnType<typeof spyOn<Console, 'warn'>>
+
+beforeEach(() => {
+  localStorage.clear()
+  warn = spyOn(console, 'warn').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  warn.mockRestore()
+})
+
+describe('linkSearch', () => {
+  it('is the click-time thunk — it reads storage at CALL time, not at creation', () => {
+    const store = makeStore('link-thunk')
+    expect(store.linkSearch()).toEqual({ range: '30d' })
+
+    persist('link-thunk', '7d')
+    // A value captured at module scope would still say 30d here. That is the bug it prevents.
+    expect(store.linkSearch()).toEqual({ range: '7d' })
+  })
+
+  it('falls back when nothing valid is stored', () => {
+    persist('link-fallback', 'not-a-range')
+    expect(makeStore('link-fallback').linkSearch()).toEqual({ range: '30d' })
+  })
+
+  it('returns the param under the store’s own param name', () => {
+    const store = createSearchParamStore({
+      key: 'link-param',
+      param: 'window',
+      values: VALUES,
+      fallback: '1d',
+    })
+    persist('link-param', '7d')
+    expect(store.linkSearch()).toEqual({ window: '7d' })
+  })
+})
+
+describe('the unwired-reader warning', () => {
+  it('fires when a link pins the fallback over a different stored value', () => {
+    const store = makeStore('warn-pinned')
+    persist('warn-pinned', '7d')
+
+    expect(store.validateSearch({ range: '30d' })).toEqual({ range: '30d' })
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(String(warn.mock.calls[0]?.[0])).toContain('linkSearch')
+  })
+
+  it('fires at most once per store, so a nav-heavy app is not spammed', () => {
+    const store = makeStore('warn-once')
+    persist('warn-once', '7d')
+
+    store.validateSearch({ range: '30d' })
+    store.validateSearch({ range: '30d' })
+    store.validateSearch({ range: '30d' })
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays silent once a reader is wired — that is the whole point', () => {
+    const store = makeStore('warn-wired')
+    persist('warn-wired', '7d')
+
+    store.linkSearch()
+    store.validateSearch({ range: '30d' })
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('stays silent for a deliberate deep link to a non-fallback value', () => {
+    const store = makeStore('warn-deeplink')
+    persist('warn-deeplink', '30d')
+
+    store.validateSearch({ range: '7d' })
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('stays silent when nothing is stored yet', () => {
+    makeStore('warn-empty').validateSearch({ range: '30d' })
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('never fires from validateSearch’s own internal read', () => {
+    // validateSearch reads the store on every navigation; that must not count as "wired", and it
+    // must not itself trigger the warning when the URL carries no param at all.
+    const store = makeStore('warn-internal')
+    persist('warn-internal', '7d')
+
+    expect(store.validateSearch({})).toEqual({ range: '7d' })
+    expect(warn).not.toHaveBeenCalled()
+    // Still unwired, so the pinned-link case is still detectable afterwards.
+    store.validateSearch({ range: '30d' })
+    expect(warn).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('validateSearch (unchanged behaviour)', () => {
+  it('prefers a valid URL param, then storage, then the fallback', () => {
+    const store = makeStore('validate')
+    expect(store.validateSearch({ range: '7d' })).toEqual({ range: '7d' })
+
+    persist('validate', '1d')
+    expect(store.validateSearch({})).toEqual({ range: '1d' })
+    expect(store.validateSearch({ range: 'bogus' })).toEqual({ range: '1d' })
+
+    localStorage.clear()
+    expect(store.validateSearch({})).toEqual({ range: '30d' })
+  })
+
+  it('discards an envelope written under a different version', () => {
+    persist('validate-version', '7d', 2)
+    expect(makeStore('validate-version').readStored()).toBeNull()
+  })
+})

package/src/router-tanstack/search-param-store.ts

@@ -9,6 +9,19 @@
  *    Call `persist(next)` alongside `navigate` so the selection survives
  *    navigation away from and back to the route.
  * 3. `readStored` — plain function for non-React contexts (tests, guards).
+ * 4. `linkSearch` — the click-time `search:` thunk a nav link needs, ready-made.
+ *
+ * ## The half that is easy to skip
+ *
+ * `validateSearch` restores the value when you navigate TO the route with no param. It cannot do
+ * anything about a nav link that declares the param itself — and a link written as
+ * `search: { range: '30d' }` at module scope pins the fallback on every click, which silently
+ * defeats the whole store. The reference consumer shipped exactly that: three features adopted the
+ * persistence, the reader had ZERO call sites, and "remember my window" had never once worked.
+ *
+ * `linkSearch` exists so that failure is unreachable from the API rather than only warned about in
+ * this comment — the mistake is made while typing `search:`, so the remedy has to be something
+ * autocomplete offers at that keystroke. The JSDoc was already here when it happened.
  *
  * Headless — no Mantine, no JSX. Same tier as `useBasaltNav` and
  * `useRouterBreadcrumbs`.
@@ -51,17 +64,18 @@
  *
  * **5. Nav links** — carry the param across sub-pages, set per destination in
  * the nav definition so only the dashboard sub-tree inherits it and every
- * other link stays clean. Use a CLICK-TIME THUNK over `readStored`:
- *
- *     const dashSearch = () => ({ range: dashboardRange.readStored() ?? '30d' })
+ * other link stays clean. Pass `linkSearch` BY REFERENCE — it is the click-time thunk:
  *
  *     navGroup({ id: 'dash', label: 'Dashboard' }, [
  *       { id: 'dash-overview', label: 'Overview', icon: <IconHome />,
- *         link: linkOptions({ to: '/dashboard', search: dashSearch }) },
+ *         link: linkOptions({ to: '/dashboard', search: dashboardRange.linkSearch }) },
  *       { id: 'dash-activity', label: 'Activity', icon: <IconPulse />,
- *         link: linkOptions({ to: '/dashboard/activity', search: dashSearch }) },
+ *         link: linkOptions({ to: '/dashboard/activity', search: dashboardRange.linkSearch }) },
  *     ])
  *
+ * `linkSearch` IS that thunk (`() => ({ [param]: readStored() ?? fallback })`) — hand-rolling it
+ * over `readStored` still works and is what you need when the link also carries other params.
+ *
  * NOT `search: true`. That flag means "keep the current search" and TanStack
  * only offers it where the target's search is OPTIONAL — a route wired to a
  * store's `validateSearch` always returns the param, so the router requires a
@@ -101,6 +115,42 @@ export type SearchParamStore<T extends string, P extends string = string> = {
   useStore: () => readonly [T, (next: T) => void]
   /** Plain read — for use outside React (tests, guards, fallback reads). */
   readStored: () => T | null
+  /**
+   * The click-time `search:` thunk for a nav link — `() => ({ [param]: readStored() ?? fallback })`.
+   *
+   * Pass it BY REFERENCE (`search: store.linkSearch`), never call it: `<Link>` re-evaluates the
+   * thunk on every click, so arriving from outside the sub-tree restores the last selection,
+   * whereas a value computed once at module scope goes stale immediately and pins the fallback.
+   */
+  linkSearch: () => { [K in P]: T }
+}
+
+/**
+ * Dev-only, once per store: the URL is pinning `fallback` while something else is persisted, and
+ * neither reader has ever been called. That combination has exactly one realistic cause — a nav
+ * link declaring the param as a literal — and it is invisible otherwise, because every individual
+ * piece looks correct and the feature merely never remembers anything.
+ *
+ * Deliberately NOT a timer over "was this store ever read": that fires in every test that builds a
+ * store, and it cannot say what to do about it. This fires only in the broken state, and names the
+ * fix.
+ */
+function warnLinkPinsFallback(input: {
+  key: string
+  param: string
+  urlValue: string
+  storedValue: string
+}): void {
+  const { key, param, urlValue, storedValue } = input
+  // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
+  console.warn(
+    `[basalt-ui] createSearchParamStore('${key}'): the URL pinned \`${param}=${urlValue}\` ` +
+      '(the fallback) ' +
+      `while '${storedValue}' was persisted, and nothing has read this store back. A nav link is ` +
+      `almost certainly declaring \`search: { ${param}: '${urlValue}' }\` at module scope, which ` +
+      "overrides the stored value on every click — pass the store's own reader instead: " +
+      '`search: <store>.linkSearch`. (dev only)',
+  )
 }
 
 // ── Implementation ─────────────────────────────────────────────────────────
@@ -110,19 +160,51 @@ export function createSearchParamStore<const T extends string, const P extends s
 ): SearchParamStore<T, P> {
   const version = opts.version ?? 1
 
-  const readStored = (): T | null => {
+  // `validateSearch` reads the store internally on every navigation, which says nothing about
+  // whether the CONSUMER wired a reader — only the two public readers below set this.
+  let readerWired = false
+  let warned = false
+
+  const read = (): T | null => {
     const raw = readPersistedValue(opts.key, version)
     if (typeof raw !== 'string') return null
     if ((opts.values as readonly string[]).includes(raw)) return raw as T
     return null
   }
 
+  const readStored = (): T | null => {
+    readerWired = true
+    return read()
+  }
+
+  const linkSearch = (): { [K in P]: T } => {
+    readerWired = true
+    return { [opts.param]: (read() ?? opts.fallback) as T } as { [K in P]: T }
+  }
+
   const validateSearch = (search: Record<string, unknown>): { [K in P]: T } => {
     const raw = search[opts.param]
     if (typeof raw === 'string' && (opts.values as readonly string[]).includes(raw)) {
+      if (
+        !warned &&
+        !readerWired &&
+        raw === opts.fallback &&
+        process.env['NODE_ENV'] !== 'production'
+      ) {
+        const stored = read()
+        if (stored !== null && stored !== raw) {
+          warned = true
+          warnLinkPinsFallback({
+            key: opts.key,
+            param: opts.param,
+            urlValue: raw,
+            storedValue: stored,
+          })
+        }
+      }
       return { [opts.param]: raw as T } as { [K in P]: T }
     }
-    return { [opts.param]: (readStored() ?? opts.fallback) as T } as { [K in P]: T }
+    return { [opts.param]: (read() ?? opts.fallback) as T } as { [K in P]: T }
   }
 
   const useStore = createPersistedState<T>({
@@ -131,5 +213,5 @@ export function createSearchParamStore<const T extends string, const P extends s
     initial: opts.fallback,
   })
 
-  return { validateSearch, useStore, readStored }
+  return { validateSearch, useStore, readStored, linkSearch }
 }

package/src/shell/app-mobile-nav.module.css

@@ -46,9 +46,17 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  /* Deliberately sub-scale: the active pill hugs a 24px glyph, so it is a shape inset rather than
-   * layout spacing — the xs..xl scale has no step this tight. */
-  padding: 2px 12px; /* theme-allow */
+  /* This span IS the active pill, so its box may not depend on what it contains: shipping no icon
+   * dependency is a supported configuration, and an empty span collapsed the pill to a 24x4px
+   * dash. The floor is the icon box PLUS its inset — everything is border-box under Mantine's
+   * reset — so the pill renders identically with and without a glyph, at every density. */
+  min-width: calc(
+    var(--vx-space-mobile-nav-icon-size) + 2 * var(--vx-space-mobile-nav-tab-inset-x)
+  );
+  min-height: calc(
+    var(--vx-space-mobile-nav-icon-size) + 2 * var(--vx-space-mobile-nav-tab-inset-y)
+  );
+  padding: var(--vx-space-mobile-nav-tab-inset-y) var(--vx-space-mobile-nav-tab-inset-x);
   border-radius: var(--vx-radius-ctrl);
   transition: transform 140ms cubic-bezier(0.32, 0.72, 0, 1);
 }

package/src/shell/app-mobile-nav.tsx

@@ -38,7 +38,7 @@ import classes from './app-mobile-nav.module.css'
  * bottom-anchored menu puts it UNDER the footer, off-screen — `menuMax` is what guarantees it fits
  * above the bar (§2.2). `shift.padding` is a viewport inset in px, not a layout spacing token.
  */
-const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } } // theme-allow
+const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } }
 
 /** A slot that navigates on tap. */
 type LinkSlot = Extract<MobileNavSlot, { kind: 'link' }>

package/src/shell/index.test.tsx

@@ -88,3 +88,55 @@ describe('BasaltShell extraMoreRows', () => {
     expect(screen.queryByLabelText('More')).toBeNull()
   })
 })
+
+/**
+ * Collapse persistence goes through the HOUSE api, not `@mantine/hooks`.
+ *
+ * Round 4 filed the reference consumer's raw `localStorage.getItem('basalt-sidebar-collapsed')` as
+ * consumer drift; round 5 corrected it — the shell itself used `useLocalStorage`, so the raw read
+ * was the only way to mirror what the shell wrote. These tests pin the shape a consumer now reads.
+ */
+describe('BasaltShell collapse persistence', () => {
+  const COLLAPSE_TOGGLE =
+    'button[aria-label="Collapse sidebar"], button[aria-label="Expand sidebar"]'
+
+  const renderShell = (storageKey: string) =>
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} storageKey={storageKey} />
+      </MantineProvider>,
+    )
+
+  test('writes the namespaced, versioned envelope — not a bare boolean at a bare key', () => {
+    const key = 'collapse-envelope'
+    localStorage.clear()
+    const { container } = renderShell(key)
+
+    fireEvent.click(container.querySelector(COLLAPSE_TOGGLE) as HTMLElement)
+
+    expect(localStorage.getItem(`basalt:${key}`)).toBe(JSON.stringify({ v: 1, value: true }))
+    expect(localStorage.getItem(key)).toBeNull()
+  })
+
+  test('adopts a pre-1.20.1 raw value once, so an upgrade keeps the sidebar collapsed', () => {
+    const key = 'collapse-legacy'
+    localStorage.clear()
+    // Exactly what `@mantine/hooks`' useLocalStorage wrote: JSON at the un-namespaced key.
+    localStorage.setItem(key, 'true')
+
+    renderShell(key)
+
+    expect(localStorage.getItem(`basalt:${key}`)).toBe(JSON.stringify({ v: 1, value: true }))
+  })
+
+  test('a value already in the house key wins over a stale legacy one', () => {
+    const key = 'collapse-both'
+    localStorage.clear()
+    localStorage.setItem(key, 'true')
+    localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: 1, value: false }))
+
+    renderShell(key)
+
+    expect(localStorage.getItem(`basalt:${key}`)).toBe(JSON.stringify({ v: 1, value: false }))
+  })
+})

package/src/shell/index.tsx

@@ -14,11 +14,10 @@
  * sidebar-collapse zustand store) stays consumer-side. The consumer resolves `item.active`,
  * `item.onClick`, `item.badge`/`item.count` and supplies `item.Anchor` — its router `<Link>`,
  * which basalt HOSTS rather than delegating rendering to. The breadcrumb is derived from the
- * active item across `sections`, not from a router hook. Collapse is persisted via
- * `@mantine/hooks` `useLocalStorage` keyed by `storageKey`.
+ * active item across `sections`, not from a router hook. Collapse is persisted via basalt's own
+ * `createPersistedState` (`../state`) keyed by `storageKey` — see `collapseStore`.
  */
 import { AppShell } from '@mantine/core'
-import { useLocalStorage } from '@mantine/hooks'
 import { useMemo } from 'react'
 import type { MouseEvent, ReactNode } from 'react'
 import { AppSidebar } from './app-sidebar'
@@ -30,6 +29,7 @@ import type { BasaltAccountProps } from './account-types'
 import type { SidebarSearchConfig } from './sidebar-search'
 import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
 import { useBasaltSpacing } from '../theme'
+import { createPersistedState } from '../state'
 import headerClasses from './app-header.module.css'
 import mobileNavClasses from './app-mobile-nav.module.css'
 
@@ -129,13 +129,20 @@ export type BasaltShellProps = {
    * `onOpen`, e.g. `() => openSpotlight()` from basalt-ui/commands.
    */
   search?: SidebarSearchConfig
-  /** localStorage key for the persisted sidebar-collapsed flag. Ignored when `collapsed` is set. */
+  /**
+   * localStorage key for the persisted sidebar-collapsed flag. Ignored when `collapsed` is set.
+   *
+   * Persisted through basalt's own `createPersistedState`, so the real storage key is
+   * `basalt:<storageKey>` and the value is the versioned `{ v, value }` envelope. A consumer
+   * mirroring this state reads it with `readPersistedValue(storageKey, 1)` from `basalt-ui/state`
+   * — never with a bare `localStorage.getItem`, which is what the pre-1.20.1 shell forced.
+   */
   storageKey?: string
   /**
-   * Controlled desktop-collapse value. When provided, the shell no longer owns the
-   * `useLocalStorage`-persisted collapse state — the consumer does (e.g. to drive it from its own
-   * `Cmd+B` hotkey). Pair with `onCollapsedChange` to receive toggle events; omitting both
-   * reproduces today's internal, persisted collapse behavior unchanged.
+   * Controlled desktop-collapse value. When provided, the shell no longer owns the persisted
+   * collapse state — the consumer does (e.g. to drive it from its own `Cmd+B` hotkey), and should
+   * own it through `createPersistedState` too. Pair with `onCollapsedChange` to receive toggle
+   * events; omitting both reproduces today's internal, persisted collapse behavior unchanged.
    */
   collapsed?: boolean
   /**
@@ -194,6 +201,54 @@ function findActiveWithParent(
   return undefined
 }
 
+/** Envelope version for the persisted collapse flag. Bump only if the value stops being a boolean. */
+const COLLAPSE_VERSION = 1
+
+/**
+ * One `createPersistedState` store per `storageKey`, memoized at module scope.
+ *
+ * Through 1.20.0 the shell persisted collapse with `@mantine/hooks`' `useLocalStorage` while
+ * `createPersistedState` was the documented house API — and this component's own docstring told
+ * consumers to mirror that when driving `collapsed` externally, so the reference consumer's raw
+ * `localStorage` call was COMPLIANCE with the shipped component rather than drift. A framework
+ * cannot ship a persistence rule its own shell breaks; this is the shell coming into line.
+ *
+ * The memo is required, not an optimization: `createPersistedState` is a per-key module FACTORY and
+ * `storageKey` is a runtime prop, so calling it during render would allocate a fresh store (and a
+ * fresh `useSyncExternalStore` subscription) on every commit. Swapping keys mid-life stays safe —
+ * every store's hook calls exactly one `useSyncExternalStore`, so the hook count never moves.
+ */
+const collapseStores = new Map<string, () => readonly [boolean, (next: boolean) => void]>()
+
+/**
+ * Seeds `basalt:<key>` from the raw pre-1.20.1 key once, so the switch doesn't silently re-expand
+ * every consumer's sidebar. Mantine's `useLocalStorage` wrote a bare `JSON.stringify(value)` at the
+ * un-namespaced key; only `'true'`/`'false'` are accepted, and only when the house key is empty.
+ * A one-upgrade bridge, not a supported format — delete it once no consumer predates 1.20.1.
+ */
+function migrateLegacyCollapse(key: string): void {
+  try {
+    if (window.localStorage.getItem(`basalt:${key}`) !== null) return
+    const legacy = window.localStorage.getItem(key)
+    if (legacy !== 'true' && legacy !== 'false') return
+    window.localStorage.setItem(
+      `basalt:${key}`,
+      JSON.stringify({ v: COLLAPSE_VERSION, value: legacy === 'true' }),
+    )
+  } catch {
+    // Storage blocked (private browsing, quota) — defaulting to expanded is a fine outcome.
+  }
+}
+
+function collapseStore(key: string): () => readonly [boolean, (next: boolean) => void] {
+  const cached = collapseStores.get(key)
+  if (cached) return cached
+  if (typeof window !== 'undefined') migrateLegacyCollapse(key)
+  const store = createPersistedState<boolean>({ key, version: COLLAPSE_VERSION, initial: false })
+  collapseStores.set(key, store)
+  return store
+}
+
 export function BasaltShell({
   brand,
   sections,
@@ -213,11 +268,7 @@ export function BasaltShell({
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal
   // container squeezes progressively worse as density rises.
   const { step } = useBasaltSpacing()
-  const [storedCollapsed, setStoredCollapsed] = useLocalStorage({
-    key: storageKey,
-    defaultValue: false,
-    getInitialValueInEffect: false,
-  })
+  const [storedCollapsed, setStoredCollapsed] = collapseStore(storageKey)()
   // Controlled/uncontrolled seam (item 19): an explicit `collapsed` prop overrides the internal
   // localStorage-persisted state entirely — the consumer becomes the source of truth.
   const isCollapseControlled = collapsedProp !== undefined

package/src/surfaces.ts

@@ -467,7 +467,7 @@ export const SURFACES = {
     kind: 'tooling',
     layer: 'non-js-asset',
     description:
-      'Prebuilt --vx-* token stylesheet — the default buildPaletteCss() output as a plain file, for a consumer with no bundler, no React and no Mantine; retune the selector or trim the spacing set with `basalt-ui tokens:css`',
+      'Prebuilt --vx-* token stylesheet — the default buildPaletteCss() output as a plain file, for a consumer that has a bundler to resolve the subpath but no React and no Mantine; with no bundler, emit a file you own via `basalt-ui tokens:css`',
     forbiddenImports: [],
   },
   './configs/*': {