bitboss-ui 3.0.0-beta.0 → 3.0.0-beta.2

package/dist/llms-full.txt

@@ -6,16 +6,16 @@
 **This file is for bulk ingestion — search indexes, embeddings, offline
 evaluation. It is far larger than a useful prompt.** If you are an agent
 about to write code, do NOT read this. Fetch
-`https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt` instead, then hop to the one
+`https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt` instead, then hop to the one
 component contract you need.
 
-Canonical URL: https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt
-Index: https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt
+Canonical URL: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-full.txt
+Index: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/llms.txt
 
 ---
 
 <!-- dist/ai/BbAccordion.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbAccordion.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAccordion.md -->
 
 # BbAccordion
 
@@ -570,7 +570,7 @@ is generated for you.
 ---
 
 <!-- dist/ai/BbAlert.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbAlert.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAlert.md -->
 
 # BbAlert
 
@@ -993,7 +993,7 @@ const publish = () => {
 ---
 
 <!-- dist/ai/BbAsterisk.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbAsterisk.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAsterisk.md -->
 
 # BbAsterisk
 
@@ -1045,7 +1045,7 @@ doesn't suit the layout; the glyph inherits nothing else from its surroundings.
 ---
 
 <!-- dist/ai/BbAvatar.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbAvatar.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAvatar.md -->
 
 # BbAvatar
 
@@ -1566,7 +1566,7 @@ available in visible text or an adjacent label.
 ---
 
 <!-- dist/ai/BbBadge.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBadge.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBadge.md -->
 
 # BbBadge
 
@@ -2304,7 +2304,7 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 ---
 
 <!-- dist/ai/BbBadgeButton.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBadgeButton.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBadgeButton.md -->
 
 # BbBadgeButton
 
@@ -2377,7 +2377,7 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 ---
 
 <!-- dist/ai/BbBaseButton.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseButton.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseButton.md -->
 
 # BbBaseButton
 
@@ -2896,7 +2896,7 @@ const sent = ref(false);
 ---
 
 <!-- dist/ai/BbBaseCheckbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseCheckbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckbox.md -->
 
 # BbBaseCheckbox
 
@@ -2951,7 +2951,7 @@ const sent = ref(false);
 ---
 
 <!-- dist/ai/BbBaseCheckboxGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseCheckboxGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckboxGroup.md -->
 
 # BbBaseCheckboxGroup
 
@@ -3021,7 +3021,7 @@ const sent = ref(false);
 ---
 
 <!-- dist/ai/BbBaseCheckboxIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseCheckboxIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckboxIcon.md -->
 
 # BbBaseCheckboxIcon
 
@@ -3203,7 +3203,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseColorInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseColorInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseColorInput.md -->
 
 # BbBaseColorInput
 
@@ -3274,7 +3274,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseColorPalette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseColorPalette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseColorPalette.md -->
 
 # BbBaseColorPalette
 
@@ -3319,7 +3319,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseDatePicker.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseDatePicker.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseDatePicker.md -->
 
 # BbBaseDatePicker
 
@@ -3368,7 +3368,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseDatePickerInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseDatePickerInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseDatePickerInput.md -->
 
 # BbBaseDatePickerInput
 
@@ -3447,7 +3447,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseInputContainer.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseInputContainer.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseInputContainer.md -->
 
 # BbBaseInputContainer
 
@@ -3501,7 +3501,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseNumberInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseNumberInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseNumberInput.md -->
 
 # BbBaseNumberInput
 
@@ -3578,7 +3578,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseRadio.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseRadio.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadio.md -->
 
 # BbBaseRadio
 
@@ -3630,7 +3630,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseRadioGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseRadioGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadioGroup.md -->
 
 # BbBaseRadioGroup
 
@@ -3700,7 +3700,7 @@ on the element (or an ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseRadioIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseRadioIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadioIcon.md -->
 
 # BbBaseRadioIcon
 
@@ -3897,7 +3897,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseRating.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseRating.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRating.md -->
 
 # BbBaseRating
 
@@ -3955,7 +3955,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseSelect.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseSelect.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSelect.md -->
 
 # BbBaseSelect
 
@@ -4049,7 +4049,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseSlider.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseSlider.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSlider.md -->
 
 # BbBaseSlider
 
@@ -4111,7 +4111,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseSwitch.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseSwitch.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitch.md -->
 
 # BbBaseSwitch
 
@@ -4166,7 +4166,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseSwitchGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseSwitchGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitchGroup.md -->
 
 # BbBaseSwitchGroup
 
@@ -4236,7 +4236,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseSwitchIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseSwitchIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitchIcon.md -->
 
 # BbBaseSwitchIcon
 
@@ -4428,7 +4428,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseTag.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseTag.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTag.md -->
 
 # BbBaseTag
 
@@ -4502,7 +4502,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseTextarea.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseTextarea.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTextarea.md -->
 
 # BbBaseTextarea
 
@@ -4570,7 +4570,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseTextInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseTextInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTextInput.md -->
 
 # BbBaseTextInput
 
@@ -4651,7 +4651,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBaseTimePickerInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBaseTimePickerInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTimePickerInput.md -->
 
 # BbBaseTimePickerInput
 
@@ -4719,7 +4719,7 @@ ancestor — they inherit):
 ---
 
 <!-- dist/ai/BbBreadcrumbs.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbBreadcrumbs.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBreadcrumbs.md -->
 
 # BbBreadcrumbs
 
@@ -5310,7 +5310,7 @@ overflow calculation runs after hydration once real widths exist.
 ---
 
 <!-- dist/ai/BbButton.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbButton.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbButton.md -->
 
 # BbButton
 
@@ -6265,7 +6265,7 @@ Anti-patterns:
 ---
 
 <!-- dist/ai/BbCheckbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbCheckbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCheckbox.md -->
 
 # BbCheckbox
 
@@ -6881,7 +6881,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbCheckboxGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbCheckboxGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCheckboxGroup.md -->
 
 # BbCheckboxGroup
 
@@ -7481,7 +7481,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbCollapsible.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbCollapsible.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCollapsible.md -->
 
 # BbCollapsible
 
@@ -7927,7 +7927,7 @@ const active = ref<DetailTab | null>('specs');
 ---
 
 <!-- dist/ai/BbColorInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbColorInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbColorInput.md -->
 
 # BbColorInput
 
@@ -8503,7 +8503,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbColorPalette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbColorPalette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbColorPalette.md -->
 
 # BbColorPalette
 
@@ -9133,7 +9133,7 @@ styling (a caret, a highlight). Two props gate interaction:
 ---
 
 <!-- dist/ai/BbConfirm.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbConfirm.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbConfirm.md -->
 
 # BbConfirm
 
@@ -9822,7 +9822,7 @@ standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 ---
 
 <!-- dist/ai/BbConfirmPortal.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbConfirmPortal.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbConfirmPortal.md -->
 
 # BbConfirmPortal
 
@@ -9856,7 +9856,7 @@ standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 ---
 
 <!-- dist/ai/BbDatePicker.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDatePicker.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDatePicker.md -->
 
 # BbDatePicker
 
@@ -10172,7 +10172,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 ---
 
 <!-- dist/ai/BbDatePickerInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDatePickerInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDatePickerInput.md -->
 
 # BbDatePickerInput
 
@@ -10963,7 +10963,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbDialog.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDialog.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDialog.md -->
 
 # BbDialog
 
@@ -11777,7 +11777,7 @@ default falls back to `config.adaptive`.
 ---
 
 <!-- dist/ai/BbDropdown.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDropdown.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdown.md -->
 
 # BbDropdown
 
@@ -12930,7 +12930,7 @@ mid-session never swaps a live menu between flyout and sheet.
 ---
 
 <!-- dist/ai/BbDropdownButton.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDropdownButton.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdownButton.md -->
 
 # BbDropdownButton
 
@@ -13490,7 +13490,7 @@ the split control) and `boundary`.
 ---
 
 <!-- dist/ai/BbDropdownGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDropdownGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdownGroup.md -->
 
 # BbDropdownGroup
 
@@ -13530,7 +13530,7 @@ the split control) and `boundary`.
 ---
 
 <!-- dist/ai/BbDropzone.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbDropzone.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropzone.md -->
 
 # BbDropzone
 
@@ -14909,7 +14909,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbForm.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbForm.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbForm.md -->
 
 # BbForm
 
@@ -15154,7 +15154,7 @@ marker stays consistent with the rules.
 ---
 
 <!-- dist/ai/BbIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbIcon.md -->
 
 # BbIcon
 
@@ -15572,7 +15572,7 @@ wrapping it.
 ---
 
 <!-- dist/ai/BbIndicator.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbIndicator.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbIndicator.md -->
 
 # BbIndicator
 
