bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.23

package/dist/ai/guides/icons-policy.md

@@ -16,12 +16,16 @@ Mandatory for AI-generated code.
 2. **`local:*` is for brand-specific art only** — logos, custom marks, one-off
    illustrations. They are SVG files in the configured `iconDir`.
 3. **Never invent icon names.** Use only names that exist in an installed
-   `@iconify-json/*` set or as files in `iconDir`. A missing icon throws at
-   mount (dev shows a Vite error overlay with the exact fix).
-4. **Icon names must be static string literals.** Production builds scan source
-   for `provider:name` literals and bundle only those — a name assembled at
-   runtime (`` `lucide:${kind}` ``) will be missing in production. Map dynamic
-   state to literals instead (e.g. a lookup object of full names).
+   `@iconify-json/*` set or as files in `iconDir`. A name that does not
+   resolve renders the built-in placeholder (a question mark in a circle,
+   tagged `data-bb-icon-missing="<name>"`) and logs one `console.error` with
+   the fix — in dev also as a Vite error overlay. It never throws.
+4. **Write icon names as literals, anywhere in the project.** The plugin
+   scans the whole project (PHP included) for `provider:name` literals and
+   bundles only those; `local:` ships everything. A name the scanner cannot
+   see as a literal — composed at runtime (`` `lucide:${kind}` ``), stored in a
+   database, chosen in an admin panel — goes in the plugin's `iconWhitelist`.
+   This holds in dev exactly as in production: dev registers the same set.
 5. **Never hand-place `BbIcon` where a component already accepts an icon** via
    a prop, item field, or dedicated slot (catalog below).
 
@@ -35,19 +39,38 @@ The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config ke
   auto-discovered. Installing `@iconify-json/lucide` makes every valid
   `lucide:<name>` available; removing it makes them all errors. Nothing to
   configure.
-- **Dev**: all icons of installed sets are registered. Referencing an
-  uninstalled prefix or a non-existent name fails loudly in the Vite error
-  overlay with an actionable message. A typo inside an installed set reads
-  "does not exist in the lucide icon set — did you mean `lucide:…`?"; a set
-  that is not installed reads "no installed icon set has the prefix `mdi`
-  (installed sets: lucide) … run: `npm install -D @iconify-json/mdi`". Read
-  the message: a typo wants a different name, a missing set wants an install,
-  never a guess.
-- **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
-  excluded) are scanned for static `provider:name` literals; each referenced
-  icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
-  icon used only in a `.stories.ts`/`.test.ts` file must also appear as a
-  literal in a scanned source file.
+- **What ships — `local:` everything, providers only what is scanned or
+  whitelisted.** Every SVG in `iconDir` is bundled. For provider sets the
+  plugin reads the **whole project** as bytes — every file under the Vite
+  root, PHP, Blade, JSON, SQL seeders and Markdown included — looking for
+  `<prefix>:<name>` where `<prefix>` is an installed set; what resolves in the
+  set's `icons.json` (icons and aliases) becomes a lazy chunk. Skipped:
+  whatever `.gitignore` ignores (every level), `node_modules`, `vendor`,
+  `storage`, the build `outDir`, every hidden path (`.something`), binary
+  files, and paths listed in `iconsScanner.exclude`. Extra locations
+  (`iconsScanner.include`) are additive. No language is parsed, so a Laravel
+  enum returning `'tabler:user-share'` counts as a literal.
+- **Dev is prod.** The same scan runs on dev start (once, cached by content
+  hash under `node_modules/.cache/bitboss-ui/`) and again per file on every
+  save, so the registry in dev is exactly the set the build emits. Typing a
+  new literal into a template renders it without a restart. An icon that is
+  neither scanned nor whitelisted therefore shows the placeholder and the
+  error on first render in dev — not after deploy.
+- **Names the scanner cannot see** — composed at runtime, persisted in a
+  database, picked by an admin — go in `iconWhitelist`: exact names
+  (`'tabler:crown'`) or globs (`'tabler:calendar-*'`). An entry that resolves
+  in no installed set fails the build with the same message the overlay shows.
+- **A missing name is loud, in both environments.** `BbIcon` renders the
+  built-in placeholder glyph with `data-bb-icon-missing="<requested name>"`
+  and logs one `console.error` per name per page load; dev adds the Vite
+  error overlay. A typo inside an installed set reads "does not exist in the
+  lucide icon set — did you mean `lucide:…`?"; a real icon nobody wrote as a
+  literal reads "exists in the lucide icon set but is not bundled … add it to
+  `iconWhitelist`"; a set that is not installed reads "no installed icon set
+  has the prefix `mdi` (installed sets: lucide) … run:
+  `npm install -D @iconify-json/mdi`". Read the message: a typo wants a
+  different name, an unscanned name wants the whitelist, a missing set wants
+  an install, never a guess.
 - **Local icons**: `iconDir` is scanned recursively; each `.svg` becomes
   `local:<basename-without-extension>`. A bare, unprefixed name normalizes to
   `local:`. Adding/removing files is picked up live in dev, and the plugin
