@vc-shell/vc-app-skill 2.1.0-pr255.4dc5c0d → 2.1.0-pr256.0fe3abb

package/runtime/knowledge/docs/ui/components/molecules/vc-switch/vc-switch.docs.md

@@ -240,20 +240,21 @@ const isActive = ref(true);
 
 ## Props
 
-| Prop           | Type                   | Default | Description                                          |
-| -------------- | ---------------------- | ------- | ---------------------------------------------------- |
-| `modelValue`   | `boolean \| undefined` | --      | Bound value via `v-model`                            |
-| `label`        | `string`               | --      | Label text above the switch                          |
-| `hint`         | `string`               | --      | Helper text displayed below the switch               |
-| `labelTooltip` | `string`               | --      | Tooltip shown on the label info icon                 |
-| `tooltip`      | `string`               | --      | **Deprecated.** Use `hint` or `labelTooltip` instead |
-| `trueValue`    | `boolean`              | `true`  | Value that represents the checked state              |
-| `falseValue`   | `boolean`              | `false` | Value that represents the unchecked state            |
-| `disabled`     | `boolean`              | `false` | Disables the switch                                  |
-| `required`     | `boolean`              | `false` | Shows a required indicator on the label              |
-| `error`        | `boolean`              | `false` | Enables error styling                                |
-| `errorMessage` | `string`               | --      | Error message displayed below the switch             |
-| `name`         | `string`               | --      | HTML name attribute for the hidden input             |
+| Prop           | Type                   | Default | Description                                                                                        |
+| -------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `modelValue`   | `boolean \| undefined` | --      | Bound value via `v-model`                                                                          |
+| `label`        | `string`               | --      | Label text above the switch                                                                        |
+| `hint`         | `string`               | --      | Helper text displayed below the switch                                                             |
+| `labelTooltip` | `string`               | --      | Tooltip shown on the label info icon                                                               |
+| `tooltip`      | `string`               | --      | **Deprecated.** Use `hint` or `labelTooltip` instead                                               |
+| `trueValue`    | `boolean`              | `true`  | Value that represents the checked state                                                            |
+| `falseValue`   | `boolean`              | `false` | Value that represents the unchecked state                                                          |
+| `disabled`     | `boolean`              | `false` | Disables the switch                                                                                |
+| `required`     | `boolean`              | `false` | Shows a required indicator on the label                                                            |
+| `error`        | `boolean`              | `false` | Enables error styling                                                                              |
+| `errorMessage` | `string`               | --      | Error message displayed below the switch                                                           |
+| `ariaLabel`    | `string`               | --      | Accessible name for the switch when no visible `label` is set. Applied only when `label` is empty. |
+| `name`         | `string`               | --      | Field name used for validation/id generation (not rendered as an HTML name attribute on the input) |
 
 ## Events
 

package/runtime/knowledge/docs/ui/components/molecules/vc-textarea/vc-textarea.docs.md

@@ -236,21 +236,21 @@ const description = ref<string>("");
 
 ## Props
 