@@ -15861,7 +15861,7 @@ const onClear = () => {
 ---
 
 <!-- dist/ai/BbNumberInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbNumberInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbNumberInput.md -->
 
 # BbNumberInput
 
@@ -16603,7 +16603,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbOffCanvas.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbOffCanvas.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbOffCanvas.md -->
 
 # BbOffCanvas
 
@@ -17573,7 +17573,7 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 ---
 
 <!-- dist/ai/BbPagination.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbPagination.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbPagination.md -->
 
 # BbPagination
 
@@ -18102,7 +18102,7 @@ reach invalid pages.
 ---
 
 <!-- dist/ai/BbPopover.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbPopover.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbPopover.md -->
 
 # BbPopover
 
@@ -18755,7 +18755,7 @@ falls back to `config.adaptive`.
 ---
 
 <!-- dist/ai/BbProgress.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbProgress.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbProgress.md -->
 
 # BbProgress
 
@@ -19250,7 +19250,7 @@ What's still on you:
 ---
 
 <!-- dist/ai/BbRadio.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbRadio.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRadio.md -->
 
 # BbRadio
 
@@ -19645,7 +19645,7 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
 ---
 
 <!-- dist/ai/BbRadioGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbRadioGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRadioGroup.md -->
 
 # BbRadioGroup
 
@@ -20205,7 +20205,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbRating.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbRating.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRating.md -->
 
 # BbRating
 
@@ -20602,7 +20602,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbSelect.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSelect.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSelect.md -->
 
 # BbSelect
 
@@ -22053,7 +22053,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbSelectPopover.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSelectPopover.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSelectPopover.md -->
 
 # BbSelectPopover
 
@@ -23461,7 +23461,7 @@ floating popover everywhere.
 ---
 
 <!-- dist/ai/BbSlider.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSlider.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSlider.md -->
 
 # BbSlider
 
@@ -23987,7 +23987,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbSmoothHeight.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSmoothHeight.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSmoothHeight.md -->
 
 # BbSmoothHeight
 
@@ -24505,7 +24505,7 @@ const expanded = ref(false);
 ---
 
 <!-- dist/ai/BbSpinner.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSpinner.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSpinner.md -->
 
 # BbSpinner
 
@@ -25251,7 +25251,7 @@ in `role="status"` with that text rendered `sr-only`. Prefer `BbButton`'s
 ---
 
 <!-- dist/ai/BbSwitch.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSwitch.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSwitch.md -->
 
 # BbSwitch
 
@@ -25861,7 +25861,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbSwitchGroup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbSwitchGroup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSwitchGroup.md -->
 
 # BbSwitchGroup
 
@@ -26407,7 +26407,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbTable.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTable.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTable.md -->
 
 # BbTable
 
@@ -28675,7 +28675,7 @@ records list.
 ---
 
 <!-- dist/ai/BbTabs.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTabs.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabs.md -->
 
 # BbTabs
 
@@ -29862,7 +29862,7 @@ route, so it is SSR-safe and shareable:
 ---
 
 <!-- dist/ai/BbTabsList.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTabsList.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsList.md -->
 
 # BbTabsList
 
@@ -29897,7 +29897,7 @@ route, so it is SSR-safe and shareable:
 ---
 
 <!-- dist/ai/BbTabsPanes.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTabsPanes.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsPanes.md -->
 
 # BbTabsPanes
 
@@ -29930,7 +29930,7 @@ route, so it is SSR-safe and shareable:
 ---
 
 <!-- dist/ai/BbTabsRoot.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTabsRoot.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsRoot.md -->
 
 # BbTabsRoot
 
@@ -29993,7 +29993,7 @@ route, so it is SSR-safe and shareable:
 ---
 
 <!-- dist/ai/BbTag.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTag.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTag.md -->
 
 # BbTag
 
@@ -30437,7 +30437,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbTextarea.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTextarea.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTextarea.md -->
 
 # BbTextarea
 
@@ -31316,7 +31316,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbTextInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTextInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTextInput.md -->
 
 # BbTextInput
 
@@ -32262,7 +32262,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbTimePicker.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTimePicker.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTimePicker.md -->
 
 # BbTimePicker
 
@@ -32499,7 +32499,7 @@ typeahead. Always pass a `label` when the trigger is an unlabelled cell or icon.
 ---
 
 <!-- dist/ai/BbTimePickerInput.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTimePickerInput.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTimePickerInput.md -->
 
 # BbTimePickerInput
 
@@ -32707,7 +32707,7 @@ Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` bin
 ---
 
 <!-- dist/ai/BbToast.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbToast.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbToast.md -->
 
 # BbToast
 
@@ -33412,7 +33412,7 @@ see the `useSafeArea` composable doc.
 ---
 
 <!-- dist/ai/BbToastPortal.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbToastPortal.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbToastPortal.md -->
 
 # BbToastPortal
 
@@ -33446,7 +33446,7 @@ see the `useSafeArea` composable doc.
 ---
 
 <!-- dist/ai/BbTooltip.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTooltip.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTooltip.md -->
 
 # BbTooltip
 
@@ -33934,7 +33934,7 @@ const files: SharedFile[] = [
 ---
 
 <!-- dist/ai/BbTree.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/BbTree.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTree.md -->
 
 # BbTree
 
@@ -34989,7 +34989,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/ChipsBox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/ChipsBox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ChipsBox.md -->
 
 # ChipsBox
 
@@ -35033,7 +35033,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/ClearableButton.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/ClearableButton.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ClearableButton.md -->
 
 # ClearableButton
 
@@ -35062,7 +35062,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/CommaBox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/CommaBox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommaBox.md -->
 
 # CommaBox
 
@@ -35104,7 +35104,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/CommonInputWrapper.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/CommonInputWrapper.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommonInputWrapper.md -->
 
 # CommonInputWrapper
 
@@ -35152,7 +35152,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/CommonPopover.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/CommonPopover.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommonPopover.md -->
 
 # CommonPopover
 
@@ -35199,7 +35199,7 @@ row) with that in mind.
 ---
 
 <!-- dist/ai/composables/useBbConfig.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useBbConfig.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbConfig.md -->
 
 # useBbConfig
 
@@ -35348,7 +35348,7 @@ hydration, so the very first paint still renders in the default locale.
 ---
 
 <!-- dist/ai/composables/useBbFormContext.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useBbFormContext.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbFormContext.md -->
 
 # useBbFormContext
 
@@ -35458,7 +35458,7 @@ stays the only place the work happens.
 ---
 
 <!-- dist/ai/composables/useBbTableContext.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useBbTableContext.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbTableContext.md -->
 
 # useBbTableContext
 
@@ -35625,7 +35625,7 @@ const deleteSelected = async () => {
 ---
 
 <!-- dist/ai/composables/useBbTabsContext.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useBbTabsContext.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbTabsContext.md -->
 
 # useBbTabsContext
 
@@ -35743,7 +35743,7 @@ const { current, goTo, isLast } = useBbTabsContext<
 ---
 
 <!-- dist/ai/composables/useConfirm.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useConfirm.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useConfirm.md -->
 
 # useConfirm
 
@@ -36056,7 +36056,7 @@ content by name and render nothing themselves.
 ---
 
 <!-- dist/ai/composables/useCountdown.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useCountdown.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useCountdown.md -->
 
 # useCountdown
 
@@ -36142,7 +36142,7 @@ const { remainingFormatted, progress, running, paused, start, pause, reset } =
 ---
 
 <!-- dist/ai/composables/useId.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useId.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useId.md -->
 
 # useId
 
@@ -36202,7 +36202,7 @@ const { id } = useId();
 ---
 
 <!-- dist/ai/composables/useMobile.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useMobile.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useMobile.md -->
 
 # useMobile
 
@@ -36287,7 +36287,7 @@ const filters = ref({ status: 'active' });
 ---
 
 <!-- dist/ai/composables/useSafeArea.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useSafeArea.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useSafeArea.md -->
 
 # useSafeArea
 
@@ -36450,7 +36450,7 @@ useSafeArea({ side: 'right', element: sidebar });
 ---
 
 <!-- dist/ai/composables/useToast.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/composables/useToast.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useToast.md -->
 
 # useToast
 
@@ -36688,7 +36688,7 @@ const id = toast({
 ---
 
 <!-- dist/ai/ErrorIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/ErrorIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ErrorIcon.md -->
 
 # ErrorIcon
 
@@ -36715,7 +36715,7 @@ const id = toast({
 ---
 
 <!-- dist/ai/FlatListBox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/FlatListBox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/FlatListBox.md -->
 
 # FlatListBox
 
@@ -36759,7 +36759,7 @@ const id = toast({
 ---
 
 <!-- dist/ai/GroupedListBox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/GroupedListBox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/GroupedListBox.md -->
 
 # GroupedListBox
 
@@ -36805,7 +36805,7 @@ const id = toast({
 ---
 
 <!-- dist/ai/guides/agent-contract.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/agent-contract.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/agent-contract.md -->
 
 # Agent Contract
 
@@ -37063,7 +37063,7 @@ case is not decidable from markup and has no hint.
 ---
 
 <!-- dist/ai/guides/ai-router.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/ai-router.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/ai-router.md -->
 
 # AI Router
 
@@ -37077,9 +37077,9 @@ Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
 Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.
 
 **Not installed, or can only fetch URLs?** The same files are served from the
-published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/…`.
+published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/…`.
 If you can make only one request, fetch
-[`…@alpha/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt)
+[`…@beta/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt)
 — this router plus the agent contract, setup, component picker, design language
 and the full component catalogue, in ~110 KB.
 
@@ -37182,7 +37182,7 @@ nothing else); the command names them if they are missing.
 ---
 
 <!-- dist/ai/guides/app-layout.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/app-layout.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/app-layout.md -->
 
 # App Layout
 
@@ -37549,7 +37549,7 @@ const footer = [
 ---
 
 <!-- dist/ai/guides/coherence-playbook.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/coherence-playbook.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/coherence-playbook.md -->
 
 # Coherence Playbook
 
@@ -37686,7 +37686,7 @@ Only for rules the `items` + `dependencies` contract cannot express — cross-co
 ---
 
 <!-- dist/ai/guides/component-picker.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/component-picker.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/component-picker.md -->
 
 # Component Picker
 
@@ -37961,7 +37961,7 @@ See:
 ---
 
 <!-- dist/ai/guides/design-language.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/design-language.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-language.md -->
 
 # Design Language
 
@@ -38545,7 +38545,7 @@ text, `--bb-label-weight`
 ---
 
 <!-- dist/ai/guides/design-tokens.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/design-tokens.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-tokens.md -->
 
 # Design Tokens
 
@@ -38968,12 +38968,40 @@ scope (`.brand { --bb-primary: … }`) does not re-derive them — re-apply the
 `light`/`dark` class on that scope, or override the derived tokens directly.
 Root-level theming (what the theme builder emits) is unaffected.
 
-### Animated themes
+### Registered knobs (`@property`)
 
-The color knobs (and `--bb-ring-opacity`) are registered with `@property`
-(typed `<color>`, `inherits: true`), which makes them **animatable** and
-fail-soft (an invalid `--bb-panel` falls back to the registered initial
-value instead of detonating every derivation). Add `.theme-animated`
+Nine tokens are registered in `variables.css`: the eight color knobs with
+`syntax: '<color>'`, and `--bb-ring-opacity` with `syntax: '<percentage>'`.
+All are `inherits: true`.
+
+**Registration types them, and a typed property rejects.** A declaration that
+does not parse as the declared syntax is invalid at computed-value time — the
+value is discarded, and because these inherit, an override at `:root` (no
+parent to inherit from) lands on the registered `initial-value`. That is the
+fail-soft half: an unparseable `--bb-panel` falls back instead of detonating
+every derivation that mixes it. It is also the trap. Write
+
+```css
+:root {
+	--bb-ring-opacity: 0.15;
+} /* wrong: not a <percentage> */
+```
+
+and nothing errors — not the build, not the console. The computed value is
+just `25%`, and every ring paints 1.67× stronger than the `15%` you asked for
+(opacity is the ring's strength; its thickness is `--bb-ring-size`).
+Percentages need the `%`; colors must be a `<color>` (`transparent` and
+`currentColor` qualify, `none` and a mistyped hex do not). Nothing in the
+toolchain catches it either: `bitboss-ui check` reads `.vue`/`.md`, never
+stylesheets.
+
+Fail-soft is only soft when the initial value is close to the real one. Every
+color knob is registered at its light default, so a rejected color override
+renders the library's own light theme. `--bb-ring-opacity` is registered at
+`25%`, which matches neither shipped scope (light `15%`, dark `40%`), so a
+rejected value there is the one that shows.
+
+Typed knobs are also **animatable**. Add `.theme-animated`
 (main.css) to the element that carries the scheme class or theme overrides:
 
 ```html
@@ -39114,7 +39142,7 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `color-mix(in srgb, …)`                                                                                                                                          | `color-mix(in oklab, …)` everywhere                                          |
 | dialog/offcanvas `--radius-multiplier` ×1.8, literal `6px`/`8px`/`0.375rem` radii                                                                                | `--bb-radius-surface` / `--bb-radius-sm`                                     |
 | `--bb-contrasting`                                                                                                                                               | `--bb-primary-fg`                                                            |
-| `--bb-easing-bezier`                                                                                                                                             | `--bb-ease`                                                                  |
+| hard-coded `cubic-bezier()` literals (v2 exposed no easing token)                                                                                                | `--bb-ease`                                                                  |
 | `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                 | `--bb-muted`                                                                 |
 | `--bb-muted-color`, `--bb-hint`, `--bb-placeholder`, `--bb-icon-color`, `--bb-prefix-color`                                                                      | `--bb-text-muted`                                                            |
 | `--bb-input-color`, `--bb-input-bg`                                                                                                                              | `--bb-text`, `--bb-panel`                                                    |
@@ -39131,6 +39159,18 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
 | `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |
 
+**This table maps names, not values.** A token that is absent from it survived
+the rename — which is not the same as surviving unchanged. Six kept their v2
+name and their global scope and moved default anyway (input height, input
+vertical padding, prefix column width, label weight, ring size, leading); the
+before/after numbers are tabled in the v2→v3 migration guide, §3. The rule
+generalizes past this migration: a `--bb-*` name is a slot in the derivation
+graph, not a promise about the number in it. An override you carried forward
+keeps working and keeps your old look; an override you deleted because "the
+name still exists" hands you whatever `variables.css` declares today. Check
+each survivor against `variables.css` and delete only the ones that were
+restating a default.
+
 ## Enforcement
 
 `npm run check:tokens` (see `scripts/check-tokens.mjs`) fails the build when:
@@ -39174,7 +39214,7 @@ like it would replace the seal rule structurally, but it breaks the system:
 ---
 
 <!-- dist/ai/guides/fetch-items-playbook.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/fetch-items-playbook.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/fetch-items-playbook.md -->
 
 # Fetch Data Items Playbook
 
@@ -39338,7 +39378,7 @@ const fetchInvoices = async (): Promise<Invoice[]> => {
 ---
 
 <!-- dist/ai/guides/floating-bottom-panel.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/floating-bottom-panel.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/floating-bottom-panel.md -->
 
 # Floating Bottom Panel
 
@@ -39469,7 +39509,7 @@ destructive path and clearing the selection after a bulk action.
 ---
 
 <!-- dist/ai/guides/icons-policy.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/icons-policy.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/icons-policy.md -->
 
 # Icons Policy
 
@@ -39727,7 +39767,7 @@ markup) yourself:
 ---
 
 <!-- dist/ai/guides/inertia-helpers.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/inertia-helpers.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/inertia-helpers.md -->
 
 # Inertia Helpers
 
@@ -41347,7 +41387,7 @@ export const useUntil = <T = boolean, U = boolean>(
 ---
 
 <!-- dist/ai/guides/inline-edit-playbook.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/inline-edit-playbook.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/inline-edit-playbook.md -->
 
 # Inline Edit Playbook
 
@@ -41689,7 +41729,7 @@ about_ the record rather than a _decision on_ it, leave it alone.
 ---
 
 <!-- dist/ai/guides/installation-and-plugin-setup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/installation-and-plugin-setup.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/installation-and-plugin-setup.md -->
 
 # Installation and Plugin Setup
 
@@ -41701,16 +41741,21 @@ Source of truth for integrating `bitboss-ui`. Two pieces are always required:
 ## 1) Install
 
 ```bash
-# v3 is a prerelease — the `@alpha` tag is REQUIRED.
+# v3 is a prerelease — a dist-tag is REQUIRED.
 # A bare `npm install bitboss-ui` still resolves to v2, which has no build
 # plugin and no `dist/ai` knowledge base, so everything below silently fails.
-npm install bitboss-ui@alpha
+npm install bitboss-ui@beta
 # recommended default icon set (any @iconify-json/* works)
 npm install -D @iconify-json/lucide
 ```
 
 Confirm you got v3 before continuing — `npm ls bitboss-ui` must report a
-`3.0.0-alpha.*` version. If it reports `2.x`, nothing in this guide applies.
+`3.0.0-*` version. If it reports `2.x`, nothing in this guide applies.
+
+**`@beta` is the current v3 channel.** `@alpha` still resolves, but it is
+frozen at the last alpha and does not receive fixes — it is not simply an older
+copy of the same line. `@latest` is the **v2** line and always will be until v3
+goes stable, so never reach for it here.
 
 Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.
 
@@ -41907,6 +41952,48 @@ import 'bitboss-ui/styles.css';
 import 'bitboss-ui/reset.css';
 ```
 
+**Exception — an app that needs its own CSS to load _before_ the library.**
+Auto-injection is library-first and not configurable: the runtime plugin
+inserts its `<style>` **before the first** `style`/`link[rel="stylesheet"]`
+already in `<head>` (`src/utils/injectLibraryStyles.ts`), so the guaranteed
+order above is exactly what you get and every app stylesheet — your Tailwind
+entry included — lands after the library. There is no option to inject later.
+
+That is the order most apps want. It is the wrong order if you need library
+rules to beat Tailwind's Preflight **by source order**, which is the case on
+**Tailwind v3**: `@tailwind base` compiles to ordinary unlayered CSS, so under
+auto-injection Preflight sits after the library sheet and its element resets
+(`button`, `input`, `h1`, …) win every equal-specificity tie. `injectStyles:
+false` + `resetCss: false` (the default) disables injection entirely and hands
+you the order:
+
+```ts
+// vite.config.ts / the `bitboss` key in nuxt.config.ts
+bitbossUi({ iconDir: '…', injectStyles: false, resetCss: false });
+```
+
+```ts
+// app entry — order is yours now
+import './app.css'; // your Tailwind entry
+import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
+```
+
+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.)
+
 ## 6) Icons
 
 - `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
@@ -41948,6 +42035,15 @@ When `true`, the **dev server** adds `./node_modules/.bitboss-ui/local-icons.jso
 
 When `true`, the **dev server** registers the bitboss-ui MCP server in each project-scoped agent-harness config on boot — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code / Copilot) — so agents can query the knowledge base with no manual setup. The write is merge-safe (leaves other servers alone) and idempotent (only logs when it actually changes a file). Windsurf is intentionally **not** written here: its config is global (`~/.codeium`), and silently editing a home-dir file that affects every project on the machine from a dev-server boot would be surprising — run `npx bitboss-ui ai-init --mcp` to register Windsurf too. This flag is the zero-command equivalent of that command's project-scoped writes. The MCP server's own runtime — `@modelcontextprotocol/sdk` and `zod` — ships as **optional peer dependencies** (~12 MB, more than every runtime dependency of the library combined, and loaded by nothing else), so install them with `npm i -D @modelcontextprotocol/sdk zod` before the harness first launches the server; both this flag and `ai-init --mcp` warn when they are missing.
 
+**MCP is a convenience, not a requirement, and skipping it costs no
+knowledge.** The server is a reader over files the install already put on disk
+— every tool `readFileSync`s out of `node_modules/bitboss-ui/dist/ai/` (plus
+`dist/styles.css` for the token lookup). An agent that opens that directory
+itself has the identical knowledge base, `npx bitboss-ui check` runs without the
+peers, and `ai-init` (no `--mcp`) still writes the harness pointers. If you are
+migrating under a "no new dependencies" constraint, leave `mcp` at `false`,
+skip `--mcp`, and point your agent at `dist/ai/guides/ai-router.md`.
+
 ### `inertiaLinkName?: string` (default: `'Link'`)
 
 Global component name used for Inertia links. **Optional** — when nothing is
@@ -42126,7 +42222,17 @@ than inventing hues.
 
 The package ships its agent docs in `node_modules/bitboss-ui/dist/ai/`. **Start at** `guides/ai-router.md`, then the catalogue `index.md`. Run `npx bitboss-ui ai-init` in the consumer project to inject harness-agnostic pointers (AGENTS.md, Cursor rules, Copilot instructions, Claude skill, Windsurf rules) so coding agents discover them without a vendor lock-in. After generating Bb\* markup, run `npx bitboss-ui check` (supports `--json`) so unknown props fail before review.
 
-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.
+**Three tiers ship under `dist/ai/`**, and the third one is easy to miss:
+`guides/` + `recipes/` are the authored prose; `<Name>.md` at the root is the
+generated typed contract for each component (props, slots, events, examples);
+`source/<Name>.md` is that same component's **complete implementation** —
+`.vue` template, `types.ts` and `index.css` in one file, one per component
+including the internal ones the package does not export. Read the source tier
+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).
 
 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. **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.
 
@@ -42146,7 +42252,7 @@ It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without it
 - [ ] build plugin configured: `bitboss-ui/vite` plugin or `bitboss-ui/nuxt` module (`bitboss` config key);
 - [ ] `iconDir` points at an existing SVG folder;
 - [ ] runtime plugin installed: `app.use(bitbossUiPlugin)` (automatic in Nuxt);
-- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'`;
+- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'` — auto injection is always library-first, so a Tailwind **v3** app that needs Preflight to load before the library must take the second option (§5);
 - [ ] if a reset is required: `resetCss: true` or `import 'bitboss-ui/reset.css'`;
 - [ ] Inertia apps: `@inertiajs/vue3` installed (no link registration needed; set `inertiaLinkName` only if you register your own link wrapper).
 - [ ] building the [Layout Scaffold](../recipes/vue/layout-scaffold.md)? `npm i @vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal` from it. This library depends on it too, so it can resolve via hoisting without being declared — don't rely on that; declare it in your own `package.json` or a strict installer (pnpm, Yarn PnP) will fail to resolve it.
@@ -42159,7 +42265,7 @@ If one of the checks fails, fix setup before creating component examples.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-alert.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-alert.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-alert.md -->
 
 # BbAlert — v2 → v3
 
@@ -42194,19 +42300,56 @@ A hand-applied `class="bb-alert--warning"` also becomes `variant="warning"` —
 see [main guide §7](../v2-to-v3.md). Custom `theme` names: register via the
 plugin's `alertVariants` option and keep your CSS.
 
+## ⚠ `theme` painted nothing in v2 — and now two identical call sites diverge
+
+v2's stylesheet shipped **zero** `.bb-alert--*` rules. The component emitted
+`bb-alert--${theme}` faithfully, but unless your own CSS defined the rule, every
+value rendered the same default surface. `theme="success"`, `theme="blue"` and
+`theme="warning"` were the same alert.
+
+In v3 the string is live, and what happens next depends on nothing but whether
+the name collides with a built-in (`outline`, `primary`, `destructive`,
+`warning`):
+
+```diff
+  <!-- these two rendered identically in v2 -->
+- <BbAlert theme="success" title="Saved" />
++ <BbAlert variant="success" title="Saved" />
+  <!-- `success` is not an alert built-in → compile error until you register it. You will notice. -->
+
+- <BbAlert theme="warning" title="Quota almost reached" />
++ <BbAlert variant="warning" title="Quota almost reached" />
+  <!-- `warning` IS a built-in → compiles, and silently repaints amber (#fffbea on #fee685). You will not. -->
+```
+
+The rename diff above is a **visual change** for `warning`, not a no-op. Before
+converting any `theme=` value, grep your own stylesheets for
+`.bb-alert--<value>`:
+
+- **Nothing styled it** → the value was decoration. Drop the prop and take the
+  v3 default, or register the name via `alertVariants` and ship no CSS for it,
+  which holds v2's appearance exactly.
+- **Your CSS styled it** → register the name and keep your rule; `warning` is
+  the one case where your rule now lands on top of a library skin, so check
+  that you override every property it sets (background, border, `--main-color`,
+  `--muted-color`) and not just the ones your v2 rule needed.
+
+The same trap applies to `BbTooltip` and `toast()` — v2 styled none of their
+theme classes either.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-avatar.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-avatar.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-avatar.md -->
 
 # BbAvatar — v2 → v3
 
 ## Changes
 
-| v2               | v3                                                                                            | Kind                                                                                            |
-| ---------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `color?: string` | removed                                                                                       | initials fallback always uses the primary tokens; override `.bb-avatar` CSS for anything custom |
-| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                               |
+| v2               | v3                                                                                            | Kind                                                                                                |
+| ---------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `color?: string` | removed                                                                                       | the fallback surface paints from two locals on `.bb-avatar` — `--bg-color` / `--text-color` (below) |
+| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                                   |
 
 ## Edits
 
@@ -42215,14 +42358,53 @@ plugin's `alertVariants` option and keep your CSS.
 + <BbAvatar :src="user.photo" :alt="user.name" />
 ```
 
-If per-user colors mattered, set them in CSS on a wrapper
-(`.team-avatar--purple .bb-avatar { … }`) — the component no longer carries
-presentation-by-prop.
+## Where the color went
+
+`.bb-avatar` declares three locals and reads them for the fallback (initials,
+slotted content, or the built-in person glyph — an image covers all of them):
+
+| local                  | default                                    | paints                      |
+| ---------------------- | ------------------------------------------ | --------------------------- |
+| `--bg-color`           | `var(--bb-primary)`                        | the avatar background       |
+| `--text-color`         | `var(--bb-primary-fg)`                     | initials / slotted fallback |
+| `--default-icon-color` | 80% mix of `--bb-primary-fg` over the fill | the built-in person glyph   |
+
+Set them on a scope, not on the component:
+
+```css
+.team-avatar .bb-avatar {
+	--bg-color: #7c3aed;
+	--text-color: #fff;
+}
+```
+
+⚠ Set **both**. `--bg-color` alone leaves the initials at `--bb-primary-fg`,
+which is the contrast pair for the _primary_ color, not for yours — the symptom
+is white-on-pale or black-on-dark initials.
+
+Use this for a color that genuinely varies per instance (per-team, per-tenant).
+If the v2 `color` was your brand color repeated at every call site, retheme
+`--bb-primary` / `--bb-primary-fg` once instead and write no per-avatar rules.
+That is the order the BbAvatar usage guide prescribes: retheme the tokens
+first, reach for the locals only when the value is per-instance.
+
+## `.bb-avatar--square` was never a library modifier
+
+If your app has a `.bb-avatar--square` rule, it is **your** CSS. v2 shipped no
+such modifier — its entire avatar stylesheet was four rules, all hardcoding
+`border-radius: 50%`, and the string `square` appears nowhere in the v2
+package. v3 bakes in the same circle.
+
+So nothing was removed and there is no v3 modifier to rename to. Your rule
+keeps working: it has the same specificity as the library's `.bb-avatar` rule
+and the library sheet is injected above your app CSS, so yours wins the tie.
+Rename the class to an app-owned block (`.p-avatar--square`) anyway, so the
+next reader does not take it for library API and go hunting for a `shape` prop.
 
 ---
 
 <!-- dist/ai/guides/migration/components/bb-badge.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-badge.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-badge.md -->
 
 # BbBadge — v2 → v3
 
@@ -42244,7 +42426,7 @@ re-express it with the new badge's `variant` API.
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
 | `content?: string \| number \| null` | `text?: string \| number` — plus new `max?: number` (renders `${max}+`)                              |
 | `color?: string` (free-form)         | `variant?: IndicatorVariantType` (`default, success, info, warning, destructive`; default `default`) |
-| `dot`, `left`, `bottom`              | unchanged                                                                                            |
+| `dot`, `left`, `bottom`              | unchanged — including precedence: `dot` renders a contentless bubble and **suppresses** the label    |
 | `floating`                           | removed — the indicator always positions against its slotted anchor                                  |
 | `#content` slot                      | dropped — use `text`                                                                                 |
 
@@ -42259,6 +42441,28 @@ re-express it with the new badge's `variant` API.
 If you styled `.bb-badge` in CSS for this use, the block is now
 `.bb-indicator` (`--dot`, `--left`, `--bottom`, `--<variant>` modifiers).
 
+### `dot` beats the label — in both versions
+
+`dot` and the label are not additive and never were. v2 rendered the content
+span only when `dot` was false; v3 does the same with `text`. Passing both has
+always produced a bare dot.
+
+The trap is on the way out, not the way in. A v2 call site that toggled the dot
+off a count —
+
+```diff
+- <BbBadge :content="unread" :dot="unread !== null" />
++ <BbIndicator :text="unread" :dot="unread !== null" />
+```
+
+— shipped a **dot**, never the number, and the port above keeps it that way.
+Drop `dot` and port `content` to `:text="unread"` alone and the number appears
+where it never did before. Carry `dot` across unchanged unless you mean to
+change the design.
+
+Nothing renders at all when `dot` is false and `text` is `null`/`undefined`, so
+`:text="count || undefined"` is the way to hide a zero.
+
 ## v2 BbChip → v3 BbBadge
 
 Same role (dismissible token), two functional deltas: `clearable` is now
@@ -42333,7 +42537,7 @@ button can span the full pill height while only the circle looks interactive.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-breadcrumbs.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-breadcrumbs.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-breadcrumbs.md -->
 
 # BbBreadcrumbs — v2 → v3
 
@@ -42360,7 +42564,7 @@ button can span the full pill height while only the circle looks interactive.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-button.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-button.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-button.md -->
 
 # BbButton — v2 → v3
 
@@ -42413,10 +42617,74 @@ The `v-bb-tooltip` directive is registered by the runtime plugin (see the
 See [main guide §7](../v2-to-v3.md) for the full pattern and how to register
 custom variant names.
 
+## Skin colors: four locals became six theme tokens per variant
+
+v2 shipped **no** variant CSS — `.bb-button--outline`, `--secondary`, `--ghost`
+and friends had zero rules in the library sheet. If your app has buttons that
+look like anything but the primary fill, your stylesheet built the skin, by
+setting locals that `.bb-button` read:
+
+```css
+/* v2 theming.css — you wrote this, and it was the whole variant */
+.bb-button--outline {
+	--color: #fff;
+	--border-color: #d1d5db;
+	--text-color: #111827;
+	/* hover / pressed / focus were DERIVED from --color automatically */
+}
+```
+
+v3 reads none of those four names. Each variant paints from its own `--bb-*`
+family, declared in `variables.css` and overridable globally or on any scope:
+
+| v2 local on `.bb-button`                   | v3                       |
+| ------------------------------------------ | ------------------------ |
+| `--color` (fill)                           | `--bb-<variant>`         |
+| `--text-color`                             | `--bb-<variant>-fg`      |
+| `--border-color`                           | `--bb-<variant>-border`  |
+| `--ring-color`                             | `--bb-<variant>-ring`    |
+| _derived_ `mix(--color 90%, black)`, hover | `--bb-<variant>-hover`   |
+| _derived_ `mix(--color 80%, black)`, press | `--bb-<variant>-pressed` |
+
+`<variant>` is `primary`, `secondary`, `outline`, `ghost`, `destructive` or
+`link`.
+
+⚠ Note the last two rows. v2 **derived** hover and pressed from the fill; v3
+**states** them. Port only `--bb-outline` and the button keeps the library's
+default hover, which will not be a shade of your color.
+
+```css
+/* v3 equivalent of the v2 block above */
+:root {
+	--bb-outline: #fff;
+	--bb-outline-border: #d1d5db;
+	--bb-outline-fg: #111827;
+	--bb-outline-hover: #f3f4f6;
+	--bb-outline-pressed: #e5e7eb;
+}
+```
+
+Silent by construction: a rule setting `--color` on `.bb-button` still parses,
+still applies, and is read by nothing. `rg -n -- '--color|--text-color|--border-color|--ring-color'`
+across your CSS and find the ones scoped to a button.
+
+Don't confuse this with the `--bb-button-*` row in
+[main guide §3](../v2-to-v3.md): the button's **dimensions** went down into
+component locals, its **colors** went up into global theme tokens. Opposite
+directions, same component.
+
+## `loading-text` was never a BbButton prop
+
+Not in v2, not in v3. If you find `loading-text` on a v2 button it was landing
+in `$attrs` and rendering nothing — delete it rather than looking for the
+replacement. The prop is real on the list and group surfaces — `BbSelect`,
+`BbCheckboxGroup`, `BbRadioGroup`, `BbTable`, `BbSelectPopover` — where it
+carries over to v3 under the same name.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-checkbox-group.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-checkbox-group.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-checkbox-group.md -->
 
 # BbCheckboxGroup / BbRadioGroup / BbSwitchGroup — v2 → v3
 
@@ -42469,10 +42737,64 @@ The `item.disabled` change is the dangerous one: nothing errors, options that
 used to render disabled simply become selectable. Grep item-building code for
 `disabled:` near these groups.
 
+## DOM: the shared `bb-cr-container` block split three ways
+
+v2 rendered one prefix for all three groups — `bb-cr-container` ("checkbox /
+radio") — so a rule written for one group hit all of them. v3 gives each group
+its own block; the suffixes are otherwise identical.
+
+| v2                                    | v3 (`{checkbox,radio,switch}`)            |
+| ------------------------------------- | ----------------------------------------- |
+| `.bb-cr-container`                    | `.bb-base-{checkbox,radio,switch}-group`  |
+| `.bb-cr-container--horizontal`        | `.bb-base-…-group--horizontal`            |
+| `.bb-cr-container--vertical`          | `.bb-base-…-group--vertical`              |
+| `.bb-cr-container--errors`            | `.bb-base-…-group--errors`                |
+| `.bb-cr-container__container`         | `.bb-base-…-group__container`             |
+| `.bb-cr-container__loading-container` | `.bb-base-…-group__loading-container`     |
+| `.bb-cr-container__no-data-container` | `.bb-base-…-group__no-data-container`     |
+| `.bb-cr-container-option`             | `.bb-base-…-group-option`                 |
+| `.bb-cr-container-option__text`       | `.bb-base-…-group-option__text`           |
+| —                                     | `.bb-base-…-group--warnings` (new)        |
+| —                                     | `.bb-base-…-group-option--selected` (new) |
+
+Nothing in v3 renders any `bb-cr-container` class, and nothing warns — the rules
+simply stop matching. **Grep your CSS and test selectors for `bb-cr-container`.**
+
+One rule that used to cover three components is now three rules. If you were
+relying on the shared prefix, group the selectors:
+
+```css
+.bb-base-checkbox-group-option__text,
+.bb-base-radio-group-option__text,
+.bb-base-switch-group-option__text {
+	font-weight: 500;
+}
+```
+
+**`BbRating` is not in this family.** v2's stylesheet carried
+`.bb-rating … .bb-cr-container__container` rules, but the component never
+rendered those classes on either version — it has always used
+`.bb-base-rating__inner-container` / `.bb-base-rating__option`. See
+[bb-rating.md](./bb-rating.md).
+
+## `legend` is required — and always was
+
+`legend: string` is a required prop on `BbCheckboxGroup`, `BbRadioGroup` and
+`BbSwitchGroup` in **v2 and v3 alike** (v2 `dist/components/BbCheckboxGroup/types.d.ts`
+declares `legend: string`, not `legend?`). If the upgrade surfaced missing-legend
+errors across your app, that is a pre-existing bug the stricter v3 build made
+visible — not a v3 break, and not something to "fix" as part of the upgrade.
+
+Treat it as its own change, separately from the migration. One migration team
+added `legend` to six groups mid-upgrade; supplying it let the generic `T`
+resolve properly, which unblocked type inference on the whole subtree and
+surfaced a cascade of unrelated downstream type errors. They reverted the lot.
+Land the migration first, then add legends one component at a time.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-checkbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-checkbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-checkbox.md -->
 
 # BbCheckbox / BbRadio / BbSwitch — v2 → v3
 
@@ -42519,7 +42841,7 @@ compiler cannot catch a boolean that changed meaning.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-chip.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-chip.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-chip.md -->
 
 # BbChip — removed in v3
 
@@ -42555,7 +42877,7 @@ Full badge/indicator picture: [bb-badge.md](./bb-badge.md).
 ---
 
 <!-- dist/ai/guides/migration/components/bb-collapsible.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-collapsible.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-collapsible.md -->
 
 # BbCollapsible — v2 → v3
 
@@ -42582,7 +42904,7 @@ stays in your markup.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-color-input.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-color-input.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-color-input.md -->
 
 # BbColorInput — v2 → v3
 
@@ -42606,7 +42928,7 @@ stays in your markup.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-color-palette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-color-palette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-color-palette.md -->
 
 # BbColorPalette — v2 → v3
 
@@ -42638,7 +42960,7 @@ stays in your markup.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-date-picker-input.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-date-picker-input.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-date-picker-input.md -->
 
 # BbDatePickerInput — v2 → v3
 
@@ -42770,8 +43092,15 @@ friends, rename it:
 | `…__calendar-btn--active`                                                                   | `.bb-segmented-field__trigger-btn--active`              |
 | `.bb-base-date-picker-input__calendar-icon`                                                 | `.bb-segmented-field__trigger-icon`                     |
 | `…__calendar--sheet`                                                                        | `.bb-base-time-picker-input__panel--sheet` (time input) |
-| `…__calendar`, `…__calendar--shown`                                                         | removed — they were styled nowhere                      |
-| `.bb-base-time-picker-input__clock-btn`                                                     | removed — use `.bb-segmented-field__trigger-btn`        |
+| `.bb-base-date-picker-input__inner-wrapper`                                                 | **removed** — see below                                 |
+
+`__inner-wrapper` has no v3 counterpart. It was a bare layout box
+(`flex: auto; display: block`) between the input chrome and the fields; v3
+drops the element and `.bb-segmented-field__fields` carries the layout. A rule
+hanging off it stops matching with nothing to rename it to — delete it, and if
+it was doing real work, move the declarations onto `__fields`.
+| `…__calendar`, `…__calendar--shown` | removed — they were styled nowhere |
+| `.bb-base-time-picker-input__clock-btn` | removed — use `.bb-segmented-field__trigger-btn` |
 
 **The block names are unchanged.** `.bb-base-date-picker-input` and
 `.bb-base-time-picker-input` are still the roots, so a rule that has to reach
@@ -42791,7 +43120,7 @@ move: `__accessible-description` on both, and `__panel`, `__panel--sheet`,
 ---
 
 <!-- dist/ai/guides/migration/components/bb-dialog.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-dialog.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dialog.md -->
 
 # BbDialog — v2 → v3
 
@@ -42800,16 +43129,18 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 
 ## Changes
 
-| v2                                                  | v3                                                                                                                                  | Kind                                                            |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                       |
-| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                      |
-| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot |
-| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                    |
-| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                       |
-| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                   |
-| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                          |
-| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                        |
+| v2                                                  | v3                                                                                                                                  | Kind                                                                                                      |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                                                                 |
+| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                                                                |
+| `#description` slot                                 | removed                                                                                                                             | same — and the `aria-describedby` wiring goes with it                                                     |
+| `#close` slot                                       | removed                                                                                                                             | a custom close control goes inside `#header`, which replaces the default ✕ — no `hide-close` alongside it |
+| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot                                           |
+| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                                                              |
+| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                                                                 |
+| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                                                             |
+| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                                                                    |
+| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                                                                  |
 
 ## ⚠ The two silent ones
 
@@ -42835,10 +43166,118 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
   </BbDialog>
 ```
 
+## CSS and tokens
+
+The `--bb-dialog-*` family is gone. Padding comes from the shared
+`--bb-panel-p`; the rest are unprefixed locals on `.bb-dialog` or plain CSS
+rules. `BbOffCanvas` is identical throughout with `.bb-offcanvas__*` parts.
+
+| v2 token                                     | v3                                                                                     |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `--bb-dialog-px` / `--bb-dialog-py` (`24px`) | `--bb-panel-p` (`16px`) — **one** value on both axes; asymmetry needs a CSS rule       |
+| `--bb-dialog-close` (`12px`)                 | **delete it** — v3's default already reproduces v2's control size                      |
+| `--bb-dialog-title-size` (`18px`)            | local `--dialog-title-fs` on `.bb-dialog`, default `calc(var(--bb-fs) + 2px)` = `16px` |
+| `--bb-dialog-title-weight` (`600`)           | no knob — `500` is hard-coded; override with a CSS rule                                |
+| —                                            | local `--dialog-gap`, default `--bb-panel-p` — the body↔footer vertical rhythm         |
+
+### `--bb-dialog-close` → delete it
+
+v2's `--bb-dialog-close` was the close **icon** width; the button around it
+added `padding: 8px`, so the control measured `12 + 16 = 28px`. v3 inverts the
+relationship: `.bb-close-button { --size }` is the whole control box and the
+glyph is derived — `max(--size - 2 × --p, 10px)`. Inside a dialog v3 already
+ships `--size: 28px; --p: 7px`, a 14px glyph in the same 28px control v2's
+default produced.
+
+So carrying the old number across shrinks the target: `--size: 12px` gives a
+12×12px control, well under the 24px WCAG 2.5.8 minimum. To get the old 12px
+glyph back, widen the padding — never shrink the box:
+
+```css
+/* 12px glyph, still a 28px control */
+.my-dialog .bb-dialog__header > .bb-close-button {
+	--p: 8px;
+}
+```
+
+The library rule is `.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0),
+so your selector needs three classes to win. A headerless dialog puts the ✕ at
+`.bb-dialog__body:first-child .bb-dialog__body-content > .bb-close-button`.
+
+### The title
+
+```css
+.my-dialog {
+	--dialog-title-fs: 18px; /* v2 --bb-dialog-title-size; drives line-height too */
+}
+.my-dialog .bb-dialog__header .bb-dialog__title {
+	font-weight: 600; /* v2 --bb-dialog-title-weight */
+}
+```
+
+There is no weight token in v3. `500` is hard-coded on
+`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0), so match that
+specificity — a two-class `.my-dialog .bb-dialog__title` loses.
+
+### Asymmetric padding
+
+`--bb-panel-p` is a single value used on both axes; there is no
+`--bb-panel-px`/`--bb-panel-py` pair. If your v2 theme set `--bb-dialog-px` ≠
+`--bb-dialog-py`, set `--bb-panel-p` to the **horizontal** value (it also
+positions the close button) and override the vertical with a `padding-block`
+rule on the part classes.
+
+```css
+/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+.my-dialog {
+	--bb-panel-p: 24px; /* horizontal + close-button inset */
+}
+.my-dialog .bb-dialog__header {
+	padding-block: 10px 5px; /* the library halves the header's bottom padding */
+}
+.my-dialog .bb-dialog__body .bb-dialog__body-content {
+	padding-block: 0 20px;
+}
+.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
+	padding-top: 20px;
+}
+.my-dialog .bb-dialog__footer {
+	padding-block: 20px;
+}
+```
+
+Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
+tracking `--bb-panel-p`. Library selectors are `.bb-dialog .bb-dialog__header`
+(0,2,0), `.bb-dialog__body-content` (0,1,0),
+`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) and
+`.bb-dialog .bb-dialog__footer` (0,2,0) — the three-class app rules above beat
+all four.
+
+### `--dialog-gap`
+
+If only the vertical rhythm _between parts_ differs, `--dialog-gap` does it
+without a padding rule — it replaces `--bb-panel-p` in the body's bottom padding
+and the footer's block padding:
+
+```css
+.my-dialog {
+	--dialog-gap: 8px;
+}
+```
+
+It does **not** reach the header's top padding, any horizontal padding, or the
+body's top padding in the headerless case; those still read `--bb-panel-p`.
+
+### `.bb-confirm`
+
+`confirm()` renders through the same `.bb-dialog__*` parts, so everything above
+reaches it. Its own button hooks changed — see
+[use-confirm.md](./use-confirm.md).
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-dropdown-button.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-dropdown-button.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropdown-button.md -->
 
 # BbDropdownButton — v2 → v3
 
@@ -42870,7 +43309,7 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 ---
 
 <!-- dist/ai/guides/migration/components/bb-dropdown.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-dropdown.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropdown.md -->
 
 # BbDropdown / `v-bb-dropdown` — v2 → v3
 
@@ -42907,7 +43346,7 @@ custom names register via the plugin's `dropdownItemVariants` option
 ---
 
 <!-- dist/ai/guides/migration/components/bb-dropzone.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-dropzone.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropzone.md -->
 
 # BbDropzone — v2 → v3
 
@@ -42935,7 +43374,7 @@ renders no hidden input at all.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-icon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-icon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-icon.md -->
 
 # BbIcon — v2 → v3
 
@@ -42960,6 +43399,48 @@ Provider prefixes now require the matching `@iconify-json/<prefix>` dev
 dependency, and names must be **literal strings** (the build scans statically;
 dynamically assembled names won't be bundled).
 
+## Your own icon plugin is probably redundant now
+
+Most v2 apps hand-rolled one, because v2 shipped no registry:
+
+```ts
+// resources/js/plugins/icons.ts — the v2 shape: glob the SVG folder yourself,
+// build a name → loader map, hand it to BbIcon under the string key.
+const icons = import.meta.glob('../../assets/icons/*.svg', { as: 'raw' });
+app.provide('icons', toRegistry(icons));
+```
+
+v3 does both halves itself. The **build** plugin scans `iconDir` recursively
+and turns every `.svg` into `local:<basename>`; the **runtime** plugin provides
+that registry to `BbIcon`. If your plugin scanned the same folder and provided
+it under `'icons'`, it is now duplicating both.
+
+⚠ It is not merely duplicate — it is **inert for `BbIcon`, silently**.
+`bitbossUiPlugin` provides the registry under a Symbol
+(`bitboss-ui:icons`) _and_ under the legacy string key `'icons'`, and `BbIcon`
+reads `inject(Symbol.for('bitboss-ui:icons')) ?? inject('icons')`. The Symbol wins,
+so your map is shadowed rather than merged. Any glyph that exists only in your
+map stops rendering and nothing warns.
+
+Check before you delete — the plugin is dead only if both hold:
+
+1. **Every SVG it registers also lives under `iconDir`.** Diff the two folders.
+   If the plugin globbed a different directory (`resources/js/icons`,
+   a package's `assets/`), move those files into `iconDir` first — otherwise
+   deletion and non-deletion both leave you with missing icons.
+2. **Nothing else injects `'icons'`.** `rg -n "inject\(['\"]icons['\"]\)"` — an
+   app component reading the map to render `<img>` or to enumerate names is
+   real usage, not `BbIcon` usage. It now receives whichever provide ran last
+   (yours, if you `app.use()` your plugin after `bitbossUiPlugin`), which is a
+   coin-flip you do not want to keep. Rewrite those call sites to import your
+   map as a plain module export — or, if what they want is the library's
+   registry, `inject(Symbol.for('bitboss-ui:icons'))`. The key is not exported
+   from the package, but it is a `Symbol.for`, so recreating it resolves the
+   same symbol.
+
+The string key `'icons'` is a compatibility shim kept for one release. Do not
+build on it.
+
 ## Prefix your own icons with `local:` while you are in there
 
 A v2 `type` naming an icon from your own `iconDir` was bare — `type="user-circle"`.
@@ -42989,7 +43470,7 @@ The same goes for any component prop that takes an icon (`prepend:icon`,
 ---
 
 <!-- dist/ai/guides/migration/components/bb-intersection.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-intersection.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-intersection.md -->
 
 # BbIntersection — v2 → v3
 
@@ -43060,7 +43541,7 @@ depended on the stricter behaviour, pass `{ threshold: 1 }` and check
 ---
 
 <!-- dist/ai/guides/migration/components/bb-offcanvas.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-offcanvas.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-offcanvas.md -->
 
 # BbOffCanvas — v2 → v3
 
@@ -43070,6 +43551,9 @@ depended on the stricter behaviour, pass `{ threshold: 1 }` and check
 | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `direction?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | `side?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`)                                         | **⚠ silent** — a leftover `direction` is ignored and the panel falls back to `'left'`                                                                                                                    |
 | `showClose?: boolean` (default `true`)                                  | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted                                                                                                                                                                                |
+| `description?: string`                                                  | removed                                                                                                    | put the copy in the default slot or own the header via `#header`; the `aria-describedby` wiring goes with it                                                                                             |
+| `#description` slot                                                     | removed                                                                                                    | same — nothing links body copy to the panel automatically now                                                                                                                                            |
+| `#close` slot                                                           | removed                                                                                                    | a custom close control goes inside `#header`, see below                                                                                                                                                  |
 | `size?: 'sm' \| 'md' \| 'lg'`                                           | `size?: Responsive<'xs'…'2xl' \| 'auto' \| CSS length>`                                                    | widened — **defaults changed**, same trap as BbDialog: v2 `{ sm: 384, md: 652, lg: 896 }` → v3 `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. Pin via `offCanvasDefaultSizes` if needed. |
 | —                                                                       | `draggable`, `stack` / `stackGap`, `persistent`, `disabled`, `fullscreen`, `eager`, `focusTarget`, `title` | additive                                                                                                                                                                                                 |
 
@@ -43121,10 +43605,41 @@ Pure rename — the `Partial<BbOffCanvasProps>` object is unchanged.
 
 Also silent on upgrade; `eslint --fix` auto-renames it.
 
+## `description` and `#close` are gone
+
+v3's slot set is `header | title | default | footer` — no `#close`, no
+`#description`, and no `description` prop. Same removal as
+[BbDialog](./bb-dialog.md).
+
+`description` copy moves into the default slot. Nothing wires
+`aria-describedby` for you any more; add it yourself if a screen reader needs
+the panel described rather than just labelled.
+
+**`#header` replaces the ✕, so `hide-close` is redundant beside it.** The
+default header renders `#title` + a `CloseButton`; providing `#header` replaces
+both, which is why a custom close control belongs inside it. The slot receives
+`{ titleId, close, title }` — put `titleId` on your title element to keep
+`aria-labelledby` intact, and call `close` from your own control.
+
+```diff
+- <BbOffCanvas v-model="open" title="Edit" :show-close="true">
+-   <template #close><SaveGuardIcon /></template>
+- </BbOffCanvas>
++ <BbOffCanvas v-model="open" title="Edit">
++   <template #header="{ titleId, close, title }">
++     <span :id="titleId" class="bb-offcanvas__title">{{ title }}</span>
++     <button @click="guardUnsaved(close)"><SaveGuardIcon /></button>
++   </template>
++ </BbOffCanvas>
+```
+
+A header renders when `title` is set **or** `#header` is provided, so the slot
+alone is enough — you do not also need a `title`.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-pagination.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-pagination.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-pagination.md -->
 
 # BbPagination — v2 → v3
 
@@ -43163,7 +43678,7 @@ The `total-items` / `total-pages` **props** are unchanged.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-popover.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-popover.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-popover.md -->
 
 # BbPopover — v2 → v3
 
@@ -43216,7 +43731,7 @@ opt out with `:adaptive="false"` if the floating panel must persist.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-rating.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-rating.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-rating.md -->
 
 # BbRating — v2 → v3
 
@@ -43238,10 +43753,61 @@ opt out with `:adaptive="false"` if the floating panel must persist.
 Adding `clearable` is recommended: the old "re-click to clear" folklore is
 now a visible affordance.
 
+`legend` is required here too, in v2 as in v3 — see the note in
+[bb-checkbox-group.md](./bb-checkbox-group.md); a missing one is a pre-existing
+bug, not an upgrade break.
+
+## DOM
+
+The block name is unchanged; the star's state modifier is not.
+
+| v2                                     | v3                                                      |
+| -------------------------------------- | ------------------------------------------------------- |
+| `.bb-base-rating__option--highlighted` | `.bb-base-rating__option--filled` / `--empty`           |
+| —                                      | `.bb-base-rating__option--disabled`, `--readonly` (new) |
+| —                                      | `.bb-base-rating--warnings`, `--forced-clear` (new)     |
+
+v2 styled unfilled stars with `:not(--highlighted)`; v3 gives them a positive
+name. Everything else survives unchanged: `.bb-base-rating`, `--disabled`,
+`--errors`, `--readonly`, `--has-value`, `__inner-container`, `__option`,
+`__label-text`. Nothing warns — a `--highlighted` rule just stops matching.
+
+`BbRating` is not part of the checkbox/radio/switch `bb-cr-container` tree, and
+was not in v2 either despite v2 shipping rules that said otherwise (below).
+Target `.bb-base-rating__inner-container` and `.bb-base-rating__option`.
+
+## `input-position="right"` / `"center"` now does something
+
+v2 shipped the alignment rules under `.bb-rating … .bb-cr-container__container`
+— a class `BbRating` never rendered (its container was already
+`.bb-base-rating__inner-container`). So the prop was accepted and typed on both
+versions but was a **no-op in v2**. v3 repoints the rules at the element the
+component actually renders.
+
+If your app worked around the dead prop with a hand-rolled alignment rule, that
+rule now fights the library's. Delete the workaround and keep the prop.
+
+## Tokens
+
+`--bb-rating-size` was a `:root` global in v2, read as
+`.bb-base-rating { --size: var(--bb-rating-size) }`. v3 drops the global and
+hard-defaults the local:
+
+```diff
+- :root { --bb-rating-size: 32px; }
++ .bb-base-rating { --size: 32px; }
+```
+
+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;
+v2's `--bb-base-rating-spacing` was referenced but never declared anywhere in
+the shipped sheet, so it never worked.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-select-popover.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-select-popover.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-select-popover.md -->
 
 # BbSelectPopover — v2 → v3
 
@@ -43303,7 +43869,7 @@ See `bb-select.md` § "DOM: listbox option classes lose their v2 `autocomplete-`
 ---
 
 <!-- dist/ai/guides/migration/components/bb-select.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-select.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-select.md -->
 
 # BbSelect — v2 → v3
 
@@ -43396,10 +43962,58 @@ Applies to every surface built on the select engine — `BbSelect`,
 `autocomplete-option` in your CSS and test selectors**; nothing warns, the rules
 simply stop matching.
 
+## Tokens: `--bb-select-option-px` / `--bb-select-option-py` are gone
+
+v2 declared both on `:root` (`16px` / `8px`) and read them in the option row, the
+group header and the no-results row. v3 declares neither, and — unlike most of
+the retired component globals — **nothing replaced them with a local**.
+`.bb-listbox__option` hard-codes its inline padding:
+
+```css
+/* src/components/BbSelectPopover/index.css */
+.bb-listbox__option {
+	height: var(--option-h);
+	padding-left: 0.5rem;
+	padding-right: 0.5rem;
+}
+```
+
+So `--bb-select-option-px`, and the `--px` local you might expect by analogy with
+`BbButton` or `BbDialog`, are both silent no-ops — no rule in the select tree
+reads either. Override with a plain declaration instead. The library's rule is
+six classes deep, so a two-class app rule loses the cascade; match the chain or
+force it:
+
+```css
+/* specificity-matched — needs your sheet to load after the library's */
+.bb-select-popover
+	.bb-listbox
+	.bb-listbox__outer-container
+	.bb-listbox__inner-container
+	span[role='listbox']
+	.bb-listbox__option {
+	padding-inline: 1rem;
+}
+
+/* or, order-independent */
+.bb-listbox__option {
+	padding-inline: 1rem !important;
+}
+```
+
+Row **height** is not yours to set in CSS. `--option-h` reads `--option-height`,
+which the component writes inline because the same number feeds the
+virtualizer's `estimateSize`; a CSS override desynchronises the paint from the
+scroll math and the list mispositions. Use `item-height` / `header-height` (or
+`compact`) instead — they move both halves together.
+
+The panel is teleported, so a wrapper class on your `<BbSelect>` does not reach
+it — scope on `.bb-select-popover` or on the surrounding page/theme class.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-slider.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-slider.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-slider.md -->
 
 # BbSlider — v2 → v3
 
@@ -43425,7 +44039,7 @@ silently degrade to `'outside'` — expected, not a bug.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-smooth-height.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-smooth-height.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-smooth-height.md -->
 
 # BbSmoothHeight — v2 → v3
 
@@ -43471,7 +44085,7 @@ matches when `tag="span"`.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-spinner.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-spinner.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-spinner.md -->
 
 # BbSpinner — v2 → v3
 
@@ -43513,21 +44127,103 @@ have made the spinner invisible and removed the page's only busy signal.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-table.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-table.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-table.md -->
 
 # BbTable — v2 → v3
 
 ## Changes
 
-| v2                                              | v3                                                                                                                                                                                                  | Kind                                                                    |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `allowSelectAll?: boolean` (default `true`)     | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                      | rename, polarity inverted                                               |
-| refetch with rows → skeleton                    | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                  | **behavior** — the skeleton only shows when there is nothing to display |
-| rows interactive while loading                  | header + rows go `inert` while loading                                                                                                                                                              | **behavior** — opt out with `interactive-while-loading`                 |
-| `#loading` slot fired on every load             | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                      | **⚠ silent** for anyone styling refetches through it                    |
-| `#no-data` replaced the empty-state `<tr>`      | fills the table's own full-width `<td>` (colspan counted, centred)                                                                                                                                  | **behavior** — pass content, not a row                                  |
-| —                                               | `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass` | additive                                                                |
-| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_ | `useBbTableContext(id).totalItems`                                                                                                                                                                  | **hard rename** on the composable handle — see below                    |
+| v2                                              | v3                                                                                                                                                                                                        | Kind                                                                    |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `allowSelectAll?: boolean` (default `true`)     | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                            | rename, polarity inverted                                               |
+| refetch with rows → skeleton                    | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                        | **behavior** — the skeleton only shows when there is nothing to display |
+| rows interactive while loading                  | header + rows go `inert` while loading                                                                                                                                                                    | **behavior** — opt out with `interactive-while-loading`                 |
+| `#loading` slot fired on every load             | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                            | **⚠ silent** for anyone styling refetches through it                    |
+| `#no-data` replaced the empty-state `<tr>`      | fills the table's own full-width `<td>` (colspan counted, centred)                                                                                                                                        | **behavior** — pass content, not a row                                  |
+| —                                               | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass` | additive                                                                |
+| —                                               | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`                                                                                                                                        | additive, **collides** — see below                                      |
+| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_ | `useBbTableContext(id).totalItems`                                                                                                                                                                        | **hard rename** on the composable handle — see below                    |
+| `--bb-table-*` custom properties                | same names without the `bb-` prefix                                                                                                                                                                       | **⚠ silent** for nested-table layouts — see below                       |
+
+## Columns gained `sortable` and `rowClass` — check yours first
+
+v2's `BbTableColumn` had neither field (`grep sortable` over the whole 2.1.135
+`BbTable/types.d.ts` exits empty), and extra fields on a column object were
+inert — so apps parked their own data there. A backend sort key named
+`sortable`. A per-column class named `rowClass`. Both are now real library
+fields, and both break in two directions at once: the **type** stops compiling
+and the **behaviour** silently changes.
+
+### The type collision
+
+Your column type is almost certainly an intersection:
+
+```ts
+type Column = BbTableColumn<Patient> & { sortable?: string }; // backend sort key
+```
+
+The intersection makes `sortable` `boolean & string` — i.e. `never`, whose
+optional form TypeScript reports as `undefined`. Every column literal in your
+app fails, and the message never mentions `BbTableColumn`:
+
+```
+error TS2322: Type 'string' is not assignable to type 'undefined'.
+```
+
+If your field is **required** (`{ sortable: string }`, no `?`) the whole object
+type collapses to `never` and you get one error per property per literal:
+
+```
+error TS2322: Type '"id"' is not assignable to type 'never'.
+error TS2322: Type 'string' is not assignable to type 'never'.
+```
+
+That fan-out is why a single shared column type produced 166 errors in one real
+migration. Fix it at the type, not at the call sites:
+
+```diff
+- type Column = BbTableColumn<Patient> & { sortable?: string };
++ type Column = BbTableColumn<Patient> & { sortKey?: string };
+
+  // or keep the name and take the field off the library type
++ type Column = Omit<BbTableColumn<Patient>, 'sortable'> & { sortable?: string };
+```
+
+`Omit` compiles, but read the next section before choosing it.
+
+### The behaviour half — a truthy `sortable` turns on the built-in sort UI
+
+`BbTable` coerces the field (`sortable: !!column.sortable` in `BbTable.vue`), so
+**any** truthy value counts — including a sort-key string like
+`'patients.created_at'`. The header stops rendering a plain label and renders a
+`.bb-table-sort` button instead, and the `<th>` gains `aria-sort="none"`. An app
+that already ships its own sortable-header UI now draws two.
+
+The damage is bounded: `sort` is a controlled model (`v-model:sort`), so the
+extra button emits and does nothing else — it cannot reorder your rows behind
+your back. But it is visible, focusable, and announced.
+
+So `Omit` silences the compiler and keeps the bug. Rename the field, or strip
+it at the `BbTable` boundary:
+
+```ts
+const tableColumns = computed(() =>
+	columns.value.map(({ sortable, ...rest }) => rest)
+);
+```
+
+Column `rowClass` is the same shape of trap without the type error, because
+`ColumnClasses` already accepts `string`: a leftover `rowClass: 'w-40'` you
+meant for the column typechecks fine and is now merged onto the whole row's
+`<tr>`, alongside the table-level `rowClass` prop. A non-`Classes` shape
+(`rowClass?: { colspan: number }`) does error, with the same `undefined`
+wording.
+
+Grep both before you start:
+
+```sh
+rg -n 'sortable|rowClass' --type ts --type vue    # keep the hits on column objects
+```
 
 ## Edits
 
@@ -43614,10 +44310,74 @@ unrelated and does not change.
 `BbPagination` consumers see the same rename through `table-id`; see
 [BbPagination](./bb-pagination.md).
 
+## The custom properties the table _publishes_ lost the `bb-` prefix
+
+These are not theming inputs — they are values `BbTable` measures at runtime and
+writes onto its own DOM, for the table's CSS and for descendants to read. You
+reach for them for exactly one reason: aligning a nested table's columns to its
+parent's. They all dropped the prefix.
+
+| v2                                          | v3                                          |
+| ------------------------------------------- | ------------------------------------------- |
+| `--bb-table-{id}-track-{key}`               | `--table-{id}-track-{key}`                  |
+| `--bb-table-offset-start` / `-end`          | `--offset-start` / `--offset-end`           |
+| `--bb-table-offset-internal-start` / `-end` | `--offset-internal-start` / `-internal-end` |
+| `--bb-table-offset-external-start` / `-end` | `--offset-external-start` / `-external-end` |
+| `--bb-table-fill`                           | `--fill`                                    |
+| `--bb-table-natural-width`                  | `--natural-width`                           |
+| `--bb-table-cell-h`                         | `--cell-h`                                  |
+
+Only the track bridge keeps a `table-` segment, because it crosses component
+boundaries; the rest are plain locals on `.bb-table`. `--padding-x`,
+`--padding-y` and `--actions-spacing` were already unprefixed in v2 and keep
+their names (their _values_ tightened: `16px`/`8px` → `12px`/`6px`, and the cell
+height `42px` → `36px`).
+
+**Every one of these fails silently.** They are read as
+`var(--offset-internal-start)` with a fallback, so a v2 override lands on a name
+nothing consumes and the layout quietly falls back to its default. The worst
+case is code that _scans_ for them — a nested-table helper matching
+`/--bb-table-[\w-]+-track/` over `element.style` matches nothing at all, no
+error, just columns that no longer line up:
+
+```diff
+- const track = /--bb-table-[\w-]+-track/;
++ const track = /--table-[\w-]+-track/;
+```
+
+Grep your app CSS and any style-scanning JS for `--bb-table-` — no name with
+that prefix exists in v3.
+
+The table is not the only component this happened to. Four more published
+variables lost the prefix the same way: `--bb-select-popover-width` → `--w` on
+`.bb-select-popover` (and the supported path is now the `width` prop, not a CSS
+override), `--bb-icon-dimensions-w` → `--w` on `.bb-icon`,
+`--bb-breadcrumbs-flex-basis` / `-flex-grow` → `--flex-basis` / `--flex-grow`,
+and `--bb-picker-preview-color` → `--picker-preview-color`. Widen the grep
+accordingly: `--bb-select-popover-`, `--bb-icon-dimensions-`, `--bb-breadcrumbs-`,
+`--bb-picker-`. See
+[design-tokens.md](../../design-tokens.md#migration-from-the-old-tokens) for the
+theming-token side of the same rename.
+
+## `caption` names the selection fieldset when `legend` is absent
+
+A `selectable` table wraps itself in a `<fieldset>` and needs an accessible
+name. v3 resolves it as `legend`, then `caption`, then a generic localized
+string — so a table that already has a `caption` is correctly named and does not
+need a `legend`.
+
+`npx bitboss-ui check` (and the ESLint rule behind it) still asks for `legend`
+specifically, so `<BbTable selectable caption="Patients" />` fails the check
+even though its fieldset is named. That one is a **quality nudge, not a broken
+affordance** — unlike the other partner-prop pairs, ignoring it does not leave
+anything silently doing nothing. Pass a `legend` when it says something the
+caption does not ("select invoices to export" vs "Invoices"); otherwise suppress
+the rule at the call site rather than duplicating the caption into a `<legend>`.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-tabs.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-tabs.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tabs.md -->
 
 # BbTabs — v2 → v3
 
@@ -43635,6 +44395,8 @@ aliases survive as deprecated re-exports, the tag name does not).
 | pane slot `#<key>` (raw)                 | `#<slotKey(key)>`                                       | normalization                                                                           |
 | URL value = raw key                      | URL value = normalized slug                             | **⚠ breaking for deep links**                                                           |
 | tab/panel DOM ids from raw key           | normalized (also fixes invalid ids for spaced keys)     | check E2E selectors                                                                     |
+| `.bb-tab*` CSS                           | `.bb-tabs*` / `.bb-tabs-list*` / `.bb-tabs-panes`       | **⚠ silent** — the whole BEM tree renamed, see below                                    |
+| —                                        | `block` (full-width, equal-width triggers)              | additive — replaces hand-rolled full-width classes                                      |
 
 `slotKey(key)` lowercases and replaces every non-word run with `_`:
 `"In Review"` → `in_review`, `"2024-03-15"` → `2024_03_15`. Keys that are
@@ -43662,10 +44424,86 @@ the normalized slug (`?section=in_review`, not `?section=In%20Review`).
 Existing bookmarks with raw values fall back to the default tab — add a
 redirect if those links matter.
 
+## CSS: every class renamed with the component
+
+The component rename took the whole BEM tree with it. v2 kept everything under
+one block, `.bb-tab`; v3 splits it into `.bb-tabs` (root) plus two blocks of
+their own, `.bb-tabs-list` (the strip) and `.bb-tabs-panes` (the pane wrapper).
+**No `.bb-tab*` selector survives**, and nothing warns — your v2 tab CSS just
+stops matching and the shipped styling shows through.
+
+| v2                                        | v3                                                                |
+| ----------------------------------------- | ----------------------------------------------------------------- |
+| `.bb-tab`                                 | `.bb-tabs`                                                        |
+| `.bb-tab--horizontal`                     | `.bb-tabs--horizontal` (+ `.bb-tabs-list--horizontal`)            |
+| `.bb-tab--vertical`                       | `.bb-tabs--vertical` (+ `.bb-tabs-list--vertical`)                |
+| `.bb-tab--disabled`                       | `.bb-tabs--disabled` (+ `.bb-tabs-list--disabled`)                |
+| `.bb-tab__label-boundary`                 | `.bb-tabs-list`                                                   |
+| `.bb-tab__label-container`                | `.bb-tabs-list__tablist`                                          |
+| `.bb-tab__label-container--no-transition` | `.bb-tabs-list__tablist--no-transition`                           |
+| `.bb-tab__btn`                            | `.bb-tabs__trigger`                                               |
+| `.bb-tab__btn--active`                    | `.bb-tabs__trigger--active`                                       |
+| `.bb-tab__label`                          | `.bb-tabs__trigger-label`, wrapped in `.bb-tabs__trigger-content` |
+| `.bb-tab__panes-container`                | `.bb-tabs-panes`                                                  |
+| `.bb-tab__pane`                           | `.bb-tabs__pane`                                                  |
+| `.bb-tab__pane--shown`                    | `.bb-tabs__pane--shown`                                           |
+
+New in v3 with no v2 counterpart: `.bb-tabs--block` / `.bb-tabs-list--block`,
+`.bb-tabs--compact` / `.bb-tabs-list--compact`, `.bb-tabs-list__prepend` and
+`__append`, `.bb-tabs-list__tablist--measuring`.
+
+Four things to know while porting rules:
+
+- **The nesting did not change.** `.bb-tab__label-container` and
+  `.bb-tabs-list__tablist` are the same `<ul>`. The sliding active pill is
+  still that element's `::before`, still positioned from `--left` / `--top` /
+  `--width` / `--height` set inline on it. A v2 pill override moves by name
+  only, not up or down a level.
+- **`.bb-tabs--horizontal` is rendered.** The direction modifier is applied
+  unconditionally (`bb-tabs--${direction}`, default `'horizontal'`), so a
+  renamed v2 rule keeps working. The library ships no _rule_ for the horizontal
+  modifier — only `--vertical` is styled — but that does not affect your
+  selectors. Do **not** rewrite these as `:not(.bb-tabs--vertical)`.
+- **The `<ul>` is no longer an only child.** `.bb-tabs-list` is a grid holding
+  `__prepend`, the tablist, and `__append`. A v2 rule written as
+  `.bb-tab__label-boundary > *` now over-matches; target
+  `.bb-tabs-list__tablist` by name.
+- **Block naming is not uniform** between the two new blocks: the pane wrapper
+  is `.bb-tabs-panes`, but the pane inside it is an element of the root,
+  `.bb-tabs__pane`. There is no `.bb-tabs-panes__pane`.
+
+Grep for survivors — this catches every v2 name and no v3 one:
+
+```sh
+rg -n 'bb-tab(__|--)|\.bb-tab\b'
+```
+
+## `block` replaces hand-rolled full-width tabs
+
+v2 shipped no full-width tab list, so apps minted their own class — commonly a
+`bb-tab--full-width` / `bb-tabs--full-width` rule stretching the `<ul>` and
+setting `flex: 1` on each button. v3 has the prop:
+
+```diff
+- <BbTab :items="items" class="bb-tabs--full-width">
++ <BbTabs :items="items" block>
+```
+
+`block` sets `.bb-tabs--block` and `.bb-tabs-list--block`: the strip stretches
+to 100% and every trigger takes an equal share of the free space, floored at
+the widest trigger's measured width (published as `--eq` on the tablist) so the
+triggers stay equal even when the strip overflows and scrolls. Horizontal only
+— the vertical strip skips the measurement.
+
+Delete the hand-rolled rule when you switch. Left in place it fights `--block`
+over the same `flex` and `min-width` declarations, and because your class name
+is now unrecognised (`bb-tabs--full-width` collides with nothing the library
+ships) neither the checker nor ESLint will tell you which one won.
+
 ---
 
 <!-- dist/ai/guides/migration/components/bb-tag.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-tag.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tag.md -->
 
 # BbTag — v2 → v3
 
@@ -43695,7 +44533,7 @@ state and bind a mapped `string[]`, syncing on `update:modelValue`.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-text-input.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-text-input.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-text-input.md -->
 
 # BbTextInput — v2 → v3
 
@@ -43730,6 +44568,28 @@ Also relevant here: the shared input wrapper's CSS block was renamed — any CSS
 or test selectors on `.bb-common-input-inner-container*` must move to
 `.common-input-wrapper--*` (see [main guide §5](../v2-to-v3.md)).
 
+## `floating` is not a prop — it is a value of `label-mode`
+
+```diff
+- <BbTextInput v-model="email" label="Email" floating />
++ <BbTextInput v-model="email" label="Email" label-mode="floating" />
+```
+
+`labelMode?: 'outside' | 'floating' | 'inside'` — same in v2 as in v3. A bare
+`floating` was never a `BbTextInput` prop on either version; it falls through
+`$attrs` onto the root element and does nothing, silently. Applies to the whole
+input family, which shares `labelMode`.
+
+`bitboss-ui check` flags it, but points the wrong way:
+
+> prop `floating` is not in BbTextInput's API — `floating` belongs to
+> BbDatePicker, BbDatePickerInput, not BbTextInput
+
+That is true and irrelevant. Those two do declare a real `floating` boolean, and
+it means something else entirely there (emit plain calendar strings instead of
+zoned ISO instants). The answer is `label-mode="floating"` on the component you
+already have.
+
 ## DOM: `--hidden-label` layout class removed (2026-08-07)
 
 `BbBaseInputContainer` — the wrapper behind every labelled control in the
@@ -43742,7 +44602,7 @@ target `--reverse`.
 ---
 
 <!-- dist/ai/guides/migration/components/bb-toast.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-toast.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-toast.md -->
 
 # BbToast / `toast()` — v2 → v3
 
@@ -43763,24 +44623,58 @@ plugin's `toastPosition` config (default `bottom-right`).
 
 ## `toast()` options
 
-| v2                      | v3                                                                                                                                                        | Kind         |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
-| `theme?: string`        | `variant?: ToastVariantType` (built-ins `default, success, info, warning, destructive`)                                                                   | typed rename |
-| `persistent`            | unchanged                                                                                                                                                 |              |
-| `title`, `text`, `icon` | unchanged                                                                                                                                                 |              |
-| —                       | `duration`, `hideClose`, `position`, `loading`, `id` + `updateToast()`, `dismissToast(reason)`, `portal` / `portalProps`, `actions: ActionButtonConfig[]` | additive     |
-
-`toast('plain string')` still works. The `BbToastMessage` type export is gone
-— type options as `BbToastOptions`.
+| v2                                     | v3                                                                                                         | Kind                      |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------- |
+| `theme?: string`                       | `variant?: ToastVariantType` (built-ins `default, success, info, warning, destructive`)                    | typed rename              |
+| `timeout?: number`                     | `duration?: number`                                                                                        | rename                    |
+| `showClose?: boolean` (default `true`) | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted |
+| `persistent`                           | unchanged                                                                                                  |                           |
+| `title`, `text`, `icon`                | unchanged (`text` is now optional)                                                                         |                           |
+| —                                      | `position`, `loading`, `id` + `updateToast()`, `dismissToast(reason)`, `portal` / `portalProps`, `actions` | additive                  |
+
+`timeout` → `duration` is the one to grep for. It is an options-object key, not
+a template attribute, so neither `bitboss-ui check` nor the eslint plugin sees
+it; TS catches a literal `toast({ timeout: 8000 })` on excess-property grounds,
+but a JS call site — or options built up in a variable — just drops the key and
+takes the default, which also shortened: **v2 6000ms, v3 4000ms**. Same rule at
+both ends: a non-positive value throws. `rg -n 'timeout' --type ts --type js`
+over your toast call sites.
+
+`showClose` inverts, it does not disappear: `showClose: false` → `hideClose: true`,
+and `showClose: true` was the default so **delete it**.
 
 ```diff
-- toast({ title: 'Deleted', theme: 'success' });
-+ toast({ title: 'Deleted', variant: 'success' });
+- toast({ title: 'Deleted', theme: 'success', timeout: 4000, showClose: false });
++ toast({ title: 'Deleted', variant: 'success', duration: 4000, hideClose: true });
 
   // the hand-rolled undo pattern collapses to:
 + toast({ title: 'Deleted', actions: [{ text: 'Undo', onClick: restore }] });
 ```
 
+`toast('plain string')` still works. The `BbToastMessage` type export is gone
+— type options as `BbToastOptions` (and a partial update as `BbToastUpdate`).
+
+## What `useToast()` returns
+
+| v2                               | v3                                                           |
+| -------------------------------- | ------------------------------------------------------------ |
+| `{ toast, dismiss, dismissAll }` | `{ toast, dismiss, update }`                                 |
+| `dismiss(id)` — id required      | `dismiss(id?, reason?)` — **no argument dismisses them all** |
+| `dismissAll()`                   | removed — call `dismiss()` with no argument                  |
+| —                                | `update(id, options)`                                        |
+
+```diff
+- const { toast, dismissAll } = useToast();
+- dismissAll();
++ const { toast, dismiss } = useToast();
++ dismiss();
+```
+
+Nothing catches this for you — `dismissAll` is not a template attribute, so
+`bitboss-ui check` and the eslint plugin never see it. Grep:
+`rg -n 'dismissAll' --type ts --type js --type vue`. Hits on a `useConfirm()`
+destructure are fine: `dismissAll` is **new** there, and unrelated.
+
 Notes on `actions` (additive but with rules): handlers run with a spinner and
 sibling-disable, and hold the dismiss timer; portal toasts ignore `actions`.
 Styling hooks moved from `theme` classes to `bb-toast-message--<variant>` —
@@ -43790,7 +44684,7 @@ custom looks register through the plugin's `toastVariants` option
 ---
 
 <!-- dist/ai/guides/migration/components/bb-tooltip.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-tooltip.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tooltip.md -->
 
 # BbTooltip / `v-bb-tooltip` — v2 → v3
 
@@ -43850,7 +44744,7 @@ registered by the runtime plugin — drop any manual
 ---
 
 <!-- dist/ai/guides/migration/components/bb-tree.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/bb-tree.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tree.md -->
 
 # BbTree — v2 → v3
 
@@ -43928,7 +44822,7 @@ lines are deliberately not built in — draw them in your own CSS against the
 ---
 
 <!-- dist/ai/guides/migration/components/use-broadcast-channel-instance.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/use-broadcast-channel-instance.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/use-broadcast-channel-instance.md -->
 
 # `useBroadcastChannelInstance` — v2 → v3
 
@@ -43985,25 +44879,34 @@ composable that renders nothing and that no component in the library consumed.
 ---
 
 <!-- dist/ai/guides/migration/components/use-confirm.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/components/use-confirm.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/use-confirm.md -->
 
 # `confirm()` / `useConfirm` — v2 → v3
 
 ## Options
 
-| v2                                                                                   | v3                                                                                                         | Kind                                                                                                                                |
-| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `yes?: boolean`, `yesText?: string`, `onYes?: () => …`                               | `yes?: false \| string \| ConfirmButtonConfig` (`{ text, variant, size, icon?, onClick? }`)                | collapsed — **`yes: false` still hides the button, unchanged from v2.** Leave it alone; only `yesText`/`onYes` move into the config |
-| `no?: boolean`, `noText?: string`, `onNo?: () => …`                                  | `no?: false \| string \| ConfirmButtonConfig`                                                              | collapsed — same: **`no: false` is a no-op migration**, it hides the button exactly as in v2                                        |
-| `actions?: boolean`                                                                  | `actions?: false \| ConfirmButtonConfig[]`                                                                 | `false` hides the footer; an array replaces the yes/no pair with custom buttons                                                     |
-| default labels `"OK"` / `"Annulla"` (hard-coded)                                     | localized via the active `locale`                                                                          | **⚠ silent** — English apps stop showing Italian "Annulla"; apps that _wanted_ the literals must pass them                          |
-| footer buttons `lg`                                                                  | footer buttons default `md`                                                                                | visual                                                                                                                              |
-| `size`                                                                               | `size?: keyof DialogSizes` — forwards to `BbDialog`                                                        | see the dialog width change in [main guide §2](../v2-to-v3.md)                                                                      |
-| —                                                                                    | `hideClose`, `variant` (`default, destructive`), `portal` / `portalProps` (mutually exclusive with `text`) | additive                                                                                                                            |
-| second `confirm()` while one is open: first promise **never settled** (hung forever) | the superseded promise resolves `false` (implicit dismiss, no callbacks)                                   | **⚠ behavioral** (bugfix 2026-07-18; the replace-not-queue semantics are unchanged)                                                 |
-
-`autoClose`, `title`, `text`, and the returned promise semantics otherwise
-carry over.
+| v2                                                                                   | v3                                                                                          | Kind                                                                                                                                |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `yes?: boolean`, `yesText?: string`, `onYes?: () => …`                               | `yes?: false \| string \| ConfirmButtonConfig` (`{ text, variant, size, icon?, onClick? }`) | collapsed — **`yes: false` still hides the button, unchanged from v2.** Leave it alone; only `yesText`/`onYes` move into the config |
+| `no?: boolean`, `noText?: string`, `onNo?: () => …`                                  | `no?: false \| string \| ConfirmButtonConfig`                                               | collapsed — same: **`no: false` is a no-op migration**, it hides the button exactly as in v2                                        |
+| `actions?: boolean`                                                                  | `actions?: false \| ConfirmButtonConfig[]`                                                  | `false` hides the footer; an array replaces the yes/no pair with custom buttons                                                     |
+| default labels `"OK"` / `"Annulla"` (hard-coded)                                     | localized via the active `locale`                                                           | **⚠ silent** — English apps stop showing Italian "Annulla"; apps that _wanted_ the literals must pass them                          |
+| footer buttons `lg`                                                                  | footer buttons default `md`                                                                 | visual                                                                                                                              |
+| `size`                                                                               | `size?: keyof DialogSizes` — forwards to `BbDialog`                                         | see the dialog width change in [main guide §2](../v2-to-v3.md)                                                                      |
+| `theme?: string`                                                                     | `variant?: ConfirmVariantType` (built-ins `default`, `destructive`)                         | typed rename — unregistered names are a compile error; add yours via the plugin's `confirmVariants`                                 |
+| `timeout?: number`                                                                   | `duration?: number`                                                                         | rename — auto-dismisses, resolves `false` quietly (no `no.onClick`), and implicitly forces `autoClose: true`                        |
+| `autoClose?: boolean` — **opt-in**, omitted means the dialog stays open              | `autoClose?: boolean` — **default `true`**                                                  | **⚠ silent behavior flip** — a v2 multi-step flow that kept the dialog open after resolve must now pass `autoClose: false`          |
+| `hideHeader?: boolean` (a union that made `title` required when `false`)             | removed — `title` is plain optional; omit it and no header renders                          | removed                                                                                                                             |
+| `useConfirm().setLoading(value)`                                                     | removed — busy state is driven by the button's `onClick` promise                            | removed — `useConfirm()` now returns `{ confirm, close, dismissAll }`                                                               |
+| —                                                                                    | `hideClose`, `portal` / `portalProps` (mutually exclusive with `text`)                      | additive                                                                                                                            |
+| second `confirm()` while one is open: first promise **never settled** (hung forever) | the superseded promise resolves `false` (implicit dismiss, no callbacks)                    | **⚠ behavioral** (bugfix 2026-07-18; the replace-not-queue semantics are unchanged)                                                 |
+
+`title`, `text`, and the returned promise semantics otherwise carry over.
+`autoClose` does **not** — see its row above.
+
+Grep for the collapsed keys: `rg -n 'yesText|noText|onYes|onNo|hideHeader|setLoading|autoClose|timeout' --type ts --type js --type vue`.
+TypeScript catches all of them (excess-property checks on the options literal,
+a hard property error on `setLoading`); a JS app gets no signal at all.
 
 ## Edits
 
@@ -44037,10 +44940,36 @@ drops the whole footer. Both spellings survive v2 → v3 untouched.
 If you only ever called `confirm('Are you sure?')`, nothing changes except the
 (localized) button labels and their size.
 
+## CSS hooks
+
+| v2                                          | v3                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `.bb-confirm__content`, `.bb-confirm__text` | unchanged — still the right targets for the body copy                                 |
+| `.bb-confirm__no` / `.bb-confirm__yes`      | **gone** — the footer buttons render as bare `BbButton`s with no confirm class        |
+| `.bb-confirm .bb-base-dialog__*`            | `.bb-confirm .bb-dialog__*` — plus `.bb-offcanvas__*`, the adaptive sheet's parts     |
+| —                                           | `.bb-confirm--<variant>` on the dialog root — the lever for per-variant confirm skins |
+
+`.bb-confirm__text` survives, so a v2 rule targeting the body copy still lands;
+do not relocate it onto `.bb-dialog__body`.
+
+The cancel button is the one that lost its hook. Restyle it per call instead of
+in CSS — v3 defaults it to `size: 'md', variant: 'outline'`, and the Yes button
+to `primary` (or `destructive` when the confirm `variant` is `destructive`):
+
+```diff
+- .bb-confirm .bb-base-dialog__footer .bb-confirm__no:hover:not(:disabled) {
+-   --color: var(--bb-primary);
+- }
++ confirm({ title: '…', no: { text: 'Keep', variant: 'ghost' } });
+```
+
+For a whole-skin change, register a confirm variant and hang the rules off
+`.bb-confirm--<name>` rather than reaching for the old element classes.
+
 ---
 
 <!-- dist/ai/guides/migration/v2-to-v3.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/migration/v2-to-v3.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/v2-to-v3.md -->
 
 # Migrating from bitboss-ui 2.x to 3.0
 
@@ -44056,39 +44985,26 @@ the per-component guides under [`migration/components/`](./components/) —
 only components with **functional** changes have one; if a component has no
 guide there, nothing about it needs migration.
 
+**Which version to migrate to.** v3 is still a prerelease, so install it by
+dist-tag:
+
+```bash
+npm install bitboss-ui@beta
+```
+
+`@beta` is the current v3 channel. Do **not** pin an exact alpha: the alpha line
+is frozen and several of its version numbers were tagged but never published, so
+`npm install bitboss-ui@3.0.0-alpha.8` fails outright with `ETARGET`. And a bare
+`npm install bitboss-ui` resolves to **v2** — `@latest` stays on the 2.x line
+until v3 goes stable. Verify with `npm ls bitboss-ui` before you change a single
+file; if it reports `2.x`, nothing below applies.
+
 **How to read the tables:** every row is a hard break — old names are gone,
 with no alias and no deprecation shim. Where the break is _silent_ (the app
 compiles and runs but behaves differently), the row is marked **⚠ silent**;
 these are the rows you cannot find by waiting for errors, so grep for them
 explicitly (section 8).
 
-## For agents: surface what this guide misses
-
-This guide is the contract for the upgrade. If during a migration you hit
-something it does not cover, **do not silently work around it** — a quiet
-workaround hides a gap that will bite the next project. Report it to the
-user in your migration summary, clearly separated from the routine edits.
-
-Reportable findings, in order of severity:
-
-1. **An undocumented break** — v2 code that compiled or behaved one way and
-   changes in v3 without a matching entry here or in the component's guide.
-2. **A mapping that doesn't hold** — you applied a documented old→new edit
-   and the result compiles but renders or behaves differently than the guide
-   promises.
-3. **An ambiguity you had to guess on** — two plausible migrations for the
-   same v2 usage and the guide doesn't say which is intended.
-4. **A pattern with no v3 home** — a v2 usage (prop combination, slot trick,
-   CSS hook) whose replacement you could not find at all.
-
-For each finding include: the component, the exact v2 usage (snippet), what
-you expected from the guide, and what actually happened. Recommend that the
-user forwards it to the bitboss-ui maintainers so the guide gets a row —
-these reports are how this document stays truthful.
-
-Routine work — renames that behaved exactly as the tables say — belongs in
-the normal summary, not in this report. The report is only for surprises.
-
 ## 0. Upgrade strategy — do it in this order
 
 1. **Swap the setup** (section 1): install the build plugin and the runtime
@@ -44174,11 +45090,54 @@ Migration deltas, one by one:
 
 | v2                                                                         | v3                                                                                                                                                                                                                                        |
 | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `import 'bitboss-ui/styles.css'` in the entry file                         | **Delete it.** The runtime plugin auto-injects styles (`injectStyles` defaults `true`). Keep a manual import only if you set `injectStyles: false`.                                                                                       |
+| `import 'bitboss-ui/styles.css'` in the entry file                         | **Delete it.** The runtime plugin auto-injects styles (`injectStyles` defaults `true`). Keep a manual import only if you set `injectStyles: false` — see the Tailwind exception below.                                                    |
 | No build plugin                                                            | **Add `bitbossUi({ iconDir })`** to `vite.config.ts` (or the `bitboss-ui/nuxt` module). The app does not build without it — components import the virtual config module.                                                                  |
 | `app.use(BbTooltipDirectivePlugin)` / `app.use(BbDropdownDirectivePlugin)` | **Delete both.** `bitbossUiPlugin` registers `v-bb-tooltip` and `v-bb-dropdown` itself (opt out with `injectDirectives: false` if the names collide).                                                                                     |
 | No reset stylesheet                                                        | Optional: `resetCss: true` or `import 'bitboss-ui/reset.css'`. Skip in Tailwind apps — Preflight already does this.                                                                                                                       |
 | Icons registered by augmenting the `IconRegistry` type                     | **Gone** (the `IconRegistry` export no longer exists — see section 5). Drop `.svg` files into `iconDir` and reference them as `local:<name>`; provider icons (`lucide:*`, `mdi:*`, …) need the matching `@iconify-json/*` dev dependency. |
+| A hand-rolled icon plugin doing `app.provide('icons', { … })`              | **Delete it** and move the art into `iconDir`. See the shadowing warning below — this one is silent.                                                                                                                                      |
+
+### ⚠ silent — a hand-rolled `provide('icons', …)` is shadowed, not merged
+
+`bitbossUiPlugin` provides the icon registry under two keys: a Symbol
+(`bitboss-ui:icons`) and the legacy string key `'icons'` — the same key an app
+icon plugin typically uses. `BbIcon` reads the **Symbol first**
+(`inject(ICONS_INJECTION_KEY) ?? inject('icons')`), so once the library plugin
+is installed your own `provide('icons', …)` map never wins. Any glyph that
+existed only in that map stops resolving, and nothing warns. Move those SVGs
+into `iconDir` and reference them as `local:<name>`.
+
+App code that still calls `inject('icons')` now receives the **library's**
+registry object, not yours. The string key is a one-release compatibility shim
+— migrate those call sites off it or delete them.
+
+### ⚠ Tailwind Preflight cannot load before the library when styles are injected
+
+Auto-injection always puts the library sheet at the **top** of `<head>` — the
+guaranteed order is reset → library styles → every other stylesheet, because
+the injector inserts before the first existing `<style>` / `<link
+rel="stylesheet">`. Preflight is an app sheet like any other, so it lands
+_after_ the library and wins every specificity tie. There is no option to
+inject later.
+
+If your v2 app depended on the opposite order (the manual
+`import 'bitboss-ui/styles.css'` placed after your Tailwind entry), keep the
+manual import and turn injection off:
+
+```ts
+// vite.config.ts
+bitbossUi({ iconDir: './src/assets/icons', injectStyles: false });
+```
+
+```ts
+// main.ts — the order is yours again
+import './app.css'; // your Tailwind entry (@import 'tailwindcss')
+import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
+```
+
+Leave `resetCss` at its `false` default here — Preflight already resets.
+`injectStyles` controls only whether the library injects its own `<style>`;
+nothing else about the plugin changes.
 
 ### Nuxt
 
@@ -44309,24 +45268,36 @@ scope instead.
   explicitly.
 - `--bb-radius` went `4px` → `8px`.
 
+Six more tokens changed value **without changing name**, so they are invisible
+to the rename map and to every grep below — see
+["Tokens that kept their name but changed"](#tokens-that-kept-their-name-but-changed).
+
 ### Token rename map
 
-| v2 override                                                                                                                                                                           | v3 replacement                                                                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-primary-base`                                                                                                                                                                   | deleted — set `--bb-primary` directly                                                                                                                                     |
-| `--bb-contrasting` / `--bb-contrasting-dark`                                                                                                                                          | `--bb-primary-fg`                                                                                                                                                         |
-| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                                      | `--bb-muted`                                                                                                                                                              |
-| `--bb-hint`, `--bb-icon-color`, `--bb-placeholder`, `--bb-prefix-color`, `--bb-muted-color`                                                                                           | `--bb-text-muted`                                                                                                                                                         |
-| `--bb-input-color`, `--bb-input-bg`                                                                                                                                                   | `--bb-text`, `--bb-panel`                                                                                                                                                 |
-| `--bb-input-font-size`, `--bb-input-mobile-font-size`                                                                                                                                 | `--bb-input-fs`, `--bb-input-fs-mobile`                                                                                                                                   |
-| `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                                         | `--bb-overlay` (one color with alpha)                                                                                                                                     |
-| `--bb-overlay-z-index`                                                                                                                                                                | `--bb-z-overlay`                                                                                                                                                          |
-| `--bb-easing-bezier`                                                                                                                                                                  | `--bb-ease`                                                                                                                                                               |
-| `--bb-dialog-px/pt/pb/gap`                                                                                                                                                            | `--bb-panel-p` (surfaces share one padding token)                                                                                                                         |
-| `--bb-button-h`, `--bb-button-icon`, `--bb-tabs-*`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-select-option-*` | **no longer global.** Component dimensions hang off `--bb-control-h`, `--bb-fs`, `--bb-radius`; anything finer is an unprefixed local token on the component's own class. |
-
-**When a v2 global becomes a component token, resize only what you use.** The
-row above is the trap: a v2 global like `--bb-button-icon` had ONE value for
+| v2 override                                                                                                                                                            | v3 replacement                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-primary-base`                                                                                                                                                    | deleted — set `--bb-primary` directly                                                                                                                                                                                                                                                                                                                      |
+| `--bb-contrasting` / `--bb-contrasting-dark`                                                                                                                           | `--bb-primary-fg`                                                                                                                                                                                                                                                                                                                                          |
+| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                       | `--bb-muted`                                                                                                                                                                                                                                                                                                                                               |
+| `--bb-hint`, `--bb-icon-color`, `--bb-placeholder`, `--bb-prefix-color`, `--bb-muted-color`                                                                            | `--bb-text-muted`                                                                                                                                                                                                                                                                                                                                          |
+| `--bb-input-color`, `--bb-input-bg`                                                                                                                                    | `--bb-text`, `--bb-panel`                                                                                                                                                                                                                                                                                                                                  |
+| `--bb-input-font-size`, `--bb-input-mobile-font-size`                                                                                                                  | `--bb-input-fs`, `--bb-input-fs-mobile`                                                                                                                                                                                                                                                                                                                    |
+| `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                          | `--bb-overlay` (one color with alpha)                                                                                                                                                                                                                                                                                                                      |
+| `--bb-overlay-z-index`                                                                                                                                                 | `--bb-z-overlay`                                                                                                                                                                                                                                                                                                                                           |
+| _(no v2 equivalent)_                                                                                                                                                   | `--bb-ease` — new in v3. v2 hard-coded seven different `cubic-bezier()` curves and exposed no easing token, so there is nothing to rename; set `--bb-ease` once if you want a house curve.                                                                                                                                                                 |
+| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | `--bb-panel-p` — **one value on both axes**, for dialogs and off-canvas alike. If your v2 px ≠ py, see "Asymmetric surface padding" below.                                                                                                                                                                                                                 |
+| `--bb-dialog-close`                                                                                                                                                    | **delete it** — do not map it onto `.bb-close-button { --size }`; v3's default already reproduces the v2 control. See below.                                                                                                                                                                                                                               |
+| `--bb-dialog-title-size`                                                                                                                                               | the local `--dialog-title-fs` on `.bb-dialog` / `.bb-offcanvas` (default `calc(var(--bb-fs) + 2px)`)                                                                                                                                                                                                                                                       |
+| `--bb-dialog-title-weight`                                                                                                                                             | **no knob** — the title is hardcoded `font-weight: 500`. Override with a CSS rule, see below.                                                                                                                                                                                                                                                              |
+| `--bb-button-h`, `--bb-button-icon`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-select-option-*` | **no longer global.** Component dimensions hang off `--bb-control-h`, `--bb-fs`, `--bb-radius`; anything finer is an unprefixed local on the component's own class — with one exception: `--bb-select-option-px/-py` have **no** v3 local, the listbox option's inline padding is a literal (`.bb-listbox__option { padding-inline: … }` in your own CSS). |
+
+**`--bb-input-*` and `--bb-label-*` are NOT in the row above.** They are still
+global v3 theme tokens, declared in `variables.css` and read across the whole
+form family — do not delete them. Several changed their default value; the
+drift table below lists which.
+
+**When a v2 global becomes a component token, resize only what you use.** That
+last row is the trap: a v2 global like `--bb-button-icon` had ONE value for
 every button because v2 had no size scale. v3 does, so the same value now lives
 in a per-size family (`--icon-size-xs … --icon-size-2xl`) that the size class
 re-points. Two mistakes follow, and both were made on a real migration:
@@ -44344,11 +45315,173 @@ doctrine in `design-tokens.md` § "Overriding one from a consumer app". And chec
 first whether the v2 value was a real customisation: if it merely restated v2's
 default, the migration is to **delete it** and inherit the v3 scale.
 
+**Asymmetric surface padding.** `--bb-panel-p` is a single value used on both
+axes. If your v2 theme set `--bb-dialog-px` ≠ `--bb-dialog-py`, set
+`--bb-panel-p` to the **horizontal** value (it also positions the close button)
+and override the vertical with a normal `padding` rule on the part classes.
+There is no `--bb-panel-px` / `--bb-panel-py` pair.
+
+```css
+/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+.my-dialog {
+	--bb-panel-p: 24px; /* horizontal + close-button inset */
+}
+.my-dialog .bb-dialog__header {
+	padding-block: 10px 5px;
+}
+.my-dialog .bb-dialog__body .bb-dialog__body-content {
+	padding-block: 0 20px;
+}
+.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
+	padding-top: 20px;
+}
+.my-dialog .bb-dialog__footer {
+	padding-block: 20px;
+}
+```
+
+Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
+tracking `--bb-panel-p`. Specificity: the library rules are
+`.bb-dialog .bb-dialog__header` (0,2,0), `.bb-dialog__body-content` (0,1,0) and
+`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) — the
+three-class app selectors above beat all of them. `BbOffCanvas` is identical
+with `.bb-offcanvas__*`.
+
+**`--px` and `--pt` are not dialog knobs.** `.bb-dialog` declares them, but
+nothing in the dialog or off-canvas CSS reads them, and every component that
+_does_ read `--px` (`BbButton`, `BbAlert`, `BbTooltip`, `BbBaseSlider`)
+re-declares it on its own root class, so an ancestor value never reaches those
+either. Setting `--px` on a dialog part is inert — it silently leaves the
+horizontal padding at whatever `--bb-panel-p` resolves to.
+
+If only the **vertical rhythm between parts** differs, the local `--dialog-gap`
+(default `--bb-panel-p`) already does it without a padding rule: it drives the
+gap below the body content and the footer's block padding on `.bb-dialog` and
+`.bb-offcanvas`. It does **not** cover the header's top padding, or the body's
+top padding in the headerless case — those still take `--bb-panel-p`.
+
+**`--bb-dialog-close` maps to nothing — delete it.** In v2 it was the close
+**icon** width (`12px`) and the button around it added `8px` of padding, so the
+control was 28px. v3 inverts the relationship: `.bb-close-button { --size }` is
+the whole control box and the icon is derived as `max(--size - 2 × --p, 10px)`.
+Inside a dialog v3 already ships `--size: 28px; --p: 7px` (a 14px glyph) — the
+same 28px control v2's default produced. Feeding v2's `12px` into `--size`
+yields a **12×12px** control, well under the WCAG 2.5.8 minimum target size. If
+you must match the old glyph exactly, widen the padding instead of shrinking
+the box:
+
+```css
+/* 12px glyph, 28px control */
+.my-dialog .bb-dialog__header > .bb-close-button {
+	--p: 8px;
+}
+```
+
+That selector needs at least three classes to beat the library's
+`.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0).
+
+**`--bb-dialog-title-weight` has no v3 home.** The title is `font-weight: 500`,
+hardcoded. Restore v2's `600` with a rule that outweighs the library's
+`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0):
+
+```css
+.my-dialog .bb-dialog__header .bb-dialog__title {
+	font-weight: 600;
+}
+```
+
 A complete v3 theme is typically two small blocks of ~10 declarations
 (`--bb-primary`, `--bb-radius`, `--bb-control-h`, `--bb-panel`, `--bb-text`,
 `--bb-border`, `--bb-danger`, …) — one in `:root, .light`, the changed knobs
 again in `.dark`. If your v2 theme was long, most of it maps to "delete".
 
+### Tokens that kept their name but changed
+
+The rename map above is keyed by _the name you must change_. These tokens kept
+their v2 name and stayed global, so they appear in no rename row and no grep
+finds them — the only symptom is that the app renders differently.
+
+**Values that drifted.** Same name, same meaning, new default:
+
+| token                 | v2                                    | v3                                                                            |
+| --------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
+| `--bb-input-h`        | `36px`                                | `32px` (via `--bb-control-h`)                                                 |
+| `--bb-input-py`       | `4px`                                 | `3px`                                                                         |
+| `--bb-input-prefix-w` | `40px`                                | `20px`                                                                        |
+| `--bb-label-weight`   | `400`                                 | `500`                                                                         |
+| `--bb-ring-size`      | `4px`                                 | `2px`                                                                         |
+| `--bb-leading`        | `24px` (`--bb-input-font-size` × 1.5) | `21px` (`--bb-input-fs` × 1.5, and `--bb-input-fs` is now `14px`, not `16px`) |
+
+The consequence cuts both ways, which is what makes it easy to get wrong: an
+app that **carried its v2 theme forward** keeps the v2 look (36px inputs, 4px
+rings) and never sees v3's proportions; an app that **deleted its theme as
+redundant** silently shifts to shorter inputs, half-width prefix columns and a
+half-thickness focus ring. Re-check each of these six against the v3 default
+and delete only the declarations that merely restated a **v2** default.
+
+**A type that narrowed.** `--bb-ring-opacity` survives by name but v3 registers
+it with `@property … syntax: '<percentage>'`:
+
+| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                              |
+| ------------------- | -------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 25%`. v3's own defaults are `15%` light / `40%` dark. |
+
+Nothing reports this — not `vue-tsc`, not the eslint plugin, not
+`npx bitboss-ui check` (none of them read CSS), and not the browser console:
+an invalid registered-property value is not a parse error, so it logs nothing.
+Grep your stylesheets for `--bb-ring-opacity` and confirm every value carries a
+`%`.
+
+Nine tokens are `@property`-registered in v3 — the eight color knobs
+(`syntax: '<color>'`) plus `--bb-ring-opacity`. Each rejects values outside its
+declared syntax the same silent way, so treat any future registration as the
+same class of break.
+
+### Button and variant skin colors moved the other way
+
+The "no longer global" row sends per-component values _down_ into unprefixed
+locals. The button **skin** colors went the opposite direction — up into global
+theme tokens. In v2 a skin was four locals set on your own modifier class:
+
+```css
+/* v2 theming.css */
+.bb-button--outline {
+	--color: #fff;
+	--border-color: #d1d5db;
+	--text-color: #111827;
+	/* hover / pressed / ring were derived from --color automatically */
+}
+```
+
+v3 reads none of those — the old locals are inert, so a skin ported verbatim
+silently reverts to the library defaults. Each variant has its own `--bb-*`
+family, declared in `variables.css` and overridable globally or on any scope:
+
+| v2 local on `.bb-button`                     | v3 token family (per variant)       |
+| -------------------------------------------- | ----------------------------------- |
+| `--color` (fill)                             | `--bb-<variant>`                    |
+| `--text-color`                               | `--bb-<variant>-fg`                 |
+| `--border-color`                             | `--bb-<variant>-border`             |
+| `--ring-color`                               | `--bb-<variant>-ring`               |
+| _derived_ `mix(--color 90%, black)` on hover | `--bb-<variant>-hover` (explicit)   |
+| _derived_ `mix(--color 80%, black)` on press | `--bb-<variant>-pressed` (explicit) |
+
+`<variant>` is one of `primary`, `secondary`, `outline`, `ghost`,
+`destructive`, `link`. Note the last two rows: v2 _derived_ hover and pressed
+from the fill, v3 states them. Porting only `--bb-outline` leaves the hover
+state on the library's default.
+
+```css
+/* v3 equivalent of the block above */
+:root {
+	--bb-outline: #fff;
+	--bb-outline-border: #d1d5db;
+	--bb-outline-fg: #111827;
+	--bb-outline-hover: #f3f4f6;
+	--bb-outline-pressed: #e5e7eb;
+}
+```
+
 ## 4. Variants: from `theme` strings and class overrides to typed registries
 
 ### What changed
@@ -44365,6 +45498,19 @@ v3 replaces all of that with per-component `variant` props whose types are
 registers. An unregistered name is a **compile error** (v2's silent
 render-unstyled behavior is gone by design), and the `theme` prop is gone.
 
+**⚠ v2 shipped no variant CSS at all, so adopting a variant is additive.** Grep
+the v2 stylesheet and the only `bb-button--*` rules are `group`, `icon` and
+`loading`; there are no `bb-alert--*`, no appearance-level `bb-badge--*`, no
+`bb-tooltip--*` and no `bb-toast-message--*` rules. v2's components _emitted_
+those names (`bb-alert--${theme}`, `bb-tooltip--${theme}`,
+`bb-toast-message--${theme}`) and the library never styled them. In v2 the
+class and the `theme` string meant **"whatever your app's CSS says, and nothing
+else."** In v3 every one of those names is a real skin, so converting hands the
+library a styling role it did not have — wherever your CSS does not override
+every property v3 sets (background, border, foreground, hover, pressed, focus
+ring), the appearance drifts. Diff a screenshot; do not assume. Section 7
+covers the class-to-prop rewrite itself.
+
 Built-in sets and the class each name maps to:
 
 | Plugin option          | Built-in variants                                                             | Class hook                          |
@@ -44378,6 +45524,54 @@ Built-in sets and the class each name maps to:
 | `dropdownItemVariants` | `default, destructive`                                                        | `bb-dropdown__item--variant-<name>` |
 | `tooltipVariants`      | `default, destructive`                                                        | `bb-tooltip--<name>`                |
 
+### Picking a v3 name for a v2 `theme` value
+
+v2's `theme` was free-form, so most apps carry names that are not in the table
+above (`error`, `danger`, `info`, `success`, `blue`, …). Work through it in
+this order:
+
+1. **Name is in the table, and your app never styled it** → use the built-in
+   `variant`. This is the only genuinely free conversion.
+2. **Name is in the table, but your app styled it itself** → v3's built-in now
+   paints underneath your rules. Decide explicitly: accept v3's look and delete
+   your CSS, or register the name (`alertVariants: ['warning']`) so your CSS
+   stays the sole styling source.
+3. **Name is not in the table** → register it and keep your CSS. **Do not remap
+   onto the "nearest" built-in.** `error → destructive`, `danger →
+destructive`, `info → primary` all compile, all look plausible in review,
+   and all silently replace your palette with the library's. Remap only as a
+   deliberate redesign decision, never as a mechanical migration step.
+4. **Name was never styled by anyone** → see the next subsection.
+
+Registering is cheap — one array entry per name — and it is the
+behaviour-preserving default. Prefer it whenever you are not sure.
+
+### ⚠ silent — a `theme` value that did nothing in v2 may do something in v3
+
+Because v2 shipped no variant CSS, unless your app defined the rule the `theme`
+prop was **inert**: every value rendered the same default surface. In v3 the
+same string is a live skin, and whether it stays inert depends entirely on
+whether the name happens to collide with a v3 built-in:
+
+```
+both of these rendered an identical plain alert in v2:
+
+  <BbAlert theme="success" />   v3: not an alert built-in → compile error, you WILL notice
+  <BbAlert theme="warning" />   v3: built-in → silently becomes an amber alert, you will NOT
+```
+
+So two identical-looking v2 call sites migrate to opposite outcomes. Before
+converting any `theme=` value, check whether _anything_ styled it in v2 — your
+stylesheet, since the library did not. If nothing did, the value was
+decoration:
+
+- register it as an empty custom variant (`alertVariants: ['success', 'blue']`)
+  to hold v2's appearance exactly, or
+- drop the prop entirely and let the v3 default apply, or
+- convert it and accept the new look **on purpose**.
+
+What you must not do is convert it mechanically and assume nothing moved.
+
 ### Custom variants are first-class
 
 If your v2 app invented its own look (a `theme="brand"` or a hand-written
@@ -44406,6 +45600,12 @@ works with a visible cast (`variant="brand" as ButtonVariantType` won't
 compile — cast the value, not the prop), but the registry is the intended
 path.
 
+**A name you keep as a plain class should not stay in the `bb-*` namespace.**
+An app-minted `bb-button--pressed` or `bb-table--borderless` is squatting on
+the library's prefix and collides the day the library ships that name. Either
+register it as a variant, or rename it into your own prefix
+(`app-button--pressed`). Section 7 has the decision table.
+
 ## 5. API-wide changes
 
 These patterns repeat across many components. The per-component guides list
@@ -44413,20 +45613,22 @@ every occurrence; this section explains each pattern once.
 
 ### 5.1 Components renamed, split, or removed
 
-| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                  |
-| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                  |
-| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                 |
-| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                          |
-| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-checkbox-icon` → `.bb-base-checkbox-icon`).                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, so these are internal now. Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`). |
-| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                              |
-| `BbIntersection` (+ `BbIntersectionProps` / `BbIntersectionEvents`)           | **removed**                                                               | No replacement — it wrapped `IntersectionObserver` in ~40 lines and carried no styling. Use `@vueuse/core`'s `useIntersectionObserver`, or copy the v2 component. Full mapping of the `shown`/`hidden`/`intersected` events and the slot props: [components/bb-intersection.md](./components/bb-intersection.md).                                                                                                                                                                                        |
-| `useBroadcastChannelInstance`                                                 | **removed**                                                               | Same reasoning: a typed wrapper over a browser API, no markup, no styling, used by no component here. Cross-tab messaging is app architecture. Use `useBroadcastChannel` from `@vueuse/core` — already in your tree, since this library depends on it. **Two behaviours do not carry over** (handler auto-removal on unmount, and the refcount the v2 docs described but never had): [components/use-broadcast-channel-instance.md](./components/use-broadcast-channel-instance.md).                     |
-| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                |
+| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-base-checkbox-container__icon` → `.bb-base-checkbox-icon`; see §5.6).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, so these are internal now. Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`).<br><br>**These primitives were also restructured, not just un-exported.** The outer+inner pair merged into one `CommonInputWrapper` (`.common-input-wrapper` / `__inner`), `BbBaseInputContainer` gained an inner `__layout` element that now carries the orientation modifiers, and `__input` became `__control`. Anything anchored to the old DOM — app CSS, test selectors, JS positioning a floating panel off `.bb-base-input-container__input` — fails silently: nothing throws, the element is simply never found. See §5.6.<br><br>**Built a custom control on the chrome?** If your app composed `BaseInputContainer` + `CommonInputOuterContainer` + `CommonInputInnerContainer` around an element the library does not ship (a highlight-overlay textarea, a field with a bespoke floating panel), there is no public v3 component to swap in — those wrappers exist in v3 but are internal. The sanctioned fallback is to **copy** the chrome into your app from the implementation source that ships with the package: `node_modules/bitboss-ui/dist/ai/source/BbBaseInputContainer.md` and `dist/ai/source/CommonInputWrapper.md` carry the complete `.vue` template, `types.ts` and `index.css` for each (89 components have one). Those files are banner-marked "Reference Only - Internal" — that bans _importing_ the internal component, not copying its template and CSS into a component of your own, which is the supported route here. The class names a copied template emits are styled by the public `bitboss-ui/styles.css`, so it inherits library chrome for free. Check first whether v3 already ships what you built — `BbTimePickerInput` and `BbTimePicker` are new in v3. |
+| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `BbIntersection` (+ `BbIntersectionProps` / `BbIntersectionEvents`)           | **removed**                                                               | No replacement — it wrapped `IntersectionObserver` in ~40 lines and carried no styling. Use `@vueuse/core`'s `useIntersectionObserver`, or copy the v2 component. Full mapping of the `shown`/`hidden`/`intersected` events and the slot props: [components/bb-intersection.md](./components/bb-intersection.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `useBroadcastChannelInstance`                                                 | **removed**                                                               | Same reasoning: a typed wrapper over a browser API, no markup, no styling, used by no component here. Cross-tab messaging is app architecture. Use `useBroadcastChannel` from `@vueuse/core` — already in your tree, since this library depends on it. **Two behaviours do not carry over** (handler auto-removal on unmount, and the refcount the v2 docs described but never had): [components/use-broadcast-channel-instance.md](./components/use-broadcast-channel-instance.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `BbRatio` (+ `BbRatioProps`, `.bb-ratio`)                                     | **removed**                                                               | No replacement — it was a one-rule wrapper. Use the `aspect-ratio` CSS property, or copy the v2 component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `useQueue`, `useQuery`                                                        | **removed**                                                               | Both were public v2 exports and neither has a v3 equivalent; the import fails at build. Copy the v2 implementations out of the 2.1.135 tarball (`dist/composables/useQueue.d.ts`, `useQuery.d.ts`) into your app, or replace them with `@vueuse/core` equivalents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ### 5.2 The polarity wave: booleans now read as opt-in
 
@@ -44448,7 +45650,7 @@ to the new name (`hide-close`).
 
 | Component(s)                                       | v2 prop (default)                                         | v3 prop (default)                                                                                                                                                                                                               |
 | -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbAlert`, `BbDialog`, `BbOffCanvas`               | `showClose` (`true`)                                      | `hideClose` (`false`) — also new on `toast()` / `confirm()` options                                                                                                                                                             |
+| `BbAlert`, `BbDialog`, `BbOffCanvas`               | `showClose` (`true`)                                      | `hideClose` (`false`) — also on `toast()` options, where v2 had `showClose` too and the same inversion applies (`showClose: false` → `hideClose: true`, `showClose: true` → delete). Genuinely **new** on `confirm()` options.  |
 | `BbTable`                                          | `allowSelectAll` (`true`)                                 | `disableSelectAll` (`false`)                                                                                                                                                                                                    |
 | `BbTabs`                                           | `animateX` / `animateY` (`true`)                          | `disableAnimateX` / `disableAnimateY` (`false`)                                                                                                                                                                                 |
 | `BbButton`                                         | `autoLoading` (`false`)                                   | `disableAutoLoading` (`false`) — **⚠ silent behavior flip:** async `@click` handlers now show the loading spinner and disable the button automatically. Pass `disable-auto-loading` to keep v2 behavior.                        |
@@ -44463,16 +45665,18 @@ to the new name (`hide-close`).
 
 ### 5.3 Straight renames
 
-| Component                                          | v2                                | v3                                                                                                                                                                     |
-| -------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbPagination`, `BbTabs`                           | `querykey`                        | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params. |
-| `BbTooltip`                                        | `timeout`                         | `delay`                                                                                                                                                                |
-| `BbIcon`                                           | `type` (required)                 | `icon`                                                                                                                                                                 |
-| `BbColorPalette`, `BbColorInput`                   | `picker`                          | `eyeDropper`                                                                                                                                                           |
-| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `labelPosition`                   | `legendPosition`                                                                                                                                                       |
-| `BbSelect`                                         | `prefill: 'focus'`                | `prefill: 'interaction'` (value rename; same default)                                                                                                                  |
-| `BbToast` (host)                                   | `placement` (e.g. `bottom-start`) | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                   |
-| `BbAlert`, `BbTooltip`, `toast()`                  | `theme`                           | `variant` (typed — see section 4)                                                                                                                                      |
+| Component                                          | v2                                | v3                                                                                                                                                                             |
+| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BbPagination`, `BbTabs`                           | `querykey`                        | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.         |
+| `BbTooltip`                                        | `timeout`                         | `delay`                                                                                                                                                                        |
+| `toast()`, `confirm()` options                     | `timeout`                         | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`. |
+| `useToast()`                                       | `dismissAll()`                    | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                         |
+| `BbIcon`                                           | `type` (required)                 | `icon`                                                                                                                                                                         |
+| `BbColorPalette`, `BbColorInput`                   | `picker`                          | `eyeDropper`                                                                                                                                                                   |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `labelPosition`                   | `legendPosition`                                                                                                                                                               |
+| `BbSelect`                                         | `prefill: 'focus'`                | `prefill: 'interaction'` (value rename; same default)                                                                                                                          |
+| `BbToast` (host)                                   | `placement` (e.g. `bottom-start`) | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                           |
+| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`     | `theme`                           | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                       |
 
 ### 5.4 Removed props (no replacement needed — behavior became default or moved)
 
@@ -44483,7 +45687,18 @@ to the new name (`hide-close`).
 - **`color` everywhere**: gone from `BbAvatar`, `BbIcon`, `BbSpinner`,
   `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbSlider`, `BbRating` and all three
   groups. Components inherit `currentColor` / theme tokens; style via CSS or
-  the token knobs.
+  the token knobs. `BbAvatar`'s knobs are named: set **both** `--bg-color` and
+  `--text-color` on `.bb-avatar` (plus `--default-icon-color` for the built-in
+  icon fallback) — setting only the background leaves the initials painted
+  `--bb-primary-fg` on top of it.
+
+  ```css
+  .team-avatar .bb-avatar {
+  	--bg-color: #7c3aed;
+  	--text-color: #fff;
+  }
+  ```
+
 - **`BbSelect`**: `showChevron` and `updateOnAnimationFrame` removed; the
   `#chevron` slot and the four `#options:prepend/append(:outer)` slots are
   gone (use the new `#header` / `#footer` panel slots). Same options-slot
@@ -44507,7 +45722,15 @@ to the new name (`hide-close`).
 - **`BbPopover`**: `showClose`, `closeLabel`, `restoreFocus`, `block` removed —
   render your own close affordance in the content (`#default="{ close }"`).
 - **`BbDialog`**: `description`, `hideHeader`, `compact`, `overlayClasses`,
-  `panelClasses` removed (use the `header` slot and normal classes).
+  `panelClasses` removed (use the `header` slot and normal classes). The
+  `#description` and `#close` **slots** are gone too — v3's slot set is
+  `header | title | default | footer`, and a custom close control goes inside
+  `#header`, which replaces the whole default header including the ✕ (so
+  `hide-close` is not needed alongside it).
+- **`BbOffCanvas`**: the same `description` prop and the same `#description` /
+  `#close` slots were removed, with the same replacements. The
+  `aria-describedby` wiring `description` used to provide is gone — put the
+  copy in the default slot.
 - **`BbBreadcrumbs`**: string `divider` removed (slot-driven now);
   `dividerWidth` default changed `5` → `16`.
 - **`BbPagination`**: `loading` removed.
@@ -44544,21 +45767,161 @@ to the new name (`hide-close`).
 - **`direction`** on inputs: the exported `InputDirection` union — keyword
   typos now fail to compile; two-word ratio strings (`'1 2'`) still work.
 
-### 5.6 Renamed CSS blocks
+### 5.5b Fields added to public object types
+
+An **added** optional field breaks a consumer as hard as a removed one, and the
+error text does not say so. If your app intersects a library object type to
+carry its own metadata — `BbTableColumn & { sortable?: string }` for a backend
+sort key, say — the intersection does not widen the property, it **collapses**
+it: `string & undefined` is `undefined`, and every column literal then fails
+with
+
+```
+error TS2322: Type 'string' is not assignable to type 'undefined'.
+```
+
+which names neither the field nor the library. That one line is worth
+searching your build log for. The fix is to rename your field (`sortKey`) or to
+subtract the library's first:
+`Omit<BbTableColumn, 'sortable'> & { sortable?: string }`.
 
-If app CSS or test selectors target library internals, these blocks moved:
+The collision-prone additions in v3:
 
-| v2                                                                                    | v3                                                                                                                                    |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__prepend-icon`, …) | `.common-input-wrapper` — modifiers `--active --compact --disabled --errors --loading --readonly --clearable` (note: no `bb-` prefix) |
-| `.base-btn`, `.base-btn--block`, …                                                    | `.bb-base-button*`                                                                                                                    |
-| `.bb-checkbox-icon` / `.bb-radio-icon` / `.bb-switch-icon`                            | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon`                                                             |
-| `.bb-chip*`                                                                           | `.bb-badge*` (component replaced)                                                                                                     |
-| `.bb-badge*` used as a floating count/dot                                             | `.bb-indicator*` (component renamed)                                                                                                  |
+| type              | added in v3                                               | hazard                                                                                                                                                                                                                                                                     |
+| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbTableColumn`   | `sortable?: boolean`                                      | intersection collapse (above), **and** a behavior flip: v3 reads it as `!!column.sortable`, so a truthy sort-key string switches on the built-in header sort button. An app with its own sort UI then renders two. Strip the field at the `BbTable` boundary or rename it. |
+| `BbTableColumn`   | `rowClass?: ColumnClasses<Item>`                          | same collapse. Note this is the **column-level** field — the table-level `rowClass` prop is separate and both accumulate.                                                                                                                                                  |
+| `BbDropdown` item | `description?: string`                                    | collapse, plus it now renders as a second line on the item.                                                                                                                                                                                                                |
+| `BbDropdown` item | `group?: never`, `selectable?: never`, `multiple?: never` | harder than a collapse: these discriminate item-from-group, so `group: 'admin'` on a plain item literal is a **direct** type error, no intersection required. Rename the field or nest your metadata under one custom key.                                                 |
+
+Everything else added in v3 lands on `*Props` / `*Slots` / internal projections
+— shapes you pass or read rather than intersect — so this list is deliberately
+short.
+
+### 5.6 Renamed CSS blocks
+
+If app CSS or test selectors target library internals, these blocks moved. This
+is the complete set — a class-by-class diff of the v2 stylesheet against v3
+leaves nothing else orphaned. All of it is **silent**: a selector on a class
+nobody emits matches nothing and throws nothing.
+
+**Input chrome**
+
+| v2                                                                                                                                | v3                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__suffix`, `__prepend-icon`, `__append-icon`)                   | `.common-input-wrapper` (+ the same suffixes) — modifiers `--active --compact --disabled --errors --loading --readonly --clearable --warnings` (note: no `bb-` prefix)                                                                                                                                                                   |
+| `.bb-common-input-outer-container`                                                                                                | merged away — the v2 outer/inner pair is one `.common-input-wrapper`, whose inner span is `.common-input-wrapper__inner`                                                                                                                                                                                                                 |
+| `.bb-base-input-outer-container` (+ `--compact`)                                                                                  | merged into `.bb-base-input-container` (+ `--compact`)                                                                                                                                                                                                                                                                                   |
+| `.bb-base-input-container__input` (+ `--left --center --right`)                                                                   | `.bb-base-input-container__control` (+ the same modifiers)                                                                                                                                                                                                                                                                               |
+| `.bb-base-input-container--horizontal` / `--vertical` / `--reverse` (on the root)                                                 | `.bb-base-input-container__layout--horizontal` / `--vertical` / `--reverse` — v3 inserts an inner `__layout` element and the orientation modifiers moved onto it; the root keeps only state modifiers (`--disabled --errors --warnings --loading --readonly --compact --floating-label --inside-label` …)                                |
+| `.bb-base-input-container--label-mode-floating`                                                                                   | `.bb-base-input-container--floating-label`                                                                                                                                                                                                                                                                                               |
+| `.bb-base-input-container__errors-outer`                                                                                          | `.bb-base-input-container__errors-wrap`                                                                                                                                                                                                                                                                                                  |
+| `.bb-base-input-container__hint-container`                                                                                        | `.bb-base-input-container__hint-wrap`                                                                                                                                                                                                                                                                                                    |
+| `.base-btn`, `.base-btn--block`, …                                                                                                | `.bb-base-button*`                                                                                                                                                                                                                                                                                                                       |
+| `.bb-base-checkbox-container` / `.bb-base-radio-container` / `.bb-base-switch-container`                                          | `.bb-base-checkbox` / `.bb-base-radio` / `.bb-base-switch` (the `--disabled` modifier survives)                                                                                                                                                                                                                                          |
+| `.bb-base-checkbox-container__icon` / `.bb-base-radio-container__icon` / `.bb-base-switch-container__icon` (+ `__icon-thumb`)     | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon` (+ `.bb-base-switch-icon__thumb`)                                                                                                                                                                                                                              |
+| `.bb-cr-container*` — the shared checkbox/radio/switch group tree (root, `--vertical`, `__container`, `-option`, `-option__text`) | split into per-control blocks: `.bb-base-checkbox-group*` / `.bb-base-radio-group*` / `.bb-base-switch-group*`, same suffixes (`--warnings`, `__loading-container`, `__no-data-container`, `-option--selected` are new). **`BbRating` no longer shares the block** — use `.bb-base-rating__inner-container` / `.bb-base-rating__option`. |
+
+**Dialogs, off-canvas, popovers**
+
+| v2                                                                                                          | v3                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-base-dialog` (+ `--deny-close --fullscreen --open`, `__header __title __body __body-content __footer`) | `.bb-dialog` / `.bb-dialog__*` — 1:1 on every one of those                                                                                                                                                                                                                                            |
+| `.bb-base-dialog__close` / `__close-icon`, `.bb-offcanvas__close` / `__close-icon`, `.bb-popover__close`    | `.bb-close-button` — one shared button, used by the dialog, the off-canvas and the popover alike                                                                                                                                                                                                      |
+| `.bb-common-popover--scrollable`                                                                            | `.bb-popover__panel--scrollable` (the rest of `.bb-common-popover*` is unchanged)                                                                                                                                                                                                                     |
+| `.bb-confirm__no`                                                                                           | **removed** — the cancel button is a plain `BbButton` with no class of its own. Restyle it through `no: { variant: … }` on the call, or through the root's `.bb-confirm--<variant>` modifier. `.bb-confirm__text` and `.bb-confirm__content` are unchanged and still the right targets for body copy. |
+
+**Tabs** — the whole tree was renamed, and v2's block name was `bb-tab`, not
+`bb-tabs`, so nothing of a v2 tab theme survives untouched:
+
+| v2                                               | v3                                                                                                                                                                                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-tab`                                        | `.bb-tabs`                                                                                                                                                                                                                                   |
+| `.bb-tab--vertical` / `--horizontal`             | `.bb-tabs--vertical` / `--horizontal` (+ `.bb-tabs-list--vertical` / `--horizontal` on the strip)                                                                                                                                            |
+| `.bb-tab__label-boundary`                        | `.bb-tabs-list`                                                                                                                                                                                                                              |
+| `.bb-tab__label-container` (+ `--no-transition`) | `.bb-tabs-list__tablist` (+ `--no-transition`) — the sliding active pill is still this element's `::before`, so a v2 `.bb-tab__label-boundary .bb-tab__label-container:before` rule becomes the single-class `.bb-tabs-list__tablist:before` |
+| `.bb-tab__btn` (+ `--active`)                    | `.bb-tabs__trigger` (+ `--active`), with new inner `.bb-tabs__trigger-content` / `.bb-tabs__trigger-label`                                                                                                                                   |
+| `.bb-tab__pane` (+ `--shown`)                    | `.bb-tabs__pane` (+ `--shown`)                                                                                                                                                                                                               |
+| `.bb-tab__panes-container`                       | `.bb-tabs-panes`                                                                                                                                                                                                                             |
+
+v2 had no full-width tab strip, so apps hand-rolled one (commonly a
+`bb-tabs--full-width` class). v3 ships it: `<BbTabs block>` sets
+`.bb-tabs--block` / `.bb-tabs-list--block` and gives the triggers equal widths.
+Delete the hand-rolled modifier rather than porting it.
+
+**Everything else**
+
+| v2                                                                                                                                                                                                                                            | v3                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-chip*`                                                                                                                                                                                                                                   | `.bb-badge*` (component replaced)                                                                                                                                                                                             |
+| `.bb-badge*` used as a floating count/dot (`--dot --floating --positioned --left --bottom --empty`, `__wrapper`, `__content-container`)                                                                                                       | `.bb-indicator*` (component renamed)                                                                                                                                                                                          |
+| `.bb-color-palette__*` (canvas, canvas-thumb, canvas-wrap, controls, eyedropper, preview, preview--alpha, preview-wrap, slider-thumb, slider-track, slider-wrap, slider-wrap--alpha, sliders, swatch, swatch--active, swatch-group, swatches) | `.bb-base-color-palette__*` — 1:1 on every one                                                                                                                                                                                |
+| `.bb-toast--top-start` / `--top` / `--top-end` / `--bottom-start` / `--bottom` / `--bottom-end`                                                                                                                                               | `.bb-toast--top-left` / `--top-center` / `--top-right` / `--bottom-left` / `--bottom-center` / `--bottom-right` (matching the `position` prop's corner set)                                                                   |
+| `.bb-toast-message__icon-container`                                                                                                                                                                                                           | **removed** — style `.bb-toast-message__icon` directly                                                                                                                                                                        |
+| `.bb-tree--open`                                                                                                                                                                                                                              | `.bb-tree__node--expanded`                                                                                                                                                                                                    |
+| `.bb-tree-row`                                                                                                                                                                                                                                | `.bb-tree__row`                                                                                                                                                                                                               |
+| `.bb-tree-main-content`                                                                                                                                                                                                                       | `.bb-tree__content`                                                                                                                                                                                                           |
+| `.bb-dropdown-button__dropdown-chevron`                                                                                                                                                                                                       | `.bb-dropdown-button__chevron`                                                                                                                                                                                                |
+| `.bb-dropdown-button--loading` / `__content` / `__icon` / `__prepend-icon` / `__append-icon`                                                                                                                                                  | **removed** — the split button delegates to `BbButton`'s internals; target `.bb-button__*` inside it                                                                                                                          |
+| `.bb-dropdown__wrapper`                                                                                                                                                                                                                       | **removed** — the extra wrapper element is gone                                                                                                                                                                               |
+| `.bb-select-popover__search-spinner`                                                                                                                                                                                                          | `.bb-select-popover__search-icon` (one element, spinner state included)                                                                                                                                                       |
+| `.bb-base-date-picker__header` (the tinted banner holding the month/year controls)                                                                                                                                                            | `.bb-base-date-picker__controls` (+ the inner `__nav-center`) — the banner is gone; the controls sit on the calendar surface. `__header-container` and `__header-cell` are unrelated and unchanged: they are the weekday row. |
+| `.bb-base-date-picker__control` / `__year-control`                                                                                                                                                                                            | `.bb-base-date-picker__nav-btn`                                                                                                                                                                                               |
+| `.bb-base-date-picker__month-button` / `__year-button`                                                                                                                                                                                        | `.bb-base-date-picker__heading-btn` (+ `--active`)                                                                                                                                                                            |
+| `.bb-base-date-picker__weekday`                                                                                                                                                                                                               | `.bb-base-date-picker__header-cell`                                                                                                                                                                                           |
+| `.bb-base-date-picker__monthday`                                                                                                                                                                                                              | `.bb-base-date-picker__date` (+ the inner `__date-button`)                                                                                                                                                                    |
+| `.bb-base-date-picker__year-container`                                                                                                                                                                                                        | `.bb-base-date-picker__year-selector`                                                                                                                                                                                         |
+| `.bb-base-date-picker__header--hidden`, `__selected-day-label`                                                                                                                                                                                | **removed**                                                                                                                                                                                                                   |
+| `.bb-commabox-item--has-comma`                                                                                                                                                                                                                | the select's comma list renders `.bb-base-select__comma-item` (`.bb-commabox-item` itself survives; `--has-comma` and `.bb-chipsbox-item--focused` do not)                                                                    |
+
+The date **input**'s own field tree (`.bb-base-date-picker-input__field`,
+`__fields`, `__placeholder`, `__separator`, `__calendar-btn`) moved to a shared
+`.bb-segmented-field__*` block — full table in
+[bb-date-picker-input.md](./components/bb-date-picker-input.md).
+
+**Removed with no counterpart:** `.bb-base-dialog--compact`,
+`.bb-offcanvas--compact`, `.bb-base-textarea--compact` (compact now lives on
+`.common-input-wrapper--compact`), `.bb-base-select--active` / `--compact` /
+`__inner-wrapper` / `__input-container` (the select activator was rebuilt —
+nearest hooks are `.bb-base-select__activator`, `__value`, `__display-value`;
+`--shown` survives), `.bb-base-rating__option--highlighted` (v3 uses
+`--filled` / `--empty`), `.bb-progress--horizontal` (`.bb-progress` /
+`.bb-progress-bar` are the blocks), `.bb-ratio` (component removed).
+
+### 5.7 Renamed custom properties the library WRITES
+
+Section 3 covers the tokens you set. These are variables the library **writes
+onto the DOM** at runtime for you to read — the usual reason to touch them is
+nested-table column alignment. They all dropped the `bb-` prefix, and every one
+of them is consumed through `var(name, fallback)`, so a v2 name silently
+resolves to the fallback instead of failing.
+
+| v2                                                    | v3                                                                         |
+| ----------------------------------------------------- | -------------------------------------------------------------------------- |
+| `--bb-table-{id}-track-{key}`                         | `--table-{id}-track-{key}`                                                 |
+| `--bb-table-offset-start` / `-end`                    | `--offset-start` / `--offset-end`                                          |
+| `--bb-table-offset-internal-start` / `-end`           | `--offset-internal-start` / `--offset-internal-end`                        |
+| `--bb-table-fill`                                     | `--fill`                                                                   |
+| `--bb-table-natural-width`                            | `--natural-width`                                                          |
+| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override |
+| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                      |
+| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                             |
+| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                   |
+
+A regex matching the old shape (`/--bb-table-[\w-]+-track/`) matches nothing in
+v3. Search your app for `--bb-table-`, `--bb-select-popover-`,
+`--bb-icon-dimensions-`, `--bb-breadcrumbs-` and `--bb-picker-` — none of those
+names exist in v3 and all of them fail quietly. `--available-height`,
+`--inner-width` and `--overlay-min-height` were dropped outright.
+
+If you re-published track variables by hand to align a deeply nested table,
+delete that code: `inherit-column-widths` takes a **table id**
+(`inherit-column-widths="<ancestor-id>"`), not just `true`, and walks the whole
+ancestor chain — it is not limited to the immediate parent.
 
 ## 6. Behavior changes you will feel at runtime
 
-No rename to grep for — these change what existing, still-compiling code does.
+Nothing here fails to compile — these change what existing code does.
 
 1. **`BbButton` tracks async click handlers by default.** An `async @click`
    now disables the button and shows a spinner until it settles. Opt out per
@@ -44584,7 +45947,14 @@ No rename to grep for — these change what existing, still-compiling code does.
    progress bar) instead of flashing to skeleton — and the rows and header go
    `inert` during the refetch. Escape hatch: `interactive-while-loading`. The
    `#loading` slot fires on the **first load only** now.
