basalt-ui 1.24.0 → 1.26.0

package/dist/state.js

@@ -1,124 +1,18 @@
-import { useSyncExternalStore } from "react";
-const noopSubscribe = (_cb) => () => {
-};
-function subscribeOnline(cb) {
-  window.addEventListener("online", cb);
-  window.addEventListener("offline", cb);
-  return () => {
-    window.removeEventListener("online", cb);
-    window.removeEventListener("offline", cb);
-  };
-}
-const getOnlineSnapshot = () => navigator.onLine;
-const getOnlineServerSnapshot = () => true;
-const isOnlineServer = typeof window === "undefined";
-function useOnlineStatus() {
-  return useSyncExternalStore(
-    isOnlineServer ? noopSubscribe : subscribeOnline,
-    isOnlineServer ? getOnlineServerSnapshot : getOnlineSnapshot,
-    getOnlineServerSnapshot
-  );
-}
-function isEnvelope(raw) {
-  return typeof raw === "object" && raw !== null && "v" in raw && typeof raw["v"] === "number" && "value" in raw;
-}
-function parseStorage(raw, opts) {
-  if (raw === null) return opts.initial;
-  try {
-    const parsed = JSON.parse(raw);
-    if (!isEnvelope(parsed)) return opts.initial;
-    let value = parsed.value;
-    if (parsed.v !== opts.version) {
-      value = opts.migrate ? opts.migrate(parsed.value, parsed.v) : opts.initial;
-    }
-    if (opts.schema) {
-      const result = opts.schema["~standard"].validate(value);
-      if (result instanceof Promise) return opts.initial;
-      if (result.issues !== void 0) return opts.initial;
-      return result.value;
-    }
-    return value;
-  } catch {
-    return opts.initial;
-  }
-}
-function writeStorage(opts, next) {
-  const storageKey = `basalt:${opts.key}`;
-  try {
-    const envelope = { v: opts.version, value: next };
-    window.localStorage.setItem(storageKey, JSON.stringify(envelope));
-  } catch {
-  }
-}
-function createPersistedState(opts) {
-  const storageKey = `basalt:${opts.key}`;
-  const listeners = /* @__PURE__ */ new Set();
-  let storageHandler = null;
-  const subscribe = (cb) => {
-    listeners.add(cb);
-    if (storageHandler === null) {
-      storageHandler = (e) => {
-        if (e.key === storageKey) {
-          for (const listener of listeners) listener();
-        }
-      };
-      window.addEventListener("storage", storageHandler);
-    }
-    return () => {
-      listeners.delete(cb);
-      if (listeners.size === 0 && storageHandler !== null) {
-        window.removeEventListener("storage", storageHandler);
-        storageHandler = null;
-      }
-    };
-  };
-  let cachedRaw = null;
-  let cachedValue = opts.initial;
-  let primed = false;
-  const getSnapshot = () => {
-    let raw;
-    try {
-      raw = window.localStorage.getItem(storageKey);
-    } catch {
-      raw = null;
-    }
-    if (primed && raw === cachedRaw) return cachedValue;
-    cachedRaw = raw;
-    cachedValue = parseStorage(raw, opts);
-    primed = true;
-    return cachedValue;
-  };
-  const getServerSnapshot = () => opts.initial;
-  const setState = (next) => {
-    writeStorage(opts, next);
-    for (const cb of listeners) cb();
-  };
-  const isServer = typeof window === "undefined";
-  return function usePersistedState() {
-    const value = useSyncExternalStore(
-      // SSR guard — subscribe must not reference `window` on the server.
-      isServer ? noopSubscribe : subscribe,
-      isServer ? getServerSnapshot : getSnapshot,
-      getServerSnapshot
-    );
-    return [value, setState];
-  };
-}
-function readPersistedValue(key, version) {
-  const storageKey = `basalt:${key}`;
-  try {
-    const raw = localStorage.getItem(storageKey);
-    if (raw === null) return null;
-    const envelope = JSON.parse(raw);
-    if (!isEnvelope(envelope)) return null;
-    if (version !== void 0 && envelope.v !== version) return null;
-    return envelope.value;
-  } catch {
-    return null;
-  }
-}
+import {
+  createPersistedState,
+  readPersistedValue
+} from "./state/persisted.js";
+import {
+  field,
+  createLocalStore,
+  resolveFieldCodec,
+  createStoreCore
+} from "./state/fields.js";
 export {
+  createLocalStore,
   createPersistedState,
+  createStoreCore,
+  field,
   readPersistedValue,
-  useOnlineStatus
+  resolveFieldCodec
 };