-| Prop              | Type      | Default     | Description                                     |
-| ----------------- | --------- | ----------- | ----------------------------------------------- |
-| `modelValue`      | `string`  | `undefined` | Bound value via `v-model`                       |
-| `label`           | `string`  | --          | Label text displayed above the textarea         |
-| `placeholder`     | `string`  | --          | Placeholder text inside the empty textarea      |
-| `hint`            | `string`  | --          | Helper text displayed below the field           |
-| `tooltip`         | `string`  | --          | Tooltip on the label info icon                  |
-| `maxlength`       | `string`  | `"1024"`    | Maximum character count (native HTML attribute) |
-| `required`        | `boolean` | `false`     | Shows a required indicator on the label         |
-| `error`           | `boolean` | `false`     | Enables error styling (red border + ring)       |
-| `errorMessage`    | `string`  | --          | Error message text below the field              |
-| `disabled`        | `boolean` | `false`     | Disables the textarea                           |
-| `name`            | `string`  | `"Field"`   | HTML name attribute                             |
-| `multilanguage`   | `boolean` | `false`     | Shows language badge on the label               |
-| `currentLanguage` | `string`  | --          | Language code displayed in the badge            |
+| Prop              | Type      | Default     | Description                                                                                          |
+| ----------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `modelValue`      | `string`  | `undefined` | Bound value via `v-model`                                                                            |
+| `label`           | `string`  | --          | Label text displayed above the textarea                                                              |
+| `placeholder`     | `string`  | --          | Placeholder text inside the empty textarea                                                           |
+| `hint`            | `string`  | --          | Helper text displayed below the field                                                                |
+| `tooltip`         | `string`  | --          | Tooltip on the label info icon                                                                       |
+| `maxlength`       | `string`  | `"1024"`    | Maximum character count (native HTML attribute)                                                      |
+| `required`        | `boolean` | `false`     | Shows a required indicator on the label                                                              |
+| `error`           | `boolean` | `false`     | Enables error styling (red border + ring)                                                            |
+| `errorMessage`    | `string`  | --          | Error message text below the field                                                                   |
+| `disabled`        | `boolean` | `false`     | Disables the textarea                                                                                |
+| `name`            | `string`  | `"Field"`   | Field name used for validation/id generation (not applied as an HTML name attribute on the textarea) |
+| `multilanguage`   | `boolean` | `false`     | Shows language badge on the label                                                                    |
+| `currentLanguage` | `string`  | --          | Language code displayed in the badge                                                                 |
 
 ## Events
 

package/runtime/knowledge/docs/ui/components/molecules/vc-toast/vc-toast.docs.md

@@ -148,7 +148,7 @@ Toasts use Sonner-style stacking: the newest toast is in front, older toasts sca
 
 On touch devices, horizontal swipe dismisses toasts (threshold: 45px or velocity > 0.11px/ms).
 
