basalt-ui 1.32.1 → 1.34.0

package/src/guard/types.ts

@@ -1,7 +1,7 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 27 violation kinds the theme guard can emit — `unframed-chart`
+ * GuardKind is the closed set of 28 violation kinds the theme guard can emit — `unframed-chart`
  * retired at the C2 consolidation wave: its only case (a hand-authored `<ChartLegend items={[...]}>`
  * array literal) is fully subsumed by the oxlint plugin's `basalt/chart-legend-literal`, which also
  * catches the `.map()`-over-a-non-series form the regex never could. `'unframed-chart'` stays a
@@ -11,7 +11,7 @@
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 27 theme-guard violation kinds. */
+/** The 28 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -40,6 +40,7 @@ export type GuardKind =
   | 'in-body-page-title'
   | 'raw-selection-control'
   | 'raw-media-query'
+  | 'unknown-vx-token'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/guard/vx-names.ts

@@ -0,0 +1,257 @@
+// GENERATED by scripts/gen-vx-names.ts — do not edit. `vx-names.test.ts` fails on drift.
+
+/** Every `--vx-*` name basalt emits: `dist/tokens.css` plus its component-scoped names. */
+export const BASALT_VX_NAMES: readonly string[] = [
+  '--vx-accent',
+  '--vx-accent-fill',
+  '--vx-accent-fill-hover',
+  '--vx-accent-hover',
+  '--vx-accentFill',
+  '--vx-accentFillHover',
+  '--vx-accentHover',
+  '--vx-area-bottom',
+  '--vx-area-top',
+  '--vx-axis',
+  '--vx-axis-stroke',
+  '--vx-axisStroke',
+  '--vx-bad',
+  '--vx-bad-ref',
+  '--vx-bad-solid',
+  '--vx-badRef',
+  '--vx-badSolid',
+  '--vx-crosshair',
+  '--vx-divider',
+  '--vx-dot-stroke',
+  '--vx-dotStroke',
+  '--vx-faint',
+  '--vx-fill-cyan',
+  '--vx-fill-grape',
+  '--vx-fill-gray',
+  '--vx-fill-green',
+  '--vx-fill-hover-cyan',
+  '--vx-fill-hover-grape',
+  '--vx-fill-hover-gray',
+  '--vx-fill-hover-green',
+  '--vx-fill-hover-indigo',
+  '--vx-fill-hover-lime',
+  '--vx-fill-hover-orange',
+  '--vx-fill-hover-pink',
+  '--vx-fill-hover-red',
+  '--vx-fill-hover-teal',
+  '--vx-fill-hover-violet',
+  '--vx-fill-hover-yellow',
+  '--vx-fill-indigo',
+  '--vx-fill-lime',
+  '--vx-fill-orange',
+  '--vx-fill-pink',
+  '--vx-fill-red',
+  '--vx-fill-teal',
+  '--vx-fill-violet',
+  '--vx-fill-yellow',
+  '--vx-fillHover-cyan',
+  '--vx-fillHover-grape',
+  '--vx-fillHover-gray',
+  '--vx-fillHover-green',
+  '--vx-fillHover-indigo',
+  '--vx-fillHover-lime',
+  '--vx-fillHover-orange',
+  '--vx-fillHover-pink',
+  '--vx-fillHover-red',
+  '--vx-fillHover-teal',
+  '--vx-fillHover-violet',
+  '--vx-fillHover-yellow',
+  '--vx-good',
+  '--vx-good-ref',
+  '--vx-good-soft',
+  '--vx-good-solid',
+  '--vx-goodRef',
+  '--vx-goodSoft',
+  '--vx-goodSolid',
+  '--vx-grid',
+  '--vx-hit',
+  '--vx-hit-gap',
+  '--vx-ink',
+  '--vx-ink2',
+  '--vx-keyboard-inset',
+  '--vx-legend-text',
+  '--vx-legendText',
+  '--vx-line',
+  '--vx-line2',
+  '--vx-muted',
+  '--vx-neutral',
+  '--vx-on-accent',
+  '--vx-onAccent',
+  '--vx-prose-measure',
+  '--vx-radius-card',
+  '--vx-radius-ctrl',
+  '--vx-radius-fine',
+  '--vx-radius-floating',
+  '--vx-radius-pill',
+  '--vx-radius-tight',
+  '--vx-shadow-card',
+  '--vx-shadow-ctrl',
+  '--vx-shadow-overlay',
+  '--vx-shadow-raised',
+  '--vx-space-agent-code-inset',
+  '--vx-space-agent-error-inset-x',
+  '--vx-space-agent-error-inset-y',
+  '--vx-space-agent-message-inset-x',
+  '--vx-space-agent-message-inset-y',
+  '--vx-space-agent-part-gap-top',
+  '--vx-space-agent-rail-inset-x',
+  '--vx-space-agent-scroll-button-gap-top',
+  '--vx-space-agent-transcript-inset',
+  '--vx-space-app-shell-header-lead-min',
+  '--vx-space-app-shell-inset',
+  '--vx-space-app-shell-inset-mobile',
+  '--vx-space-article-card-meta-gap-top',
+  '--vx-space-article-card-tag-inset-x',
+  '--vx-space-article-card-tag-inset-y',
+  '--vx-space-article-card-tags-gap',
+  '--vx-space-article-column-gap',
+  '--vx-space-article-footer-gap',
+  '--vx-space-article-footer-margin-top',
+  '--vx-space-article-footer-padding-top',
+  '--vx-space-article-header-gap',
+  '--vx-space-article-header-margin-bottom',
+  '--vx-space-article-header-padding-bottom',
+  '--vx-space-article-meta-row-gap',
+  '--vx-space-article-nav-target-gap',
+  '--vx-space-article-toc-rail-width',
+  '--vx-space-badge-inset-x',
+  '--vx-space-badge-inset-y',
+  '--vx-space-callout-inset-x',
+  '--vx-space-callout-inset-y',
+  '--vx-space-callout-title-row-gap',
+  '--vx-space-card-inset-x',
+  '--vx-space-card-inset-y',
+  '--vx-space-code-block-body-inset-y',
+  '--vx-space-code-block-content-inset-x',
+  '--vx-space-code-block-floating-copy-offset',
+  '--vx-space-code-block-header-gap',
+  '--vx-space-code-block-header-inset-right',
+  '--vx-space-code-block-header-inset-y',
+  '--vx-space-code-block-header-right-gap',
+  '--vx-space-control-gap',
+  '--vx-space-control-height',
+  '--vx-space-control-height-ctl',
+  '--vx-space-control-height-tag',
+  '--vx-space-control-height-widget',
+  '--vx-space-guide-body-gap-bottom',
+  '--vx-space-guide-footer-gap-top',
+  '--vx-space-guide-footer-inset-top',
+  '--vx-space-icon-size',
+  '--vx-space-input-height',
+  '--vx-space-mermaid-container-inset',
+  '--vx-space-mobile-nav-icon-size',
+  '--vx-space-mobile-nav-row-height',
+  '--vx-space-mobile-nav-tab-gap',
+  '--vx-space-mobile-nav-tab-inset-x',
+  '--vx-space-mobile-nav-tab-inset-y',
+  '--vx-space-nav-icon-gap',
+  '--vx-space-page-bar-row-height',
+  '--vx-space-prose-article-block-gap',
+  '--vx-space-prose-article-h1-gap-bottom',
+  '--vx-space-prose-article-h1-gap-top',
+  '--vx-space-prose-article-h2-rule-gap',
+  '--vx-space-prose-article-heading-gap-bottom',
+  '--vx-space-prose-article-heading-gap-top',
+  '--vx-space-prose-article-list-gap-bottom',
+  '--vx-space-prose-article-list-gap-top',
+  '--vx-space-prose-article-list-indent',
+  '--vx-space-prose-article-paragraph-gap',
+  '--vx-space-prose-chat-heading-gap-bottom',
+  '--vx-space-prose-chat-heading-gap-top',
+  '--vx-space-prose-chat-list-gap-bottom',
+  '--vx-space-prose-chat-list-indent',
+  '--vx-space-prose-chat-list-item-gap',
+  '--vx-space-prose-chat-nested-list-gap',
+  '--vx-space-prose-code-block-inset-x',
+  '--vx-space-prose-code-block-inset-y',
+  '--vx-space-prose-heading-anchor-gap',
+  '--vx-space-prose-inline-code-inset-x',
+  '--vx-space-prose-inline-code-inset-y',
+  '--vx-space-prose-quote-indent',
+  '--vx-space-prose-quote-inset-y',
+  '--vx-space-prose-table-cell-inset-x',
+  '--vx-space-prose-table-cell-inset-y',
+  '--vx-space-row-inset-x',
+  '--vx-space-row-inset-y',
+  '--vx-space-row-line-height',
+  '--vx-space-section-gap',
+  '--vx-space-section-header-height',
+  '--vx-space-settings-row-gap',
+  '--vx-space-settings-row-inset-y',
+  '--vx-space-sheet-row-height',
+  '--vx-space-sidebar-account-inset-bottom',
+  '--vx-space-sidebar-account-inset-top',
+  '--vx-space-sidebar-account-inset-x',
+  '--vx-space-sidebar-avatar-size',
+  '--vx-space-sidebar-block-row-height',
+  '--vx-space-sidebar-brand-inset-x',
+  '--vx-space-sidebar-child-list-gap-bottom',
+  '--vx-space-sidebar-child-list-gap-top',
+  '--vx-space-sidebar-child-list-indent',
+  '--vx-space-sidebar-child-row-indent',
+  '--vx-space-sidebar-child-row-inset-y',
+  '--vx-space-sidebar-region-gap',
+  '--vx-space-sidebar-search-gap',
+  '--vx-space-sidebar-search-trigger-height',
+  '--vx-space-sidebar-section-gap',
+  '--vx-space-sidebar-section-label-gap',
+  '--vx-space-stack-lg',
+  '--vx-space-stack-md',
+  '--vx-space-stack-sm',
+  '--vx-space-stack-xl',
+  '--vx-space-stack-xs',
+  '--vx-space-stat-card-gap',
+  '--vx-space-sticky-header-clearance',
+  '--vx-space-toc-link-indent',
+  '--vx-space-toc-link-inset-y',
+  '--vx-space-toc-root-gap',
+  '--vx-space-toc-sub-indent',
+  '--vx-space-virtual-row-inset-x',
+  '--vx-space-virtual-row-inset-y',
+  '--vx-space-widget-header-height',
+  '--vx-status-bad',
+  '--vx-status-excellent',
+  '--vx-status-good',
+  '--vx-status-neutral',
+  '--vx-status-warn',
+  '--vx-surface-bg',
+  '--vx-surface-border',
+  '--vx-surface-elevated',
+  '--vx-surface-field',
+  '--vx-surface-hairline',
+  '--vx-surface-overlay',
+  '--vx-surface-panel',
+  '--vx-surface-panel-hover',
+  '--vx-surface-panelHover',
+  '--vx-surface-subtle',
+  '--vx-text-display',
+  '--vx-text-h1',
+  '--vx-text-h2',
+  '--vx-text-kpi',
+  '--vx-text-lg',
+  '--vx-text-md',
+  '--vx-text-micro',
+  '--vx-text-nano',
+  '--vx-text-sm',
+  '--vx-text-xl',
+  '--vx-text-xs',
+  '--vx-tooltip-bg',
+  '--vx-tooltip-border',
+  '--vx-tooltip-muted',
+  '--vx-tooltip-shadow',
+  '--vx-tooltip-text',
+  '--vx-tooltipBg',
+  '--vx-tooltipBorder',
+  '--vx-tooltipMuted',
+  '--vx-tooltipShadow',
+  '--vx-tooltipText',
+  '--vx-warn',
+  '--vx-warn-ref',
+  '--vx-warn-solid',
+  '--vx-warnRef',
+  '--vx-warnSolid',
+]

