@vc-shell/vc-app-skill 2.0.0-alpha.32 → 2.0.0-alpha.33-pr220.455e322

package/runtime/knowledge/docs/core/composables/useAsync/useAsync.docs.md

@@ -3,6 +3,7 @@
 Wraps an asynchronous function with reactive `loading` state, reactive `error` state, and automatic error notifications. This is the standard way to handle API calls, saves, deletes, and other async operations throughout VC-Shell applications.
 
 When the returned `action` is called, `useAsync` automatically:
+
 1. Sets `loading` to `true` and clears any previous `error`
 2. Executes your async function
 3. On failure: parses the error into a `DisplayableError`, stores it in `error`, logs it, optionally shows a toast notification, and re-throws
@@ -23,7 +24,11 @@ import { OrderClient } from "@api/orders";
 
 const { getApiClient } = useApiClient(OrderClient);
 
-const { loading, error, action: loadOrder } = useAsync<string>(async (id) => {
+const {
+  loading,
+  error,
+  action: loadOrder,
+} = useAsync<string>(async (id) => {
   const client = await getApiClient();
   return await client.getOrderById(id);
 });
@@ -44,41 +49,38 @@ import { useAsync } from "@vc-shell/framework";
 
 ### Parameters
 
-| Parameter     | Type                            | Required | Description                                      |
-|---------------|---------------------------------|----------|--------------------------------------------------|
-| `innerAction` | `AsyncAction<Payload, Result>`  | Yes      | The async function to wrap                       |
-| `options`     | `UseAsyncOptions`               | No       | Configuration for notifications                  |
+| Parameter     | Type                           | Required | Description                     |
+| ------------- | ------------------------------ | -------- | ------------------------------- |
+| `innerAction` | `AsyncAction<Payload, Result>` | Yes      | The async function to wrap      |
+| `options`     | `UseAsyncOptions`              | No       | Configuration for notifications |
 
 #### Type Aliases
 
 ```typescript
-type AsyncAction<Payload = void, Result = void> = (
-  payload?: Payload,
-  ...rest: any[]
-) => Promise<Result>;
+type AsyncAction<Payload = void, Result = void> = (payload?: Payload, ...rest: any[]) => Promise<Result>;
 ```
 
 #### UseAsyncOptions
 
-| Option          | Type      | Default | Description                                          |
-|-----------------|-----------|---------|------------------------------------------------------|
-| `notify`        | `boolean` | `true`  | Show an error toast notification on failure           |
+| Option          | Type      | Default | Description                                              |
+| --------------- | --------- | ------- | -------------------------------------------------------- |
+| `notify`        | `boolean` | `true`  | Show an error toast notification on failure              |
 | `notifyTimeout` | `number`  | `8000`  | Duration in milliseconds before the toast auto-dismisses |
 
 ### Returns: `UseAsyncReturn<Payload, Result>`
 
-| Property  | Type                                        | Description                                                       |
-|-----------|---------------------------------------------|-------------------------------------------------------------------|
-| `loading` | `DeepReadonly<Ref<boolean>>`                | Reactive loading state -- `true` while the action is executing    |
-| `error`   | `DeepReadonly<Ref<DisplayableError \| null>>` | Reactive error -- set on failure, cleared on next invocation      |
-| `action`  | `AsyncAction<Payload, Result>`              | Wrapped function with the same signature as `innerAction`         |
+| Property  | Type                                          | Description                                                    |
+| --------- | --------------------------------------------- | -------------------------------------------------------------- |
+| `loading` | `DeepReadonly<Ref<boolean>>`                  | Reactive loading state -- `true` while the action is executing |
+| `error`   | `DeepReadonly<Ref<DisplayableError \| null>>` | Reactive error -- set on failure, cleared on next invocation   |
+| `action`  | `AsyncAction<Payload, Result>`                | Wrapped function with the same signature as `innerAction`      |
 
 ### Type Parameters
 
-| Name      | Default | Description                                            |
-|-----------|---------|--------------------------------------------------------|
-| `Payload` | `void`  | Type of the first argument passed to `action`          |
-| `Result`  | `void`  | Return type of the async operation                     |
+| Name      | Default | Description                                   |
+| --------- | ------- | --------------------------------------------- |
+| `Payload` | `void`  | Type of the first argument passed to `action` |
+| `Result`  | `void`  | Return type of the async operation            |
 
 ---
 
@@ -117,12 +119,10 @@ await loadProduct("prod-42");
 When the inner function returns a value, it becomes the resolved value of `action`:
 
 ```typescript
-const { action: validateSeller } = useAsync<Seller, ValidationFailure[]>(
-  async (seller) => {
-    const client = await getApiClient();
-    return await client.validateSeller(seller);
-  },
-);
+const { action: validateSeller } = useAsync<Seller, ValidationFailure[]>(async (seller) => {
+  const client = await getApiClient();
+  return await client.validateSeller(seller);
+});
 
 const failures = await validateSeller(sellerData);
 // failures is typed as ValidationFailure[]
@@ -134,14 +134,25 @@ The `error` ref contains a parsed `DisplayableError` after a failure. It is auto
 
 ```vue
 <template>
-  <VcAlert v-if="error" variant="error">
+  <VcAlert
+    v-if="error"
+    variant="error"
+  >
     {{ error.message }}
   </VcAlert>
-  <VcButton :loading="loading" @click="save">Save</VcButton>
+  <VcButton
+    :loading="loading"
+    @click="save"
+    >Save</VcButton
+  >
 </template>
 
 <script setup lang="ts">
-const { loading, error, action: save } = useAsync(async () => {
+const {
+  loading,
+  error,
+  action: save,
+} = useAsync(async () => {
   await saveOrder(order.value);
 });
 </script>
@@ -153,18 +164,30 @@ By default, `useAsync` shows a toast notification on failure. The notification i
 
 ```typescript
 // Default: shows toast on error
-const { action: save } = useAsync(async () => { /* ... */ });
+const { action: save } = useAsync(async () => {
+  /* ... */
+});
 
 // Explicit: custom timeout
-const { action: save } = useAsync(async () => { /* ... */ }, {
-  notify: true,
-  notifyTimeout: 5000,
-});
+const { action: save } = useAsync(
+  async () => {
+    /* ... */
+  },
+  {
+    notify: true,
+    notifyTimeout: 5000,
+  },
+);
 
 // Silent: no toast notification
-const { action: silentRefresh } = useAsync(async () => { /* ... */ }, {
-  notify: false,
-});
+const { action: silentRefresh } = useAsync(
+  async () => {
+    /* ... */
+  },
+  {
+    notify: false,
+  },
+);
 ```
 
 ### Combining with useApiClient
@@ -190,9 +213,15 @@ const { action: search, loading } = useAsync<SearchQuery>(async (query) => {
 When a blade has multiple async operations, combine their loading states into one:
 
 ```typescript
-const { action: load, loading: loadLoading } = useAsync<string>(async (id) => { /* ... */ });
-const { action: save, loading: saveLoading } = useAsync<Product>(async (p) => { /* ... */ });
-const { action: remove, loading: deleteLoading } = useAsync<string>(async (id) => { /* ... */ });
+const { action: load, loading: loadLoading } = useAsync<string>(async (id) => {
+  /* ... */
+});
+const { action: save, loading: saveLoading } = useAsync<Product>(async (p) => {
+  /* ... */
+});
+const { action: remove, loading: deleteLoading } = useAsync<string>(async (id) => {
+  /* ... */
+});
 
 // Single reactive boolean: true if ANY operation is running
 const loading = useLoading(loadLoading, saveLoading, deleteLoading);
@@ -220,19 +249,15 @@ export function useFulfillmentCenter() {
     details.value = await client.getFulfillmentCenterById(id!);
   });
 
-  const { action: save, loading: saveLoading } = useAsync<FulfillmentCenter>(
-    async (data) => {
-      const client = await getApiClient();
-      await client.updateFulfillmentCenter({ fulfillmentCenter: data });
-    },
-  );
+  const { action: save, loading: saveLoading } = useAsync<FulfillmentCenter>(async (data) => {
+    const client = await getApiClient();
+    await client.updateFulfillmentCenter({ fulfillmentCenter: data });
+  });
 
-  const { action: remove, loading: deleteLoading } = useAsync<string>(
-    async (id) => {
-      const client = await getApiClient();
-      await client.deleteFulfillmentCenter([id!]);
-    },
-  );
+  const { action: remove, loading: deleteLoading } = useAsync<string>(async (id) => {
+    const client = await getApiClient();
+    await client.deleteFulfillmentCenter([id!]);
+  });
 
   return {
     details,
@@ -341,14 +366,18 @@ async function onSave() {
 ```typescript
 // BAD -- creates a new loading ref each call, template never sees it
 async function loadData() {
-  const { action, loading } = useAsync(async () => { /* ... */ });
+  const { action, loading } = useAsync(async () => {
+    /* ... */
+  });
   await action();
 }
 ```
 
 ```typescript
 // GOOD -- create at setup time, call the action later
-const { action: loadData, loading } = useAsync(async () => { /* ... */ });
+const { action: loadData, loading } = useAsync(async () => {
+  /* ... */
+});
 
 onMounted(() => loadData());
 ```
@@ -381,9 +410,9 @@ const { action: save, loading: saveLoading } = useAsync(async () => saveData());
 
 ## Related
 
-| Resource | Description |
-|----------|-------------|
-| [`useApiClient`](../useApiClient/) | Provides typed API client instances to pass into `useAsync` |
-| [`useLoading`](../useLoading/) | Combines multiple `loading` refs into a single boolean |
-| [`useModificationTracker`](../useModificationTracker/) | Tracks dirty state for forms -- often used alongside `useAsync` for save operations |
-| [`notification`](../../../shared/components/notifications/) | The toast notification system used by `useAsync` for error display |
+| Resource                                                    | Description                                                                         |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [`useApiClient`](../useApiClient/)                          | Provides typed API client instances to pass into `useAsync`                         |
+| [`useLoading`](../useLoading/)                              | Combines multiple `loading` refs into a single boolean                              |
+| [`useModificationTracker`](../useModificationTracker/)      | Tracks dirty state for forms -- often used alongside `useAsync` for save operations |
+| [`notification`](../../../shared/components/notifications/) | The toast notification system used by `useAsync` for error display                  |

package/runtime/knowledge/docs/core/composables/useBeforeUnload/useBeforeUnload.docs.md

@@ -12,12 +12,12 @@ Prevents the browser tab from closing when unsaved changes exist by hooking into
 
 ```vue
 <script setup lang="ts">
-import { useBeforeUnload } from '@vc-shell/framework';
-import { ref, computed } from 'vue';
+import { useBeforeUnload } from "@vc-shell/framework";
+import { ref, computed } from "vue";
 
 // Suppose your blade has a form with a "dirty" flag
-const originalName = ref('Widget A');
-const currentName = ref('Widget A');
+const originalName = ref("Widget A");
+const currentName = ref("Widget A");
 
 const isModified = computed(() => originalName.value !== currentName.value);
 
@@ -27,7 +27,10 @@ useBeforeUnload(isModified);
 
 <template>
   <VcBlade title="Edit Widget">
-    <VcInput v-model="currentName" label="Name" />
+    <VcInput
+      v-model="currentName"
+      label="Name"
+    />
     <VcButton @click="save">Save</VcButton>
   </VcBlade>
 </template>
@@ -37,14 +40,14 @@ useBeforeUnload(isModified);
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `modified` | `ComputedRef<boolean>` | Yes | When `true`, the browser shows a leave-confirmation dialog on tab close or refresh |
+| Parameter  | Type                   | Required | Description                                                                        |
+| ---------- | ---------------------- | -------- | ---------------------------------------------------------------------------------- |
+| `modified` | `ComputedRef<boolean>` | Yes      | When `true`, the browser shows a leave-confirmation dialog on tab close or refresh |
 
 ### Returns
 
-| Property | Type | Description |
-|---|---|---|
+| Property   | Type                   | Description                                                             |
+| ---------- | ---------------------- | ----------------------------------------------------------------------- |
 | `modified` | `ComputedRef<boolean>` | Pass-through of the input ref, useful for chaining or template bindings |
 
 ## How It Works
@@ -57,13 +60,13 @@ Because the listener is added in `onBeforeMount` (not `setup`), it avoids attach
 
 ```vue
 <script setup lang="ts">
-import { useBeforeUnload } from '@vc-shell/framework';
-import { ref, computed, watch } from 'vue';
+import { useBeforeUnload } from "@vc-shell/framework";
+import { ref, computed, watch } from "vue";
 
 const props = defineProps<{ productId: string }>();
 
-const product = ref({ name: '', price: 0 });
-const snapshot = ref({ name: '', price: 0 });
+const product = ref({ name: "", price: 0 });
+const snapshot = ref({ name: "", price: 0 });
 
 // Load data and take a snapshot of the original state
 async function load() {
@@ -73,9 +76,7 @@ async function load() {
 }
 
 // Deep-compare current vs. snapshot
-const isModified = computed(() =>
-  JSON.stringify(product.value) !== JSON.stringify(snapshot.value),
-);
+const isModified = computed(() => JSON.stringify(product.value) !== JSON.stringify(snapshot.value));
 
 // Guard the browser tab
 useBeforeUnload(isModified);
@@ -84,7 +85,7 @@ useBeforeUnload(isModified);
 defineExpose({
   onBeforeClose: () => {
     if (isModified.value) {
-      return confirm('You have unsaved changes. Discard?');
+      return confirm("You have unsaved changes. Discard?");
     }
     return true;
   },

package/runtime/knowledge/docs/core/composables/useBlade/useBlade.docs.md

@@ -44,7 +44,9 @@ openBlade({ name: "OrderDetails", param: "order-123" });
 import { useBlade } from "@vc-shell/framework";
 
 // Typed options — no manual casting needed
-interface BladeOptions { sellerProduct?: SellerProduct }
+interface BladeOptions {
+  sellerProduct?: SellerProduct;
+}
 const { param, options, callParent } = useBlade<BladeOptions>();
 
 console.log(options.value?.sellerProduct); // typed as SellerProduct | undefined
@@ -70,7 +72,10 @@ const blade = useBlade();
 `useBlade<TOptions>()` accepts an optional generic to type the `options` computed ref:
 
 ```typescript
-interface MyOptions { productId: string; mode: "edit" | "create" }
+interface MyOptions {
+  productId: string;
+  mode: "edit" | "create";
+}
 const { options } = useBlade<MyOptions>();
 // options.value is MyOptions | undefined — no manual casting needed
 ```
@@ -83,68 +88,68 @@ Without the generic, `options.value` defaults to `Record<string, unknown> | unde
 
 These are reactive `ComputedRef` values that reflect the current blade's state. Accessing them outside blade context throws a runtime error.
 
-| Property   | Type                                                  | Description                                             |
-|------------|-------------------------------------------------------|---------------------------------------------------------|
-| `id`       | `ComputedRef<string>`                                 | The current blade's unique ID within the blade stack    |
-| `param`    | `ComputedRef<string \| undefined>`                    | Route parameter passed when the blade was opened        |
-| `options`  | `ComputedRef<TOptions \| undefined>`                  | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()` |
-| `query`    | `ComputedRef<Record<string, string> \| undefined>`    | URL query parameters scoped to this blade               |
-| `closable` | `ComputedRef<boolean>`                                | `true` when this blade has a parent (i.e., can be closed) |
-| `expanded` | `ComputedRef<boolean>`                                | `true` when this blade is the active (rightmost) blade  |
-| `name`     | `ComputedRef<string>`                                 | The blade's registered component name                   |
+| Property   | Type                                               | Description                                                                                                                                                |
+| ---------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`       | `ComputedRef<string>`                              | The current blade's unique ID within the blade stack                                                                                                       |
+| `param`    | `ComputedRef<string \| undefined>`                 | Route parameter passed when the blade was opened                                                                                                           |
+| `options`  | `ComputedRef<TOptions \| undefined>`               | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()` |
+| `query`    | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade                                                                                                                  |
+| `closable` | `ComputedRef<boolean>`                             | `true` when this blade has a parent (i.e., can be closed)                                                                                                  |
+| `expanded` | `ComputedRef<boolean>`                             | `true` when this blade is the active (rightmost) blade                                                                                                     |
+| `name`     | `ComputedRef<string>`                              | The blade's registered component name                                                                                                                      |
 
 #### Navigation Methods (work everywhere)
 
-| Method      | Signature                                                        | Description                                            |
-|-------------|------------------------------------------------------------------|--------------------------------------------------------|
+| Method      | Signature                                                              | Description                                                                                 |
+| ----------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `openBlade` | `(event: BladeOpenEvent & { isWorkspace?: boolean }) => Promise<void>` | Open a blade as a child of the current blade, or as a workspace root if `isWorkspace: true` |
 
 #### Action Methods (blade context required)
 
-| Method          | Signature                               | Description                                        |
-|-----------------|-----------------------------------------|----------------------------------------------------|
-| `closeSelf`     | `() => Promise<boolean>`                | Close the current blade. Returns `true` if a guard prevented closure. Respects `onBeforeClose` guards. |
-| `closeChildren` | `() => Promise<void>`                   | Close all child blades of the current blade        |
-| `replaceWith`   | `(event: BladeOpenEvent) => Promise<void>` | Replace the current blade with a different one in the same position (destroys the old blade) |
+| Method          | Signature                                  | Description                                                                                                    |
+| --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `closeSelf`     | `() => Promise<boolean>`                   | Close the current blade. Returns `true` if a guard prevented closure. Respects `onBeforeClose` guards.         |
+| `closeChildren` | `() => Promise<void>`                      | Close all child blades of the current blade                                                                    |
+| `replaceWith`   | `(event: BladeOpenEvent) => Promise<void>` | Replace the current blade with a different one in the same position (destroys the old blade)                   |
 | `coverWith`     | `(event: BladeOpenEvent) => Promise<void>` | Cover the current blade — hides it and opens a new blade on top. Closing the new blade reveals the hidden one. |
 
 #### Communication Methods (blade context required)
 
-| Method              | Signature                                                      | Description                                                    |
-|---------------------|----------------------------------------------------------------|----------------------------------------------------------------|
-| `callParent`        | `<T = unknown>(method: string, args?: unknown) => Promise<T>`  | Invoke a method exposed by the parent blade                    |
-| `exposeToChildren`  | `(methods: Record<string, (...args: unknown[]) => unknown>) => void` | Expose methods that child blades can call via `callParent` |
+| Method             | Signature                                                            | Description                                                |
+| ------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `callParent`       | `<T = unknown>(method: string, args?: unknown) => Promise<T>`        | Invoke a method exposed by the parent blade                |
+| `exposeToChildren` | `(methods: Record<string, (...args: unknown[]) => unknown>) => void` | Expose methods that child blades can call via `callParent` |
 
 #### Guards and Errors (blade context required)
 
-| Method          | Signature                                    | Description                                         |
-|-----------------|----------------------------------------------|-----------------------------------------------------|
-| `onBeforeClose` | `(guard: () => Promise<boolean>) => void`    | Register a guard that can prevent blade closure      |
-| `setError`      | `(error: unknown) => void`                   | Display an error banner on the blade                 |
-| `clearError`    | `() => void`                                 | Clear the blade error banner                         |
+| Method          | Signature                                 | Description                                     |
+| --------------- | ----------------------------------------- | ----------------------------------------------- |
+| `onBeforeClose` | `(guard: () => Promise<boolean>) => void` | Register a guard that can prevent blade closure |
+| `setError`      | `(error: unknown) => void`                | Display an error banner on the blade            |
+| `clearError`    | `() => void`                              | Clear the blade error banner                    |
 
 #### Banner Management (blade context required)
 
-| Method         | Signature                                                    | Description                                                    |
-|----------------|--------------------------------------------------------------|----------------------------------------------------------------|
-| `addBanner`    | `(options: Omit<IBladeBanner, "id" \| "_system">) => string` | Add a custom banner to the blade. Returns the banner's unique ID. |
-| `removeBanner` | `(id: string) => void`                                       | Remove a specific banner by its ID                             |
+| Method         | Signature                                                    | Description                                                             |
+| -------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `addBanner`    | `(options: Omit<IBladeBanner, "id" \| "_system">) => string` | Add a custom banner to the blade. Returns the banner's unique ID.       |
+| `removeBanner` | `(id: string) => void`                                       | Remove a specific banner by its ID                                      |
 | `clearBanners` | `() => void`                                                 | Remove all custom banners (system error/modified banners are preserved) |
 
 #### Lifecycle Hooks (blade context required)
 
-| Method          | Signature                         | Description                                              |
-|-----------------|-----------------------------------|----------------------------------------------------------|
-| `onActivated`   | `(callback: () => void) => void`  | Register a callback fired when this blade becomes the active (rightmost) blade. Only fires on transitions, not on initial mount. |
-| `onDeactivated` | `(callback: () => void) => void`  | Register a callback fired when this blade loses active status (another blade opens on top). |
+| Method          | Signature                        | Description                                                                                                                      |
+| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `onActivated`   | `(callback: () => void) => void` | Register a callback fired when this blade becomes the active (rightmost) blade. Only fires on transitions, not on initial mount. |
+| `onDeactivated` | `(callback: () => void) => void` | Register a callback fired when this blade loses active status (another blade opens on top).                                      |
 
 > **Note:** Each hook can only be registered once per `useBlade()` call. A second registration logs a warning and is ignored. Use `onMounted` for initial-mount logic — `onActivated` only fires on subsequent activations.
 
 #### Deprecated
 
-| Method             | Signature                                               | Description                         |
-|--------------------|---------------------------------------------------------|-------------------------------------|
-| `provideBladeData` | `(data: MaybeRef<Record<string, unknown>>) => void`     | **Deprecated.** Use `defineBladeContext()` instead. |
+| Method             | Signature                                           | Description                                         |
+| ------------------ | --------------------------------------------------- | --------------------------------------------------- |
+| `provideBladeData` | `(data: MaybeRef<Record<string, unknown>>) => void` | **Deprecated.** Use `defineBladeContext()` instead. |
 
 ### BladeOpenEvent
 
@@ -186,8 +191,12 @@ openBlade({
   name: "FulfillmentCenterDetails",
   param: centerId,
   options: { mode: "edit" },
-  onOpen() { selectedItemId.value = centerId; },
-  onClose() { selectedItemId.value = undefined; },
+  onOpen() {
+    selectedItemId.value = centerId;
+  },
+  onClose() {
+    selectedItemId.value = undefined;
+  },
 });
 
 // Open as workspace (replaces entire blade stack)
@@ -317,6 +326,7 @@ async function onSave() {
 ```
 
 > **Tip:** `callParent` is generic. If the parent method returns a value, you can type it:
+>
 > ```typescript
 > const count = await callParent<number>("getOffersCount");
 > ```
@@ -419,11 +429,7 @@ addBanner({
 // Banner with custom render function
 addBanner({
   variant: "info",
-  render: () => h("span", [
-    "Data synced from ",
-    h("b", "Warehouse A"),
-    " at 14:32",
-  ]),
+  render: () => h("span", ["Data synced from ", h("b", "Warehouse A"), " at 14:32"]),
 });
 
 // Remove a specific banner
@@ -438,14 +444,14 @@ clearBanners();
 
 The options object passed to `addBanner`:
 
-| Property      | Type                              | Default  | Description                                        |
-|---------------|-----------------------------------|----------|----------------------------------------------------|
-| `variant`     | `"danger" \| "warning" \| "info" \| "success"` | required | Color scheme and default icon              |
-| `message`     | `string`                          | --       | Plain text message                                 |
-| `render`      | `() => VNode`                     | --       | Custom render function (takes priority over message) |
-| `dismissible` | `boolean`                         | `false`  | Show a close button to dismiss the banner          |
-| `icon`        | `string`                          | --       | Override the default variant icon (lucide icon name) |
-| `action`      | `{ label: string; handler: () => void }` | --  | Action button displayed on the right side          |
+| Property      | Type                                           | Default  | Description                                          |
+| ------------- | ---------------------------------------------- | -------- | ---------------------------------------------------- |
+| `variant`     | `"danger" \| "warning" \| "info" \| "success"` | required | Color scheme and default icon                        |
+| `message`     | `string`                                       | --       | Plain text message                                   |
+| `render`      | `() => VNode`                                  | --       | Custom render function (takes priority over message) |
+| `dismissible` | `boolean`                                      | `false`  | Show a close button to dismiss the banner            |
+| `icon`        | `string`                                       | --       | Override the default variant icon (lucide icon name) |
+| `action`      | `{ label: string; handler: () => void }`       | --       | Action button displayed on the right side            |
 
 > **Note:** `addBanner` returns a unique string ID. Use it with `removeBanner(id)` to programmatically remove a specific banner. `clearBanners()` removes all custom banners but preserves system banners (error and unsaved changes).
 
@@ -489,6 +495,7 @@ const isLoading = computed(() => ctx.value.loading as boolean);
 ```
 
 > **When to use which:**
+>
 > - `defineBladeContext` / `injectBladeContext` -- for sharing data with **child widgets and nested components** within the same blade's component tree (via provide/inject).
 > - `callParent` / `exposeToChildren` -- for **cross-blade communication** between parent and child blades in the blade stack.
 
@@ -514,8 +521,12 @@ function onRowClick(event: { data: { id?: string } }) {
   openBlade({
     name: "ProductDetails",
     param: event.data.id,
-    onOpen() { selectedItemId.value = event.data.id; },
-    onClose() { selectedItemId.value = undefined; },
+    onOpen() {
+      selectedItemId.value = event.data.id;
+    },
+    onClose() {
+      selectedItemId.value = undefined;
+    },
   });
 }
 
@@ -577,7 +588,9 @@ const item = ref<Order>();
 
 defineBladeContext({ item }); // share with widgets
 
-async function reload() { await loadOrder(props.param!); }
+async function reload() {
+  await loadOrder(props.param!);
+}
 exposeToChildren({ reload }); // child ShipmentDetails can callParent("reload")
 
 function openShipment(id: string) {
@@ -651,7 +664,9 @@ openBlade({ name: "OrderDetails", param: orderId });
 ```vue
 <!-- BAD -- child calls callParent("reload") but parent never exposed it -->
 <script setup lang="ts">
-async function reload() { /* ... */ }
+async function reload() {
+  /* ... */
+}
 // Missing: exposeToChildren({ reload })
 // or: defineExpose({ reload })
 </script>
@@ -660,7 +675,9 @@ async function reload() { /* ... */ }
 ```vue
 <!-- GOOD -- explicitly expose methods for children -->
 <script setup lang="ts">
-async function reload() { /* ... */ }
+async function reload() {
+  /* ... */
+}
 exposeToChildren({ reload });
 // Also expose title for breadcrumbs
 defineExpose({ reload, title });
@@ -709,12 +726,16 @@ defineBladeContext({ item, loading });
 
 ```typescript
 // BAD -- accesses the ComputedRef object, not the value
-if (param) { /* always truthy -- it's a ComputedRef object */ }
+if (param) {
+  /* always truthy -- it's a ComputedRef object */
+}
 ```
 
 ```typescript
 // GOOD -- access the reactive value
-if (param.value) { /* correct -- checks the actual string */ }
+if (param.value) {
+  /* correct -- checks the actual string */
+}
 ```
 
 ---
@@ -730,11 +751,11 @@ if (param.value) { /* correct -- checks the actual string */ }
 
 ## Related
 
-| Resource | Description |
-|----------|-------------|
-| [`defineBladeContext` / `injectBladeContext`](../useBladeContext.docs.md) | Share reactive blade data with descendant widgets |
-| [`useBladeRegistry`](../useBladeRegistry/) | Look up registered blade components by name |
-| [`VcBlade`](../../../ui/components/organisms/vc-blade/) | The blade UI shell component (header, toolbar, content area) |
-| [`VcBladeNavigation`](../../../shared/components/blade-navigation/) | The container component that renders the blade stack |
-| [`useToolbar`](../../../shared/composables/useToolbar/) | Dynamic toolbar management for blades |
-| [`usePopup`](../../../shared/composables/usePopup/) | Confirmation dialogs, commonly used in close guards |
+| Resource                                                                  | Description                                                  |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [`defineBladeContext` / `injectBladeContext`](../useBladeContext.docs.md) | Share reactive blade data with descendant widgets            |
+| [`useBladeRegistry`](../useBladeRegistry/)                                | Look up registered blade components by name                  |
+| [`VcBlade`](../../../ui/components/organisms/vc-blade/)                   | The blade UI shell component (header, toolbar, content area) |
+| [`VcBladeNavigation`](../../../shared/components/blade-navigation/)       | The container component that renders the blade stack         |
+| [`useToolbar`](../../../shared/composables/useToolbar/)                   | Dynamic toolbar management for blades                        |
+| [`usePopup`](../../../shared/composables/usePopup/)                       | Confirmation dialogs, commonly used in close guards          |