basalt-ui 1.29.2 → 1.30.0

package/README.md

@@ -241,7 +241,12 @@ exemption:
 ```
 
 `check-theme` fails loudly (instead of a false `✓`) when the configured roots resolve to zero
-scanned files, and `doctor`'s `guard-scan` check agrees with it. Each root's **parent** also
+scanned files, and `doctor`'s `guard-scan` check agrees with it — it shares `scannableFiles` with
+`check-theme`, so the two cannot disagree about what would be scanned. (`guard-scan` and
+`install-parity` were absent from `doctor` for four minors up to 1.29.2, with no MIGRATING row, and
+are back in 1.30.0. While they were gone a consumer CI step that ran `doctor` to catch an
+install/manifest version mismatch caught nothing, zero-file roots could ship as a permanently green
+guard, and this sentence described a check that did not exist.) Each root's **parent** also
 contributes its `index.html` and its `public/` tree — the Vite layout `basaltViteConfig` assumes,
 and where a raw `theme-color` or webmanifest `background_color` actually lives. `.json` is never
 blanket-scanned; `include` names one explicitly and is the only route to it. `profile:
@@ -375,7 +380,7 @@ Apply opacity with `alpha(token, a)` (backed by `color-mix`) — never `rgba()`,
 App-specific series colors live in the consumer, not the framework. The framework ships the factories:
 
 ```ts
-// src/theme/series.ts — the single guard-exempt file
+// src/lib/series.ts — the ONE path check-theme exempts by default (see the note below)
 import { defineSeries, groupTokens } from 'basalt-ui/tokens'
 
 // 1. Declare the series with light/dark pairs (ColorPair shape — hex strings per scheme)
@@ -402,6 +407,22 @@ export const colors = groupTokens(GROUP, SERIES)
 export const paletteGroups = { [`${GROUP}-`]: SERIES }
 ```
 
+> **Put it at `<first basalt.root>/lib/series.ts`, or the guard reports it.** `defineSeries` takes
+> hex `ColorPair`s _by type_, so this is the one file the doctrine tells you to write raw hex in —
+> and the exemption is an exact PATH, not a shape: `check-theme` skips
+> `<first basalt.root>/lib/series.ts` (the same value `DESIGN.md`'s `{{SERIES_MODULE_PATH}}`
+> renders, so the two cannot drift), and nothing special-cases a file merely _because_ it calls
+> `defineSeries`. A series module anywhere else — `src/theme/series.ts`, say — reports `raw-hex`
+> twice per pair. Two ways out, and the second is not the same as the first:
+>
+> ```json
+> // package.json — `seriesModulePath` MOVES the default exemption; `exempt` REPLACES it wholesale
+> { "basalt": { "seriesModulePath": "src/theme/series.ts" } }
+> ```
+>
+> Writing your own `basalt.exempt` array REPLACES the series default rather than adding to it, so
+> list your series module in that array explicitly whenever you use the key at all.
+
 ```tsx
 // main.tsx — wire paletteGroups into BasaltProvider
 import { BasaltProvider, createBasaltTheme } from 'basalt-ui'

package/agent/rules/basalt-controls.md

@@ -42,8 +42,7 @@ size tier and one persistence binding, and basalt owns all three. The API is in
 | C15 | Every touch target inside a home clears the `touchControlHeight` floor below `sm`. The mobile `Filters (n)` sheet draws no row of its own — it renders the same `PanelRow` the aside's panel surface does. |
 | C16 | A new guard lands `warn` with a dated `promote` version, and the build fails once the package version reaches it while the rule is still `warn`.                                                           |
 
-C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTable` and C12 are
-**advisory** — the generated header above says so. A green lint run is not evidence they hold.
+A green lint run is not evidence the advisory laws the generated header above lists hold.
 
 ## The three homes
 
@@ -52,12 +51,10 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `PageBar`                                                                         | `actions`, `sync`, `filters`, `filtersEnd`, `tabs` | `ctl`        | the page's filters, tabs, actions, refresh |
 | `Section`                                                                         | `actions`, `tabs`                                  | `ctl`        | that section's own controls and its count  |
 | `WidgetHeader` / `ChartCard` / `StatCard` / `BasaltDataTable` / `SettingsSection` | `actions`                                          | `ctl`        | that widget's own controls and its count   |