-The auto-dismiss timer (default 5000ms) pauses on hover. Set `timeout: false` for persistent toasts.
+The auto-dismiss timer (default 3000ms) pauses on hover. Set `timeout: false` for persistent toasts.
 
 ```ts
 notification("Quick flash", { timeout: 1500 });
@@ -246,11 +246,11 @@ These props are used internally by the notification system. You rarely need to s
 
 | Prop             | Type                                             | Default        | Description                                            |
 | ---------------- | ------------------------------------------------ | -------------- | ------------------------------------------------------ |
-| `content`        | `string \| Component`                            | --             | Notification message or custom component               |
+| `content`        | `string \| VNode \| Component`                   | --             | Notification message or custom component               |
 | `notificationId` | `number \| string`                               | --             | Unique identifier                                      |
 | `updateId`       | `number \| string`                               | --             | ID for update tracking                                 |
 | `type`           | `"default" \| "success" \| "error" \| "warning"` | `"default"`    | Notification type (determines icon and accent color)   |
-| `timeout`        | `number \| boolean`                              | `5000`         | Auto-dismiss delay in ms, or `false` to disable        |
+| `timeout`        | `number \| boolean`                              | `3000`         | Auto-dismiss delay in ms, or `false` to disable        |
 | `pauseOnHover`   | `boolean`                                        | `true`         | Pause timeout while mouse hovers over the toast        |
 | `limit`          | `number`                                         | --             | Maximum number of visible notifications                |
 | `position`       | `NotificationPosition`                           | `"top-center"` | Screen position for the toast                          |
@@ -269,16 +269,18 @@ These props are used internally by the notification system. You rarely need to s
 
 ## Notification Service Methods
 
-| Method                       | Signature                                                                           | Description                     |
-| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------- |
-| `notification()`             | `(message: string \| Component, options?: NotificationOptions) => string \| number` | Show a default notification     |
-| `notification.success()`     | `(message: string \| Component) => string \| number`                                | Show a success notification     |
-| `notification.error()`       | `(message: string \| Component) => string \| number`                                | Show an error notification      |
-| `notification.warning()`     | `(message: string \| Component) => string \| number`                                | Show a warning notification     |
-| `notification.update()`      | `(id, options: Partial<NotificationOptions>) => void`                               | Update an existing notification |
-| `notification.remove()`      | `(id: string \| number) => void`                                                    | Remove a specific notification  |
-| `notification.clearAll()`    | `() => void`                                                                        | Remove all notifications        |
-| `notification.setPosition()` | `(position: NotificationPosition) => void`                                          | Change the global position      |
+| Method                         | Signature                                                                                    | Description                                                                              |
+| ------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `notification()`               | `(message: string \| VNode \| Component, options?: NotificationOptions) => string \| number` | Show a default notification                                                              |
+| `notification.success()`       | `(message: string \| VNode \| Component, options?: NotificationOptions) => string \| number` | Show a success notification                                                              |
+| `notification.error()`         | `(message: string \| VNode \| Component, options?: NotificationOptions) => string \| number` | Show an error notification                                                               |
+| `notification.warning()`       | `(message: string \| VNode \| Component, options?: NotificationOptions) => string \| number` | Show a warning notification                                                              |
+| `notification.update()`        | `(id: string \| number, options: NotificationOptions) => string \| number`                   | Update an existing notification; returns the id                                          |
+| `notification.remove()`        | `(id?: string \| number) => void`                                                            | Remove a specific notification; omitting the id removes all (equivalent to `clearAll()`) |
+| `notification.clearAll()`      | `() => void`                                                                                 | Remove all notifications                                                                 |
+| `notification.clearPosition()` | `(position: NotificationPosition) => void`                                                   | Remove all notifications in one position                                                 |
+| `notification.setPosition()`   | `(position: NotificationPosition) => void`                                                   | Change the global position                                                               |
+| `notification.debug()`         | `() => { active; defaultOptions }`                                                           | Diagnostics helper: logs active toasts and default options, returns them                 |
 
 ## CSS Variables
 

package/runtime/knowledge/docs/ui/components/organisms/vc-app/vc-app.docs.md

@@ -89,6 +89,10 @@ VcApp orchestrates several internal systems:
 
 On desktop viewports, VcApp renders a collapsible sidebar on the left with navigation menu items, user info in the footer, and the blade workspace on the right. On mobile viewports, the sidebar is replaced by a top bar with a hamburger menu that opens a slide-over navigation panel.
 
+### Environment Indicator
+
+VcApp renders a `VcEnvironmentBanner` when an environment name is detected via `useEnvironmentName()` (derived from the current hostname) and the environment is not ignored. The banner surfaces the environment name and color, making it obvious when you are working against a non-production instance.
+
 ### Sidebar Menu Search
 
 ::storybook id="layout-vcapp--with-sidebar-search" height="500"
@@ -140,7 +144,7 @@ If you use the `menu` slot to provide a custom menu, the `searchQuery` prop is p
 
 ### Dynamic Module Registration
 
-Modules registered via `useDynamicModules()` are loaded at runtime. Each module can contribute menu items, blades, toolbar actions, settings pages, and dashboard widgets. VcApp handles module loading errors gracefully by displaying notification toasts.
+Modules are provided/consumed via the `DynamicModulesKey` injection (see `injection-keys.ts` and `useShellBootstrap`) and loaded at runtime. Each module can contribute menu items, blades, toolbar actions, settings pages, and dashboard widgets. VcApp handles module loading errors gracefully by displaying notification toasts.
 
 ### App Hub
 

package/runtime/knowledge/docs/ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md

@@ -77,6 +77,24 @@ The card is centered both vertically and horizontally. On narrow viewports, it s
 
 The layout uses a `<main>` element as the page landmark and an `<h2>` for the card title, providing a correct heading hierarchy for screen readers and SEO.
 
+### App Version Footer
+
+When the active route sets `meta.appVersion`, VcAuthLayout renders that string below the card (in a `.vc-auth-layout__version` element). Set it via your Vue Router route meta; when absent, nothing is rendered.
+
+## CSS Custom Properties
+
+| Variable                       | Default                                                         | Description                    |
+| ------------------------------ | --------------------------------------------------------------- | ------------------------------ |
+| `--auth-layout-bg`             | `var(--neutrals-100)`                                           | Page background                |
+| `--auth-layout-card-bg`        | `var(--additional-50)`                                          | Card background                |
+| `--auth-layout-card-border`    | `var(--neutrals-200)`                                           | Card border color              |
+| `--auth-layout-card-shadow`    | `0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)` | Card shadow                    |
+| `--auth-layout-card-radius`    | `12px`                                                          | Card corner radius             |
+| `--auth-layout-card-max-width` | `420px`                                                         | Card / footer max width        |
+| `--auth-layout-title-color`    | `var(--neutrals-900)`                                           | Title text color               |
+| `--auth-layout-subtitle-color` | `var(--neutrals-400)`                                           | Subtitle and footer text color |
+| `--auth-layout-version-color`  | `var(--neutrals-400)`                                           | Version string text color      |
+
 ## Recipe: Sign-In Page with SSO
 
 ```vue