-6. **Dynamic slot names are normalized** via
+6. **A truthy column `sortable` switches on v3's own sort UI.** `BbTable` reads
+   the field as `!!column.sortable`, so a column carrying a backend sort key
+   (`sortable: 'created_at'`) renders the built-in header sort button and sets
+   `aria-sort` — an app with its own sort control then shows two. Sorting stays
+   a controlled model (`v-model:sort`), so nothing reorders on its own; the
+   button appears and emits. Strip or rename the field at the `BbTable`
+   boundary. The compile-time half of the same collision is in §5.5b.
+7. **Dynamic slot names are normalized** via
    `slotKey(key) = key.split(/\W+/g).join('_').toLowerCase()` in
    `BbBreadcrumbs`, `BbTree`, `BbTabs`, and the date-picker day slots.
    `#Order History` → `#order_history`. **⚠ silent**: a stale raw-key slot
@@ -44593,15 +45963,20 @@ No rename to grep for — these change what existing, still-compiling code does.
    normalized slug (`?tab=In%20Review` → `?tab=in_review` — update deep links
    and server code), and tab/panel DOM ids are normalized. Only `v-model` /
    item `key` stay raw.
-7. **Dialogs, popovers, dropdowns and selects open as bottom sheets on mobile**
+8. **Dialogs, popovers, dropdowns and selects open as bottom sheets on mobile**
    by default (`adaptive`, default `true`). Set `adaptive: false` in the
    plugin, or per component, for v2-like floating behavior.
-8. **`confirm()` buttons**: default labels are localized (no more hard-coded
+9. **`confirm()` buttons**: default labels are localized (no more hard-coded
    "OK"/"Annulla") and footer buttons default to `md`.
-9. **Invalid enum-ish prop values** (`size`, `direction`, `BbSlider.labelMode`)
-   now warn in dev and fall back to the documented default instead of
-   rendering broken or throwing.
-10. **`BbTree` is a disclosure list, not an ARIA tree**: the unfulfilled
+10. **`confirm()` closes itself now.** `autoClose` was opt-in in v2 — after
+    `resolve`/`reject` the dialog stayed up until you called `close()`. In v3 it
+    defaults to `true`. ⚠ silent: the promise settles exactly as before, the
+    dialog just disappears. A multi-step flow that kept it open between steps
+    has to pass `autoClose: false`.
+11. **Invalid enum-ish prop values** (`size`, `direction`, `BbSlider.labelMode`)
+    now warn in dev and fall back to the documented default instead of
+    rendering broken or throwing.
+12. **`BbTree` is a disclosure list, not an ARIA tree**: the unfulfilled
     `role="tree"` / `treeitem` / `aria-level` markup is gone, and a collapsed
     branch's children are now `inert` (out of the Tab order). Tests or CSS
     keyed on the removed roles match nothing — see
@@ -44625,6 +46000,23 @@ These keep _rendering_ in v3 (the class hooks still exist), but they are now
 the wrong layer: they bypass the typed registry, silently drift when the
 library renames internals, and duplicate what a prop expresses. Convert them.
 
+**But the conversion is additive, not neutral.** v2 shipped no variant CSS
+(§4): those class names carried your rules and nothing else. In v3 each one is
+a real skin, so every rewrite below slides the library's rules _underneath_
+yours — background, border, foreground, hover, pressed, focus ring. Wherever
+your CSS does not override all of them, the appearance drifts. Diff a
+screenshot; do not assume. Two consequences before you start:
+
+- **Leaving the class alone is not a safe holding position.** `variant`
+  defaults to `primary`, so in v3 `<BbButton class="bb-button--outline">`
+  renders `bb-button--primary bb-button--outline` — the built-in skin and your
+  class fighting in the cascade. For a pure class override, pass
+  `variant="none"`; it is the one value that emits no variant class.
+- **A name that collides with a v3 built-in is the dangerous case, not the easy
+  one.** If your app owned the look of `warning` / `destructive` / `secondary`,
+  converting to the same-named `variant` hands that look to the library.
+  Register the name as a custom variant (§4) to keep your CSS the only source.
+
 ### Finding them
 
 Run in the consumer project:
@@ -44635,34 +46027,54 @@ rg -n 'class="[^"]*bb-[a-z-]+--' --type vue
 rg -n ":class=\"[^\"]*'bb-[a-z-]+--" --type vue
 # free-form theme props (removed in v3)
 rg -n '(:?theme)=' --type vue
+# the same prop as an option-object key — toast()/confirm() live in .ts
+rg -n 'theme' --type ts --type js
 # raw component markup rebuilt from classes (no <BbX> tag on the same line)
 rg -n 'class="bb-(button|badge|alert|toast-message|tooltip|indicator)\b' --type vue
 ```
 
 ### Correcting them
 
-| Found                                                                         | Rewrite as                                                                                     |
-| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `<BbButton class="bb-button--outline">`                                       | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)          |
-| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                  | `<BbAlert variant="warning">`                                                                  |
-| `class="bb-badge bb-badge--secondary"` on a `<span>`                          | `<BbBadge variant="secondary">` — the real component, not markup cosplay                       |
-| `bb-toast-message--success` styling / v2 `theme` on toasts                    | `toast({ variant: 'success' })`                                                                |
-| `bb-tooltip--destructive`                                                     | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`        |
-| A **custom** modifier (`bb-button--brand`, any name not in section 4's table) | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`. |
-| A class that overrides _layout_, not look (widths, margins)                   | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.      |
+| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                 |
+| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                      |
+| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                              |
+| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                   |
+| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success' })`                                                                                                                                                                                                                                                                            |
+| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                    |
+| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                             |
+| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or register the name (§4) so your CSS stays the sole styling source. Converting silently does the former.                                                                                                                        |
+| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you. |
+| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                  |
 
 Rule of thumb: if the class name encodes a **meaning** (state, emphasis,
 severity), it should be a variant; if it encodes **geometry**, it stays a
 class.
 
+Whatever stays a class should not stay in the `bb-*` namespace. An app-minted
+`bb-table--borderless` or `bb-avatar--square` is squatting on the library's
+prefix — neither name has ever shipped, and the day one does, your rule and the
+library's collide silently. Rename them into your own prefix.
+
 ## 8. The silent-failure audit
 
 Everything the compiler cannot catch, in one grep pass. Run each in the
 consumer project; every hit needs a decision, not necessarily a change.
 
+Two surfaces have no other net. **Composable option objects live in `.ts`** —
+`toast({ … })` and `confirm({ … })` inside stores, interceptors and helpers —
+and neither gate reaches them: `npx bitboss-ui check` opens only `.vue` and
+`.md`, and the eslint plugin walks template ASTs. **Nothing reads CSS at all**,
+not the CLI, not eslint, not `vue-tsc`, not the browser console. The
+`--type ts --type js` lines and the token/class lines below are the whole
+safety net for those two. (ripgrep's `js` type already covers `*.vue`, so
+adding `--type vue` to them is redundant.)
+
+**Props, slots and markup**
+
 ```bash
 rg -in 'querykey'                         # → queryKey (URL params silently move)
-rg -n 'show-close|showClose'              # → hide-close (inverted) ONLY on BbAlert/BbDialog/BbOffCanvas. On BbPopover and BbTooltip the close button is GONE: delete the prop, never rename it
+rg -n 'show-close|showClose'              # → hide-close (inverted) on BbAlert/BbDialog/BbOffCanvas and in toast() options, which had showClose in v2 too. On BbPopover and BbTooltip the close button is GONE: delete the prop, never rename it
 rg -n 'allow-select-all|allowSelectAll'   # → disable-select-all, inverted
 rg -n 'auto-loading|autoLoading'          # BbButton behavior flip / rename
 rg -n 'disabled-while-loading|disabledWhileLoading'  # removed
@@ -44672,11 +46084,11 @@ rg -n ':flip=|flip="'                     # → disable-flip on palette/select-p
 rg -n 'hide-arrow|show-arrow|arrow-padding|hideArrow|showArrow|arrowPadding'  # removed off tooltips
 rg -n '<BbChip'                           # component removed → BbBadge clearable
 rg -n '<BbBadge'                          # v2 badges are v3 indicators — review each
-rg -n '<BbTab[ >]'                        # → BbTabs
+rg -n '<BbTab\b'                          # → BbTabs (\b so a tag name alone on its line still matches, and <BbTabs does not)
 rg -n '#label-'                           # BbTabs label slot → #label:<slotKey>
-rg -n 'reverse' --type vue                # BbRadio/BbSwitch default flipped
-rg -n ':timeout=' --type vue              # BbTooltip → delay (BbAvatar keeps timeout)
-rg -n '<BbIcon[^>]*type='                 # → icon=, and prefix your own icons `local:` (bb-icon.md)
+rg -n 'reverse' --type ts --type js       # BbRadio/BbSwitch default flipped
+rg -n 'timeout' --type vue                # BbTooltip → delay (BbAvatar keeps timeout); no ':' so static attrs match too
+rg -nU '<BbIcon[^>]*type='                # → icon=, and prefix your own icons `local:` (bb-icon.md). -U so a multi-line tag matches
 rg -n '(icon|type)="[a-z][a-z0-9-]*"'     # bare icon names in templates → `local:<name>` so the Iconify extension previews them
 rg -n 'allow-writing|allowWriting'        # → disable-writing, inverted + new tokens
 rg -n 'show-chevron|showChevron|updateOnAnimationFrame|update-on-animation-frame'  # removed
@@ -44684,17 +46096,48 @@ rg -n 'label-position|labelPosition'      # groups → legend-position
 rg -n 'prefill="focus"|prefill: .focus.'  # → 'interaction'
 rg -n ':prefill="false"|prefill: false'   # now search-first, not load-on-open
 rg -n 'role="tree|treeitem'               # BbTree ARIA roles removed
-rg -n ':filter-by="[^\x27\[]'             # function/string filterBy → string[]
+rg -n 'filter-by|filterBy'                # function/string filterBy → string[] (camelCase spelling lives in .ts option objects)
 rg -n 'option:prepend|option:append|options:prepend|options:append|#chevron'  # removed slots
 rg -n '<Bb(Checkbox|Radio|Switch|Slider|Rating|Avatar|Icon|Spinner)[^>]*color='  # removed color props
 rg -n 'disabled:' --type ts --type vue    # item.disabled near option components → selectable
-rg -n 'picker' --type vue                 # color input/palette → eye-dropper
-rg -n 'bb-common-input-inner-container'   # CSS block → .common-input-wrapper
-rg -n 'IconRegistry|BbToastMessage|useWizard|BaseButtonProps|BaseDialog'  # removed exports
+rg -n 'picker' --type ts --type js        # color input/palette → eye-dropper
+```
+
+**Composable option objects and imports (`.ts` / `.js`)**
+
+```bash
+rg -n 'timeout' --type ts --type js       # toast()/confirm() options → duration
+rg -n 'theme' --type ts --type js         # toast()/confirm() options → variant
+rg -n 'dismissAll'                        # useToast().dismissAll() → dismiss() with no argument. useConfirm() has a NEW dismissAll — check which one each hit is
+rg -n 'autoClose|auto-close'              # confirm(): opt-in in v2, default true in v3 (section 6)
+rg -n 'yesText|noText|onYes|onNo|hideHeader|setLoading' --type ts --type js  # confirm() options collapsed into the yes/no configs
+rg -n 'BbTableColumn\s*&|DropdownItem\s*&' --type ts  # intersections that collapse to `undefined` (§5.5b)
+rg -n "provide\('icons'|inject\('icons'"  # a hand-rolled icon registry is shadowed, not merged, by the plugin's (section 1)
+rg -n 'IconRegistry|BbToastMessage|useWizard|useQueue|useQuery|useBroadcastChannelInstance|BaseButtonProps|BaseDialog'  # removed exports
 rg -n 'setConfig'                         # only locale survives at runtime
-rg -n -- '--bb-(contrasting|primary-base|hint|icon-color|input-|overlay-|button-|dialog-p)'  # retired tokens
 ```
 
+**CSS: tokens and class names**
+
+```bash
+rg -n -- '--bb-(contrasting|hint|icon-color|primary-(base|dark)|panel-(light|dark|disabled)|border-(light|dark|hover)|text-(light|dark|secondary|tertiary)|input-(color|compact-|font-size|inner-h|prefix(-px)?([^-a-zA-Z0-9]|$))|label-(size|compact-spacing-y)|overlay-(color|opacity|z-index)|dialog-|button-|badge-|checkbox-w|radio-space|switch-|rating-size|base-rating-spacing|slider-|table-|select-option-|select-popover-|progress-track|toast-m|breadcrumbs-|picker-|icon-dimensions-)'  # every retired v2 token — v3 declares none of them (sections 3 and 5.7)
+rg -n -- '--bb-ring-opacity'              # survives by name; every value must now carry a % (section 3)
+rg -n 'bb-base-dialog|bb-tab__|bb-tab--|bb-cr-container|bb-common-input-outer-container|bb-common-input-inner-container|bb-base-input-container__input|bb-base-(checkbox|radio|switch)-container|bb-tree-row|bb-tree-main-content|bb-confirm__no|bb-dropdown__wrapper|bb-offcanvas__close|bb-popover__close|bb-ratio'  # renamed or deleted CSS blocks — nothing in v3 emits any of these (§5.6)
+rg -n 'bb-color-palette__'                # → .bb-base-color-palette__*; only __popover survives under the old name
+rg -n 'bb-tabs--'                         # v3's own modifiers are --horizontal --vertical --block --compact --disabled; anything else is app-minted, and a hand-rolled full-width tab list is now <BbTabs block>
+```
+
+⚠ That first pattern is exact on purpose, and the near-misses are the point: a
+looser one (`input-`, `overlay-`, `dialog-p`) sweeps up tokens that are still
+live globals, and deleting those overrides shifts the layout silently. All of
+these survive in v3 under the same name — do not remove them because a pattern
+matched: `--bb-input-h`, `-px`, `-py`, `-icon`, `-spacing`, `-prefix-w`,
+`--bb-leading`, `--bb-label-spacing-x` / `-spacing-y`, `--bb-label-weight`,
+`--bb-ring-size`, `--bb-ring-opacity`, `--bb-arrow`, `--bb-radius`,
+`--bb-primary`, `--bb-panel`, `--bb-text`, `--bb-border`, `--bb-danger`,
+`--bb-ring`, `--bb-surface-hover` (and `--bb-overlay-blur`, new in v3). Six of
+them changed **default value** — the drift table in section 3 says which.
+
 Also review, with no greppable signature: dialog/off-canvas **widths**
 (section 2), the **primary color** (section 3), `adaptive` bottom sheets on
 mobile (section 6), and any UX that relied on second-click-to-clear selects.
@@ -44704,7 +46147,10 @@ mobile (section 6), and any UX that relied on second-click-to-clear selects.
 Detailed old→new tables and edit outlines live in
 [`migration/components/`](./components/). Components not listed have **no
 functional changes** — nothing to migrate beyond the family-wide notes above.
-That no-migration set is: `BbNumberInput`, `BbTextarea`, `BbProgress`.
+That no-migration set is: `BbNumberInput`, `BbTextarea`, `BbProgress` — with
+one caveat: the family-wide CSS renames in §5.6 still reach them
+(`.bb-base-textarea--compact`, `.bb-progress--horizontal` and the input-chrome
+blocks all moved), so check your stylesheet even for these three.
 
 `BbSmoothHeight` is **not** in it: its `tag` narrowed from any non-void element
 to `'div' | 'span'`, so anything else is now a compile error — see
@@ -44723,11 +46169,12 @@ to `'div' | 'span'`, so anything else is now a compile error — see
 | Selects           | [BbSelect](./components/bb-select.md) · [BbSelectPopover](./components/bb-select-popover.md)                                                                                                                                                              |
 | Choice controls   | [BbCheckbox / BbRadio / BbSwitch](./components/bb-checkbox.md) · [the three groups](./components/bb-checkbox-group.md)                                                                                                                                    |
 | Other inputs      | [BbSlider](./components/bb-slider.md) · [BbRating](./components/bb-rating.md) · [BbTag](./components/bb-tag.md) · [BbDropzone](./components/bb-dropzone.md)                                                                                               |
+| Removed           | [BbIntersection](./components/bb-intersection.md) · [useBroadcastChannelInstance](./components/use-broadcast-channel-instance.md)                                                                                                                         |
 
 ---
 
 <!-- dist/ai/guides/options-items-playbook.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/options-items-playbook.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/options-items-playbook.md -->
 
 # Options and Items Playbook
 
@@ -44950,7 +46397,7 @@ When an item is a link, the component navigates — never your code. `BbDropdown
 ---
 
 <!-- dist/ai/guides/page-shell.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/page-shell.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/page-shell.md -->
 
 # Page Shell
 
@@ -45216,7 +46663,7 @@ Two things in that rule are load-bearing if you change it:
 ---
 
 <!-- dist/ai/guides/validated-forms.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/guides/validated-forms.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/validated-forms.md -->
 
 # Validated Forms
 
@@ -45410,7 +46857,7 @@ rules in `fixtures/vue/app/validators.ts`), asserted by
 ---
 
 <!-- dist/ai/GuidesComponent.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/GuidesComponent.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/GuidesComponent.md -->
 
 # GuidesComponent
 
@@ -45437,7 +46884,7 @@ rules in `fixtures/vue/app/validators.ts`), asserted by
 ---
 
 <!-- dist/ai/index.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/index.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/index.md -->
 
 # AI Knowledge Base
 
@@ -45656,40 +47103,40 @@ Do not use these components directly in consumer code unless the user explicitly
 - [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) - Canonical installation, style handling, and full plugin option reference for Vite, Nuxt, and Inertia consumers.
 - [Migration v2 → v3](./guides/migration/v2-to-v3.md) - Complete upgrade guide from bitboss-ui 2.x to 3.0 — plugin-based setup, token overhaul, variant registries, global behavioral changes, and the silent-failure audit playbook.
 - [Migration v2→v3: BbAlert](./guides/migration/components/bb-alert.md) - showClose inverted to hideClose, theme replaced by typed variant.
-- [Migration v2→v3: BbAvatar](./guides/migration/components/bb-avatar.md) - The color prop is removed — the initials fallback is always primary.
+- [Migration v2→v3: BbAvatar](./guides/migration/components/bb-avatar.md) - The color prop is removed — retheme the fallback through the --bg-color / --text-color locals.
 - [Migration v2→v3: BbBadge (and where your v2 badges went)](./guides/migration/components/bb-badge.md) - The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
 - [Migration v2→v3: BbBreadcrumbs](./guides/migration/components/bb-breadcrumbs.md) - Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
 - [Migration v2→v3: BbButton](./guides/migration/components/bb-button.md) - Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry.
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](./guides/migration/components/bb-checkbox.md) - reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
-- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](./guides/migration/components/bb-checkbox-group.md) - labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required.
+- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](./guides/migration/components/bb-checkbox-group.md) - labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 - [Migration v2→v3: BbChip (removed)](./guides/migration/components/bb-chip.md) - BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
 - [Migration v2→v3: BbCollapsible](./guides/migration/components/bb-collapsible.md) - The tag prop is removed; the root is always a div.
 - [Migration v2→v3: BbColorInput](./guides/migration/components/bb-color-input.md) - picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](./guides/migration/components/bb-color-palette.md) - flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](./guides/migration/components/bb-date-picker-input.md) - allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
-- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, several presentation props removed, default widths changed, adaptive bottom sheet on mobile by default.
+- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
 - [Migration v2→v3: BbDropdown](./guides/migration/components/bb-dropdown.md) - Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
 - [Migration v2→v3: BbDropdownButton](./guides/migration/components/bb-dropdown-button.md) - autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
 - [Migration v2→v3: BbDropzone](./guides/migration/components/bb-dropzone.md) - modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](./guides/migration/components/bb-icon.md) - The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](./guides/migration/components/bb-intersection.md) - Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
-- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction→side; showClose→hideClose; size defaults change; adaptive drawer configs unify on offCanvasProps.
+- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
 - [Migration v2→v3: BbPagination](./guides/migration/components/bb-pagination.md) - querykey renamed to queryKey; the loading prop is removed.
 - [Migration v2→v3: BbPopover](./guides/migration/components/bb-popover.md) - Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
-- [Migration v2→v3: BbRating](./guides/migration/components/bb-rating.md) - color removed; name no longer required.
+- [Migration v2→v3: BbRating](./guides/migration/components/bb-rating.md) - color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
 - [Migration v2→v3: BbSelect](./guides/migration/components/bb-select.md) - allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
 - [Migration v2→v3: BbSelectPopover](./guides/migration/components/bb-select-popover.md) - flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
 - [Migration v2→v3: BbSlider](./guides/migration/components/bb-slider.md) - thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](./guides/migration/components/bb-smooth-height.md) - The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](./guides/migration/components/bb-spinner.md) - The color prop is removed; spinners follow currentColor.
-- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row.
-- [Migration v2→v3: BbTabs (was BbTab)](./guides/migration/components/bb-tabs.md) - Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized.
+- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.
+- [Migration v2→v3: BbTabs (was BbTab)](./guides/migration/components/bb-tabs.md) - Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
 - [Migration v2→v3: BbTag](./guides/migration/components/bb-tag.md) - modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
-- [Migration v2→v3: BbTextInput](./guides/migration/components/bb-text-input.md) - The type prop narrows to the text-like input types — number/date values must move to their dedicated components.
+- [Migration v2→v3: BbTextInput](./guides/migration/components/bb-text-input.md) - The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
 - [Migration v2→v3: BbToast and toast()](./guides/migration/components/bb-toast.md) - Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).
 - [Migration v2→v3: BbTooltip](./guides/migration/components/bb-tooltip.md) - timeout renamed to delay; theme replaced by typed variant; hideArrow is now a declared prop; block removed; modelValue is new.
 - [Migration v2→v3: BbTree](./guides/migration/components/bb-tree.md) - Item model rewritten — payload moves under meta, open becomes expanded, identifier becomes itemValue, expansion is a v-model.
-- [Migration v2→v3: confirm() / useConfirm](./guides/migration/components/use-confirm.md) - yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, labels are localized, footer buttons default md.
+- [Migration v2→v3: confirm() / useConfirm](./guides/migration/components/use-confirm.md) - yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, theme→variant, timeout→duration, autoClose flips to default-true, labels are localized, footer buttons default md.
 - [Migration v2→v3: useBroadcastChannelInstance](./guides/migration/components/use-broadcast-channel-instance.md) - Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
 - [Options and Items Playbook](./guides/options-items-playbook.md) - How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
 - [Page Shell](./guides/page-shell.md) - App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
@@ -45698,7 +47145,7 @@ Do not use these components directly in consumer code unless the user explicitly
 ---
 
 <!-- dist/ai/ListBox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/ListBox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ListBox.md -->
 
 # ListBox
 
@@ -45745,7 +47192,7 @@ Do not use these components directly in consumer code unless the user explicitly
 ---
 
 <!-- dist/ai/OptionsContainer.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/OptionsContainer.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/OptionsContainer.md -->
 
 # OptionsContainer
 
@@ -45787,7 +47234,7 @@ Do not use these components directly in consumer code unless the user explicitly
 ---
 
 <!-- dist/ai/recipes/inertia/approvals-inbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/approvals-inbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/approvals-inbox.md -->
 
 # Recipe: Approvals Inbox (Inertia)
 
@@ -47439,7 +48886,7 @@ function` — identical call sites to the Vue/Nuxt recipes,
 ---
 
 <!-- dist/ai/recipes/inertia/command-palette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/command-palette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/command-palette.md -->
 
 # Recipe: Command Palette (Inertia)
 
@@ -47751,7 +49198,7 @@ const { open } = useCommandPalette();
 ---
 
 <!-- dist/ai/recipes/inertia/inline-edit-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/inline-edit-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/inline-edit-workspace.md -->
 
 # Recipe: Inline-Edit Workspace (Inertia)
 
@@ -49563,7 +51010,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/recipes/inertia/layout-scaffold.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/layout-scaffold.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/layout-scaffold.md -->
 
 <!--
 	GENERATED FILE — do not edit by hand.
@@ -50301,7 +51748,7 @@ the current page (mobile nav, global filters).
 ---
 
 <!-- dist/ai/recipes/inertia/onboarding.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/onboarding.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/onboarding.md -->
 
 # Recipe: Workspace Onboarding (Inertia)
 
@@ -52093,7 +53540,7 @@ OnboardingState::for($request->user())])`) and drop the workspace-wide
 ---
 
 <!-- dist/ai/recipes/inertia/ownership-atlas.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/ownership-atlas.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/ownership-atlas.md -->
 
 # Recipe: Ownership Atlas (Inertia)
 
@@ -53483,7 +54930,7 @@ export interface OwnerDetail extends Owner {
 ---
 
 <!-- dist/ai/recipes/inertia/record-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/record-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/record-form.md -->
 
 # Recipe: Record Form (Inertia)
 
@@ -54973,7 +56420,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/inertia/records-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/records-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/records-workspace.md -->
 
 # Recipe: Records Workspace (Inertia)
 
@@ -56616,7 +58063,7 @@ If a page genuinely has no peek, delete the shell wiring rather than leaving
 ---
 
 <!-- dist/ai/recipes/inertia/upload-center.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/upload-center.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/upload-center.md -->
 
 # Recipe: Upload Center (Inertia)
 
@@ -58628,7 +60075,7 @@ function` — identical call sites to the Vue/Nuxt recipes,
 ---
 
 <!-- dist/ai/recipes/inertia/wizard-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/inertia/wizard-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/wizard-form.md -->
 
 # Recipe: Wizard Form (Inertia)
 