package/src/index.ts

@@ -85,8 +85,6 @@ export {
   PageAside,
   type PageAsideProps,
   type PageAsideSlot,
-  useBreakpoint,
-  type BreakpointName,
   useSizeClass,
   type SizeClass,
   PageTitle,

package/src/notifications/mount-guard.ts

@@ -12,7 +12,6 @@
  * as `provider/lab-theme.ts`.
  */
 import { useEffect } from 'react'
-import { isDev } from '../common/is-dev'
 
 let mountedNotificationsCount = 0
 
@@ -25,7 +24,7 @@ let mountedNotificationsCount = 0
 export function useNotificationsMountGuard(): void {
   useEffect(() => {
     mountedNotificationsCount++
-    if (mountedNotificationsCount > 1 && isDev()) {
+    if (mountedNotificationsCount > 1 && process.env.NODE_ENV !== 'production') {
       console.warn(
         '[basalt] more than one Notifications overlay is mounted at once — mount exactly ONE ' +
           "<BasaltOverlays notifications /> (they all render Mantine's <Notifications />, so " +

package/src/provider/index.tsx

@@ -34,7 +34,6 @@ import { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from
 import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
-import { isDev } from '../common/is-dev'
 import { useMediaQuery } from '../common/use-media-query'
 import { registerColorSchemeSetter } from '../commands/shell-bridge'
 import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
@@ -125,7 +124,7 @@ export type BasaltProviderProps = {
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
 
 function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
-  if (isDev()) {
+  if (process.env.NODE_ENV !== 'production') {
     // eslint-disable-next-line no-console -- intentional dev-only diagnostic when no onError is supplied
     console.error('[BasaltProvider] unhandled error', ctx.kind, error)
   }
@@ -382,7 +381,7 @@ const providerMounts = createMountCounter()
 
 function useDuplicateProviderGuard(): void {
   useEffect(() => {
-    if (providerMounts.mount() > 1 && isDev()) {
+    if (providerMounts.mount() > 1 && process.env.NODE_ENV !== 'production') {
       console.warn(
         '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
           'BasaltProviders double-mount MantineProvider, the palette <style> and ' +

package/src/provider/lab-theme.ts

@@ -33,9 +33,9 @@
  * The delta also carries `other.basaltDerive`/`basaltRadius`/`basaltDensity`, so `BasaltBridge`'s
  * existing injection emits the matching `--vx-*` CSS off the running theme — one path, both halves.
  *
- * DEV-tool path only, twice over: it is compiled out of a production build entirely (see
- * {@link LAB_ENABLED}), and even in a dev build, with the "Apply" switch off — or in any app that
- * never mounts the panel, since the persisted key is written by nothing else —
+ * DEV-tool path only, twice over: it is compiled out of a production build entirely (see the
+ * DEV-build gate on `useLabTheme`), and even in a dev build, with the "Apply" switch off — or in
+ * any app that never mounts the panel, since the persisted key is written by nothing else —
  * {@link applyLabOverride} returns the consumer theme verbatim.
  */
 import { mergeThemeOverrides } from '@mantine/core'
@@ -44,7 +44,6 @@ import { useMemo } from 'react'
 import { useDeriveControlsState, toDeriveOverride } from '../theme-lab/derive-state'
 import type { DeriveOverride } from '../theme-lab/derive-state'
 import { baseTheme, createBasaltTheme } from '../theme'
-import { isDev } from '../common/is-dev'
 
 type Plain = Record<string, unknown>
 
@@ -124,20 +123,27 @@ export function applyLabOverride(
   return mergeThemeOverrides(theme, themeOverrideDelta(baseTheme, labTheme))
 }
 
-/**
- * DEV-build gate. `BasaltProvider` is the mandatory `.` entry, so an unconditional subscription to
- * the lab store would make EVERY production app pay a localStorage read + schema validation on first
- * render and keep a `window` 'storage' listener registered for its whole lifetime — to answer a
- * question ("is the dev lab active?") that is always "no" in an app that never mounts
- * `<DeriveControls>`. Resolved ONCE at module scope, so it also lets a bundler drop
- * `useLabThemeDev` (and with it the `theme-lab/derive-state` import) from a production build.
+/*
+ * DEV-build gate (on `useLabTheme` below). `BasaltProvider` is the mandatory `.` entry, so an
+ * unconditional subscription to the lab store would make EVERY production app pay a localStorage
+ * read + schema validation on first render and keep a `window` 'storage' listener registered for
+ * its whole lifetime — to answer a question ("is the dev lab active?") that is always "no" in an
+ * app that never mounts `<DeriveControls>`.
+ *
+ * Resolved ONCE at module scope, so a bundler can drop `useLabThemeDev` (and with it the
+ * `theme-lab/derive-state` + `state/persisted` imports) from a production build — but only
+ * because the gate is a literal, dotted `process.env.NODE_ENV` read inside the ternary itself.
+ * Measured (minified prod builds, dev branch behind an import): the literal read folds in
+ * Vite/Rolldown, esbuild, Bun and webpack + terser alike, in both the dotted and the bracketed
+ * form; dotted is kept as the form every `define` implementation matches. A cross-module
+ * `isDev()` call and a module-level `const` both LEAK the dev branch in esbuild and Bun (and
+ * `isDev()` in Rolldown too), which is how 1.32.1 shipped the whole lab store in every production
+ * app's first-paint chunk. `check-budgets.ts`'s provider-only budget pins it.
  *
- * The cost: the lab does nothing in a PRODUCTION BUILD of a playground/dev app. It is a dev tool run
- * through a dev server (`bun run dev`), so that is the right side of the trade — but if you ever
- * preview the playground via `vite build && vite preview`, the sliders will be inert there.
+ * The cost: the lab does nothing in a PRODUCTION BUILD of a playground/dev app. It is a dev tool
+ * run through a dev server (`bun run dev`), so that is the right side of the trade — but if you
+ * ever preview the playground via `vite build && vite preview`, the sliders will be inert there.
  */
-const LAB_ENABLED = isDev()
-
 /**
  * Dev build: subscribed to the lab store.
  *
@@ -159,9 +165,10 @@ function useLabThemeProd(overrides: MantineThemeOverride | undefined): MantineTh
 }
 
 /**
- * `BasaltProvider`'s theme resolution. Picked at module scope, not per render — both implementations
- * call their hooks unconditionally at their own top level, and which one is bound never changes for
- * the app's lifetime, so the hook order is as stable as a plain function's (a `LAB_ENABLED ? use…()`
- * inline in one function body would be a conditional hook call and a `react/rules-of-hooks` error).
+ * `BasaltProvider`'s theme resolution. Picked at module scope, not per render — both
+ * implementations call their hooks unconditionally at their own top level, and which one is bound
+ * never changes for the app's lifetime, so the hook order is as stable as a plain function's (a
+ * `dev ? use…()` inline in one function body would be a conditional hook call and a
+ * `react/rules-of-hooks` error).
  */
-export const useLabTheme = LAB_ENABLED ? useLabThemeDev : useLabThemeProd
+export const useLabTheme = process.env.NODE_ENV !== 'production' ? useLabThemeDev : useLabThemeProd

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

@@ -43,6 +43,24 @@ export type CreateSearchStoreOptions<S extends Record<string, AnyField>> = {
   fields: S
   /** Envelope version — bump when the field set changes to discard stale localStorage. */
   version?: number
+  /**
+   * Search params this store does NOT own that a URL-lane write drops, in the SAME navigate —
+   * `['page']` on a paginated list, so narrowing the set on page 5 lands on page 1 and Back restores
+   * both together. Dropped, not written: the route's own `validateSearch` resolves the default
+   * (`page` → 1), so the store never has to know it. Applies to a URL-lane field's setter and
+   * `clear()` when the value moves, and to `useReset()` when any field moves; an explicit `patch`
+   * naming the same key wins.
+   *
+   * **URL-lane writes only.** A `url: false` field (mirror-only or memory) makes no navigate, so it
+   * has none to ride — and a `useReset()` on a store with no URL-lane field keeps the page too.
+   *
+   * Store-wide by design: every filter of a list narrows the same list. A param the store owns is
+   * refused at definition — reset a field with `useReset()` or its own `clear()`.
+   *
+   * @example
+   * createSearchStore({ key: 'shares', fields: { q: field.string({}), sort: … }, resets: ['page'] })
+   */
+  resets?: readonly string[]
 }
 
 export type SearchStore<S extends Record<string, AnyField>> = {
@@ -205,6 +223,28 @@ function assertNoLazyUrlFallback(key: string, fields: Record<string, AnyField>):
   }
 }
 
+/**
+ * `resets` exists for keys the store does NOT own; one it owns would be dropped from the URL while
+ * the mirror kept its value — the same URL/mirror split `patch` refuses. Static, so thrown at
+ * definition.
+ */
+function assertResetsNotOwned(input: {
+  key: string
+  resets: readonly string[]
+  paramOwners: ReadonlyMap<string, string>
+}): void {
+  const { key, resets, paramOwners } = input
+  for (const param of resets) {
+    const owner = paramOwners.get(param)
+    if (owner === undefined) continue
+    throw new Error(
+      `basalt-ui: createSearchStore('${key}'): \`resets\` names \`${param}\`, which this store's ` +
+        `field '${owner}' owns. \`resets\` is for sibling params the store does not own (a ` +
+        '`page`); a field of the store is reset through `useReset()` or its own `clear()`.',
+    )
+  }
+}
+
 /** The memory-only lane: neither the URL nor the mirror, so the value lives in the store's own
  * session-scoped external store (`StoreCore.memoryUse`) — the lane `createLocalStore` also uses. */
 function isMemoryLane(entry: StoreEntry): boolean {
@@ -240,6 +280,25 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
   for (const entry of core.urlEntries) {
     for (const param of entry.codec.params) paramOwners.set(param, entry.name)
   }
+  const resets = o.resets ?? []
+  assertResetsNotOwned({ key: o.key, resets, paramOwners })
+  /** Spread right after `prev` in every store navigate, so a `patch` or the field itself wins. */
+  const resetPatch: Record<string, undefined> = Object.fromEntries(
+    resets.map((param) => [param, undefined]),
+  )
+  /**
+   * `resetPatch` when `next` moves the field off what the URL holds NOW — read from the navigate's
+   * own `prev`, never the render-captured value, which a second `set()` in the same tick would
+   * misjudge against a value the first one already replaced.
+   */
+  const resetsFor = (
+    entry: StoreEntry,
+    prev: Record<string, unknown>,
+    next: unknown,
+  ): Record<string, undefined> | undefined => {
+    const current = core.resolve(entry, prev, core.readRecord())
+    return entry.codec.equals(next, current) ? undefined : resetPatch
+  }
   const persistedNames = new Set(
     core.entries.filter((entry) => entry.codec.lane.persist).map((entry) => entry.name),
   )
@@ -326,8 +385,10 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
       if (!validated) return
       navigate({
         to: '.',
+        // Gated like the setter: clearing a field already at its fallback keeps the page.
         search: (prev: Record<string, unknown>) => ({
           ...prev,
+          ...resetsFor(entry, prev, entry.codec.fallback),
           ...entry.codec.toSearch(entry.codec.fallback),
         }),
         replace: true,
@@ -356,8 +417,11 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
             // `patch` FIRST, the field's own params last: a patch is for keys the store does not
             // own (clearing a sibling `detailDate` with `undefined`), so it must never be able to
             // overwrite the value this very call is setting.
+            // `resets` only when the value moves: a no-op write (a debounced box settling back on
+            // what it held) must not throw the reader off the page they are on.
             search: (prev: Record<string, unknown>) => ({
               ...prev,
+              ...resetsFor(entry, prev, next),
               ...opts?.patch,
               ...entry.codec.toSearch(next),
             }),
@@ -464,7 +528,15 @@ export function buildSearchStore<const S extends Record<string, AnyField>>(
         }
         navigate({
           to: '.',
-          search: (prev: Record<string, unknown>) => ({ ...prev, ...patch }),
+          // `resets` only when some field actually moves — the same gate as the setter and
+          // `clear()`. A `Reset all` with everything already at its fallback must keep the page:
+          // this navigate REPLACES, so a page dropped here could not be got back with Back.
+          search: (prev: Record<string, unknown>) => {
+            const moved = validatedEntries.some(
+              (entry) => resetsFor(entry, prev, entry.codec.fallback) !== undefined,
+            )
+            return { ...prev, ...(moved ? resetPatch : undefined), ...patch }
+          },
           replace: true,
           // Same reason as a single field's write above — a `Reset all` pressed from the mobile
           // sheet must not also scroll the page it was pressed on.

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

@@ -69,6 +69,18 @@
   height: var(--vx-space-mobile-nav-icon-size);
 }
 
+/* The first-letter fallback for an icon-less slot (`nav-glyph.tsx`) sits in the same icon-size box
+ * an svg gets, so the pill's height does not depend on the glyph's line box. */
+.tabIcon > [data-nav-glyph] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--vx-space-mobile-nav-icon-size);
+  height: var(--vx-space-mobile-nav-icon-size);
+  line-height: 1;
+  font-weight: 600;
+}
+
 .tab:active .tabIcon {
   transform: scale(0.9);
 }

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

@@ -39,6 +39,7 @@ import type {
 import type { BasaltAccountProps } from './account-types'
 import type { SettingsMenuItem } from './index'
 import { NavCountBadge } from './nav-count-badge'
+import { hasIcon, initialGlyph } from './nav-glyph'
 import { SidebarBlockToneDot } from './sidebar-blocks'
 import { sidebarBlockMobile } from './sidebar-block-model'
 import { useBasaltSpacing } from '../theme'
@@ -456,7 +457,13 @@ export function MobileNav({
   const tabInner = (slot: MobileNavSlot) => (
     <>
       <span className={classes.tabIcon}>
-        {slot.icon ?? (slot.kind !== 'link' && slot.isMore ? <IconMore /> : null)}
+        {hasIcon(slot.icon) ? (
+          slot.icon
+        ) : slot.kind !== 'link' && slot.isMore ? (
+          <IconMore />
+        ) : (
+          initialGlyph(slot.short)
+        )}
         {hasCount(slot) ? <span className={classes.tabDot} aria-hidden /> : null}
       </span>
       <Text className={classes.label}>{slot.short}</Text>

package/src/shell/app-sidebar.module.css

@@ -47,6 +47,12 @@
   margin-inline-end: var(--vx-space-nav-icon-gap);
 }
 
+/* The first-letter fallback for an icon-less row (`nav-glyph.tsx`) — a glyph, not a text run. */
+.link :global(.mantine-NavLink-section[data-position='left']) > [data-nav-glyph] {
+  line-height: 1;
+  font-weight: 600;
+}
+
 /* Inactive rows: muted text + faint icon. Active rows keep the theme's ink text (via `--nl-color`)
  * untouched — this selector only ever matches when `data-active` is absent. `aria-current` is no
  * longer part of the exclusion: `use-nav.ts` is the sole authority on active, stamping exactly one