@@ -256,8 +279,10 @@ markup) yourself:
   (slot content or `text`; `aria-label` only to override).
 - Inventing or guessing icon names; assuming a set is installed without
   checking `package.json`.
-- Runtime-composed icon names (template strings / concatenation) — invisible to
-  the build scanner, broken in production.
+- Runtime-composed icon names (template strings / concatenation) without a
+  matching `iconWhitelist` entry — invisible to the scanner, so they render the
+  placeholder (in dev too). Prefer a lookup of full literals; whitelist what
+  must stay dynamic.
 - Setting `color`/`fill` on the icon element instead of the parent.
 - Falling back to random provider sets when a needed `local:` asset is missing —
   ask for the SVG (or approval to substitute) instead.

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -221,7 +221,7 @@ Two runtime options control CSS:
 
 Guaranteed order when injected: **reset → library styles → all other stylesheets**, so app-local CSS can always override the library.
 
-`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary.
+`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary. A reset of SOME kind is a prerequisite of the components, not a nicety: every size in the component sheets is written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Preflight provides all of that; on a page with neither Preflight nor this file, a selectable table's fieldset grows a groove border and a 36px cell renders 49px. `reset.css` is optional only in the sense that you may bring your own — the component test suite runs against this file, with no Tailwind on the page.
 
 **Tailwind v4 cascade layers vs. scoped `<style>`:** Tailwind v4's `@import
 'tailwindcss'` puts every utility class in `@layer utilities`. A Vue SFC's
@@ -290,23 +290,193 @@ Leave `resetCss` at `false` here — Preflight already reset everything.
 Nothing else about the plugin changes; `injectStyles` controls only whether the
 library injects its own `<style>`.
 
-**Tailwind v4 apps do not need this** — source order does not decide their ties
-at all. `@import 'tailwindcss'` puts Preflight in a real `@layer base` and
-utilities in `@layer utilities`, and layered rules lose to unlayered rules of
-equal specificity **regardless of source order**. `dist/styles.css` declares no
-`@layer`, so the library wins those ties wherever it is injected: leave
-auto-injection on. The same mechanic bites the other way, and silently — a
-utility cannot re-size a Bb component either. `<BbButton class="h-12 px-6">`
-loses to the library's own `.bb-button { height: var(--h); padding-left:
-var(--px); padding-right: var(--px) }` (equal specificity, unlayered), with no
-warning from anything. Size Bb components through their props and tokens, never
-utilities. (Same trap as the scoped-`<style>` case above, one level up.)
+**Tailwind v4 apps do not need `injectStyles: false`** — source order does not
+decide their ties at all. `@import 'tailwindcss'` puts Preflight in a real
+`@layer base` and utilities in `@layer utilities`, and **a layered rule loses to
+an unlayered one regardless of source order**. Leave auto-injection on and use
+`cssLayers` below.
+
+### Cascade layers — the switch that decides who wins a tie
+
+The cascade weighs **layer before specificity**. Unlayered CSS beats every
+layered rule, however specific the layered one is. That one fact means there is
+no single correct default, so the option is opt-in and you tell the library
+where it sits:
+
+| your CSS                                     | `cssLayers`                         | who wins a tie                                 |
+| -------------------------------------------- | ----------------------------------- | ---------------------------------------------- |
+| no layers (plain CSS, Tailwind v3)           | unset (default)                     | source order — library first, so your CSS wins |
+| Tailwind v4, or any layered CSS              | your full order, ours in it (below) | exactly what your array says                   |
+| no layers, and you want to override anything | `['bitboss-ui']`                    | you do, always                                 |
+
+The value is always an array: your complete layer order with `bitboss-ui` in
+it, and `bitboss-ui-reset` immediately before it **when `resetCss` is on**.
+With the reset off you may list `bitboss-ui-reset` anyway — an unused layer is
+just empty — so the constant below works in every project, and you do not need
+to know that Tailwind carries a reset of its own to use it.
+
+**We do not ask you to add an `@layer` line to your stylesheet.** The plugin
+injects the declaration ahead of its own rules, and a layer's position is fixed
+by its first mention — so the order you configure is the order you get.
+
+#### Tailwind v4
+
+```ts
+// vite.config.ts — or the `bitboss` key in nuxt.config.ts
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: TAILWIND_V4_LAYERS,
+});
+```
+
+`TAILWIND_V4_LAYERS` is
+`['theme', 'base', 'bitboss-ui-reset', 'bitboss-ui', 'components', 'utilities']`:
+Tailwind's own order with ours **after `base`**, so Preflight cannot outrank
+the components, and **before `utilities`**, so `<BbButton class="px-6">`
+works. Prefer the constant to the literal — a six-item array that has to be
+exactly right is the kind of thing a typo turns into a silent loss of every
+tie.
+
+#### Tailwind v3, or plain CSS
+
+Leave `cssLayers` unset. v3 emits unlayered CSS, and two unlayered stylesheets
+are decided by source order — which auto-injection already puts in your favour.
+
+#### Tailwind v3 — making utilities win anyway (opt-in)
+
+v3 has no native layers of its own, but you can put its output into real ones
+by wrapping the directives yourself. This is the shape PrimeVue documents, and
+it is the only way to get v4's behaviour on v3:
+
+```css
+/* your Tailwind entry, e.g. app.css */
+@layer tailwind-base, bitboss-ui-reset, bitboss-ui, tailwind-utilities;
+
+@layer tailwind-base {
+	@tailwind base;
+}
+
+@layer tailwind-utilities {
+	@tailwind components;
+	@tailwind utilities;
+}
+```
+
+```ts
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: [
+		'tailwind-base',
+		'bitboss-ui-reset',
+		'bitboss-ui',
+		'tailwind-utilities',
+	],
+});
+```
+
+Both halves are required and they must agree: the CSS puts Tailwind's expanded
+output INTO the layers, and `cssLayers` puts us between them. Verified against
+a real v3 build — `.p-4` on a `Bb*` component wins, and Preflight no longer
+outranks the components.
+
+This is the one case where you write an `@layer` line yourself, because the
+line has to wrap YOUR directives and we cannot reach them. Ours is emitted as
+usual; the two declarations name the same order, and a layer's position is
+fixed by its first mention, so they agree rather than fight.
+
+#### "I just want to override things and not think about it"
+
+```ts
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: ['bitboss-ui'], // ['bitboss-ui-reset', 'bitboss-ui'] with resetCss: true
+});
+```
+
+Declares our layer(s) and nothing else. All of your unlayered CSS then wins,
+whatever its specificity.
+
+> **Do not use this if your app loads a baseline stylesheet.** A reset is
+> unlayered CSS made of element selectors, which is the exact combination this
+> value inverts: `normalize.css`, your own `baseline.css`, or **Tailwind v3's
+> Preflight** stop losing to our components on specificity and start outranking
+> them outright. Measured on a real v3 build, a component rule of
+> `margin: 5px` renders as `0px` — Preflight's `margin: 0` wins. The library
+> does not look "overridable", it looks broken: controls lose their height,
+> padding and borders, and nothing warns. If you want utilities to win on v3,
+> use the layer hack above, which keeps the reset below us where it belongs.
+
+Two further consequences: your global element rules (`button {}`, `input {}`)
+now outrank component internals too — and this is the **wrong** value for a
+layered app, because your own layers are declared later and land above ours,
+Preflight included. A Tailwind v4 app uses the array above.
+
+#### What "the utility loses" actually means
+
+Not "utilities stop working on `Bb*` components". The cascade picks a winner
+**per property**, so a layered utility loses only where we declare that exact
+property on that element. Anything we leave alone is uncontested and simply
+applies. Measured against the shipped sheet, v4 with `cssLayers` unset:
+
+| on a `BbButton` | outcome          | why                                   |
+| --------------- | ---------------- | ------------------------------------- |
+| `w-20`          | applies          | we never declare `width`              |
+| `h-12`          | applies          | we declare `min-height`, not `height` |
+| `m-4`           | applies          | we never declare `margin`             |
+| `p-4`           | **half applies** | top/bottom land, left/right lose      |
+| `px-6`          | no effect        | we declare both padding longhands     |
+| `rounded-lg`    | no effect        | we declare `border-radius`            |
+| `text-lg`       | no effect        | we declare `font-size`                |
+| `gap-2`         | no effect        | we declare `gap`                      |
+
+**The shorthand row is the one that hurts.** A clean loss is legible: you write
+`px-6`, nothing moves, you go looking. `p-4` expands to four longhands, we
+declare only the horizontal two, so their vertical padding applies while our
+horizontal survives — a component nobody designed, with no signal that anything
+was overridden.
+
+So `cssLayers` does not turn utilities from broken into working. It turns them
+from a per-property lottery into "always wins". **Predictability is the
+feature, not capability** — and it is why the fix is worth taking even in an app
+where the handful of utilities you tried happened to land.
+
+#### Symptoms and what they mean
+
+| what you see                                                          | cause                                                                           | fix                                                 |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------- |
+| a Tailwind utility on a `Bb*` component does nothing, or half-applies | v4 utilities are layered, the library is not — see the per-property table above | `cssLayers: TAILWIND_V4_LAYERS`                     |
+| every component lost its background / border                          | you listed only our two layers in a layered (v4) app                            | `cssLayers: TAILWIND_V4_LAYERS`                     |
+| your global `button {}` reset suddenly restyles component internals   | you listed only our two layers in an unlayered app                              | that is what it does — use the full order, or unset |
+| components lost their height / padding / borders on **v3**            | you listed only our layers while a reset or Preflight is unlayered              | use the v3 layer hack, or leave `cssLayers` unset   |
+| nothing changed after setting `cssLayers`                             | the option lives in the **build plugin**, not in `app.use()`                    | set it in `vite.config.ts` / `nuxt.config.ts`       |
+| build fails naming a layer                                            | your array omits `bitboss-ui` (or the reset layer with `resetCss: true`)        | the error prints a working array — copy it          |
+
+A malformed value **fails the build**, never the browser: a wrong layer order is
+invisible at runtime, because the CSS still parses and merely loses every tie.
+
+#### The one thing layers do not fix
+
+Layers decide ties between rules. They do not help when a component's own
+inline `style` sets a property, because inline styles beat every layer. Where a
+component needs to be positioned or sized by its parent, it exposes a CSS
+variable, and that hook works in every configuration:
+
+```html
+<!-- takes the row's slack; works on v3, v4, layered or not -->
+<BbBreadcrumbs class="min-w-0" style="--flex-grow: 1" :items="crumbs" />
+```
+
+Reach for the documented variable before reaching for a utility.
 
 ## 6) Icons
 
-- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
-- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. In dev, every `prefix:name` the registry does not know produces a Vite error overlay with the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon is a missing file in `iconDir` and surfaces as `BbIcon`'s runtime error naming it. Production builds report none of this — the scan simply drops what does not resolve, so a wrong name fails at runtime there.
-- Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
+- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`. **`local:` ships everything.**
+- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. **Providers ship only what is scanned or whitelisted**: the plugin reads the whole project as bytes — every file under the Vite root, PHP and Blade and JSON and SQL included — for `<prefix>:<name>` literals of the installed sets, and emits one lazy chunk per name that resolves. Skipped: gitignored paths (every `.gitignore` level), `node_modules`, `vendor`, `storage`, the build `outDir`, hidden paths, binaries, and `iconsScanner.exclude` globs; `iconsScanner.include` adds locations. The scan is cached by content hash under `node_modules/.cache/bitboss-ui/`, runs on 2–4 worker threads once a project passes ~1500 files (a cold scan is disk-bound, and the threads let a slow disk serve reads in parallel — roughly 0.2 s for 10k files on a laptop), prints one line (file count, elapsed, threads) after a cold scan, and stays silent when warm.
+- **This holds in dev exactly as in prod.** Dev registers the same scanned-plus-whitelisted set, re-scans a file on every save, and hot-updates the registry — a new literal renders without a restart, and a name that is neither scanned nor whitelisted fails on first render in dev instead of after deploy.
+- **Names the scanner cannot see** — composed at runtime, stored in a database, chosen in an admin UI — go in `iconWhitelist` (exact names or globs). An entry that resolves in no installed set fails the build with the actionable message.
+- **A name that does not resolve renders the built-in placeholder** (a question mark in a circle, sized and coloured like the icon it replaces, with `data-bb-icon-missing="<name>"`) and logs one `console.error` per name per page load, in both environments; dev also raises the Vite error overlay. The message is the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, a real icon nobody wrote as a literal is told to use `iconWhitelist`, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon names the `.svg` that is not in `iconDir`. `BbIcon` never throws for a missing name, so the surrounding tree stays mounted.
 - The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and (in dev, unless `vscodeSettings: false`) wires `.vscode/settings.json` so the Iconify editor extension previews local icons.
 
 Policy for choosing icons: [Icons Policy](./icons-policy.md).
