basalt-ui 1.20.0 → 1.21.0

package/dist/guard/index.js

@@ -54,6 +54,38 @@ const INLINE_SPACING = new RegExp(
   "g"
 );
 const MICRO_SPACING_CEILING_PX = 10;
+const STYLE_ATTRIBUTE_OPENER = /\b(?:style|styles|sx|css)\s*=\s*\{?\s*$/;
+const OBJECT_DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::([^=]*))?=\s*$/;
+const STYLE_OBJECT_NAME = /(?:Style|Styles|Css)$|^(?:style|styles|css|sx)$/;
+const STYLE_OBJECT_TYPE = /\bCSS(?:Properties|Object)\b|\bStyle(?:s|Prop)?\b/;
+const STYLE_BOUND_IDENTIFIER = /\b(?:style|styles|sx|css)=\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+const NESTED_OBJECT_KEY = /(?:[\w$]+|'[^']*'|"[^"]*"|\[[^\]]*\])\s*:\s*$/;
+const MAX_STYLE_CONTEXT_SCAN = 4e3;
+function isStyleObjectContext(codeText, at, styleIdentifiers) {
+  let depth = 0;
+  const stop = Math.max(0, at - MAX_STYLE_CONTEXT_SCAN);
+  for (let i = at - 1; i >= stop; i--) {
+    const ch = codeText[i];
+    if (ch === "}") depth++;
+    else if (ch === "{") {
+      if (depth > 0) {
+        depth--;
+        continue;
+      }
+      const before = codeText.slice(Math.max(0, i - 120), i);
+      if (STYLE_ATTRIBUTE_OPENER.test(before)) return true;
+      const declaration = OBJECT_DECLARATION.exec(before);
+      if (declaration !== null) {
+        const [, name = "", annotation = ""] = declaration;
+        return STYLE_OBJECT_NAME.test(name) || STYLE_OBJECT_TYPE.test(annotation) || styleIdentifiers.has(name);
+      }
+      if (before.endsWith("{")) continue;
+      if (NESTED_OBJECT_KEY.test(before)) continue;
+      return false;
+    }
+  }
+  return false;
+}
 const ROOT_FONT_SIZE_PX = 16;
 function isSubScaleCssSpacing(line, matchIndex) {
   const colon = line.indexOf(":", matchIndex);
@@ -129,13 +161,52 @@ const EXEMPT_RULE_ALIASES = {
   "surface-shadow-override": "raw-surface",
   "css-raw-surface": "raw-surface"
 };
+function normalizeExemptPattern(pattern) {
+  return pattern.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function exemptGlobToRegExp(pattern) {
+  const body = pattern.split(/(\*\*\/|\*\*|\*|\?)/).map((part) => {
+    if (part === "**/") return "(?:.*/)?";
+    if (part === "**") return ".*";
+    if (part === "*") return "[^/]*";
+    if (part === "?") return "[^/]";
+    return part.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${body}$`);
+}
+function exemptPatternMatches(pattern, relPath) {
+  const p = normalizeExemptPattern(pattern);
+  if (p === "") return false;
+  if (relPath === p || relPath.startsWith(`${p}/`)) return true;
+  if (/[*?]/.test(p)) {
+    const re = exemptGlobToRegExp(p);
+    if (re.test(relPath)) return true;
+    if (!p.includes("/") && re.test(relPath.split("/").pop() ?? "")) return true;
+    return false;
+  }
+  return !p.includes("/") && relPath.split("/").includes(p);
+}
 function isRuleExempt(kind, relPath, exemptRules) {
   const alias = EXEMPT_RULE_ALIASES[kind];
   if (alias !== void 0 && isRuleExempt(alias, relPath, exemptRules)) return true;
   const patterns = exemptRules?.[kind];
   if (patterns === void 0 || patterns.length === 0) return false;
-  const segments = relPath.split("/");
-  return patterns.some((pattern) => segments.includes(pattern.replace(/\/$/, "")));
+  return patterns.some((pattern) => exemptPatternMatches(pattern, relPath));
+}
+function unmatchedExemptPatterns(cfg, scannedRelPaths) {
+  const out = [];
+  for (const [kind, patterns] of Object.entries(cfg.exemptRules ?? {})) {
+    const known = Object.hasOwn(GUARD_RULES, kind);
+    for (const pattern of patterns ?? []) {
+      if (!known) {
+        out.push({ kind, pattern, reason: "unknown-kind" });
+        continue;
+      }
+      if (scannedRelPaths.some((relPath) => exemptPatternMatches(pattern, relPath))) continue;
+      out.push({ kind, pattern, reason: "no-match" });
+    }
+  }
+  return out;
 }
 const PLUGIN_RULE_IDS = /* @__PURE__ */ new Set([
   "no-raw-font-size",
@@ -157,7 +228,7 @@ const PLUGIN_RULE_IDS = /* @__PURE__ */ new Set([
   "ai-sdk-major"
 ]);
 const MIN_ALLOW_REASON_LENGTH = 4;
-function parseAllowAnnotation(rest) {
+function parseAllowAnnotation(rest, scope) {
   const rules = [];
   const unknownRules = [];
   let remainder = rest.replace(/^[\s,]+/, "");
@@ -176,51 +247,87 @@ function parseAllowAnnotation(rest) {
     inIdSlot = /^\s*,/.test(after);
   }
   const reason = remainder.replace(/^(?:—|–|-{1,2}|:)\s*/, "").trim();
-  return { rules, unknownRules, hasReason: reason.length >= MIN_ALLOW_REASON_LENGTH };
+  return { rules, unknownRules, hasReason: reason.length >= MIN_ALLOW_REASON_LENGTH, scope };
 }
 const MAX_CSS_CONTINUATION_LINES = 8;
+const MAX_COMMENT_BLOCK_LINES = 8;
 const COMMENT_OPENER_BEFORE = /(?:\/\/|\/\*|<!--)\s*$/;
 const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/;
 const ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/;
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function allowTokenRe(allowComment) {
+  return new RegExp(`${escapeRegExp(allowComment)}(-file)?(?![\\w-])`, "g");
+}
+function jsonAllowKeyRe(allowComment) {
+  return new RegExp(`"basalt:${escapeRegExp(allowComment)}(-file)?"\\s*:\\s*"([^"]*)"`, "g");
+}
 function collectAllowAnnotations(lines, codeLines, allowComment, syntax) {
   const byLine = /* @__PURE__ */ new Map();
+  const fileScoped = [];
   const declared = [];
   const add = (index, annotation) => {
     const list = byLine.get(index) ?? [];
     list.push(annotation);
     byLine.set(index, list);
   };
+  const record = (index, annotation, trailing) => {
+    declared.push({ line: index + 1, annotation });
+    if (annotation.scope === "file") {
+      fileScoped.push(annotation);
+      return;
+    }
+    add(index, annotation);
+    if (!trailing) {
+      for (let ahead = 1; ahead <= MAX_COMMENT_BLOCK_LINES; ahead++) {
+        const raw = lines[index + ahead] ?? "";
+        add(index + ahead, annotation);
+        if (raw.trim() !== "" && (codeLines[index + ahead] ?? "").trim() !== "") break;
+        if (raw.trim() === "") break;
+      }
+      return;
+    }
+    if (syntax !== "css") return;
+    for (let back = 1; back <= MAX_CSS_CONTINUATION_LINES; back++) {
+      const previous = (codeLines[index - back] ?? "").trim();
+      if (previous === "" || /[;{}]$/.test(previous)) break;
+      add(index - back, annotation);
+    }
+  };
+  const token = allowTokenRe(allowComment);
+  const jsonKey = jsonAllowKeyRe(allowComment);
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i] ?? "";
     const stripped = codeLines[i] ?? "";
     const isCommentOnlyLine = stripped.trim() === "" || COMMENT_ONLY_LINE.test(line);
-    let from = 0;
-    for (; ; ) {
-      const at = line.indexOf(allowComment, from);
-      if (at === -1) break;
-      from = at + allowComment.length;
-      if (stripped[at] !== " " && !COMMENT_OPENER_BEFORE.test(line.slice(0, at))) continue;
-      const annotation = parseAllowAnnotation(line.slice(from));
-      if (ANNOTATION_PREFIX.test(line.slice(0, at))) declared.push({ line: i + 1, annotation });
-      add(i, annotation);
-      if (isCommentOnlyLine) {
-        add(i + 1, annotation);
-        continue;
-      }
-      if (syntax !== "css") continue;
-      for (let back = 1; back <= MAX_CSS_CONTINUATION_LINES; back++) {
-        const previous = (codeLines[i - back] ?? "").trim();
-        if (previous === "" || /[;{}]$/.test(previous)) break;
-        add(i - back, annotation);
+    if (syntax === "markup") {
+      for (const m of line.matchAll(jsonKey)) {
+        record(i, parseAllowAnnotation(m[2] ?? "", m[1] === void 0 ? "line" : "file"), false);
       }
     }
+    for (const m of line.matchAll(token)) {
+      const at = m.index;
+      const before = line.slice(0, at);
+      if (stripped[at] !== " " && !COMMENT_OPENER_BEFORE.test(before)) continue;
+      if (!ANNOTATION_PREFIX.test(before)) continue;
+      const rest = line.slice(at + m[0].length);
+      record(
+        i,
+        parseAllowAnnotation(rest, m[1] === void 0 ? "line" : "file"),
+        !isCommentOnlyLine
+      );
+    }
   }
-  return { waivers: byLine, declared };
+  return { waivers: byLine, fileScoped, declared };
+}
+function annotationCovers(annotation, kind) {
+  if (annotation.rules.includes(kind)) return true;
+  if (annotation.scope === "file") return false;
+  return annotation.rules.length === 0 && annotation.unknownRules.length === 0;
 }
 function annotationsCover(annotations, kind) {
-  return (annotations ?? []).some(
-    (a) => a.rules.length === 0 && a.unknownRules.length === 0 || a.rules.includes(kind)
-  );
+  return (annotations ?? []).some((a) => annotationCovers(a, kind));
 }
 function guardSyntaxFor(relPath) {
   if (relPath.endsWith(".css")) return "css";
@@ -606,14 +713,14 @@ const GUARD_RULES = {
     kind: "theme-allow-unscoped",
     pattern: /theme-allow/,
     // handled inline (annotation pass); entry keeps the registry complete
-    message: "theme-allow without a usable rule id and a reason. Write `theme-allow <rule-id> \u2014 <why>`: the id scopes the exception to that one kind (a bare comment waives EVERY kind on the line, including ones added later), and the reason is what makes it reviewable in a diff. An id that names no rule is a typo, not a blanket waiver \u2014 it suppresses nothing."
+    message: "theme-allow without a usable rule id and a reason. Write `theme-allow <rule-id> \u2014 <why>`: the id scopes the exception to that one kind (a bare comment waives EVERY kind on the line, including ones added later), and the reason is what makes it reviewable in a diff. An id that names no rule is a typo, not a blanket waiver \u2014 it suppresses nothing. `theme-allow-file <rule-id> \u2014 <why>` declares the whole file, and must name its ids: a bare one waives nothing."
   },
   "surface-shadow-override": {
     kind: "surface-shadow-override",
     pattern: SHADOW_DECL,
     // handled inline (value is judged, not just matched)
     enabled: (cfg) => cfg.rawSurface,
-    message: "Token-composed boxShadow that REPLACES card depth \u2014 a card whose shadow drops --vx-shadow-card is the one card in the app with no depth. Compose with it (`${VX.shadowCard}, <your ring>`) rather than instead of it."
+    message: "Token-composed boxShadow that REPLACES surface depth \u2014 a card whose shadow drops --vx-shadow-card is the one card in the app with no depth. Compose with the depth token for its tier (`${VX.shadowCard}, <your ring>`; a fixed/floating surface wants --vx-shadow-overlay) rather than instead of it."
   },
   "css-raw-surface": {
     kind: "css-raw-surface",
@@ -638,6 +745,19 @@ const GUARD_RULES = {
     message: "Raw font-size literal \u2014 route through VX.text.* (numbers) / --vx-text-* (CSS), or the Mantine fz token. Same rule the oxlint plugin enforces as basalt/no-raw-font-size; this is the half a check-theme-only CI can see."
   }
 };
+function guardKindRemedy(kind) {
+  return `${kind}: ${GUARD_RULES[kind].message}`;
+}
+const JSON_FAMILY_FILE = /\.(?:webmanifest|json)$/;
+function guardWaiverHint(relPath) {
+  if (relPath.endsWith(".webmanifest")) {
+    return 'A manifest cannot reference a CSS variable, so a hex here is a hand-copy that drifts: let basaltAppPlugin emit it (`manifest: { \u2026 }` in vite.config.ts) instead of hand-writing it. For a manifest basalt does not generate, declare the exception with a `"basalt:theme-allow-file": "raw-hex \u2014 <why>"` member.';
+  }
+  if (JSON_FAMILY_FILE.test(relPath)) {
+    return 'JSON has no comments \u2014 declare a deliberate exception with a `"basalt:theme-allow-file": "<rule-id> \u2014 <why>"` member.';
+  }
+  return "Add a `theme-allow <rule-id> \u2014 <why>` comment for a deliberate exception (`theme-allow-file` declares the whole file).";
+}
 function ruleApplies(kind, relPath) {
   const appliesTo = GUARD_RULES[kind].appliesTo;
   return appliesTo === void 0 || appliesTo(relPath);
@@ -655,8 +775,19 @@ function checkSource(text, relPath, cfg) {
   const syntax = guardSyntaxFor(relPath);
   const codeText = syntax === "markup" ? stripMarkupComments(text) : stripComments(text, syntax);
   const codeLines = codeText.split("\n");
-  const { waivers, declared } = collectAllowAnnotations(lines, codeLines, cfg.allowComment, syntax);
-  const isAllowed = (line, kind) => annotationsCover(waivers.get(line - 1), kind);
+  const { waivers, fileScoped, declared } = collectAllowAnnotations(
+    lines,
+    codeLines,
+    cfg.allowComment,
+    syntax
+  );
+  const fileWaived = /* @__PURE__ */ new Set();
+  for (const annotation of fileScoped) {
+    for (const rule of annotation.rules) {
+      if (Object.hasOwn(GUARD_RULES, rule)) fileWaived.add(rule);
+    }
+  }
+  const isAllowed = (line, kind) => fileWaived.has(kind) || annotationsCover(waivers.get(line - 1), kind);
   const isAllowedInRange = (start, end, kind) => {
     for (let n = start; n <= end; n++) if (isAllowed(n, kind)) return true;
     return false;
@@ -678,6 +809,14 @@ function checkSource(text, relPath, cfg) {
     });
   }
   const rawHtmlLayoutLines = /* @__PURE__ */ new Set();
+  const lineStarts = [];
+  for (let n = 0, i = 0; i < codeLines.length; i++) {
+    lineStarts.push(n);
+    n += (codeLines[i] ?? "").length + 1;
+  }
+  const styleIdentifiers = new Set(
+    [...codeText.matchAll(STYLE_BOUND_IDENTIFIER)].map((m) => m[1] ?? "")
+  );
   for (let i = 0; i < lines.length; i++) {
     const line = codeLines[i] ?? "";
     for (const m of line.matchAll(GUARD_RULES["raw-hex"].pattern)) {
@@ -751,6 +890,9 @@ function checkSource(text, relPath, cfg) {
     if (GUARD_RULES["inline-spacing"].enabled(cfg)) {
       for (const m of line.matchAll(GUARD_RULES["inline-spacing"].pattern)) {
         if (syntax === "css" && isSubScaleCssSpacing(line, m.index)) continue;
+        const hasUnit = /^[a-z%]/.test(line.slice(m.index + m[0].length));
+        if (syntax === "ts" && !hasUnit && !isStyleObjectContext(codeText, lineStarts[i] + m.index, styleIdentifiers))
+          continue;
         push("inline-spacing", i + 1, m[0]);
       }
     }
@@ -860,5 +1002,8 @@ export {
   GENERATED_HEADER_LINE,
   GUARD_RULES,
   TOKENS_ONLY_DISABLED_KINDS,
-  checkSource
+  checkSource,
+  guardKindRemedy,
+  guardWaiverHint,
+  unmatchedExemptPatterns
 };

package/dist/router-tanstack/multi-search-param-store.d.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`.
  *
@@ -73,6 +74,18 @@ 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[];
+    };
 };
 export declare function createMultiSearchParamStore<const T extends string, const P extends string>(opts: MultiSearchParamStoreOptions<T, P>): MultiSearchParamStore<T, P>;
 //# sourceMappingURL=multi-search-param-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"multi-search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/multi-search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAA;IACR,0FAA0F;IAC1F,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,SAAS,CAAC,EAAE,CAAA;IACvB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC/E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;IAC/E;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,CAAA;IACrE,0EAA0E;IAC1E,UAAU,EAAE,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,CAAA;CACtC,CAAA;AAID,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACxF,IAAI,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAoC7B"}
+{"version":3,"file":"multi-search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/multi-search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAMH,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACtF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAA;IACR,0FAA0F;IAC1F,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,SAAS,CAAC,EAAE,CAAA;IACvB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC/E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;IAC/E;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,CAAA;IACrE,0EAA0E;IAC1E,UAAU,EAAE,MAAM,SAAS,CAAC,EAAE,GAAG,IAAI,CAAA;IACrC;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE;KAAE,CAAA;CAC7C,CAAA;AAID,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACxF,IAAI,EAAE,4BAA4B,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAwC7B"}

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

@@ -16,6 +16,9 @@ function createMultiSearchParamStore(opts) {
     if (!Array.isArray(raw)) return null;
     return normalize(raw);
   };
+  const linkSearch = () => {
+    return { [opts.param]: readStored() ?? fallback };
+  };
   const validateSearch = (search) => {
     const fromUrl = normalize(search[opts.param]);
     if (fromUrl.length > 0) {
@@ -28,7 +31,7 @@ function createMultiSearchParamStore(opts) {
     version,
     initial: fallback
   });
-  return { validateSearch, useStore, readStored };
+  return { validateSearch, useStore, readStored, linkSearch };
 }
 export {
   createMultiSearchParamStore

package/dist/router-tanstack/search-param-store.d.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
@@ -97,6 +111,16 @@ 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;
+    };
 };
 export declare function createSearchParamStore<const T extends string, const P extends string>(opts: SearchParamStoreOptions<T, P>): SearchParamStore<T, P>;
 //# sourceMappingURL=search-param-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAMH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CAC3B,CAAA;AAID,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAyBxB"}
+{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAMH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;CAClC,CAAA;AAgCD,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAyDxB"}

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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"}