basalt-ui 1.19.1 → 1.20.0

package/agent/rules/basalt-router.md

@@ -104,10 +104,16 @@ Install `@tanstack/react-router` as a peer, then import from `basalt-ui/router-t
 
 **Prerequisites:**
 
-- `@tanstack/router-plugin/vite` must be configured in your Vite config and `tsr generate` must
-  have run at least once — the `StaticDataRouteOption` augmentation only takes effect once the route
-  tree (`src/routeTree.gen.ts`) has been generated. In CI and after adding routes, run
-  `tsr generate` (or `bun run typecheck`, which triggers it) before relying on breadcrumb or nav data.
+- **The only hard prerequisite is the `Register` module augmentation** (see "The prerequisite that
+  makes all of this real" below). `defineNav` / `navGroup` / `navTarget` / `flattenNav` / `useNav` /
+  `createSearchParamStore` all work against a hand-written `createRouter({ routeTree })` with
+  code-defined routes, no Vite plugin and no generated tree — verified end-to-end in a consumer,
+  including that a bad `to` still prints the real route-path union.
+- **`@tanstack/router-plugin/vite` + `tsr generate` are needed only for `staticData`** — that is,
+  for `useRouterBreadcrumbs` and any nav metadata read off the route tree. The
+  `StaticDataRouteOption` augmentation takes effect once `src/routeTree.gen.ts` exists. In CI and
+  after adding routes, run `tsr generate` (or `bun run typecheck`, which triggers it) before relying
+  on breadcrumb data.
 - The loader's `context.queryClient` requires `createRootRouteWithContext<{ queryClient: QueryClient }>()`.
   Run `basalt-ui init` to scaffold a `query-client.ts` + `__root.tsx` seed that wires the TanStack
   Router + Query context correctly — the generated `__root.tsx` uses
@@ -255,12 +261,18 @@ With that missing, every `to` widens to `string`, a nonexistent route path compi
 required `search` compiles, and the API looks like it is working while catching nothing. This is
 the single highest-value thing to verify when adopting the config: change one `to` to a garbage
 path and confirm you get a compile error listing the real route paths. If you don't, the
-augmentation is missing or `tsr generate` has not run.
-
-Second thing to know before you migrate: TypeScript cannot catch a destination that FORGETS a
-default `search` when the route validates with `validateSearch: (raw: Record<string, unknown>) => T`
-— that gives TanStack an input type where no key is required. Diff an old hand-written target table
-against the new definition by hand, key by key.
+augmentation is missing (or, on a file-route setup, `tsr generate` has not run).
+
+Second thing to know before you migrate: whether a missing `search` is caught depends on the
+schema's OUTPUT type, not on the `validateSearch` signature. If every key of `T` is required —
+which is what a Zod object with defaults produces, since defaults apply on parse and the output has
+no optionals — TanStack raises `MakeRequiredSearchParams` and the compiler catches it. Two routes in
+one consumer had been shipping nav links with no search params behind a `to={target.to as never}`
+cast; removing the callback surfaced both immediately.
+
+**The caveat holds only when `T` has no required keys** (every key optional, or the validator
+returns a partial). There, a forgotten `search` compiles — diff the old target table against the new
+definition by hand, key by key. Everywhere else, trust the error.
 
 Error messages here are the router's own and they are large: one wrong `to` prints the whole
 route-path union plus a `RouterCore<…>` blob, because TanStack's `Constrain` falls back to the

package/agent/rules/basalt-tokens.md

@@ -24,12 +24,76 @@ status pops — never floods. (Blueprint/Basalt zinc-charcoal are the historical
 ancestors; `docs/DESIGN-SPEC.md` in the basalt-ui repo supersedes both — see its "Doctrine
 inversions" section.) This
 rule is the operational checklist; it is enforced mechanically by **`basalt-ui check-theme`**
-(wire it into `lint`: `oxlint . && basalt-ui check-theme`). A violation fails the build. Escape hatch: a
-`theme-allow` line comment (diff-visible, deliberate).
+(wire it into `lint`: `oxlint . && basalt-ui check-theme`; `init` seeds that as `lint:basalt`). A
+violation fails the build. Escape hatch: a scoped `theme-allow <rule-id> — <reason>` comment
+(diff-visible, deliberate) — see the contract below.
 
 `check-theme` reads its config from your `package.json` `"basalt"` key
-(`{ roots?, exempt?, spacingSteps?, forbiddenAccents? }`); set `roots` to your source dirs and `exempt`
-to the files that legitimately define palette values.
+(`{ roots?, exempt?, include?, profile?, severity?, spacingSteps?, forbiddenAccents? }`); set `roots`
+to your source dirs and `exempt` to the files that legitimately define palette values.
+
+**`roots` is not optional in practice.** Omitted it falls back to `src` relative to the cwd — fine
+for a single-app repo, zero files for anything under `apps/*/src`, and `check-theme` then exits 1
+with `0 files scanned`. Since 1.20.0 `init` writes a real `roots` from the detected layout and
+`doctor`'s `guard-scan` check fails when the configured roots resolve to nothing; before that a repo
+could look fully wired while the gate scanned nothing.
+
+The scan reaches slightly beyond `roots`: each root's PARENT contributes its `index.html` and its
+`public/` tree (the Vite layout basalt's own preset assumes), because that is where a `theme-color`
+meta and a webmanifest's `background_color` actually live. `.json` is never blanket-scanned — name a
+design-surface JSON in `basalt.include`, the only route to one.
+
+## `theme-allow` — the 1.20.0 contract
+
+Scope it. `theme-allow <rule-id> — <reason>` waives that ONE kind; the id is a guard kind
+(`raw-surface`, `inline-spacing`, …) or an oxlint plugin rule (`hand-rolled-plot`,
+`raw-scroll-container`, …), with or without the `basalt/` prefix.
+
+```tsx
+// theme-allow raw-surface — third-party widget needs a literal corner
+<Widget style={{ borderRadius: 3 }} />
+```
+
+- **A bare `theme-allow` still waives everything**, so no upgrade takes a build down over comment
+  placement — but it now reports `theme-allow-unscoped` (`warn` for one minor, then `error`).
+  Rescope the ones you have; that is the whole migration.
+- **Spell the id right — a typo waives nothing.** A word in the id slot that names no rule is
+  recorded as unknown and suppresses nothing; the annotation covers exactly the ids it got right.
+  Only a genuinely bare `theme-allow` is the blanket form. Because the id slot is read strictly, a
+  prose reason has to be introduced by a separator: `theme-allow: <why>` or
+  `theme-allow <id> — <why>`, never `theme-allow <why>`.
+- **Three placements work and both engines agree on all three**: the reported line, a comment-ONLY
+  line directly above it (the only form JSX can express — the reported line is usually a multi-line
+  opening tag or a `{expr}` child), and in CSS a trailing annotation reaching back over the
+  declaration it terminates. The third is what survives the shipped `oxfmt` reflowing a long
+  `background-color` so the hex lands ABOVE the comment.
+- **`basalt/hand-rolled-plot` no longer grants whole-file immunity** off whichever comment happened
+  to sit on the first assembly node. Every node is waived on its own; a file-scoped exception needs
+  a written declaration that both names the rule and gives a reason, anywhere in the file.
+
+### New in 1.20.0 — five guard kinds, all `warn` for one minor
+
+| Kind                      | Fires on                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `theme-allow-unscoped`    | a `theme-allow` with no rule id, no reason, or an id that names no rule                                             |
+| `surface-shadow-override` | a `boxShadow` built FROM tokens that REPLACES `--vx-shadow-card` instead of composing with it                       |
+| `css-raw-surface`         | the kebab dialect of the surface kinds in CSS (`border-radius: 6px`); sub-scale corners and circle/pill values pass |
+| `inline-font-size`        | `style={{ fontSize: 11 }}` — the `check-theme` half of `basalt/no-raw-font-size`, for a CI that runs only the guard |
+| `hidden-inline-style`     | a multi-line opening tag, or a style object hoisted to a const — `raw-html-layout`'s formatting-independent half    |
+
+Two new oxlint rules ship at `warn` alongside them: **`basalt/shadow-basalt-export`** (below) and
+**`basalt/hand-rolled-shell`** (`AppShell` parts or `Burger` in a file that does not render
+`BasaltShell`). **`basalt/raw-size-literal` is now `error`** — CSS-length strings on
+`size`/`fz`/`fontSize`. Every kind keeps its own boolean, `basalt.severity` and `exemptRules`.
+
+## The guard sees palette, not vocabulary
+
+Round 4 swept seven consumer repos: every gate green, and ~15 independently re-rolled copies of
+components basalt already ships (`StatCard` in 4 of 4 apps, `EmptyState`, a 266-line hand-rolled
+`AppShell`). A fork written by a token-fluent author uses exactly the right tokens, so no palette
+guard can ever see it. **`basalt/shadow-basalt-export` is the cheap detector** — it warns when a
+local component's name collides with a live basalt export, read from the real shipped barrel. The
+habit it stands in for: check whether basalt already ships the thing before building it.
 
 ## Filled surfaces — the fill band
 
@@ -158,5 +222,10 @@ export const paletteGroups = { [`${GROUP}-`]: SERIES } // -> { 'activity-': SERI
 ## When the guard fires
 
 Fix the source, don't silence it — reach for the right token first. Only add `theme-allow` for a
-genuine, documented exception (e.g. a third-party widget needing a literal). The palette-definition
-files are listed in your `exempt` set so they don't self-trip.
+genuine, documented exception (a third-party widget needing a literal), scoped to the rule id, with
+a reason: a bare `// theme-allow` passes the check, tells the next reader nothing, and now reports
+`theme-allow-unscoped` besides. The palette-definition files are listed in your `exempt` set so they
+don't self-trip. A stylesheet emitted by `basalt-ui tokens:css` needs no entry — in a `.css` file
+carrying that exact two-line `@generated basalt-ui` header, the guard skips the LINES that are
+basalt custom properties, selectors, `}` or self-closing comments. Pasting the marker anywhere else
+suppresses nothing, and an ordinary declaration added to such a file is still reported.

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

@@ -53,6 +53,28 @@ own the files.
 - `.basalt/manifest.json` — a sha256 per managed file + the basalt-ui version that wrote it, so
   `sync` can three-way diff and `doctor` can spot a stale install.
 
+It also patches `package.json`: **`basalt.roots`** inferred from the real layout (workspace packages
+depending on basalt or Mantine, else every workspace `src/`, else `src`) and a **`lint:basalt`**
+script (`oxlint . && basalt-ui check-theme`). Everything derives from `roots` — the guard's scan, the
+seeded CI `oxfmt` globs, the default exemption — so a workspace repo without it scaffolds a guard
+that scans zero files while every gate reports green. Correct it if your sources live elsewhere. A
+Mantine-free consumer adds `"basalt": { "profile": "tokens-only" }` by hand; `check-theme` never
+infers that, because inferring it from a missing `@mantine/core` would silence 17 kinds on a repo
+that simply keeps Mantine in another workspace package.
+
+**`init` on an EXISTING app is a lint-debt event, not a no-op.** Adopting the shipped preset turns
+on whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
+findings on the first run. `init` names the plugins and every file it kept — plus what keeping it
+costs (an existing `.oxlintrc.json` that does not `extends` the preset means the entire basalt lint
+half is off, and nothing else says so; `--merge-lint` splices it in). Run `oxlint .` and triage
+before the next commit; turn a rule off with a written reason rather than disabling a plugin.
+
+Then `basalt-ui doctor`. `SKIPPED` is a third outcome beside pass/warn/fail and exits non-zero on
+its own — a check that could not run is not a check that passed — and the hard checks now include
+`basalt-resolves`, `guard-scan` (would `check-theme` cover more than zero files?) and
+`oxlint-preset` (does `.oxlintrc.json` really extend the preset? JSONC is parsed, not rejected).
+Expect doctor to go red where it was green on an older basalt; that is the point.
+
 After `init`, do the runtime wiring (the CLI scaffolds files, not your app's composition):
 
 ```tsx
@@ -94,10 +116,15 @@ ordering (e.g. alongside `@content-collections/vite`) and the full head/PWA/mani
 import 'basalt-ui/styles.css' // @layer basalt base styles, iOS input safety net, font stack
 ```
 
-Lint wires as `oxlint . && basalt-ui check-theme` — the theme guard is the teeth behind the token
-doctrine. The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts`
-on a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is the
-single guard-exempt palette source — see `/basalt-charts`.
+Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` script) — the theme
+guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
+already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
+passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
+`basalt/shadow-basalt-export` warns on the name collision; nothing catches the rest.
+
+The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on
+a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is
+the single guard-exempt palette source — see `/basalt-charts`.
 
 ## Refresh: `bunx basalt-ui sync`
 
@@ -140,13 +167,22 @@ both.
 - A thin `DESIGN.md` (deltas) + the thirteen `basalt-*` rules + the managed CLAUDE block are present.
 - `<first basalt.root>/lib/series.ts` exists as the one guard-exempt series source (for any app metric colors).
 - `basalt-ui sync --check` wired in CI (recommended) to catch drift on future upgrades.
+- `basalt-ui doctor` run after `init` and read to the last line — a `SKIPPED` check exits non-zero
+  and is not a pass.
 
 ## Notes
 
 - `init`, `sync`, and `check-theme` are all **real**. `sync` reconciles via a sha256 three-way diff
   (`--check` is a CI drift gate, `--force` overwrites local edits); `check-theme` is the palette
-  guard; `doctor` verifies the installed basalt-ui version against the manifest. All via
-  `bunx basalt-ui …`.
+  guard; `doctor` checks resolution, version, guard scan, oxlint preset, spacing-scale drift and
+  cross-package `ai` major parity. All via `bunx basalt-ui …`.
+- **Not a React app?** `bunx basalt-ui tokens:css --out src/tokens.css` emits the `--vx-*` layer with
+  no package in your dependency tree, `--selector-class dark` for the Tailwind `<html class="dark">`
+  convention, and `fonts:css` emits the shipped `--basalt-font-*` stacks. Both carry the two-line
+  `@generated basalt-ui` header the guard skips on — that header verbatim, and then only the LINES
+  that are basalt custom properties, selectors, `}` or self-closing comments, so the marker pasted
+  into a `.tsx` suppresses nothing and a declaration added to such a file is still reported — and
+  both take `--check` as a CI drift gate. See `docs/FRAMEWORK-FREE.md` in the basalt-ui repo.
 - The framework ships **no** icon or notification dep — pass icons as `ReactNode` and wire toasts
   yourself (e.g. `ThemeLabControls`' `copyIcon` / `onCopy`).
 - The framework DOES ship `motion` (motion.dev, formerly framer-motion) as a bundled dependency —

package/configs/check.yml

@@ -5,8 +5,14 @@
 # color literals / off-identity accents that bypass the --vx-* token system).
 # `basalt-ui sync --check` fails when the basalt-managed files (rules, skills, the
 # CLAUDE block) have drifted from the installed basalt-ui version.
-# The oxfmt globs below are rendered from `basalt.roots` at init time — this file is a
-# template, not a raw copy, so a monorepo doesn't seed a `src/**` that matches nothing.
+# The oxfmt globs below are rendered from `basalt.roots` at init time — `init` writes that
+# key from the repo's real layout (workspace packages included), so a monorepo does not
+# seed a `src/**` that matches nothing.
+# The basalt-ui command below is the LOCAL bin, rendered from where basalt actually
+# installed. `bunx basalt-ui` is deliberately not used: when the package is not resolvable
+# from the working directory (bun's isolated linker puts it beside the package that depends
+# on it, not at the root) bunx silently downloads a DIFFERENT copy from npm and the gate
+# runs a version nobody pinned.
 name: check
 on:
   pull_request:
@@ -23,8 +29,9 @@ jobs:
           bun-version: latest
       - run: bun install --frozen-lockfile
       - run: bunx oxlint .
-      - run: bunx basalt-ui check-theme
-      - run: bunx basalt-ui sync --check
+      - run: '{{BASALT_BIN}} doctor'
+      - run: '{{BASALT_BIN}} check-theme'
+      - run: '{{BASALT_BIN}} sync --check'
       - run: bunx oxfmt {{ROOTS_GLOBS}} '!**/dist/**' --check
       # Enable once your app defines these package.json scripts:
       # - run: bun run typecheck

package/configs/lefthook.yml

@@ -4,8 +4,17 @@
 #     - node_modules/basalt-ui/configs/lefthook.yml
 # lefthook merges these commands with the consumer's own, so this preset auto-updates
 # with the package. Runs oxlint + oxfmt on staged files and the theme guard on the whole
-# tree, pre-commit. Assumes oxlint/oxfmt are installed and your .oxlintrc.json extends
-# ./node_modules/basalt-ui/configs/oxlint.json.
+# tree, pre-commit. Assumes oxlint/oxfmt are installed.
+#
+# It does NOT assume your `.oxlintrc.json` extends the shipped preset — that assumption was
+# false for exactly the repos this seed exists for, since `init` KEEPS an existing oxlint
+# config. `basalt-ui doctor` now checks the extends and hard-fails when it is missing; run it
+# in CI (the seeded check.yml does) rather than trusting a comment nobody reads.
+#
+# `init` seeds the path RESOLVED from where basalt actually installed. Under bun's isolated
+# linker basalt lives beside the package that depends on it, not at the repo root, and a
+# root-relative `extends` there resolves to nothing — silently, because lefthook merges an
+# empty file without complaint.
 pre-commit:
   parallel: true
   commands:
@@ -28,5 +37,15 @@ pre-commit:
     # was written against: a guard that only runs when someone remembers to run it is not a guard.
     # 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.
+    #
+    # 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 your own lefthook.yml to name the package:
+    #   pre-commit:
+    #     commands:
+    #       check-theme:
+    #         env: { BASALT_CWD: apps/web }
     check-theme:
       run: bunx basalt-ui check-theme