package/dist/styles.css

@@ -68,6 +68,19 @@
     font-size: max(16px, var(--input-fz, 1rem)) !important;
   }
 
+  /* `data-numeric` — one typographic law, every element. A number read as a MEASUREMENT (a preset
+     like `7d`/`30d`, a KPI value, a table cell, a count tag) is mono with tabular figures, so
+     digits line up column-wise and a changing value does not reflow its neighbours. Declared here,
+     unscoped, because the attribute is the contract: `theme/segmented-control.module.css` and
+     `controls/controls.module.css` were each carrying their own copy, which is why a plain
+     `<Text data-numeric>` in a consumer silently rendered in the sans face. Those two module rules
+     STAY — they additionally set `font-size` for their own component, which is a component
+     decision, not a law. */
+  [data-numeric] {
+    font-family: var(--basalt-font-mono);
+    font-variant-numeric: tabular-nums;
+  }
+
   /* Focus ring = the accent as INK, not as a fill. Mantine hardcodes the ring to
      `var(--mantine-primary-color-filled)` — the SURFACE token, which is deliberately deep in both
      schemes so a white label sits on it (see ACCENT in tokens/palette.ts). A ring is read against

package/dist/surfaces.d.ts

@@ -6,13 +6,35 @@
  * RULE_NAMES: derived projection — the deduped set of doctrine rule names (PROJECTION 1).
  */
 import type { GuardKind } from './guard/types.js';
-/** The 13 on-disk rule names (agent/rules/basalt-{name}.md — the set-equality target).
+/** The 6 on-disk rule names (agent/rules/basalt-{name}.md — the set-equality target).
+ *
+ * One rule file per DOCTRINE, not per subpath: `state` also owns the router bridge's placement law
+ * (the two were one argument split across two files), and `batteries` owns every adapter surface
+ * whose doctrine is "use the shipped thing" — query, forms, notifications, commands, data, content,
+ * agent and the app-global layer. Thirteen files carried 4,177 lines, 55% of it with no guard
+ * behind it and the identity paragraph restated six times (`docs/CONTROLS-SPEC.md` §7).
  *
  * @example
  * const r: RuleName = 'tokens' // ok
  * // const bad: RuleName = 'overlays' // tsc error — not in the union
  */
-export type RuleName = 'tokens' | 'charts' | 'mantine' | 'router' | 'query' | 'state' | 'forms' | 'notifications' | 'commands' | 'data' | 'agent' | 'content' | 'app';
+export type RuleName = 'tokens' | 'charts' | 'mantine' | 'state' | 'controls' | 'batteries';
+/**
+ * Every rule the shipped oxlint JS plugin registers (`configs/oxlint-plugin.js` → `rules`), as one
+ * literal union AND one runtime list — the type and the list are the same declaration, so they
+ * cannot drift from each other. What they CAN drift from is the plugin itself, which this module
+ * must not import (it is a standalone `.js` loaded through `jsPlugins` out of a consumer's
+ * node_modules, and `surfaces.ts` is dependency-free by contract). `oxlint-plugin.test.ts` closes
+ * that gap: it asserts this list is EXACTLY the plugin's own rule keys, and `check-coverage`
+ * asserts every id here maps to exactly one surface.
+ *
+ * @example
+ * const id: PluginRuleId = 'hand-rolled-filter' // ok
+ * // const bad: PluginRuleId = 'hand-rolled-filters' // tsc error
+ */
+export declare const PLUGIN_RULE_ID_LIST: readonly ["no-raw-font-size", "raw-size-literal", "card-inset", "chart-in-raw-surface", "hand-rolled-plot", "chart-legend-literal", "shadow-basalt-export", "hand-rolled-shell", "raw-scroll-container", "hand-rolled-filter", "control-outside-home", "control-size-literal", "page-bar-budget", "in-body-page-title", "responsive-twin", "search-literal-link", "use-search-from-literal", "visx-boundary", "visx-tooltip", "token-layer-boundary", "agent-resume-guard", "agent-no-raw-usechat", "ai-sdk-major"];
+/** One registered oxlint plugin rule id — the literal union of {@link PLUGIN_RULE_ID_LIST}. */
+export type PluginRuleId = (typeof PLUGIN_RULE_ID_LIST)[number];
 /** The 3 shipped skill names (agent/skills/basalt-{name}/SKILL.md, placed into a consumer's
  * .claude/skills/ by `basalt-ui init`/`sync` — the same managed path the rules take).
  *
@@ -88,15 +110,33 @@ type BaseSurface = {
  *
  * @example
  * const s: DoctrineSpec = { kind: 'doctrine', layer: 'headless', rule: 'tokens',
- *   skill: ['basalt-design'], guardKinds: ['raw-hex'], forbiddenImports: [] }
+ *   skill: ['basalt-design'], guardKinds: ['raw-hex'], pluginRules: ['no-raw-font-size'],
+ *   forbiddenImports: [] }
  */
 export type DoctrineSpec = BaseSurface & {
     readonly kind: 'doctrine';
     readonly rule: RuleName;
     /** A LIST (skill↔surface is many-to-one — basalt-design covers tokens AND mantine AND state). */
     readonly skill: readonly SkillName[];
-    /** Required, but [] is legal for advisory surfaces (router/query: rule only, no guard). */
+    /** Required, but [] is legal for advisory surfaces (the batteries: rule only, no guard). */
     readonly guardKinds: readonly GuardKind[];
+    /**
+     * The oxlint plugin rules this surface's doctrine is enforced by — the AST half of the same seam
+     * `guardKinds` covers with text scans. Required (`[]` is legal, and says "no AST rule guards
+     * this"), because the ABSENCE of the field is what let the generated coverage headers claim a
+     * rule was "backed by" a guard kind while the plugin rule doing the real work went unnamed (D8).
+     *
+     * Every id in {@link PLUGIN_RULE_ID_LIST} maps to EXACTLY ONE surface — asserted by
+     * `check-coverage` and by `oxlint-plugin.test.ts`, so a new plugin rule cannot ship without a
+     * home, and one rule cannot be counted as coverage for two surfaces.
+     */
+    readonly pluginRules: readonly PluginRuleId[];
+    /**
+     * Laws this surface states but nothing enforces — printed under `not guarded:` in the generated
+     * `<!-- basalt:coverage -->` header. The honest half of the block: claiming coverage that does
+     * not exist is D8, and the only way a reader can tell is if the doc says so itself.
+     */
+    readonly advisoryLaws?: readonly string[];
 };
 /**
  * A tooling surface owes NO triad — these fields are statically ABSENT (cannot be set).
@@ -111,6 +151,8 @@ export type ToolingSpec = BaseSurface & {
     readonly rule?: never;
     readonly skill?: never;
     readonly guardKinds?: never;
+    readonly pluginRules?: never;
+    readonly advisoryLaws?: never;
 };
 /** The discriminated union — the SURFACES registry value type. */
 export type SurfaceSpec = DoctrineSpec | ToolingSpec;