package/runtime/knowledge/docs/ui/components/organisms/vc-blade/vc-blade.docs.md

@@ -53,7 +53,6 @@ Use VcBlade for every screen in a vc-shell application -- it is the standard con
   <VcBlade
     title="My First Blade"
     icon="lucide-box"
-    @close="$emit('close:blade')"
   >
     <div class="tw-p-4">Hello from a blade!</div>
   </VcBlade>
@@ -64,6 +63,9 @@ defineBlade({ name: "MyFirstBlade", url: "/my-first-blade" });
 </script>
 ```
 
+!!! tip "No close/expand wiring needed"
+Inside the navigation stack VcBlade closes itself and reads its expanded/closable state from the stack automatically. You don't declare `expanded`/`closable` props or forward `@close`/`@expand`/`@collapse` events — that wiring is a legacy fallback kept only for standalone (Storybook) use.
+
 !!! tip "Every blade needs a name"
 Every blade must define a `name` in `defineBlade`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
 
@@ -101,14 +103,9 @@ A blade has four visual zones, rendered top-to-bottom:
     :title="title"
     icon="lucide-tag"
     width="50%"
-    :expanded="expanded"
-    :closable="closable"
     :toolbar-items="toolbar"
     :modified="hasChanges"
     :loading="isLoading"
-    @close="$emit('close:blade')"
-    @expand="$emit('expand:blade')"
-    @collapse="$emit('collapse:blade')"
   >
     <!-- Your content here -->
   </VcBlade>
@@ -125,29 +122,13 @@ defineBlade({
   routable: false, // Optional: exclude from direct URL access
 });
 
-// Standard props injected by the navigation system
-export interface Props {
-  expanded: boolean;
-  closable: boolean;
-  param?: string; // Entity ID
-  options?: { sellerProduct?: object };
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  expanded: true,
-  closable: true,
-});
-
-export interface Emits {
-  (event: "close:blade"): void;
-  (event: "expand:blade"): void;
-  (event: "collapse:blade"): void;
-}
-const emit = defineEmits<Emits>();
-
-const { openBlade, closeSelf, callParent, onBeforeClose } = useBlade();
+// Navigation state and data come from useBlade() — not props.
+// `param` (entity id) and `options` (rich context) are reactive refs.
+const { openBlade, closeSelf, callParent, onBeforeClose, param, options } = useBlade<{
+  sellerProduct?: object;
+}>();
 
-const title = computed(() => (props.param ? "Edit Offer" : "New Offer"));
+const title = computed(() => (param.value ? "Edit Offer" : "New Offer"));
 const isLoading = ref(false);
 const hasChanges = ref(false);
 
@@ -166,15 +147,18 @@ defineExpose({ title });
 </script>
 ```
 
