basalt-ui 1.20.0 → 1.22.0

package/dist/router-tanstack/search-param-store.js

@@ -1,25 +1,53 @@
 import { createPersistedState, readPersistedValue } from "../state.js";
+function warnLinkPinsFallback(input) {
+  const { key, param, urlValue, storedValue } = input;
+  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 \u2014 pass the store's own reader instead: \`search: <store>.linkSearch\`. (dev only)`
+  );
+}
 function createSearchParamStore(opts) {
   const version = opts.version ?? 1;
-  const readStored = () => {
+  let readerWired = false;
+  let warned = false;
+  const read = () => {
     const raw = readPersistedValue(opts.key, version);
     if (typeof raw !== "string") return null;
     if (opts.values.includes(raw)) return raw;
     return null;
   };
+  const readStored = () => {
+    readerWired = true;
+    return read();
+  };
+  const linkSearch = () => {
+    readerWired = true;
+    return { [opts.param]: read() ?? opts.fallback };
+  };
   const validateSearch = (search) => {
     const raw = search[opts.param];
     if (typeof raw === "string" && opts.values.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 };
     }
-    return { [opts.param]: readStored() ?? opts.fallback };
+    return { [opts.param]: read() ?? opts.fallback };
   };
   const useStore = createPersistedState({
     key: opts.key,
     version,
     initial: opts.fallback
   });
-  return { validateSearch, useStore, readStored };
+  return { validateSearch, useStore, readStored, linkSearch };
 }
 export {
   createSearchParamStore

package/dist/router-tanstack/search-param-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-param-store.test.d.ts.map

package/dist/router-tanstack/search-param-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-param-store.test.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.test.ts"],"names":[],"mappings":""}

package/dist/shell/index.d.ts

@@ -67,13 +67,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;
     /**

package/dist/shell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAK3F,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAElF;;;;GAIG;AACH,YAAY,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG;IACxB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6CAA6C;IAC7C,KAAK,EAAE,WAAW,CAAA;IAClB,mGAAmG;IACnG,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,SAAS,CAAA;IAC3B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,oBAAoB;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAgDD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,UAAuC,EACvC,SAAS,EAAE,aAAa,EACxB,iBAAiB,EACjB,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE,gBAAgB,+BAgGlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}

package/dist/shell/index.js

@@ -1,6 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { AppShell } from "@mantine/core";
-import { useLocalStorage } from "@mantine/hooks";
 import { useMemo } from "react";
 import { AppSidebar } from "./app-sidebar.js";
 import { MobileNav, accountRowCount } from "./app-mobile-nav.js";
@@ -8,6 +7,7 @@ import { projectMobileNav } from "./mobile-nav-model.js";
 import { AppBreadcrumbs } from "./app-breadcrumbs.js";
 import { PageActionsOutlet, PageHeaderProvider } from "./page-header.js";
 import { useBasaltSpacing } from "../theme/index.js";
+import { createPersistedState } from "../state.js";
 import headerClasses from "./app-header.module.css";
 import mobileNavClasses from "./app-mobile-nav.module.css";
 import { AppSidebar as AppSidebar2 } from "./app-sidebar.js";
@@ -47,6 +47,28 @@ function findActiveWithParent(items, parentLabel, parentAnchor, parentHref) {
   }
   return void 0;
 }
+const COLLAPSE_VERSION = 1;
+const collapseStores = /* @__PURE__ */ new Map();
+function migrateLegacyCollapse(key) {
+  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 {
+  }
+}
+function collapseStore(key) {
+  const cached = collapseStores.get(key);
+  if (cached) return cached;
+  if (typeof window !== "undefined") migrateLegacyCollapse(key);
+  const store = createPersistedState({ key, version: COLLAPSE_VERSION, initial: false });
+  collapseStores.set(key, store);
+  return store;
+}
 function BasaltShell({
   brand,
   sections,
@@ -62,11 +84,7 @@ function BasaltShell({
   children
 }) {
   const { step } = useBasaltSpacing();
-  const [storedCollapsed, setStoredCollapsed] = useLocalStorage({
-    key: storageKey,
-    defaultValue: false,
-    getInitialValueInEffect: false
-  });
+  const [storedCollapsed, setStoredCollapsed] = collapseStore(storageKey)();
   const isCollapseControlled = collapsedProp !== void 0;
   const collapsed = isCollapseControlled ? collapsedProp : storedCollapsed;
   const toggleCollapse = () => {

package/dist/tokens/index.d.ts

@@ -40,6 +40,7 @@ export declare const VX: {
     readonly legendGap: number;
     readonly legendFontSize: 13.5;
     readonly text: {
+        readonly nano: 10;
         readonly micro: 11;
         readonly xs: 12.5;
         readonly sm: 13.5;
@@ -49,6 +50,7 @@ export declare const VX: {
         readonly h2: 21;
         readonly kpi: 24;
         readonly h1: 26;
+        readonly display: 30;
     };
     readonly radiusCard: "var(--vx-radius-card)";
     readonly radiusCtrl: "var(--vx-radius-ctrl)";
@@ -240,7 +242,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/dist/tokens/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"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"}

package/dist/tokens/index.js

@@ -14,6 +14,8 @@ import { deriveRadius } from "./palette.js";
 import { deriveSpacing } from "./palette.js";
 const alpha = (token, a) => `color-mix(in srgb, ${token} ${Math.round(a * 100)}%, transparent)`;
 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,
@@ -30,8 +32,10 @@ const TEXT = {
   // article-density Prose h2 (docs/CONTENT-SPEC.md §5)
   kpi: 24,
   // the StatCard hero numeral (density pass: 31 → 24, tighter/less shouty)
-  h1: 26
+  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
 };
 const VX = {
   // Non-color sizing constants

package/dist/tokens/palette.d.ts

@@ -112,11 +112,11 @@ export declare const SHADOW: {
      * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
      */
     readonly raised: {
-        readonly light: "0 1px 2px rgba(28, 25, 23, 0.10)";
+        readonly light: "0 1px 2px rgba(28, 25, 23, 0.1)";
         readonly dark: "0 1px 2px rgba(0, 0, 0, 0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)";
     };
     readonly overlay: {
-        readonly light: "0 8px 24px rgba(28, 25, 23, 0.10)";
+        readonly light: "0 8px 24px rgba(28, 25, 23, 0.1)";
         readonly dark: "0 8px 24px rgba(0, 0, 0, 0.5)";
     };
 };

package/dist/tokens/palette.js

@@ -72,7 +72,7 @@ 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
@@ -80,7 +80,7 @@ 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)"
   }
 };

package/dist/tokens/text-scale.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=text-scale.test.d.ts.map

package/dist/tokens/text-scale.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-scale.test.d.ts","sourceRoot":"","sources":["../../src/tokens/text-scale.test.ts"],"names":[],"mappings":""}

package/dist/tokens.css

@@ -138,6 +138,7 @@
   --vx-fill-hover-lime: color-mix(in srgb, var(--vx-fill-lime) 88%, #000);
   --vx-fill-hover-yellow: color-mix(in srgb, var(--vx-fill-yellow) 88%, #000);
   --vx-fill-hover-orange: color-mix(in srgb, var(--vx-fill-orange) 88%, #000);
+  --vx-text-nano: 10px;
   --vx-text-micro: 11px;
   --vx-text-xs: 12.5px;
   --vx-text-sm: 13.5px;
@@ -147,6 +148,7 @@
   --vx-text-h2: 21px;
   --vx-text-kpi: 24px;
   --vx-text-h1: 26px;
+  --vx-text-display: 30px;
   --vx-area-top: 22%;
   --vx-area-bottom: 1%;
   --vx-good: color-mix(in srgb, var(--vx-good-solid) 18%, transparent);
@@ -274,8 +276,8 @@ html[data-mantine-color-scheme='light'] {
   --vx-divider: color-mix(in srgb, #e5e5e5 65%, transparent);
   --vx-shadow-card: 0 1px 2px rgba(28, 25, 23, 0.05), 0 0 0 1px var(--vx-surface-hairline);
   --vx-shadow-ctrl: 0 1px 2px rgba(28, 25, 23, 0.12);
-  --vx-shadow-raised: 0 1px 2px rgba(28, 25, 23, 0.10);
-  --vx-shadow-overlay: 0 8px 24px rgba(28, 25, 23, 0.10);
+  --vx-shadow-raised: 0 1px 2px rgba(28, 25, 23, 0.1);
+  --vx-shadow-overlay: 0 8px 24px rgba(28, 25, 23, 0.1);
   --vx-surface-bg: #f2f2f5;
   --vx-surface-panel: #fafafd;
   --vx-surface-panel-hover: #ffffff;

package/dist/vite.d.ts

@@ -49,7 +49,21 @@ export type BasaltAppOptions = {
         light: string;
         dark: string;
     };
-    /** Manifest `background_color` + anti-FOUC paint color. Default: the resolved dark theme color. */
+    /**
+     * Which scheme the anti-FOUC `<style>` paints before the app boots. Default `'dark'` —
+     * `BasaltProvider`'s own default. `'light'` paints the light surface, `'auto'` declares
+     * `color-scheme: light dark` and picks the background off `prefers-color-scheme`, and `false`
+     * paints the background but declares no `color-scheme` at all (leave native controls to Mantine).
+     *
+     * Set this to whatever the app passes as `defaultColorScheme` — a mismatch is a visible flash of
+     * the wrong surface, not a correctness bug: the boot rule stops applying the moment Mantine
+     * writes `data-mantine-color-scheme` on `<html>` (see `BOOT_SCOPE`).
+     */
+    colorScheme?: 'dark' | 'light' | 'auto' | false;
+    /**
+     * Manifest `background_color` + anti-FOUC paint color. Default: the theme color matching
+     * `colorScheme` (the dark one for `'dark'` / `'auto'` / `false`, the light one for `'light'`).
+     */
     backgroundColor?: string;
     /** Manifest `display` mode. Default: `'standalone'`. */
     display?: 'standalone' | 'minimal-ui' | 'fullscreen' | 'browser';
@@ -66,7 +80,10 @@ export type BasaltAppOptions = {
     scope?: string;
     /** Manifest `id`. Default: the resolved `startUrl` (default- or explicitly-derived, per above). */
     id?: string;
-    /** Icon links + manifest icon paths. `false` skips the head `<link>` icons entirely. */
+    /**
+     * Icon links + manifest icon paths. `false` skips BOTH — the head `<link>` icons and the
+     * manifest's `icons` array — so a manifest is never emitted pointing at files that 404.
+     */
     icons?: false | {
         dir?: string;
     };
@@ -104,13 +121,21 @@ export type BasaltAppOptions = {
  * manifest `theme_color` both need a FLAT color, so the flattening step is the contract this
  * plugin owes its output regardless of which shape the palette hands it.
  *
+ * Two behaviours worth knowing before adopting it, both of which the plugin owns because the
+ * consumer cannot reach them:
+ *  • It HOISTS the shell's `<meta charset>` ahead of everything it injects, so the encoding
+ *    declaration stays inside the spec's first 1024 bytes (see `hoistCharset`).
+ *  • The anti-FOUC `<style>` expires the moment Mantine resolves the real scheme, and `colorScheme`
+ *    selects which surface it paints until then (see `BOOT_SCOPE` / `buildBootStyle`).
+ *
  * @example
  * // vite.config.ts
  * import { basaltAppPlugin, basaltViteConfig } from 'basalt-ui/vite'
  *
  * export default {
  *   ...basaltViteConfig({ port: 5173 }),
- *   plugins: [react(), ...basaltAppPlugin({ name: 'Argo' })],
+ *   // colorScheme mirrors <BasaltProvider defaultColorScheme> — omit it for the dark default.
+ *   plugins: [react(), ...basaltAppPlugin({ name: 'Argo', colorScheme: 'auto' })],
  * }
  */
 export declare function basaltAppPlugin(options: BasaltAppOptions): PluginOption[];

package/dist/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AA6CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAgFpE;AAgBD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,mGAAmG;IACnG,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,wFAAwF;IACxF,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AAuZD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AA6CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAgFpE;AAgBD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;IAC/C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AA4gBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}

package/dist/vite.js

@@ -140,6 +140,29 @@ const VIEWPORT_TAG = {
   tag: "meta",
   attrs: { name: "viewport", content: "width=device-width, initial-scale=1.0, viewport-fit=cover" }
 };
+const BOOT_SCOPE = "html:not([data-mantine-color-scheme])";
+const BOOT_COLOR_SCHEME = { dark: "dark", light: "light", auto: "light dark" };
+function buildBootStyle(input) {
+  const { colorScheme, themeColor, backgroundColor, explicitBackground } = input;
+  if (colorScheme === false) return `${BOOT_SCOPE}{background-color:${backgroundColor}}`;
+  const scheme = BOOT_COLOR_SCHEME[colorScheme];
+  if (colorScheme !== "auto" || explicitBackground) {
+    return `${BOOT_SCOPE}{background-color:${backgroundColor};color-scheme:${scheme}}`;
+  }
+  return `${BOOT_SCOPE}{background-color:${themeColor.light};color-scheme:${scheme}}@media(prefers-color-scheme:dark){${BOOT_SCOPE}{background-color:${themeColor.dark}}}`;
+}
+const CHARSET_META_RE = /[ \t]*<meta\s+charset\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>=]+))\s*\/?>[ \t]*\r?\n?/i;
+const HTTP_EQUIV_CHARSET_RE = /<meta\s[^>]*http-equiv\s*=\s*["']?content-type["']?[^>]*>/i;
+const DEFAULT_CHARSET = "UTF-8";
+function hoistCharset(html) {
+  if (HTTP_EQUIV_CHARSET_RE.test(html)) return { html, tag: void 0 };
+  const match = CHARSET_META_RE.exec(html);
+  const charset = match?.[1] ?? match?.[2] ?? match?.[3] ?? DEFAULT_CHARSET;
+  return {
+    html: match ? html.replace(CHARSET_META_RE, "") : html,
+    tag: { tag: "meta", attrs: { charset } }
+  };
+}
 function buildSeoTags(input) {
   const { name, description, seo } = input;
   const tags = [];
@@ -183,7 +206,7 @@ function buildStaticTags(input) {
     options,
     shortName,
     themeColor,
-    backgroundColor,
+    bootStyle,
     iconsEnabled,
     iconsDir,
     darkreader,
@@ -210,10 +233,7 @@ function buildStaticTags(input) {
       }
     }
   );
-  tags.push({
-    tag: "style",
-    children: `html{background-color:${backgroundColor};color-scheme:dark}`
-  });
+  tags.push({ tag: "style", children: bootStyle });
   if (iconsEnabled) {
     tags.push(
       {
@@ -274,8 +294,9 @@ function buildManifestJson(input) {
     scope,
     id,
     display,
-    themeColor,
+    schemeColor,
     backgroundColor,
+    iconsEnabled,
     iconsDir,
     base
   } = input;
@@ -287,21 +308,29 @@ function buildManifestJson(input) {
     start_url: startUrl,
     scope,
     display,
-    theme_color: themeColor.dark,
+    // A manifest carries ONE theme color, so it follows the boot scheme rather than the dual
+    // `<meta name="theme-color">` pair. Unchanged for the default (`'dark'`) and for `'auto'`.
+    theme_color: schemeColor,
     background_color: backgroundColor,
-    icons: [
-      {
-        src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest192)),
-        sizes: "192x192",
-        type: "image/png"
-      },
-      {
-        src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest512)),
-        sizes: "512x512",
-        type: "image/png",
-        purpose: "any maskable"
-      }
-    ]
+    // `icons: false` reaches HERE too, not just the head links. The array was unconditional, so
+    // `{ manifest: true, icons: false }` shipped a manifest pointing at two PNGs the app never
+    // ships — an installable app with broken icons, and the reason rb went hybrid (plugin for the
+    // head, a hand-written manifest for the rest). A manifest with NO icons member is valid.
+    ...iconsEnabled ? {
+      icons: [
+        {
+          src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest192)),
+          sizes: "192x192",
+          type: "image/png"
+        },
+        {
+          src: withBase(base, withIconPath(iconsDir, ICON_FILES.manifest512)),
+          sizes: "512x512",
+          type: "image/png",
+          purpose: "any maskable"
+        }
+      ]
+    } : {}
   };
   return JSON.stringify(manifest, null, 2);
 }
@@ -313,7 +342,15 @@ function createMainPlugin(options) {
   const iconsDir = options.icons === false ? void 0 : options.icons?.dir;
   const manifestEnabled = options.manifest !== false;
   const themeColor = resolveThemeColors(options.themeColor);
-  const backgroundColor = options.backgroundColor ?? themeColor.dark;
+  const colorScheme = options.colorScheme ?? "dark";
+  const schemeColor = colorScheme === "light" ? themeColor.light : themeColor.dark;
+  const backgroundColor = options.backgroundColor ?? schemeColor;
+  const bootStyle = buildBootStyle({
+    colorScheme,
+    themeColor,
+    backgroundColor,
+    explicitBackground: options.backgroundColor !== void 0
+  });
   let manifestJson = "";
   let manifestHref = "/site.webmanifest";
   let staticTags = [];
@@ -332,8 +369,9 @@ function createMainPlugin(options) {
         scope,
         id,
         display,
-        themeColor,
+        schemeColor,
         backgroundColor,
+        iconsEnabled,
         iconsDir,
         base
       });
@@ -341,7 +379,7 @@ function createMainPlugin(options) {
         options,
         shortName,
         themeColor,
-        backgroundColor,
+        bootStyle,
         iconsEnabled,
         iconsDir,
         darkreader,
@@ -350,9 +388,20 @@ function createMainPlugin(options) {
         manifestHref
       });
     },
-    transformIndexHtml(html) {
-      const tags = hasViewportMeta(html) ? staticTags : [VIEWPORT_TAG, ...staticTags];
-      return { html, tags };
+    transformIndexHtml: {
+      // `pre` so this plugin's tags are the FIRST head-prepend contributions Vite collects — that
+      // ordering is what puts the hoisted <meta charset> at the very top of <head> rather than
+      // behind another plugin's tags. Vite injects all collected tags after every hook has run.
+      order: "pre",
+      handler(html) {
+        const hoisted = hoistCharset(html);
+        const tags = [
+          ...hoisted.tag ? [hoisted.tag] : [],
+          ...hasViewportMeta(html) ? [] : [VIEWPORT_TAG],
+          ...staticTags
+        ];
+        return { html: hoisted.html, tags };
+      }
     },
     generateBundle() {
       if (!manifestEnabled) return;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.20.0
+# basalt-ui v1.22.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.20.0
+Version: 1.22.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/kinds/Bars.tsx

@@ -125,7 +125,7 @@ export type BarsProps<T> = {
   /** Legend config forwarded to `CartesianChart`; `false` disables the legend (sparkline escape).
    * Default `{ placement: 'bottom' }`. */
   legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean

package/src/charts/kinds/Donut.tsx

@@ -50,7 +50,7 @@ export type DonutProps<K extends string = SeriesKey> = {
   centerContent?: ReactNode
   innerRatio?: number
   padAngle?: number
-  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean

package/src/charts/kinds/DualPanel.tsx

@@ -94,7 +94,7 @@ export type DualPanelProps<T> = {
   /** Legend config forwarded to `ChartFrame`; `false` disables the legend (sparkline escape).
    * Default `{ placement: 'bottom' }`. */
   legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
@@ -521,7 +521,7 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
             </>
           )}
 
-          {/* theme-allow basalt/hand-rolled-plot: TWO panes over one x scale is not a single
+          {/* theme-allow-file basalt/hand-rolled-plot: TWO panes over one x scale is not a single
               cartesian plot, so `CartesianChart` (one plot rect, one or two y axes) cannot express
               it. This file therefore assembles the plot itself — but from the SAME parts every
               other chart gets: `ChartFrame`, `autoMargin` + `probeAxisLabels`, `useChartCursor`,

package/src/charts/kinds/Heatmap.tsx

@@ -53,7 +53,7 @@ export type HeatmapProps<T> = {
   renderTooltip?: (cell: HeatmapCell) => ReactNode
   /** Optional gradient legend strip below the grid (faint → solid color). */
   legend?: { min: string; max: string }
-  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean

package/src/charts/kinds/MultiLine.tsx

@@ -52,7 +52,7 @@ export type MultiLineProps<T> = {
   /** Legend config forwarded to `CartesianChart`; `false` disables the legend (sparkline escape).
    * Default `{ placement: 'bottom' }`. */
   legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded to `CartesianChart` as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded to `CartesianChart` as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean

package/src/charts/kinds/StackedArea.tsx

@@ -33,7 +33,7 @@ export type StackedAreaProps<T> = {
   /** Legend config forwarded to `CartesianChart`; `false` disables the legend (sparkline escape).
    * Default `{ placement: 'bottom' }`. */
   legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean

package/src/charts/kinds/ZonedLine.tsx

@@ -73,7 +73,7 @@ export type ZonedLineProps<T> = {
   /** Legend config forwarded to `CartesianChart`; `false` disables the legend (sparkline escape).
    * Default `{ placement: 'bottom' }`. */
   legend?: ChartLegendConfig | false
-  /** Accessible text alternative, forwarded to `CartesianChart` as `aria-label` (+ `role="img"`). */
+  /** Accessible text alternative, forwarded to `CartesianChart` as `aria-label` (+ `role="group"`). */
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean