bitboss-ui 3.0.0-beta.57 → 3.0.0-beta.58

package/bin/bitboss-ui-mcp.mjs

@@ -1161,6 +1161,19 @@ function getComponent({
 		const type = (manifest.types ?? []).find((t) => t.name === name);
 		if (type) {
 			const use = type.usedBy?.[0];
+			// Q74.1: a component's own Props type is that component's props.
+			const propsOf =
+				type.component && name === `${type.component}Props`
+					? type.component
+					: null;
+			// Q74.2: `fields` stand in for a declaration that adds nothing.
+			const shape = type.definition
+				? '`definition` above is the type itself'
+				: type.fields
+					? '`fields` above are its shape'
+					: propsOf
+						? `Its fields are ${possessive(propsOf)} props: get_component('${propsOf}')`
+						: 'It is described above';
 			return {
 				found: true,
 				kind: 'type',
@@ -1179,9 +1192,10 @@ function getComponent({
 				...(type.fields ? { fields: type.fields } : {}),
 				// A union of private members: each member's fields (Q51.21).
 				...(type.members ? { members: type.members } : {}),
+				...(propsOf ? { propsOf } : {}),
 				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
 				hint: use
-					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. \`definition\` above is the type itself; call get_component('${use.component}') to see it in use.`
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. ${shape}; call get_component('${use.component}') to see it in use.`
 					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
 			};
 		}
@@ -2124,7 +2138,11 @@ function docIndex() {
 					? `accepted values ${type.values.join(' | ')}`
 					: type.fields
 						? `object shape, fields ${type.fields.join('; ')}`
-						: String(type.definition ?? '')) +
+						: type.definition
+							? String(type.definition)
+							: type.component && type.name === `${type.component}Props`
+								? `the props of ${type.component}`
+								: '') +
 				`. import type { ${type.name} } from 'bitboss-ui'.`,
 			read: { tool: 'get_component', args: { name: type.name } },
 		});
@@ -2556,6 +2574,66 @@ function changeLine(row, focus) {
 	return `${row.id} ${row.summary ?? firstSentence(row.description, 160)}`;
 }
 
+/**
+ * One page of `[release, line]` pairs, grouped by release: it ends at
+ * CHANGES_PAGE lines or CHANGES_PAGE_CHARS of them, so its size holds however
+ * long the lines grow; the rest is a cursor away.
+ */
+function pageLines(lines, cursor) {
+	const start = Math.max(0, Number(cursor ?? 0) || 0);
+	let end = start;
+	for (let used = 0; end < lines.length && end - start < CHANGES_PAGE; end++) {
+		used += lines[end][1].length + 3;
+		if (used > CHANGES_PAGE_CHARS && end > start) break;
+	}
+	const byRelease = {};
+	for (const [release, line] of lines.slice(start, end))
+		(byRelease[release] ??= []).push(line);
+	return {
+		byRelease,
+		more:
+			end < lines.length
+				? { nextCursor: String(end), remaining: lines.length - end }
+				: {},
+	};
+}
+
+/**
+ * Q74.4: what the releases in range ADDED, as `[release, "area · what"]`,
+ * oldest first; `unreleased` only when `until` is open. A component keeps
+ * the lines of its own area (BbDialog → `dialog`) and those whose commits
+ * touched its folder (a family scope: `inputs`).
+ */
+function addedPairs(doc, { since, until, component }) {
+	const area = component
+		? String(component).replace(/^Bb/, '').toLowerCase()
+		: null;
+	return Object.entries(doc.added ?? {})
+		.filter(([at]) => {
+			if (at === 'unreleased') return until == null;
+			if (since != null && compareVersions(at, String(since)) <= 0)
+				return false;
+			if (until != null && compareVersions(at, String(until)) > 0) return false;
+			return true;
+		})
+		.flatMap(([at, entries]) =>
+			entries
+				.map((entry) =>
+					typeof entry === 'string' ? { text: entry, components: [] } : entry
+				)
+				.filter(
+					({ text, components }) =>
+						!area ||
+						text.split(' · ')[0] === area ||
+						components.includes(String(component))
+				)
+				.map(({ text }) => [at, text])
+		);
+}
+
+const ADDED_HINT =
+	'Fixes are not tracked. What the range added, one line per feature: list_changes({ since, kind: "added" }).';
+
 function changeLines(rows, cursor, withClassMap = false, focus) {
 	const lines = [];
 	const classRenames = {};
@@ -2576,25 +2654,12 @@ function changeLines(rows, cursor, withClassMap = false, focus) {
 					? -1
 					: compareVersions(a, b)
 	);
+	const page = pageLines(lines, cursor);
+	// The class map rides on the first page only.
 	const start = Math.max(0, Number(cursor ?? 0) || 0);
-	// A page ends at CHANGES_PAGE lines or CHANGES_PAGE_CHARS of them, so its
-	// size holds however long the summaries grow; the rest is a cursor away.
-	let end = start;
-	for (let used = 0; end < lines.length && end - start < CHANGES_PAGE; end++) {
-		used += lines[end][1].length + 3;
-		if (used > CHANGES_PAGE_CHARS && end > start) break;
-	}
-	const byRelease = {};
-	for (const [release, line] of lines.slice(start, end))
-		(byRelease[release] ??= []).push(line);
 	return {
-		changes: byRelease,
-		...(end < lines.length
-			? {
-					nextCursor: String(end),
-					remaining: lines.length - end,
-				}
-			: {}),
+		changes: page.byRelease,
+		...page.more,
 		...(Object.keys(classRenames).length && start === 0 && !withClassMap
 			? {
 					classRenames: `${Object.keys(classRenames).length} .bb-* class renames (the beta.36 sweep): the map with surface: 'class'`,
@@ -2692,6 +2757,24 @@ function listChanges({
 		}
 	}
 
+	if (kind === 'added') {
+		const pairs = addedPairs(doc, { since, until, component });
+		const page = pageLines(pairs, cursor);
+		return {
+			version: doc.version,
+			since: since ?? null,
+			until: until ?? doc.version,
+			...(component ? { filteredBy: { component } } : {}),
+			count: pairs.length,
+			added: page.byRelease,
+			...page.more,
+			hint:
+				pairs.length === 0
+					? 'Nothing added in that range (fixes are not tracked).'
+					: 'One "area · what" line per feature, grouped by release, from its feat commit. Breaking changes: the same call without kind. Next page: cursor: nextCursor.',
+		};
+	}
+
 	const rows = detail === 'rows';
 	const filtered = (doc.breaking ?? []).filter(
 		(row) =>
@@ -2751,7 +2834,8 @@ function listChanges({
 						Object.fromEntries(Object.entries(bucket).filter(([, n]) => n > 0)),
 					])
 			),
-			hint: 'Counts only (a missing count is 0). What a bump breaks: list_changes({ since: "<your version>" }), one line per change; from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
+			added: addedPairs(doc, {}).length,
+			hint: 'Counts only (a missing count is 0). What a bump breaks: list_changes({ since: "<your version>" }), one line per change; from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows". `added`: features, kind: "added".',
 		};
 	}
 
@@ -2808,10 +2892,11 @@ function listChanges({
 			count: inRange.length,
 			...changeLines(inRange, cursor, surface === 'class', component),
 			guide: doc.guide,
+			added: addedPairs(doc, { since, until, component }).length,
 			hint:
 				inRange.length === 0
-					? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
-					: 'One line per change, grouped by the release that shipped it (id, components, old → new, or the break in one sentence). Whole rows: detail: "rows". The `guide` page explains each. Next page: cursor: nextCursor.',
+					? `No breaking changes recorded in that range: nothing BREAKS. ${ADDED_HINT}`
+					: `One line per change, grouped by the release that shipped it (id, components, old → new, or the break in one sentence). Whole rows: detail: "rows". The \`guide\` page explains each. Next page: cursor: nextCursor. \`added\`: features, kind: "added".`,
 		};
 	}
 
@@ -2824,7 +2909,7 @@ function listChanges({
 		guide: doc.guide,
 		hint:
 			inRange.length === 0
-				? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
+				? `No breaking changes recorded in that range: nothing BREAKS. ${ADDED_HINT}`
 				: `Each entry names the component and the new spelling; \`guide\` is the migration page with the full explanation. ${ROW_FIELDS}`,
 	};
 }
@@ -3018,7 +3103,7 @@ function buildServer() {
 		'list_changes',
 		{
 			description:
-				'Breaking changes between bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on>: one line per change, grouped by release. No arguments: counts per release. Narrow with component / surface / kind; detail: "rows" for the full records. Only BREAKING changes are tracked; features and fixes are not.',
+				'Breaking changes between bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on>: one line per change, grouped by release. No arguments: counts per release. Narrow with component / surface / kind; detail: "rows" for the full records. kind: "added" lists what the range added (features); fixes are not tracked.',
 			inputSchema: {
 				since: z
 					.string()
@@ -3053,9 +3138,11 @@ function buildServer() {
 						'Only renames of this surface (`item` = a field of an `items` entry, e.g. a dropdown row `key` → `value`).'
 					),
 				kind: z
-					.enum(['rename', 'behaviour'])
+					.enum(['rename', 'behaviour', 'added'])
 					.optional()
-					.describe('Only renames, or only behaviour changes.'),
+					.describe(
+						"Only renames, or only behaviour changes; 'added': what the range added (features), one line each."
+					),
 				detail: z
 					.enum(['lines', 'rows'])
 					.optional()

package/bin/bitboss-ui.mjs

@@ -40,8 +40,8 @@
  *   add       Copy Inertia helpers into the app as files it owns
  *             (scripts/lib/helpers-add.mjs); `helpers list|diff|update`
  *             reports on them and refreshes the ones the app has not edited.
- *   changelog Breaking changes between two releases — `--since <version>`
- *             answers "what breaks if I bump", without MCP. Reads the
+ *   changelog Breaking changes between two releases, then what they added —
+ *             `--since <version>` answers "what breaks if I bump", without MCP. Reads the
  *             installed `dist/ai/changelog.json`.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
  *             (search_docs, search_components, get_component, get_composable,
@@ -167,7 +167,7 @@ function coreRules(version) {
 1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
 2. **Obey the agent contract**: \`${CONTRACT}\`.
 3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
-4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
+4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; a row marked \`common: true\` is whole in \`${KNOWLEDGE_BASE}/manifest/common.json\`; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` (an object row reads its own \`label\` and \`value\`; \`item-text\` / \`item-value\` only for other field names, never to restate those two), \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
@@ -780,7 +780,7 @@ function printFindingLegend(findings) {
  */
 /**
  * `changelog [--since <v>] [--until <v>] [--json]` — what breaks between two
- * releases, for anyone not driving the MCP server (a human at a terminal, CI,
+ * releases, then what they added (Q74.4: one line per feature), for anyone not driving the MCP server (a human at a terminal, CI,
  * or an agent whose harness has no MCP). Same data and same range rules as the
  * `list_changes` tool; this is the transport-free path to it.
  */
@@ -823,6 +823,22 @@ function changelogCommand({ since, until, json: jsonMode }) {
 		if (until != null && compareReleaseVersions(at, until) > 0) return false;
 		return true;
 	});
+	// Q74.4: what the range ADDED (feat commits, one line each), oldest first.
+	const inRange = (at) => {
+		if (!ranged) return true;
+		if (at === 'unreleased') return until == null;
+		if (since != null && compareReleaseVersions(at, since) <= 0) return false;
+		if (until != null && compareReleaseVersions(at, until) > 0) return false;
+		return true;
+	};
+	const added = Object.entries(doc.added ?? {})
+		.filter(([at]) => inRange(at))
+		.flatMap(([at, entries]) =>
+			entries.map((entry) => ({
+				at,
+				line: typeof entry === 'string' ? entry : entry.text,
+			}))
+		);
 
 	if (jsonMode) {
 		console.log(
@@ -833,6 +849,7 @@ function changelogCommand({ since, until, json: jsonMode }) {
 					until: until ?? doc.version,
 					count: rows.length,
 					breaking: rows,
+					added: added.map(({ at, line }) => `[${at}] ${line}`),
 					guide: doc.guide,
 				},
 				null,
@@ -845,13 +862,26 @@ function changelogCommand({ since, until, json: jsonMode }) {
 	const range = ranged
 		? `${since ?? 'the start of v3'} → ${until ?? doc.version}`
 		: `the whole v2 → v3 upgrade`;
+	const printAdded = () => {
+		if (!added.length) return;
+		// Compact by default: the whole v3 line is hundreds of lines.
+		if (!ranged) {
+			console.log(
+				`\n${added.length} addition(s) over ${range}: list one hop with --since <your version>.`
+			);
+			return;
+		}
+		console.log(`\n${added.length} addition(s), ${range}:\n`);
+		for (const { at, line } of added) console.log(`  [${at}] ${line}`);
+	};
 	if (rows.length === 0) {
 		// "Nothing breaks" and "I could not tell you" must not look alike.
 		console.log(
 			`[bitboss-ui] changelog: no BREAKING changes in ${range}.\n` +
-				'            Features and fixes are deliberately not tracked here, so this\n' +
-				'            means nothing breaks — not that nothing changed.'
+				'            Fixes are not tracked here, so this means nothing\n' +
+				'            breaks — not that nothing changed.'
 		);
+		printAdded();
 		return;
 	}
 	console.log(
@@ -874,6 +904,7 @@ function changelogCommand({ since, until, json: jsonMode }) {
 		}
 		if (entry.guide) console.log(`           ${entry.guide}`);
 	}
+	printAdded();
 	console.log(`\nFull migration guide: ${doc.guide}`);
 }
 
@@ -1651,7 +1682,8 @@ Commands:
                       \`bitboss-ui/validated\`, retired: everything is in
                       \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
                       \`unregistered-rule\` (a string or object rule no
-                      \`defineRule\` in the project registers; a
+                      \`defineRule\` in the project registers (in a .md
+                      page, also one the page's own fences show); a
                       registration it cannot read is named, never skipped:
                       list such names under \`registeredRules\` in
                       bitboss-ui.check.json),
@@ -1721,8 +1753,10 @@ Commands:
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is
                       exclusive. With no range, every break in the v2 → v3
-                      upgrade. Only BREAKING changes are tracked, so an empty
-                      result means nothing breaks, not that nothing changed.
+                      upgrade. Then what the range added, one line per feature
+                      (with no range, only their count). Fixes are not tracked,
+                      so no breaking changes means nothing breaks, not that
+                      nothing changed.
                         npx bitboss-ui changelog --since 3.0.0-beta.20
                       Pair it with \`check --manifest\` to turn the list into the
                       files in YOUR app that break.

package/dist/ai/BbDialog.md

@@ -203,8 +203,9 @@ reads `data` in two places:
   `data` (typed `any`, so `data.name` reads with no cast);
 - in code, `useBbDialogContext<T>(id)` returns it typed, along with `open`,
   `show(data?)` and `hide()`. A component inside the dialog can call it too.
-  On an open dialog, `show(newData)` replaces the data and a bare `show()`
-  (or a trigger without `data`) keeps it.
+  A `show()` on an open dialog changes nothing: it joins the opening (its
+  promise, its data); the new data, trigger and `onComplete` are ignored. A
+  show during the close transition opens it again.
 
 `data` stays set until the close transition has run, so the content never
 flashes empty while the dialog fades out. The edit-record example in
@@ -241,7 +242,8 @@ The rules:
 - **An open before the dialog mounts waits for it.** A `show()`, or a
   `v-bb-dialog` click whose own handler renders the dialog through a `v-if`,
   is held until the dialog registers, so one click opens it (up to 1s; then
-  it settles `'missing'` with a dev warning, and `onComplete` never runs).
+  it settles `'missing'` with a dev warning, and `onComplete` never runs). A
+  `hide()` meanwhile cancels a held `show()`, silently: it settles `'hide'`.
   The warning suggests the nearest registered id for a typo, and says when a
   dialog with that id exists but is out of reach (inside an on-demand dialog,
   which is private, or parked by KeepAlive) or is a `BbOffCanvas`.
@@ -323,7 +325,6 @@ const replace = (saved: Member) => {
   | `'close'`                 | the ✕ or the slots' `close()`                                                                                    |
   | `'swipe'`                 | the phone sheet swiped away                                                                                      |
   | `'hide'`                  | `hide()`, or the model set to `false` (also a bound `v-model` whose parent refused the open)                     |
-  | `'replaced'`              | a newer `show()` on the open dialog took over                                                                    |
   | `'missing'`               | no dialog with that id mounted within 1s                                                                         |
   | `'unmounted'`             | the dialog unmounted (or KeepAlive parked it), or a waiting `show()`'s caller went away                          |
   | `'failed'`                | an on-demand dialog could not render                                                                             |
@@ -340,6 +341,101 @@ const replace = (saved: Member) => {
   flags the unawaited promise of a bare `edit.show(row)`, write
   `void edit.show(row)`.
 
+#### The page saves: a promise from `onComplete`
+
+When the page owns the save (it knows the endpoint, the list to update),
+`onComplete` returns the request's promise. `complete(value)` calls it first,
+and the dialog stays open and **locked** until it settles: the ✕, Cancel,
+Escape and the backdrop are refused, and a footer `BbButton` whose click
+returns `complete(value)` spins. Resolved, the dialog closes and the opening
+settles `{ completed: true, value }`; rejected, it stays open with its data
+and `complete()` rejects with the same error, so the dialog can show it.
+
+```vue
+<template>
+	<BbButton v-bb-dialog="{ id: 'rename', data: row, onComplete: save }">
+		Rename
+	</BbButton>
+	<BbDialog id="rename" v-slot="{ data, complete }" title="Rename">
+		<BbForm :model="data" @submit="() => complete(data)">
+			<BbTextInput label="Name" name="name" />
+			<BbButton type="submit">Save</BbButton>
+		</BbForm>
+	</BbDialog>
+</template>
+```
+
+From code: `edit.show(row, { onComplete: save })` (both the id and the
+component handle). A `save` function passed in `data` is no longer needed.
+A sync `onComplete` (or none) closes at once, as before.
+
+`onComplete` is just a function. A trigger inside a child component gets the
+page's save the way your app already shares things: a function prop
+(`:save="saveMember"`), a page `provide` / `inject`, or a store action. Not an
+emit: an emit cannot return the promise.
+
+To show a rejected save's field errors, keep them in a `ref` bound on the
+form, `<BbForm :field-errors="fieldErrors">` (BbForm § The page's errors
+object): the dialog stays open, and each message lands under its field until
+the user edits it.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+
+const fieldErrors = ref<Record<string, string[]>>({});
+</script>
+
+<template>
+	<BbDialog id="rename" v-slot="{ data, complete }" title="Rename">
+		<BbForm
+			:field-errors="fieldErrors"
+			:model="data"
+			@submit="
+				() =>
+					complete(data).catch((error) => {
+						// Your save's rejection: the 422 body's `errors` by field path.
+						fieldErrors = error.errors ?? {};
+					})
+			"
+		>
+			<BbTextInput label="Name" name="name" />
+			<BbButton type="submit">Save</BbButton>
+		</BbForm>
+	</BbDialog>
+</template>
+```
+
+With Inertia, the page's `useForm().errors` is that object already; the
+record-form recipe (`ai/recipes/inertia/record-form.md`) binds
+`<BbForm :field-errors="form.errors">` the same way.
+
+An Inertia visit (`router.put`, `form.put`) returns no promise and never
+rejects on its own, so `onComplete` wraps it: a validation error rejects
+with the errors (the example above reads `error.errors`), success resolves,
+and a visit cut short by another visit resolves too, closing the dialog.
+
+```ts
+import { router } from '@inertiajs/vue3';
+
+type User = { id: number; name: string };
+
+const save = (user: User) =>
+	new Promise<void>((resolve, reject) => {
+		router.put(`/users/${user.id}`, user, {
+			onSuccess: () => resolve(),
+			onError: (errors) => reject({ errors }),
+			// Cancelled or interrupted: close. Anything else that ends here
+			// unsettled (a 500, a network error) keeps the dialog open.
+			// Both are no-ops after onSuccess / onError.
+			onFinish: (visit) =>
+				visit.cancelled || visit.interrupted
+					? resolve()
+					: reject(new Error('The save failed')),
+		});
+	});
+```
+
 #### The data is a copy
 
 Every opening holds its own **reactive copy** of the `data` it was given
@@ -421,7 +517,7 @@ default.
 			</div>
 		</template>
 		<template #footer="{ data, close, complete, reset }">
-			<!-- `reset()` restores the default, on an edit too: it clears. -->
+			<!-- `reset()` clears the default's keys; an edit keeps its `id`. -->
 			<BbButton variant="ghost" @click="reset">Clear</BbButton>
 			<BbButton variant="ghost" @click="close">Cancel</BbButton>
 			<BbButton
@@ -462,9 +558,11 @@ const save = (saved: Member) => {
 </script>
 ```
 
-- **`reset()`** (the slots', or `useBbDialogContext(id).reset()`) restores a
-  fresh copy of `default-data`, on an edit too: it clears the form, it doesn't
-  go back to the row. Cancel is what discards an edit.
+- **`reset()`** (the slots', or `useBbDialogContext(id).reset()`) restores
+  the keys `default-data` declares from a fresh copy, on an edit too, and keeps
+  every key it doesn't declare: the row's `id` stays, so a cleared edit still
+  saves as an edit. It doesn't go back to the row's values; Cancel is what
+  discards an edit.
 - **Every close resets it** as well: nothing to do on `@show` or `@hidden`.
 - **An object, not a function.** The dialog copies it every time and never
   writes it, so a module constant is safe.
@@ -577,10 +675,16 @@ const createForDesign = async () => {
   KeepAlive park. A flow that changes the URL inside one dialog (a wizard
   whose steps are routes) opens it from the parent route or the persistent
   layout, which stays mounted. A `show()` from a store lives until closed.
-- **A second `show()` stacks** a second instance on top, with its own promise.
-  Give a create flow one trigger: several buttons each opening the same
-  component stack copies. Opened by id, the single mounted dialog dedupes
-  instead.
+- **From a store.** Create the handle in the setup store's body (or under
+  `app.runWithContext()`), then `show()` / `hide()` from its actions or a
+  router hook. Created in a plain module, outside any injection context,
+  `show()` settles `'failed'` with a dev warning.
+- **One handle, one dialog.** `useBbDialogContext(Component)` is the same
+  handle as the id form (`isReady`, `open`, `data`, `show`, `hide`,
+  `complete`, `reset`), about its own dialog: a `show()` while it is open
+  joins it. Another handle (another `useBbDialogContext(Component)` call, or
+  another trigger element) opens its own instance on top, with its own
+  promise. `isReady` says a `<BbHost />` is mounted to render it.
 - **Each opening gets its own DOM id**, so two stacked instances stay valid
   HTML; `aria-controls` on the trigger follows it. A template dialog keeps the
   `id` you gave it. To find one in an e2e test, use its role and title,
@@ -968,6 +1072,18 @@ const form = useBbFormContext('edit-member-form');
   field uses, `form.setErrors({ ...errors, _request: [message] })`, and shows in
   the form's `unmatchedErrors` (see BbForm § Server errors).
 
+#### Steps in one dialog
+
+- **Each step's first field gets `autofocus`**: it fires when the field
+  mounts, so focus follows the step with no watcher (`focus-target` picks only
+  where the opening starts).
+- **A final success step with no field is a status region**
+  (`role="status"`), announced as it appears, not a focus target.
+- **A footer button that changes type in place** (Next, `type="button"`,
+  becoming Accept, `type="submit"`, during its own click): give each its own
+  `key`. Unkeyed, Vue reuses the element, its type flips mid-click, and the
+  click on Next submits the form.
+
 ### Lifecycle events and lazy content
 
 Four events bracket the transitions — `show` fires as the model turns `true`,
@@ -987,11 +1103,16 @@ Every way to close, side by side:
 | Escape, Back on a URL dialog, a backdrop click, a swipe | the user     | yes: `persistent` too                 | `reason: 'escape'` / `'backdrop'` / `'swipe'` | on the key, Back, click or swipe                                                    |
 | `hide()` (context), the model set to `false`            | your code    | no                                    | `{ completed: false, reason: 'hide' }`        | at once                                                                             |
 | `complete(value)` (slots, context)                      | your code    | no                                    | `{ completed: true, value }`                  | at once                                                                             |
-| `@hide`                                                 | the dialog   | it reports a close, it can't stop one | settled together with it                      | as any close above **starts**                                                       |
+| `@hide`                                                 | the dialog   | it reports a close, it can't stop one | emits it (the same object)                    | as any close above **starts**                                                       |
 | `@hidden`                                               | the dialog   | it reports a close, it can't stop one | already settled                               | after the close transition; focus returns, `data` clears and the body unmounts then |
 
 A refused close fires nothing and settles nothing. Use `@hide` for what
-follows the decision (a toast, a refresh), `@hidden` for teardown.
+follows the decision (a toast, a refresh), `@hidden` for teardown. `@hide`
+carries the opening's result, so a live preview reverts on a dismissal with
+no flag of its own: `@hide="(r) => { if (!r.completed) restore() }"`. To
+tell a save from a cancel, close a save with `complete()` (slots or context),
+not by writing the model: on a `v-model` dialog too, it closes through the
+model and reports `{ completed: true }`.
 
 The body lives **per opening**: nothing inside the dialog renders until it
 opens, and the body unmounts after the close transition (right after
@@ -1003,7 +1124,9 @@ tests that query content before opening): `data` still clears while closed (to
 `undefined`, or the `default-data` copy), so an eager body guards its own
 reads. `transition-duration` (ms, default
 `250`) times both the open/close animation and when `hidden` fires — reopening
-during the close transition keeps the dialog open instead of snapping shut.
+during the close transition keeps the dialog open instead of snapping shut, with
+a fresh body: every new opening gets one, a reopen mid-close included (an
+`eager` body is kept).
 
 ### Size
 
@@ -1056,6 +1179,11 @@ Every dismissal path is governed by two props, and by a form inside:
   - `true`: always locked.
   - `false`: never locked, not even mid-save. Closing mid-save is then on you.
 
+  Binding it to your own flag: beside a `BbForm`, another async action (a
+  footer Delete) binds `:prevent-close="deleting || undefined"`; a plain
+  `false` while idle would switch the form's lock off. A dialog with no
+  `BbForm` binds `:prevent-close="saving"`.
+
 `persistent` keeps the ✕ (and the slots' `close`) as the deliberate exit;
 `prevent-close` removes every exit but the model.
 
@@ -1580,6 +1708,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   `href`/`to` to the button.
 - **Don't toggle `v-model` from `@hide`/`@hidden` handlers** to "cancel" a
   close — use `persistent` instead; the close paths already guard correctly.
+- **Catch `complete()` in a reusable dialog** whenever an opener may pass an
+  `onComplete` that rejects (`complete(data).catch(…)`, as in § The page
+  saves). Uncaught, the rejection travels through the form's `@submit` and
+  reaches `app.config.errorHandler`.
 - **Don't leave the `header` slot without a close control** — it replaces the
   default ×, so you must render your own wired to `close`.
 - **Don't query dialog content before it has opened, or after it has closed**,
@@ -1625,7 +1757,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `content`, `description`, `footer`, `header`, `root`, `sheet`, `title`. States: `fullscreen`, `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDialogProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, renders as a `BbOffCanvas` drawer instead of a centred dialog; the surface is chosen when the dialog opens and kept until it closes. Unset: the global `config.adaptive`. |
-| `defaultData` | `Record<string, any> \| undefined` |  |  | The `data` of an opening that passes none (a create), as an object: copied at once and exposed as `data`, so inputs bind `data.x` with no guard. An opening with data lays it over this (`{ ...defaultData, ...row }`, one level). `reset()` restores a fresh copy, and every close does too. |
+| `defaultData` | `Record<string, any> \| undefined` |  |  | The `data` of an opening that passes none (a create), as an object: copied at once and exposed as `data`, so inputs bind `data.x` with no guard. An opening with data lays it over this (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys, keeping an edit's `id`; a close restores it. |
 | `description` | `string \| undefined` |  |  | One short line under the title, muted (the shadcn `DialogDescription` shape), and the only element `aria-describedby` points at. Keep it to a sentence; anything longer belongs in the body. |
 | `eager` | `boolean \| undefined` | `false` |  | Keep the body mounted while closed, from before the first opening. Without it the body mounts per opening and unmounts after `@hidden`. `data` still clears while closed, so an eager body guards its reads. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
@@ -1636,7 +1768,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL carrying the key opens the dialog on load, and Back closes it (refused like Escape when locked). Template dialogs only; a record id stays in your own query. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on mobile), spread over its defaults. A `pt` inside it styles only the sheet (passthrough guide § Inside the sheet). |
 | `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close is still allowed. |
-| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape and the ✕, and the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always. `false`: never, not even mid-save. |
+| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape and the ✕, and the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always. `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
 | `queryKey` | `string \| undefined` | `"dialog"` |  | The query key `navigation` writes. |
 | `replace` | `boolean \| undefined` | `false` |  | With `navigation`, replaces the history entry instead of pushing one, so Back leaves the page instead of closing the dialog. |
 | `size` | `Responsive<NonNullable<number \| CssSize \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
@@ -1671,7 +1803,7 @@ States are listed in precedence order: when two are on at once and their entries
 ## Events
 
 - `hidden` — `(): void` — Emitted after the close transition completes and the dialog is fully dismissed.
-- `hide` — `(): void` — Emitted as soon as the dialog starts to close (model becomes false).
+- `hide` — `(result: BbDialogResult): void` — Emitted as soon as the dialog starts to close (model becomes false), with the opening's result: the same object its promise settles with, `{ completed: true, value }` or `{ completed: false, reason }` (Q73.6).
 - `show` — `(): void` — Emitted as soon as the dialog starts to open (model becomes true).
 - `shown` — `(): void` — Emitted once the open transition has run (symmetric with `hidden`): the dialog is settled, so code that measures or anchors to its content sees the final layout. Not emitted for a dialog closed before it finished opening.
 - `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
@@ -1679,10 +1811,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void; complete: (value?: any) => void; reset: () => void; data: any }` — Primary body content of the dialog, rendered in the scrollable body area.
+- `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; data: any }` — Primary body content of the dialog, rendered in the scrollable body area.
 - `description` — scope: `BbDialogDescriptionSlotProps` `{ text: string; data: any }` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
-- `footer` — scope: `BbDialogFooterSlotProps` `{ close: () => void; complete: (value?: any) => void; reset: () => void; data: any }` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
-- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; complete: (value?: any) => void; reset: () => void; title: string; data: any }` — Replaces the whole header (title and ✕) on both surfaces, so it owns closing: wire your control to `close`, and `titleId` onto your title. It renders even without `title`. Its root is a flex item: give it `flex-1` to fill the width.
+- `footer` — scope: `BbDialogFooterSlotProps` `{ close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; data: any }` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
+- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; title: string; data: any }` — Replaces the whole header (title and ✕) on both surfaces, so it owns closing: wire your control to `close`, and `titleId` onto your title. It renders even without `title`. Its root is a flex item: give it `flex-1` to fill the width.
 - `title` — scope: `BbDialogTitleSlotProps` `{ text: string; data: any }` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.
 
 ## CSS custom properties

package/dist/ai/BbDropdown.md

@@ -2124,8 +2124,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   width; pass a number when menus must align across rows.
 - Item `variant`s other than `destructive` render only a class hook — register
   names via the `dropdownItemVariants` plugin option and ship their CSS.
-- `<BbDropdownGroup>` must sit in a `BbDropdown` (or `BbDropdownButton`)
-  default slot, its `id` must match a group's `id`, and a `multiple` group's
+- `<BbDropdownGroup>` must sit in a `BbDropdown`'s default slot (a
+  `BbDropdownButton`'s `#dropdown`), its `id` must match a group's `id`, and a `multiple` group's
   model must be an array — all three misuses throw.
 - Placeholder texts default to the config locale's "Loading…" / "No results"
   strings (`locale` plugin option) unless you set `loading-text` /