bitboss-ui 3.0.0-alpha.4 → 3.0.0-alpha.6

package/README.md

@@ -6,11 +6,29 @@ Vue 3 component library used across BitBoss products. It ships typed building bl
 
 ## What’s in the package
 
-Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, and **`index.css`**) plus this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
+Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
 
 ### Styles
 
 - **Global stylesheet** — import `bitboss-ui/styles.css` once. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
+- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`).
+
+### TypeScript: use `vue-tsc` 3
+
+Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
+silently checks **nothing** about the props of the nine components declared with
+`generic="T"` — `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`,
+`BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` —
+because they emit as generic functions rather than `DefineComponent<…>`, a shape
+Vue Language Tools 2 cannot read props out of.
+
+The trap is that the failure is partial and invisible: unknown-**component**
+checking still fires and non-generic components still reject bad props, so the
+gate looks like it is working. A real consumer shipped
+`<BbRadioGroup label="…">` (the prop is `legend`) through six release slices on
+`vue-tsc@^2.2.12` with a green `--noEmit`.
+
+Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### TypeScript: icons
 
@@ -18,15 +36,16 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, and **`index.css`*
 
 ### Composables
 
-| Composable                    | Role                                                      |
-| ----------------------------- | --------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).      |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging. |
-| `useConfirm`                  | Programmatic confirm / modal flows.                       |
-| `useCountdown`                | Countdown timer state.                                    |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                     |
-| `useQueue`                    | Simple async task queue.                                  |
-| `useToast`                    | Toast notifications API.                                  |
+| Composable                    | Role                                                       |
+| ----------------------------- | ---------------------------------------------------------- |
+| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
+| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
+| `useConfirm`                  | Programmatic confirm / modal flows.                        |
+| `useCountdown`                | Countdown timer state.                                     |
+| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
+| `useQueue`                    | Simple async task queue.                                   |
+| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
+| `useToast`                    | Toast notifications API.                                   |
 
 ### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
 
@@ -70,13 +89,14 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 The same knowledge base the npm package ships is served publicly over a CDN, so
 an agent can read it before anything is installed. `@alpha` tracks the latest
-v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.4`) for stable
-links.
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
+links. Sizes grow with the catalogue — treat them as the current order of
+magnitude, not a contract.
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~74 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~17 KB) — link index into every document.
+- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~19 KB) — link index into every document.
 - [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~2.9 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -203,10 +223,19 @@ can **query** the knowledge base (search components, read a contract, validate
 markup) instead of reading files blind:
 
 ```bash
+npm i -D @modelcontextprotocol/sdk zod
 npx bitboss-ui ai-init --mcp
 ```
 
-The agent harness launches the server itself (`npx bitboss-ui mcp`) on demand —
+Those two are **optional peer dependencies**, not dependencies: together they
+weigh ~12 MB — more than every runtime dependency of the component library
+combined — and nothing but the MCP server loads them, so installing
+`bitboss-ui` never drags them in. `ai-init --mcp` warns if they are missing,
+and `bitboss-ui mcp` tells you what to install rather than dying on a module
+resolution error.
+
+The agent harness launches the server itself (`npx bitboss-ui@<installed version> mcp`,
+pinned so npx can never fall back to fetching a different version from the registry) on demand —
 you never run it by hand. `--mcp` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
@@ -331,13 +360,16 @@ A standard `llms.txt` discovery file is also published at:
 
 ### Package exports
 
-```ts
-// catalogue entry
-import 'bitboss-ui/ai';
-// or resolve concrete files:
-// bitboss-ui/ai/components.json
-// bitboss-ui/ai/guides/ai-router.md
-```
+These are **resolution paths, not importable modules** — they resolve to
+Markdown and JSON, so a side-effect `import` of them neither type-checks nor
+bundles. Use them with `import.meta.resolve` / `require.resolve`, or read the
+files directly:
+
+| Subpath                             | Resolves to                    |
+| ----------------------------------- | ------------------------------ |
+| `bitboss-ui/ai`                     | `dist/ai/index.md` (catalogue) |
+| `bitboss-ui/ai/components.json`     | `dist/ai/components.json`      |
+| `bitboss-ui/ai/guides/ai-router.md` | `dist/ai/guides/ai-router.md`  |
 
 Agents can also read paths under `node_modules/bitboss-ui/dist/ai/` directly.
 
@@ -374,7 +406,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 The source repository is private while v3 is in development, so there is no
 public issue tracker yet. **Report bugs by email to
-[dev@bitboss.it](mailto:dev@bitboss.it)** — that address is the `bugs` contact
+[hey@bitboss.it](mailto:hey@bitboss.it)** — that address is the `bugs` contact
 in `package.json`, so `npm bugs bitboss-ui` opens it too.
 
 To make a report actionable, include:

package/bin/bitboss-ui-mcp.mjs

@@ -7,8 +7,22 @@
  *
  * Built on `@modelcontextprotocol/sdk` (McpServer over the stdio transport);
  * the SDK owns JSON-RPC framing, capability handshake, and protocol-version
- * negotiation. Tool input schemas are declared as zod shapes (zod ships with
- * the SDK); the SDK renders them to the JSON Schema advertised by tools/list.
+ * negotiation. Tool input schemas are declared as zod shapes; the SDK renders
+ * them to the JSON Schema advertised by tools/list.
+ *
+ * BOTH imports below are OPTIONAL PEERS, not dependencies — together ~12 MB,
+ * more than every runtime dependency of the component library combined, and
+ * loaded by nothing else. `bin/bitboss-ui.mjs` catches the resolution failure
+ * and names them; `missingMcpPeers()` warns at registration time.
+ *
+ * `zod`'s declared range is `^3.25 || ^4.0` — copied verbatim from the SDK's
+ * own dependency range, NOT invented. Do not "simplify" it to `>=` or to a
+ * single major: the schemas built here are validated by the SDK's OWN copy of
+ * zod, so a consumer hoisting a different MAJOR fails the SDK's brand checks
+ * while npm stays silent (both ranges are independently satisfied). Mirroring
+ * the range means it moves when the SDK's does. Everything used here
+ * (`z.string`, `z.enum`, `z.number`, `.describe`, `.int`, `.min`, `.optional`)
+ * is stable across zod 3 and 4, so the lower bound costs nothing.
  *
  * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
  * Register with an MCP-capable harness via `npx bitboss-ui ai-init --mcp`.
@@ -17,7 +31,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {
@@ -257,7 +271,7 @@ function* eachTokenDeclaration(css) {
 
 /**
  * `list_tokens({ filter })` — the `--bb-*` design tokens with their values,
- * read from the shipped stylesheet (the same 89 `check:tokens` counts).
+ * read from the shipped stylesheet (the same 90 `check:tokens` counts).
  *
  * WHY ONLY `--bb-*` — and why there is no opt-in for the unprefixed ones, even
  * though `search_components` has `includeReferenceOnly`. The two tiers are not
@@ -405,12 +419,28 @@ function getRecipe({ platform, name, maxChars } = {}) {
 			error: `Unknown platform '${platform}' — expected one of ${RECIPE_PLATFORMS.join(', ')}`,
 		};
 	}
-	const fileName = String(name ?? '').endsWith('.md')
-		? String(name)
-		: `${name}.md`;
-	const filePath = join(AI_ROOT, 'recipes', platform, fileName);
-	if (!existsSync(filePath)) {
-		return { found: false, error: `Recipe not found: ${platform}/${fileName}` };
+	// Contain reads to the platform's recipe dir — no traversal out of the
+	// knowledge base. `platform` is already allow-listed above, but `name` is
+	// free text, so it gets the same treatment as `get_guide`'s: leading
+	// separators stripped, `..` rejected outright, and the joined path checked
+	// to still sit under the recipe dir.
+	const rel = String(name ?? '').replace(/^\/+/, '');
+	if (!rel || rel.includes('..')) {
+		return {
+			found: false,
+			error: `Invalid recipe name '${name}'.`,
+			hint: 'Call list_recipes for the available names.',
+		};
+	}
+	const fileName = rel.endsWith('.md') ? rel : `${rel}.md`;
+	const recipesDir = join(AI_ROOT, 'recipes', platform);
+	const filePath = join(recipesDir, fileName);
+	if (!filePath.startsWith(`${recipesDir}${sep}`) || !existsSync(filePath)) {
+		return {
+			found: false,
+			error: `Recipe not found: ${platform}/${fileName}`,
+			hint: 'Call list_recipes for the available names.',
+		};
 	}
 	const { content, ...meta } = truncateMarkdown(
 		readFileSync(filePath, 'utf-8'),

package/bin/bitboss-ui.mjs

@@ -16,7 +16,9 @@
  *   locale    Generate a custom locale blueprint (.locale.ts)
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
- *             v-models). Exits 1 on findings; supports --json output.
+ *             v-models, unknown `<template #slot>` names, `href`/`to`/
+ *             `method` on a component that doesn't declare them). Exits 1
+ *             on findings; supports --json output.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
  *             (search_components, get_component, list_recipes, get_recipe,
  *             validate) to MCP-capable agent harnesses.
@@ -33,11 +35,15 @@ import {
 	statSync,
 	writeFileSync,
 } from 'node:fs';
+import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
 import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { ensureMcpConfigs } from '../scripts/lib/mcp-config.mjs';
+import {
+	ensureMcpConfigs,
+	missingMcpPeers,
+} from '../scripts/lib/mcp-config.mjs';
 import {
 	loadManifest,
 	validateMarkdown,
@@ -236,6 +242,21 @@ function aiInit({ mcp = false } = {}) {
 				action: result.action,
 			});
 		}
+
+		// The harness launches the server on demand, long after this command
+		// ran — so a missing peer would surface inside an agent as a server
+		// that never starts. Say it here, where the person is still watching.
+		const missing = missingMcpPeers(projectRoot);
+		if (missing.length > 0) {
+			console.warn(
+				`[bitboss-ui] the MCP server needs ${missing.join(' and ')}, which ${
+					missing.length > 1 ? 'are' : 'is'
+				} not installed:\n` +
+					`\n  npm i -D ${missing.join(' ')}\n\n` +
+					'  Optional peers, not dependencies — ~12 MB that only the MCP\n' +
+					'  server uses. The harness entries above are written either way.'
+			);
+		}
 	}
 
 	console.log(`[bitboss-ui] ai-init complete (library v${version})`);
@@ -533,10 +554,11 @@ function summarizeFileCounts(files) {
 }
 
 /**
- * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup in `.vue`
- * and `.md` files against the installed components.json manifest.
+ * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup (props,
+ * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
+ * the installed components.json manifest.
  */
-function checkCommand(globs, jsonMode) {
+function checkCommand(globs, jsonMode, allowEmpty = false) {
 	const projectRoot = process.cwd();
 
 	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
@@ -547,9 +569,34 @@ function checkCommand(globs, jsonMode) {
 		process.exit(1);
 	}
 	const manifest = loadManifest(manifestPath);
+
+	/*
+	 * Every `--bb-*` the INSTALLED package declares, read from the stylesheet
+	 * the consumer actually ships. Read from disk rather than hardcoded so this
+	 * can never claim a token is invented when their version does declare it.
+	 * Absent stylesheet → an empty set → the unknown-token hint stays silent,
+	 * which is the right failure: no data, no accusation.
+	 */
+	const stylesPath = join(PACKAGE_ROOT, 'dist', 'styles.css');
+	const knownTokens = existsSync(stylesPath)
+		? new Set(
+				[
+					...readFileSync(stylesPath, 'utf-8').matchAll(
+						/(--bb-[a-z0-9-]+)\s*:/gi
+					),
+				].map((m) => m[1].toLowerCase())
+			)
+		: new Set();
 	const files = resolveCheckFiles(projectRoot, globs);
 
 	const findings = [];
+	/*
+	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
+	 * exit code, so a guess can never fail a consumer's build. `--no-hints`
+	 * silences them for anyone who finds them noisy.
+	 */
+	const hints = [];
+	const wantHints = !process.argv.includes('--no-hints');
 	for (const file of files) {
 		const relPath = relative(projectRoot, file);
 		const content = readFileSync(file, 'utf-8');
@@ -559,15 +606,53 @@ function checkCommand(globs, jsonMode) {
 		for (const finding of fileFindings) {
 			findings.push({ file: relPath, ...finding });
 		}
+		// .md files are documentation ABOUT components; a round <img> in a doc
+		// example is illustrative, not a hand-roll.
+		if (wantHints && !file.endsWith('.md')) {
+			for (const hint of findHandRollHints(content, knownTokens)) {
+				hints.push({ file: relPath, ...hint });
+			}
+		}
 	}
 
+	/** Advisory block, printed on success and on failure alike. Never fatal. */
+	const printHints = () => {
+		if (hints.length === 0) return;
+		console.log(
+			`\n[bitboss-ui] ${hints.length} hint(s) — advisory, not errors:`
+		);
+		for (const hint of hints) {
+			console.log(`  ${hint.file}:${hint.line}`);
+			console.log(`    → ${hint.message}`);
+		}
+		console.log(
+			'  Deliberate? Ignore these, record them in a HANDROLLED note, or pass --no-hints.'
+		);
+	};
+
 	if (jsonMode) {
-		console.log(JSON.stringify({ findings }, null, 2));
+		console.log(
+			JSON.stringify({ findings, hints, files: files.length }, null, 2)
+		);
 		if (findings.length > 0) process.exit(1);
+		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
 		return;
 	}
 
 	if (files.length === 0) {
+		// An EXPLICIT pattern that matched nothing is almost always a typo'd or
+		// stale CI path, and answering it with exit 0 means the step goes green
+		// having validated nothing — the check that was meant to catch bad
+		// markup is itself the thing that broke, silently (SWP-016). A bare
+		// sweep finding nothing is a different, legitimate case (a package with
+		// no .vue files yet), so it still passes.
+		if (globs.length > 0 && !allowEmpty) {
+			console.error(
+				`[bitboss-ui] check: no .vue/.md files matched ${globs.map((g) => `\`${g}\``).join(', ')} — nothing was validated. ` +
+					'Fix the path, or pass `--allow-empty` if an empty match is expected.'
+			);
+			process.exit(1);
+		}
 		console.log(
 			'[bitboss-ui] check: no .vue/.md files matched — nothing to do.'
 		);
@@ -576,8 +661,9 @@ function checkCommand(globs, jsonMode) {
 
 	if (findings.length === 0) {
 		console.log(
-			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models.`
+			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
+		printHints();
 		return;
 	}
 
@@ -603,6 +689,7 @@ function checkCommand(globs, jsonMode) {
 	console.error(
 		'\nFix the markup (or the component API) so it stays copy-safe for agents.'
 	);
+	printHints();
 	process.exit(1);
 }
 
@@ -621,14 +708,19 @@ Commands:
                       server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
                       VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
                       global) — merges, never overwrites other servers.
-  check [glob…] [--json]
+  check [glob…] [--json] [--allow-empty]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
-                      bad v-models). Defaults to every .vue/.md file under the
-                      current directory (node_modules, dist, .git, vendor,
+                      bad v-models, unknown \`<template #slot>\` names,
+                      \`href\`/\`to\`/\`method\` on a component that doesn't declare
+                      them). Defaults to every .vue/.md file under the current directory
+                      (node_modules, dist, .git, vendor,
                       storage, public, .output, .nuxt, bootstrap/cache
                       excluded — pass an explicit glob/path to widen the scan).
-                      Exits 1 on findings; \`--json\` prints \`{ findings: [...] }\`.
+                      Exits 1 on findings, and on an explicit glob that matched
+                      nothing (a typo'd CI path validates zero files silently) —
+                      pass \`--allow-empty\` when an empty match is expected.
+                      \`--json\` prints \`{ findings: [...], files }\`.
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
@@ -674,14 +766,41 @@ switch (command) {
 		const { values, positionals } = parseCommandArgs(
 			command,
 			commandArgs,
-			{ json: { type: 'boolean' } },
+			{
+				json: { type: 'boolean' },
+				'allow-empty': { type: 'boolean' },
+			},
 			{ allowPositionals: true }
 		);
-		checkCommand(positionals, values.json ?? false);
+		checkCommand(
+			positionals,
+			values.json ?? false,
+			values['allow-empty'] ?? false
+		);
 		break;
 	}
 	case 'mcp': {
-		const { main } = await import('./bitboss-ui-mcp.mjs');
+		// `@modelcontextprotocol/sdk` + `zod` are OPTIONAL peers, not
+		// dependencies: together they weigh ~12 MB — more than every runtime
+		// dependency of the component library combined, and the SDK drags in a
+		// whole HTTP stack (express, hono, cors, jose). Only this subcommand
+		// needs them, so consumers who never run the MCP server do not pay for
+		// it. That makes the import failure a SUPPORTED path, and a bare
+		// ERR_MODULE_NOT_FOUND stack is not an answer — say what to install.
+		let main;
+		try {
+			({ main } = await import('./bitboss-ui-mcp.mjs'));
+		} catch (error) {
+			if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+			console.error(
+				'bitboss-ui mcp needs two optional peer dependencies that are not installed:\n' +
+					'\n  npm i -D @modelcontextprotocol/sdk zod\n\n' +
+					'They are optional because they are ~12 MB and only this subcommand uses them.\n' +
+					`Resolution failed with: ${error.message}`
+			);
+			process.exitCode = 1;
+			break;
+		}
 		await main();
 		break;
 	}

package/dist/ai/BbAlert.md

@@ -76,6 +76,13 @@ icon as a pair.
 The default variant is `outline`. `warning` and `destructive` are treated as
 high-priority for accessibility (see below).
 
+There is no `success` (or `positive`) variant, and it will not be added — the
+shared status vocabulary is closed to `danger`/`warn` by ruling, see
+[Design Tokens § Brand knobs](./guides/design-tokens.md#brand-knobs-what-a-theme-builder-sets)
+("state colors are project-owned"). Reach for `primary` for a positive
+confirmation, or register your own variant (below) if the project needs a
+distinct success tone.
+
 #### Registering project variants
 
 Variants are an open registry, not a closed enum. The vite/nuxt plugin's
@@ -200,9 +207,13 @@ click handler for something a link can do.
 </div>
 ```
 
-These are the only two slots — there is no default or actions slot. A short
-inline link in `#text` (as above) is fine; anything more interactive belongs
-outside the alert, or in a `BbDialog`.
+**The default slot is the text slot.** `<BbAlert>Something went wrong</BbAlert>`
+is the shortest form and the one to reach for; `text` as a prop is for when a
+string is all you have (an `:items` loop, a server message). When more than one
+is present the most specific wins: `#text` > children > `text`.
+
+There is no `actions` slot. A short inline link in the text (as above) is fine;
+anything more interactive belongs outside the alert, or in a `BbDialog`.
 
 #### Brand art via a raw SVG
 
@@ -346,9 +357,6 @@ const publish = () => {
 
 ### Gotchas & anti-patterns
 
-- **There is no default slot.** `<BbAlert>some text</BbAlert>` renders
-  nothing — Vue drops an unconsumed default slot silently, with no warning.
-  Use `title`/`text` (or `#title`/`#text`, see above).
 - **Omitting `v-model` does not make an alert permanent** — the close button
   still dismisses it locally. Use `hide-close` for that.
 - Don't rebuild dismissal with your own button + `v-if`; the built-in close
@@ -400,7 +408,8 @@ const publish = () => {
 
 ## Slots
 
-- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text.
+- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present…
+- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text. Wins over children and `text`.
 - `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.
 
 ## See Also