-| `SettingsRow`                                                                     | `control`                                          | Mantine `md` | ONE form field, bound to a setting         |
-| `FormRow` / `FormGroup` (`basalt-ui/forms`)                                       | children                                           | Mantine `md` | ONE form field or a labelled cluster       |
+| `SettingsRow` · `FormRow` / `FormGroup` (`basalt-ui/forms`)                       | `control` · children                               | Mantine `md` | ONE form field, or a labelled cluster      |
 
 - **Inside `BasaltShell`** both `PageBar` rows are portals (header / the band above the scrollport)
   — where you write `<PageBar>` never moves it. Without a shell both rows render in flow, sticky.
-  The header height is a token, never state.
 - **The form row keeps Mantine's own `md` tier** — a raw `Select` in `SettingsRow.control` is the
   right answer, `size` there is load-bearing. Neither `SettingsRow` nor `FormRow`/`FormGroup` is a
   tiered slot; no filter or size rule applies to them.
@@ -76,10 +73,9 @@ C1's cross-file case, a hand-rolled section heading, C11 outside `BasaltDataTabl
 | `touchControlHeight`  | hit area below `sm`                                        | every home                                          |
 | `controlHeight`       | `size="md"`                                                | forms — unchanged                                   |
 
-Each home wraps its **slot** — never its body — in a hoisted theme provider defaulting every
-Mantine control inside it to `size="ctl"`. A raw `Button` in `PageBar.actions` is already the right
-height with no prop; a `size="xs"` typed there is law C5 (`basalt/control-size-literal`). Mantine's
-own `sm`/`xs` are NOT re-pointed elsewhere. Exception: `ChartCard.actions` is Mantine-free, so it
+A home sizes its **slot**, never its body: a raw `Button` in `PageBar.actions` is already the right
+height with no prop, and a `size="xs"` typed there is law C5 (`basalt/control-size-literal`).
+Mantine's own `sm`/`xs` are NOT re-pointed. Exception: `ChartCard.actions` is Mantine-free, so it
 carries only the tier attribute and its controls size themselves.
 
 ## Binding a control to a store
@@ -103,52 +99,56 @@ The store, its fields and their lanes are basalt-state.md. What this file adds:
 is a tsc error. `ActionGroup`/`OverflowMenu`/`SyncButton` take typed action DATA, never children.
 
 **The date picker is injected, never imported.** `basalt-ui/controls` resolves with no
-`@mantine/dates` installed; `DateRangePicker` comes from `basalt-ui/controls-dates` through
-`RangeFilter.customPicker`. Never import `@mantine/dates` from a shared module or reach for
-`DateInput`/`DatePickerInput` inside a home slot.
+`@mantine/dates`; `DateRangePicker` comes from `basalt-ui/controls-dates` through
+`RangeFilter.customPicker`. Never import it in a shared module or reach for `DatePickerInput`.
 
 ## `FilterSet` owns the responsive story
 
-Do not build one at the call site. Above `sm`, `FilterSet` measures its own children and folds the
-tail into a `+N` pill. Below `sm`, the first `inline` children stay pills and one `Filters (n)`
-pill opens a sheet where every child renders full-width and answers one `Reset all`. **`n` and
-`Reset all` are DERIVED** from whether each field differs from its fallback — adding a filter is
-one JSX line, no count or reset handler to maintain.
+Do not build one at the call site. Above `sm` it measures its own children and folds the tail into
+a `+N` pill. Below `sm` the first `inline` children stay pills and one `Filters (n)` pill opens a
+sheet where every child is full-width and answers one `Reset all`. **`n` and `Reset all` are
+DERIVED** from whether each field differs from its fallback — a filter is one JSX line, no handler.
 