+!!! warning "Legacy pattern: `expanded` / `closable` props and `close:blade` emits"
+Older blades declared `defineProps<{ expanded; closable; param }>()`, wired `withDefaults`, and re-emitted `close:blade` / `expand:blade` / `collapse:blade`. This is no longer needed. The navigation stack owns expanded/closable state (a workspace root is not closable, the rightmost blade is expanded), and VcBlade closes itself. Read `param`, `options`, `query`, `expanded`, and `closable` from `useBlade()` instead — see [useBlade docs](../../../../core/composables/useBlade/useBlade.docs.md).
+
 ### defineOptions Reference
 
-| Property      | Type      | Description                                                             |
-| ------------- | --------- | ----------------------------------------------------------------------- |
-| `name`        | `string`  | **Required.** Unique blade identifier for `openBlade({ name: "..." })`. |
-| `url`         | `string`  | URL path segment (e.g., `"/offers"` produces `/#/.../offers`).          |
-| `isWorkspace` | `boolean` | Marks blade as a workspace (root-level, not closable).                  |
-| `routable`    | `boolean` | When `false`, blade cannot be opened via direct URL navigation.         |
-| `menuItem`    | `object`  | Registers a sidebar menu entry: `{ id, title, icon, priority }`.        |
+| Property      | Type      | Description                                                                                                        |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `name`        | `string`  | **Required.** Unique blade identifier for `openBlade({ name: "..." })`.                                            |
+| `url`         | `string`  | URL path segment (e.g., `"/offers"` produces `/#/.../offers`).                                                     |
+| `isWorkspace` | `boolean` | Marks blade as a workspace (root-level, not closable).                                                             |
+| `routable`    | `boolean` | When `false`, blade cannot be opened via direct URL navigation.                                                    |
+| `menuItem`    | `object`  | Registers a sidebar menu entry: `{ title, icon, priority }` (plus optional `groupConfig`, `permissions`, `badge`). |
 
 ### defineExpose
 
@@ -310,10 +294,13 @@ const entityId = computed(() => ctx.value.item?.id);
 
 ### Expanded / Collapsed
 
-`expanded` indicates whether this blade is the active (rightmost) one. The navigation system manages it -- just pass through:
+`expanded` indicates whether this blade is the active (rightmost) one. The navigation system manages it entirely -- **don't** declare an `expanded` prop or forward `@expand`/`@collapse`. If you need the current value, read it reactively from `useBlade()`:
 
-```vue
-<VcBlade :expanded="expanded" @expand="$emit('expand:blade')" @collapse="$emit('collapse:blade')">
+```ts
+const { expanded } = useBlade();
+
+// e.g. show a compact layout when this blade is collapsed behind others
+const layout = computed(() => (expanded.value ? "full" : "compact"));
 ```
 
 ### Closing
@@ -372,10 +359,11 @@ interface IBladeToolbar {
   id?: string;
   title?: string | Ref<string> | ComputedRef<string>;
   icon?: string | (() => string);
-  clickHandler?(): void;
-  disabled?: boolean | ComputedRef<boolean>;
-  isVisible?: boolean | Ref<boolean> | ComputedRef<boolean> | ((blade?: BladeDescriptor) => boolean);
+  clickHandler?(app?: Record<string, any> | null): void;
+  disabled?: boolean | ComputedRef<boolean | undefined>;
+  isVisible?: boolean | Ref<boolean | undefined> | ComputedRef<boolean | undefined> | ((blade?: BladeDescriptor) => boolean | undefined);
   separator?: "left" | "right" | "both";
+  permissions?: string | string[];
 }
 ```
 