@@ -317,7 +487,37 @@ Options are the same for `bitboss-ui/vite` and the `bitboss` key in Nuxt.
 
 ### `iconDir: string` (required)
 
-Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`.
+Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`. Every file in it ships.
+
+### `iconsScanner?: { include?: string[]; exclude?: string[]; maxFileSize?: number }`
+
+Tunes the provider-icon source scan (see [Icons](#6-icons)). All three are optional and additive to the defaults; the root is always scanned.
+
+- `include` — extra paths or globs scanned **in addition** to the Vite root: a vendor package that carries icon names, a directory outside the root (`'../shared/ui'`, `'vendor/acme/ui-kit/**/*.php'`). Relative entries resolve against the root. An entry is explicit, so the built-in skips (`vendor`, hidden segments, `.gitignore` files above it) do not apply to the entry itself — only to what lies beneath it. The Nuxt module adds the project `rootDir` here automatically, because Nuxt roots Vite at `app/`.
+- `exclude` — globs removed from the scan on top of the defaults, in gitignore syntax, relative to the root (`['resources/legacy/**', '**/*.sql']`).
+- `maxFileSize` — bytes. Exists only so a database dump is not read into memory; the default is 256 MiB, so a real source file is never skipped for its size.
+
+```ts
+bitbossUi({
+	iconDir: './resources/icons',
+	iconsScanner: {
+		include: ['vendor/acme/ui-kit/src'],
+		exclude: ['database/dumps/**'],
+	},
+});
+```
+
+### `iconWhitelist?: string[]`
+
+Provider icons that **always** ship, scanned or not — exact names (`'tabler:crown'`) and globs (`'tabler:calendar-*'`, expanded against the installed set). This is the home of every name the scanner cannot see as a literal: composed at runtime, read from a database, picked by an admin. An entry that resolves in no installed set — a typo, an uninstalled prefix, a glob matching nothing — **fails the build** with the same actionable message the dev overlay shows for a missing icon. `local:` names never belong here (they all ship already).
+
+```ts
+bitbossUi({
+	iconDir: './resources/icons',
+	// `icon` is stored per category in the database; the admin picks from these.
+	iconWhitelist: ['tabler:category', 'tabler:tag', 'tabler:calendar-*'],
+});
+```
 
 ### `injectStyles?: boolean` (default: `true`)
 
@@ -327,6 +527,28 @@ Auto-inject the library stylesheet at runtime. If `false`, you must `import 'bit
 
 Inject the reset stylesheet (always ordered before the library stylesheet). Keep `false` and import `bitboss-ui/reset.css` if you prefer explicit control.
 
+### `cssLayers?: string[]` (default: unset)
+
+Wraps the library's stylesheets in CSS cascade layers and declares where they
+sit. Opt-in. Full guide with copy-paste blocks in §5 → _Cascade layers_.
+
+The value is your app's **complete** layer order with `bitboss-ui` in it, and
+`bitboss-ui-reset` before it when `resetCss` is on (listing it anyway is fine).
+Unset means unlayered, today's behaviour, right for plain CSS and Tailwind v3.
+
+```ts
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
+// Tailwind v4 — ['theme', 'base', 'bitboss-ui-reset', 'bitboss-ui', 'components', 'utilities']
+cssLayers: TAILWIND_V4_LAYERS;
+// no layers of your own, and you want to override anything
+cssLayers: ['bitboss-ui']; // ['bitboss-ui-reset', 'bitboss-ui'] with resetCss: true
+```
+
+You do not add an `@layer` line to your own CSS — the plugin emits the
+declaration ahead of its rules. An invalid array, or a boolean, fails the build
+with a message containing a working replacement.
+
 ### `injectDirectives?: boolean` (default: `true`)
 
 Registers the global `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and `v-bb-time` directives when the runtime plugin installs — all five, on both the Vue and the Nuxt runtime. Each registration is skipped if the app already declared a directive under that name, so disable the option only if you want none of them.
@@ -534,6 +756,39 @@ says this in its header.
 | `dropdownItemVariants` | `default, destructive`                                  | `bb-dropdown__item--variant-<name>` |
 | `tooltipVariants`      | `default, destructive`                                  | `bb-tooltip--<name>`                |
 | `toastVariants`        | `default, success, info, warning, destructive`          | `bb-toast-message--<name>`          |
+| `inputVariants`        | `outline, secondary, ghost`                             | `common-input-wrapper--<name>`      |
+
+`inputVariants` is the `variant` prop of the eight text-like controls
+(`BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbTag`,
+`BbDatePickerInput`, `BbTimePickerInput`, `BbColorInput`). Its class hook is
+the shared field box, and a custom entry is a **token block, not a rule set**:
+the box's geometry (height, padding, border width) never changes with the
+variant, so a variant only assigns the look variables the box reads —
+
+```css
+/* a registered `inputVariants: ['brand']` */
+.common-input-wrapper--brand {
+	--bg: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
+	--bg-hover: color-mix(in oklab, var(--bb-primary) 12%, var(--bb-panel));
+	--bg-disabled: var(--bb-muted);
+	/* read `--state-border` to tint under errors/warnings like `outline`;
+	   leave it out to stay untinted like `ghost` */
+	--border-color: var(
+		--state-border,
+		color-mix(in oklab, var(--bb-primary) 40%, var(--bb-border))
+	);
+	--border-focus: var(--state-border, var(--bb-primary));
+	/* the focus ring: leave this out and the variant has none, like `none` */
+	--ring-size: var(--bb-ring-size);
+	/* what the box paints under the ring (ghost/secondary use their hover wash) */
+	--bg-focus: var(--bg-hover);
+}
+```
+
+The ring's **colour** is state-owned (primary, danger under errors, warn under
+warnings) and never a variant's business; whether a ring is **drawn** is the
+variant's call through `--ring-size` — the three built-ins draw it, `none` does
+not, and a custom variant chooses.
 
 Variant props are locked to the registered set (`keyof <X>VariantRegistry`):
 an unregistered name is a compile error, not a silently unstyled render.
@@ -564,10 +819,12 @@ when the contract cannot answer the question — the usual case is rebuilding
 chrome around a control the library does not ship, since the class names such a
 template emits are already styled by the public `bitboss-ui/styles.css`.
 
-Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
+Add `--mcp` to also register a live MCP server (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp` — the installed binary, not `npx`, so it can never fetch from the registry, its optional peers resolve in your project rather than in an npx cache, and it cannot drift behind an upgrade) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
 
 For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. One deliberate boundary: the rule's "did you mean `<prop>`?" hints for a mistyped/unknown attribute are advisory message text, not fixes — `eslint --fix` (including an unattended run in a pre-commit hook) never applies them; only the registered v2→v3 migrations above are auto-fixed. A guess applied blind across a codebase would be a silent behavior change, so acting on a hint is always a per-site decision. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
 
+Two rules in `recommended` are `warn` rather than `error`, because each describes markup that may be deliberate. `bitboss-ui/no-unknown-event` flags an `@event` the component does not emit (it falls through to the root element, so it may be a considered native listener). `bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the installed package does not declare, in a `<style>` block or a static `style="…"` attribute — an undefined custom property is invalid-at-computed-value-time, so CSS discards the **entire declaration** and the rule silently does nothing at runtime. Supplying a fallback (`var(--bb-canvas, #f8fafc)`) is defined behaviour and is never reported; `allowTokens` exempts names you define yourself. The token list is read from the `dist/styles.css` you installed, so it cannot claim a token is invented when your version declares it, and with no stylesheet present the rule stays silent. Before reaching for a `--bb-*` name at all, re-read the two tiers above: a name the library does not declare usually means the knob you want is a **component** token, not a gap in the global set. `bitboss-ui check` carries two further advisory hints that are deliberately not ESLint rules — the hand-rolled avatar and spinner detectors — because both are guesses, and a lint rule that fires on correct code teaches people to ignore all of them.
+
 **The manifest ships with the package** — `dist/ai/components.json` is inside
 the tarball, and the rules resolve it relative to their own file, so a normal
 install needs no configuration. If it ever cannot be read (a broken install, a
@@ -576,6 +833,18 @@ nothing), the rules cannot check anything: they now **warn once** saying they
 are inactive rather than passing silently. Pass `failClosed: true` to a rule's
 options if you would rather CI stop than under-check.
 
+Alongside `components` the manifest carries a `types` array: the public TYPE
+exports (`BbTableColumn`, `BbDropdownItem`, …), each with the component and prop
+it is written on. That is how `check`, the ESLint rules and the MCP server tell
+a type used as a tag from a typo and from a component your app owns — three
+cases that used to share one message and one (usually wrong) remedy.
+
+**`allowComponents` is a per-tag off switch, not the suppression of one
+message.** An allowlisted name is skipped whole: no unknown-component finding,
+and no prop, event, v-model or slot check on that tag, permanently. Right for an
+app-owned `<BbRichEditor>`; wrong for everything else — never reach for it to
+quieten a `Bb*` name the library itself exports.
+
 `recommended` also enables **`bitboss-ui/no-reverse-false`**, which covers the one v2 break a rename table cannot: `reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its NAME and inverted its MEANING in v3, so the v2 spelling `:reverse="false"` (control on the right) is now a no-op that renders the control on the LEFT. Nothing else catches it — it is a declared prop, correctly typed, holding its own default value — and it cannot be expressed as a rename, because a rename entry is keyed by prop name and would rewrite the legitimate v3 spellings too. The rule flags only a LITERAL `:reverse="false"` (a dynamic `:reverse="isRtl"` that evaluates false is left alone) and offers both corrections as editor suggestions; pass `{ assumeV2: true }` to promote the v2-intent rewrite to a real `--fix` for a bulk sweep, then remove it — the two readings produce opposite layouts, so it must never be on by default. See [the migration guide](../guides/migration/components/bb-checkbox.md).
 
 It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without its documented required partner — BbTable `keyboard-navigation` / `v-model:highlighted` without `row-class` (the shipped tint says "current row"; `row-class` says why, and is how you override it), or `loading-text` without `:loading` bound — compiles and mounts clean and just does nothing; the rule names the missing partner and quotes why.

package/dist/ai/guides/migration/components/bb-rating.md

@@ -76,6 +76,31 @@ override off `:root` and onto the block — the value itself is yours to keep:
 
 Set it on `.bb-base-rating` itself (or on a rule that also matches it) — the
 local is declared on that block, so a value inherited from an ancestor is
-overridden before it is read. `--spacing` (star gap) is the companion local;
+overridden before it is read. `--space` (star gap) is the companion local;
 v2's `--bb-base-rating-spacing` was referenced but never declared anywhere in
 the shipped sheet, so it never worked.
+
+### `--spacing` → `--space` (hard rename, no alias)
+
+The star-gap local was called `--spacing` until 2026-09-09. **Tailwind v4 built
+its entire spacing scale on a variable of that exact name** — `p-4` compiles to
+`padding: calc(var(--spacing) * 4)`, where v3 emitted a literal `1rem`. Custom
+properties inherit, so `--spacing: 0px` on `.bb-base-rating` silently zeroed
+**every** spacing utility a Tailwind v4 app used inside the component's slots:
+
+```html
+<!-- on Tailwind v4, before the rename: padding, gap and size all resolved to 0 -->
+<BbRating>
+	<template #icon><Icon class="size-5 p-1" /></template>
+</BbRating>
+```
+
+If you overrode the gap, rename the property. The value is unchanged:
+
+```diff
+- .bb-base-rating { --spacing: 4px; }
++ .bb-base-rating { --space: 4px; }
+```
+
+Nothing else changes. `--space` is not a Tailwind theme namespace, so it cannot
+collide the same way.

package/dist/ai/guides/migration/components/bb-tooltip.md

@@ -15,6 +15,7 @@ summary: timeout renamed to delay; theme replaced by typed variant; hideArrow is
 | `activator` / `boundary` loose types   | `ElementOrComponentRef*`                                                   | transparent in templates                                                                                              |
 | `showClose?: boolean` (default `true`) | removed                                                                    | **the tooltip has no close button.** ⚠ Do **not** rewrite to `hide-close` — that prop does not exist here. Delete it. |
 | `block`                                | removed                                                                    | dead prop — it styled nothing (same as `BbPopover.block`)                                                             |
+| `width` = a fixed bubble width         | `width` = a **maximum** width (default cap `40ch`)                         | behavior change — same prop name, see below                                                                           |
 | —                                      | `modelValue` + `update:modelValue`                                         | additive — a tooltip can now be opened/closed programmatically                                                        |
 
 The tooltip is the **only** surface that kept its arrow — popovers, selects,
@@ -43,6 +44,23 @@ If you were passing `:show-close="false"` you already had the v3 behaviour —
 deleting the prop changes nothing visually. `npx bitboss-ui check` flags both
 spellings and names this file.
 
+### `width` caps the bubble instead of fixing it
+
+In v2 `width` set the bubble's width outright, so `:width="300"` on a 150px
+hint left half the bubble empty. In v3 it compiles to `max-width`: the bubble
+wraps at that measure but still shrinks to its text. Nothing to rewrite — the
+prop keeps its name and its values, and long hints look the same. Short ones
+get narrower, which is the point.
+
+Two consequences worth knowing:
+
+- A tooltip with **no** `width` is now capped at `40ch` rather than running the
+  full width of the viewport. Override it in CSS with `--max-w` on
+  `.bb-tooltip` (or per instance with the prop).
+- Values v2 mis-parsed now work. `'20rem'` used to render a 20**px** bubble;
+  `'auto'` and `calc()`/`min()` values threw during render. All of them are
+  passed to CSS as written.
+
 ## Edits
 
 ```diff