-| Below `sm`       | What basalt does                                                                                                                   |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `PageBar` row 1  | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action                                               |
-| `PageBar` row 2  | line 1: `ViewTabs` full-width (a `Select` past three options) · line 2: one inline pill · `Filters (n)` · the aside's `Panel` pill |
-| a section header | title · count · one inline action, the rest in a kebab; tabs past three become a `Select`                                          |
-| a widget header  | value + delta wrap under the title; the sparkline drops to bleed; one `⋯` action                                                   |
+| Below `sm`      | What basalt does                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `PageBar` row 1 | breadcrumb · the `primary` action as an icon · ONE kebab holding every `more` action                                           |
+| `PageBar` row 2 | line 1: `ViewTabs` full-width (a `Select` past three options) · line 2: one inline pill · `Filters (n)` · the aside's own pill |
 
 Every swap is CSS inside the control (one mount), never a JS media query. Two mounts under
 `visibleFrom`/`hiddenFrom` is `basalt/responsive-twin`.
 
 ## The aside
 
-`PageAside` is a shell REGION, not a fourth home — C1 still names three. Its body IS a home: it
-scopes children to the `panel` surface, so the same `SelectFilter` that is a pill in the page bar
-is a ROW in the aside — never two components, the surface is read from where it's mounted.
+`PageAside` is a shell REGION, not a fourth home — C1 still names three, and its body IS one:
+children scope to the `panel` surface, so a `SelectFilter` renders its ROW form there, not a pill.
 
-| In the aside     | Write                                                                             |
+```tsx
+<PageAside title="Composition" persistKey="composition">
+  <PanelRow label="Weight">…</PanelRow>
+</PageAside>
+```
+
+| In a `PageAside` | What it is                                                                        |
 | ---------------- | --------------------------------------------------------------------------------- |
+| `title`          | REQUIRED — the header text AND the region's accessible name; omitted, it THROWS   |
+| `persistKey`     | persists the fold at `basalt:aside:<persistKey>`; omitted the fold is per-mount   |
+| `defaultFolded`  | the fold on first render, honoured only while nothing is persisted                |
+| `classNames`     | the three boxes it paints — `root` / `header` / `body`                            |
 | an inspector row | `PanelRow` — label above, optional `hint`, mono `readout`, `end` slot             |
 | a bound slider   | `SliderControl` — min/max/step come off the handle, never props                   |
 | a facet list     | `MultiSelectFilter` + `counts` (and `max`, past which the tail folds)             |
 | a group of rows  | `Section` — flush inside the aside, which draws the rhythm itself                 |
 | a choice         | `PanelChoice` — a track only while ≤3 options AND every label fits, else `Select` |
 
-- ONE `PageAside` per page, written AFTER the main content — it portals into the region from `sm`
-  up, its tree position is reading order, not layout.
-- Below `sm` it projects into `PageBar` row 2 as one `Panel` pill; with no row 2 — or shell-less —
-  it renders in flow. One node either way (C9).
+- ONE per page, written AFTER the main content — tree position is reading order, not layout.
+- Below `sm` it projects into `PageBar` row 2 as one pill carrying its own `title`, and that row
+  exists ONLY when the bar has `tabs`, `filters` or filter-end actions — without one, or with no
+  shell, it renders in flow at the BOTTOM of the page. One node either way (C9).
 - A bound control outside all of this is `basalt/bound-control-outside-home` — a slot prop, a
   `FilterSet`, a `PageAside` or a `PanelRow` is a home; nothing else is.
 
 ## Sidebar blocks
 
 A non-destination list, a progress meter or a bespoke node in the sidebar is a `SidebarBlock` —
-declared data, three kinds (`list`/`progress`/`custom`), placed `'nav'`/`'bottom'`. Because it's
-data, basalt owns what a `ReactNode` slot couldn't: a rail dot/ring when collapsed, a persisted
-fold, one More-sheet row per block. A `custom` block is desktop-only, by design.
+declared data, three kinds (`list`/`progress`/`custom`), placed `'nav'`/`'bottom'`; the rail and
+More-sheet projections are basalt's from there (C13). A `custom` block is desktop-only, by design.

package/agent/skills/basalt-app/SKILL.md

