basalt-ui 1.32.0 → 1.33.0

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/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/mobile-nav-model.ts

@@ -87,8 +87,6 @@ export function blockRowCount(blocks: readonly SidebarBlock[] | undefined): numb
   }).length
 }
 
-const DEV = process.env['NODE_ENV'] !== 'production'
-
 /**
  * §2.3 rule 1. A section's `mobile: false` wins over every item inside it; otherwise the item's own
  * field decides, with the shorthand booleans normalized and `undefined` meaning "reachable, but not
@@ -351,7 +349,7 @@ function buildCandidates(
   /** Rule 11 — `mobile: 'tab'` on a disabled destination is a configuration mistake, not a slot. */
   const tabbable = (item: SidebarItem): boolean => {
     if (!item.disabled) return true
-    if (DEV) {
+    if (process.env.NODE_ENV !== 'production') {
       console.warn(
         `[basalt] MobileNav: "${item.key}" asks for a bar slot but is disabled — a disabled destination never becomes a tab. It still renders, disabled, in the More surface.`,
       )
@@ -373,7 +371,7 @@ function buildCandidates(
         candidates.push(sectionCandidate(section, menuMax))
         continue
       }
-      if (DEV) {
+      if (process.env.NODE_ENV !== 'production') {
         console.warn(
           `[basalt] MobileNav: mobileNav.tabs names "${id}", which is neither a destination key nor a visible section label — ignoring it.`,
         )
@@ -464,7 +462,7 @@ export function projectMobileNav(
   const limit = needsMore ? maxTabs - 1 : maxTabs
   const kept = candidates.slice(0, limit)
   const dropped = candidates.slice(limit)
-  if (DEV && dropped.length > 0) {
+  if (process.env.NODE_ENV !== 'production' && dropped.length > 0) {
     // Rule 13 wants the NAMES, not a tally: "2 candidates dropped" tells a consumer their bar is
     // wrong, while the keys tell them which `mobile: 'tab'` to move or which section to reorder.
     console.warn(

package/src/shell/page-bar.tsx

@@ -46,9 +46,6 @@ import asideClasses from './page-aside.module.css'
 /** The custom property row 2's measured height is published on. */
 export const PAGE_BAR_HEIGHT_VAR = '--basalt-page-bar-h'
 
-/** Dev-only diagnostics, constant-folded out of a production bundle — see {@link useAsidePanelSlot}. */
-const DEV = process.env['NODE_ENV'] !== 'production'
-
 /**
  * What a `PageAside` publishes when it projects itself into row 2 below `sm`
  * (`docs/ASIDE-SPEC.md` §0 "Desktop and mobile are one declaration"). Metadata only — the aside's
@@ -236,7 +233,7 @@ export function useAsidePanelSlot(): {
     setSettled(true)
   }, [])
   useEffect(() => {
-    if (!DEV || !settled || !inShell || panelHost) return
+    if (process.env.NODE_ENV === 'production' || !settled || !inShell || panelHost) return
     console.warn(
       "[basalt] PageAside: this page's PageBar renders no row 2 (no `tabs`, no `filters`, no `filtersEnd`), so below `sm` there is no pill to open the aside — it renders in flow at the bottom of the page instead. Give the bar a row 2, or expect the in-flow form on a phone.",
     )
@@ -346,6 +343,30 @@ function useMeasuredHeightVar(active: boolean): (el: HTMLDivElement | null) => v
   return attach
 }
 
+/**
+ * The page's control bar — row 1 (title/icon, `actions`, `sync`) and row 2 (`tabs`, `filters`,
+ * `filtersEnd`). Inside `BasaltShell` both rows portal into shell chrome; with no shell it renders
+ * ONE sticky bar in flow, `title` leading, and needs no `PageBarProvider`.
+ *
+ * @example
+ * // Shell-less (linewatch-shaped): the store is local, the bar is the page's first child.
+ * const filters = createLocalStore({ key: 'outages', fields: { q: field.string({ max: 60 }) } })
+ *
+ * function OutagesPage() {
+ *   const [q] = filters.field.q.use()
+ *   return (
+ *     <>
+ *       <PageBar
+ *         title="Outages"
+ *         actions={{ primary: { key: 'export', label: 'Export', onClick: exportCsv } }}
+ *         filters={<FilterSet><SearchFilter field={filters.field.q} placeholder="Find a line" /></FilterSet>}
+ *         classNames={{ root: classes.bleed }} // your gutter bleed — see `PageBarSlot`
+ *       />
+ *       <OutageTable query={q} />
+ *     </>
+ *   )
+ * }
+ */
 export function PageBar({
   title,
   icon,

package/src/surfaces.ts

@@ -355,6 +355,8 @@ export const SURFACES = {
       'inline-font-size',
       'css-raw-surface',
       'surface-shadow-override',
+      // A `var(--vx-*)` naming a token basalt no longer (or never) emits.
+      'unknown-vx-token',
       // Not a token kind — the kind that judges the ANNOTATION rather than the code. It lands here
       // because `agent/rules/basalt-tokens.md` is where the `theme-allow` grammar is documented
       // (said once, on purpose), so this is the header that must name its enforcement.

package/src/tokens/index.ts

@@ -52,6 +52,16 @@ export type { RadiusValues } from './palette'
 export { deriveSpacing } from './palette'
 export type { SpaceValues } from './palette'
 
+// The two responsive tables — MIGRATING recipes and the raw-breakpoint guard messages send
+// consumers here for them; `migrating-imports.test.ts` pins that every documented import resolves.
+export {
+  CONTAINER_CLASSES,
+  CONTAINER_GRID_BREAKPOINTS,
+  resolveContainerClass,
+  SIZE_CLASSES,
+} from './size-classes'
+export type { ContainerClass } from './size-classes'
+
 /** A per-theme color pair: a hue keeps its identity but shifts shade across schemes. */
 export type ColorPair = { light: string; dark: string }
 

package/src/tokens/size-classes.ts

@@ -14,6 +14,20 @@ export const CONTAINER_CLASSES = { micro: 0, compact: 240, regular: 480, wide: 8
 
 export type ContainerClass = keyof typeof CONTAINER_CLASSES
 
+/**
+ * `CONTAINER_CLASSES` as the five-key map `<Grid type="container" breakpoints={…}>` takes (Mantine
+ * types it `Record<MantineSize, string>`), so `Grid.Col` keys resolve onto the grid's own width:
+ * `xs` opens compact, `sm` regular, `md`/`lg`/`xl` wide. `basalt/raw-breakpoint` trusts this import
+ * by name (from `basalt-ui/tokens`) — any other imported map is unreadable to it and flagged.
+ */
+export const CONTAINER_GRID_BREAKPOINTS = {
+  xs: `${CONTAINER_CLASSES.compact}px`,
+  sm: `${CONTAINER_CLASSES.regular}px`,
+  md: `${CONTAINER_CLASSES.wide}px`,
+  lg: `${CONTAINER_CLASSES.wide}px`,
+  xl: `${CONTAINER_CLASSES.wide}px`,
+} as const
+
 /** The class a MEASURED inline size falls in (`px` is a min-width boundary, so 240 is `compact`). */
 export function resolveContainerClass(px: number): ContainerClass {
   if (px >= CONTAINER_CLASSES.wide) return 'wide'

package/dist/common/is-dev.d.ts

@@ -1,3 +0,0 @@
-/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
-export declare function isDev(): boolean;
-//# sourceMappingURL=is-dev.d.ts.map

package/dist/common/is-dev.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-dev.d.ts","sourceRoot":"","sources":["../../src/common/is-dev.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,wBAAgB,KAAK,IAAI,OAAO,CAE/B"}

package/dist/common/is-dev.js

@@ -1,6 +0,0 @@
-function isDev() {
-  return process.env["NODE_ENV"] !== "production";
-}
-export {
-  isDev
-};

package/src/common/is-dev.ts

@@ -1,4 +0,0 @@
-/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
-export function isDev(): boolean {
-  return process.env['NODE_ENV'] !== 'production'
-}