basalt-ui 1.20.0 → 1.21.0

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.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 inline-spacing — a floating-ui viewport inset, not layout spacing
+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/tokens/index.ts

@@ -89,8 +89,30 @@ export const alpha = (token: string, a: number): string =>
  * `theme/index.ts`), so the component surface scales with the user's browser font-size AND with
  * `--mantine-scale`. `md` is the body step; `lg` is pinned at exactly 16px because it doubles as
  * the iOS input floor (see the `styles.css` floor — Safari zooms the viewport on focus below 16px).
+ *
+ * ## Adding a rung
+ *
+ * The ladder is hand-tuned per ROLE, not generated — but it is not arbitrary either, and the
+ * constraint is what keeps a "just add the size I need" request from dissolving it. Every adjacent
+ * pair sits between **1.06× and 1.17×**, so a new rung must too:
+ *
+ *  • Below the range, two rungs are visually the same size and the ladder stops being a choice —
+ *    the guard would then report a size for which two tokens are equally "right".
+ *  • Above it, the jump reads as a different type system rather than the next step of this one.
+ *
+ * That test is what admitted `nano` (11/10 = 1.10) and `display` (30/26 = 1.154, the second-widest
+ * step, which is the shape a display tier is supposed to have), and what rejected a 20px rung
+ * between `xl` (18) and `h2` (21): 21/20 = 1.05 is below the floor, and `h2` is already 1px away
+ * from any 20px site. A size the ladder declines to grow a rung for is a size that should snap to
+ * its nearest step — not a `theme-allow`.
+ *
+ * A rung is also a ROLE, not just a number. `nano` and `display` are both deliberately named for
+ * where they belong (a label engraved inside a drawn object; a numeral read from across a room)
+ * rather than for a position, because the failure mode of a bare `xxs`/`xxl` is that it becomes the
+ * escape hatch for every size the ladder was meant to prevent.
  */
 const TEXT = {
+  nano: 10, // engraved/graphic label INSIDE a drawn object (a plate face, a dial, a chip) — never UI copy or prose
   micro: 11, // mono uppercase micro-label (table th, Menu.Label, sidebar/section headers, axis ticks)
   xs: 12.5, // delta badges, tooltip meta, dense chrome, StatCard labels
   sm: 13.5, // table/stat numerals, chart tooltip, legend
@@ -100,6 +122,7 @@ const TEXT = {
   h2: 21, // article-density Prose h2 (docs/CONTENT-SPEC.md §5)
   kpi: 24, // the StatCard hero numeral (density pass: 31 → 24, tighter/less shouty)
   h1: 26, // article-density Prose h1 (docs/CONTENT-SPEC.md §5)
+  display: 30, // a numeral read at arm's length (a keypad readout, a timer, a kiosk figure) — not a heading
 } as const
 
 export const VX = {
@@ -766,7 +789,7 @@ export type BuildPaletteOpts = {
    * `'core'` keeps the 9 generic anchors — the stack rhythm, the two control heights, the row
    * insets — and drops the 99 named for a specific basalt component
    * (`--vx-space-agent-transcript-inset`, `--vx-space-toc-sub-indent`, …), taking the emitted set
-   * from 202 variables to 103. Nothing outside basalt's own React components reads those, so a
+   * from 204 variables to 105. Nothing outside basalt's own React components reads those, so a
    * framework-free consumer is carrying them for nothing.
    *
    * This is a SPACING filter only: color, radius, shadow, type and status variables are identical

package/src/tokens/palette.ts

@@ -132,7 +132,7 @@ export const SHADOW = {
    * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
    */
   raised: {
-    light: '0 1px 2px rgba(28, 25, 23, 0.10)',
+    light: '0 1px 2px rgba(28, 25, 23, 0.1)',
     dark: '0 1px 2px rgba(0, 0, 0, 0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
   },
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a REAL drop shadow, a
@@ -140,7 +140,7 @@ export const SHADOW = {
   // Unlike `card`, no embedded ring: floating surfaces carry a real 1px `--vx-surface-border` so
   // Mantine's rotated-square arrow inherits a proper edge.
   overlay: {
-    light: '0 8px 24px rgba(28, 25, 23, 0.10)',
+    light: '0 8px 24px rgba(28, 25, 23, 0.1)',
     dark: '0 8px 24px rgba(0, 0, 0, 0.5)',
   },
 } as const

package/src/tokens/text-scale.test.ts

@@ -0,0 +1,51 @@
+/**
+ * The type ladder's own law — the thing that decides whether a requested size gets a rung.
+ *
+ * This exists because the ladder is hand-tuned rather than generated, which is exactly the shape
+ * that erodes: a consumer reports "no step for 20px", someone adds 20, and now 20 and 21 are the
+ * same size and the guard reports a violation with two equally-correct remedies. Pinning the ratio
+ * band makes the next request answerable with arithmetic instead of taste.
+ */
+import { describe, expect, it } from 'bun:test'
+import { VX } from './index'
+
+/** Every adjacent pair of the shipped ladder, ascending. */
+const STEPS = Object.values(VX.text)
+const RATIOS = STEPS.slice(1).map((size, index) => size / STEPS[index]!)
+
+/** The band documented on `TEXT` in `tokens/index.ts`. Widen it only with a reason written there. */
+const MIN_RATIO = 1.06
+const MAX_RATIO = 1.17
+
+describe('the type ladder', () => {
+  it('is strictly ascending, so `Object.values` order IS the ladder order', () => {
+    expect(STEPS).toEqual(STEPS.toSorted((a, b) => a - b))
+    expect(new Set(STEPS).size).toBe(STEPS.length)
+  })
+
+  it('keeps every adjacent step inside the 1.06–1.17 band', () => {
+    const offenders = RATIOS.map((ratio, index) => ({
+      pair: `${STEPS[index]} → ${STEPS[index + 1]}`,
+      ratio: Number(ratio.toFixed(3)),
+    })).filter(({ ratio }) => ratio < MIN_RATIO || ratio > MAX_RATIO)
+
+    expect(offenders).toEqual([])
+  })
+
+  it('spans the two ends consumers reported as unreachable', () => {
+    // A label engraved inside a drawn object, and a numeral read at arm's length. Both arrived from
+    // the same consumer round; both are roles the ladder genuinely had no step for.
+    expect(VX.text.nano).toBe(10)
+    expect(VX.text.display).toBe(30)
+  })
+
+  it('has no rung between xl and h2 — 21/20 = 1.05 is below the band', () => {
+    // The third site from that report. `h2` is the remedy, not a waiver: it is 1px away.
+    expect(STEPS.filter((size) => size > VX.text.xl && size < VX.text.h2)).toEqual([])
+    expect(VX.text.h2 / 20).toBeLessThan(MIN_RATIO)
+  })
+
+  it('pins the iOS input floor, which is a rung with an external constraint', () => {
+    expect(VX.text.lg).toBe(16)
+  })
+})