@@ -55,8 +55,10 @@ export default defineConfig({
 ```
 
 Then `BasaltShell` with a `useNav(NAV)` spread (basalt-state.md), `PageBar` per page
-(basalt-controls.md), and `<first basalt.root>/lib/series.ts` as the app's one guard-exempt series
-source (`/basalt-charts`). There is no Tailwind.
+(basalt-controls.md), `PageAside` on any page that needs a right-hand inspector — a region a ROUTE
+claims rather than a shell prop, so it never appears in `BasaltShell`'s props — and
+`<first basalt.root>/lib/series.ts` as the app's one guard-exempt series source (`/basalt-charts`).
+There is no Tailwind.
 
 ## 3. Verify the wiring took
 

package/agent/templates/query-client.ts.tpl

@@ -2,11 +2,25 @@
  * Basalt query client — configure once, share via router context.
  * Extend staleTime / gcTime defaults and add per-query error handling here.
  *
+ * A FACTORY, not a module-level singleton, and that is load-bearing under SSR: a
+ * `export const queryClient = createBasaltQueryClient()` is created once per PROCESS,
+ * so every request a Node server handles shares one cache — one user's data served to
+ * the next. Call `makeQueryClient()` once per request on the server, and once at module
+ * scope in a browser-only entry:
+ *
+ *   // main.tsx (CSR) — one client for the tab's lifetime
+ *   const queryClient = makeQueryClient()
+ *
+ *   // an SSR/prerender entry — one per request, never hoisted
+ *   const queryClient = makeQueryClient()
+ *
  * Scaffold written by `basalt-ui init`. This file is yours — `basalt-ui sync` will not overwrite it.
  */
 import { createBasaltQueryClient } from 'basalt-ui'
 
-export const queryClient = createBasaltQueryClient({
-  // staleTime: 60_000,   // optional: global cache freshness window (ms)
-  // gcTime: 5 * 60_000,  // optional: inactive-query garbage-collection window (ms)
-})
+export function makeQueryClient() {
+  return createBasaltQueryClient({
+    // staleTime: 60_000,   // optional: global cache freshness window (ms)
+    // gcTime: 5 * 60_000,  // optional: inactive-query garbage-collection window (ms)
+  })
+}

package/configs/lefthook.yml

@@ -10,10 +10,16 @@
 # `lefthook dump`: declare `pre-commit.commands.oxfmt.run` (or `glob:`) in your file and the
 # preset's value is what runs — yours is discarded silently, with no warning. Only keys this preset
 # does NOT define merge in from yours. So:
-#   • `env:`, `exclude:`, `skip:` and any command name not used here — yours, they merge.
+#   • `env:`, `root:`, `exclude:`, `skip:` and any command name not used here — yours, they merge.
 #   • `run:` and `glob:` on a command below — NOT overridable. Do not try.
 # The sanctioned seams are therefore:
-#   • `BASALT_BIN` (below) — set it via `env:` to point the guard at a specific CLI.
+#   • `root:` — the ONE seam that fixes a monorepo, and the one nobody guesses. Lefthook runs every
+#     command at the REPO ROOT; `root:` moves one command into your package and rewrites
+#     `{staged_files}` relative to it. Every command below needs it when the app is not the repo
+#     root — otherwise `oxlint`/`oxfmt` run where there is no config and `check-theme` scans
+#     nothing. See the recipe at the bottom of this file.
+#   • `BASALT_CWD` / `BASALT_BIN` (below) — set them via `env:` to point the guard at a package and
+#     at a specific CLI. An alternative to `root:` for `check-theme` only.
 #   • `exclude:` — carve files out of a glob you cannot narrow.
 #   • a differently-named command of your own, plus `skip: true` on the one here you are replacing.
 #
@@ -62,23 +68,49 @@ pre-commit:
     # Without this, a consumer accumulates violations indefinitely while `check-theme` is never
     # invoked, and the kinds it never ran are indistinguishable from the kinds that found nothing.
     #
-    # `$BASALT_BIN` is the one sanctioned override seam here, because `run:` itself is not
-    # overridable (see the note at the top). It defaults to `bunx --no-install basalt-ui`:
-    #   • `--no-install` because a plain `bunx basalt-ui` in a repo where basalt is not resolvable
-    #     from the ROOT (bun's isolated linker puts it beside the package that depends on it)
-    #     silently downloads a DIFFERENT copy from npm and gates the commit with a version nobody
-    #     pinned. With the flag it fails loudly instead, which is the answer you can act on.
-    #   • point it at the local bin to fix that, exactly as the seeded check.yml does:
-    #       pre-commit:
-    #         commands:
-    #           check-theme:
-    #             env: { BASALT_BIN: ./packages/web/node_modules/.bin/basalt-ui }
+    # `$BASALT_CWD` and `$BASALT_BIN` are the sanctioned override seams here, because `run:` itself
+    # is not overridable (see the note at the top).
     #
     # Lefthook runs commands at the REPO ROOT, while in a monorepo the `basalt` config and the
-    # manifest live in a package below it — verified to produce `0 files scanned`, i.e. following
-    # this preset installed a gate that never gated. `check-theme` now relocates to the single
-    # workspace package carrying a basalt config and says so; with more than one, set BASALT_CWD
-    # in the same `env:` block to name the package:
-    #   env: { BASALT_CWD: apps/web }
+    # manifest live in a package below it. Since 1.29.0 the CLI resolves ONE way — `BASALT_CWD`,
+    # else the invocation cwd — and infers nothing from siblings or parents, so at the root it
+    # reads a directory with no basalt config and scans nothing. That used to be an unexplained
+    # `0 files scanned`; it now names this preset and the two fixes. `BASALT_CWD` is the fix that
+    # needs no other change, and this `run:` derives the bin from it so one setting covers both:
+    #   pre-commit:
+    #     commands:
+    #       check-theme:
+    #         env: { BASALT_CWD: apps/web }
+    #
+    # The default bin is `<BASALT_CWD>/node_modules/.bin/basalt-ui`, i.e. the local bin of the
+    # package the guard is being run FOR, and plain `node_modules/.bin/basalt-ui` when BASALT_CWD
+    # is unset. That replaces a `bunx --no-install basalt-ui` default which resolved to nothing at
+    # the root under bun's isolated linker — the linker puts basalt beside the package that depends
+    # on it, never at the root, so the default was broken in exactly the layout BASALT_CWD exists
+    # for. A missing bin now fails with the path it looked for instead of `bunx`'s resolver error.
+    # Override it (a hoisted install, a pinned copy) with `env: { BASALT_BIN: … }` in the same
+    # block; it wins outright.
     check-theme:
-      run: ${BASALT_BIN:-bunx --no-install basalt-ui} check-theme
+      run: ${BASALT_BIN:-${BASALT_CWD:+$BASALT_CWD/}node_modules/.bin/basalt-ui} check-theme
+
+# ── MONOREPO RECIPE (the app is NOT at the repo root) ────────────────────────────────────────────
+# `extends` merges the commands above, but NOT a working directory — so at the repo root `oxlint`
+# and `oxfmt` run where your `.oxlintrc.json` and your binaries are not, and `check-theme` scans a
+# directory with no basalt config. Add `root:` per command in YOUR root lefthook.yml — it merges,
+# because the preset deliberately does not define it:
+#
+#   # <repo>/lefthook.yml
+#   extends:
+#     - apps/web/node_modules/basalt-ui/configs/lefthook.yml
+#   pre-commit:
+#     commands:
+#       oxlint: { root: 'apps/web/' }
+#       oxfmt: { root: 'apps/web/' }
+#       check-theme: { root: 'apps/web/' }
+#
+# One mechanism for all three, and `check-theme` needs nothing else: `root:` moves the invocation
+# cwd, which is the only thing the CLI resolves from. `env: { BASALT_CWD: apps/web }` is the
+# equivalent for the guard alone — reach for it when the command has to keep running at the root.
+#
+# `basalt-ui doctor` reads the MERGED config (`lefthook dump`) rather than this file, so it is what
+# tells you whether the result actually gates.