basalt-ui 1.25.0 → 1.27.0

package/dist/surfaces.js

@@ -1,3 +1,28 @@
+const PLUGIN_RULE_ID_LIST = [
+  "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"
+];
 const v = (spec, message, extra) => ({
   spec,
   match: "path",
@@ -27,9 +52,29 @@ const SURFACES = {
       "card-with-border",
       "raw-form-control",
       "sub-16-input-font",
-      "mantine-shade-index"
+      "mantine-shade-index",
+      // The text lane of the kinds whose remedy IS a Mantine primitive or a Mantine-owned prop:
+      // C8's page title (same id as the plugin rule, so one annotation waives both lanes), the
+      // spacing props, and the layout primitives an inline `display`/raw element replaces.
+      "in-body-page-title",
+      "raw-spacing",
+      "inline-spacing",
+      "inline-display",
+      "raw-html-layout",
+      "hidden-inline-style"
+    ],
+    // The chrome half of the plugin: the shell, the card idiom, the page title and the scroll
+    // doctrine. `hand-rolled-shell` sits here rather than on a shell-shaped surface because
+    // `BasaltShell` IS the root barrel's promise (docs/CONTROLS-SPEC.md §6 wave 6).
+    pluginRules: [
+      "hand-rolled-shell",
+      "card-inset",
+      "in-body-page-title",
+      "raw-scroll-container",
+      "page-bar-budget",
+      "shadow-basalt-export"
     ],
-    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)",
+    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)",
     optionalPeers: [
       "react-markdown",
       "remark-gfm",
@@ -46,7 +91,20 @@ const SURFACES = {
     layer: "headless",
     rule: "charts",
     skill: ["basalt-charts"],
-    guardKinds: ["raw-hex", "raw-color-fn", "raw-visx-axis", "unframed-chart"],
+    guardKinds: [
+      "raw-hex",
+      "raw-color-fn",
+      "raw-visx-axis",
+      "unframed-chart",
+      "chart-missing-aria-label"
+    ],
+    pluginRules: [
+      "hand-rolled-plot",
+      "chart-legend-literal",
+      "chart-in-raw-surface",
+      "visx-boundary",
+      "visx-tooltip"
+    ],
     description: "CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)",
     globs: {
       shipped: ["**/charts/**"],
@@ -64,7 +122,28 @@ const SURFACES = {
     layer: "headless",
     rule: "tokens",
     skill: ["basalt-design", "basalt-charts"],
-    guardKinds: ["raw-hex", "raw-color-fn", "off-identity-accent", "off-system-surface-var"],
+    guardKinds: [
+      "raw-hex",
+      "raw-color-fn",
+      "off-identity-accent",
+      "off-system-surface-var",
+      // The rest of the value lane: every kind whose remedy is a `--vx-*` token or a theme knob,
+      // in TSX and in kebab CSS alike.
+      "raw-font-family",
+      "raw-radius",
+      "raw-surface",
+      "inline-font-size",
+      "css-raw-surface",
+      "surface-shadow-override",
+      // Not a token kind — the kind that judges the ANNOTATION rather than the code. It lands here
+      // because `agent/rules/basalt-tokens.md` is where the `theme-allow` grammar is documented
+      // (said once, on purpose), so this is the header that must name its enforcement.
+      "theme-allow-unscoped"
+    ],
+    // The type-scale rules live with the tokens, not with `.`: both police a value that left the
+    // `--vx-*` system, which is this surface's whole subject. `token-layer-boundary` is the
+    // repo-local-only rule that keeps the layer upstream of Mantine (see below).
+    pluginRules: ["no-raw-font-size", "raw-size-literal", "token-layer-boundary"],
     description: "VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)",
     globs: {
       shipped: ["**/tokens/**"],
@@ -102,9 +181,10 @@ const SURFACES = {
   "./query": {
     kind: "doctrine",
     layer: "headless",
-    rule: "query",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     description: "createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools",
     optionalPeers: ["@tanstack/react-query-devtools"],
     globs: {
@@ -117,10 +197,12 @@ const SURFACES = {
   "./router-tanstack": {
     kind: "doctrine",
     layer: "headless",
-    rule: "router",
+    rule: "state",
     skill: ["basalt-app"],
     guardKinds: [],
-    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)",
+    // Law C10 — a nav link's `search` and a reader's `from` are both this bridge's contract.
+    pluginRules: ["search-literal-link", "use-search-from-literal"],
+    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)",
     optionalPeers: ["@tanstack/react-router"],
     globs: {
       shipped: [],
@@ -132,9 +214,10 @@ const SURFACES = {
   "./forms": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "forms",
+    rule: "batteries",
     skill: ["basalt-design"],
     guardKinds: [],
+    pluginRules: [],
     description: "Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)",
     optionalPeers: ["@mantine/form"],
     forbiddenImports: []
@@ -142,9 +225,10 @@ const SURFACES = {
   "./notifications": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "notifications",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     description: "Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter",
     optionalPeers: ["@mantine/notifications"],
     forbiddenImports: []
@@ -152,9 +236,10 @@ const SURFACES = {
   "./commands": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "commands",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     description: "typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays",
     optionalPeers: ["@mantine/spotlight", "@mantine/modals", "@tanstack/react-hotkeys"],
     forbiddenImports: []
@@ -162,9 +247,10 @@ const SURFACES = {
   "./data": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "data",
+    rule: "batteries",
     skill: ["basalt-design"],
     guardKinds: [],
+    pluginRules: [],
     description: "Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) \u2014 prefer ./data/table or ./data/virtual for per-feature opt-in",
     optionalPeers: ["@tanstack/react-table", "@tanstack/react-virtual"],
     forbiddenImports: []
@@ -172,9 +258,10 @@ const SURFACES = {
   "./data/table": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "data",
+    rule: "batteries",
     skill: ["basalt-design"],
     guardKinds: [],
+    pluginRules: [],
     description: "BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)",
     optionalPeers: ["@tanstack/react-table"],
     forbiddenImports: []
@@ -182,9 +269,10 @@ const SURFACES = {
   "./data/virtual": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "data",
+    rule: "batteries",
     skill: ["basalt-design"],
     guardKinds: [],
+    pluginRules: [],
     description: "BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)",
     optionalPeers: ["@tanstack/react-virtual"],
     forbiddenImports: []
@@ -192,9 +280,11 @@ const SURFACES = {
   "./agent": {
     kind: "doctrine",
     layer: "headless",
-    rule: "agent",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    // The three agent-chat correctness rules — they honour `basalt-agent-allow`, not `theme-allow`.
+    pluginRules: ["agent-resume-guard", "agent-no-raw-usechat", "ai-sdk-major"],
     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)",
     optionalPeers: ["ai", "use-stick-to-bottom"],
     globs: {
@@ -207,9 +297,10 @@ const SURFACES = {
   "./agent-chat": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "agent",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     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 \u2014 a virtualized transcript opens scrolled to the newest message unless initialScroll is "start"), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional \u2014 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 \u2014 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).',
     optionalPeers: [
       "ai",
@@ -229,10 +320,11 @@ const SURFACES = {
   "./content": {
     kind: "doctrine",
     layer: "mantine-coupled",
-    rule: "content",
+    rule: "batteries",
     skill: ["basalt-design"],
     guardKinds: [],
-    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 \u2014 `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 \u2014 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) \u2014 the content/prose surface',
+    pluginRules: [],
+    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 \u2014 `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 \u2014 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) \u2014 the content/prose surface',
     optionalPeers: [
       "shiki",
       "@shikijs/langs",
@@ -246,13 +338,55 @@ const SURFACES = {
     ],
     forbiddenImports: []
   },
+  "./controls": {
+    kind: "doctrine",
+    layer: "mantine-coupled",
+    rule: "controls",
+    skill: ["basalt-design"],
+    // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
+    // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
+    guardKinds: ["raw-selection-control"],
+    // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
+    // `responsive-twin` all ship `error`; `control-outside-home` is the one grace entry left in
+    // `PLUGIN_RULE_GRACE`, re-dated to 1.28.0 against the wave-7 measurement (see its `why`).
+    // The budget rules live on `.` with `PageBar` itself.
+    pluginRules: [
+      "hand-rolled-filter",
+      "control-outside-home",
+      "control-size-literal",
+      "responsive-twin"
+    ],
+    // docs/CONTROLS-SPEC.md §6 "Honest coverage" — verbatim, because a generated header claiming
+    // otherwise is D8 again.
+    advisoryLaws: [
+      "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 \u2014 a table/list stating its count when it is not a BasaltDataTable",
+      "C12 \u2014 one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy"
+    ],
+    description: 'The control tier (docs/CONTROLS-SPEC.md \xA73): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle \u2014 no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), 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 \u2014 the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+    optionalPeers: [],
+    forbiddenImports: []
+  },
+  "./controls-dates": {
+    kind: "doctrine",
+    layer: "mantine-coupled",
+    rule: "controls",
+    skill: ["basalt-design"],
+    guardKinds: [],
+    pluginRules: [],
+    description: "DateRangePicker \u2014 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 \xA73).",
+    optionalPeers: ["@mantine/dates"],
+    forbiddenImports: []
+  },
   "./state": {
     kind: "doctrine",
     layer: "headless",
     rule: "state",
     skill: ["basalt-design"],
     guardKinds: ["localstorage-theme"],
-    description: "createPersistedState (versioned localStorage) + useOnlineStatus \u2014 Mantine-free state primitives",
+    pluginRules: [],
+    description: "createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store \u2014 Mantine-free state primitives",
     optionalPeers: [],
     // Consumers import basalt-ui/state from node_modules (lint-ignored), so there is nothing to
     // enforce consumer-side, and a shipped **/state* glob would wrongly hit consumers' own
@@ -270,6 +404,7 @@ const SURFACES = {
     rule: "mantine",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     description: "ConnectivityProvider (aggregates browser online/offline, React Query onlineManager, SSE, and health-check pings into one status), useConnectivity, and ConnectivityIndicator \u2014 auto-mounted by BasaltProvider",
     optionalPeers: [],
     forbiddenImports: []
@@ -304,9 +439,10 @@ const SURFACES = {
     // synthetic global app-wide ban layer — the src/**+app/** glob
     kind: "doctrine",
     layer: "app-global",
-    rule: "app",
+    rule: "batteries",
     skill: ["basalt-app"],
     guardKinds: [],
+    pluginRules: [],
     globs: {
       // Shipped is a catch-all (not just src/**+app/**) so consumer code under components/, lib/,
       // features/, etc. is also covered. The @visx/*-only-in-charts and Mantine-free charts/tokens
@@ -348,6 +484,7 @@ function hasTokenLayerBoundaryRegistered(rules) {
   return rules?.["basalt/token-layer-boundary"] === "error";
 }
 export {
+  PLUGIN_RULE_ID_LIST,
   RULE_NAMES,
   SKILL_NAMES,
   SURFACES,

package/dist/theme/controls.module.css

@@ -204,7 +204,8 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 /*
  * Reduced motion drops the fade, never the shadow: a static shadow is not motion, and removing it
  * would strip the very hierarchy this pass exists to establish from the users who asked for less
- * animation. `subtle`'s hover depth still lands — it just lands instantly.
+ * animation. `default`/`filled`/`light`/`outline`'s hover depth still lands — it just lands
+ * instantly. `subtle` stays flat regardless, as it does in every other state (see above).
  */
 @media (prefers-reduced-motion: reduce) {
   .buttonRoot,
@@ -282,3 +283,17 @@ html[data-mantine-color-scheme] .tabsRoot {
 html .tableRoot {
   --table-border-color: var(--vx-surface-hairline);
 }
+
+/*
+ * The LAST row's separator is dropped — exactly the rule (and exactly the reasoning) the Accordion
+ * above already carries: a separator BETWEEN items is information, and the same line drawn after the
+ * final item is an outer border pretending to be one. It mattered more once `BasaltDataTable`'s
+ * `withTableBorder` went to `false` by default, because the two used to sit on top of each other and
+ * the doubling hid which of them was drawing the line.
+ *
+ * Scoped to `tbody`: a `tfoot` (a totals row) is separated FROM the body by the rule above it, which
+ * is a between rule and stays.
+ */
+html .tableRoot tbody tr:last-of-type {
+  border-bottom: none;
+}

package/dist/theme/ctl-theme.d.ts

@@ -0,0 +1,32 @@
+import type { MantineThemeOverride } from '@mantine/core';
+import type { ReactNode } from 'react';
+/** The `MantineThemeOverride` a `<CtlSlot>` provides — see this module's doc for the merge/
+ * precedence contract. Exported so a consumer composing its own slot (a bespoke home not covered
+ * by `PageBar`/`Section`/the sidebar blocks) can reach the SAME tier without re-declaring it. */
+export declare const CTL_THEME: MantineThemeOverride;
+export type CtlSlotProps = {
+    children: ReactNode;
+    /**
+     * Which tier the slot imposes. `ctl` (the default) is the 30px control tier every home's control
+     * row uses. `widget` is the 24px ActionIcon step a `WidgetHeader tier="widget"` header row can
+     * hold — see {@link WIDGET_THEME} for the misalignment that makes it a separate tier rather than
+     * a caller's `size` prop.
+     *
+     * The values are the TIER names, matching the `data-basalt-tier` attribute the slot emits and the
+     * one `ChartCard` already writes by hand (it lives inside the Mantine-free `charts/` boundary and
+     * so cannot mount this component). `widget` maps to Mantine's `size="icon"`; the two vocabularies
+     * differ and that is upstream's, not basalt's.
+     *
+     * @default 'ctl'
+     */
+    tier?: 'ctl' | 'widget';
+};
+/**
+ * Wrap a home's SLOT (never its body) to render every Mantine control inside it at the `ctl` tier.
+ * The marker is a Mantine `Box` (not a raw `<div>` — `basalt/raw-html-layout` flags inline
+ * layout/surface styling on a bare HTML tag), `display: contents` keeps it out of the slot's own
+ * flex/grid layout while leaving the `data-basalt-tier="ctl"` attribute queryable/testable
+ * (`docs/CONTROLS-SPEC.md` §5) without the wrapper participating in flow.
+ */
+export declare function CtlSlot({ children, tier }: CtlSlotProps): ReactNode;
+//# sourceMappingURL=ctl-theme.d.ts.map

package/dist/theme/ctl-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctl-theme.d.ts","sourceRoot":"","sources":["../../src/theme/ctl-theme.tsx"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAe,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;iGAEiG;AACjG,eAAO,MAAM,SAAS,EAAE,oBAyBvB,CAAA;AA0BD,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;CACxB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAY,EAAE,EAAE,YAAY,GAAG,SAAS,CAQ3E"}

package/dist/theme/ctl-theme.js

@@ -0,0 +1,54 @@
+import { jsx } from "react/jsx-runtime";
+import {
+  ActionIcon,
+  Box,
+  Button,
+  Checkbox,
+  Input,
+  MantineThemeProvider,
+  MultiSelect,
+  NativeSelect,
+  Radio,
+  SegmentedControl,
+  Select,
+  Switch,
+  TextInput
+} from "@mantine/core";
+const CTL_THEME = {
+  components: {
+    Button: Button.extend({ defaultProps: { size: "ctl" } }),
+    ActionIcon: ActionIcon.extend({ defaultProps: { size: "ctl" } }),
+    Input: Input.extend({ defaultProps: { size: "ctl" } }),
+    TextInput: TextInput.extend({ defaultProps: { size: "ctl" } }),
+    Select: Select.extend({ defaultProps: { size: "ctl" } }),
+    MultiSelect: MultiSelect.extend({ defaultProps: { size: "ctl" } }),
+    SegmentedControl: SegmentedControl.extend({ defaultProps: { size: "ctl" } }),
+    NativeSelect: NativeSelect.extend({ defaultProps: { size: "ctl" } }),
+    // The theme keys are the component names Mantine's own `useProps` looks up — `RadioGroup`, not
+    // `Radio.Group` (`RadioGroup.mjs`: `useProps("RadioGroup", …)`).
+    Radio: Radio.extend({ defaultProps: { size: "ctl" } }),
+    // Mantine types `RadioGroup.size` as a CLOSED `MantineSize`, while `Radio`, `Checkbox`,
+    // `Checkbox.Group`, `Switch` and `Switch.Group` all type theirs OPEN
+    // (`MantineSize | (string & {})`) — verified in the installed 9.3.0 `.d.ts` files, so this is an
+    // upstream inconsistency, not a statement that `RadioGroup` cannot take a custom tier. At
+    // runtime `getSize` interpolates the string identically for all six. The cast restores what
+    // every sibling type already allows; it widens nothing.
+    RadioGroup: Radio.Group.extend({ defaultProps: { size: "ctl" } }),
+    Checkbox: Checkbox.extend({ defaultProps: { size: "ctl" } }),
+    CheckboxGroup: Checkbox.Group.extend({ defaultProps: { size: "ctl" } }),
+    Switch: Switch.extend({ defaultProps: { size: "ctl" } }),
+    SwitchGroup: Switch.Group.extend({ defaultProps: { size: "ctl" } })
+  }
+};
+const WIDGET_THEME = {
+  components: {
+    ActionIcon: ActionIcon.extend({ defaultProps: { size: "icon" } })
+  }
+};
+function CtlSlot({ children, tier = "ctl" }) {
+  return /* @__PURE__ */ jsx(MantineThemeProvider, { inherit: true, theme: tier === "widget" ? WIDGET_THEME : CTL_THEME, children: /* @__PURE__ */ jsx(Box, { "data-basalt-tier": tier, style: { display: "contents" }, children }) });
+}
+export {
+  CTL_THEME,
+  CtlSlot
+};

package/dist/theme/ctl-theme.test.d.ts

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

package/dist/theme/ctl-theme.test.d.ts.map

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

package/dist/theme/ctl-tier-coverage.test.d.ts

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

package/dist/theme/ctl-tier-coverage.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctl-tier-coverage.test.d.ts","sourceRoot":"","sources":["../../src/theme/ctl-tier-coverage.test.ts"],"names":[],"mappings":""}

package/dist/theme/divider-law.test.d.ts

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

package/dist/theme/divider-law.test.d.ts.map

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

package/dist/theme/icon-slot.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `IconSlot` — the ONE box every `icon` prop in the public API renders through
+ * (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * basalt ships no icon dependency, so every `icon` slot takes a `ReactNode` the consumer fills —
+ * and a consumer's glyph arrives at whatever geometry its own icon set chose: `width="24"` from
+ * Tabler's defaults, no `width` at all from a hand-written `<svg viewBox="0 0 20 20">`, a
+ * `stroke-width` tuned for a 24px box, or an `<img>` off a sprite sheet. Passing that node straight
+ * into Mantine's `leftSection` (which is a bare `flex` box with no size of its own) lets the CALLER
+ * decide the height of a basalt control's row. That is the class of bug this component closes: the
+ * icon's box is the framework's, and there is no prop on it.
+ *
+ * **Derived, not configured.** There is no `size` prop, on purpose — a size at a call site is the
+ * same C5 violation a `size="xs"` on a Button is. The box reads `--vx-space-icon-size` (default
+ * 16px, the control tier's mark), and the only thing entitled to set that var is a HOME's own CSS:
+ * `WidgetHeader` sets it per `data-tier`, so a `tier="widget"` heading draws 14px icons and a
+ * `tier="section"` heading draws 16px, with every call site unchanged.
+ *
+ * Mantine-free and dependency-free (one CSS module, one `<span>`), so `src/widget-header/**` — which
+ * `ChartCard` composes from inside `src/charts/**` — can deep-import it without pulling
+ * `@mantine/*` into the charts graph (`scripts/check-dist-layering.mjs`). Deep-import it as
+ * `../theme/icon-slot`, never through the `./theme` barrel, for exactly that reason. INTERNAL: it is
+ * not on any barrel. A consumer never needs it — passing `icon` IS the contract, and this is what
+ * makes that contract hold.
+ *
+ * `data-basalt-icon` is the queryable marker, the same idiom `CtlSlot` uses for `data-basalt-tier`:
+ * a CSS-module class name is a build-time hash, so it is not something a test — or a consumer
+ * debugging a misaligned row — can select on.
+ *
+ * @example
+ * // A control's icon slot — no size anywhere at the call site.
+ * <Button leftSection={<IconSlot>{icon}</IconSlot>}>{label}</Button>
+ */
+import type { ReactNode } from 'react';
+export type IconSlotProps = {
+    readonly children: ReactNode;
+    /**
+     * Composed ONTO the slot class, never in place of it — a home adds colour/state rules (the pill's
+     * muted-then-ink icon, a header's faint one) and the geometry stays the slot's.
+     */
+    readonly className?: string;
+};
+export declare function IconSlot({ children, className }: IconSlotProps): ReactNode;
+//# sourceMappingURL=icon-slot.d.ts.map

package/dist/theme/icon-slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-slot.d.ts","sourceRoot":"","sources":["../../src/theme/icon-slot.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,aAAa,GAAG,SAAS,CAa1E"}

package/dist/theme/icon-slot.js

@@ -0,0 +1,21 @@
+import { jsx } from "react/jsx-runtime";
+import classes from "./icon-slot.module.css";
+function IconSlot({ children, className }) {
+  return (
+    // `aria-hidden` unconditionally: an icon in a basalt control is DECORATIVE by construction —
+    // every control that takes one also carries a label or an `aria-label`, so a named icon would
+    // double the announced name. A caller wanting a meaningful graphic names the control, not this.
+    /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: className === void 0 ? classes.slot : `${classes.slot} ${className}`,
+        "data-basalt-icon": true,
+        "aria-hidden": "true",
+        children
+      }
+    )
+  );
+}
+export {
+  IconSlot
+};

package/dist/theme/icon-slot.module.css

@@ -0,0 +1,47 @@
+/*
+ * The framework's ONE icon box (`docs/CONTROLS-SPEC.md` §3) — see `icon-slot.tsx` for why every
+ * `icon` prop in the public API renders through it.
+ *
+ * The box is a FIXED square, not a shrink-to-fit inline box: `width`/`height` are declared on the
+ * slot itself so the row's geometry is decided by the SLOT and never by the glyph the caller
+ * happened to pass. `--vx-space-icon-size` is the host's override hook (a `WidgetHeader` tier, a
+ * collapsed rail), defaulting to the 16px the control tier draws; it is deliberately NOT a
+ * `--vx-space-*` token declared by `tokens/index.ts` — no home needs it globally, and a token would
+ * invite a call site to set it.
+ */
+.slot {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--vx-space-icon-size, 1rem);
+  height: var(--vx-space-icon-size, 1rem);
+  /* The glyph is `display: block` below, so the slot has no text to lead — a residual line box is
+   * what pushed a 16px icon a fraction below the optical centre of a 30px button. */
+  line-height: 0;
+}
+
+/*
+ * `width`/`height: 100%` is what makes ANY consumer glyph land on the tier. An inline `<svg>`
+ * carries its own `width`/`height` attributes (14, 20, 24 — or none at all, which paints at the
+ * `viewBox`'s intrinsic size, or 300×150 with no `viewBox` either), and those attributes are
+ * PRESENTATION attributes: they lose to any CSS declaration. So the slot restates them from the
+ * box, and the caller's own numbers stop mattering.
+ *
+ * `display: block` removes the baseline the glyph would otherwise sit on. An inline `<svg>` aligns
+ * its own bottom edge to the parent's text baseline, which leaves the descender gap BELOW it inside
+ * the box — the icon then paints high or low of centre by a fraction of the line box, and by a
+ * DIFFERENT fraction per font stack. `object-fit: contain` keeps a non-square glyph whole rather
+ * than stretching it to the square box.
+ *
+ * `img` and `picture` are covered too: an icon slot filled from a sprite sheet or a remote asset is
+ * the same geometry problem, and a consumer's icon set is as likely to be one as the other.
+ */
+.slot > svg,
+.slot > img,
+.slot > picture {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}

package/dist/theme/icon-slot.module.css.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly slot: string
+}
+export default classes

package/dist/theme/icon-slot.test.d.ts

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

package/dist/theme/icon-slot.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-slot.test.d.ts","sourceRoot":"","sources":["../../src/theme/icon-slot.test.tsx"],"names":[],"mappings":""}

package/dist/theme/index.d.ts

@@ -10,6 +10,7 @@ import type { BasaltFontsConfig } from '../tokens/index.js';
  */
 export type { BasaltFontsConfig } from '../tokens/index.js';
 export { useBasaltSpacing } from './use-basalt-spacing.js';
+export { CTL_THEME, CtlSlot, type CtlSlotProps } from './ctl-theme.js';
 declare module '@mantine/core' {
     interface MantineThemeOther {
         basaltDerive?: DeriveConfig;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AASvD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAm5BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAmJ/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAIvD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AASnE,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AA26BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAyR/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}