@@ -60129,7 +61576,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/recipes/nuxt/approvals-inbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/approvals-inbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/approvals-inbox.md -->
 
 # Recipe: Approvals Inbox (Nuxt)
 
@@ -61718,7 +63165,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/nuxt/command-palette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/command-palette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/command-palette.md -->
 
 # Recipe: Command Palette (Nuxt)
 
@@ -62019,7 +63466,7 @@ const { open } = useCommandPalette();
 ---
 
 <!-- dist/ai/recipes/nuxt/inline-edit-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/inline-edit-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/inline-edit-workspace.md -->
 
 # Recipe: Inline-Edit Workspace (Nuxt)
 
@@ -63773,7 +65220,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/recipes/nuxt/layout-scaffold.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/layout-scaffold.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/layout-scaffold.md -->
 
 <!--
 	GENERATED FILE — do not edit by hand.
@@ -64511,7 +65958,7 @@ the current page (mobile nav, global filters).
 ---
 
 <!-- dist/ai/recipes/nuxt/onboarding.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/onboarding.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/onboarding.md -->
 
 # Recipe: Workspace Onboarding (Nuxt)
 
@@ -66236,7 +67683,7 @@ const previews: Record<StepId, StepPreview> = {
 ---
 
 <!-- dist/ai/recipes/nuxt/record-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/record-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/record-form.md -->
 
 # Recipe: Record Form (Nuxt)
 
@@ -67739,7 +69186,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/nuxt/records-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/records-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/records-workspace.md -->
 
 # Recipe: Records Workspace (Nuxt)
 
@@ -69300,7 +70747,7 @@ If a page genuinely has no peek, delete the shell wiring rather than leaving
 ---
 
 <!-- dist/ai/recipes/nuxt/upload-center.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/upload-center.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/upload-center.md -->
 
 # Recipe: Upload Center (Nuxt)
 
@@ -71195,7 +72642,7 @@ void ctx.rows.value; … })` re-fetches its own JSON detail for free — the
 ---
 
 <!-- dist/ai/recipes/nuxt/wizard-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/nuxt/wizard-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/wizard-form.md -->
 
 # Recipe: Wizard Form (Nuxt)
 
@@ -72705,7 +74152,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/recipes/vue/approvals-inbox.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/approvals-inbox.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/approvals-inbox.md -->
 
 # Recipe: Approvals Inbox (Vue)
 
@@ -74212,7 +75659,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/vue/command-palette.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/command-palette.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/command-palette.md -->
 
 # Recipe: Command Palette (Vue)
 
@@ -74510,7 +75957,7 @@ const { open } = useCommandPalette();
 ---
 
 <!-- dist/ai/recipes/vue/inline-edit-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/inline-edit-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/inline-edit-workspace.md -->
 
 # Recipe: Inline-Edit Workspace (Vue)
 
@@ -76156,7 +77603,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/recipes/vue/layout-scaffold.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/layout-scaffold.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/layout-scaffold.md -->
 
 <!--
 	GENERATED FILE — do not edit by hand.
@@ -76894,7 +78341,7 @@ the current page (mobile nav, global filters).
 ---
 
 <!-- dist/ai/recipes/vue/onboarding.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/onboarding.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/onboarding.md -->
 
 # Recipe: Workspace Onboarding (Vue)
 
@@ -78574,7 +80021,7 @@ const previews: Record<StepId, StepPreview> = {
 ---
 
 <!-- dist/ai/recipes/vue/record-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/record-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/record-form.md -->
 
 # Recipe: Record Form (Vue)
 
@@ -80161,7 +81608,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/vue/records-workspace.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/records-workspace.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/records-workspace.md -->
 
 # Recipe: Records Workspace (Vue)
 
@@ -81638,7 +83085,7 @@ If a page genuinely has no peek, delete the shell wiring rather than leaving
 ---
 
 <!-- dist/ai/recipes/vue/upload-center.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/upload-center.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/upload-center.md -->
 
 # Recipe: Upload Center (Vue)
 
@@ -83492,7 +84939,7 @@ const currency = new Intl.NumberFormat('en-US', {
 ---
 
 <!-- dist/ai/recipes/vue/wizard-form.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/recipes/vue/wizard-form.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/wizard-form.md -->
 
 # Recipe: Wizard Form (Vue)
 
@@ -84934,7 +86381,7 @@ const longDate = (value: string) =>
 ---
 
 <!-- dist/ai/WarningIcon.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/WarningIcon.md -->
+<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/WarningIcon.md -->
 
 # WarningIcon