@@ -555,7 +543,7 @@ const toolbar = ref([
 ### Blade with Data Table
 
 ```vue
-<VcBlade :title="$t('ORDERS.LIST.TITLE')" icon="lucide-file-text" width="50%" :expanded="expanded" :closable="closable" :toolbar-items="toolbar">
+<VcBlade :title="$t('ORDERS.LIST.TITLE')" icon="lucide-file-text" width="50%" :toolbar-items="toolbar">
   <VcDataTable
     v-model:sort-field="sortField" v-model:sort-order="sortOrder"
     v-model:search-value="searchValue" v-model:active-item-id="selectedItemId"
@@ -582,16 +570,6 @@ defineOptions({});
 defineBlade({ name: "ProductDetails", url: "/product" });
 ```
 
-### Forgetting to expose the title
-
-```ts
-// WRONG -- Breadcrumbs show nothing
-const title = computed(() => product.value?.name);
-
-// CORRECT
-defineExpose({ title });
-```
-
 ### Wrong onBeforeClose return value
 
 ```ts
@@ -614,37 +592,29 @@ const { openBlade } = useBlade();
 openBlade({ name: "ProductsList" });
 ```
 
-### Not passing expanded/closable through
-
-```vue
-<!-- WRONG -- hardcoded, ignores navigation system -->
-<VcBlade :expanded="true" :closable="true">
-
-<!-- CORRECT -- pass props from navigation -->
-<VcBlade :expanded="expanded" :closable="closable">
-```
-
 ## Props
 
-| Prop           | Type               | Default     | Description                                                                                                                                                                               |
-| -------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title`        | `string`           | `undefined` | Title text in the blade header.                                                                                                                                                           |
-| `subtitle`     | `string`           | `undefined` | Secondary text below the title.                                                                                                                                                           |
-| `icon`         | `string`           | `undefined` | Icon name (e.g., `"lucide-box"`) displayed before the title.                                                                                                                              |
-| `width`        | `number \| string` | `"30%"`     | Blade width. Numbers are pixels; strings are CSS values.                                                                                                                                  |
-| `expanded`     | `boolean`          | `undefined` | Whether the blade fills all available width. Inside a blade-navigation context this prop is overridden by the active blade's expanded state; in standalone use the prop is read directly. |
-| `closable`     | `boolean`          | `true`      | Whether the close button is shown.                                                                                                                                                        |
-| `toolbarItems` | `IBladeToolbar[]`  | `[]`        | Action buttons in the toolbar zone.                                                                                                                                                       |
-| `modified`     | `boolean`          | `undefined` | Shows unsaved changes indicator and banner.                                                                                                                                               |
-| `loading`      | `boolean`          | `undefined` | Shows skeleton placeholders for all blade zones.                                                                                                                                          |
+| Prop           | Type               | Default     | Description                                                                                                                                                                                                                                                               |
+| -------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `string`           | `undefined` | Title text in the blade header.                                                                                                                                                                                                                                           |
+| `subtitle`     | `string`           | `undefined` | Secondary text below the title.                                                                                                                                                                                                                                           |
+| `icon`         | `string`           | `undefined` | Icon name (e.g., `"lucide-box"`) displayed before the title.                                                                                                                                                                                                              |
+| `width`        | `number \| string` | `"30%"`     | Blade width. Numbers are pixels; strings are CSS values.                                                                                                                                                                                                                  |
+| ~~`expanded`~~ | `boolean`          | `undefined` | **Deprecated.** Managed by the navigation stack — ignored inside blade navigation, where the active (rightmost) blade is expanded automatically. Read the live value from `useBlade().expanded`. Retained only as a standalone/Storybook fallback.                        |
+| ~~`closable`~~ | `boolean`          | `true`      | **Deprecated.** Managed by the navigation stack — ignored inside blade navigation, where closability is derived from stack position (a workspace root is not closable). Read the live value from `useBlade().closable`. Retained only as a standalone/Storybook fallback. |
+| `toolbarItems` | `IBladeToolbar[]`  | `[]`        | Action buttons in the toolbar zone.                                                                                                                                                                                                                                       |
+| `modified`     | `boolean`          | `undefined` | Shows unsaved changes indicator and banner.                                                                                                                                                                                                                               |
+| `loading`      | `boolean`          | `undefined` | Shows skeleton placeholders for all blade zones.                                                                                                                                                                                                                          |
 
 ## Events
 
-| Event      | Payload | Description                                     |
-| ---------- | ------- | ----------------------------------------------- |
-| `close`    | --      | Close button clicked. Re-emit as `close:blade`. |
-| `expand`   | --      | Blade expanded. Re-emit as `expand:blade`.      |
-| `collapse` | --      | Blade collapsed. Re-emit as `collapse:blade`.   |
+> **Note:** These events fire **only in standalone/Storybook use**. Inside the navigation stack VcBlade closes itself (via `closeSelf()`) and handles expand/collapse internally, so there is nothing to forward. Use `onBeforeClose()` from `useBlade()` to run logic (like an unsaved-changes guard) before the blade closes. A leftover `@close` listener inside blade navigation triggers a dev-mode deprecation warning.
+
+| Event      | Payload | Description                                                        |
+| ---------- | ------- | ------------------------------------------------------------------ |
+| `close`    | --      | Standalone only. Close button clicked.                             |
+| `expand`   | --      | Standalone only. Blade expanded (no `maximized` context present).  |
+| `collapse` | --      | Standalone only. Blade collapsed (no `maximized` context present). |
 
 ## Slots
 

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/composables/table-composables.docs.md

@@ -73,20 +73,18 @@ The central engine. Distributes `availableWidth` among visible columns according
 
 ```ts
 interface EngineInput {
-  visibleIds: string[]; // Ordered list of visible column IDs
-  specs: Record<string, ColumnSpec>; // Per-column: weight, minWidth, maxWidth
   availableWidth: number; // Container width in px
-  fitMode: "gap" | "fit"; // "gap" leaves filler space, "fit" fills width
+  columns: { id: string; spec: ColumnSpec }[]; // Ordered visible columns with per-column weight, minPx, maxPx
+  mode: "fit" | "gap"; // "gap" leaves filler space, "fit" fills width
 }
 
 interface EngineOutput {
   widths: Record<string, number>; // Computed px width per column ID
-  totalWidth: number; // Sum of all computed widths
-  overflow: boolean; // true when sum(minWidth) > availableWidth
+  fillerWidth: number; // Leftover space returned to the filler pseudo-element
 }
 ```
 
-In crisis (`overflow: true`), each column receives its `minWidth` regardless of weight, and a console warning is emitted.
+In crisis (when `sum(minPx) > availableWidth`), the engine squeezes columns proportionally below their minimums (`crisisSqueeze`) and emits a `console.warn`.
 
 #### `parseColumnWidth(value: string | number | undefined, availableWidth: number): ParsedWidth`
 
@@ -94,14 +92,14 @@ Parses a `VcColumn` `width` prop into a concrete pixel value.
 
 ```ts
 type ParsedWidth =
-  | { type: "px"; value: number } // "200", 200, "200px"
-  | { type: "pct"; value: number } // "20%" → 0.2 * availableWidth
-  | { type: "auto"; value: undefined }; // undefined, "auto"
+  | { type: "px"; desiredPx: number } // "200", 200, "200px"
+  | { type: "percent"; desiredPx: number } // "20%" → 0.2 * availableWidth
+  | { type: "auto"; desiredPx: null }; // undefined, "auto"
 ```
 
-#### `buildInitialWeights(parsed: ParsedWidth[], availableWidth: number): Record<string, number>`
+#### `buildInitialWeights(parsed: { id: string; parsed: ParsedWidth }[], availableWidth: number): Record<string, number>`
 
-Converts an array of `ParsedWidth` values (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns.
+Converts an array of `{ id, parsed }` entries (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns.
 
 ```ts
 // Example: three columns — 200px, 20%, auto — with 800px available