@@ -130,8 +172,9 @@ export declare const SURFACES: {
         readonly layer: "mantine-coupled";
         readonly rule: "mantine";
         readonly skill: readonly ["basalt-app", "basalt-design"];
-        readonly guardKinds: readonly ["raw-motion-value", "card-with-border", "raw-form-control", "sub-16-input-font", "mantine-shade-index"];
-        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)";
+        readonly guardKinds: readonly ["raw-motion-value", "card-with-border", "raw-form-control", "sub-16-input-font", "mantine-shade-index", "in-body-page-title", "raw-spacing", "inline-spacing", "inline-display", "raw-html-layout", "hidden-inline-style"];
+        readonly pluginRules: readonly ["hand-rolled-shell", "card-inset", "in-body-page-title", "raw-scroll-container", "page-bar-budget", "shadow-basalt-export"];
+        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)";
         readonly optionalPeers: readonly ["react-markdown", "remark-gfm", "rehype-sanitize", "remend", "shiki", "beautiful-mermaid"];
         readonly forbiddenImports: readonly [];
     };
@@ -140,7 +183,8 @@ export declare const SURFACES: {
         readonly layer: "headless";
         readonly rule: "charts";
         readonly skill: readonly ["basalt-charts"];
-        readonly guardKinds: readonly ["raw-hex", "raw-color-fn", "raw-visx-axis", "unframed-chart"];
+        readonly guardKinds: readonly ["raw-hex", "raw-color-fn", "raw-visx-axis", "unframed-chart", "chart-missing-aria-label"];
+        readonly pluginRules: readonly ["hand-rolled-plot", "chart-legend-literal", "chart-in-raw-surface", "visx-boundary", "visx-tooltip"];
         readonly description: "CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)";
         readonly globs: {
             readonly shipped: readonly ["**/charts/**"];
@@ -158,7 +202,8 @@ export declare const SURFACES: {
         readonly layer: "headless";
         readonly rule: "tokens";
         readonly skill: readonly ["basalt-design", "basalt-charts"];
-        readonly guardKinds: readonly ["raw-hex", "raw-color-fn", "off-identity-accent", "off-system-surface-var"];
+        readonly guardKinds: readonly ["raw-hex", "raw-color-fn", "off-identity-accent", "off-system-surface-var", "raw-font-family", "raw-radius", "raw-surface", "inline-font-size", "css-raw-surface", "surface-shadow-override", "theme-allow-unscoped"];
+        readonly pluginRules: readonly ["no-raw-font-size", "raw-size-literal", "token-layer-boundary"];
         readonly description: "VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)";
         readonly globs: {
             readonly shipped: readonly ["**/tokens/**"];
@@ -192,9 +237,10 @@ export declare const SURFACES: {
     readonly './query': {
         readonly kind: "doctrine";
         readonly layer: "headless";
-        readonly rule: "query";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools";
         readonly optionalPeers: readonly ["@tanstack/react-query-devtools"];
         readonly globs: {
@@ -206,10 +252,11 @@ export declare const SURFACES: {
     readonly './router-tanstack': {
         readonly kind: "doctrine";
         readonly layer: "headless";
-        readonly rule: "router";
+        readonly rule: "state";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
-        readonly description: "TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)";
+        readonly pluginRules: readonly ["search-literal-link", "use-search-from-literal"];
+        readonly description: "TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; deprecated createSearchParamStore/createMultiSearchParamStore wrappers until 1.29.0)";
         readonly optionalPeers: readonly ["@tanstack/react-router"];
         readonly globs: {
             readonly shipped: readonly [];
@@ -220,9 +267,10 @@ export declare const SURFACES: {
     readonly './forms': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "forms";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)";
         readonly optionalPeers: readonly ["@mantine/form"];
         readonly forbiddenImports: readonly [];
@@ -230,9 +278,10 @@ export declare const SURFACES: {
     readonly './notifications': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "notifications";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter";
         readonly optionalPeers: readonly ["@mantine/notifications"];
         readonly forbiddenImports: readonly [];
@@ -240,9 +289,10 @@ export declare const SURFACES: {
     readonly './commands': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "commands";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays";
         readonly optionalPeers: readonly ["@mantine/spotlight", "@mantine/modals", "@tanstack/react-hotkeys"];
         readonly forbiddenImports: readonly [];
@@ -250,9 +300,10 @@ export declare const SURFACES: {
     readonly './data': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "data";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in";
         readonly optionalPeers: readonly ["@tanstack/react-table", "@tanstack/react-virtual"];
         readonly forbiddenImports: readonly [];
@@ -260,9 +311,10 @@ export declare const SURFACES: {
     readonly './data/table': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "data";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)";
         readonly optionalPeers: readonly ["@tanstack/react-table"];
         readonly forbiddenImports: readonly [];
@@ -270,9 +322,10 @@ export declare const SURFACES: {
     readonly './data/virtual': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "data";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)";
         readonly optionalPeers: readonly ["@tanstack/react-virtual"];
         readonly forbiddenImports: readonly [];
@@ -280,9 +333,10 @@ export declare const SURFACES: {
     readonly './agent': {
         readonly kind: "doctrine";
         readonly layer: "headless";
-        readonly rule: "agent";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly ["agent-resume-guard", "agent-no-raw-usechat", "ai-sdk-major"];
         readonly description: "Headless streaming-chat layer: useAgentStream, aiSdkTransport (recommended default) + edenTransport, isResumable/ResumableAgentTransport (stream-resumption seam), PartList, coalesceParts, the ForeignPart/definePartRenderers/narrowAgentPart open part-registry seam, plus the multi-thread createThreadsStore + useAgentThreadRuns + outcome-resolver seam (Mantine-free)";
         readonly optionalPeers: readonly ["ai", "use-stick-to-bottom"];
         readonly globs: {
@@ -294,9 +348,10 @@ export declare const SURFACES: {
     readonly './agent-chat': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "agent";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed (variant/renderRow), ThreadFeedRow (inline-expanding Slack row, lazily mounted + kept mounted), ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props, per-message MessageAffordances, groupConsecutive, and an optional virtualize/height windowing mode whose VirtualizeOptions carry overscan/estimateSize/initialScroll — a virtualized transcript opens scrolled to the newest message unless initialScroll is \"start\"), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional — ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without it installed even though peerDependenciesMeta marks it optional (npm has no per-subpath optionality). remend is genuinely optional here — ThreadTranscript reaches it only through the lazy dynamic import() inside content/markdown.tsx, and @tanstack/react-virtual the same way through the lazy import() behind ThreadTranscript virtualize (absent peer degrades to an unwindowed, height-bound pane).";
         readonly optionalPeers: readonly ["ai", "motion", "remend", "use-stick-to-bottom", "react-markdown", "remark-gfm", "shiki", "@shikijs/langs", "@shikijs/themes", "beautiful-mermaid", "@tanstack/react-virtual"];
         readonly forbiddenImports: readonly [];
@@ -304,20 +359,45 @@ export declare const SURFACES: {
     readonly './content': {
         readonly kind: "doctrine";
         readonly layer: "mantine-coupled";
-        readonly rule: "content";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
-        readonly description: "Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers; `streaming` is a rendering mode ONLY — `contentTrust` is the independent security input, and any surface rendering agent/model output must pin `contentTrust=\"untrusted\"`, the sole input to the image-origin allowlist; a `fenceRenderers` registry — settledOnly/FenceRenderer/FenceRenderers/FenceRenderContext; `sanitizeSchema`, an additions-only SanitizeSchemaExtension merged over BASALT_SANITIZE_SCHEMA via mergeSanitizeSchema; the remend streaming-repair pass is now a lazy optional peer), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), ArticleFilterBar (category/tags filter UI), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface";
+        readonly pluginRules: readonly [];
+        readonly description: "Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers; `streaming` is a rendering mode ONLY — `contentTrust` is the independent security input, and any surface rendering agent/model output must pin `contentTrust=\"untrusted\"`, the sole input to the image-origin allowlist; a `fenceRenderers` registry — settledOnly/FenceRenderer/FenceRenderers/FenceRenderContext; `sanitizeSchema`, an additions-only SanitizeSchemaExtension merged over BASALT_SANITIZE_SCHEMA via mergeSanitizeSchema; the remend streaming-repair pass is now a lazy optional peer), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), FilterSet/ViewTabs/MultiSelectFilter re-exported from ./controls (they replaced the controlled ArticleFilterBar), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface";
         readonly optionalPeers: readonly ["shiki", "@shikijs/langs", "@shikijs/themes", "beautiful-mermaid", "react-markdown", "remark-gfm", "rehype-sanitize", "remend", "@mantine/spotlight"];
         readonly forbiddenImports: readonly [];
     };
+    readonly './controls': {
+        readonly kind: "doctrine";
+        readonly layer: "mantine-coupled";
+        readonly rule: "controls";
+        readonly skill: readonly ["basalt-design"];
+        readonly guardKinds: readonly ["raw-selection-control"];
+        readonly pluginRules: readonly ["hand-rolled-filter", "control-outside-home", "control-size-literal", "responsive-twin"];
+        readonly advisoryLaws: readonly ["C1 as a cross-file law (a control placed in one file, its home declared in another)", "hand-rolled section headings (argo writes `<Text fw={600} size=\"sm\">` + children, which no AST heuristic matches without false positives)", "C11 — a table/list stating its count when it is not a BasaltDataTable", "C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy"];
+        readonly description: "The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). Every control owns its own desktop/mobile swap in CSS (C9) and renders size=\"ctl\" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.";
+        readonly optionalPeers: readonly [];
+        readonly forbiddenImports: readonly [];
+    };
+    readonly './controls-dates': {
+        readonly kind: "doctrine";
+        readonly layer: "mantine-coupled";
+        readonly rule: "controls";
+        readonly skill: readonly ["basalt-design"];
+        readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
+        readonly description: "DateRangePicker — the @mantine/dates implementation of RangeFilter's customPicker seam. Its own subpath because @mantine/dates is an optional peer and basaltViteConfig pre-bundles the whole @mantine scope, so a consumer without the peer (linewatch) must never resolve it: nothing under src/controls may import it, statically or lazily (docs/CONTROLS-SPEC.md §3).";
+        readonly optionalPeers: readonly ["@mantine/dates"];
+        readonly forbiddenImports: readonly [];
+    };
     readonly './state': {
         readonly kind: "doctrine";
         readonly layer: "headless";
         readonly rule: "state";
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly ["localstorage-theme"];
-        readonly description: "createPersistedState (versioned localStorage) + useOnlineStatus — Mantine-free state primitives";
+        readonly pluginRules: readonly [];
+        readonly description: "createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store — Mantine-free state primitives";
         readonly optionalPeers: readonly [];
         readonly globs: {
             readonly shipped: readonly [];
@@ -331,6 +411,7 @@ export declare const SURFACES: {
         readonly rule: "mantine";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly description: "ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator — auto-mounted by BasaltProvider";
         readonly optionalPeers: readonly [];
         readonly forbiddenImports: readonly [];
@@ -362,9 +443,10 @@ export declare const SURFACES: {
     readonly '#app': {
         readonly kind: "doctrine";
         readonly layer: "app-global";
-        readonly rule: "app";
+        readonly rule: "batteries";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
+        readonly pluginRules: readonly [];
         readonly globs: {
             readonly shipped: readonly ["**/*.{ts,tsx}"];
             readonly repo: readonly ["packages/basalt-ui/src/**"];
@@ -379,7 +461,7 @@ export declare const SURFACES: {
 };
 /**
  * Derived, deduped set of doctrine rule names. Projection 1 of SURFACES.
- * → ['mantine', 'charts', 'tokens', 'query', 'router', 'forms', 'notifications', 'commands', 'data', 'agent', 'content', 'state', 'app'] (order is insertion order of Set)
+ * → ['mantine', 'charts', 'tokens', 'batteries', 'state', 'controls'] (order is insertion order of Set)
  *
  * @example
  * RULE_NAMES.includes('tokens') // true

package/dist/surfaces.d.ts.map

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